US-D15: Flow P2 — Trường chiều (story SAPP US-07)

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.

Mode B – As-built tại commit e77c47a · nguồn Fact: inventory 26878 §3.3 (A-125). Khung stepper → US-D01 · lịch sử / log SAP → US-D02 · loại bước → US-D03. U01:x = bước x của luồng US-01 ở US-D09 §4a.

Field	Value
US ID	US-D15
Role thực hiện	Người dùng tool — Assumption (OQ về G-01 · inventory Q-05 — xem 00-overview §6)
Phase	Phase 2 của SAPP-26878 (DTTH) · chip US-07 · Trường chiều (id us07)
Priority	N/A — as-built, đã triển khai (backlog R2: không xếp Priority)
Status	Draft
NFR liên quan	NFR-P-01 (quyền, FS nền tảng) · NFR của 26878 — xem 00-overview §5
OQ liên quan	OQ-D-07, OQ-D-06, OQ-D-13, OQ-D-15 — xem 00-overview §6 · DR-D-06 — xem 00-overview §6b

1. US Statement

As a Người dùng tool (Assumption — OQ về G-01)
I want dựng đúng bộ dữ liệu của US-01 (lớp ACCA · F1 · BLENDED · cơ sở NEU), đọc các trường chiều của
       bút toán, và có sẵn công thức dựng dữ liệu lệch cho các ca âm
So that kiểm được rằng bút toán mang đúng các trường chiều (dimensions) mà kế toán dùng để phân bổ

• Nguồn "So that": shared/runbooks/sapp/sapp-26878/phase-2/us-07/README.md:6 ("Kiểm rằng bút toán mang đúng các trường chiều (dimensions) mà kế toán dùng để phân bổ"); hint luồng sapp-26878-flows.ts:5590. Tiêu chí nghiệm thu của tool: [Assumption] (OQ-D-13).

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B). Dependency runtime như US-D09 §2. Các giá trị mong đợi của kiểm chứng gắn với lớp mà bước 3 dựng (chương trình ACCA, môn F1, hình thức BLENDED, cơ sở NEU) — đổi các giá trị đó ở bước 3 thì kiểm chứng tương ứng báo sai (sapp-26878-flows.ts:5384-5401).

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Luồng có 18 bước: 16 bước đầu dùng lại nguyên U01:1 → U01:16 theo đúng thứ tự của US-01, thêm 2 bước riêng; không có API riêng và không có bước trả lại mã lớp	M1	AC-M1.1	fe/src/ui/components/works/sapp/sapp-26878-flows.ts:5592-5617
BR-02	"Đọc trường chiều" lọc log SAP theo deal_id, tự chạy 9 kiểm chứng với giá trị mong đợi cố định cho lớp ACCA · F1 · BLENDED · NEU, luôn coi là xong; panel SQL 3 câu chỉ đọc	M2	AC-M2.1 → AC-M2.10	sapp-26878-flows.ts:5402-5506
BR-03	"Dựng dữ liệu lệch" là bước hướng dẫn liệt kê 10 công thức dựng ca âm (mỗi ca cần lớp / Deal khác và chạy lại lượt quét), xong khi người dùng bấm xác nhận; chỉ một ca cần SQL ghi (đặt loại ghi danh ra ngoài danh sách)	M1 - A18	AC-M1.2	sapp-26878-flows.ts:5523-5574
BR-04	Câu SQL ghi không tự chạy và phải qua hộp xác nhận	M1 - A18	AC-M1.2	fe/src/ui/components/works/sapp/sapp-26878-step-sql.tsx:200-213

4. Design

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

[Chip "US-07 · Trường chiều", portal Dev | Staging]
  ↓
[M1] U01:1 → U01:2 → … → U01:16
  ↓
[M2] Đọc trường chiều (9 kiểm chứng, luôn "xong")
  ↓
[M1] Dựng dữ liệu lệch (công thức chạy lại chip cho ca âm)

Bảng bước (Fact: sapp-26878-flows.ts:5592-5617).

