Sửa rẻ - SỬA sổ khái niệm UI

0. Mục tiêu

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

Mục tiêu:

• Chỉ xử lý đúng slot vừa sửa.
• Không quét lại toàn UI.
• Không match lại 30 item đang đúng.
• Không làm rung các slot không liên quan.
• Nếu sửa làm phát sinh khái niệm mới thì Owner duyệt rồi mới đưa vào sổ chung.

1. Điều kiện trước khi chạy quy trình này

Quy trình này chỉ chạy khi UI đã qua quy trình lập sổ lần đầu.

Phải có sẵn:

• bảng sua_re_khai_niem_nhap;
• bảng sua_re_ui_khai_niem_nhap;
• usage hiện hành của UI trong bảng sua_re_ui_khai_niem_nhap;
• mỗi usage có slot_key bền;
• slot_key không chứa raw_label, scan_id, hoặc chỉ số mảng.

Nếu chưa có những điều kiện trên thì phải chạy quy trình Sửa rẻ - LẬP sổ khái niệm UI trước.

2. Luật cứng của sửa-rẻ

Sửa đâu → rà đó.
Sửa một slot → chỉ kiểm đúng slot đó.
Không quét lại toàn UI.
Không match lại toàn bộ UI.
Không ghi đè dữ liệu của slot khác.

3. Phiếu sửa / change_scope

Mỗi lần sửa phải có phiếu sửa.

Nơi lưu G1:

ui-preview/change-scope/<ui_id>.jsonl

Mỗi dòng JSONL là một phiếu.

Mẫu tối thiểu:

{
  "ui_id": "master-list-quy-trinh-v1",
  "ui_file": "master-list.js",
  "slot_key": "master-list-quy-trinh-v1::code_marker:qv-note",
  "anchor": "code_marker:qv-note",
  "kind": "edit",
  "old_label": "Ghi chú",
  "new_label": "Ghi chú nội bộ",
  "old_purpose": "Chú thích tự do cho task.",
  "new_purpose": "Chú thích nội bộ cho task, chỉ admin thấy.",
  "reason": "phân biệt ghi chú công khai và ghi chú nội bộ",
  "requester": "cowork:huyen",
  "at": "2026-07-07T10:00:00Z"
}

kind gồm:

add
edit
delete

4. Luật verify slot trước khi ghi

Đây là điểm bắt buộc.

Không được tin mù slot_key trong phiếu sửa.

Trước khi render SQL delta, Agent phải kiểm:

1. slot_key có tồn tại trong usage hiện hành của UI không;
2. nếu phiếu có old_label, old_label phải khớp hoặc gần khớp usage hiện hành;
3. nếu phiếu có anchor, anchor phải trỏ đúng vị trí trong file UI;
4. nếu không xác minh được slot, phải HOLD, không ghi PG.

Lý do:

Nếu người sửa gõ sai slot_key, hệ có thể ghi nhầm slot khác và làm hỏng dữ liệu đang đúng. Đây là lỗi ngầm nguy hiểm nhất của quy trình sửa-rẻ.

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

B0. Scan lại bằng cùng scanner trước khi quyết định sửa

Trước B1/B2, nếu có UI source hoặc vùng sửa đọc được, Agent phải dùng cùng nguyên tắc scanner của SR-LAP để nhận diện nguồn khái niệm thật của UI/vùng sửa.

Không mặc định bóc DOM, không mặc định tìm một biến cụ thể, không mặc định tin seed cũ. Agent phải xác định nguồn theo thứ tự:

structured config → contract/schema → JS render/computed marker → DOM/data marker → text fallback

Bảng luật nhận diện nguồn đầy đủ (R1–R5 + luật phân vai (a)(b)(c)) là nguồn sự thật gốc duy nhất ở SR-LAP mục A0a (sua-re-lap-so-khai-niem-ui.md). SR-SUA dùng đúng bảng đó, không chép lại. Các luật chung sau áp y nguyên khi sửa-rẻ:

• JS-render là secondary source bắt buộc đọc khi có code_marker/computed field ngoài config (SR-LAP A0a luật (c)).
• Độ hạt object-leaf: gộp leaf chỉ-cùng-nhau-xuất-hiện thành 1 slot (SR-LAP A0c).
• Page-frame page_config: config khung trang không auto thành khái niệm, đánh needs_review (SR-LAP A0e).
• Concept vs usage: 1 concept → nhiều usage row; anchor priority chỉ chọn anchor tốt cho từng usage, không bóp bỏ usage khác (SR-LAP A0f).

