US-S02: Chuẩn bị điều kiện và dọn dữ liệu sau test

Thuộc FS: 00-overview.md — SAPP-26297 Chuyển nhượng học viên (tool sapp.011) 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.

Cơ chế chạy bước (fixture, bước SQL, xác nhận câu GHI, ghi ngược fixture) → US-S01. Cơ chế SQL runner → US-P09.

Field	Value
US ID	US-S02
Role thực hiện	R1 - Người dùng tool — Assumption (OQ về G-01 → OQ-S-01)
Phase	As-built (đã triển khai @ e77c47a)
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-S-02, NFR-S-05 — xem Overview §5
OQ liên quan	OQ-S-01, OQ-S-09, OQ-S-14 — xem Overview §6

1. US Statement

As a Người dùng tool  [Assumption — OQ-S-01]
I want kiểm tra tiền điều kiện dữ liệu trên DB Ops trước khi chạy các luồng, và dọn dữ liệu test sau khi chạy xong
So that [Assumption — OQ-S-18] các luồng 1–3 chạy trên dữ liệu đúng giả định của guide QA
        (tool ghi: "Chạy trước mọi luồng: migration, dữ liệu 2 lớp cùng môn + 2 học viên 0%. Chạy phần dọn sau khi test xong.")

2. Dependencies & Definition Of Ready

N/A — đã triển khai. Dependency runtime:

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Fixture có class_id_l1, class_id_l2, user_a, user_b (0.1); thêm user_c, foundation_class_id (0.2)	Tester	—
D2	SQL runner kết nối được DB Ops dev/staging (US-P09)	BE / Admin CMS	—

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Case 0.1 gồm 5 câu chỉ đọc: (1) migration đã thêm 3 cột subject_id, cancelled_by, cancelled_at vào bảng lịch sử chuyển nhượng; (2) L1 và L2 là lớp LESSON cùng môn; (3) A, B đang NORMAL với tiến độ 0 hoặc trống; (4) B chưa nhận chuyển nhượng môn này (0 dòng, hoặc mọi dòng REVERTED); (5) lớp Foundation đi kèm L1	M1 - case 0.1	AC-M1.1	fe/src/ui/components/works/sapp/sapp-26297-flows.ts:544-573 · be/libs/constants/src/lib/sapp/sapp-26297-sql.constants.ts:22-61
BR-02	Tool không tự ghi subject_id / foundation_class_id từ kết quả 0.1 — ghi chú yêu cầu tester chép tay vào fixture	M1 - case 0.1	AC-M1.2	sapp-26297-flows.ts:559-571
BR-03	Case 0.2 gồm 3 câu GHI + 1 hướng dẫn: trả type NORMAL cho A, B, C tại L1, L2, F1; đưa tiến độ đã học về 0 cho A tại L1 và B tại L2; xoá bản ghi lịch sử A→B và C→B; hướng dẫn khôi phục học viên bị xoá mềm ở nhóm 3B bằng câu #3 của panel nhóm B	M1 - case 0.2	AC-M1.3	sapp-26297-flows.ts:574-590 · sapp-26297-sql.constants.ts:230-249
BR-04	Mọi câu chỉ chạy trên DB Ops dev/staging theo môi trường đang chọn (NFR-S-02)	M1	AC-M1.1, AC-M1.3	be/libs/constants/src/lib/sapp/sapp-ops-sql.constants.ts:29-32
BR-05	Catalogue s26297.* có 39 entry (20 đọc, 19 GHI); id = prefix của panel + số thứ tự bắt đầu từ 1; một prefix = một panel trên màn; bản FE phải khớp bản BE (NFR-S-05)	Toàn tool	AC-M1.4	sapp-26297-sql.constants.ts:1-20 · sapp-26297-flows.ts:321-349 · fe/src/ui/components/works/sapp/sapp-26297-sql.ts:9-270

4. Design

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

[Tab "Chuẩn bị · Dọn"]
  ├─ case 0.1 Kiểm tiền điều kiện  → 5 câu đọc → tester chép subject_id, foundation_class_id vào fixture
  │     ↓
  │   [chạy luồng 1 → 6]
  │     ↓
  └─ case 0.2 Dọn dữ liệu sau test → 3 câu GHI → (khôi phục nhóm 3B ở panel 3B)

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

