US-D04: Flow P1: Học phí thường (F-P1-01 · story SAPP US-03)

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-40 … A-46. Hành vi từng loại bước → US-D03; khung stepper → US-D01.

Field	Value
US ID	US-D04
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 us03
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-12, OQ-D-16 — xem Overview §6

1. US Statement

As a Người dùng tool (Assumption — OQ về G-01)
I want dựng một deal học phí thường, đi qua các mốc stage tới Won, 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-03 phase 1
        (trích shared/runbooks/sapp/sapp-26878/README.md:10); lợi ích cụ thể: [Assumption]

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B). Dependency runtime: pipeline học phí của flow us03 đã cấu hình cho portal (sapp-26878.constants.ts:382-507); người dùng có quyền thao tác trên SAPP OPS ở môi trường tương ứng (bước 2, 4 làm tay).

3. Business Rules

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 thứ tự ở bảng bước §4.b; cho phép "Dùng deal có sẵn".	M1	AC-M1.1	sapp-26878-flows.ts:1165-1217,934-936
BR-02	Bắt buộc khi tạo deal: doi_tuong_mua_hang, thoi_gian_ket_thuc_dao_tao_bo_sung; thêm cccd_ho_chieu (cá nhân) hoặc ma_so_thue_cong_ty (doanh nghiệp).	M1 - bước 1	AC-M1.2	sapp-26878-flows.ts:941-943
BR-03	Khuyến nghị (cảnh báo mềm): ngay_ghi_nhan_doanh_thu ("Chưa điền Ngày ghi nhận doanh thu → posting_date rỗng, SAP sẽ reject hóa đơn."), co_so_hoc__new_ ("Chưa điền Cơ sở học → center gửi sang SAP rỗng.").	M1 - bước 1	AC-M1.3	sapp-26878-flows.ts:944-955
BR-04	Không hiển thị (kèm lý do): goi_khoa_hoc, tvts_uu_ai_bo_sung_ap_dung (Ops ghi khi sync đơn), loai_phi_dich_vu ("Phải để trống. Có giá trị là deal bị hiểu thành deal phí dịch vụ, không phải học phí.").	M1 - bước 1	AC-M1.3	sapp-26878-flows.ts:959-979
BR-05	Bước 3 gợi ý stage Soạn thảo hợp đồng; bước 5 gợi ý Won - Hoàn tất thủ tục — mốc Won của luồng học phí, nơi event SAP bắn ra (theo hint).	M1 - bước 3, 5	AC-M1.4	sapp-26878-flows.ts:1120-1124,1136-1140
BR-06	Bước 4 hướng dẫn: tạo từng transaction trên Ops (tạo → "Chờ xác nhận" → confirm); tổng amount các transaction cần ≥ order amount.	M1 - bước 4	AC-M1.1	sapp-26878-flows.ts:987-993,1126-1134
BR-07	Bước 6 đồng bộ lại hóa đơn và bước 7 đồng bộ lại reconcile trên chính deal bước 1; cả hai thuộc story đồng bộ lại US-08.	M1 - bước 6, 7	AC-M1.5	sapp-26878-flows.ts:1147-1163,2404

4. Design

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

