Council Review — GPT — Vòng 1: Dự thảo Bảng Master Entity Enrichment

Ngày: 2026-04-23
Reviewer: Incomex Hội đồng AI (GPT)
Draft được review: du-thao-entity-enrichment-master-fix30.md
Prompt chuẩn: council-prompt-entity-enrichment-master-round1.md

ĐIỂM: 8.6/10 VERDICT: APPROVE WITH CHANGES

ĐÁNH GIÁ TỪNG MỤC

A. Kiến trúc bảng master

A1 — Schema phù hợp? Đánh giá: Ý tưởng schema là đúng hướng và khớp HP: tách SSOT enrichment khỏi entity runtime để chặn việc AI ghi thẳng không duyệt; dùng PG table + FK thay text tự do là đúng NT10, NT13 và hỗ trợ NT2/NT5/NT12. Tuy nhiên schema hiện tại còn 3 điểm cần sửa:

composition_level và governance_role đang là TEXT thuần nhưng thực chất suy ra được từ SSOT khác (entity_species, collection_registry) → dễ drift, chạm NT1 (một sự thật nhưng nhiều bản sao).
provenance đang để trong master là hợp lý, nhưng cần ràng buộc rõ vai trò của nó với label FAC-PROV ở entity mirror để tránh 2 nguồn provenance khác nhau.
Thiếu trường quản trị duyệt tối thiểu: approved_at, approved_by hoặc tham chiếu tới request/approval record; nếu không “approved gate” mới có trạng thái mà chưa có audit duyệt đủ mạnh.

Kết luận: Giữ bảng master, nhưng nên biến các field suy ra được thành field tính/seed-only hoặc bỏ khỏi master; và bổ sung audit duyệt.

A2 — 1 bảng cho 500K+ rows có rủi ro performance? Đánh giá: Không thấy đây là rủi ro chính. Với PostgreSQL, 500K rows là nhỏ nếu index đúng và query path hẹp. Thiết kế “1 bảng duy nhất cho tất cả entity” còn đúng tinh thần SSOT và giúp query phủ toàn cục. Chưa có căn cứ phải partition ở mốc này. Theo NT13, nên dùng PG native đơn giản trước; partition chỉ khi có số liệu chứng minh cần.

Khuyến nghị kỹ thuật:

Tạo index thực dụng: (approved, updated_at), partial index WHERE approved='yes', index (synced_at), (source_table), (jurisdiction), (species_code).
Không partition ở phase 1. Theo dõi sau khi vượt nhiều triệu row hoặc khi xuất hiện retention/window query nặng.

A3 — FK chuẩn hóa đủ chưa? Đánh giá: Hướng FK là rất đúng với NT10 và khắc phục triệt để pilot sai “Đ22 / Điều 22 / D22”. Nhưng chưa đủ chặt.

jurisdiction → normative_registry(code) là đúng.
species_code → entity_species(code) là đúng.
Nên xem lại source_table: không FK được trực tiếp tới collection_registry.collection_name nếu khác kiểu/không unique? Nếu unique thì nên FK hoặc ít nhất CHECK/trigger verify tồn tại trong collection_registry, vì đây là điểm neo governance rất quan trọng theo Đ36 GP1/GP8.1.
governance_role không nên là text tự do; nếu giữ thì phải derive từ collection_registry, không cho nhập tay.
Nếu dùng approval thật sự, nên có approval_request_id/approved_by liên kết với cơ chế Đ32 thay vì cột yes/no thuần.

A4 — PK = entity_code có đúng không? Đánh giá: Đúng, với điều kiện giữ đúng giả định hiện hành của hệ thống: entity_code là mã định danh toàn cục duy nhất theo luật Registry/metadata hiện hành. Nếu code đã là global SSOT thì composite PK (entity_code, source_table) chỉ tạo dư thừa và mở đường cho duplicate logic, đụng NT1 + Đ14.

Điều kiện bắt buộc: phải ghi rõ trong amend rằng entity_enrichment.entity_code tham chiếu 1:1 với entity toàn cục; source_table là metadata phụ, không tham gia identity.

A5 — Approved gate trigger hiện đúng chưa? Đánh giá: Chưa đúng đủ. Đây là lỗ lớn nhất của draft. Trigger hiện tại:

