US-E01: Kiểm tra flow process eContract của một deal &ZeroWidthSpace;

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.

Field	Value
US ID	US-E01
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.005 Retry econtract
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-E-01, NFR-E-02, NFR-E-05, NFR-E-07 — xem Overview §5
OQ liên quan	OQ-E-04, OQ-E-05, OQ-E-09, OQ-E-12 — xem Overview §6

1. US Statement &ZeroWidthSpace;

text

As a Người dùng tool  [Assumption (OQ về G-01)]
I want nhập HubSpot deal id để đọc mọi flow process eContract của deal và nhận kết luận
       "dừng / đủ điều kiện retry tay / hệ thống tự chạy"
So that [Assumption — OQ-E-12] tôi biết luồng hợp đồng điện tử của deal đang kẹt ở đâu và có cần
       retry tay hay chỉ cần chờ cron

2. Dependencies & Definition Of Ready &ZeroWidthSpace;

N/A — đã triển khai. Dependency runtime để màn chạy được:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Khoá `SAPP_PROD_ECONTRACT_DB_HOST / _NAME / _USERNAME` (bắt buộc), `_PORT` (mặc định 3306), `_PASSWORD` trong `env_systems` — US-P04	Admin CMS	Runtime
D2	Tool `sapp.005` đang bật / đã mở khoá ở FE — US-P02	Admin CMS	Runtime
D3	User DB econtract prod có quyền đọc `econtract_flow_processes`	SAPP	Runtime

3. Business Rules &ZeroWidthSpace;

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Phải nhập deal id (bỏ khoảng trắng đầu/cuối) mới được kiểm tra; để trống → báo "Thiếu deal id"	M1 - action A1 Kiểm tra	AC-M1.2	`fe/src/ui/components/works/sapp/retry-econtract-tool.tsx:413-422`
BR-02	Kiểm tra chỉ đọc mọi flow process của deal trên DB econtract PROD; không đọc cột dữ liệu request (chứa đường dẫn file trên server)	M1 - action A1	AC-M1.1	`be/libs/modules/src/lib/sapp/common.service.ts:1707-1721` · `:2404-2415` · `be/libs/constants/src/lib/sapp/sapp.constants.ts:128-150`
BR-03	Deal không có flow process nào → kết luận Dừng ở bước 1, lý do "Không tìm thấy flow process nào cho deal này."	M1 - vùng kết luận	AC-M1.3	`retry-econtract-tool.tsx:67-70` · `:591-600`
BR-04	Deal có ≥ 2 flow process cùng tên (tính cả dòng SUCCESS) → Dừng, lý do "Có N bản ghi cùng flow X — không xác định được process cần retry."	M1 - vùng kết luận	AC-M1.4	`retry-econtract-tool.tsx:71-79`
BR-05	Không có dòng nào ở trạng thái FAIL → Dừng, lý do liệt kê `tên = trạng thái` từng dòng, "không có gì để retry."	M1 - vùng kết luận	AC-M1.5	`retry-econtract-tool.tsx:80-88`
BR-06	Có ≥ 1 dòng FAIL với retry ≥ 1 (retry = số lần đã chạy lại, không phải số lượt còn lại) → Đủ điều kiện retry tay; chỉ các dòng này được liệt kê và theo dõi	M1 - vùng kết luận	AC-M1.6	`retry-econtract-tool.tsx:89-90` · `:603-621` · `be/libs/interface/src/lib/dto/sapp/econtract-flow-process.dto.ts:29-33`
BR-07	Mọi dòng FAIL đều có retry = 0 → Hệ thống tự chạy: không hiện nút Retry, bước 2 hiện "Hệ thống tự chạy", tự sang bước Chờ cron (không có lời gọi ghi)	M1 - stepper, vùng Chờ cron	AC-M1.7	`retry-econtract-tool.tsx:89-90` · `:342-353` · `:195` · `:631-633` · `:650-652`
BR-08	Trong lúc đang gọi API hoặc đang chờ cron, ô deal id và nút Kiểm tra bị khoá (kể cả phím Enter)	M1 - field deal id, action A1	AC-M1.8	`retry-econtract-tool.tsx:554-563`
BR-09	Mở màn với `?dealId=` → chỉ điền sẵn ô deal id, không tự kiểm tra	M1 - trigger	AC-M1.9	`retry-econtract-tool.tsx:403-411`
BR-10	Khi Dừng ở bước 1 → hiện ghi chú liên hệ developer kèm nút "Copy thông tin gửi dev" (chi tiết ở US-E03)	M1 - vùng kết luận	AC-M1.3	`retry-econtract-tool.tsx:520` · `:145-146`
BR-11	Danh sách "Flow process của deal (N)" luôn hiện đủ mọi dòng: tên, trạng thái, retry, reprocess, loại hợp đồng, cập nhật, và "Xem dữ liệu thô" (JSON của dòng)	M1 - danh sách	AC-M1.1	`retry-econtract-tool.tsx:217-264` · `:706-711`
BR-12	Thiếu cấu hình kết nối DB econtract → lỗi mã `13001`; lỗi đọc khác → mã `13004`	M1 - action A1	EC-M1.1, EC-M1.2	`common.service.ts:1685-1704` · `:1712-1720` · `be/libs/constants/src/lib/error-codes/error-codes.constants.ts:518-537`

