KB-4D5F
Phụ lục 02C3 Điều 38 — Metadata Governance (PASS)
18 min read Revision 1
dieu38tacphu-luc-02metadata-governancebuoc-c3pass
Metadata Governance
Phụ lục 02C3 Điều 38
Trạng thái: PASS — GPT review + 7 chỉnh, User duyệt Phạm vi: Document envelope + Text unit + Component + Relation. 4 loại object, 1 bộ quy tắc thống nhất. Không làm: Chưa đặt tên bảng/cột, chưa pseudo-SQL, chưa DOT list, chưa migration. Không lặp lại: 02C1 (cây unit), 02C2 (catalog component). 02C3 chỉ nói metadata governance xuyên suốt. Câu hỏi cốt lõi: "Field nào bắt buộc, ai điền, khi nào điền, máy tự điền gì, kiểm tra chất lượng bằng gì?"
1. Core schema vs Profile — 2 tầng metadata
| Tầng | Vai trò | Áp cho ai | Thay đổi thế nào |
|---|---|---|---|
| Core schema | Bộ fields bắt buộc chung, mọi object đều phải có, không ngoại lệ | 4 loại object | Thay đổi core schema = phải đi qua amend path hợp pháp theo hệ thống luật hiện hành; không xử lý như config change. |
| Profile | Bộ fields bổ sung theo loại object/doc family. Không phá core, chỉ thêm. | Từng loại VB, từng loại component, từng loại relation | Thêm profile mới = INSERT config. Không sửa schema lõi (NT4). |
Tại sao 2 tầng?
- 1 tầng duy nhất → schema cứng, không mở rộng.
- Quá nhiều tầng → phức tạp, khó validate, khó enforce.
- 2 tầng = vừa đủ: core giữ kỷ luật chung, profile cho phép linh hoạt theo ngữ cảnh.
2. Core metadata framework — bắt buộc mọi object
2.1 Core bắt buộc thật sự cho mọi object (4/4 loại)
Mọi object trong hệ thống, bất kể loại, đều phải có tối thiểu 4 nhóm thông tin:
| Nhóm | Mô tả | Thể hiện cụ thể |
|---|---|---|
| Identifier | Định danh duy nhất toàn hệ thống | code (document, component), address (unit), edge_id (relation) |
| Status / Validity | Trạng thái hiện hành | lifecycle status, governance status, valid_time |
| Timestamps | Khi nào tạo, khi nào sửa | created_at, updated_at |
| Classification | Thuộc loại gì | doc_type, section_type, component_type, edge_type |
2.2 Core-equivalent theo từng object family
Ngoài 4 nhóm chung, mỗi loại object có thêm core fields đặc thù — bắt buộc cho loại đó nhưng không áp cứng cho loại khác:
| Loại object | Core-equivalent fields | Ghi chú |
|---|---|---|
| Document envelope | name, owner, version, description, doc_type (FK config), article_number, enacted_at, council_score, kb_path | Đã có trong normative_registry |
| Text unit | title, owner, version, description, doc_code (FK document), parent (FK self), sort_order, body, body_hash (GENERATED), section_code, tier | 02C1 đã chốt |
| Component | name, owner, version, description (spec_summary), component_type, interface (in/out), lifecycle_status, governance_status, base_component (nếu variant) | 02C2 đã chốt |
| Relation | source, target, edge_type, confidence, provenance, status | Không có title/owner/version theo nghĩa thông thường — provenance + valid_time thay vai trò tương đương |
Về description: Description thuộc core governance expectation. Mức bắt buộc cụ thể theo object type và legal coverage tương ứng — document, unit, component: bắt buộc (Description Governance Fix 27-28 đã proven). Relation: không bắt buộc (provenance + edge_type đã đủ ngữ nghĩa). Object kỹ thuật nhỏ: theo config, tránh bắt tuyệt đối quá sớm (bài học Đ43).
3. Profile — bổ sung theo loại, không phá core
3.1 Profile cho document envelope (theo doc_type)
| Doc family | Ví dụ profile fields |
|---|---|
| Luật (law) | legal_effect, normative_type, amendment_chain |
| Chính sách (policy) | effective_date, review_cycle, applicable_scope, target_audience |
| SOP | actor, department, expected_frequency, compliance_level |
| Hướng dẫn (guide) | skill_level, prerequisite_docs |
3.2 Profile cho text unit (theo section_type hoặc doc_family)
| Ngữ cảnh | Ví dụ profile fields |
|---|---|
| Unit loại "guard" trong luật | trigger_event, reject_condition, error_message |
| Unit loại "formula" | binding_codes, data_source, refresh_frequency |
| Unit loại "procedure" trong SOP | actor, tool, expected_duration, precondition |
3.3 Profile cho component (theo component_type)
| Component type | Ví dụ profile fields |
|---|---|
| Pattern | applicable_problem_types, proven_at |
| Guard | trigger_timing, severity |
| Config rule | config_table_ref, validation_type |
3.4 Profile cho relation (theo edge_type)
| Edge type | Ví dụ profile fields |
|---|---|
| 'implements' | implementation_completeness, test_coverage |
| 'amends' | amendment_scope, breaking_change |
| 'depends_on' | dependency_strength, fallback_available |
3.5 Nguyên tắc quản profile
| Quy tắc | Giải thích |
|---|---|
| Profile schema = config, không phải code | Thêm profile mới = INSERT config row. Không sửa PG schema. (NT4) |
| Profile schema phân biệt required vs optional | Required profile fields → birth gate reject nếu thiếu. Optional profile fields → DOT daily nhắc nếu thiếu, không reject. |
| Mỗi field trong profile phải justify "PG không tự biết" | Chống khai thừa (NT11). |
| Agent không tự sáng tác profile field | Phải nằm trong config đã đăng ký. Free-form = cấm (02A Câu 4). |
| Profile validate bởi DOT/birth gate | Required → birth gate. Optional → DOT daily. |
4. Field responsibility — ai điền, khi nào, bằng gì?
4.1 Ma trận responsibility
| Loại fill | Ai làm | Khi nào | Ví dụ | Cơ chế |
|---|---|---|---|---|
| System auto | PG trigger / GENERATED column | Mỗi INSERT/UPDATE, tự động | body_hash, timestamps, valid_period, status transitions, doc_level | Trigger BEFORE INSERT/UPDATE, GENERATED ALWAYS AS |
| DOT derive | DOT chạy theo schedule hoặc event | Sau INSERT, daily, hoặc khi event trigger | binding validation, drift detection, stale check, vector sync flag. Các field dẫn xuất áp dụng theo từng object type (không phải mọi field derive áp cho mọi object). | DOT paired (writer derive + checker verify) |
| Agent manual | Agent khi tạo/sửa object | Birth (INSERT) hoặc amend (UPDATE draft) | owner, doc_code, parent, section_type, title, body, spec_summary, component_type | Birth gate validate bắt buộc |
| Agent assisted | Agent fill, system gợi ý | Birth hoặc sửa, có suggest | pattern_refs, binding_type | Tương lai: fn_reuse_search, KG recommend |
Về tier (text unit): Tier là khái niệm cấu trúc (atom/molecule/compound theo Đ0-B) nên quản theo nguyên tắc derived-first — DOT/system tính từ parent chain + composition. Agent chỉ đề xuất giá trị ban đầu nếu luật cho phép; DOT/checker mới là nơi xác nhận cuối cùng. Hạn chế manual để tránh điền sai.
4.2 Ma trận cho từng loại object
Document envelope:
| Field | Fill type | Birth gate validate? |
|---|---|---|
| code | Agent manual | ✅ unique, format |
| name | Agent manual | ✅ NOT NULL |
| doc_type | Agent manual | ✅ FK config |
| doc_level | System auto (trigger từ doc_type config) | — |
| version | System auto | — |
| status | System auto (lifecycle trigger) | — |
| enacted_at | System auto (khi status→enacted) | — |
| content_hash | System auto (GENERATED) | — |
| owner | Agent manual | ✅ NOT NULL |
| description | System auto + Agent (Description Governance pattern) | ✅ NOT NULL |
| Required profile fields | Agent manual | ✅ |
| Optional profile fields | Agent manual | — (DOT nhắc nếu thiếu) |
Text unit:
| Field | Fill type | Birth gate validate? |
|---|---|---|
| address | System auto hoặc Agent | ✅ unique, format |
| doc_code | Agent manual | ✅ FK document |
| parent | Agent manual | ✅ FK self, cùng document |
| sort_order | Agent manual | ✅ NOT NULL |
| title | Agent manual | ✅ (tùy section_type) |
| body | Agent manual | ✅ NOT NULL |
| body_hash | System auto (GENERATED) | — |
| section_type | Agent manual | ✅ FK controlled vocabulary |
| section_code | Agent manual | ✅ |
| owner | Agent manual | ✅ NOT NULL |
| status | System auto | — |
| version | System auto | — |
| tier | Derived-first (DOT/system tính); Agent đề xuất ban đầu | — (xác nhận bởi DOT) |
| vector_synced_at | System auto (sau body change) | — |
| description | System auto + Agent | ✅ NOT NULL |
| Required profile fields | Agent manual | ✅ |
| Optional profile fields | Agent manual | — (DOT nhắc) |
Component:
| Field | Fill type | Birth gate validate? |
|---|---|---|
| code | Agent manual | ✅ unique, format |
| name | Agent manual | ✅ NOT NULL |
| component_type | Agent manual | ✅ FK controlled vocabulary |
| spec_summary | Agent manual | ✅ NOT NULL |
| interface (in/out) | Agent manual | ✅ cấu trúc hợp lệ |
| lifecycle_status | System auto (default draft) | — |
| governance_status | Agent manual (default experimental) | — |
| owner | Agent manual | ✅ NOT NULL |
| version | System auto | — |
| base_component | Agent manual (nếu variant) | ✅ FK exists nếu có |
| pg_object_refs | Agent manual | — (optional, chỉ trỏ) |
| reuse_decision_ref | System auto (birth gate kiểm) | ✅ phải có record |
| description | System auto + Agent | ✅ NOT NULL |
| Required profile fields | Agent manual | ✅ |
| Optional profile fields | Agent manual | — (DOT nhắc) |
Relation:
| Field | Fill type | Birth gate validate? |
|---|---|---|
| source | Agent manual hoặc DOT auto-extract | ✅ FK exists |
| target | Agent manual hoặc DOT auto-extract | ✅ FK exists |
| edge_type | Agent manual hoặc DOT classify | ✅ FK controlled vocabulary |
| confidence | Agent manual (1.0) hoặc DOT (< 1.0) | ✅ range 0-1 |
| provenance | System auto + Agent | ✅ NOT NULL |
| valid_time | Agent manual (nếu temporal) | — |
| status | System auto (default active) | — |
| Profile fields | Agent manual hoặc DOT | — (optional) |
5. Completeness vs Correctness vs Consistency — 3 tầng kiểm tra
Bài học Fix 27-28: Completeness ≠ correctness. Có field là chưa đủ — field phải đúng.
| Tầng | Mô tả | Khi nào | Ai kiểm | Ví dụ |
|---|---|---|---|---|
| Completeness (đủ field) | Core fields + required profile fields phải NOT NULL / có giá trị hợp lệ | Birth gate — lúc INSERT | PG trigger BEFORE INSERT | owner NULL → reject. section_type không thuộc vocabulary → reject. Required profile field thiếu → reject. |
| Correctness (đúng logic) | Giá trị field phải đúng ngữ nghĩa, đúng business rule | DOT daily — sau INSERT | DOT paired (checker) | parent trỏ unit khác document → sai. binding_codes trỏ binding không tồn tại → sai. |
| Consistency (nhất quán chéo) | Metadata giữa các object liên quan phải nhất quán | DOT daily/weekly | DOT paired (checker) | Document enacted nhưng unit con draft → sai. BOM version ≠ component version thực → mismatch. |
5.1 Birth gate validate gì? (completeness — chặn rác vào PG)
| Object | Birth gate kiểm |
|---|---|
| Document envelope | code unique, name NOT NULL, doc_type FK valid, owner NOT NULL, description NOT NULL, required profile fields |
| Text unit | address unique, doc_code FK valid, parent FK valid + cùng document, body NOT NULL, section_type FK valid, owner NOT NULL, description NOT NULL, required profile fields |
| Component | code unique, name NOT NULL, component_type FK valid, spec_summary NOT NULL, owner NOT NULL, reuse_decision_ref exists, description NOT NULL, required profile fields |
| Relation | source FK exists, target FK exists, edge_type FK valid, confidence range 0-1, provenance NOT NULL |
5.2 DOT daily kiểm gì? (correctness + consistency + optional enrichment)
| Kiểm tra | Mô tả | Phát hiện → hành động |
|---|---|---|
| Orphan unit | Text unit mà doc_code trỏ document không tồn tại/retired | → system_issues CRITICAL |
| Binding drift | Bound value ≠ giá trị thực trong PG source | → WARNING + auto-fix nếu draft |
| Ref gãy | Relation target đã retired/deleted | → WARNING |
| BOM mismatch | Component version trong BOM ≠ version thực | → WARNING |
| Optional profile enrichment | Object có đủ core + required profile nhưng thiếu optional profile fields | → INFO (nhắc fill, không reject) |
| Status inconsistency | Document enacted nhưng unit con vẫn draft | → WARNING |
| Component stale | Component deprecated > 90 ngày chưa retire | → INFO |
| Vector stale | Text unit body thay đổi nhưng vector_synced_at chưa update | → queue re-vector |
| Tier verify | Tier do agent đề xuất ≠ tier DOT tính từ parent chain | → WARNING + suggest correct tier |
6. Reuse pattern từ Đ43 và các luật đã proven
02C0 đã chốt: tái sử dụng có chọn lọc, không nguyên trạng. Mục này ghi rõ pattern nào lấy, phần nào lấy.
| Pattern đã proven | Nguồn | Reuse cho metadata governance thế nào |
|---|---|---|
| Birth gate + dual trigger | Đ0-G, Fix 27-28 Description Governance | Áp cho mọi object type — birth gate validate completeness, paired DOT kiểm correctness. Mở rộng từ 1 field (description) sang toàn bộ core + profile. |
| Config-driven sections | Đ43 context pack (dot_config) | Profile schema = config table. Thêm profile = INSERT config, không sửa schema. Giống cách Đ43 dùng dot_config cho section list/thresholds. |
| Checksum detect change | Đ43 (logical_checksum + file_checksum) | body_hash GENERATED column trên text unit — pattern đã proven ở normative_registry.content_hash. |
| Self-healing loop | Fix 26 (fn_log_issue → auto-fix → re-check → fallback) | DOT phát hiện correctness/consistency sai → log issue → auto-fix nếu draft + rule cho phép → re-check → escalate nếu không fix được. Cùng pattern, khác scope. |
| 2-phase publish | Đ43 (staging → validate → promote → compensate) | Lifecycle transitions (draft → enacted) nên validate trước promote — staging check metadata completeness trước khi chính thức enacted. Pattern tương tự. |
| Pivot count (đếm từ data, không hardcode) | Đ26, Đ43 | Derived metadata fields (tier, binding validation, species count) = tính từ PG data runtime, không hardcode. Cùng tinh thần pivot_count(). |
Không reuse nguyên trạng: Description Governance Fix 27-28 thiết kế cho 1 field duy nhất (description) trên 21 tables. Metadata governance cho text unit + component = nhiều fields + profile + cross-object consistency → mở rộng pattern, không copy code.
7. Tóm tắt — metadata governance hoạt động thế nào?
Agent tạo object
→ Birth gate kiểm completeness (core + required profile)
→ PASS → vào PG
→ FAIL → reject, nêu rõ thiếu gì
Object sống trong PG
→ System auto fill: timestamps, hash, status transitions
→ DOT derive: các field dẫn xuất áp dụng theo từng object type
→ DOT daily kiểm correctness + consistency
→ Đúng → im lặng
→ Sai → system_issues (severity theo loại)
→ Auto-fix nếu draft + rule cho phép (self-healing pattern)
→ Cảnh báo + escalate nếu enacted hoặc không fix được
Metadata luôn đúng vì:
① Birth gate chặn rác vào (completeness)
② System auto fill cái máy biết
③ DOT derive cái cần tính (theo từng object type)
④ DOT daily kiểm cái có thể sai theo thời gian (correctness + consistency)
⑤ Agent chỉ xử lý ngoại lệ
Nguyên tắc xuyên suốt:
- Metadata governance áp đồng đều cho 4 loại object. Không có loại nào được miễn.
- Core schema thay đổi = amend path hợp pháp (hiếm). Profile thay đổi = INSERT config (linh hoạt).
- Agent không tự sáng tác field. Mọi field phải nằm trong core hoặc profile đã đăng ký.
- Completeness kiểm lúc birth (required = reject). Correctness kiểm daily. Consistency kiểm cross-object. Optional enrichment = DOT nhắc, không reject.
- Tận dụng pattern đã proven từ Đ43, Fix 26, Fix 27-28 — mở rộng, không viết lại từ đầu.
Ranh giới 02C3: File này chốt quy tắc metadata governance ở mức concept. Chi tiết schema cụ thể (tên cột, kiểu dữ liệu, constraint), DOT list, trigger implementation, migration → bước thiết kế sau khi phụ lục metadata governance (02C0 BLOCKER) hoàn tất. File này không đủ căn cứ để triển khai kỹ thuật — là concept model phục vụ soạn luật.
Bảng tổng kết hiệu chỉnh
| # | Đã sửa gì | Vì sao sửa |
|---|---|---|
| 1 | "amend luật (Đ32)" → "amend path hợp pháp" | Đ32 là approval, không phải framework amend |
| 2 | "core fields chung" → "core metadata framework", tách core 4/4 + core-equivalent theo family | Relation không fit khuôn document/unit/component |
| 3 | Description = core expectation, mức bắt buộc theo object type/legal coverage | Bài học Đ43, tránh bắt tuyệt đối quá sớm |
| 4 | Profile: tách required (birth reject) vs optional (DOT nhắc) | Sửa mâu thuẫn logic giữa mục 3.5 và 5.2 |
| 5 | Tier = derived-first, DOT/system xác nhận, agent chỉ đề xuất | Tier là cấu trúc, hạn chế manual |
| 6 | Flow cuối: "DOT derive field theo từng object type" | Không liệt kê species/tier như áp cho mọi object |
| 7 | Thêm mục 6: Reuse pattern từ Đ43/Fix 26-28 | User yêu cầu + 02C0 đã chốt reuse có chọn lọc |
3 lưu ý GPT cho bước schema sau (không sửa ở 02C3):
- Relation: chốt rõ "lifecycle riêng" hay chỉ "validity/status" ở schema phase
- Description: giữ đúng "core governance expectation" — không bắt cứng tuyệt đối
- Reuse Đ43: giữ đúng "mở rộng pattern, không copy code" — không làm mềm đi
PASS | 02C3 Metadata Governance | 7 mục, 4 loại object, concept only | GPT review + 7 chỉnh | User duyệt