IF NEW.approved = OLD.approved THEN
  NEW.approved := 'no';
END IF;

logic này sẽ reset approved cho cả những update kỹ thuật như DOT chỉ ghi synced_at, updated_at, hoặc thao tác bảo trì không làm thay đổi nội dung enrichment. Kết quả: DOT sync có thể tự làm record quay lại approved='no', gây vòng lặp hoặc mất sync giả. Điều này vi phạm tinh thần NT9 và NT14 vì cơ chế chưa thực thi an toàn.

Kết luận: approved chỉ nên reset khi thay đổi các field nghiệp vụ cần review lại (description, jurisdiction, enrichment_notes, có thể provenance) — không reset khi chỉ đổi approved, approved_at, approved_by, synced_at, updated_at.

B. Cơ chế sync

B6 — Debounce 5 phút + 24h heartbeat hợp lý? Đánh giá: Hợp lý cho single VPS và rất đúng tinh thần NT2 + NT12: có động cơ chính sync, có nhịp kiểm định/heartbeat. 5 phút giúp gom burst update; 24h heartbeat giúp parity không bị “quên mãi mãi”.

Rủi ro: Nếu chỉ dựa vào last_edit > 5 phút mà không có verify DOT mạnh, có thể xảy ra “tưởng đã sync nhưng chưa sync”. May là draft đã có DOT verify cặp, nên mô hình này ổn. Cần ghi rõ heartbeat là verify parity, không nhất thiết re-write toàn bộ để tránh churn.

B7 — DOT sync cặp đã đủ chưa? Đánh giá: Gần đủ, đúng NT12. Nhưng nên thêm 4 guard:

Idempotent write: chỉ update entity khi giá trị mirror thực sự khác.
Scope guard: chỉ sync các field được master sở hữu; cấm DOT ghi đè field ngoài hợp đồng.
Success gate: chỉ set synced_at sau khi write entity + provenance mirror thành công.
Drift issue model: verify phát hiện lệch phải ghi system_issues với matching key ổn định theo Đ22 §1.1, tránh spam issue mới mỗi cycle.

B8 — Seed khi birth có conflict với birth guard/provenance hiện có? Đánh giá: Về nguyên tắc không conflict, vì Đ4 §2.1.1 đã có pattern companion trigger AFTER INSERT cho provenance; thêm 1 companion trigger seed master là phù hợp với DUAL-TRIGGER/companion architecture. Nhưng cần cực rõ về thứ tự và payload:

BEFORE trigger Đ4 sinh/kiểm tra description cơ bản trên entity gốc.
AFTER trigger provenance gắn PROV-DOT.
AFTER trigger seed entity_enrichment copy snapshot ban đầu.

Cảnh báo: seed master phải lấy giá trị sau BEFORE trigger (description đã auto-gen), không lấy row thô trước guard. Đồng thời nếu trigger provenance hoặc birth registry fail thì cả transaction phải rollback đồng bộ; không chấp nhận entity sinh nhưng master không có row (đúng như draft nêu).

C. Amend luật

C9 — Đ3 §2.7 mới đặt ở Đ3 có đúng SSOT không? Đánh giá: Đúng, vì đây là luật Metadata và entity_enrichment về bản chất là hạ tầng quản lý metadata/enrichment. Đ3 hiện đã sở hữu mô hình 2 mức mô tả (§2.5), template (§2.6), và ngoại lệ backfill (§2.4), nên đặt định nghĩa master enrichment ở Đ3 là logic nhất.

Lưu ý: Đ22 chỉ nên sở hữu health-check hạ tầng scan bảng này; Đ4 sở hữu thời điểm birth seed; Đ3 mới là nơi định nghĩa “enrichment là gì, SSOT ở đâu”.

C10 — Đ4 thêm companion trigger 2 có quá nặng? Đánh giá: Không quá nặng ở mức hiện tại. 3 trigger AFTER INSERT vẫn trong ngưỡng bình thường nếu mỗi trigger làm đúng 1 việc nhỏ, thuần PG-native, cùng transaction. Điều này phù hợp NT13 và pattern Đ4 §2.1.1 đã có sẵn.