Kết luận ở FE là bản sao luật của BE để giải thích trước; BE kiểm tra lại và quyết định khi Retry (US-E02 BR-03) — retry-econtract-tool.tsx:62-65.

4. Design &ZeroWidthSpace;

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

text

[Hub → Retry econtract]  (hoặc …/econtract?dealId=X → điền sẵn, BR-09)
  ↓ nhập deal id, bấm Kiểm tra / Enter
[M1: Retry econtract — bước 1 Kiểm tra]
  ├─ không có dòng / trùng tên / không FAIL ─→ Dừng ở bước 1 + ghi chú liên hệ dev (US-E03)
  ├─ mọi FAIL có retry = 0 ──────────────────→ bước 2 "Hệ thống tự chạy" → bước 3 Chờ cron (như US-E02 M2)
  ├─ có FAIL retry ≥ 1 ───────────────────────→ "Đủ điều kiện retry" + nút Retry (US-E02)
  └─ lỗi API ─────────────────────────────────→ hộp lỗi "Không đọc được flow process"

b. Chi tiết từng màn &ZeroWidthSpace;

Màn M1 - Retry econtract (bước 1 Kiểm tra) &ZeroWidthSpace;

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn "Retry econtract" trong nhóm "SAPP 20603 - EContract" ở hub (`/works/sapp/tools/econtract`), hoặc mở link `?dealId=`
Mô tả ngắn	Tiêu đề "Retry econtract flow process"; mô tả "Chạy lại luồng econtract của một deal bị lỗi… Chỉ chạy lại luồng — không đổi deal stage trên HubSpot." Stepper 4 bước: Kiểm tra → Retry → Chờ cron → Kết quả

UI States &ZeroWidthSpace;

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	Ô "HubSpot deal id" (placeholder "vd. 12345678901…") + nút "Kiểm tra"; chưa có stepper	N/A
Loading	Đang đọc flow process	Nút "Đang kiểm tra…", stepper bước 1 đang chạy, dòng "Đang đọc flow process…"	N/A
Has data — Dừng	BR-03/04/05	Stepper bước 1 đỏ (dừng); khung "Dừng ở bước 1 — không retry được deal này" + lý do; ghi chú liên hệ developer + nút copy	N/A
Has data — Đủ điều kiện	BR-06	Khung "Đủ điều kiện retry": "`tên (retry = N)` … đang FAIL và cron không tự lấy nữa. Retry sẽ đặt lại retry = 0 để cron chạy lại ở phút kế tiếp." + nút "Retry process này"	N/A
Has data — Hệ thống tự chạy	BR-07	Bước 2 đánh dấu "Hệ thống tự chạy"; khung "Hệ thống sẽ tự chạy lại trong ~1 phút" + đồng hồ đếm ngược	N/A
Empty	Deal không có dòng	Là state Dừng (BR-03) + "Flow process của deal (0)" / "Không có bản ghi nào."	N/A
Error	API lỗi	Hộp lỗi tiêu đề "Không đọc được flow process", nội dung `thông điệp (mã)`	N/A
Disabled	Đang gọi / đang chờ cron	Ô deal id và nút Kiểm tra bị khoá (BR-08)	N/A

