US-D07: Flow P1: Chuyển đổi — chuỗi 3 deal (F-P1-04 · story SAPP US-11) &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-70 … A-74. Hành vi từng loại bước → US-D03; khung stepper → US-D01.

Field	Value
US ID	US-D07
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 `us11`
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 &ZeroWidthSpace;

text

As a Người dùng tool (Assumption — OQ về G-01)
I want dựng chuỗi ba deal chuyển đổi khóa học (Deal gốc → Deal trừ → Deal cộng) với đơn Ops nối chuỗi, 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-11 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 học phí (Deal gốc) và pipeline chuyển đổi (Deal trừ, Deal cộng) của các flow BE us11-source, us11-minus, us11-plus đã 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ó 18 bước, chia 3 khối deal (1a Deal gốc · 1b Deal trừ · 1c Deal cộng) + 1 bước đồng bộ lại; rail hiện mỗi khối một hàng. Mọi khối cho phép "Dùng deal có sẵn".	M1	AC-M1.1	`sapp-26878-flows.ts:1976-2009`; `chainSteps` `:1024-1082`
BR-02	Cả ba deal là cùng một học viên: gán contact khác nhau giữa các khối → cảnh báo "… phải là CÙNG một học viên." (không chặn).	M1 - bước 1, 7, 13	AC-M1.2	`sapp-26878-flows.ts:1638-1641,1685-1688,1748-1751`; `sapp-26878-tool.tsx:1764-1800`
BR-03	Deal gốc dựng như deal học phí US-03 (bắt buộc `doi_tuong_mua_hang`, `thoi_gian_ket_thuc_dao_tao_bo_sung` + nhánh). Deal trừ bắt buộc `loai_phi_dich_vu` (chỉ `Không ghi nhận phí`) + `doi_tuong_mua_hang`. Deal cộng bắt buộc `loai_phi_dich_vu` (chỉ `Chuyển đổi`), `tai_khoan_nhan_phi_dich_vu`, `bu_san_pham_cung_cap_dich_vu`, `doi_tuong_mua_hang` + `cccd_ho_chieu`/`h_t_n` hoặc `ma_so_thue_cong_ty`/`ten_cong_ty`.	M1 - bước 1, 7, 13	AC-M1.3	`sapp-26878-flows.ts:1647,1694,1733-1735,1757-1764,1823-1825`
BR-04	Deal gốc có bước "Sync gói khóa học" ngay sau đơn Ops: ghi `goi_khoa_hoc` để Ops dựng Registered Course cho đơn điều chỉnh giảm ở mắt xích sau.	M1 - bước 3	AC-M1.4	`sapp-26878-flows.ts:1845-1857`
BR-05	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` của Deal trừ.	M1 - bước 8	AC-M1.5	`sapp-26878-flows.ts:1876-1881`
BR-06	Bước đơn Ops của Deal trừ và Deal cộng hiện "công thức đơn" kèm deal id thật: `order-tru` (deal = Deal trừ, `service_fee_type = KHONG_GHI_NHAN_PHI`, `original_deal_id` = Deal gốc, sản phẩm chứa cả môn cũ lẫn môn mới, `final_price` âm) và `order-cong` (deal = Deal cộng, `service_fee_type = CHUYEN_DOI`, `original_deal_id` = Deal trừ, sản phẩm = môn mới).	M1 - bước 9, 14	AC-M1.6	`sapp-26878-flows.ts:1997-2008`
BR-07	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 (đúng thiết kế theo hint); Deal cộng là deal duy nhất bắn event, một sự kiện sinh 3 chứng từ.	M1 - bước 4, 6, 10, 12, 15, 17	AC-M1.7	`sapp-26878-flows.ts:1857-1873,1903-1921,1944-1964`
BR-08	Bước 18 đồng bộ lại chỉ hóa đơn, ghim vào Deal cộng (story US-12); kèm 3 lưu ý theo thứ tự: chỉ đặt trên Deal cộng (đặt trên Deal gốc không báo lỗi mà đồng bộ nhầm hóa đơn học phí của chính nó), đứ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 18	AC-M1.8	`sapp-26878-flows.ts:1966-1974,1985-1994,730-779`

4. Design &ZeroWidthSpace;

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

text

[Chip "US-11 · Chuyển đổi"] → [M1: Stepper 18 bước, 3 hàng]
  1a Deal gốc : 1 Tạo deal → 2 Đơn Ops → 3 Sync gói khóa học → 4 Soạn thảo HĐ → 5 Giao dịch → 6 Kéo Won
  1b Deal trừ : 7 Tạo deal → 8 Gắn deal gốc → 9 Đơn điều chỉnh giảm → 10 Thông tin TT → 11 Giao dịch → 12 Kéo Won (không event)
  1c Deal cộng: 13 Tạo deal → 14 Đơn chuyển đổi → 15 Thông tin TT → 16 Giao dịch → 17 Kéo Won (event, 3 chứng từ)
  → 18 Đồng bộ lại hóa đơn (Deal cộng) → hết luồng

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

Màn M1 - Stepper flow "US-11 · Chuyển đổi" &ZeroWidthSpace;

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip `US-11 · Chuyển đổi` (Dev / Staging)
Mô tả ngắn	Hint: "Luồng phức tạp nhất: MỘT sự kiện sinh BA chứng từ trên BA deal … Chuỗi được nối bằng `original_deal_id` của hai đơn Ops, KHÔNG có gì trên HubSpot thể hiện liên kết này." Bảng "Chuỗi deal đã dựng (`<x>`/3)".

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 (Dev → dev portal; Staging → prod portal)	Deal gốc đã có
2	1a · Đơn hàng Ops	`guide` (M2)	— tay: đơn học phí cho Deal gốc	Bấm "Đã hiểu"
3	1a · Sync gói khóa học	`sync` (M4)	HubSpot Deal gốc `goi_khoa_hoc`	Gọi thành công
4	1a · Chuyển deal stage	`stage` (M3)	Deal gốc → `Soạn thảo hợp đồng`	Chuyển thành công
5	1a · Giao dịch trong đơn	`guide` (M2)	— tay	Bấm "Đã hiểu"
6	1a · Kéo sang Won	`stage` (M3)	Deal gốc → `Won - Hoàn tất thủ tục`	Chuyển thành công
7	1b · Tạo deal (Deal trừ)	`deal` (M1)	HubSpot deal + contact	Deal trừ đã có
8	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
9	1b · Đơn hàng Ops	`guide` (M2)	— tay: đơn điều chỉnh giảm theo `order-tru`	Bấm "Đã hiểu"
10	1b · Chuyển deal stage	`stage` (M3)	Deal trừ → `Thông tin thanh toán`	Chuyển thành công
11	1b · Giao dịch trong đơn	`guide` (M2)	— tay	Bấm "Đã hiểu"
12	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
13	1c · Tạo deal (Deal cộng)	`deal` (M1)	HubSpot deal + contact	Deal cộng đã có
14	1c · Đơn hàng Ops	`guide` (M2)	— tay: đơn chuyển đổi theo `order-cong`	Bấm "Đã hiểu"
15	1c · Chuyển deal stage	`stage` (M3)	Deal cộng → `Thông tin thanh toán`	Chuyển thành công
16	1c · Giao dịch trong đơn	`guide` (M2)	— tay	Bấm "Đã hiểu"
17	1c · Kéo sang Won	`stage` (M3)	Deal cộng → `Won - Hoàn tất thủ tục` (bắn event, 3 chứng từ)	Chuyển thành công
18	Đồng bộ lại hóa đơn	`resync` (M6)	Deal cộng `trang_thai_dong_bo_hoa_don` = `Đồng bộ lại` (story US-12)	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	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 với deal id thật	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à CÙNG một học viên."	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
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ỉ `Không ghi nhận phí`)	—	—	BR-03	"Còn thiếu: …"	Bước 7	—
Deal trừ: `doi_tuong_mua_hang`	Yes	Enum	—	—	BR-03	"Còn thiếu: …"	Bước 7	—
Deal cộng: `loai_phi_dich_vu`	Yes	Enum (chỉ `Chuyển đổi`)	—	—	BR-03	"Còn thiếu: …"	Bước 13	—
Deal cộng: `tai_khoan_nhan_phi_dich_vu`, `bu_san_pham_cung_cap_dich_vu`, `doi_tuong_mua_hang`	Yes	Theo HubSpot	—	—	BR-03	"Còn thiếu: …"	Bước 13	—
Deal cộng: `cccd_ho_chieu`, `h_t_n` / `ma_so_thue_cong_ty`, `ten_cong_ty`	Yes theo nhánh	Text	Danh tính test	—	BR-03	"Còn thiếu: …"	Bước 13	`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, 7, 13	—