Điều kiện: phải tránh để trigger seed master gọi logic nặng hoặc join rộng. Chỉ seed snapshot tối thiểu, còn enrichment chi tiết để phase sau. Nếu trigger seed bắt đầu làm lookup phức tạp, khi đó birth path sẽ bị phình sai hướng.

C11 — Đ22 H11b mở rộng scan master + entity có redundant không? Đánh giá: Có chồng lấn nhẹ nhưng nên giữ cả 2, vì chúng trả lời 2 câu hỏi khác nhau:

Scan master: quản trị enrichment pipeline có bị kẹt không? (approved='no' quá lâu, chưa sync, thiếu row...)
Scan entity: runtime mirror cuối cùng có đúng/đủ không? (đặc biệt với bypass hoặc drift ngoài DOT)

Đây là đúng tinh thần “sổ kép” của Đ22 §2 và NT12 hai chiều. Không nên gộp thành 1 check duy nhất; nên tách 2 check-code để issue rõ nguồn gốc.

C12 — Đ36 đăng ký bảng mới là governed, species governance_infra có đúng không? Đánh giá: Đúng. entity_enrichment là bảng governance hạ tầng, trực tiếp điều phối write path metadata và sync xuống entity. Nó không phải dữ liệu người dùng thuần, cũng không phải log/observed. Gắn governed + governance_infra khớp Đ36 GP1/GP4 và HP NT6/NT13.

D. Tầm nhìn scale

D13 — 900,000 quan hệ tương lai, bảng master có chứa được không? Đánh giá: Có chứa được, vì draft này giải quyết metadata enrichment per entity, không phải kho toàn bộ quan hệ semantic nhiều-nhiều. 900,000 quan hệ quy trình × bước × entity là bài toán khác, gần NĐ-36-01 / entity_relations hơn là bắt entity_enrichment gánh.

Kết luận: Không nên biến entity_enrichment thành bảng quan hệ đa dụng. Nó nên giữ vai trò “master metadata row per entity”. Quan hệ lớn trong tương lai phải đi bảng relation riêng theo hướng Đ36 GP5 / NĐ-36-01.

D14 — Thêm cột tương lai: ALTER TABLE đủ hay cần JSONB? Đánh giá: Phase này ALTER TABLE là đúng, JSONB chỉ nên dùng rất hạn chế. HP NT10/NT13 thiên về PG-validate-query-enforce; JSONB quá sớm sẽ làm mất chuẩn hóa và mở cửa cho text tự do kiểu mới.

Đề xuất:

Field ổn định, có semantics rõ, có nhu cầu filter/query/enforce → cột thật + FK/check.
Chỉ dùng extra_metadata JSONB cho vùng thật sự exploratory, không phải đường chính của governance. Nếu thêm JSONB thì phải nói rõ không được dùng để né chuẩn hóa.

E. Rủi ro + Vi phạm HP

E15 — Vi phạm NT nào? Đánh giá: Dự thảo không vi phạm nền tảng ở cấp ý tưởng, thậm chí còn chữa đúng bệnh của pilot và bám rất sát HP:

NT1: tạo 1 SSOT enrichment thay vì rải update trên nhiều entity.
NT2: approved gate + DOT sync + seed tự động.
NT4: thêm cột tương lai bằng metadata/schema, không sửa app code.
NT5: verify DOT + H11b scan master.
NT10: FK chuẩn hóa, chống text tự do.
NT12: sync + verify theo cặp.
NT13: PG-first, PG-native, PG-driven.

Tuy nhiên hiện có 2 điểm suýt vi phạm nếu giữ nguyên:

Trigger approved reset quá rộng → có thể làm hệ thống tự tạo drift giả, đụng NT9/NT14.
Lưu composition_level + governance_role dạng text mà không khóa nguồn gốc → tạo 2 nguồn sự thật, đụng NT1.

E16 — Rủi ro lớn nhất nếu triển khai / không triển khai? Nếu triển khai:

Rủi ro lớn nhất là thiết kế gate chưa chặt: approved reset sai phạm vi, audit duyệt yếu, drift giữa master và mirror. Đây là rủi ro kỹ thuật sửa được bằng patch.

Nếu không triển khai:

Tiếp tục mô hình hiện trạng sẽ giữ nguyên 3 bệnh gốc: AI ghi trực tiếp không duyệt, text tự do không chuẩn hóa, không có toàn cảnh để vận hành ở scale 57K→500K. Đây là rủi ro kiến trúc lớn hơn nhiều và sẽ tiếp tục tạo dữ liệu sai khó sửa hàng loạt.

PATCHES ĐỀ XUẤT

P1 — Sửa trigger approved gate theo field-level diff Chỉ reset approved='no' khi thay đổi các field nghiệp vụ cần review lại: description, jurisdiction, enrichment_notes, provenance (nếu coi provenance là nội dung duyệt). Không reset khi chỉ đổi approved, approved_at, approved_by, synced_at, updated_at, _dot_origin.

P2 — Bổ sung audit duyệt tối thiểu Thêm approved_at TIMESTAMPTZ, approved_by TEXT (hoặc FK tới cơ chế approval Đ32 nếu có path rõ). approved='yes' mà không có dấu vết người/cơ chế duyệt là chưa đủ mạnh cho governance.

P3 — Giảm drift do field suy ra được Không cho nhập tay governance_role và composition_level. Một trong 2 hướng:

bỏ 2 cột khỏi master, derive lúc query/join; hoặc
giữ như snapshot nhưng chỉ seed/refresh bằng trigger, cấm update trực tiếp và nêu rõ “cache field, không phải SSOT”.

P4 — Ràng buộc source_table với collection_registry Nếu collection_registry.collection_name đủ điều kiện unique/FK thì nối FK trực tiếp. Nếu không, thêm trigger/check verify source_table phải tồn tại trong collection_registry. Đây là neo quản trị quan trọng theo Đ36.

P5 — Tách hợp đồng field master-owned khi DOT sync Viết rõ DOT chỉ được mirror xuống các field nào của entity gốc: tối thiểu description và provenance label. Không được mở rộng ngầm sang mọi cột entity khác nếu chưa amend luật tương ứng.

P6 — Thêm issue/check code riêng cho master governance Trong amend Đ22, tách ít nhất 2 check riêng:

HC-ENRICH-MISSING-ROW: entity có nhưng master thiếu row → CRITICAL
HC-ENRICH-DRIFT: approved yes nhưng mirror lệch/sync trễ → WARNING/CRITICAL theo ngưỡng
HC-ENRICH-STALE-REVIEW: approved no quá N ngày → WARNING Tách mã check giúp auto-close/reopen đúng theo Đ22 §1.1.

P7 — Ghi rõ scope enrichment theo Đ3 §2.5 Draft đang nói “TẤT CẢ entity”, nhưng Đ3 §2.5 phân biệt thực thể kiến trúc với bản ghi vận hành. Cần patch câu chữ: mọi entity đều có row master để quản trị tối thiểu, nhưng không phải mọi entity đều nằm trong scope enrichment chi tiết của AI. Những species bị exclude phải đọc từ config tương tự H11b để không xung đột Đ3 hiện hành.

P8 — Chỉ số/index phase 1 phải ban hành ngay NT14 yêu cầu thực thi được ngay; vì vậy draft nên ghi cụ thể index tối thiểu thay vì nói chung chung. Nếu không, team triển khai sẽ phải tự đoán.

NHẬN XÉT TỔNG THỂ

Đây là một đổi kiến trúc đúng hướng và nên làm. Nó xử lý đúng bệnh gốc của pilot thất bại: tách nơi AI/người viết enrichment khỏi entity runtime, đưa governance về PG table chuẩn hóa, có approved gate, có DOT sync cặp, có seed từ birth và có khả năng quét toàn cục. Về tinh thần, draft khớp mạnh với HP NT1/NT2/NT10/NT12/NT13 hơn phương án “AI viết trực tiếp lên entity”.

Điểm khiến tôi chưa approve final ngay không nằm ở triết lý, mà nằm ở độ chặt của cơ chế thực thi: trigger approved hiện còn lỗi logic; audit duyệt còn mỏng; vài cột đang có nguy cơ thành bản sao SSOT khác. Nếu áp 8 patch trên, đặc biệt P1/P2/P3/P7, tôi đánh giá bản này có thể lên mức APPROVE FINAL ở vòng 2.