Màn M1 - Tab "Chuẩn bị · Dọn"

Field	Value
Figma frame	N/A
Trigger vào màn	Tab mặc định khi mở màn tool; hoặc bấm tab "Chuẩn bị · Dọn"
Mô tả ngắn	Tóm tắt: "Chạy trước mọi luồng … Chỉ trên DB dev/staging." 2 case: 0.1, 0.2. Mọi ô fixture đều hiện ở tab này (US-S01 BR-05)

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vào tab	Tóm tắt + 2 case đóng	N/A
Loading	Đang chạy câu SQL	Theo US-S01 M3 / US-P09	N/A
Has data	Chạy xong câu	Kết quả dưới từng câu	N/A
Empty	Câu đọc trả 0 dòng	Theo US-P09 (với câu (4) của 0.1: 0 dòng là đạt)	N/A
Error	Runner lỗi	Theo US-P09	N/A
Disabled	N/A	—	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Fixture class_id_l1, class_id_l2, user_a, user_b, subject_id	Yes cho 0.1	Text	—	id Ops	US-S01 BR-06	—	Always ở tab này	—
Fixture user_c, foundation_class_id	Yes cho 0.2	Text	—	id Ops	US-S01 BR-06	—	Always ở tab này	foundation_class_id chép từ câu (5) của 0.1

Actions

A1 - Chạy panel SQL chuẩn bị (s26297.pre)

Item	Description
Trigger	Mở case 0.1, chạy từng câu
Behavior	5 câu đọc (BR-01). Không ghi
Success Result	Tester đối chiếu kết quả với ghi chú từng câu, chép subject_id / foundation_class_id vào fixture (BR-02)

Error cases:

Case	Expected Handling
Câu (1) trả < 3 dòng	Ghi chú: "Thiếu thì luồng 1–3 fail toàn bộ" — tool không chặn luồng khác

A2 - Chạy panel SQL dọn (s26297.clean)

Item	Description
Trigger	Mở case 0.2, chạy từng câu (mỗi câu hỏi xác nhận GHI)
Behavior	3 câu GHI (BR-03). Ghi vào: DB Ops dev/staging — bảng trạng thái học viên trong lớp (type, tiến độ) và bảng lịch sử chuyển nhượng (xoá dòng)
Success Result	Dữ liệu A, B, C trở về trạng thái sẵn sàng test lại

Error cases:

Case	Expected Handling
Tester huỷ xác nhận	Không chạy câu đó

Catalogue s26297.* theo panel (39 entry):

Prefix	Dùng ở case	Đọc	GHI	Việc làm
pre.1-5	0.1	5	0	Kiểm migration, lớp, trạng thái A/B, lịch sử của B, lớp Foundation đi kèm
f1v.1-3	1.A, 2.B	3	0	Verify sau chuyển nhượng: trạng thái hai phía, bản ghi lịch sử mới nhất, đúng 1 bản ghi A→B
f2v.1-2	2.A, 2.6, 2.7, 4.D	2	0	Verify sau hủy: trạng thái + tiến độ hai phía, bản ghi REVERTED không bị xoá
c12.1	1.2	0	1	A tại L1: tiến độ 3/10
c24.1-2	2.4	0	2	Xoá mềm L2 / khôi phục L2
c25.1-2	2.5	0	2	Xoá mềm B khỏi L2 / khôi phục
c26.1	2.6	0	1	B tại L2: tiến độ 1/10
c31.1	3.1	1	0	Tìm lớp Lesson khác môn
c32.1	3.2	1	0	Tìm lớp Revision
c33.1	1.3, 3.3	0	1	B tại L2: tiến độ 3/10
c34.1	1.4, 3.4	0	1	B tại L2 → RESERVED
c35.1	3.5	1	0	Bản ghi TRANSFERRED của B trong môn
c36.1-2	1.5, 2.7, 3.6	1	1	Lớp Foundation đi kèm L1 / A tại F1 → RESERVED
int.1	1.2–1.5, 3.1–3.6 (bước "3.7")	1	0	Trạng thái A/B + số bản ghi A→B không đổi sau từ chối
grpb.1-3	3B	1	2	Trạng thái user_x/user_y / dựng target_type cho user_x / khôi phục xoá mềm
clean.1-3	0.2	0	3	Trả NORMAL / tiến độ về 0 / xoá lịch sử A→B, C→B
lms.1-3	4.1–4.8	1	2	Lớp của học viên test / dựng target_type / trả NORMAL
hs5.1-3	5 (A.1, B, 5.1–5.8)	3	0	Dòng đồng bộ enrollment của ticket (ghi ngược hs_user_id) / trạng thái học viên mọi lớp / lớp đã khai giảng chưa
hs5s.1-3	5.3 (dùng cho 5.4, 5.6)	0	3	Tiến độ 2/10 tại lớp mới 2 / lớp cũ → MOVED_OUT / lớp mới 1 → TRANSFERED_TO
Tổng		20	19