Filter / Search / Sort &ZeroWidthSpace;

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

Actions &ZeroWidthSpace;

A1 - Tạo deal từng khối (bước 1, 7, 13) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Tạo deal" ở bước deal của khối
Behavior	Theo US-D03 M1 A1 với spec BR-03; mỗi bước deal chỉ cần deal của chính khối đó. ⚠️ 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; bảng chuỗi tăng `<x>`/3

Error cases:

Case	Expected Handling
Thiếu field	"Còn thiếu: …"

A2 - Sync gói khóa học (bước 3) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Đồng bộ gói khóa học"
Behavior	Theo US-D03 M4 A1 (BR-04). ⚠️ Ghi PROD: Staging ghi lên portal production (NFR-D-03, OQ-D-02).
Success Result	`goi_khoa_hoc` của Deal gốc cập nhật

Error cases:

Case	Expected Handling
Không có giá trị mới	Không ghi (US-D03 EC-M4.1)

A3 - Gắn deal gốc (bước 8) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Gắn deal gốc"
Behavior	Theo US-D03 M5 A1 (BR-05). ⚠️ 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

A4 - Chuyển stage (bước 4, 6, 10, 12, 15, 17) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Chuyển stage"
Behavior	Theo US-D03 M3 A1 (BR-07). ⚠️ 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
Kéo Won Deal cộng trước khi hai đơn Ops đúng `original_deal_id`	Tool không kiểm; theo hint luồng không chạy phía hệ ngoài