#	Tên bước	Loại	Tái dùng	Ghi gì (hệ thống · môi trường)	Điều kiện chuyển (xong)
1–16	Kiểm tra kết nối Ops … Chạy lượt quét	như US-D09	U01:1 → U01:16 (đúng thứ tự)	Như US-D09 §4a bước 1–16 (Ops dev/staging, HubSpot — ⚠️ portal prod khi Staging, SAP service; Redis run history)	Như US-D09
17	Đọc trường chiều	trace + sql	riêng	Không ghi (SQL us07.dims chỉ đọc)	Luôn xong
18	Dựng dữ liệu lệch	guide + sql	riêng	Ops DB chỉ khi người dùng chạy câu us07.skew.1	Bấm "Đã đọc công thức dựng lệch"

⚠️ Ghi PROD — trên Staging, bước 8, 9, 11, 14, 15 ghi HubSpot portal production (như US-D09 §4a).

Tình trạng nghiệm thu gần nhất (nguồn ngoài code, chưa kiểm chứng ở R3): runbook ghi 🟡 8/9 trên dev 2026-09-18 — một ca cần lớp nhiều buổi (shared/runbooks/sapp/sapp-26878/phase-2/us-07/README.md:3-4); staging ✅ 2026-09-22 (.../phase-2/staging/README.md §6i).

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

Màn M1 - Chuỗi bước dựng dữ liệu (bước 1–16) và bước 18

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Chọn chip US-07 · Trường chiều (inventory E-07)
Mô tả ngắn	Dựng như US-01; bước 18 là danh sách công thức dựng dữ liệu lệch.

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Sitting mới	Bước 1 mở (→ US-D01)	N/A
Loading	Đang gọi hệ ngoài	Như US-D09	N/A
Has data	Bước xong	Như US-D09	N/A
Empty	Staging, pool mã lớp rỗng	Như US-D09 EC-M1.2	N/A
Error	Hệ ngoài trả lỗi	Như US-D09	N/A
Disabled	Bước khóa; bước 7 trên Staging	Như US-D09	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
B18 · id bản ghi ghi danh (class_user_id)	—	Text	—	id	Hint: id bản ghi ghi danh, không phải id người dùng; lấy trên màn lớp ở Ops	—	Always	—

Field bước 1–16 → US-D09.

Actions

A18 - Dựng dữ liệu lệch (bước 18)

Item	Description
Trigger	Mở bước, đọc checklist; tùy chọn chạy câu ① (xác nhận); bấm "Đã đọc công thức dựng lệch"
Behavior	Checklist 10 ca: Center = ALL khi lớp Hybrid/Live Online có cơ sở; cơ sở chưa map; lớp F2F không có cơ sở; Short courses → CMA_02; loại trừ B2B/Finhub; nhánh dự phòng theo pipeline; bộ ba không có trong danh mục; thiếu định danh khách; tổng giờ bằng 0; loại ghi danh ngoài danh sách (BR-03). Câu ① ghi Ops DB dev/staging; câu ② chỉ đọc danh sách cơ sở.
Success Result	Bước xong khi xác nhận; mỗi ca âm cần chạy lại chip với lớp / Deal khác

Error cases:

Case	Expected Handling
Ca Suối Nhum (UEL)	Guide: không dựng được trên dev (không có dữ liệu cơ sở)

Acceptance Criteria của màn M1

AC-M1.1 - Chuỗi 18 bước

Given một sitting mới của luồng US-07
When người dùng xem stepper
Then bước 1–16 trùng tên và thứ tự với bước 1–16 của US-01, bước 17 "Đọc trường chiều", bước 18 "Dựng dữ liệu lệch"
And không có bước "Trả lại mã lớp"

Maps to:

• Business Rule: BR-01

AC-M1.2 - Công thức dựng lệch

When mở bước 18
Then thấy danh sách 10 công thức ca âm và panel SQL (câu ① ghi, câu ② đọc)
When chạy câu ① và xác nhận
Then loại ghi danh của bản ghi đã nhập đổi sang giá trị ngoài danh sách
And bước xong khi bấm "Đã đọc công thức dựng lệch"

Maps to:

• Business Rule: BR-03, BR-04

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	⚠️ Observed — chạy luồng trên Staging	Luồng không có bước "Trả lại mã lớp" (chỉ US-01 có), trong khi runbook staging §0.1 ghi mọi lượt đều trả mã. Mỗi lượt giữ vĩnh viễn một mã của pool staging; cạn pool → bước Tạo lớp của mọi luồng phase 2 bị chặn. OQ-D-07 · DR-D-06 — xem 00-overview §6 / §6b
EC-M1.2	Đổi hình thức / cơ sở / môn ở bước 3	Kiểm chứng tương ứng ở bước 17 báo fail — theo code đó là ca âm có chủ đích
EC-M1.3	⚠️ Observed — "Dùng deal có sẵn" ở bước 8	Như US-D09 EC-M1.3 — OQ-D-06