[Chip "US-03 · Học phí thường"] → [M1: Stepper 7 bước]
  1 Tạo deal → 2 Đơn hàng Ops (tay) → 3 Soạn thảo hợp đồng → 4 Giao dịch trong đơn (tay)
  → 5 Kéo sang Won (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

Màn M1 - Stepper flow "US-03 · Học phí thường"

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip US-03 · Học phí thường (portal Dev / Staging)
Mô tả ngắn	Tiêu đề "US-03 · Hóa đơn doanh thu học phí thường (Deal Won) → SAP"; hint "Luồng học phí thường: hóa đơn dựng từ đơn hàng Ops, công ty hạch toán suy từ pipeline của deal."

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 us03 đã có
2	Đơn hàng Ops	guide (M2)	— tay: tạo đơn cho deal bước 1 trên SAPP OPS	Bấm "Đã hiểu"
3	Soạn thảo hợp đồng	stage (M3)	HubSpot dealstage → Soạn thảo hợp đồng	Chuyển thành công
4	Giao dịch trong đơn	guide (M2)	— tay: tạo + confirm transaction, tổng ≥ order amount	Bấm "Đã hiểu"
5	Kéo sang Won	stage (M3)	HubSpot dealstage → Won - Hoàn tất thủ tục (bắn event SAP)	Chuyển thành công
6	Đồng bộ lại hóa đơn	resync (M6)	HubSpot trang_thai_dong_bo_hoa_don = Đồng bộ lại (story US-08)	Bấm ≥ 1 lần thành công
7	Đồng bộ lại reconcile	resync (M6)	HubSpot trang_thai_tu_dong_reconcile = Đồng bộ lại (story US-08)	Bấm ≥ 1 lần — hết luồng

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Phiên mới	Bước 1 mở, bước 2–7 khoá (US-D01)	N/A
Loading	Tải pipeline / stage	Theo khối US-D03 M1, M3	N/A
Has data	Đã tạo deal	Deal id hiện ở thanh ngữ cảnh + "Log SAP" bật (US-D02)	N/A
Empty	Portal chưa cấu hình pipeline us03	Cảnh báo ở bước 1 (US-D03 EC-M1.3)	N/A
Error	Lỗi ở bước	Theo khối US-D03	N/A
Disabled	Prod	Flow không chạy trên Prod (NFR-D-02)	N/A

Fields

Field của bước 1 (khối deal, US-D03 M1) — riêng flow này:

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
doi_tuong_mua_hang	Yes	Enum HubSpot	—	—	BR-02	"Còn thiếu: doi_tuong_mua_hang"	Always	—
thoi_gian_ket_thuc_dao_tao_bo_sung	Yes	Date HubSpot	—	—	BR-02	"Còn thiếu: …"	Always	—
cccd_ho_chieu	Yes (cá nhân)	Text	Danh tính test	—	BR-02	"Còn thiếu: cccd_ho_chieu"	Nhánh cá nhân	doi_tuong_mua_hang
ma_so_thue_cong_ty	Yes (doanh nghiệp)	Text	—	—	BR-02	"Còn thiếu: …"	Nhánh doanh nghiệp	doi_tuong_mua_hang
ngay_ghi_nhan_doanh_thu, co_so_hoc__new_	No (khuyến nghị)	Date / Enum	—	—	BR-03	Cảnh báo mềm	Always	—
h_t_n, phone_number, email, dia_chi	No	Text	Danh tính test	—	—	—	Nhánh cá nhân	—
ten_cong_ty, phone_number, email, dia_chi_cong_ty	No	Text	—	—	—	—	Nhánh doanh nghiệp	—
hubspot_owner_id	No	Dropdown (3 owner cố định, OQ-D-12)	—	—	—	—	Always	—
goi_khoa_hoc, tvts_uu_ai_bo_sung_ap_dung, loai_phi_dich_vu	—	Không hiển thị (lý do)	—	—	BR-04	—	Hidden	—

Filter / Search / Sort

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

Actions

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

Item	Description
Trigger	Bấm "Tạo deal"
Behavior	Theo US-D03 M1 A1 với spec BR-02…BR-04. ⚠️ 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 [IT TEST][SAPP-26878] US-03 … <n>; 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)

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

Error cases:

Case	Expected Handling
Deal không do tool tạo	13033 (US-D03 BR-08)

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

Item	Description
Trigger	Bấm "Đã hiểu"
Behavior	Theo US-D03 M2; người dùng tự làm trên SAPP OPS (OQ-D-10). 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)

Item	Description
Trigger	Bấm "Đồng bộ lại"
Behavior	Theo US-D03 M6 A1 (BR-07); ghi lượt vào bucket story US-08. ⚠️ 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ước đó trống	Cảnh báo "Property này đang trống — deal chưa từng qua SAP… Kéo Won ở bước 5 trước đã." (bước 6) / "…Thường phải đồng bộ lại hóa đơn (bước 6) xong trước." (bước 7)