Sau đó đối chiếu scan mới với PG hiện hành:

unchanged: cùng slot_key, label/purpose không đổi;
changed: cùng slot_key, label/purpose hoặc concept đổi;
new_slot: scan mới có, PG chưa có;
missing: PG có current, scan/vùng sửa không còn thấy.

Sửa-rẻ không có nghĩa là đọc UI bằng cách khác. Nó dùng cùng scanner, nhưng chỉ xử lý phần delta sau khi so với PG.

B0b. Scan khái niệm, không scan dữ liệu

Nếu nguồn có mảng/list, anchor phải gộp mảng bằng []. Không tạo slot theo từng index dữ liệu.

Ví dụ đúng:

config_key:PAGE.items[].steps[].tasks[].minutes

Ví dụ sai:

config_key:PAGE.items[0].steps[2].tasks[4].minutes

Một thuộc tính xuất hiện ở nhiều bản ghi vẫn chỉ là một slot khái niệm nếu cùng path tổng quát.

Ngoài gộp mảng [] (chiều dữ liệu), còn gộp object-leaf theo chiều đồng-xuất-hiện: các leaf scalar chỉ-cùng-nhau-hiện trên bề mặt là 1 slot (vd maker.t+maker.n ⇒ maker; links.mot/moit/mout ⇒ links). Chỉ tách khi leaf tự nổi độc lập. Luật gốc ở SR-LAP A0c.

B0c. Hai lớp scan khi sửa: UI concept và luồng nghiệp vụ

Nếu UI/vùng sửa có cả luồng nghiệp vụ, Agent phải tách 2 lớp:

1. UI concept layer: dùng để cập nhật sổ khái niệm UI theo cơ chế current/history.
2. Business-flow layer: dùng để phát hiện thay đổi luồng, bước, vai trò, điều kiện, input/output. Lớp này chỉ ghi artifact/report flow nếu chưa có schema PG riêng; không nhét lẫn vào 2 bảng sua_re_*.

Flow change artifact nên lưu dưới dạng JSONL, ví dụ:

/opt/incomex/docs/mcp-writes/sua-re/flow-scan/<ui_id>/<scan_id>.jsonl