Màn M2 - Bước 17 "Đọc trường chiều"

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Mở bước 17
Mô tả ngắn	Trace log SAP theo deal_id (→ US-P05) + 9 kiểm chứng trên khối dimensions và 3 trường cấp trên.

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Mở bước	Hint + mã lớp + trace tự chạy + panel SQL us07.dims	N/A
Loading	Đang tra	Trace đang tải	N/A
Has data	Có trail	Kết quả 9 kiểm chứng	N/A
Empty	Chưa có bút toán	Trace rỗng	N/A
Error	Trace lỗi	→ US-P05	N/A
Disabled	N/A	N/A	N/A

Fields

N/A — bước chỉ đọc.

Actions

A17 - Đọc trường chiều

Item	Description
Trigger	Mở bước (tự chạy); chạy tay SQL
Behavior	9 kiểm chứng (BR-02). SQL ① mẫu số tuyệt đối từng dòng, ② mã cơ sở trong LMS, ③ lỗi dữ liệu nguồn gần đây — đều chỉ đọc.
Success Result	Bước luôn xong

Error cases:

Case	Expected Handling
Không đọc được trường	Kiểm chứng = unknown

Acceptance Criteria của màn M2

AC = kiểm chứng tự chấm (sapp-26878-flows.ts:5402-5472).

AC-M2.1 - department cố định CX

Then pass khi dimensions.department = CX

Maps to:

• Business Rule: BR-02

AC-M2.2 - exp_rev_code cố định REV.0005

Then pass khi dimensions.exp_rev_code = REV.0005

Maps to:

• Business Rule: BR-02

AC-M2.3 - sub_bu suy từ Program của khóa

Then pass khi dimensions.sub_bu = ACCA_01

Maps to:

• Business Rule: BR-02

AC-M2.4 - center tra từ cơ sở (BLENDED)

Then pass khi dimensions.center = NEU

Maps to:

• Business Rule: BR-02

AC-M2.5 - item_code tra từ chương trình · môn · hình thức

Then pass khi item_code = SALE.01.000004

Maps to:

• Business Rule: BR-02

AC-M2.6 - Mẫu số tính trên toàn bộ lớp

Then pass khi standard_hours_remaining giảm đúng bằng lesson_hours của buổi liền trước, từng bước một

Maps to:

• Business Rule: BR-02

AC-M2.7 - Có customer_id

Then pass khi phần tử cuối của payload CÓ customer_id

Maps to:

• Business Rule: BR-02

AC-M2.8 - Có branch_id

Then pass khi phần tử cuối của payload CÓ branch_id

Maps to:

• Business Rule: BR-02

AC-M2.9 - Có dimensions.project_code

Then pass khi phần tử cuối của payload CÓ dimensions.project_code

Maps to:

• Business Rule: BR-02

AC-M2.10 - Bước đọc không chặn

Given một kiểm chứng fail hoặc unknown
Then bước 17 vẫn "xong" và bước 18 mở

Maps to:

• Business Rule: BR-02

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	⚠️ Observed (OQ-D-20) — hint luồng và hint bước ghi "Tám kiểm chứng"	Code khai 9 kiểm chứng (sapp-26878-flows.ts:5402-5472 vs :5479,5590). Chỉ là lệch mô tả trong màn; đề xuất ghi Drift nội bộ — điều phối viên quyết
EC-M2.2	Lớp chỉ có một buổi	Kiểm chứng "Mẫu số tính trên toàn bộ lớp" cần nhiều buổi để so; runbook ghi đây là ca 🟡 chưa đo được
EC-M2.3	Kiểm chứng fail nhưng đi tiếp	Không có gate — OQ-D-15

5. Cross-feature AC

AC-X.1 - Dùng lại bước US-01

Given bước U01:1–16 thay đổi ở US-01
When mở luồng US-07
Then luồng dùng đúng định nghĩa mới

Maps to:

• Liên quan nội bộ FS 26878 (không có mã REL) (US-D09)