US-E05: Thống kê lỗi eContract theo khoảng thời gian

Thuộc FS: 00-overview.md — SAPP-20603 eContract (Retry · Check luồng · Thống kê lỗi) Phần chung (tổng quan, roles, flow tổng, related features, NFR, Open Questions, References) xem ở Overview. File này chỉ chứa nội dung riêng của US.

Chỉ đọc. Màn này chỉ chạy truy vấn đọc (SELECT) trên DB econtract PRODUCTION — không ghi hệ thống nào, ngoài cache Redis của mind_keep cho mốc job trace cũ nhất.

Field	Value
US ID	US-E05
Role thực hiện	R1 - Người dùng tool (Assumption (OQ về G-01) — OQ-E-04)
Phase	Đã triển khai (as-built @ e77c47a) — sub-tool sapp.013 Thống kê lỗi econtract
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-E-01, NFR-E-03, NFR-E-04, NFR-E-05, NFR-E-07 — xem Overview §5
OQ liên quan	OQ-E-04, OQ-E-07, OQ-E-10, OQ-E-12 — xem Overview §6

1. US Statement

As a Người dùng tool  [Assumption (OQ về G-01)]
I want chọn một khoảng thời gian, độ rộng bucket và flow để xem số lần chạy job econtract bị lỗi theo
       thời gian, tách theo flow, tỷ lệ lỗi, lỗi và bước gặp nhiều nhất
So that [Assumption — OQ-E-12] tôi theo dõi được mức độ lỗi của luồng hợp đồng điện tử và biết lỗi nào
       đang chiếm phần lớn (chưa rõ chỉ số dùng để báo cáo hay cảnh báo)

2. Dependencies & Definition Of Ready

N/A — đã triển khai. Dependency runtime:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Khoá SAPP_PROD_ECONTRACT_DB_* trong env_systems — US-P04	Admin CMS	Runtime
D2	Bảng econtract_job_traces tồn tại và đọc được (có trên prod từ 2026-08-13 13:28:58 UTC — số đo 2026-09-25-mind-sapp-20603-ket-qua.md)	SAPP	Runtime
D3	Tool sapp.013 truy cập được — US-P02	Admin CMS	Runtime

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Mặc định khi mở màn: Từ = 24 giờ trước, Đến = bây giờ (giờ máy), bucket 15 phút, "Tất cả flow"; không tự tải — phải bấm Xem hoặc một preset	M1 - bộ lọc	AC-M1.1	fe/src/ui/components/works/sapp/econtract-error-stats-tool.tsx:177-183 · :174-252 (chỉ tải trong nút Xem / preset, không có lời gọi khi mở màn)
BR-02	"Từ" tính bao gồm, "Đến" không bao gồm; nhập theo giờ máy, gửi đi dạng ISO	M1 - field Từ / Đến	AC-M1.2	be/libs/interface/src/lib/dto/sapp/econtract-error-stats.dto.ts:20-24 · econtract-error-stats-tool.tsx:234-240 · :342 · :355
BR-03	FE chặn trước: phải đủ 2 thời điểm; Đến phải sau Từ; số bucket (khoảng ÷ bucket) ≤ 1500 — sai → hộp "Khoảng thời gian không hợp lệ" với câu tương ứng, không gọi API	M1 - action A1	AC-M1.3	econtract-error-stats-tool.tsx:217-233 · :53
BR-04	BE kiểm lại cùng điều kiện (bucket ∈ {1, 5, 15, 60}) và từ chối mã 13062	M1 - action A1	EC-M1.1	be/libs/modules/src/lib/sapp/common.service.ts:1920-1935 · be/libs/constants/src/lib/sapp/sapp.constants.ts:197-205 · be/libs/constants/src/lib/error-codes/error-codes.constants.ts:568-573
BR-05	5 preset "1 giờ · 1′", "6 giờ · 5′", "24 giờ · 15′", "7 ngày · 60′", "30 ngày · 60′": đặt Từ = bây giờ − khoảng, Đến = bây giờ, bucket tương ứng và tải ngay (giữ flow đang chọn)	M1 - action A2	AC-M1.4	econtract-error-stats-tool.tsx:64-70 · :245-252 · :402-414
BR-06	Danh sách flow trong bộ lọc = 5 flow biết trước (CREATE_CONTRACT, CONTRACT_COMPLETED, CANCEL_CONTRACT, EFY_CONTRACT_COMPLETED, EFY_CANCEL_CONTRACT) + mọi flow đã thấy trong các lần tải; để trống = tất cả	M1 - field Flow	AC-M1.5	econtract-error-stats-tool.tsx:56-62 · :183 · :211-213 · :384-389 · common.service.ts:1962
BR-07	Mọi số liệu đếm chỉ từ job trace (mỗi lần chạy 1 dòng, chỉ thêm), không từ flow process — vì flow process bị ghi đè khi retry sẽ làm mất lỗi đã hồi phục	M1 - toàn bộ kết quả	AC-M1.6	common.service.ts:1908-1916 · econtract-error-stats.dto.ts:10-17
BR-08	5 ô tổng: Lần chạy, Lần chạy lỗi, Tổng deal, Deal bị lỗi, Tỷ lệ lỗi (ô lỗi > 0 tô đỏ)	M1 - tóm tắt	AC-M1.6	econtract-error-stats-tool.tsx:419-466
BR-09	Tỷ lệ lỗi = 100 × lần lỗi ÷ lần chạy, làm tròn 2 chữ số thập phân; không có lần chạy → "—" (ô tổng) / bỏ trống (biểu đồ), không tính là 0%. Mọi bucket trong khoảng đều có mặt, bucket rỗng = 0 lần	M1 - ô Tỷ lệ lỗi, biểu đồ	AC-M1.7	common.service.ts:2067-2090 · econtract-error-stats-tool.tsx:316-318 · :554-558
BR-10	"Lỗi gặp nhiều nhất" = top 20 lỗi gom theo dòng đầu của error (cắt 300 ký tự), kèm số lần lỗi, số deal, lần đầu, lần cuối; "Bước chết nhiều nhất" đếm theo step + provider trên 2000 lần chạy lỗi mới nhất — chạm trần → cảnh báo TRUNCATED	M1 - 2 bảng xếp hạng	AC-M1.8	sapp.constants.ts:206-215 · common.service.ts:2011-2033 · :2109 · econtract-error-stats-tool.tsx:606-679
BR-11	Khoảng bắt đầu trước job trace cũ nhất → cảnh báo PREDATES_TRACE; vùng đó tô xám trên biểu đồ (0 vì chưa ghi, không phải vì không lỗi)	M1 - biểu đồ, cảnh báo	AC-M1.9	common.service.ts:2123-2130 · econtract-error-stats-tool.tsx:87-88 · :267 · :273 · :289-298
BR-12	Bảng thiếu / không quyền đọc → cảnh báo, không làm hỏng lượt	M1 - cảnh báo	AC-M1.9	common.service.ts:1982-1991
BR-13	3 biểu đồ: "Lỗi theo thời gian" (đường Lần chạy lỗi, Deal bị lỗi, nét đứt Tổng lần chạy); "Lần chạy lỗi theo flow" (cột chồng theo flow); "Tỷ lệ lỗi (%)"	M1 - biểu đồ	AC-M1.6	econtract-error-stats-tool.tsx:487-601

