Khung giải pháp — Text as Code

Phụ lục 02B Điều 38 — Solution Approach

Trạng thái: PASS — GPT review + User duyệt 2026-04-24 Đầu vào: Phụ lục 01 (Mục tiêu, BAN HÀNH) + Phụ lục 02A (Inventory, CHỐT) Không làm ở bước này: Chưa chốt schema, chưa đặt tên bảng/function, chưa đếm DOT, chưa migration, chưa nợ luật chi tiết.

1. Bài toán này sẽ được giải bằng mô hình tổng thể nào?

Incomex chuyển từ document-centric (mỗi VB = 1 file lớn, sửa cả file, review cả file) sang unit-centric (mỗi VB = tập hợp các miếng nhỏ trong PG, sửa/review/vector riêng từng miếng).

Mô hình tổng thể gồm 5 lớp:

Lớp	Vai trò	Ví dụ nôm na
Unit model	Mỗi miếng thông tin = 1 row PG, có địa chỉ riêng, sửa riêng, version riêng	Mỗi khoản luật = 1 viên gạch. Sửa 1 viên không đụng viên khác.
Metadata governance	Mỗi miếng có metadata chuẩn (ai sở hữu, loại gì, trạng thái gì, bind gì). Metadata có schema bắt buộc, có birth gate validate, có DOT kiểm quality.	Mỗi viên gạch có tem chất lượng. Thiếu tem = không được xây.
Component / BOM	Pattern lặp → đóng gói thành component chuẩn. VB = lắp ráp từ component. BOM biết VB dùng component nào, version nào.	Nhà xây từ gạch tiêu chuẩn. Biết tường nào dùng gạch gì.
Traceability	Liên kết xuyên chuỗi Text ↔ Code ↔ Workflow ↔ Knowledge. Sửa 1 chỗ → biết chỗ khác ảnh hưởng. Ref gãy tự phát hiện.	Kéo 1 sợi dây → biết ngay đầu kia nối ở đâu. Dây đứt → chuông kêu.
Hot/cold runtime	Thao tác sửa = ghi thẳng PG (nhanh, kiểm ngay). Embedding, vector sync, KG enrichment = chạy sau (không chặn).	Ghi sổ = viết tay tại chỗ. Scan lưu điện tử = làm sau vài phút.

5 lớp này phục vụ chuỗi giá trị Text → Code → Workflow → Knowledge đã chốt ở Phụ lục 01.

2. Ta mượn từ 3 ngành nào, lấy phần gì?

Ngành	Lấy gì	KHÔNG lấy gì
DITA / CCMS (technical writing — Boeing, IBM)	Tư duy topic-based: chia nhỏ → metadata → lắp ráp → content reuse → sửa topic tự cập nhật mọi nơi dùng nó	XML engine, DITA OT, CCMS commercial tool
PLM / BOM (manufacturing — ô tô, hàng không)	Tư duy component: catalog linh kiện, lifecycle (draft→active→retired), BOM (danh sách linh kiện lắp thành sản phẩm), variant, compatibility matrix, ECO (change process có kiểm soát)	CAD integration, ERP sync, supplier management
CMDB / ITSM (IT ops — ServiceNow, BMC)	Tư duy Configuration Item: federated catalog (1 nơi tra cứu, nhiều nơi lưu), dependency mapping, impact analysis (sửa A → biết B bị ảnh hưởng), multi-view (cùng data, nhiều góc nhìn)	Auto-discovery agent, ITIL process framework, enterprise pricing

Bổ sung nhẹ: Akoma Ntoso (addressing scheme cho VB pháp luật), DO-178C (traceability 4 tầng), W3C Semantic Annotation (metadata governance pattern).

Runtime thống nhất trên PG. Không bê toolchain nào vào.

3. Quyết định lớn cần chốt trước khi đi chi tiết

