US-D05: Flow P1: Gia hạn / Bảo lưu (F-P1-02 · story SAPP US-05) &ZeroWidthSpace;

Thuộc FS: 00-overview.md — SAPP-26878 · Tạo dữ liệu test doanh thu (Ops → HubSpot → SAP) 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. As-built tại commit e77c47a. Nguồn Fact: inventory 26878 A-50 … A-55. Hành vi từng loại bước → US-D03; khung stepper → US-D01.

Field	Value
US ID	US-D05
Role thực hiện	R1 - Người dùng tool (`Assumption (OQ về G-01)`, OQ-D-05)
Phase	As-built (đã triển khai) — phase 1 của ticket, chip `us05`
Priority	N/A (as-built)
Status	Draft
NFR liên quan	NFR-D-02, NFR-D-03, NFR-D-04, NFR-D-06 — xem Overview §5
OQ liên quan	OQ-D-02, OQ-D-06, OQ-D-10, OQ-D-16 — xem Overview §6

1. US Statement &ZeroWidthSpace;

text

As a Người dùng tool (Assumption — OQ về G-01)
I want dựng một deal phí dịch vụ gia hạn hoặc bảo lưu, kéo tới mốc hoàn thành phí, rồi bắn đồng bộ lại hóa đơn và reconcile
So that kiểm được luồng "Đồng bộ Deal → hóa đơn SAP" cho story US-05 phase 1
        (trích shared/runbooks/sapp/sapp-26878/README.md:10); lợi ích cụ thể: [Assumption]

2. Dependencies & Definition Of Ready &ZeroWidthSpace;

N/A — đã triển khai (Mode B). Dependency runtime: pipeline gia hạn / bảo lưu của flow us05 đã cấu hình cho portal (sapp-26878.constants.ts:382-507).

3. Business Rules &ZeroWidthSpace;

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Flow có 7 bước, 1 deal, theo bảng bước §4.b; cho phép "Dùng deal có sẵn". Hóa đơn phí dịch vụ dựng chỉ từ property trên deal — đơn Ops không bắt buộc.	M1	AC-M1.1	`sapp-26878-flows.ts:1219-1226,1359-1411`
BR-02	Bắt buộc: `loai_phi_dich_vu`, `tai_khoan_nhan_phi_dich_vu`, `bu_san_pham_cung_cap_dich_vu`, `muc_phi_can_dong`, `khoa_hoc_bao_luu_gia_han`, `doi_tuong_mua_hang`; thêm `cccd_ho_chieu` + `h_t_n` (cá nhân) hoặc `ma_so_thue_cong_ty` + `ten_cong_ty` (doanh nghiệp).	M1 - bước 1	AC-M1.2	`sapp-26878-flows.ts:1228-1238`
BR-03	`loai_phi_dich_vu` chỉ cho chọn `Phí gia hạn` hoặc `Phí bảo lưu`.	M1 - bước 1	AC-M1.3	`sapp-26878-flows.ts:1274-1276`
BR-04	Cảnh báo mềm: BU sản phẩm = CGMA ("chưa được cấp `sub_bu` / `project_code` ⇒ payload không hợp lệ, không gửi SAP và gửi mail kế toán"); loại phí lệch tên pipeline (gia hạn trên pipeline "bảo lưu" và ngược lại); `co_so_hoc__new_` trống; `ngay_ghi_nhan_doanh_thu` chỉ để đối chiếu (luồng không đọc).	M1 - bước 1	AC-M1.4	`sapp-26878-flows.ts:1239-1250,1277-1299`
BR-05	Không hiển thị (kèm lý do): `thoi_gian_ket_thuc_dao_tao_bo_sung`, `goi_khoa_hoc`, `tvts_uu_ai_bo_sung_ap_dung`, `hubspot_owner_id`.	M1 - bước 1	AC-M1.3	`sapp-26878-flows.ts:1254-1273`
BR-06	Bước 2 (Đơn hàng Ops) và bước 4 (Giao dịch) chỉ cần khi test cấn trừ tự động; cấn trừ cần giao dịch đã đồng bộ SAP (`sap_sync_status = SUCCESS`). Không test cấn trừ → bấm "Đã hiểu" để qua.	M1 - bước 2, 4	AC-M1.5	`sapp-26878-flows.ts:1301-1324`
BR-07	Bước 3 gợi ý `Thông tin thanh toán`; bước 5 gợi ý `Hoàn thành phí dịch vụ` (dev) hoặc `Won - Hoàn thành 100% phí dịch vụ` (pipeline `[UAT-TEST]` staging) — mốc bắn event SAP.	M1 - bước 3, 5	AC-M1.6	`sapp-26878-flows.ts:1310-1337`
BR-08	Bước 6 (hóa đơn) và 7 (reconcile) trên chính deal bước 1, thuộc story US-09; kèm lưu ý ngày: `posting_date` / `due_date` là ngày bấm, nhưng `external_reference` không đổi nên SAP trả chứng từ cũ.	M1 - bước 6, 7	AC-M1.7	`sapp-26878-flows.ts:1339-1357,708-709,767`