Nếu phát hiện thay đổi nghiệp vụ nhưng chưa có schema flow chính thức, report phải ghi flow_change_pending_schema, không tự ghi PG.

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 ý
B1	Tạo phiếu sửa	Có sửa UI	Cowork hoặc Owner	JSONL có ui_id, ui_file, slot_key hoặc anchor, old/new label/purpose	ui-preview/change-scope/<ui_id>.jsonl	Phiếu là trigger của quy trình
B2	Đọc phiếu sửa	Có phiếu mới	Agent	phiếu được parse hợp lệ	phiên làm việc/report	Không scan toàn UI
B3	Verify slot với PG hiện hành	Sau B2	Agent đọc PG read-only	xác nhận slot tồn tại và đúng old_label/anchor	report ngắn	Không tin mù slot_key trong phiếu
B4	Verify anchor trong file UI	Sau B3	Agent đọc đúng anchor	xác nhận anchor còn tồn tại trong UI	report ngắn	Chỉ kiểm đúng anchor, không quét lại toàn file
B5	Render SQL delta	Slot đã verify	Agent	SQL delta cho đúng slot	/opt/incomex/dot/sql/sua-re/*.sql	Không đụng slot khác
B6	Kiểm SQL trước manifest	Có SQL delta	Agent trình summary; Owner/Fable/GPT soi nếu cần	summary file/bảng/số dòng/thao tác	KB/prompt report	Không để Agent tự duyệt mù SQL của chính nó
B7	Cập nhật manifest	SQL được chấp nhận	Claude Code/Owner theo lệnh	dòng sha256<TAB>relpath	approved-sql-manifest.tsv	Manifest là cổng ghi PG
B8	Apply delta	Manifest hợp lệ	dot-pg-atomic-apply	dòng cũ của slot is_current=false, dòng mới is_current=true	sua_re_ui_khai_niem_nhap	Không xóa mù
B9	Resolve concept cho delta	Trong SQL delta/apply	SQL qua dot-pg-atomic-apply	nếu exact/alias thì gán concept_id; nếu không thì pending	sua_re_ui_khai_niem_nhap	Match ghi chỉ trên slot delta
B10	Xuất report nếu cần	Sau B8/B9	Agent SELECT/VIEW read-only	chỉ dòng delta nếu review/candidate/purpose đổi	KB report	Không match lại toàn UI
B11	Owner duyệt nếu có pending	Có review/candidate	Owner	map_existing / create_new / keep_pending	phản hồi Owner / phiếu decision	matched thì bỏ qua
B12	Apply decision	Owner đã duyệt	Agent render SQL decision + dot-pg-atomic-apply	nối concept cũ hoặc tạo concept mới	2 bảng PG	Chỉ áp đúng slot
B13	Báo cáo hoàn tất	Sau B12	Agent	slot nào đổi, concept_id nào, có phát sinh concept mới không	KB report	Dùng để kiểm sửa có rẻ thật không

6. Cách ghi dữ liệu khi sửa

6.1. Nếu sửa nhãn nhưng vẫn là khái niệm cũ

Ví dụ:

Ghi chú → Ghi chú nội bộ

Nếu vẫn map vào concept cũ, SQL delta làm:

1. lật bản cũ của slot:

is_current = false

2. insert bản mới cùng slot_key, scan mới:

slot_key giữ nguyên
item_key = slot_key || '::' || scan_id mới
raw_label = nhãn mới
purpose = purpose mới
concept_id = concept cũ nếu exact/alias resolve được
is_current = true

Các slot khác không đổi.

6.2. Nếu sửa làm phát sinh khái niệm mới

Nếu delta không khớp concept cũ:

concept_id = null
match_status = candidate hoặc review

Owner duyệt create_new thì decision SQL:

1. insert concept mới vào sua_re_khai_niem_nhap;
2. ghi first_seen_* từ usage delta;
3. update usage delta trỏ vào concept mới.

6.3. Nếu phiếu sửa sai slot

Nếu verify không khớp:

HOLD
không render SQL
không cập nhật manifest
không ghi PG

7. Review report cho sửa-rẻ

Report chỉ hiện slot có vấn đề, không hiện toàn UI.

Mẫu:

BẢNG DUYỆT SỬA-RẺ
UI: master-list-quy-trinh-v1
Slot: master-list-quy-trinh-v1::code_marker:qv-note
Thay đổi: Ghi chú → Ghi chú nội bộ
Purpose mới: Chú thích nội bộ cho task, chỉ admin thấy.

Kết quả match:
- matched / review / candidate
- gợi ý concept nếu có
- vì sao

Owner chọn:
[ ] map_existing
[ ] create_new
[ ] keep_pending

8. 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ò
sua_re_ui_khai_niem_nhap	đã có sau quy trình lập sổ	lưu usage/slot hiện hành và lịch sử slot
sua_re_khai_niem_nhap	đã có sau quy trình lập sổ	sổ concept chung nháp
change-scope/<ui_id>.jsonl	cần có	phiếu sửa đầu vào
dot-pg-atomic-apply	đã có	apply SQL delta/decision
SQL import-delta	cần làm	lật current cũ + insert current mới cho đúng slot
SQL decision	cần làm	apply Owner decision
SELECT/VIEW delta	cần làm	report read-only

9. Tiêu chí PASS của quy trình sửa-rẻ

Một lượt sửa-rẻ PASS khi:

- có phiếu sửa rõ slot;
- Agent verify slot với PG hiện hành trước khi ghi;
- Agent verify anchor trong UI trước khi ghi;
- chỉ đúng slot đó được cập nhật;
- slot_key giữ nguyên;
- item_key mới theo scan mới;
- các slot khác không thay đổi;
- không quét lại toàn UI;
- không match lại toàn UI;
- nếu phát sinh pending thì Owner duyệt;
- báo cáo KB ghi rõ kết quả.

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

• Không lập sổ lần đầu cho UI chưa có dữ liệu.
• Không promote sang bảng chính thức.
• Không tạo DOT mới.
• Không chuẩn hóa marker toàn bộ UI.
• Không xử lý sửa hàng loạt nhiều UI cùng lúc.

Các nội dung đó để phase sau.