L1 Phụ lục 03 Đ38 — Text Unit Governance
PHỤ LỤC ĐIỀU 38 — TEXT UNIT GOVERNANCE
Phụ lục 03 Điều 38 (Text Unit)
Trạng thái: DỰ THẢO — chờ Council review + User duyệt Loại: Phụ lục mới gắn vào Đ38 Concept gốc: 02C1 (Text Unit Catalog Model) Đóng blocker: 02D0 blocker "Đ38 chưa định nghĩa text unit" Che phủ hở: 02DX QĐ1 — "Đ38 chưa có text unit model"
§1. Mục đích
Luật hóa text unit là đơn vị quản trị thông tin nhỏ nhất 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.
Phụ lục này bổ sung Đ38 v3.0 §A1 (chia thẻ + metadata) bằng mô hình quản trị cụ thể, đưa Đ38 từ "document-centric" sang "unit-centric".
§2. Phạm vi
Áp dụng cho mọi văn bản quản trị thuộc scope Đ38: luật, chính sách, SOP, hướng dẫn, knowledge. Luật là pilot — nền tảng serve mọi loại.
§3. Định nghĩa
§3.1 Text unit
Đơn vị thông tin nhỏ nhất được quản lý độc lập trong PG. Mỗi unit có địa chỉ riêng (address), version riêng, review state riêng, vector riêng. Tương tự DITA topic.
§3.2 Document envelope
Bao bì của văn bản — chứa metadata tổng (tên, loại, version, lifecycle, council score, owner). KHÔNG chứa nội dung chi tiết. Nội dung sống trong text units. Tương tự DITA map.
Trong giai đoạn hiện hành, document envelope có thể được map/neo với normative_registry; thiết kế chi tiết xác định ở design phase.
§3.3 Quan hệ document ↔ unit
Document envelope sở hữu 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.
§3.4 Addressing scheme
Mỗi unit có address duy nhất toàn hệ thống, dạng: {doc_code}-{section_path} (VD: D43-S2-P2-1).
Quy tắc:
- Canonical address là định danh kỹ thuật unique toàn hệ thống, bất biến sau khi tạo. Đổi nội dung = tạo version mới, giữ address.
- Section code (§2.2.1) là human-readable alias, có thể đổi theo render hoặc cấu trúc đọc. Không dùng section code làm định danh kỹ thuật.
§3.5 Cây cấu trúc (quan hệ dọc)
Units tổ chức theo cây parent-child trong cùng document:
- Mỗi unit chỉ có 1 parent (cây thuần, không phải DAG).
- Parent phải cùng document. Không nhúng unit từ document khác vào cây (đó là tham chiếu ngang, không phải cấu trúc).
- Thứ tự con xác định bởi sort_order.
- Xóa/retire parent → con phải được xử lý (cảnh báo hoặc cascade).
- Không giới hạn số tầng. Thực tế Incomex: 4–6 tầng.
- Unit có thể xuất hiện trong nhiều rendered views, nhưng chỉ có một canonical parent trong cây cấu trúc của document gốc.
§3.6 Tham chiếu ngang (quan hệ ngang)
Liên kết giữa units bất kỳ (có thể khác document) — quản bằng universal_edges, KHÔNG bằng parent-child pointer.
Quy tắc phân tách: Quan hệ dọc KHÔNG chạy qua universal_edges. Quan hệ ngang KHÔNG dùng parent-child pointer. 2 kênh tách biệt.
§3.7 Lifecycle theo unit
Mỗi unit tối thiểu phải phân biệt được: draft / current (enacted) / superseded / retired. Tên trạng thái chi tiết tuân thủ Đ4 hoặc được chuẩn hóa ở design phase.
§3.8 Version theo unit
- Mỗi unit có version riêng.
- Unit đã enacted = bất biến (QĐ1, Đ4). Sửa = tạo version mới.
- Sửa unit con KHÔNG tự động bump version cha.
- Document version = summary (bump khi có change-set enacted).
§3.9 Change-set
Nhiều thay đổi ở nhiều units có thể được nhóm vào change-set để review chung, approve chung, bump document version. Chi tiết change-set governance: xem L5 (clarify Đ32).
§3.10 Species
text_unit phải được đăng ký như một species/loài quản trị theo Đ29 hoặc cơ chế tương đương hiện hành. Thao tác cụ thể xử lý ở L4/design.
§4. Nguyên tắc bắt buộc
| # | Nguyên tắc | Cơ sở |
|---|---|---|
| 1 | PG unit là SSOT. Mọi nội dung văn bản quản trị sống trong PG dưới dạng unit. File/KB = backup, không phải truth. | NT1, NT13, Phụ lục 01 |
| 2 | Enacted = bất biến. Unit đã enacted không sửa đè. Thay đổi qua version mới / change-set / amend path hợp pháp. | Đ4, QĐ1 |
| 3 | Address bất biến. Canonical address không đổi suốt vòng đời unit. Section code có thể đổi theo render. | 02C1 §6.1 |
| 4 | Cây dọc tách graph ngang. Parent-child = cấu trúc trình bày. Edges = tham chiếu ngữ nghĩa. Không trộn. | 02C1 §4 |
| 5 | Mọi unit bình đẳng về cấu trúc. Tầng sâu ≠ phức tạp hơn. Cùng core metadata, cùng quy tắc. | 02C1 §7 |
| 6 | Review gắn vào unit. Review unit cha KHÔNG tự động approve con. | QĐ6, 02C1 §6.2 |
| 7 | Vector = projection async. PG unit = gốc. Vector/Qdrant = bản chiếu phục vụ retrieval. | QĐ2, Phụ lục 01 nguyên tắc vector |
| 8 | Reuse pattern birth gate. Birth gate validate metadata completeness tại INSERT — nguyên lý từ Đ0-G/Fix 27-28, thiết kế mới theo scope unit (nhiều fields + profile). | 02DY |
| 9 | Hot path PG, enrichment async. Sửa unit = ghi PG, kiểm integrity ngay trong transaction. Latency budget cụ thể xác định ở design phase. Vector sync, KG enrichment = chạy sau. | QĐ5, Phụ lục 01 |
§5. Ranh giới — không làm gì trong phụ lục này
| Không làm | Lý do |
|---|---|
| Không định nghĩa component/BOM | Thuộc L2 |
| Không chốt metadata schema cụ thể (tên cột, kiểu dữ liệu) | Thuộc L3 + design phase |
| Không định nghĩa bảng cụ thể (text_units, text_unit_versions, text_unit_edges...) | Schema/tên bảng/cột thuộc design phase |
| Không chốt trigger/function/DOT list | Thuộc design + implementation phase |
| Không định nghĩa workflow engine/UI | Ngoài scope Đ38 ở giai đoạn này |
| Không migration plan chi tiết | Thuộc C7 sau khi design hoàn tất |
§6. Liên kết với luật hiện hành
| Luật | Quan hệ |
|---|---|
| Đ38 v3.0 | Phụ lục này bổ sung §A1, chuyển từ "chia thẻ" thành mô hình unit-centric chính thức |
| Đ4 (Lifecycle) | Unit lifecycle tuân thủ Đ4: draft → enacted → superseded → retired |
| Đ0-G (Birth) | Birth gate áp cho text_unit — xem L4 mở rộng Đ0-G |
| Đ29 (Species) | text_unit đăng ký species theo Đ29 — thao tác ở L4/design |
| Đ32 (Approval) | Review/approval ở cấp unit + change-set — xem L5 clarify Đ32 |
| Đ39 (KG) | Text unit vector pipeline mở rộng Đ39 — liên kết ở C5 design |
| Đ33 (PG) | PG First. Hot path PG. Cold path async. |
| HP NT1 | SSOT. Unit trong PG là truth. |
| HP NT11 | Khai tối thiểu. Metadata chỉ khai cái PG không tự biết. |
| HP NT13 | PG First, PG Native, PG Driven. |
§7. Điều kiện PASS
| # | Điều kiện |
|---|---|
| 1 | Định nghĩa text unit, document envelope, addressing, cây dọc, ref ngang — rõ ràng, không mâu thuẫn với 02C1 |
| 2 | Nguyên tắc bất biến (enacted, canonical address) nhất quán với Đ4 và QĐ1 |
| 3 | Phân tách dọc/ngang nhất quán với 02C1 §4 |
| 4 | Không trượt sang schema/implementation/tên bảng |
| 5 | Không mâu thuẫn với Đ38 v3.0, Đ4, Đ0-G, Đ29, Đ32, Đ33, Đ39, HP |
| 6 | L1 đủ làm tiền đề cho L3 (Metadata Governance) và L5 (Unit-level Review) |
| 7 | Council review (GPT + ít nhất 1 agent khác) + User duyệt |
DỰ THẢO | Phụ lục 03 Đ38 — Text Unit Governance | L1 | GPT review: PASS có điều kiện, 6 chỉnh đã áp dụng | Chờ Council + User