US-D18: Đồng bộ lại theo story và gửi lại thô (5 màn re-sync, 3 màn gửi lại)

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-90, A-91, A-92, E-03 … E-06. Chip "Trace log SAP" và "Chạy lượt quét" → US-P05 (không lặp).

Field	Value
US ID	US-D18
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) — story đồng bộ lại phase 1 (US-08/09/10/12/14) + gửi lại thô (phase 1 và 2)
Priority	N/A (as-built)
Status	Draft
NFR liên quan	NFR-D-01, NFR-D-02, NFR-D-03, NFR-D-04, NFR-D-05, NFR-D-08 — xem Overview §5
OQ liên quan	OQ-D-01, OQ-D-02, OQ-D-13, OQ-D-17 — xem Overview §6

1. US Statement

As a Người dùng tool (Assumption — OQ về G-01)
I want chọn lại một lượt test cũ của flow phase 1 và bắn đồng bộ lại hóa đơn / reconcile cho đúng deal, xem lịch sử các lần bấm;
       và gửi lại sang SAP một giao dịch, một bút toán hoặc mọi dòng lỗi của một lớp theo id
So that kiểm được các story đồng bộ lại (US-08/09/10/12/14) của "Đồng bộ Deal → hóa đơn SAP" và phần gửi lại của DTTH
        (trích shared/runbooks/sapp/sapp-26878/README.md:10-11); lợi ích cụ thể: [Assumption]

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B). Dependency runtime:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Lượt test phase 1 đã ghi trong lịch sử (US-D02)	Người dùng	N/A — runtime
D2	Ops passthrough cho các route gửi lại SAP (→ US-P08)	BE	N/A — runtime

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Có 5 chip đồng bộ lại, đặt theo flow nguồn: "Re-sync US-03" = story US-08, "Re-sync US-05" = US-09, "Re-sync US-06" = US-10, "Re-sync US-11" = US-12, "Re-sync US-13" = US-14. Mỗi màn chỉ liệt kê flow nguồn thuộc đúng story đó.	M1	AC-M1.1	sapp-26878-flows.ts:2397-2446; sapp-26878-resync-tool.tsx:268-275
BR-02	Màn liệt kê các lượt test của flow nguồn trên portal đang chọn; với mỗi deal chỉ hiện nút cho deal + loại mà flow nguồn khai ở bước resync (US-11/13: Deal cộng + hóa đơn; US-03/05/06: hóa đơn + reconcile); deal không được phép hiện "mắt xích trung gian".	M1 - danh sách lượt	AC-M1.2	sapp-26878-flows.ts:2458-2470; sapp-26878-resync-tool.tsx:121-190
BR-03	Bấm hóa đơn / reconcile → ghi Đồng bộ lại vào property tương ứng của deal (như bước resync, US-D03 M6), rồi ghi một bản ghi mới (mã mới) vào lịch sử của story — mỗi lần bấm một bản ghi; lỗi ghi lịch sử không báo.	M1 - action Đồng bộ lại	AC-M1.3	sapp-26878-resync-tool.tsx:77-106; sapp-26878-tool.tsx:1526-1545
BR-04	Màn hiện giải thích chung + phần riêng của story và các lưu ý payload của story (cùng nội dung với bước resync trong stepper; story US-08 không có lưu ý).	M1	AC-M1.4	sapp-26878-resync-tool.tsx:44-50,283-296; sapp-26878-flows.ts:780-790
BR-05	"Lịch sử đồng bộ lại (<story>)": mỗi dòng một lần bấm, mới nhất trước, gồm thời điểm, loại (hóa đơn / reconcile), deal, flow nguồn; lưu tách riêng khỏi lịch sử dựng deal và khỏi story khác; tự đọc lại sau mỗi lần bấm thành công.	M1 - lịch sử	AC-M1.5	sapp-26878-resync-tool.tsx:195-266,316-330
BR-06	Có 3 chip gửi lại thô trong nhóm Trace, mỗi chip một màn: "Gửi lại bút toán" (Phase 2, entry_id), "Gửi lại lớp" (Phase 2, class_id — mọi dòng lỗi của lớp), "Gửi lại giao dịch" (Phase 1, transaction_id). Mỗi màn ghi rõ phase và lưu ý đối tượng.	M2	AC-M2.1	sap-resync-panel.tsx:41-73; sapp-26878-tool.tsx:2105-2122
BR-07	Gửi lại thô: id trống → "Chưa điền id." (không gọi); thành công → in nguyên dữ liệu trả về; lỗi → thông điệp lỗi hoặc "Lỗi không rõ.".	M2 - action Gửi lại	AC-M2.2, AC-M2.3	sap-resync-panel.tsx:120-160
BR-08	Mọi chip của US này chỉ bật Dev + Staging (giao diện); màn gửi lại ghi rõ "⛔ Ghi dữ liệu — cố ý không có trên prod."	M1, M2	AC-M2.4	sapp-26878-tool.tsx:91-119; sap-resync-panel.tsx:75-83,166-170