#	Quyết định	Ý nghĩa	Cơ sở
QĐ1	PG unit là đơn vị gốc — mỗi miếng thông tin = 1 row PG, có địa chỉ duy nhất, sửa/review/version/vector riêng. Unit đã ban hành (enacted) không được sửa đè trực tiếp — thay đổi phải đi qua version mới / change-set / amend path hợp pháp (Đ4, Đ32).	Chuyển từ file-centric sang unit-centric. Đây là thay đổi nền tảng lớn nhất.	DITA topic, Akoma Ntoso eId, NT1, NT13, Đ4, Đ32, use case vận hành cốt lõi (Phụ lục 01)
QĐ2	Vector là projection của PG unit — PG unit là SSOT. Vector/Qdrant là bản chiếu async phục vụ retrieval. Sửa unit → re-vector đúng unit đó. Vector không phải hot path.	Giải dứt điểm câu hỏi "vector ở đâu trong kiến trúc". PG validate, vector search.	Phụ lục 01 nguyên tắc hiệu năng, NT13
QĐ3	Metadata có core schema + profile — core schema chung mọi loại unit (bắt buộc). Profile bổ sung theo loại VB (luật có field khác SOP). Field responsibility rõ: ai fill, khi nào, system auto hay agent manual. Birth gate validate.	Giải dứt điểm câu hỏi "metadata quản thế nào". Không free-form.	DITA metadata, GR5, Fix 27-28 (bài học description governance), NT14
QĐ4	Component / BOM là mô hình reuse — pattern lặp = đóng gói thành component có spec, version, lifecycle, owner. VB = BOM (danh sách component lắp ráp). Tạo mới phải chứng minh không reuse được.	Chuyển từ "xe độc bản" sang "công nghiệp hóa".	PLM/BOM, MT0B/MT0C, TC7, TC10
QĐ5	Hot path đồng bộ PG, enrichment async — sửa unit/binding/metadata/lifecycle = ghi PG, kiểm integrity ngay (< 50ms). Vector sync, KG enrichment, semantic indexing = chạy sau (≤ vài phút).	Giải dứt điểm câu hỏi "cái gì nhanh, cái gì chờ".	Phụ lục 01 hot/cold, NT13
QĐ6	Review và approval đi theo unit + change-set, không theo file — council review từng unit (hoặc nhóm unit thay đổi). Không review cả file 45KB.	Giải V5 (review hời hợt). Làm review khả thi khi mở rộng.	DITA topic review, Đ32, MT3

4. Những gì chưa đi sâu ở bước này

#	Chưa quyết	Lý do hoãn
1	Schema cuối — tên bảng, tên cột, kiểu dữ liệu, FK, constraint cụ thể	Phải chốt approach trước. Schema là hệ quả của approach, không phải ngược lại.
2	Danh sách DOT cuối — bao nhiêu DOT mới, tên gì, paired thế nào	DOT sinh ra từ schema + quy trình. Chưa có schema → chưa đếm DOT.
3	Migration chi tiết — sections JSONB → unit rows, thứ tự, zero-downtime cụ thể	Migration phụ thuộc schema cuối. Phải qua Bước C.
4	Nợ luật / amend cụ thể — luật nào sửa khoản nào, nội dung amend	Amend sinh ra sau khi thiết kế xong. Liệt kê sớm = tự tạo debt giả.
5	UI / Workflow engine — Nuxt render, Directus admin, workflow orchestration	GR4: không vượt scope. Đ34 (workflow) chưa active.
6	Machine semantics chi tiết — rule_type taxonomy, binding_type taxonomy, annotation format	GR5: metadata governance cần gói khảo sát riêng. Sẽ đào sâu ở Bước C.

5. Thứ tự đi vào chi tiết sau khi chốt khung

C0 là bước legal bắt buộc trước mọi thiết kế kỹ thuật.

Bước	Nội dung	Tại sao thứ tự này
C0	Legal alignment & Law gap map — map QĐ1–QĐ6 vào luật hiện hành, chỉ ra: đã che phủ, cần clarify, cần amend, cần phụ lục mới. Xác định thứ tự: viết/sửa luật gì trước khi thiết kế gì.	Bắt buộc trước mọi thiết kế. Tinh thần Incomex: mọi việc căn cứ theo luật, thiếu luật thì viết luật trước.
C1	Data model lõi — unit model + document envelope + addressing scheme	Nền cho mọi thứ khác. Không có unit → không có gì để metadata, BOM, trace.
C2	Metadata governance — core schema, profile strategy, field responsibility, birth validation, derived rules, quality checking	Nền thứ 2. Không có metadata governance → unit có nhưng data rác. Bài học Fix 27-28.
C3	Component / BOM + Reuse — component registry, BOM structure, reuse decision, compatibility, golden path	Dựa trên C1+C2. Component = unit ở tầng cao hơn. BOM = quan hệ giữa component và document.
C4	Traceability + Impact — ref chéo enforce, dependency chain, impact analysis, orphan detection	Dựa trên C1+C3. Traceability xuyên chuỗi Text↔Code↔Workflow↔Knowledge cần unit + component + edges.
C5	Runtime hot/cold + Vector — write path, trigger integrity, vector sync mechanism, backlog observability	Dựa trên C1–C4. Khi biết data model + metadata + traceability → mới biết hot path cần kiểm gì, cold path sync gì.
C6	Views + Observability — reading view, machine view, BOM view, portfolio dashboard	Dựa trên C1–C5. View = render từ SSOT. Dashboard = tổng hợp metrics.
C7	Migration — migration sections→units, zero-downtime, thứ tự triển khai	Cuối cùng. Khi toàn bộ thiết kế + legal alignment rõ → mới biết migration plan cụ thể.

PASS 2026-04-24 | Phụ lục 02B | Khung giải pháp Text as Code | 5 câu, 6 QĐ, 6 hoãn, C0–C7 (8 bước, legal trước design) | GPT review + User duyệt