4. Design

a. Mối liên hệ giữa các màn & User Flow

[Hub → Thống kê lỗi econtract]
  ↓ (không tự tải — BR-01)
[M1: bộ lọc Từ / Đến / Bucket / Flow]
  ├─ bấm "Xem" ─────┐
  └─ bấm preset ────┴→ kiểm tra FE (BR-03) ─ sai → hộp "Khoảng thời gian không hợp lệ"
                        └─ đúng → GET error-stats (chỉ đọc) → cảnh báo · 5 ô tổng · 3 biểu đồ · top lỗi · bước chết
                                                             └─ ô "Deal bị lỗi" → "Danh sách" → US-E06

b. Chi tiết từng màn

Màn M1 - Thống kê lỗi econtract

Field	Value
Figma frame	N/A
Trigger vào màn	Hub → "Thống kê lỗi econtract" (/works/sapp/tools/econtract-error-stats)
Mô tả ngắn	"Số lần chạy job econtract bị lỗi theo thời gian, tách theo flow, tỷ lệ lỗi, lỗi và bước gặp nhiều nhất. Đếm từ econtract_job_traces — chỉ đọc, không thay đổi dữ liệu."

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	Bộ lọc với giá trị mặc định (BR-01) + hàng preset "Nhanh:"; chưa có kết quả	N/A
Loading	Đang tải	Nút "Đang tải…"; bộ lọc và preset bị khoá	N/A
Has data	Tải xong	Cảnh báo (nếu có) → 5 ô tổng → dòng múi giờ DB → 3 biểu đồ → "Lỗi gặp nhiều nhất (N) — dòng đầu của error" → "Bước chết nhiều nhất (N)"	N/A
Empty	Không có lần chạy lỗi	Ô tổng = 0; biểu đồ theo flow: "Không có lần chạy lỗi nào trong khoảng này."; "Không có lỗi nào trong khoảng này."; "Không có bước lỗi nào trong khoảng này."	N/A
Error	API lỗi	Hộp lỗi "Không tải được thống kê lỗi econtract" + thông điệp (mã) (vd 13061, 13062, 13001)	N/A
Disabled	Đang tải	Mọi control bị khoá	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Từ (giờ máy)	Yes	Datetime picker	Bây giờ − 24 giờ	Ngày + giờ, không xoá được	Hợp lệ (BR-03)	"Chọn đủ thời điểm bắt đầu và kết thúc."	Always	-
Đến (không gồm)	Yes	Datetime picker	Bây giờ	Ngày + giờ, không xoá được	Sau "Từ" (BR-03)	"Thời điểm kết thúc phải sau thời điểm bắt đầu."	Always	Từ
Bucket	Yes	Dropdown	15 phút	1 / 5 / 15 / 60 phút	Số bucket ≤ 1500 (BR-03)	"Khoảng này ra hơn 1500 bucket với bucket N phút — chọn bucket rộng hơn hoặc thu hẹp khoảng."	Always	Từ, Đến
Flow	No	Dropdown	"Tất cả flow"	Tên flow	Trong danh sách BR-06	-	Always	-

