Phụ lục 02C1 Điều 38 — Text Unit Catalog Model
Text Unit Catalog Model
Phụ lục 02C1 Điều 38
Trạng thái: DỰ THẢO v1.1 — GPT review + 6 chỉnh áp dụng, chờ User duyệt Mục đích: Chốt mô hình quản trị miếng thông tin TRƯỚC khi nói schema. Không làm: Chưa đặt tên bảng, chưa pseudo-SQL, chưa index/constraint, chưa migration. Câu hỏi cốt lõi: "Catalog quản miếng thông tin của Incomex sẽ quản cái gì, theo lớp nào, và không loạn khi vào tầng sâu?"
1. "Miếng thông tin" là gì?
Một text unit là đơn vị thông tin nhỏ nhất được quản lý độc lập trong PG — có thể sửa riêng, review riêng, version riêng, vector riêng mà không đụng các đơn vị khác.
Ví dụ nôm na: Một cuốn sách = 1 văn bản. Mỗi nút nội dung cần quản riêng = 1 unit. Unit không đồng nghĩa cứng với cấp mục lục — unit là đơn vị quản trị độc lập, đủ nhỏ để sửa/review/version riêng. Một "chương" lớn có thể chứa nhiều units con, không nhất thiết bản thân chương là 1 unit vật lý duy nhất.
Ví dụ cụ thể Incomex: Đ43 (Luật Bản đồ Hệ thống) hiện là 1 file 45KB. Sau khi atomize:
Đ43 (document envelope)
├── §0 Tầm nhìn (unit — text, ~2KB)
├── §1 Phạm vi (unit — text)
├── §2 Kiến trúc (unit — text + formula)
│ ├── §2.1 Stack (unit con)
│ ├── §2.2 Context Pack (unit con)
│ │ ├── §2.2.1 Sections (unit cháu)
│ │ └── §2.2.2 Config (unit cháu — config type)
│ └── §2.3 Publish flow (unit con)
├── §3 DOT (unit — dot_ref type)
...
Mỗi unit: < 2KB, có địa chỉ riêng, sửa riêng, vector riêng.
2. Văn bản mẹ chứa miếng con như thế nào?
2 lớp rõ ràng:
| Lớp | Vai trò | Ví dụ |
|---|---|---|
| Document envelope | Bao bì — chứa metadata tổng của văn bản (tên, loại, version, lifecycle, council score, author, enacted date). KHÔNG chứa nội dung chi tiết. | normative_registry row cho "Đ43" |
| Text units | Nội dung — mỗi unit là 1 miếng thông tin thuộc document đó. Nhiều units tạo thành cây nội dung. | Các row unit cho §0, §1, §2, §2.1, §2.2... |
Quan hệ: Document envelope sở hữu (owns) tập hợp text units. Mỗi unit biết mình thuộc document nào. Document không chứa nội dung inline — nội dung sống trong units.
Tương tự DITA: Document envelope = DITA map. Text unit = DITA topic. Map liệt kê topics, không chứa nội dung.
3. Cây nhiều tầng — mẹ, con, cháu, chắt
3.1 Cấu trúc cây
Mỗi unit có thể có 1 unit cha (parent). Parent = NULL nghĩa là unit nằm ở tầng cao nhất (root) của document.
Root level (parent = NULL): §0, §1, §2, §3...
Tầng 2 (parent = §2): §2.1, §2.2, §2.3
Tầng 3 (parent = §2.2): §2.2.1, §2.2.2
Tầng 4 (parent = §2.2.1): §2.2.1a, §2.2.1b
Không giới hạn số tầng. Thực tế Incomex hiện tại: luật sâu nhất ~4 tầng. Chính sách/SOP có thể 5-6 tầng. PG recursive query xử lý thoải mái.
3.2 Quy tắc cây
| Quy tắc | Giải thích |
|---|---|
| Mỗi unit chỉ có 1 parent | Không đa cha. Cây thuần, không phải DAG. |
| Parent phải cùng document | Unit con phải thuộc cùng document envelope với parent. Không "nhúng" unit từ document khác vào cây cấu trúc (đó là ref chéo, không phải cấu trúc). Nếu cần dùng lại nội dung từ document khác, phải làm bằng tham chiếu / assembly logic / component reuse (02C2), không làm bằng cách đưa unit ngoài vào làm child trực tiếp. |
| Thứ tự con xác định bởi sort_order | Các unit cùng cấp có thứ tự rõ ràng (1, 2, 3...). |
| Xóa parent → con phải xử lý | Không để con mồ côi. Xóa/retire parent → cảnh báo hoặc cascade. |
3.3 Tại sao cây thuần, không phải graph?
Cấu trúc dọc (parent-child trong cùng document) phải là cây thuần — vì cây phản ánh cấu trúc trình bày vật lý của văn bản: chương → mục → khoản → điểm. Đây là thứ tự đọc.
Quan hệ ngang (unit này tham chiếu unit khác, kể cả khác document) là graph — quản bằng edges, không phải parent-child. Chi tiết ở mục 5.
4. Quan hệ cấu trúc (dọc) vs quan hệ tham chiếu (ngang)
Phân biệt rõ ràng 2 loại quan hệ — đây là điểm cốt lõi tránh loạn:
| Quan hệ cấu trúc (dọc) | Quan hệ tham chiếu (ngang) | |
|---|---|---|
| Bản chất | Cha-con trong cùng cây văn bản | Liên kết giữa 2 units bất kỳ (có thể khác document) |
| Ví dụ | §2.2 chứa §2.2.1, §2.2.2 | §2.2.1 của Đ43 tham chiếu §4.1 của Đ35 |
| Cơ chế quản lý | Parent-child pointer trên unit | Edge trong universal_edges |
| Cardinality | 1 parent : N children (cây) | M:N (graph) |
| Scope | Trong cùng 1 document | Xuyên document, xuyên loại VB |
| Khi unit bị xóa/retire | Con phải xử lý (cascade/cảnh báo) | Ref gãy = cảnh báo (không cascade nội dung) |
| Tương tự ngành | DITA: topic nằm trong map | CMDB: CI depends-on CI khác |
Quy tắc vàng: Quan hệ dọc KHÔNG bao giờ chạy qua universal_edges. Quan hệ ngang KHÔNG bao giờ dùng parent-child pointer. 2 kênh tách biệt, không trộn.
5. Metadata ở 3 cấp
5.1 Cấp Document (document envelope)
Metadata tổng của văn bản — đã có trong normative_registry:
| Metadata | Ví dụ | Ai quản |
|---|---|---|
| Tên, mã (code) | "Đ43", "Luật Bản đồ Hệ thống" | Agent lúc tạo |
| Loại VB (doc_type) | 'law', 'policy', 'sop' | Config table |
| Version tổng | "v1.2" | System auto |
| Lifecycle status | 'enacted' | Trigger lifecycle |
| Council score | 9.5 | Council input |
| Enacted date/session | 2026-04-17, S178 | Agent/system |
| Owner/department | — | Agent lúc tạo |
Cấp document KHÔNG chứa nội dung. Chỉ metadata bao bì.
5.2 Cấp Unit (mỗi miếng thông tin)
Core metadata — bắt buộc mọi unit, mọi loại VB:
| Metadata | Mô tả | Ai fill | Khi nào |
|---|---|---|---|
| Địa chỉ (address) | Mã duy nhất trong hệ thống, VD: 'D43-S2-P2-1' | System auto hoặc Agent | Birth |
| Section code | Mã đọc được, VD: '§2.2.1' | Agent | Birth |
| Title | Tiêu đề ngắn | Agent | Birth |
| Body | Nội dung text | Agent | Birth + sửa |
| Body hash | Fingerprint nội dung, detect sửa lén | System auto (GENERATED) | Auto |
| Owner | Ai sở hữu | Agent | Birth |
| Status | draft/review/enacted/amended/retired/superseded | System auto (trigger) | Lifecycle events |
| Version | Version riêng của unit | System auto | Khi enacted/amend |
| Review state | pending/approved/rejected/needs_change | Agent/reviewer | Review events |
| Section type | text/formula/condition/definition/guard/config... | Agent | Birth |
| Parent | Trỏ unit cha (NULL = root) | Agent | Birth |
| Document | Trỏ document envelope | Agent | Birth |
| Sort order | Thứ tự trong cùng cấp | Agent | Birth + sửa |
| Tier | atom/molecule/compound (Đ0-B) | Agent hoặc DOT derive | Birth + derive |
| Created/updated timestamps | — | System auto | Auto |
| Vector sync tracking | Biết unit đã vector chưa, khi nào | System auto | Sau body change |
Profile metadata — bổ sung theo loại VB (không phá core):
| Loại VB | Ví dụ profile fields |
|---|---|
| Luật | legal_effect, normative_type (imperative/declarative), amendment_relation |
| Chính sách | effective_date, review_cycle, applicable_scope |
| SOP | actor, tool, expected_duration, precondition |
| Workflow step | input, output, next_step, error_handler |
Profile fields lưu riêng (không trộn vào core). Mỗi loại VB có profile schema riêng — được định nghĩa trong config, validate bởi DOT/birth gate.
5.3 Cấp Relation (metadata trên edges)
Quan hệ ngang (unit↔unit, unit↔code, unit↔entity) cần metadata riêng:
| Metadata | Mô tả |
|---|---|
| Edge type | 'references', 'implements', 'depends_on', 'amends', 'supersedes' |
| Confidence | Mức tin cậy (1.0 = chắc chắn, do agent ghi; 0.7 = auto-extract) |
| Provenance | Nguồn gốc edge (ai tạo, từ đâu, khi nào) — Đ39 A8 |
| Valid time | Edge có hiệu lực từ-đến (temporal) — Đ39 C11 |
| Status | Relation cũng là đối tượng cần lifecycle/validity: active, superseded, broken-risk, retired-reference. Taxonomy chi tiết chốt ở bước sau. |
Relation metadata nằm trên universal_edges (đã có), không tạo cơ chế mới.
6. Unit ở tầng sâu — address, review, version, reference
Đây là câu hỏi khó nhất. Trả lời rõ:
6.1 Address (địa chỉ)
Pattern addressing hierarchical — học từ Akoma Ntoso:
{doc_code}-{section_path}
Ví dụ:
D43-S0= Đ43, §0 (tầng 1)D43-S2= Đ43, §2 (tầng 1)D43-S2-P2= Đ43, §2, mục 2 (tầng 2)D43-S2-P2-1= Đ43, §2, mục 2, khoản 1 (tầng 3)D43-S2-P2-1a= Đ43, §2, mục 2, khoản 1, điểm a (tầng 4)
Quy tắc:
- Address là bất biến (immutable) sau khi tạo. Đổi nội dung = tạo version mới, giữ address.
- Address là unique toàn hệ thống — không chỉ unique trong document.
- Address kết hợp doc_code + section path → luôn biết unit thuộc document nào.
- Section code (§2.2.1) là human-readable alias, có thể đổi. Address là ID kỹ thuật, không đổi.
6.2 Review ở tầng sâu
Nguyên tắc: review đi theo unit, không theo tầng.
- Council/reviewer vote trên đúng unit cần review — dù ở tầng nào.
- Review unit cha KHÔNG tự động approve unit con. Mỗi unit review độc lập.
- Khi cần review "cả mục §2.2" → review từng unit con (§2.2.1, §2.2.2) + unit cha (§2.2).
- Cơ chế tổng hợp từ unit review lên document approval là bài toán governance sẽ được chốt cùng Đ32 clarify; 02C1 chỉ chốt nguyên tắc rằng review gắn vào unit, còn aggregate rule không mặc định tự suy ra.
6.3 Version ở tầng sâu
Nguyên tắc: version đi theo unit, document version là summary.
- Mỗi unit có version riêng (1.0, 1.1, 2.0...).
- Sửa unit con KHÔNG tự động bump version cha. Cha version bump khi cấu trúc cha thay đổi (thêm/xóa/đổi thứ tự con).
- Document version = summary (VD: "v1.2 — amend §2.2.1 + §3.1"). Bump khi có change-set enacted.
- Unit đã enacted → bất biến (QĐ1). Sửa = tạo unit version mới. Unit cũ giữ nguyên (superseded).
- Change-set: Nhiều thay đổi ở nhiều unit có thể được nhóm vào một change-set để phục vụ review chung, approve chung, và bump version ở cấp document. Chi tiết change-set thuộc bước governance sau.
6.4 Reference ở tầng sâu
Nguyên tắc: reference trỏ đến address, không trỏ đến nội dung.
- "§2.2.1 của Đ43 tham chiếu §4.1 của Đ35" → edge: source=D43-S2-P2-1, target=D35-S4-P1, type='references'.
- Ref sâu = ref bình thường. Address đảm bảo trỏ đúng unit dù ở tầng nào.
- Ref gãy: target unit retire → edge vẫn tồn tại nhưng target status = retired → DOT phát hiện → system_issues.
7. Tóm tắt — không loạn khi vào tầng sâu
| Câu hỏi | Trả lời |
|---|---|
| Tầng sâu có gì khác tầng nông? | Không khác. Mọi unit cùng cấu trúc, cùng core metadata, cùng quy tắc. Tầng sâu chỉ có parent ≠ NULL. |
| Address có loạn không? | Không. Address = doc_code + section path. Dù sâu mấy tầng, address luôn duy nhất + readable. |
| Review có loạn không? | Không. Review theo unit, không theo tầng. Unit nào cần review thì review unit đó. Aggregate lên document = bài toán Đ32 clarify. |
| Version có loạn không? | Không. Version theo unit. Sửa con không bump cha. Document version = summary. Change-set nhóm nhiều unit change. |
| Ref chéo có loạn không? | Không. Ref trỏ đến address. Address bất biến. Ref gãy tự phát hiện bởi DOT. |
| Core metadata có bị thay đổi theo tầng không? | Không. Core metadata giống nhau mọi tầng. Profile metadata có thể khác theo doc_type nhưng không theo tầng. |
Nguyên tắc thiết kế then chốt: Mọi unit bình đẳng về cấu trúc. Tầng sâu ≠ phức tạp hơn. Tầng chỉ là vị trí trong cây — không ảnh hưởng cách quản lý, cách review, cách version, cách reference.
Ranh giới 02C1: File này chỉ chốt mô hình catalog và ranh giới quản trị. Chi tiết core schema, profile schema, field responsibility, validation matrix sẽ được đào sâu ở 02C2 (Metadata Governance) hoặc bước tương ứng. 02C1 nói metadata ở mức "cần gì, ai fill" — chưa chốt "schema cụ thể ra sao".
DỰ THẢO v1.1 | 02C1 Text Unit Catalog Model | 7 mục, concept only, no schema | GPT review + 6 chỉnh áp dụng | Chờ User duyệt