A5 - Xác nhận hướng dẫn (bước 2, 5, 9, 11, 14, 16) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Đã hiểu"
Behavior	Theo US-D03 M2; bước 9, 14 hiện công thức đơn (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

A6 - Đồng bộ lại hóa đơn (bước 18) &ZeroWidthSpace;

Item	Description
Trigger	Bấm "Đồng bộ lại"
Behavior	Theo US-D03 M6 A1 trên Deal cộng (BR-08); lượt ghi vào bucket US-12. ⚠️ 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 &ZeroWidthSpace;

AC-M1.1 - Rail 3 hàng, đi hết 18 bước &ZeroWidthSpace;

gherkin

Given chip "US-11 · Chuyển đổi" trên Dev
When người dùng mở stepper
Then rail có 3 hàng "1a · Deal gốc", "1b · Deal trừ", "1c · Deal cộng" và bước "Đồng bộ lại hóa đơn"
When người dùng hoàn tất lần lượt 18 bước
Then flow kết thúc ở bước 18 "… hết luồng"

Maps to:

Business Rule: BR-01

AC-M1.2 - Cảnh báo contact khác học viên &ZeroWidthSpace;

gherkin

Given Deal gốc gán contact C1
When Deal trừ gán contact C2 (khác C1)
Then hiện cảnh báo "1a · Deal gốc và 1b · Deal trừ đang gán hai contact khác nhau (C1 vs C2) nhưng phải là CÙNG một học viên."
And vẫn cho tạo deal

Maps to:

Business Rule: BR-02

AC-M1.3 - Loại phí thu hẹp theo khối &ZeroWidthSpace;

gherkin

Given bước 7 (Deal trừ) đang mở
Then dropdown loai_phi_dich_vu chỉ có "Không ghi nhận phí"
Given bước 13 (Deal cộng) đang mở
Then dropdown loai_phi_dich_vu chỉ có "Chuyển đổi" và bắt buộc thêm tai_khoan_nhan_phi_dich_vu, bu_san_pham_cung_cap_dich_vu

Maps to:

Business Rule: BR-03

AC-M1.4 - Sync gói khóa học trên Deal gốc &ZeroWidthSpace;

gherkin

Given đơn Ops của Deal gốc đã sync property lộ trình
When người dùng chạy bước 3
Then goi_khoa_hoc của Deal gốc được gộp theo US-D03 BR-12

Maps to:

Business Rule: BR-04

AC-M1.5 - Gắn deal gốc lên Deal trừ &ZeroWidthSpace;

gherkin

Given đã có Deal gốc G và Deal trừ T
When người dùng chạy bước 8
Then deal_id_goc_cua_chuyen_doi của T = G

Maps to:

Business Rule: BR-05

AC-M1.6 - Công thức đơn có id thật &ZeroWidthSpace;

gherkin

Given đã có Deal gốc G, Deal trừ T, Deal cộng P
When người dùng mở bước 14
Then công thức "order-cong" ghi "deal_id = Deal cộng P · service_fee_type = CHUYEN_DOI · original_deal_id = Deal trừ T · …"
And công thức "order-tru" ghi "deal_id = Deal trừ T · service_fee_type = KHONG_GHI_NHAN_PHI · original_deal_id = Deal gốc G · … final_price là SỐ ÂM"

Maps to:

Business Rule: BR-06

AC-M1.7 - Stage gợi ý theo khối &ZeroWidthSpace;

gherkin

Given bước 12 (Kéo sang Won của Deal trừ) đang mở
Then dropdown chọn sẵn "Won - Hoàn tất thủ tục" và hint nói kéo Won ở đây KHÔNG sinh sự kiện
Given bước 17 đang mở
Then hint nói đây là deal DUY NHẤT kéo Won để sinh sự kiện

Maps to:

Business Rule: BR-07

AC-M1.8 - Đồng bộ lại chỉ Deal cộng, chỉ hóa đơn &ZeroWidthSpace;

gherkin

Given chuỗi đã kéo Won Deal cộng
When người dùng mở bước 18
Then bước ghim vào Deal cộng, chỉ có hóa đơn, hiện 3 lưu ý với lưu ý "Chỉ đặt `Đồng bộ lại` trên DEAL CỘNG…" đứng đầu
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-12

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	Tự đặt `Đồng bộ lại` lên Deal gốc trên HubSpot (ngoài tool)	Theo lưu ý: không báo lỗi mà đồng bộ nhầm hóa đơn học phí của Deal gốc
EC-M1.2	Xoá / huỷ một mắt xích sau khi Won	Đồng bộ lại hỏng (lưu ý đứt chuỗi)
EC-M1.3	⚠️ 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.4	Bước deal của khối sau khi khối trước chưa xong	Bị khoá bởi gate (US-D01 BR-06)

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Kéo Won Deal cộng sinh 3 chứng từ &ZeroWidthSpace;

gherkin

Given hai đơn Ops nối chuỗi đúng original_deal_id
When bước 17 kéo Deal cộng sang Won
Then hệ ngoài sinh 3 chứng từ trên 3 deal (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 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-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-D07: Flow P1: Chuyển đổi — chuỗi 3 deal (F-P1-04 · story SAPP US-11) &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-11 · Chuyển đổi" &ZeroWidthSpace;

UI States &ZeroWidthSpace;

Fields &ZeroWidthSpace;

Filter / Search / Sort &ZeroWidthSpace;

Actions &ZeroWidthSpace;

A1 - Tạo deal từng khối (bước 1, 7, 13) &ZeroWidthSpace;

A2 - Sync gói khóa học (bước 3) &ZeroWidthSpace;

A3 - Gắn deal gốc (bước 8) &ZeroWidthSpace;

A4 - Chuyển stage (bước 4, 6, 10, 12, 15, 17) &ZeroWidthSpace;

A5 - Xác nhận hướng dẫn (bước 2, 5, 9, 11, 14, 16) &ZeroWidthSpace;

A6 - Đồng bộ lại hóa đơn (bước 18) &ZeroWidthSpace;

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

AC-M1.1 - Rail 3 hàng, đi hết 18 bước &ZeroWidthSpace;

AC-M1.2 - Cảnh báo contact khác học viên &ZeroWidthSpace;

AC-M1.3 - Loại phí thu hẹp theo khối &ZeroWidthSpace;

AC-M1.4 - Sync gói khóa học trên Deal gốc &ZeroWidthSpace;

AC-M1.5 - Gắn deal gốc lên Deal trừ &ZeroWidthSpace;

AC-M1.6 - Công thức đơn có id thật &ZeroWidthSpace;

AC-M1.7 - Stage gợi ý theo khối &ZeroWidthSpace;

AC-M1.8 - Đồng bộ lại chỉ Deal cộng, chỉ hóa đơn &ZeroWidthSpace;

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

5. Cross-feature AC &ZeroWidthSpace;

AC-X.1 - Kéo Won Deal cộng sinh 3 chứng từ &ZeroWidthSpace;

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