Filter / Search / Sort (chỉ màn List/Report — xóa nếu không phải)

Loại	Theo field	Kiểu	Default	Notes
Filter	Thời gian	Date range (Từ bao gồm, Đến không bao gồm) + 5 preset	24 giờ gần nhất	BR-01, BR-02, BR-05
Filter	Bucket	Dropdown	15 phút	BE mặc định 5 nếu không gửi (econtract-error-stats.dto.ts:26-30)
Filter	Flow	Dropdown	Tất cả	BR-06
Search	-	-	-	N/A
Sort	-	Cố định	Top lỗi theo số lần lỗi giảm dần	Không đổi được
Pagination	-	-	-	N/A — top 20 lỗi (BR-10)

Actions

A1 - Xem

Item	Description
Trigger	Bấm "Xem"
Behavior	Kiểm tra BR-03 → gọi GET /api/v1/sapp/prod/econtract/error-stats?from&to&bucketMin&flowName. Chỉ đọc DB econtract PRODUCTION (6 truy vấn quét toàn bảng song song, NFR-E-03); ghi duy nhất là cache Redis mind_keep cho mốc job trace cũ nhất
Success Result	UI State Has data; danh sách flow bổ sung flow mới thấy (BR-06)

Error cases:

Case	Expected Handling
Khoảng sai (FE)	Hộp "Khoảng thời gian không hợp lệ", không gọi API
Khoảng sai (BE)	Hộp lỗi … (13062)
Lỗi dựng thống kê	Hộp lỗi Failed to build econtract error stats (13061)

A2 - Preset

Item	Description
Trigger	Bấm một nút trong hàng "Nhanh:"
Behavior	Đặt Từ / Đến / Bucket theo BR-05 rồi chạy như A1 (chỉ đọc)
Success Result	Như A1

Error cases:

Case	Expected Handling
Như A1	Như A1

Acceptance Criteria của màn M1

AC-M1.1 - Mặc định, không tự tải

Given người dùng vừa mở màn Thống kê lỗi
When màn hiển thị
Then Từ = 24 giờ trước, Đến = bây giờ, Bucket = 15 phút, Flow = "Tất cả flow"
And chưa có lời gọi API nào

Maps to:

• Business Rule: BR-01

AC-M1.2 - Từ bao gồm, Đến không bao gồm

Given một lần chạy lỗi lúc đúng 10:00:00 và một lần lúc đúng 11:00:00
When người dùng xem khoảng Từ 10:00 Đến 11:00
Then lần 10:00:00 được đếm, lần 11:00:00 không được đếm

Maps to:

• Business Rule: BR-02

AC-M1.3 - Chặn khoảng không hợp lệ ở FE

Given Từ = 30 ngày trước, Đến = bây giờ, Bucket = 1 phút (43 200 bucket)
When người dùng bấm "Xem"
Then hiện hộp "Khoảng thời gian không hợp lệ" với câu "Khoảng này ra hơn 1500 bucket với bucket 1 phút — …"
And không có lời gọi API

Maps to:

• Business Rule: BR-03

AC-M1.4 - Preset tải ngay

Given Flow đang chọn CREATE_CONTRACT
When người dùng bấm "7 ngày · 60′"
Then Từ = bây giờ − 7 ngày, Đến = bây giờ, Bucket = 60 phút
And màn tải thống kê ngay, chỉ cho flow CREATE_CONTRACT