Fields &ZeroWidthSpace;

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
HubSpot deal id	Yes	Text (bàn phím số trên mobile)	Trống, hoặc giá trị `?dealId=`	Tự do — không kiểm tra định dạng (⚠️ Observed, OQ-E-09)	Bỏ khoảng trắng đầu/cuối, không rỗng (BR-01)	"Thiếu deal id" / "Nhập HubSpot deal id cần retry."	Always; Readonly khi đang gọi / chờ cron (BR-08)	-
(hiển thị) Tên flow	-	Text	-	vd `CREATE_CONTRACT`	-	-	Mỗi dòng	-
(hiển thị) Trạng thái	-	Badge	-	`NEW` / `SUCCESS` / `FAIL`	-	-	Mỗi dòng	-
(hiển thị) retry · reprocess · loại · cập nhật	-	Text	-	cập nhật: `YYYY-MM-DD HH:mm:ss` theo giờ máy	-	-	Mỗi dòng	cập nhật có thể lệch múi giờ (OQ-E-05)
(hiển thị) Xem dữ liệu thô	-	JSON text (mở / đóng)	Đóng	-	-	-	Mỗi dòng	NFR-E-02

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

N/A — màn tra cứu theo 1 deal, không có lọc / sắp xếp / phân trang (danh sách hiện theo thứ tự DB trả về).

Actions &ZeroWidthSpace;

A1 - Kiểm tra &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Kiểm tra" hoặc Enter trong ô deal id
Behavior	Kiểm tra BR-01 → đặt lại lượt về 1 → gọi đọc flow process (chỉ đọc, DB econtract PROD, BR-02) → FE đánh giá kết luận theo BR-03…BR-07. Không ghi hệ thống nào
Success Result	Hiện stepper + kết luận + danh sách flow process (BR-11)

Error cases:

Case	Expected Handling
Ô trống	Hộp lỗi "Thiếu deal id" (BR-01), không gọi API
Thiếu cấu hình DB	Hộp lỗi "Không đọc được flow process" + `… (13001)` (BR-12)
Lỗi DB / mạng khác	Hộp lỗi "Không đọc được flow process" + `… (13004)` hoặc thông điệp lỗi

Acceptance Criteria của màn M1 &ZeroWidthSpace;

AC-M1.1 - Đọc và liệt kê flow process &ZeroWidthSpace;

gherkin

Given deal D có các flow process trên DB econtract prod
When người dùng nhập D và bấm "Kiểm tra"
Then hệ thống chỉ đọc (không ghi) các dòng của D
And hiện "Flow process của deal (N)" với tên, trạng thái, retry, reprocess, loại, cập nhật và "Xem dữ liệu thô" của từng dòng
And dữ liệu thô không chứa cột dữ liệu request

Maps to:

Business Rule: BR-02, BR-11
Field/Action: A1

AC-M1.2 - Thiếu deal id &ZeroWidthSpace;

gherkin

Given ô "HubSpot deal id" trống hoặc chỉ có khoảng trắng
When người dùng bấm "Kiểm tra"
Then hiện hộp lỗi "Thiếu deal id" với nội dung "Nhập HubSpot deal id cần retry."
And không có lời gọi API