4. Design &ZeroWidthSpace;

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

text

[Chip "US-05 · Gia hạn / Bảo lưu"] → [M1: Stepper 7 bước]
  1 Tạo deal → 2 Đơn hàng Ops (tuỳ chọn, tay) → 3 Thông tin thanh toán → 4 Giao dịch (tuỳ chọn, tay)
  → 5 Hoàn thành phí DV (event SAP) → 6 Đồng bộ lại hóa đơn → 7 Đồng bộ lại reconcile → hết luồng

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

Màn M1 - Stepper flow "US-05 · Gia hạn / Bảo lưu" &ZeroWidthSpace;

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip `US-05 · Gia hạn / Bảo lưu` (Dev / Staging)
Mô tả ngắn	Tiêu đề "US-05 · Hóa đơn phí Gia hạn / Bảo lưu (Deal Won) → SAP".

Bảng bước

#	Tên bước	Loại (US-D03)	Ghi gì / ở đâu	Điều kiện chuyển sang bước sau
1	Tạo deal	`deal` (M1)	HubSpot deal + contact (Dev → dev portal; Staging → prod portal); Redis danh sách deal	Deal `us05` đã có
2	Đơn hàng Ops	`guide` (M2)	— tay, không bắt buộc (chỉ khi test cấn trừ)	Bấm "Đã hiểu"
3	Thông tin thanh toán	`stage` (M3)	HubSpot `dealstage` → `Thông tin thanh toán`	Chuyển thành công
4	Giao dịch trong đơn	`guide` (M2)	— tay, chỉ khi test cấn trừ	Bấm "Đã hiểu"
5	Hoàn thành phí DV	`stage` (M3)	HubSpot `dealstage` → `Hoàn thành phí dịch vụ` / `Won - Hoàn thành 100% phí dịch vụ` (event SAP)	Chuyển thành công
6	Đồng bộ lại hóa đơn	`resync` (M6)	`trang_thai_dong_bo_hoa_don` = `Đồng bộ lại` (story US-09)	Bấm ≥ 1 lần
7	Đồng bộ lại reconcile	`resync` (M6)	`trang_thai_tu_dong_reconcile` = `Đồng bộ lại` (story US-09)	Bấm ≥ 1 lần — hết luồng

UI States &ZeroWidthSpace;

State	Khi nào	Hiển thị	Figma frame
Default	Phiên mới	Bước 1 mở, còn lại khoá (US-D01)	N/A
Loading	Tải pipeline / stage	Theo US-D03 M1, M3	N/A
Has data	Đã tạo deal	Deal id ở thanh ngữ cảnh; "Log SAP" bật	N/A
Empty	Chưa cấu hình pipeline	Cảnh báo ở bước 1	N/A
Error	Lỗi ở bước	Theo US-D03	N/A
Disabled	Prod	Không chạy (NFR-D-02)	N/A

Fields &ZeroWidthSpace;

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
`loai_phi_dich_vu`	Yes	Enum (thu hẹp: `Phí gia hạn`, `Phí bảo lưu`)	—	—	BR-02, BR-03	"Còn thiếu: loai_phi_dich_vu"	Always	—
`tai_khoan_nhan_phi_dich_vu`, `bu_san_pham_cung_cap_dich_vu`, `muc_phi_can_dong`, `khoa_hoc_bao_luu_gia_han`, `doi_tuong_mua_hang`	Yes	Theo HubSpot	—	—	BR-02	"Còn thiếu: …"	Always	—
`cccd_ho_chieu`, `h_t_n`	Yes (cá nhân)	Text	Danh tính test	—	BR-02	"Còn thiếu: …"	Nhánh cá nhân	`doi_tuong_mua_hang`
`ma_so_thue_cong_ty`, `ten_cong_ty`	Yes (doanh nghiệp)	Text	—	—	BR-02	"Còn thiếu: …"	Nhánh doanh nghiệp	`doi_tuong_mua_hang`
`co_so_hoc__new_`, `ngay_ghi_nhan_doanh_thu`	No (khuyến nghị)	Enum / Date	—	—	BR-04	Cảnh báo mềm	Always	—
`phone_number`, `email`, `dia_chi` / `dia_chi_cong_ty`	No	Text	Danh tính test	—	—	—	Theo nhánh	—
`thoi_gian_ket_thuc_dao_tao_bo_sung`, `goi_khoa_hoc`, `tvts_uu_ai_bo_sung_ap_dung`, `hubspot_owner_id`	—	Không hiển thị (lý do)	—	—	BR-05	—	Hidden	—