Nguồn: sapp-26297-sql.constants.ts:20-316; bảng Ops chạm tới: trạng thái học viên trong lớp (type, tiến độ, deleted_at), classes.deleted_at, lịch sử chuyển nhượng, liên kết Foundation, dòng đồng bộ enrollment HubSpot (inventory §4.4).

Acceptance Criteria của màn M1

AC-M1.1 - Kiểm tiền điều kiện

Given môi trường "dev" và fixture có class_id_l1, class_id_l2, user_a, user_b, subject_id
When người dùng chạy 5 câu của case 0.1
Then câu (1) trả đúng 3 dòng subject_id, cancelled_by, cancelled_at
And câu (2) trả 2 dòng type LESSON có subject_id giống nhau
And câu (3) cho A, B type NORMAL và completed = 0 hoặc NULL
And câu (4) trả 0 dòng hoặc mọi dòng status REVERTED
And không câu nào ghi dữ liệu

Maps to:

• Business Rule: BR-01, BR-04

AC-M1.2 - Chép id vào fixture bằng tay

Given câu (2) và câu (5) của case 0.1 đã chạy xong
Then fixture subject_id và foundation_class_id KHÔNG tự thay đổi
And ghi chú câu hướng dẫn tester chép giá trị vào fixture

Maps to:

• Business Rule: BR-02

AC-M1.3 - Dọn dữ liệu

Given A→B và C→B đã có bản ghi lịch sử, A/B/C đang ở type khác NORMAL tại L1/L2/F1
When người dùng chạy 3 câu của case 0.2 và xác nhận từng câu
Then A, B, C có type NORMAL tại L1, L2, F1
And tiến độ đã học của A tại L1 và B tại L2 = 0
And bảng lịch sử không còn dòng nào có người cho A hoặc C và người nhận B

Maps to:

• Business Rule: BR-03, BR-04

AC-M1.4 - Catalogue nhất quán

Given một case tham chiếu id "s26297.<prefix>.<n>"
Then id đó có trong cả bản FE và bản BE của catalogue
And nếu thiếu trong bản FE thì màn lỗi khi tải (NFR-S-05)

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	⚠️ Observed — phạm vi xoá của câu dọn lịch sử	Hành vi hiện tại: câu (3) của 0.2 xoá cứng mọi bản ghi lịch sử có người cho A / C và người nhận B — không lọc ngày, không lọc bản ghi đã xoá mềm (sapp-26297-sql.constants.ts:245-249) — OQ-S-09
EC-M1.2	⚠️ Observed — ép NORMAL bất kể trạng thái gốc	Hành vi hiện tại: câu (1) của 0.2 đặt NORMAL cho A, B, C ở cả 3 lớp, kể cả khi trạng thái gốc trước test không phải NORMAL (sapp-26297-sql.constants.ts:231-236) — OQ-S-09
EC-M1.3	Chưa chép foundation_class_id trước khi dọn	Câu có token {foundation_class_id} chưa thay — hành vi theo US-P09 (thiếu param)
EC-M1.4	Quên khôi phục học viên bị xoá mềm ở 3B	0.2 không tự khôi phục — chỉ có dòng hướng dẫn dùng câu #3 panel nhóm B

5. Cross-feature AC

AC-X.1 - Phụ thuộc SQL runner

Given SQL runner dùng chung không có kết nối DB Ops của môi trường đang chọn
When người dùng chạy câu của case 0.1 hoặc 0.2
Then lỗi hiển thị theo US-P09

Maps to:

• REL-04 (Affects - Ops SQL runner)