⚠️ Observed (không viết thành BR): loại / nguồn của mỗi lần bấm không được BE lưu (EC-M1.2, OQ-D-01, DR-D-01); lịch sử chỉ trên Redis 30 ngày / 50 bản ghi (NFR-D-05, OQ-D-17); BE có route prod cho đồng bộ lại và cả 3 route gửi lại (NFR-D-02, OQ-D-02).

4. Design

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

[US-D01.M1 Khung tool]
  ├─ chip "Re-sync US-0x" (nhóm Phase 1) ──→ [M1: Đồng bộ lại theo story]
  │       chọn flow nguồn → chọn lượt → bấm hóa đơn / reconcile → lịch sử đồng bộ lại tự làm mới
  ├─ chip "Gửi lại bút toán" / "Gửi lại lớp" / "Gửi lại giao dịch" (nhóm Trace) ──→ [M2: Gửi lại thô]
  └─ chip "Chạy lượt quét" / "Trace log SAP" (nhóm Trace) ──→ [M3: tham chiếu US-P05]

b. Chi tiết từng màn

Màn M1 - Đồng bộ lại theo story ("Re-sync US-03/05/06/11/13")

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip "Re-sync US-0x"
Mô tả ngắn	Hai phần: "Chọn bản test để đồng bộ lại (<story>)" (giải thích, lưu ý, chọn flow nguồn, danh sách lượt) và "Lịch sử đồng bộ lại (<story>)".

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa mở	Flow nguồn đầu tiên của story được chọn	N/A
Loading	Tải lượt / lịch sử	"Đang tải…"	N/A
Has data	Có lượt	Thẻ "Bản test <thời điểm>" với từng deal + nút	N/A
Empty	Flow nguồn chưa có lượt	"Luồng này chưa có bản test nào trên portal <env>. Dựng một deal ở luồng đó trước, rồi quay lại đây."	N/A
Empty (lịch sử)	Chưa bấm lần nào	"Chưa có lần đồng bộ lại nào của <story> trên portal <env>."	N/A
Error	Tải / ghi lỗi	"Không tải được danh sách bản test" / "Không tải được lịch sử đồng bộ lại" / "Không đặt được trạng thái đồng bộ lại"	N/A
Disabled	Một lần bấm đang chạy	Mọi nút tạm tắt; nút đang chạy có spinner	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Flow nguồn	Yes	Dropdown (các flow thuộc story)	Flow đầu tiên	—	BR-01	—	Always (story có 1 flow nguồn → 1 lựa chọn)	Chip story
Lượt test (thẻ)	—	Readonly: thời điểm tạo, deal (nhãn, tên)	—	Locale vi-VN	—	—	Always	Flow nguồn, portal
Dòng lịch sử	—	Readonly: thời điểm, loại, deal, "từ <flow nguồn>"	—	—	—	—	Always	Story, portal

Filter / Search / Sort

Loại	Theo field	Kiểu	Default	Notes
Filter	Flow nguồn	Dropdown	Flow đầu tiên của story	Portal lấy từ khung tool
Search	—	—	—	Không có
Sort	Thời điểm	Giảm dần	Mới nhất trước	BE trả sẵn thứ tự
Pagination	—	Không có	Tối đa 50 bản ghi / bucket (⚠️ Observed, NFR-D-05)	—

Actions

A1 - Đồng bộ lại một deal của lượt cũ

Item	Description
Trigger	Bấm "hóa đơn" hoặc "reconcile" ở một deal
Behavior	Ghi Đồng bộ lại vào trang_thai_dong_bo_hoa_don / trang_thai_tu_dong_reconcile của deal trên HubSpot của portal (Dev → dev portal; Staging → prod portal); BE chỉ nhận deal do tool tạo (NFR-D-04). Ghi bản ghi mới vào bucket story trên Redis mind_keep (BR-03). Làm mới lịch sử. ⚠️ Ghi PROD: Staging ghi lên deal của portal HubSpot production (NFR-D-03); BE có route prod/sapp-26878/deals/{dealId}/resync (NFR-P-01, NFR-D-02, OQ-D-02).
Success Result	Property = Đồng bộ lại; dòng mới trong lịch sử

Error cases:

Case	Expected Handling
BE / HubSpot lỗi	"Không đặt được trạng thái đồng bộ lại"; không ghi lịch sử
Deal không do tool tạo	400 13033 → như trên

Acceptance Criteria của màn M1