Maps to:

Business Rule: BR-01

AC-M1.3 - Dừng: không có flow process &ZeroWidthSpace;

gherkin

Given deal D không có flow process nào
When người dùng kiểm tra D
Then stepper dừng ở bước 1 và hiện "Dừng ở bước 1 — không retry được deal này"
And lý do "Không tìm thấy flow process nào cho deal này."
And hiện ghi chú "Cần liên hệ developer để kiểm tra kỹ hơn…" kèm nút "Copy thông tin gửi dev"
And không có nút Retry

Maps to:

Business Rule: BR-03, BR-10

AC-M1.4 - Dừng: trùng tên flow &ZeroWidthSpace;

gherkin

Given deal D có 2 dòng cùng tên CREATE_CONTRACT (một FAIL, một SUCCESS)
When người dùng kiểm tra D
Then kết luận Dừng với lý do "Có 2 bản ghi cùng flow CREATE_CONTRACT — không xác định được process cần retry."

Maps to:

Business Rule: BR-04

AC-M1.5 - Dừng: không có dòng FAIL &ZeroWidthSpace;

gherkin

Given mọi flow process của deal D đều ở trạng thái SUCCESS hoặc NEW
When người dùng kiểm tra D
Then kết luận Dừng, lý do liệt kê "tên = trạng thái" từng dòng và "không có gì để retry."

Maps to:

Business Rule: BR-05

AC-M1.6 - Đủ điều kiện retry tay &ZeroWidthSpace;

gherkin

Given deal D có dòng CREATE_CONTRACT ở FAIL với retry = 1, tên flow không trùng
When người dùng kiểm tra D
Then bước 1 xong, bước 2 "Retry" là bước hiện tại
And hiện khung "Đủ điều kiện retry" nêu "CREATE_CONTRACT (retry = 1)" và nút "Retry process này"

Maps to:

Business Rule: BR-06

AC-M1.7 - Hệ thống tự chạy &ZeroWidthSpace;

gherkin

Given mọi dòng FAIL của deal D đều có retry = 0
When người dùng kiểm tra D
Then không hiện nút Retry và bước 2 hiện "Hệ thống tự chạy"
And hiện "Hệ thống sẽ tự chạy lại trong ~1 phút" với đồng hồ đếm ngược
And không có lời gọi ghi nào
And việc đọc lại và kết quả diễn ra như US-E02 AC-M2.1…AC-M2.4

Maps to:

Business Rule: BR-07

AC-M1.8 - Khoá nhập khi đang bận &ZeroWidthSpace;

gherkin

Given màn đang gọi API hoặc đang đếm ngược chờ cron
When người dùng thử sửa ô deal id, bấm "Kiểm tra" hoặc Enter
Then ô và nút bị khoá, không có lượt kiểm tra mới

Maps to:

Business Rule: BR-08

AC-M1.9 - Deep link chỉ điền sẵn &ZeroWidthSpace;

gherkin

Given người dùng mở …/econtract?dealId=123
When màn tải xong
Then ô deal id có giá trị "123"
And chưa có lời gọi API cho tới khi người dùng bấm "Kiểm tra"

Maps to:

