Giao diện
US-D08: Flow P1: Chuyển nhượng — 3 deal, 2 học viên (F-P1-05 · story SAPP US-13) ​
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-80 … A-83 (backlog R2 ghi A-90…A-92 — xem ghi chú lệch ở Overview §4.1). Hành vi từng loại bước → US-D03; khung stepper → US-D01.
| Field | Value |
|---|---|
| US ID | US-D08 |
| 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 us13 |
| 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 ​
text
As a Người dùng tool (Assumption — OQ về G-01)
I want dựng chuỗi ba deal chuyển nhượng khóa học giữa hai học viên (Deal gốc + Deal trừ của học viên chuyển ra,
Deal cộng của học viên nhận), kéo Won Deal cộng rồi đồng bộ lại hóa đơn
So that kiểm được luồng "Đồng bộ Deal → hóa đơn SAP" cho story US-13 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í (Deal gốc) và pipeline chuyển nhượng (Deal trừ, Deal cộng) của các flow BE us13-source, us13-minus, us13-plus đã cấu hình cho portal (sapp-26878.constants.ts:382-507).
3. Business Rules ​
| ID | Rule | Áp dụng ở | Đã cover bởi (AC) | Nguồn code (Mode B/C) |
|---|---|---|---|---|
| BR-01 | Flow có 17 bước, 3 khối (1a Deal gốc · 1b Deal trừ · 1c Deal cộng) + 1 bước đồng bộ lại; không có bước sync gói khóa học. Mọi khối cho phép "Dùng deal có sẵn". | M1 | AC-M1.1 | sapp-26878-flows.ts:2337-2374,2011-2020 |
| BR-02 | Hai học viên: Deal gốc và Deal trừ là học viên chuyển ra (cùng contact); Deal cộng là học viên nhận (contact khác). Sai vai trò → cảnh báo "… phải là CÙNG một học viên." / "… phải là HAI học viên khác nhau." (không chặn). | M1 - bước 1, 6, 12 | AC-M1.2 | sapp-26878-flows.ts:2012-2015,2060-2063,2132-2135; sapp-26878-tool.tsx:1764-1800 |
| BR-03 | Deal gốc dựng như deal học phí US-03. Deal trừ bắt buộc loai_phi_dich_vu (chỉ Chuyển nhượng), tai_khoan_nhan_phi_dich_vu, bu_san_pham_cung_cap_dich_vu, doi_tuong_mua_hang + nhánh. Deal cộng bắt buộc loai_phi_dich_vu (chỉ Không ghi nhận phí), tai_khoan_nhan_phi_dich_vu, bu_san_pham_cung_cap_dich_vu, co_so_hoc__new_, doi_tuong_mua_hang + nhánh (cccd_ho_chieu/h_t_n hoặc ma_so_thue_cong_ty/ten_cong_ty). | M1 - bước 1, 6, 12 | AC-M1.3 | sapp-26878-flows.ts:2021,2069-2076,2126-2128,2141-2149,2184-2186 |
| BR-04 | Deal trừ có bước "Gắn deal gốc" ngay sau bước tạo deal (ghi id Deal gốc vào deal_id_goc_cua_chuyen_doi). | M1 - bước 7 | AC-M1.4 | sapp-26878-flows.ts:2236-2242 |
| BR-05 | Bước đơn Ops hiện công thức đơn có id thật: order-out (deal = Deal trừ, service_fee_type = CHUYEN_NHUONG, original_deal_id = Deal gốc, sản phẩm = môn đem chuyển nhượng, final_price âm, service_fee = phí chuyển nhượng) phải tạo trước order-in (deal = Deal cộng, service_fee_type = KHONG_GHI_NHAN_PHI, original_deal_id = Deal trừ, course_packages = gói nhận). Loại phí trên hai đơn "ngược trực giác": người chuyển ra là người trả phí. | M1 - bước 8, 13 | AC-M1.5 | sapp-26878-flows.ts:2340-2342,2361-2374,2244-2262 |
| BR-06 | Stage gợi ý: Deal gốc Soạn thảo hợp đồng → Won - Hoàn tất thủ tục; Deal trừ và Deal cộng Thông tin thanh toán → Won - Hoàn tất thủ tục. Kéo Won Deal trừ không sinh sự kiện; Deal cộng là deal duy nhất bắn event, sinh 3 phần tử payloads cho 2 khách hàng (theo hint). | M1 - bước 3, 5, 9, 11, 14, 16 | AC-M1.6 | sapp-26878-flows.ts:2218-2232,2262-2280,2303-2325 |
| BR-07 | Bước 17 đồng bộ lại chỉ hóa đơn, ghim vào Deal cộng (story US-14); kèm 3 lưu ý: chỉ đặt trên Deal cộng, đứt mắt xích nào cũng hỏng, payload dựng lại từ đầu (ngày bấm). | M1 - bước 17 | AC-M1.7 | sapp-26878-flows.ts:2327-2335,2346-2358,775-779 |
4. Design ​
a. Mối liên hệ giữa các màn & User Flow ​
text
[Chip "US-13 · Chuyển nhượng"] → [M1: Stepper 17 bước, 3 hàng]
1a Deal gốc (HV chuyển ra) : 1 Tạo deal → 2 Đơn Ops → 3 Soạn thảo HĐ → 4 Giao dịch → 5 Kéo Won
1b Deal trừ (HV chuyển ra) : 6 Tạo deal → 7 Gắn deal gốc → 8 Đơn chuyển nhượng RA → 9 Thông tin TT → 10 Giao dịch → 11 Kéo Won (không event)
1c Deal cộng (HV nhận) : 12 Tạo deal → 13 Đơn chuyển nhượng VÀO → 14 Thông tin TT → 15 Giao dịch → 16 Kéo Won (event)
→ 17 Đồng bộ lại hóa đơn (Deal cộng) → hết luồngb. Chi tiết từng màn ​
Màn M1 - Stepper flow "US-13 · Chuyển nhượng" ​
| Field | Value |
|---|---|
| Figma frame | N/A |
| Trigger vào màn | Chọn chip US-13 · Chuyển nhượng (Dev / Staging) |
| Mô tả ngắn | Tiêu đề "US-13 · Chuyển nhượng khóa học giữa hai học viên (Deal Won) → SAP"; hint nêu luồng duy nhất gửi 3 phần tử payloads với 2 khách hàng và cảnh báo loại phí ngược trực giác. |
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 | 1a · Tạo deal (Deal gốc) | deal (M1) | HubSpot deal + contact HV chuyển ra (Dev → dev portal; Staging → prod portal) | Deal gốc đã có |
| 2 | 1a · Đơn hàng Ops | guide (M2) | — tay: đơn học phí | Bấm "Đã hiểu" |
| 3 | 1a · Chuyển deal stage | stage (M3) | Deal gốc → Soạn thảo hợp đồng | Chuyển thành công |
| 4 | 1a · Giao dịch trong đơn | guide (M2) | — tay | Bấm "Đã hiểu" |
| 5 | 1a · Kéo sang Won | stage (M3) | Deal gốc → Won - Hoàn tất thủ tục | Chuyển thành công |
| 6 | 1b · Tạo deal (Deal trừ) | deal (M1) | HubSpot deal, cùng contact HV chuyển ra | Deal trừ đã có |
| 7 | 1b · Gắn deal gốc | link (M5) | Deal trừ deal_id_goc_cua_chuyen_doi = id Deal gốc | Gọi thành công |
| 8 | 1b · Đơn hàng Ops | guide (M2) | — tay: đơn chuyển nhượng RA (order-out, tạo trước) | Bấm "Đã hiểu" |
| 9 | 1b · Chuyển deal stage | stage (M3) | Deal trừ → Thông tin thanh toán | Chuyển thành công |
| 10 | 1b · Giao dịch trong đơn | guide (M2) | — tay | Bấm "Đã hiểu" |
| 11 | 1b · Kéo sang Won | stage (M3) | Deal trừ → Won - Hoàn tất thủ tục (không sinh sự kiện) | Chuyển thành công |
| 12 | 1c · Tạo deal (Deal cộng) | deal (M1) | HubSpot deal + contact HV nhận (khác) | Deal cộng đã có |
| 13 | 1c · Đơn hàng Ops | guide (M2) | — tay: đơn chuyển nhượng VÀO (order-in) | Bấm "Đã hiểu" |
| 14 | 1c · Chuyển deal stage | stage (M3) | Deal cộng → Thông tin thanh toán | Chuyển thành công |
| 15 | 1c · Giao dịch trong đơn | guide (M2) | — tay | Bấm "Đã hiểu" |
| 16 | 1c · Kéo sang Won | stage (M3) | Deal cộng → Won - Hoàn tất thủ tục (bắn event) | Chuyển thành công |
| 17 | Đồng bộ lại hóa đơn | resync (M6) | Deal cộng trang_thai_dong_bo_hoa_don = Đồng bộ lại (story US-14) | 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 | Rail 3 hàng + bước đồng bộ lại; chỉ bước 1 mở | N/A |
| Loading | Tải pipeline / stage | Theo US-D03 M1, M3 | N/A |
| Has data | Có deal trong chuỗi | Bảng "Chuỗi deal đã dựng (<x>/3)" + công thức đơn | N/A |
| Empty | Chưa có deal | Công thức đơn còn trống id | N/A |
| Error | Lỗi ở bước | Theo US-D03 | N/A |
| Cảnh báo | Contact sai vai trò | "… phải là HAI học viên khác nhau." / "… phải là CÙNG một học viên." | N/A |
| Disabled | Prod | Không chạy (NFR-D-02) | N/A |
Fields ​
| Field | Required | Type | Default | Format | Validation | Error Message | Visibility | Depends On |
|---|---|---|---|---|---|---|---|---|
Deal gốc: doi_tuong_mua_hang, thoi_gian_ket_thuc_dao_tao_bo_sung (+ nhánh như US-D04) | Yes | Theo HubSpot | Danh tính test | — | BR-03 | "Còn thiếu: …" | Bước 1 | — |
Deal trừ: loai_phi_dich_vu | Yes | Enum (chỉ Chuyển nhượng) | — | — | BR-03 | "Còn thiếu: …" | Bước 6 | — |
Deal trừ: tai_khoan_nhan_phi_dich_vu, bu_san_pham_cung_cap_dich_vu, doi_tuong_mua_hang + nhánh | Yes | Theo HubSpot | — | — | BR-03 | "Còn thiếu: …" | Bước 6 | doi_tuong_mua_hang |
Deal cộng: loai_phi_dich_vu | Yes | Enum (chỉ Không ghi nhận phí) | — | — | BR-03 | "Còn thiếu: …" | Bước 12 | — |
Deal cộng: tai_khoan_nhan_phi_dich_vu, bu_san_pham_cung_cap_dich_vu, co_so_hoc__new_, doi_tuong_mua_hang + nhánh | Yes | Theo HubSpot | — | — | BR-03 | "Còn thiếu: …" | Bước 12 | doi_tuong_mua_hang |
| Contact mỗi khối | Yes | Tạo mới / chọn có sẵn | — | — | BR-02 (cảnh báo) | — | Bước 1, 6, 12 | — |
Filter / Search / Sort ​
N/A — không phải màn List.
Actions ​
A1 - Tạo deal từng khối (bước 1, 6, 12) ​
| Item | Description |
|---|---|
| Trigger | Bấm "Tạo deal" |
| Behavior | Theo US-D03 M1 A1 với spec BR-03. ⚠️ 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 của khối tạo xong |
Error cases:
| Case | Expected Handling |
|---|---|
| Thiếu field | "Còn thiếu: …" |
A2 - Gắn deal gốc (bước 7) ​
| Item | Description |
|---|---|
| Trigger | Bấm "Gắn deal gốc" |
| Behavior | Theo US-D03 M5 A1 (BR-04). ⚠️ Ghi PROD: Staging ghi lên portal production (NFR-D-03, OQ-D-02). |
| Success Result | Deal trừ mang id Deal gốc |
Error cases:
| Case | Expected Handling |
|---|---|
| Chưa có Deal gốc | Không gắn được |
A3 - Chuyển stage (bước 3, 5, 9, 11, 14, 16) ​
| Item | Description |
|---|---|
| Trigger | Bấm "Chuyển stage" |
| Behavior | Theo US-D03 M3 A1 (BR-06). ⚠️ 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 |
|---|---|
| Deal không do tool tạo | 13033 (US-D03 BR-08) |
A4 - Xác nhận hướng dẫn (bước 2, 4, 8, 10, 13, 15) ​
| Item | Description |
|---|---|
| Trigger | Bấm "Đã hiểu" |
| Behavior | Theo US-D03 M2; bước 8, 13 hiện công thức đơn (BR-05). Không ghi dữ liệu từ tool. |
| Success Result | Bước xong |
Error cases:
| Case | Expected Handling |
|---|---|
| Tạo đơn VÀO trước đơn RA | Tool không kiểm; hướng dẫn yêu cầu đơn RA trước |
A5 - Đồng bộ lại hóa đơn (bước 17) ​
| Item | Description |
|---|---|
| Trigger | Bấm "Đồng bộ lại" |
| Behavior | Theo US-D03 M6 A1 trên Deal cộng (BR-07); lượt ghi vào bucket US-14. ⚠️ Ghi PROD: Staging ghi property trên portal production (NFR-D-03, OQ-D-02). |
| Success Result | Property hóa đơn của Deal cộng = Đồng bộ lại |
Error cases:
| Case | Expected Handling |
|---|---|
| Property trống | Cảnh báo "chưa từng qua SAP" |
Acceptance Criteria của màn M1 ​
AC-M1.1 - Rail 3 hàng, 17 bước, không có sync ​
gherkin
Given chip "US-13 · Chuyển nhượng" trên Dev
When người dùng mở stepper
Then rail có 3 hàng và bước "Đồng bộ lại hóa đơn"; khối Deal gốc không có bước "Sync gói khóa học"
When người dùng hoàn tất lần lượt 17 bước
Then flow kết thúc ở bước 17Maps to:
- Business Rule: BR-01
AC-M1.2 - Hai học viên khác nhau ​
gherkin
Given Deal trừ gán contact C1 (HV chuyển ra)
When Deal cộng cũng gán C1
Then hiện cảnh báo "… đang gán cùng một contact (C1) nhưng phải là HAI học viên khác nhau."
Given Deal gốc gán C1 và Deal trừ gán C2
Then hiện cảnh báo "… phải là CÙNG một học viên."Maps to:
- Business Rule: BR-02
AC-M1.3 - Loại phí thu hẹp theo khối ​
gherkin
Given bước 6 (Deal trừ) đang mở
Then dropdown loai_phi_dich_vu chỉ có "Chuyển nhượng"
Given bước 12 (Deal cộng) đang mở
Then dropdown loai_phi_dich_vu chỉ có "Không ghi nhận phí" và co_so_hoc__new_ là bắt buộcMaps to:
- Business Rule: BR-03
AC-M1.4 - Gắn deal gốc ​
gherkin
Given đã có Deal gốc G và Deal trừ T
When người dùng chạy bước 7
Then deal_id_goc_cua_chuyen_doi của T = GMaps to:
- Business Rule: BR-04
AC-M1.5 - Công thức đơn RA / VÀO ​
gherkin
Given đã có G, T, P
When người dùng mở bước 8
Then công thức "order-out" ghi "deal_id = Deal trừ T · service_fee_type = CHUYEN_NHUONG · original_deal_id = Deal gốc G · … final_price là SỐ ÂM · service_fee = phí chuyển nhượng"
When mở bước 13
Then công thức "order-in" ghi "deal_id = Deal cộng P · service_fee_type = KHONG_GHI_NHAN_PHI · original_deal_id = Deal trừ T · …"Maps to:
- Business Rule: BR-05
AC-M1.6 - Chỉ Deal cộng bắn event ​
gherkin
Given bước 11 (Kéo sang Won Deal trừ) đang mở
Then hint nói kéo Won ở đây KHÔNG sinh sự kiện
Given bước 16 đang mở
Then hint nói đây là deal DUY NHẤT kéo Won để sinh sự kiệnMaps to:
- Business Rule: BR-06
AC-M1.7 - Đồng bộ lại chỉ Deal cộng ​
gherkin
Given Deal cộng đã kéo Won
When người dùng mở bước 17
Then bước ghim vào Deal cộng, chỉ có hóa đơn, hiện 3 lưu ý của story US-14
When bấm "Đồng bộ lại"
Then trang_thai_dong_bo_hoa_don của Deal cộng = "Đồng bộ lại" và lượt ghi vào lịch sử story US-14Maps 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 | Đặt Đồng bộ lại lên Deal trừ (ngoài tool) | Theo lưu ý: hệ ngoài không gửi, ghi FAILED + mail chỉ rõ Deal cộng |
| EC-M1.2 | Đặt lên Deal gốc (ngoài tool) | Theo lưu ý: không báo lỗi, đồng bộ nhầm hóa đơn học phí của Deal gốc |
| EC-M1.3 | Sửa lệch số môn giữa hai đơn | Theo lưu ý: đồng bộ lại lỗi "Số môn nhận chuyển nhượng (N) không bằng số môn chuyển nhượng ra (M)" |
| EC-M1.4 | ⚠️ Observed: khối dùng "deal có sẵn" | Mọi bước còn lại của khối đó tự đánh dấu xong (US-D01 EC-M2.3) → OQ-D-06 |
| EC-M1.5 | Comment code nói US-13 chưa có bước resync | Code thật đã có bước 17 — Drift DR-D-09 |
5. Cross-feature AC ​
AC-X.1 - Kéo Won Deal cộng sinh payload cho 2 khách hàng ​
gherkin
Given đơn RA và đơn VÀO nối chuỗi đúng
When bước 16 kéo Deal cộng sang Won
Then hệ ngoài gửi 3 phần tử payloads cho 2 khách hàng (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 ​
gherkin
Given chuỗi đã có deal
When người dùng bấm "Log SAP"
Then log SAP của mọi deal trong chuỗi hiển thị theo US-P05Maps to:
- REL-03 (Affects - Tra log SAP + quét doanh thu)