AC-M1.1 - Chip đúng story

Given người dùng chọn chip "Re-sync US-11"
When màn mở
Then tiêu đề phần là "Chọn bản test để đồng bộ lại (US-12)" và dropdown flow nguồn chỉ có "US-11 · Chuyển đổi"

Maps to:

• Business Rule: BR-01

AC-M1.2 - Nút theo rule flow nguồn

Given lượt test của "US-13 · Chuyển nhượng" có 3 deal
When màn "Re-sync US-13" liệt kê lượt đó
Then chỉ Deal cộng có nút "hóa đơn"; Deal gốc và Deal trừ hiện "mắt xích trung gian"
Given lượt test của "US-03"
Then deal có cả "hóa đơn" và "reconcile"

Maps to:

• Business Rule: BR-02

AC-M1.3 - Mỗi lần bấm một bản ghi

Given lượt test US-05 có deal D
When người dùng bấm "hóa đơn" hai lần
Then property hóa đơn của D = "Đồng bộ lại" sau mỗi lần
And lịch sử đồng bộ lại US-09 có thêm 2 dòng riêng

Maps to:

• Business Rule: BR-03, BR-05

AC-M1.4 - Lưu ý payload theo story

Given người dùng mở "Re-sync US-06"
Then màn hiện lưu ý môn thi trước, lưu ý ngày bấm sau
Given người dùng mở "Re-sync US-03"
Then màn không hiện lưu ý payload nào

Maps to:

• Business Rule: BR-04

AC-M1.5 - Lịch sử tách riêng, tự làm mới

Given lịch sử US-08 trống trên Dev
When người dùng bấm "reconcile" thành công
Then phần "Lịch sử đồng bộ lại (US-08)" tự tải lại và có 1 dòng mới nhất ở đầu
And lịch sử dựng deal của flow US-03 (US-D02) không thay đổi vì lần bấm này

Maps to:

• Business Rule: BR-05

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Lượt test ở portal khác	Không hiện (lọc theo portal hiện tại)
EC-M1.2	⚠️ Observed: dòng lịch sử cần "loại" và "từ <flow>"	Hành vi hiện tại: BE không lưu trigger / sourceFlow → cột loại hiện —, không hiện "từ <flow>" (sapp-26878-resync-tool.tsx:228-238; common.service.ts:1145-1156) → OQ-D-01, DR-D-01
EC-M1.3	Bấm khi deal chưa từng qua SAP	Vẫn ghi Đồng bộ lại (US-D03 BR-14); màn này không hiện cảnh báo "chưa từng qua SAP" như bước trong stepper (TODO: xác nhận bằng chạy thử)
EC-M1.4	Lỗi ghi lịch sử	Không báo; lần bấm vẫn tính thành công

Màn M2 - Gửi lại thô sang SAP ("Gửi lại bút toán" · "Gửi lại lớp" · "Gửi lại giao dịch")

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn một trong 3 chip gửi lại ở nhóm Trace
Mô tả ngắn	Tiêu đề theo loại ("Gửi lại MỘT bút toán" / "Gửi lại mọi dòng lỗi của MỘT LỚP" / "Gửi lại MỘT giao dịch"); hint "<Phase> · endpoint Ops. Đang trỏ portal <env>. ⛔ Ghi dữ liệu — cố ý không có trên prod."; nhãn phase, ô id, nút "Gửi lại", lưu ý đối tượng.

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa mở	Nhãn phase + ô id + "Gửi lại"	N/A
Loading	Đang gửi	Spinner trên nút	N/A
Has data	Thành công	Khung xanh in nguyên dữ liệu trả về	N/A
Empty	Id trống khi bấm	"Chưa điền id."	N/A
Error	Lỗi	Thông điệp lỗi hoặc "Lỗi không rõ."	N/A
Disabled	Đang gửi	Nút tắt	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
entry_id	Yes	Text (uuid dòng trong sap_revenue_lesson_entries)	—	Bỏ khoảng trắng	Không trống	"Chưa điền id."	Chip "Gửi lại bút toán"	—
class_id	Yes	Text (uuid lớp)	—	Bỏ khoảng trắng	Không trống	"Chưa điền id."	Chip "Gửi lại lớp"	—
transaction_id	Yes	Text (transactionId phía Ops)	—	Bỏ khoảng trắng	Không trống	"Chưa điền id."	Chip "Gửi lại giao dịch"	—

Filter / Search / Sort

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

Actions

A1 - Gửi lại