Acceptance Criteria của màn M1

AC-M1.1 - Đi hết 7 bước

Given chip "US-03 · Học phí thường" trên Dev
When người dùng lần lượt hoàn tất bước 1 → 7 theo bảng bước
Then mỗi bước mở sau khi bước trước xong, bước 2 và 4 xong khi bấm "Đã hiểu"
And bước 7 hiện "… hết luồng"

Maps to:

• Business Rule: BR-01, BR-06

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

Given doi_tuong_mua_hang = cá nhân
When chưa điền cccd_ho_chieu
Then nút "Tạo deal" tắt với "Còn thiếu: cccd_ho_chieu"
Given doi_tuong_mua_hang = doanh nghiệp
Then field bắt buộc là ma_so_thue_cong_ty thay cho cccd_ho_chieu

Maps to:

• Business Rule: BR-02

AC-M1.3 - Khuyến nghị và field bị loại

Given bước 1 đang mở
When ngay_ghi_nhan_doanh_thu để trống
Then hiện cảnh báo "Chưa điền Ngày ghi nhận doanh thu → `posting_date` rỗng, SAP sẽ reject hóa đơn." nhưng vẫn tạo được deal
And form không có ô goi_khoa_hoc, tvts_uu_ai_bo_sung_ap_dung, loai_phi_dich_vu mà hiện lý do loại

Maps to:

• Business Rule: BR-03, BR-04

AC-M1.4 - Stage gợi ý

Given deal đã tạo ở pipeline học phí
When mở bước 3
Then dropdown chọn sẵn "Soạn thảo hợp đồng"
When mở bước 5
Then dropdown chọn sẵn "Won - Hoàn tất thủ tục"

Maps to:

• Business Rule: BR-05

AC-M1.5 - Đồng bộ lại hai loại trên cùng deal

Given deal bước 1 đã kéo Won
When người dùng bấm "Đồng bộ lại" ở bước 6 rồi ở bước 7
Then trang_thai_dong_bo_hoa_don rồi trang_thai_tu_dong_reconcile của chính deal đó = "Đồng bộ lại"
And mỗi lần bấm thêm một lượt vào lịch sử story US-08

Maps to:

• Business Rule: BR-07

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Kéo Won khi chưa tạo đơn / giao dịch trên Ops	Tool không kiểm (bước 2, 4 chỉ là hướng dẫn); hệ ngoài có thể không phát hóa đơn
EC-M1.2	⚠️ Observed: bước 1 chọn "Dùng deal có sẵn"	Bước 2–7 tự đánh dấu "đã bỏ qua" và tính là xong (US-D01 EC-M2.3) → OQ-D-06
EC-M1.3	Bấm bước 7 trước khi bước 6 từng chạy	Không xảy ra qua gate; nếu bỏ qua bước 6 thì bước 7 vẫn ghi và cảnh báo nếu property trống
EC-M1.4	⚠️ Observed: contact mới trùng email trên Staging	Contact thật trên portal prod bị cập nhật (US-D03 EC-M1.5) → OQ-D-16

5. Cross-feature AC

AC-X.1 - Kéo Won bắn event SAP

Given đơn và giao dịch đã có trên Ops
When bước 5 kéo deal sang "Won - Hoàn tất thủ tục"
Then hệ ngoài (webhook HubSpot → lms-be → SAP) phát hóa đơn và ghi trạng thái về deal (Fact theo hint)

Maps to:

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

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

Given deal bước 1 đã kéo Won hoặc đã đồng bộ lại
When người dùng bấm "Log SAP"
Then log SAP của deal hiển thị theo US-P05 (sự kiện, bước SAP_CALLED, callback)

Maps to:

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

Ghi chú: deal của flow này đồng bộ lại được cả từ màn "Re-sync US-03" (US-D18) — liên hệ nội bộ FS, không phải REL.