Business Rule: BR-09

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	`env_systems` thiếu host / tên DB / username econtract	Hộp lỗi "Không đọc được flow process" với `SAPP econtract database is not configured (13001)` (BR-12)
EC-M1.2	Mất kết nối DB / mạng giữa lượt	Hộp lỗi "Không đọc được flow process" với mã `13004` hoặc thông điệp lỗi; không đổi dữ liệu
EC-M1.3	⚠️ Observed — deal id có ký tự không phải số / ký tự đặc biệt	Hành vi hiện tại: BE không kiểm tra định dạng; FE ghép deal id vào URL không mã hoá → truy vấn trả rỗng (Dừng BR-03) hoặc URL lỗi. OQ-E-09
EC-M1.4	⚠️ Observed — giờ "cập nhật"	Hành vi hiện tại: đọc thẳng DATETIME, không theo đồng hồ DB như màn Check luồng → có thể lệch theo múi giờ tiến trình BE. OQ-E-05, DR-E-02
EC-M1.5	Dữ liệu trên prod đổi giữa lúc Kiểm tra và lúc bấm Retry (cron vừa chạy)	Kết luận ở màn là ảnh chụp tại lúc đọc; BE kiểm tra lại khi Retry (US-E02 EC-M1.1…EC-M1.4)
EC-M1.6	Refresh trang giữa lượt	Mất trạng thái stepper; ô deal id chỉ điền lại nếu URL có `?dealId=` (màn không tự ghi deal id lên URL)

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Không truy cập được khi tool bị khoá (nền tảng) &ZeroWidthSpace;

gherkin

Given tool sapp.005 đang tắt / ẩn / khoá trên hub
When người dùng mở /works/sapp/tools/econtract
Then FE xử lý theo US-P02 (không vào được màn hoặc phải mở khoá)
And BE không kiểm tra trạng thái tool (NFR-E-01)

Maps to:

REL-01 (Affects - Hub & khoá tool)

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

gherkin

Given khoá SAPP_PROD_ECONTRACT_DB_HOST chưa có trong env_systems
When người dùng kiểm tra bất kỳ deal nào
Then nhận lỗi mã 13001 (EC-M1.1)

Maps to:

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

AC-X.3 - Không gọi HubSpot &ZeroWidthSpace;

gherkin

Given người dùng kiểm tra deal D
When lượt kiểm tra hoàn tất
Then không có lời gọi nào tới HubSpot; deal id chỉ là khoá tra cứu trên DB econtract

Maps to:

REL-04 (Affects - HubSpot deal)

sapp-platform-as-built-v0.1-20260930

sapp-hubspot-as-built-v0.1-20260930

sapp-26878-as-built-v0.1-20260930

sapp-26297-as-built-v0.1-20260930

sapp-24395-as-built-v0.1-20260930

sapp-23954-as-built-v0.1-20260930

sapp-20603-econtract-as-built-v0.1-20260930

US-E01: Kiểm tra flow process eContract của một deal &ZeroWidthSpace;

1. US Statement &ZeroWidthSpace;

2. Dependencies & Definition Of Ready &ZeroWidthSpace;

3. Business Rules &ZeroWidthSpace;

4. Design &ZeroWidthSpace;

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

b. Chi tiết từng màn &ZeroWidthSpace;

Màn M1 - Retry econtract (bước 1 Kiểm tra) &ZeroWidthSpace;

UI States &ZeroWidthSpace;

Fields &ZeroWidthSpace;

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

Actions &ZeroWidthSpace;

A1 - Kiểm tra &ZeroWidthSpace;

Acceptance Criteria của màn M1 &ZeroWidthSpace;

AC-M1.1 - Đọc và liệt kê flow process &ZeroWidthSpace;

AC-M1.2 - Thiếu deal id &ZeroWidthSpace;

AC-M1.3 - Dừng: không có flow process &ZeroWidthSpace;

AC-M1.4 - Dừng: trùng tên flow &ZeroWidthSpace;

AC-M1.5 - Dừng: không có dòng FAIL &ZeroWidthSpace;

AC-M1.6 - Đủ điều kiện retry tay &ZeroWidthSpace;

AC-M1.7 - Hệ thống tự chạy &ZeroWidthSpace;

AC-M1.8 - Khoá nhập khi đang bận &ZeroWidthSpace;

AC-M1.9 - Deep link chỉ điền sẵn &ZeroWidthSpace;

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

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Không truy cập được khi tool bị khoá (nền tảng) &ZeroWidthSpace;

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

AC-X.3 - Không gọi HubSpot &ZeroWidthSpace;