Item	Description
Trigger	Bấm "Gửi lại"
Behavior	Gọi route gửi lại SAP của SAPP Ops qua passthrough (US-P08) ở portal đang chọn (Dev → Ops dev; Staging → Ops staging): gửi lại một bút toán / mọi dòng lỗi của lớp / một giao dịch; Ops gửi sang SAP (BR-06, BR-07). ⚠️ Ghi PROD: giao diện chặn Prod (BR-08) nhưng BE có đủ 3 route prod (sapp-ops.controller.ts:1651,1667,2350) (NFR-P-01, NFR-D-02, OQ-D-02).
Success Result	Dữ liệu trả về hiện nguyên văn

Error cases:

Case	Expected Handling
Id trống	"Chưa điền id.", không gọi
Nhầm loại id (vd id bút toán ở màn giao dịch)	Theo lưu ý: nhận 404 chứ không im lặng
Ops lỗi	Thông điệp lỗi / "Lỗi không rõ."

Acceptance Criteria của màn M2

AC-M2.1 - Mỗi chip một đối tượng

Given người dùng chọn chip "Gửi lại giao dịch"
Then màn chỉ có ô transaction_id, nhãn "Phase 1" và lưu ý "Đây là đối tượng KHÁC hai nút trên…"
Given người dùng chọn chip "Gửi lại lớp"
Then màn chỉ có ô class_id, nhãn "Phase 2" và lưu ý entries_queued cắt ở ngưỡng 200

Maps to:

• Business Rule: BR-06

AC-M2.2 - Id trống

Given ô id trống
When người dùng bấm "Gửi lại"
Then hiện "Chưa điền id." và không có lời gọi API

Maps to:

• Business Rule: BR-07

AC-M2.3 - Thành công in nguyên dữ liệu

Given entry_id hợp lệ trên Dev
When người dùng bấm "Gửi lại"
Then khung kết quả hiện nguyên dữ liệu Ops trả về (JSON)

Maps to:

• Business Rule: BR-07

AC-M2.4 - Không mở trên Prod

Given người dùng đang ở chip "Trace log SAP" trên Prod
When chọn chip "Gửi lại bút toán"
Then portal tự chuyển sang Dev kèm thông báo đổi portal (US-D01 BR-02)
And hint màn ghi "⛔ Ghi dữ liệu — cố ý không có trên prod."

Maps to:

• Business Rule: BR-08

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Bấm liên tiếp	Nút tắt khi đang gửi (NFR-D-08)
EC-M2.2	"Gửi lại lớp" trả số lớn ở entries_queued	Theo lưu ý: là số dòng nhặt, không phải số dòng được gửi
EC-M2.3	Id có khoảng trắng	Bỏ khoảng trắng đầu/cuối trước khi gửi

Màn M3 - Chip "Chạy lượt quét" và "Trace log SAP" (tham chiếu)

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip "Chạy lượt quét" (Dev/Staging) hoặc "Trace log SAP" (Dev/Staging/Prod)
Mô tả ngắn	"Chạy lượt quét": nút quét + danh sách lượt quét bên dưới. "Trace log SAP": tra log + danh sách lượt quét. Toàn bộ hành vi → US-P05 (inventory A-92, E-04, E-05).

UI States

N/A — mô tả ở US-P05.

Fields

N/A — mô tả ở US-P05.

Filter / Search / Sort

N/A — mô tả ở US-P05.

Actions

N/A — mô tả ở US-P05. Ghi dữ liệu: "Chạy lượt quét" bắn lượt quét trên SAP service Dev/Staging (không có route Prod); "Trace log SAP" chỉ đọc (chạy được cả Prod).

Acceptance Criteria của màn M3

AC-M3.1 - Trace mở được Prod, quét thì không

Given người dùng chọn chip "Trace log SAP"
Then portal Prod bấm được
When người dùng chọn chip "Chạy lượt quét" khi đang Prod
Then portal tự chuyển sang Dev (US-D01 BR-02)

Maps to:

• Business Rule: BR-08
• NFR: NFR-D-02

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

N/A — xem US-P05.

5. Cross-feature AC

AC-X.1 - Gửi lại đi qua Ops passthrough

Given màn "Gửi lại bút toán" trên Staging
When người dùng bấm "Gửi lại"
Then lời gọi đi qua Ops passthrough và auto-login Ops staging (US-P08)

Maps to:

• REL-06 (Affects - Ops passthrough + auto-login)

AC-X.2 - Đồng bộ lại kích hoạt hệ ngoài

Given deal đã từng qua SAP
When người dùng bấm "hóa đơn" ở màn Re-sync
Then hệ ngoài (webhook HubSpot → lms-be → SAP) xử lý lại và ghi SUCCESS / FAILED về property (Fact theo hint)

Maps to:

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

AC-X.3 - Chip quét / trace dùng màn nền tảng

Given người dùng chọn chip "Chạy lượt quét"
Then màn quét và danh sách lượt quét hoạt động theo US-P05

Maps to:

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