Chuẩn format báo cáo sau khi quét UI — v0.1 (bản thử)

Trạng thái: v0.1 — BẢN THỬ, chưa chốt. Khuôn này rút từ dữ liệu thật của UI master-list-quy-trinh-v1 (config-driven) và đối chiếu 30 slot đang có trong PG. Nó sẽ được chỉnh sau đợt quét thử 2 UI (master-list, mow-unified-canvas) vì canvas có thể thuộc dạng UI khác. Đừng coi đây là chuẩn cuối cho tới khi có ghi "v1.0 — CHỐT".

0. Mục đích

Một khuôn chung để mọi bên quét UI đều xuất ra cùng một dạng, nhờ đó máy so sánh (diff) chỉ báo khác biệt thật, không báo nhiễu hình thức.

Các bên phải theo khuôn này:

• Agent quét (Claude Code, Codex…).
• DOT scanner (khi viết ở bước sau).

Lưu ý quan trọng — đây KHÔNG phải format của PG. Format quét chỉ chứa thứ quét ra được. PG có thêm nhiều cột chỉ sinh ra sau khi ghi sổ (id, scan_id, is_current, concept_id, dedupe_key, owner_decision…). Quan hệ giữa hai bên là phép chiếu ở mục 5, không phải bắt hai bên giống hệt nhau.

1. Định dạng file

• Một file JSONL: mỗi dòng một slot, một object JSON.
• Encoding UTF-8, tiếng Việt có dấu để nguyên.
• Sắp xếp: theo slot_key tăng dần (abc). Bắt buộc — để hai bản luôn cùng trật tự, diff mới sạch.
• Tên file: <ui_id>__<who>.jsonl với who = claude | codex | dot (vd master-list-quy-trinh-v1__claude.jsonl).

2. Các trường của một dòng (đúng thứ tự, đủ trường)

Trường	Bắt buộc	Giá trị
ui_id	có	định danh UI, vd master-list-quy-trinh-v1
location_anchor	có	địa chỉ bền của slot (mục 3)
slot_key	có	ui_id::location_anchor (ghép đúng, không thêm bớt)
anchor_type	có	config_key | code_marker | text_marker
source_layer	có	config | js | dom | text
raw_label	có	nhãn hiển thị lúc quét (chỉ để người đọc, KHÔNG phải khóa)
kind	có	concept (vào sổ khái niệm) | flow_data (dữ liệu luồng, KHÔNG vào sổ)
purpose	có	mô tả mục đích, hoặc "" nếu chưa rõ
purpose_status	có	explicit | inferred | unknown

Không thêm trường tự phát. Cần trường mới → đề xuất ở report, không nhét vào dòng.

3. Luật dựng location_anchor (phần chống lệch-giả quan trọng nhất)

Anchor phải có tiền tố loại, theo thứ tự ưu tiên:

1. config_key:<đường-dẫn-trong-config> — bền nhất. Vd config_key:MASTER_CONFIG.items[].maker.
2. code_marker:<marker-ổn-định> — cho slot tính toán/hiển thị nằm trong JS. Vd code_marker:qv-tot.
3. text_marker:<chuỗi-hiển-thị> — yếu nhất, chỉ khi không có gì bền hơn.

Quy tắc chuẩn hóa bắt buộc (hai bên sai lệch nhau ở đây là hỏng diff):

• Mảng luôn viết [] rỗng, KHÔNG số. Đúng: items[].steps[].items[].min. Sai: items[0].steps[2].items[1].min. Một thuộc tính xuất hiện ở 1.000 phần tử vẫn là một slot.
• Nhiều leaf luôn đi cùng nhau và cùng một điểm trên UI → gộp về object cha, KHÔNG tách leaf. Vd items[].maker (không tách .t / .n), items[].links (không tách .mot/.moit/.mout). (Đây là bài học thật từ master-list: PG neo ở object-level.)
• KHÔNG đưa raw_label vào anchor/slot_key. Nhãn đổi được; địa chỉ thì không.
• KHÔNG dùng chỉ số, id runtime, hay giá trị dữ liệu trong anchor.

4. Ranh giới kind: khái niệm UI vs dữ liệu luồng

• concept — loại thuộc tính: mã quy trình, số phút, trạng thái, người thực hiện, tổng phút… Cái này vào sổ khái niệm.
• flow_data — nội dung cụ thể của một luồng: "WF-0001 gồm task nào", "task A mấy phút", input/output của một task cụ thể. Quét ra thì ghi nhận với kind=flow_data để đối chiếu, nhưng không đưa vào sổ khái niệm sua_re_*.

Phân biệt nhanh: gộp [] xong mà vẫn là một loại thông tin → concept. Nếu là một bản ghi/giá trị cụ thể → flow_data.

5. Phép chiếu sang PG (để đối chiếu, KHÔNG phải để trùng khuôn)

Khi so bản quét với sổ PG (sua_re_ui_khai_niem_nhap), ghép theo:

Bản quét	↔	PG
slot_key	=	slot_key
location_anchor	=	location_anchor
raw_label	~	raw_label (chỉ tham khảo, có thể khác do đổi nhãn)
kind=concept	→	dòng usage trong sổ
kind=flow_data	→	KHÔNG có trong sổ (đúng)

Các cột PG không có trong bản quét (đúng, không phải lỗi): id, item_key, scan_id, is_current, concept_id, owner_concept_id, dedupe_key, match_status, owner_decision. Chúng sinh ra ở bước ghi sổ, không phải bước quét.

6. Kết quả so sánh (diff) — các nhóm

Khi so hai bản quét (hoặc quét-vs-PG), mỗi slot rơi vào đúng một nhóm:

• match — cùng slot_key, cùng kind.
• only_A / only_B — chỉ một bên có (bên kia sót, hoặc là slot thật mới).
• anchor_diff — cùng chỗ trên UI nhưng hai bên đặt anchor khác cấu trúc (vd một bên gộp object, một bên tách leaf). Đây là chưa thống nhất quy tắc, không phải thiếu.
• label_or_purpose_diff — cùng slot_key nhưng raw_label/purpose khác.
• kind_diff — cùng slot_key nhưng một bên gọi concept, bên kia flow_data. Phải xử, vì ảnh hưởng có vào sổ hay không.

Diff chỉ được phản ánh khác biệt thật. Nếu diff báo lệch mà soi ra do format (thứ tự, tiền tố, khoảng trắng) → đó là lỗi format, sửa khuôn, không phải lệch nội dung.

7. Câu nhớ

Cùng khuôn — cùng trật tự — anchor cùng luật, thì diff mới nói thật. Quét ra concept với flow_data; sổ chỉ nhận concept. Format quét ≠ format PG; nối nhau bằng slot_key, không bắt giống hệt.