Sửa rẻ - LẬP sổ khái niệm UI

0. Mục tiêu

Quy trình này dùng cho lần đầu lập sổ khái niệm của một UI.

Mục tiêu:

• Đưa khái niệm của UI vào bảng nháp sua_re_ui_khai_niem_nhap.
• So với sổ chung nháp sua_re_khai_niem_nhap.
• Khái niệm cũ thì nối về concept đã có.
• Khái niệm mới thì Owner duyệt rồi mới đưa vào sổ chung.
• Không tạo DOT mới trong G1.

1. Phạm vi G1

G1 chọn PA3:

Agent đọc seed/scan → render SQL template → manifest duyệt → dot-pg-atomic-apply → PG nháp → SELECT/VIEW report

Không làm trong G1:

• DOT mới.
• Directus collection.
• Nuxt UI.
• Promote sang bảng chính thức.
• Vector/report chính thức.
• dot-collection-create.
• dot-report-publish.

2. Quy tắc khóa dữ liệu

2.1. slot_key

slot_key là danh tính bền của một vị trí/đầu mối khái niệm trên UI.

Công thức:

slot_key = ui_id + '::' + location_anchor

Trong đó location_anchor ưu tiên:

config_key:<path>      tốt nhất
code_marker:<class>    chấp nhận
text_marker:<string>   dễ vỡ, chỉ dùng tạm

Cấm đưa các thành phần sau vào slot_key:

• raw_label
• scan_id
• chỉ số mảng như items[3]

2.2. item_key

item_key là danh tính của một bản ghi slot trong một lần scan.

Công thức:

item_key = slot_key || '::' || scan_id

2.3. raw_label và purpose

raw_label và purpose chỉ là thuộc tính của slot.

Chúng không phải khóa.

Lý do: nếu đưa nhãn vào khóa, sửa nhãn sẽ biến thành xóa bản ghi cũ + thêm bản ghi mới, phá mục tiêu sửa-rẻ.

3. Ghi chú riêng cho pilot master-list

Pilot đầu tiên dùng:

master-list-quy-trinh-v1

Trong pilot này, không bóc lại UI từ đầu nếu đã có seed hợp lệ.

Input seed đã có:

• concept-ledger.js: 13 concept.
• ui-contracts.js: 30 usage.
• Kỳ vọng: 27 matched, 2 candidate, 1 review.

Agent phải đọc seed, sinh slot_key, rồi render SQL import.

Không được bóc lại UI thô rồi tạo bộ concept khác, vì sẽ không tái tạo được baseline 27/2/1.

4. Quy trình vận hành

Bước	Nhiệm vụ	Khi nào bắt đầu / ai ra lệnh / trigger	Ai làm	Yêu cầu sản phẩm hoàn thành	Ghi/lưu ở đâu	Lưu ý
A1	Chỉ định UI lập sổ	Owner yêu cầu lập sổ cho một UI	Owner	ui_id, ui_file, phạm vi scan	Prompt hoặc KB task	G1 pilot là master-list-quy-trinh-v1
A2	Lấy input seed/scan	Sau A1	Agent	seed hoặc scan artifact đã đọc được	file seed / file scan	Pilot dùng concept-ledger.js + ui-contracts.js, không bóc lại từ đầu
A3	Sinh slot_key và item_key	Sau A2	Agent	mỗi usage có slot_key, item_key, anchor_quality	scan artifact nội bộ / report	slot_key không chứa nhãn, scan_id, index
A4	Render SQL tạo/nạp	Sau A3	Agent	SQL create/import đã render	/opt/incomex/dot/sql/sua-re/*.sql	SQL chưa ghi PG nếu chưa qua manifest
A5	Kiểm SQL trước khi duyệt manifest	Có SQL	Agent trình summary; Owner/Fable/GPT soi nếu cần	Summary: file nào, bảng nào, số dòng, thao tác gì	KB/prompt report	Không để Agent tự duyệt mù SQL của chính nó
A6	Cập nhật manifest	SQL đã được chấp nhận	Claude Code/Owner theo lệnh	dòng sha256<TAB>relpath	/opt/incomex/dot/sql/approved-sql-manifest.tsv	Manifest là cổng duyệt ghi PG
A7	Apply SQL	Manifest hợp lệ	dot-pg-atomic-apply	dữ liệu được ghi atomic	PG public.directus	Không psql tay
A8	Resolve concept khi import	Trong SQL import/apply	SQL qua dot-pg-atomic-apply	dòng matched được gán concept_id; dòng chưa chắc để null/pending	sua_re_ui_khai_niem_nhap	Match có phần ghi: concept_id được resolve ngay khi import; SELECT/VIEW chỉ report
A9	Xuất review report	Sau import/match	Agent chạy SELECT/VIEW read-only	report chỉ gồm review/candidate/delta	KB report	Không bắt Owner xem matched
A10	Owner duyệt pending	Có review report	Owner	quyết định map_existing, create_new, keep_pending	phản hồi Owner / phiếu decision	AI không tự quyết ca mơ hồ
A11	Apply decision	Owner đã duyệt	Agent render SQL decision + dot-pg-atomic-apply	usage được nối concept; nếu mới thì insert concept	2 bảng PG nháp	Một transaction
A12	Báo cáo hoàn tất	Sau A11	Agent	số concept, usage, matched, review, candidate, new	KB report	Là bằng chứng kết thúc lượt lập sổ

5. Cơ chế match trong lượt lập sổ

Match không chỉ là SELECT read-only.

Khi import, SQL được phép resolve khớp rõ:

exact concept_key / alias rõ → gán concept_id
không rõ → concept_id null, đưa review/candidate

SELECT/VIEW dùng để:

• kiểm số lượng matched/review/candidate;
• xuất report Owner;
• không ghi dữ liệu.

Không fuzzy auto-match.

6. Hạ tầng/công cụ phục vụ quy trình này

Hạ tầng/công cụ	Trạng thái	Vai trò
dot-pg-atomic-apply	đã có	cổng ghi PG duy nhất
/opt/incomex/dot/sql/	đã có	nơi đặt SQL allowlist
approved-sql-manifest.tsv	đã có	duyệt SQL bằng sha256
sua_re_khai_niem_nhap	cần tạo	sổ khái niệm chung nháp
sua_re_ui_khai_niem_nhap	cần tạo	usage/slot từng UI
SQL create-core.sql	cần làm	tạo 2 bảng
SQL import seed/full	cần làm	nạp concept + usage
SQL decision	cần làm	apply quyết định Owner
SELECT/VIEW delta	cần làm	report review/candidate/delta

7. Tiêu chí PASS của quy trình lập sổ

Với pilot master-list-quy-trinh-v1, PASS khi:

- 2 bảng PG nháp được tạo bằng dot-pg-atomic-apply.
- Concept seed được nạp đúng.
- Usage seed được nạp đúng.
- 30 usage có slot_key hợp lệ.
- Không slot_key nào chứa raw_label, scan_id, hoặc index.
- Tái tạo được baseline 27 matched / 2 candidate / 1 review.
- Review report chỉ hiện dòng cần Owner quyết.
- Không dùng DOT mới.
- Không dùng Directus/Nuxt/vector/promote.

8. Cái không giải quyết trong quy trình này

• Không sửa UI.
• Không xử lý delta sửa-rẻ.
• Không promote sang bảng chính thức.
• Không tạo DOT mới.
• Không chuẩn hóa toàn bộ MO*.

Phần sửa-rẻ sau khi sổ đã lập nằm ở quy trình riêng: sua-re-sua-so-khai-niem-ui.md.