US-D01: Chạy một flow test theo stepper (chọn portal, chọn flow, bỏ qua, reset, lưu / khôi phục phiên)

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-01 … A-07.

Field	Value
US ID	US-D01
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) — khung dùng chung cho cả phase 1 và phase 2 của ticket
Priority	N/A (as-built)
Status	Draft
NFR liên quan	NFR-D-01, NFR-D-02, NFR-D-05, NFR-D-09 — xem Overview §5
OQ liên quan	OQ-D-05, OQ-D-06 — xem Overview §6

1. US Statement

As a Người dùng tool (Assumption — OQ về G-01)
I want chọn portal và một flow test, rồi đi lần lượt qua các bước của flow trong một stepper
       (bỏ qua bước đã làm ngoài tool, làm lại từ đầu khi cần, và không mất tiến độ khi tải lại trang)
So that dựng đúng thứ tự dữ liệu test mà "chip `sapp-26878` dựng sẵn mọi bước cho người test bấm tay"
        (trích shared/runbooks/sapp/sapp-26878/phase-2/README.md:6); lợi ích cụ thể cho người dùng: [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	Tool sapp.010 đang bật / đã mở khoá ở hub (→ US-P02)	Admin CMS	N/A — runtime
D2	Trình duyệt cho phép sessionStorage (lưu phiên)	Người dùng	N/A — runtime

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Portal có 3 lựa chọn Dev / Staging / Prod. Mọi chip dựng data hoặc ghi dữ liệu chỉ bật Dev và Staging; Prod chỉ bật cho chip "Trace log SAP". Tab không bật vẫn hiện nhưng không bấm được.	M1 - field Portal	AC-M1.1, AC-M1.2	sapp-26878-tool.tsx:91-119,1977-2006
BR-02	Đổi sang chip không cho phép portal đang chọn → tool tự chuyển sang portal đầu tiên được phép và hiện thông báo "<chip> chỉ chạy trên <danh sách> — đã chuyển portal từ <cũ> sang <mới>." (có nút "Đã hiểu").	M1 - action Chọn chip	AC-M1.3	sapp-26878-tool.tsx:1923-1935,2150-2165
BR-03	Chip được chia 3 nhóm: Phase 1 · hóa đơn & tiền vé (5 flow + 5 chip Re-sync), Trace (Trace log SAP, Chạy lượt quét, Gửi lại bút toán, Gửi lại lớp, Gửi lại giao dịch), Phase 2 · doanh thu thực hiện (9 flow). Chip flow mở stepper; chip khác mở màn riêng (US-D18, US-P05).	M1 - field Chip	AC-M1.4	sapp-26878-tool.tsx:182-218,2038-2150,2173-2220
BR-04	Flow, portal và bước đang xem được ghi vào địa chỉ trang (?flow=&env=&step=) — mở lại đúng đường dẫn thì về đúng vị trí. Đổi chip/portal không tạo mục lịch sử trình duyệt mới (Back rời khỏi tool).	M1, M2	AC-M1.5	sapp-26878-tool.tsx:263-297,930-935,1937-1942
BR-05	Mỗi cặp (flow, portal) là một phiên riêng. Toàn bộ trạng thái phiên (bước đang xem, deal đã tạo, bước đã xác nhận / chuyển stage / đồng bộ / gắn / ops / bỏ qua, giá trị form, các id thu được, danh tính test, mã phiên) được lưu trong trình duyệt theo tab và khôi phục khi quay lại cặp đó; đóng tab là mất.	M2	AC-M2.6	sapp-26878-tool.tsx:314-391,439-526,754-788
BR-06	Một bước chỉ mở được khi mọi bước trước nó đã xong; quay lại bước đã qua luôn được.	M2 - rail bước	AC-M2.1, AC-M2.2	sapp-26878-tool.tsx:888-906
BR-07	Bấm bước chưa mở → tool hiện lý do bằng câu đầy đủ: bước chưa triển khai ("… chưa được triển khai trong tool — làm bước này bằng tay trên SAPP OPS.") hoặc bị khoá ("… mở sau khi xong bước <n>. Hoàn thành bước đó, hoặc bấm "Bỏ qua bước này" nếu bạn đã làm nó bên ngoài tool.").	M2 - rail bước	AC-M2.2	sapp-26878-tool.tsx:1113-1135
BR-08	Xong một bước → sau 1,2 giây tool tự chuyển sang bước kế, hiện "Xong — đang chuyển sang bước <n> · <tên>" kèm nút "Ở lại bước này" để huỷ việc chuyển. Chủ động bấm bước khác cũng huỷ lượt chuyển đang chờ.	M2	AC-M2.3	sapp-26878-tool.tsx:359,907-930,1202-1221
BR-09	Mọi bước đều có "Bỏ qua bước này": bước được coi là xong; người dùng có thể nhập tay các giá trị mà bước lẽ ra sinh ra để bước sau dùng (để trống thì bước sau tự hỏi lại).	M3	AC-M3.1, AC-M3.2	sapp-26878-step-skip.tsx:28-60,79-100; sapp-26878-tool.tsx:798-824,1225-1240
BR-10	Bỏ qua bước tạo deal mà có nhập deal_id → deal đó được ghi vào chuỗi ở chế độ "deal có sẵn".	M3	AC-M3.3	sapp-26878-tool.tsx:798-824
BR-11	"Bắt đầu lại" cần bấm 2 lần (lần 1 đổi nhãn thành "Chắc chắn xoá? Bấm lại"; rời nút là huỷ). Xác nhận → xoá phiên của đúng (flow, portal) hiện tại, về bước 1; flow và portal khác không bị ảnh hưởng.	M2 - action Bắt đầu lại	AC-M2.4, AC-M2.5	sapp-26878-tool.tsx:494-502,1062-1090,1905-1916

⚠️ Observed (không viết thành BR): deal ở chế độ "deal có sẵn" làm mọi bước không phải bước deal thuộc deal đó tự đánh dấu xong (xem EC-M2.3, OQ-D-06).

4. Design

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

[Hub → mở tool sapp.010]
  ↓
[M1: Khung tool — portal + chip]
  ├─ chọn chip flow (phase 1 / phase 2) ──→ [M2: Stepper của flow]
  │        ├─ mở bước (≤ bước chưa xong đầu tiên) ──→ thân bước theo loại (US-D03)
  │        ├─ bước xong ──→ 1,2 s ──→ bước kế (hoặc "Ở lại bước này")
  │        ├─ "Bỏ qua bước này" ──→ [M3: Hộp bỏ qua] ──→ bước xong, bước sau mở
  │        ├─ "Bắt đầu lại" ×2 ──→ phiên mới, bước 1
  │        └─ "Log SAP" / "Lịch sử" ──→ US-D02
  ├─ chọn chip Re-sync / Gửi lại ──→ US-D18
  └─ chọn chip Trace log SAP / Chạy lượt quét ──→ US-P05

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

Màn M1 - Khung tool (tiêu đề, portal, chip)

Field	Value
Figma frame	N/A
Trigger vào màn	Mở /works/sapp/tools/sapp-26878 (có thể kèm ?flow=&env=&step=)
Mô tả ngắn	Hàng tiêu đề "SAPP-26878 Doanh thu thực hiện (Ops → HubSpot → SAP)" + bộ chọn portal; bên dưới là 3 nhóm chip. Có nút thu gọn phần đầu (khi thu gọn, tiêu đề hiện tên chip đang mở).

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	Tiêu đề, 3 tab portal (Dev/Staging/Prod), 3 nhóm chip; chip đang mở tô đậm; vùng dưới hiện stepper hoặc màn của chip	N/A
Loading	—	N/A — khung không tải dữ liệu; từng bước tự có trạng thái tải (US-D03)	N/A
Has data	Đã chọn chip	Vùng dưới hiện stepper (chip flow) hoặc màn chip	N/A
Empty	—	N/A — luôn có chip mặc định	N/A
Error	—	N/A ở khung; lỗi hiện ở bước / màn chip	N/A
Disabled	Portal không cho phép với chip đang mở	Tab mờ, không bấm được, tooltip "<Portal> — chỉ mở cho màn Trace log SAP"	N/A
Thông báo đổi portal	Vừa đổi chip làm portal bị đổi	Dòng thông báo lịch sự + nút "Đã hiểu"	N/A
Thu gọn	Bấm nút thu gọn	Ẩn nhóm chip; tiêu đề hiện tên chip đang mở	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Portal	Yes	Tab (Dev / Staging / Prod)	Theo ?env=; không có thì theo mặc định của tool	—	Chỉ các portal được phép với chip (BR-01)	— (tab bị tắt)	Always	Chip đang mở
Chip	Yes	Nhóm nút (19 chip)	Theo ?flow=	—	—	—	Ẩn khi thu gọn	—

Filter / Search / Sort

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

Actions

A1 - Chọn portal

Item	Description
Trigger	Bấm một tab portal đang bật
Behavior	Đổi portal; stepper remount theo phiên (flow, portal) mới (BR-05); ghi ?env= (BR-04). Không ghi dữ liệu ra hệ ngoài.
Success Result	Stepper hiện phiên của cặp (flow, portal) vừa chọn

Error cases:

Case	Expected Handling
Bấm tab bị tắt	Không làm gì (tab disabled)

A2 - Chọn chip

Item	Description
Trigger	Bấm một chip
Behavior	Mở stepper (chip flow) hoặc màn riêng (chip khác). Portal hiện tại không được phép → tự đổi portal + thông báo (BR-02). Ghi ?flow= (BR-04).
Success Result	Vùng dưới hiện nội dung của chip

Error cases:

Case	Expected Handling
Đang ở Prod (chip Trace) chuyển sang chip flow	Portal tự chuyển sang Dev, hiện thông báo đổi portal

Acceptance Criteria của màn M1

AC-M1.1 - Prod bị tắt với chip dựng data

Given người dùng đang ở chip flow "US-03 · Học phí thường"
When người dùng nhìn bộ chọn portal
Then tab Dev và Staging bấm được, tab Prod mờ và không bấm được
And tooltip của tab Prod là "Prod — chỉ mở cho màn Trace log SAP"

Maps to:

• Business Rule: BR-01
• Field/Action: Portal

AC-M1.2 - Prod bật với chip Trace

Given người dùng chọn chip "Trace log SAP"
When người dùng nhìn bộ chọn portal
Then cả ba tab Dev, Staging, Prod đều bấm được

Maps to:

• Business Rule: BR-01

AC-M1.3 - Tự đổi portal khi rời Trace

Given người dùng đang ở chip "Trace log SAP" trên portal Prod
When người dùng chọn chip "US-11 · Chuyển đổi"
Then portal tự chuyển sang Dev
And tool hiện "US-11 · Chuyển đổi chỉ chạy trên Dev / Staging — đã chuyển portal từ Prod sang Dev." kèm nút "Đã hiểu"

Maps to:

• Business Rule: BR-02
• Field/Action: A2 - Chọn chip

AC-M1.4 - Ba nhóm chip

Given người dùng mở tool
When phần đầu không bị thu gọn
Then tool hiện nhóm "Phase 1 · hóa đơn & tiền vé" (5 chip flow + 5 chip "Re-sync US-0x"),
     nhóm Trace (5 chip) và nhóm "Phase 2 · doanh thu thực hiện" (9 chip flow)

Maps to:

• Business Rule: BR-03

AC-M1.5 - Mở lại đúng vị trí từ đường dẫn

Given người dùng đang ở bước 4 của chip "us05" trên Staging
When người dùng sao chép đường dẫn trang rồi mở ở cùng tab sau khi tải lại
Then tool mở chip "US-05 · Gia hạn / Bảo lưu", portal Staging, bước 4

Maps to:

• Business Rule: BR-04, BR-05

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

ID	Tình huống	Hành vi mong đợi
EC-M1.1	?env=prod với chip flow	Tab Prod không được phép với chip; tool chỉ cho chọn Dev/Staging (BR-01). Hành vi chính xác khi tải trang với tham số không hợp lệ chưa đối chiếu — TODO: xác nhận bằng chạy thử
EC-M1.2	Mở 2 tab cùng flow + portal	Mỗi tab có phiên riêng (lưu theo tab); run history ghi riêng theo mã phiên của từng tab (US-D02)
EC-M1.3	⚠️ Observed: BE vẫn nhận route prod cho thao tác ghi	Chặn prod chỉ nằm ở giao diện — xem NFR-D-02, OQ-D-02

Màn M2 - Stepper của một flow

Field	Value
Figma frame	N/A
Trigger vào màn	Chọn chip flow (phase 1 hoặc phase 2)
Mô tả ngắn	Cột trái: nút "Bắt đầu lại" + rail bước (mỗi deal của chuỗi một hàng). Cột phải: thanh ngữ cảnh lượt chạy (portal, các id đã thu), nút "Bỏ qua bước này", thân bước theo loại (US-D03), nút "Log SAP" / "Lịch sử" (US-D02).

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Phiên mới	Bước 1 mở; các bước sau khoá	N/A
Khôi phục	Quay lại cặp (flow, portal) đã có phiên trong tab	Về bước đang xem, giữ deal/id/form đã nhập	N/A
Bước xong	Bước vừa hoàn tất	Dấu xong trên rail + dòng "Xong — đang chuyển sang bước <n>" + "Ở lại bước này"	N/A
Bước bỏ qua	Bấm bỏ qua / deal có sẵn	Bước đánh dấu bỏ qua; dòng "Bước này đã được bỏ qua — bước sau đã mở."	N/A
Bước khoá	Bước sau bước chưa xong	Nút bước mờ nhưng vẫn bấm được; bấm → hiện lý do (BR-07)	N/A
Xác nhận reset	Bấm "Bắt đầu lại" lần 1	Nút đỏ "Chắc chắn xoá? Bấm lại"	N/A
Error	Lỗi ở một bước	Hiện ở thân bước (US-D03)	N/A

Fields

N/A — rail bước không có ô nhập; field của từng bước xem US-D03.

Filter / Search / Sort

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

Actions

A1 - Mở một bước

Item	Description
Trigger	Bấm một bước trên rail
Behavior	Bước ≤ bước chưa xong đầu tiên → mở (BR-06); ngược lại hiện lý do (BR-07). Ghi ?step=. Không ghi dữ liệu ra hệ ngoài.
Success Result	Thân bước hiện ở cột phải

Error cases:

Case	Expected Handling
Bước chưa triển khai	Câu "… chưa được triển khai trong tool — làm bước này bằng tay trên SAPP OPS."

A2 - Tự chuyển bước / Ở lại bước này

Item	Description
Trigger	Hệ thống: bước vừa xong
Behavior	Chờ 1,2 giây rồi mở bước kế (BR-08). "Ở lại bước này" huỷ lượt chuyển.
Success Result	Bước kế mở, hoặc giữ nguyên bước hiện tại

Error cases:

Case	Expected Handling
Bước cuối flow	Không có lượt chuyển; thân bước hiện "… — hết luồng."

A3 - Bắt đầu lại

Item	Description
Trigger	Bấm "Bắt đầu lại" hai lần liên tiếp
Behavior	Xoá phiên của (flow, portal) hiện tại trong trình duyệt, đặt ?step=1, dựng lại stepper với mã phiên mới (BR-11). Không xoá dữ liệu đã tạo trên HubSpot / Ops / SAP và không xoá run đã ghi.
Success Result	Stepper về bước 1, form trống

Error cases:

Case	Expected Handling
Bấm 1 lần rồi bấm chỗ khác	Huỷ xác nhận, nút trở lại "Bắt đầu lại"

Acceptance Criteria của màn M2

AC-M2.1 - Gate bước

Given flow "US-03 · Học phí thường" ở bước 1 chưa tạo deal
When người dùng nhìn rail bước
Then chỉ bước 1 mở được; bước 2…7 ở trạng thái khoá
When người dùng tạo deal thành công ở bước 1
Then bước 2 mở được

Maps to:

• Business Rule: BR-06

AC-M2.2 - Bấm bước khoá hiện lý do

Given bước 3 chưa xong
When người dùng bấm bước 5
Then bước 5 không mở
And tool hiện ""Kéo sang Won" mở sau khi xong bước 3. Hoàn thành bước đó, hoặc bấm "Bỏ qua bước này" nếu bạn đã làm nó bên ngoài tool."

Maps to:

• Business Rule: BR-06, BR-07

AC-M2.3 - Tự chuyển sau 1,2 giây

Given người dùng vừa hoàn tất bước 3 của flow có bước 4
When 1,2 giây trôi qua mà người dùng không bấm "Ở lại bước này"
Then tool mở bước 4
But nếu người dùng bấm "Ở lại bước này" trước đó thì tool giữ nguyên bước 3

Maps to:

• Business Rule: BR-08

AC-M2.4 - Reset hai lần

Given phiên của "US-11 · Chuyển đổi" trên Dev đang ở bước 9
When người dùng bấm "Bắt đầu lại" một lần
Then nút đổi thành "Chắc chắn xoá? Bấm lại" và chưa xoá gì
When người dùng bấm lại lần nữa
Then stepper về bước 1, mọi giá trị đã nhập của phiên bị xoá

Maps to:

• Business Rule: BR-11
• Field/Action: A3 - Bắt đầu lại

AC-M2.5 - Reset không chạm phiên khác

Given có phiên "US-11 · Chuyển đổi" trên Dev và trên Staging
When người dùng reset phiên trên Dev
Then phiên trên Staging vẫn giữ nguyên khi chuyển sang Staging

Maps to:

• Business Rule: BR-05, BR-11

AC-M2.6 - Khôi phục phiên trong tab

Given người dùng đã tạo deal ở bước 1 và đang ở bước 3 của "US-05" trên Dev
When người dùng chuyển sang chip khác rồi quay lại "US-05" trên Dev (cùng tab)
Then stepper về bước 3 và vẫn hiện deal id đã tạo
When người dùng đóng tab rồi mở lại tool ở tab mới
Then phiên bắt đầu lại từ đầu

Maps to:

• Business Rule: BR-05

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

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Tải lại trang giữa flow	Phiên khôi phục từ bộ nhớ trình duyệt của tab (BR-05)
EC-M2.2	Reset sau khi đã tạo deal thật	Deal/contact trên HubSpot và run trên Redis vẫn còn; chỉ phiên trong trình duyệt bị xoá
EC-M2.3	⚠️ Observed: deal được ghi ở chế độ "deal có sẵn" (qua bước deal hoặc qua bỏ qua có deal_id)	Hành vi hiện tại: mọi bước không phải bước deal thuộc deal đó hiện là "đã bỏ qua" và tính là xong — ở flow một-deal (mọi flow phase 2) gồm cả các bước Ops tạo lớp, đơn, giao dịch, quét (sapp-26878-tool.tsx:847-857). Cố ý hay bug → OQ-D-06
EC-M2.4	Chuỗi nhiều deal	Rail tách thành nhiều hàng, mỗi hàng một deal (nhãn deal ở đầu hàng)

Màn M3 - Hộp "Bỏ qua bước này"

Field	Value
Figma frame	N/A
Trigger vào màn	Bấm "Bỏ qua bước này" (có trên mọi bước; đã bỏ qua thì nhãn là "Đã bỏ qua — sửa lại")
Mô tả ngắn	Hộp hỏi các giá trị bước lẽ ra sinh ra cho bước sau, cho phép bỏ qua có hoặc không kèm giá trị

UI States

State	Khi nào	Hiển thị	Figma frame
Default – có output	Bước sinh giá trị cho bước sau	"Bước sau cần các giá trị dưới đây. Điền những gì bạn đã có; để trống thì bước sau sẽ tự hỏi lại." + một ô cho mỗi giá trị	N/A
Default – không output	Bước không sinh giá trị	"Bước này không tạo ra giá trị nào cho bước sau."	N/A
Loading / Empty / Error	—	N/A — hộp không gọi API	N/A
Disabled	—	N/A	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
deal_id	No	Text	—	—	Bỏ khoảng trắng đầu/cuối; trống thì bỏ	—	Bước deal	—
contact_name, contact_email, contact_phone	No	Text	—	—	Như trên	—	Bước deal	—
Giá trị Ops sinh ra (vd class_id, order_id, order_amount, class_seq…)	No	Text	—	—	Như trên	—	Bước ops sinh giá trị đó	Spec bước (sapp-26878-step-skip.tsx:28-60)

Filter / Search / Sort

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

Actions

A1 - Bỏ qua (kèm hoặc không kèm giá trị)

Item	Description
Trigger	Bấm nút xác nhận trong hộp
Behavior	Đánh dấu bước xong (BR-09); giá trị không trống được đưa vào kho id của phiên cho bước sau dùng; bước deal có deal_id → ghi deal ở chế độ "deal có sẵn" (BR-10). Không ghi dữ liệu ra hệ ngoài.
Success Result	Hộp đóng; dòng "Bước này đã được bỏ qua — bước sau đã mở."

Error cases:

Case	Expected Handling
Bỏ qua không nhập giá trị cần thiết	Bước sau thiếu id và tự hỏi lại / báo thiếu tại bước đó

Acceptance Criteria của màn M3

AC-M3.1 - Bỏ qua mở bước sau

Given bước 2 "Đơn hàng Ops" của US-03 đang mở
When người dùng bấm "Bỏ qua bước này" rồi xác nhận
Then bước 2 được đánh dấu bỏ qua và bước 3 mở được

Maps to:

• Business Rule: BR-09

AC-M3.2 - Giá trị nhập tay được bước sau dùng

Given một bước ops sinh "class_id"
When người dùng bỏ qua bước đó và nhập class_id = "abc"
Then các bước sau dùng class_id = "abc" làm giá trị điền sẵn

Maps to:

• Business Rule: BR-09

AC-M3.3 - Bỏ qua bước deal có deal_id

Given bước "Tạo deal" đang mở
When người dùng bỏ qua và nhập deal_id = "123"
Then chuỗi deal ghi deal "123" ở chế độ "deal có sẵn"

Maps to:

• Business Rule: BR-10

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

ID	Tình huống	Hành vi mong đợi
EC-M3.1	Nhập chỉ khoảng trắng	Giá trị bị bỏ, coi như không nhập
EC-M3.2	Bỏ qua bước đã bỏ qua trước đó	Nút "Đã bỏ qua — sửa lại" mở lại hộp để sửa giá trị
EC-M3.3	⚠️ Observed: deal_id nhập tay không được kiểm tra tồn tại / do tool tạo	Xem OQ-D-06; các bước sau gọi BE với deal không do tool tạo sẽ bị từ chối 13033 (NFR-D-04)

5. Cross-feature AC

AC-X.1 - Tool chỉ vào được khi hub cho phép

Given sub-tool sapp.010 đang bị khoá ở hub
When người dùng mở /works/sapp/tools/sapp-26878
Then hành vi khoá / mở khoá theo US-P02 (tool không tự kiểm tra thêm)

Maps to:

• REL-01 (Affects - Hub /works/sapp + khoá tool)

AC-X.2 - Chip Trace và Chạy lượt quét mở màn nền tảng

Given người dùng ở tool 26878
When người dùng chọn chip "Trace log SAP" hoặc "Chạy lượt quét"
Then màn tra log / quét hoạt động theo US-P05

Maps to:

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