Filter / Search / Sort &ZeroWidthSpace;

N/A — không phải màn List.

Actions &ZeroWidthSpace;

A1 - Tạo deal (bước 1) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Tạo deal"
Behavior	Theo US-D03 M1 A1 với spec BR-02…BR-05. ⚠️ Ghi PROD: Staging tạo deal/contact trên portal HubSpot production (NFR-D-03); BE còn route prod (NFR-D-02, OQ-D-02).
Success Result	Deal tạo xong; bước 2 mở

Error cases:

Case	Expected Handling
Thiếu field bắt buộc	"Còn thiếu: …"

A2 - Chuyển stage (bước 3, 5) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Chuyển stage"
Behavior	Theo US-D03 M3 A1 (BR-07); bước 5 là mốc bắn event SAP (REL-08). ⚠️ Ghi PROD: Staging chuyển stage trên portal production (NFR-D-03, OQ-D-02).
Success Result	Deal ở stage đích

Error cases:

Case	Expected Handling
Pipeline không có nhãn gợi ý	Chọn tay (US-D03 EC-M3.1)

A3 - Xác nhận hướng dẫn (bước 2, 4) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Đã hiểu"
Behavior	Theo US-D03 M2 (BR-06). Không ghi dữ liệu từ tool.
Success Result	Bước xong

Error cases:

Case	Expected Handling
—	Không gọi API

A4 - Đồng bộ lại (bước 6, 7) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Đồng bộ lại"
Behavior	Theo US-D03 M6 A1 (BR-08); lượt ghi vào bucket US-09. ⚠️ Ghi PROD: Staging ghi property trên portal production (NFR-D-03, OQ-D-02).
Success Result	Property = `Đồng bộ lại`

Error cases:

Case	Expected Handling
Property trống	Cảnh báo "…Kéo sang mốc `Hoàn thành phí dịch vụ` ở bước 5 trước đã."

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

AC-M1.1 - Đi hết flow không cần đơn Ops &ZeroWidthSpace;

gherkin

Given chip "US-05 · Gia hạn / Bảo lưu" trên Dev
When người dùng tạo deal, bấm "Đã hiểu" ở bước 2 và 4 mà không tạo đơn, chuyển stage bước 3 và 5, rồi đồng bộ lại bước 6, 7
Then flow đi hết 7 bước

Maps to:

Business Rule: BR-01, BR-06

AC-M1.2 - Bắt buộc theo nhánh &ZeroWidthSpace;

gherkin

Given doi_tuong_mua_hang = doanh nghiệp
When chưa điền ten_cong_ty
Then nút "Tạo deal" tắt với "Còn thiếu: ten_cong_ty"

Maps to:

Business Rule: BR-02

AC-M1.3 - Loại phí thu hẹp và field bị loại &ZeroWidthSpace;

gherkin

Given bước 1 đang mở
When người dùng mở dropdown loai_phi_dich_vu
Then chỉ có "Phí gia hạn" và "Phí bảo lưu"
And form không có ô thoi_gian_ket_thuc_dao_tao_bo_sung, goi_khoa_hoc, tvts_uu_ai_bo_sung_ap_dung, hubspot_owner_id

Maps to:

Business Rule: BR-03, BR-05

AC-M1.4 - Cảnh báo CGMA và lệch pipeline &ZeroWidthSpace;

gherkin

Given bu_san_pham_cung_cap_dich_vu = "CGMA"
Then hiện cảnh báo "BU sản phẩm = CGMA: chưa được cấp `sub_bu` / `project_code` ⇒ payload không hợp lệ, không gửi SAP và gửi mail kế toán."
Given loai_phi_dich_vu = "Phí gia hạn" và pipeline có tên chứa "bảo lưu"
Then hiện cảnh báo lệch loại phí / pipeline
And cả hai không chặn "Tạo deal"