Maps to:

• Business Rule: BR-05

AC-M1.5 - Danh sách flow

Given lần tải trước trả về flow "NEW_FLOW_X" chưa có trong 5 flow biết trước
When người dùng mở dropdown Flow
Then thấy "Tất cả flow", 5 flow biết trước và "NEW_FLOW_X"

Maps to:

• Business Rule: BR-06

AC-M1.6 - Số liệu từ job trace

Given trong khoảng có 10 lần chạy job (4 FAIL của 1 deal, 6 SUCCESS của 3 deal)
When kết quả hiện ra
Then Lần chạy = 10, Lần chạy lỗi = 4, Tổng deal = 4, Deal bị lỗi = 1, Tỷ lệ lỗi = 40%
And 3 biểu đồ "Lỗi theo thời gian", "Lần chạy lỗi theo flow", "Tỷ lệ lỗi (%)" hiện theo bucket
And số liệu không phụ thuộc trạng thái hiện tại của flow process (kể cả khi deal đã được retry thành công)

Maps to:

• Business Rule: BR-07, BR-08, BR-13

AC-M1.7 - Tỷ lệ lỗi và bucket rỗng

Given một bucket trong khoảng không có lần chạy nào
When biểu đồ "Tỷ lệ lỗi (%)" hiện
Then bucket đó bỏ trống, không vẽ 0%
And ở biểu đồ đếm, bucket đó có giá trị 0

Maps to:

• Business Rule: BR-09

AC-M1.8 - Top lỗi và bước chết

Given trong khoảng có hơn 20 loại lỗi khác nhau (theo dòng đầu của error)
When kết quả hiện ra
Then "Lỗi gặp nhiều nhất" có đúng 20 dòng, mỗi dòng có message, lần lỗi, deal, lần đầu, lần cuối
And "Bước chết nhiều nhất" đếm theo step + provider
And nếu có từ 2000 lần chạy lỗi trở lên thì hiện cảnh báo "Bước lỗi chỉ được đếm trên 2000 lần chạy lỗi mới nhất của khoảng này"

Maps to:

• Business Rule: BR-10

AC-M1.9 - Khoảng trước job trace cũ nhất

Given Từ sớm hơn job trace cũ nhất của bảng
When kết quả hiện ra
Then hiện cảnh báo "Khoảng thời gian bắt đầu trước job trace cũ nhất — vùng tô xám là chưa có dữ liệu, không phải không có lỗi."
And vùng đó tô xám trên biểu đồ

Maps to:

• Business Rule: BR-11, BR-12

Negative AC / Edge Cases của màn M1

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Gọi thẳng API với bucket 7 hoặc to ≤ from	BE từ chối 13062 (BR-04)
EC-M1.2	Đúng 2000 lần chạy lỗi / đúng 500 deal lỗi	Hành vi hiện tại: cảnh báo cắt vẫn bật (so ≥ trần) — lệch tài liệu DR-E-01, OQ-E-10
EC-M1.3	Nhiều người bấm liên tục / chọn 30 ngày	Mỗi lượt 6 truy vấn quét toàn bảng prod, không giới hạn tần suất; chi phí không phụ thuộc độ dài khoảng (NFR-E-03, OQ-E-07)
EC-M1.4	Bucket < 15 phút	Biểu đồ tỷ lệ hiện gợi ý "Bucket dưới 15 phút thường chỉ có 1–2 lần chạy… chọn bucket 15 hoặc 60 phút để đọc xu hướng." (econtract-error-stats-tool.tsx:555-558)
EC-M1.5	Múi giờ máy người xem khác UTC	Nhập / hiển thị theo giờ máy; dòng ghi "đồng hồ DB econtract: <múi giờ>" (NFR-E-05)
EC-M1.6	Refresh trang	Bộ lọc về mặc định, kết quả mất (không lưu trên URL)

5. Cross-feature AC

AC-X.1 - Lần chạy lại do Retry được đếm

Given US-E02 đã Retry deal D và cron econtract chạy lại (thành công hoặc lỗi)
When người dùng xem thống kê khoảng chứa thời điểm chạy lại
Then lần chạy lại đó được đếm vào Lần chạy (và Lần chạy lỗi nếu FAIL)

Maps to:

• REL-03 (Be Affected - Cron econtract-payment + EFY/FPT)

AC-X.2 - Thiếu cấu hình env_systems

Given env_systems thiếu khoá bắt buộc SAPP_PROD_ECONTRACT_DB_*
When người dùng bấm "Xem"
Then hộp lỗi mã 13001

Maps to:

• REL-02 (Affects - Cấu hình env_systems)