Maps to:

Business Rule: BR-04

AC-M1.5 - Đơn Ops tuỳ chọn &ZeroWidthSpace;

gherkin

Given người dùng chỉ kiểm hóa đơn phí dịch vụ
When mở bước 2
Then hướng dẫn nói đơn hàng Ops không bắt buộc và "bấm “Đã hiểu” để sang bước sau"

Maps to:

Business Rule: BR-06

AC-M1.6 - Stage mốc theo portal &ZeroWidthSpace;

gherkin

Given portal Staging với pipeline [UAT-TEST]
When mở bước 5
Then dropdown chọn sẵn "Won - Hoàn thành 100% phí dịch vụ"
Given portal Dev
Then dropdown chọn sẵn "Hoàn thành phí dịch vụ"

Maps to:

Business Rule: BR-07

AC-M1.7 - Đồng bộ lại kèm lưu ý ngày &ZeroWidthSpace;

gherkin

Given deal đã qua mốc bước 5
When người dùng mở bước 6
Then khối hiện lưu ý "`posting_date` / `due_date` của hóa đơn là NGÀY BẤM…"
When bấm "Đồng bộ lại"
Then trang_thai_dong_bo_hoa_don = "Đồng bộ lại" và lượt ghi vào lịch sử story US-09

Maps to:

Business Rule: BR-08

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Xoá `loai_phi_dich_vu` trên HubSpot trước khi đồng bộ lại	Hint cảnh báo sẽ dựng nhầm hóa đơn học phí — dữ liệu hỏng, không phải ca âm tính hợp lệ (`sapp-26878-flows.ts:1339-1347`)
EC-M1.2	⚠️ Observed: bước 1 "Dùng deal có sẵn"	Bước 2–7 tự đánh dấu xong (US-D01 EC-M2.3) → OQ-D-06
EC-M1.3	Test cấn trừ nhưng giao dịch chưa `SUCCESS`	Tool không kiểm; cấn trừ không chạy phía hệ ngoài (BR-06)

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Mốc hoàn thành phí bắn event SAP &ZeroWidthSpace;

gherkin

Given deal đủ property bắt buộc
When bước 5 chuyển sang mốc hoàn thành phí
Then hệ ngoài phát hóa đơn phí dịch vụ (Fact theo hint)

Maps to:

REL-08 (Be Affected - webhook HubSpot → lms-be → SAP)

AC-X.2 - Kiểm kết quả bằng Log SAP &ZeroWidthSpace;

gherkin

Given deal đã qua bước 5 hoặc 6
When người dùng bấm "Log SAP"
Then log SAP của deal hiển thị theo US-P05

Maps to:

REL-03 (Affects - Tra log SAP + quét doanh thu)

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-D05: Flow P1: Gia hạn / Bảo lưu (F-P1-02 · story SAPP US-05) &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 - Stepper flow "US-05 · Gia hạn / Bảo lưu" &ZeroWidthSpace;

UI States &ZeroWidthSpace;

Fields &ZeroWidthSpace;

Filter / Search / Sort &ZeroWidthSpace;

Actions &ZeroWidthSpace;

A1 - Tạo deal (bước 1) &ZeroWidthSpace;

A2 - Chuyển stage (bước 3, 5) &ZeroWidthSpace;

A3 - Xác nhận hướng dẫn (bước 2, 4) &ZeroWidthSpace;

A4 - Đồng bộ lại (bước 6, 7) &ZeroWidthSpace;

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

AC-M1.1 - Đi hết flow không cần đơn Ops &ZeroWidthSpace;

AC-M1.2 - Bắt buộc theo nhánh &ZeroWidthSpace;

AC-M1.3 - Loại phí thu hẹp và field bị loại &ZeroWidthSpace;

AC-M1.4 - Cảnh báo CGMA và lệch pipeline &ZeroWidthSpace;

AC-M1.5 - Đơn Ops tuỳ chọn &ZeroWidthSpace;

AC-M1.6 - Stage mốc theo portal &ZeroWidthSpace;

AC-M1.7 - Đồng bộ lại kèm lưu ý ngày &ZeroWidthSpace;

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

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Mốc hoàn thành phí bắn event SAP &ZeroWidthSpace;

AC-X.2 - Kiểm kết quả bằng Log SAP &ZeroWidthSpace;