KB-7294 rev 32
Hiến pháp Kiến trúc Hệ thống Incomex v4.6.3 BAN HÀNH
17 min read Revision 32
constitutionfoundationv4.6.313-ntdot-pairpg-firstdieu43-enacteds178-fix15
HIẾN PHÁP KIẾN TRÚC HỆ THỐNG INCOMEX — v4.6.3 BAN HÀNH
Văn bản tối cao. Vi phạm Hiến pháp = vi phạm nghiêm trọng nhất. Ban hành: S148. Cập nhật: S157 (2026-04-02) +Điều 38. S176 (2026-04-13) +Kiến trúc 4 DB + 3 lớp Não-Kho-Cổng + Ngoại lệ NT3. S176B (2026-04-14) +Điều 41 BAN HÀNH. S177 Fix 8 (2026-04-14) Đ35 v5.1. S178 Fix 9 (2026-04-16) +NT12 DOT cặp + NT13 PG First + Đ43 v1.1 BAN HÀNH. S178 Fix 11 (2026-04-17) Đ43 v1.2 FINAL amend (cố định→tự động) + rev 2 patch NT2/NT4 SQL DDL post-enact. v4.6.3 BAN HÀNH. Giữ nguyên toàn bộ nền tảng v4.6.2 và bổ sung enact gói DOT Repair Governance S178 Fix 15 v4 FINAL: +P9 định vị
ops-codevào kiến trúc 3 lớp; +Đ22 v1.1, +Đ32 v1.1, +Đ33 v2.1, +Đ35 v5.2, +Đ41 v1.1; Đ43 giữ v1.2 FINAL và nhận extension vận hànhops_code_inventoryở context-pack/living-doc theo gói enact.
13 NGUYÊN TẮC NỀN TẢNG — CẤM VI PHẠM
| # | Nguyên tắc | Nghĩa | Hệ quả |
|---|---|---|---|
| 1 | LÀM MỘT LẦN, DÙNG MÃI | SSOT duy nhất | Sửa 1 chỗ = thay đổi mọi nơi |
| 2 | TỰ ĐỘNG 100% | Máy thực hiện | Làm tay = thiết kế sai |
| 3 | DOT 100% (CÓ NGOẠI LỆ) | Mọi thao tác qua script đăng ký | Không DOT = không làm được. 5 ngoại lệ ghi trong Điều 33 §13 |
| 4 | SẴN SÀNG THAY ĐỔI | Thay đổi = metadata/config | Sửa code = thiết kế tồi |
| 5 | TỰ PHÁT HIỆN, TỰ SỬA | Hệ thống biết khi sai | Không chờ con người |
| 6 | 5 TẦNG ĐỒNG BỘ — CẤM CODE NUXT | PG→Directus→Nuxt, Directus→AgentData→Qdrant | Bypass = CẤM (trừ ngoại lệ kiến trúc Điều 33 §13) |
| 7 | DUAL-TRIGGER | Trigger chính + trigger phụ | 1 trigger = không test được |
| 8 | ASSEMBLY FIRST | PG → Directus → nguồn mở → code cuối | Code = giải pháp cuối |
| 9 | KHÔNG CHẮC ĐÚNG = SAI | Không chắc → DỪNG + verify | "Cứ làm đi" = CẤM |
| 10 | QUẢN LÝ BẰNG PG, KHÔNG BẰNG TEXT | Máy cần validate/query/enforce → PG | Text = documentation. PG = truth. |
| 11 | KHAI TỐI THIỂU, THÔNG TIN TỐI ĐA | Thông tin PG đã có mà khai lại = thiết kế sai | PG catalog tự phát hiện. Chỉ khai cái PG không biết. |
| 12 | DOT THEO CẶP (2 CHIỀU) | Động cơ chính thực hiện + động cơ phụ phát hiện lệch, xử lý, báo cáo | Không có cặp = không có tự kiểm = thiết kế sai |
| 13 | ƯU TIÊN PG NATIVE | PG có tính năng sẵn → dùng. Không có → mới thiết kế mới | Đã có PG mà vẫn tự đẻ = xin phép user + giải thích lý do. Khác NT11: NT11 về metadata/schema, NT13 về tính năng runtime/logic |
→ Chi tiết: law-01-foundation-principles.md v3.0
→ NT3 ngoại lệ: dieu33-postgresql-law.md §13
KIẾN TRÚC HẠ TẦNG DỮ LIỆU — 4 DATABASE + 3 LỚP NÃO-KHO-CỔNG (BỔ SUNG S176)
Mọi thiết kế, mọi script, mọi DOT, mọi báo cáo PHẢI biết rõ kiến trúc này. Không hiểu kiến trúc = không được triển khai. Bài học S176 (cả buổi chiều rà soát mới hiểu): luật mới (HP v4.4.0) đã quên kiến trúc cũ (data-connection-law.md v1.1) → mọi người mò mẫm. Hiến pháp v4.5.0 phục hồi và bổ sung chính thức.
A. CỤM POSTGRESQL — 4 DATABASE TRONG 1 CLUSTER
PostgreSQL 16 chạy trên VPS Contabo EU làm nền tảng dữ liệu DUY NHẤT. Cluster postgres (container Docker postgres, port 5432) chứa 4 database có vai trò riêng biệt:
| # | Database | Owner | Vai trò | Lớp | Gateway hợp pháp |
|---|---|---|---|---|---|
| 1 | directus |
workflow_admin | Business warehouse — Directus CMS, mọi bảng nghiệp vụ user nhập, mọi managed collections, mọi PG function/trigger phục vụ Directus | Lớp KHO | Directus REST API + DOT chính thức + PG function fn_* |
| 2 | incomex_metadata |
workflow_admin | Agent Data store — kb_documents, kb_documents_history, kb_audit_log, metadata_store, chat_messages, cron_heartbeat. Bản chất NoSQL-style, tương thích Qdrant vector | Lớp NÃO | Agent Data FastAPI (pg_store.py) — cổng riêng, không qua Directus |
| 3 | workflow |
workflow_admin | Placeholder workflow engine — đang RỖNG có chủ đích. Để dành cho Kestra/Temporal/workflow engine giai đoạn sau (theo data-connection-law.md v1.1 Điều 4) | Lớp ENGINE (chưa active) | Sẽ định khi engine được kích hoạt |
| 4 | postgres |
workflow_admin | Default cluster admin DB — không chứa dữ liệu nghiệp vụ. Chỉ dùng để admin cluster | — | Không truy cập trực tiếp |
Quan trọng: 4 DB này KHÔNG được gom thành 1. Tách 4 DB là kiến trúc đúng, không phải tai nạn migration. Lý do tách:
incomex_metadatariêng để Agent Data có thể vận hành độc lập, NoSQL-style upsert mà không vướng Directus schema constraints.workflowriêng để workflow engine tương lai có không gian riêng, không trộn với business data.directusriêng để Directus CMS làm SSOT business data sạch.
B. 3 LỚP KIẾN TRÚC — NÃO, KHO, CỔNG (kế thừa data-connection-law v1.1)
Nguyên tắc: Không trộn vai trò. Mỗi thành tố nằm rõ ở 1 lớp chính. Luồng dữ liệu: Cổng → Não → Kho (hoặc ngược lại khi hiển thị).
Lớp NÃO (Brain) — Suy luận, AI, vector search
- Agent Data FastAPI (chạy trên VPS Docker) — orchestrator AI, gọi Qdrant + đọc/ghi
incomex_metadata - Qdrant (Docker container) — vector store cho embedding tri thức, tìm kiếm semantic
- AI agents IDE (Cursor, Codex, Gemini CLI, Claude Code, Claude Desktop) — gọi API, không lưu trữ lâu dài
- Vai trò: đọc tri thức, sinh phản hồi, điều khiển CI/CD, KHÔNG là SSOT cho dữ liệu lâu dài
Lớp KHO (Warehouse) — Bản ghi chính thức, SSOT
- PostgreSQL DB
directus— SSOT cho mọi business records (workflows, tasks, modules, system_issues, meta_catalog, knowledge_documents, registry tables, governance, KG…) - PostgreSQL DB
incomex_metadata— SSOT cho Agent Data document store (kb_documents, audit log, history, metadata store, chat messages) - Directus CMS (ứng dụng, port 8055) — gateway chính thức cho
directusDB, áp dụng 3 vùng schema (Core/Migration/Growth) - GitHub — SSOT cho mã nguồn (Nuxt, DOT scripts, infra YAML, Terraform); GitHub là đường ống push→VPS, không phải SSOT runtime
- GCP Secret Manager — SSOT cho mọi secret (PG password, API token, service account)
- Vai trò: lưu trữ chính thức, schema enforce, version, audit, phân quyền
Lớp CỔNG (Gate) — Giao diện người, hệ thống ngoài
- Nuxt Web (
https://vps.incomexsaigoncorp.vn) — portal hiển thị, đọc Directus REST/GraphQL qua nuxt-directus, KHÔNG truy cập DB trực tiếp - Directus Admin UI (port 8055) — admin nội bộ thao tác business data
- Lark Suite (Base, Docs, Sheets, Messenger) — nguồn dữ liệu nghiệp vụ thực, sync 2 chiều với Directus qua DOT chuyên biệt
- Chatwoot (planned) — CSKH đa kênh, sẽ tích hợp khi active
- GitHub Actions — CI/CD, push qua SSH→VPS deploy
- Vai trò: thu nhận input người, hiển thị output, KHÔNG là SSOT, KHÔNG được truy cập DB trực tiếp (trừ deploy hook hợp pháp đăng ký trong Điều 33)
C. NGUYÊN TẮC ĐỌC KIẾN TRÚC
- Mọi tài liệu phân tích PHẢI bắt đầu bằng câu hỏi: "DB nào? Lớp nào?" Không trả lời được = không được phân tích tiếp.
- Mỗi DOT trong
dot_toolsPHẢI khai báo: ghi vào DB nào (directus / incomex_metadata / workflow), thuộc lớp nào (Não / Kho / Cổng). - Mọi writer mới phải đối chiếu kiến trúc TRƯỚC khi viết code. Viết writer mà chưa đối chiếu = vi phạm Hiến pháp.
data-connection-law.mdv1.1 không còn là SSOT (đã được nâng lên Hiến pháp), nhưng nội dung kiến trúc 3 lớp được kế thừa nguyên vẹn vào đây.
2 CHIỀU QUẢN LÝ
TOP-DOWN: Luật → Phạm vi → Cơ quan → Liên kết → Thực thi (Điều 37)
Văn bản quy phạm → Sections có cấu trúc → Binding sống (Điều 38)
BOTTOM-UP: Thực thể → Khai sinh → Phân loại → Đếm (Điều 0-G, 22, 29...)
Khớp 2 chiều qua mọi tầng trung gian = HỆ THỐNG TOÀN VẸN
TUYÊN NGÔN | QUY TRÌNH 4 BƯỚC | CHIẾN LƯỢC SMART DATA | KIẾN TRÚC | HẠ TẦNG
→ Giữ nguyên v4.2.0. Xem revision trước. → BỔ SUNG S176: Phần KIẾN TRÚC HẠ TẦNG DỮ LIỆU ở trên thay thế và mở rộng phần "HẠ TẦNG" cũ.
THUẬT NGỮ
→ terminology-glossary.md v2.2 — 9 sections. +Section 9: Văn bản quy phạm, Section, Binding, Template, Instance (Điều 38).
→ BỔ SUNG S176: Thêm thuật ngữ "Lớp Não / Kho / Cổng" + "Database directus / incomex_metadata / workflow / postgres".
MỤC LỤC LUẬT
Nền tảng — ✅
| Điều | Tên | File |
|---|---|---|
| — | Giải thích Từ ngữ v2.2 | terminology-glossary.md |
| 0 | Luật Thực thể + Bảo toàn | law-00-entity.md |
| 0-B | 7 Lớp Cấu tạo (33 species) | law-00b-composition.md |
| 0-G | Luật Khai Sinh | law-00g-birth.md |
| 0-H | Đồng bộ 5 Tầng + DOT 2 cấp | law-00h-5layer-sync.md |
| 0-S/M/L | Single Provider, Đo lường, Dùng lại | law-00sml-amendments.md |
| 1 | 13 Nguyên tắc Nền tảng | law-01-foundation-principles.md v3.0 (cần update +NT12+NT13) |
Registry & Governance — ✅
| Điều | Tên |
|---|---|
| 2 | Registry + ID |
| 3 | Metadata |
| 4 | Sinh sản (Birth Process) |
| 5 | 5 Tầng Kiến trúc |
| 6 | Đồng bộ |
| 7 | Assembly First |
| 8 | Phụ thuộc |
| 9 | Schema Governance |
Vận hành — ✅
| Điều | Tên |
|---|---|
| 10 | Inject |
| 11 | Idempotent |
| 12 | Vòng đời |
| 13 | Danh mục Sống |
| 14 | Chống Trùng lặp |
| 15 | State Machine |
| 16 | Checkpoint |
| 17 | Multi-Domain |
| 18 | i18n |
| 19 | Orphan Scanner |
| 22 | Self-Healing |
Quản trị — ✅ BAN HÀNH
| Điều | Tên | Ghi chú |
|---|---|---|
| 24 | Luật Nhãn (Label) | ✅ 6 facets × 6 layers. |
| 26 | Luật Pivot (Đếm) v4.0 | ✅ pivot_definitions, pivot_count(). |
| 28 | Luật Kỹ thuật Hiển thị v2.0 | ✅ S150. 2 vòng Council. |
| 29 | Luật Phân loại (Species + Collection) | ✅ 33 species, 7 dimensions. |
| 30 | Luật Bảo vệ Hồi quy v1.2 | ✅ Playwright, contracts. |
| 31 | Luật Toàn vẹn Hệ thống v1.2 | ✅ 100% detection, Điều 31+. |
| 32 | Luật Phê duyệt v1.1 | ✅ S178 Fix 15 BAN HÀNH. PG-native action/request types, split code/payload, quorum approvals, bridge migration, audit-safe FK. |
| 33 | Luật PostgreSQL v2.1 | ✅ S176 BAN HÀNH, amend S178 Fix 15. Giữ nguyên v2.0 và bổ sung chuẩn _dot_origin cho bảng governance mới, phù hợp enact DOT Repair Governance v4 FINAL. |
| 35 | Luật Quản trị DOT v5.2 | ✅ S177 Fix 8 BAN HÀNH, amend S178 Fix 15 v4 FINAL. Bổ sung flow fix_repair_dot, verify 3 tầng, ADMIN fallback audit, paired test retrofit và liên kết APR risk/quorum. |
| 36 | Luật Collection Protocol v4.0 | ✅ S155. 17 health checks. Self-healing. |
| 37 | Luật Tổ chức Bộ máy v3.3 | ✅ S150+. 2 vòng Council. 7→14 triggers. 6→14 DOT. |
| 38 | Luật Văn bản Quy phạm v2.3 | ✅ S157. 2 vòng Council (Gemini 9.5 + GPT 8.9). 7 cấp VB. 9 section types. 6 cơ chế nhất quán. 14 triggers + 1 EXCLUDE. 14 DOT. 2 render engine. Thay thế law_registry → normative_registry. |
| 39 | Luật Knowledge Graph v2.3 | ✅ S159. 3 vòng Council (Gemini 9.5 + GPT 8.8). 26 bài toán. 36 DOT (18 cặp). 10 quy trình. Scaffold Graph + Priority Graph HTN + Self-Learning RLKGF + Conversational Acquisition. Nguyên tắc vàng: AI đề xuất, không tự ban hành. |
| 41 | Luật Vận hành Mã VPS v1.1 | ✅ S176B BAN HÀNH, amend S178 Fix 15 v4 FINAL. Bổ sung ops-code/ như logical deployment class, deploy_kind trong vps_deploy_log, và hành lang deploy/backup/log riêng cho sửa DOT canonical enacted. |
| 43 | Luật Bản đồ Hệ thống v1.2 FINAL (rev 2) | ✅ S178 Fix 11 BAN HÀNH (2026-04-17). Council 2 vòng v1.1 DONE + v1.2 amend thuần kỹ thuật (Fix 11 Council 2 vòng: R1 Gemini 9.5 MINOR + GPT 6.9 CHANGES → 7 patches P1-P7 schema/config hóa; R2 Gemini 10 FINAL + GPT 8.8 MINOR → 2 patches P8+P9 security guards SQL executor + render_config contract). v1.2 rev 2 post-enact audit: Desktop rà 13 NT phát hiện 2 lỗ hổng tầng SQL DDL mà Council bỏ sót → P10 GRANT DEFAULT PRIVILEGES cross-DB + P11 Trigger function body đọc dot_config runtime. 11 patches total. 18 vi phạm HP đã đóng (16 từ v1.2 + 2 từ rev 2). Triết lý v1.1 giữ 100%. Context Pack tự sinh (8 section config-driven) + 2 DOT cặp + 2 checksum + 2-phase publish + compensating. File: dieu43-system-context-law.md rev 10. Triển khai: 3/17 Bootstrap DONE (Phase 1+2+3+Q2) — đang làm Phase 4a script nặng nhất. |
Dự thảo — 📝
| Điều | Tên | Ghi chú |
|---|---|---|
| 34 | Luật Workflow | Chờ workflow engine active |
Lỗi thời — ⛔
| Tên | Lý do |
|---|---|
Luật Luồng DL v1.1 (data-connection-law.md) |
SUPERSEDED — nội dung kiến trúc 3 lớp đã đưa lên Hiến pháp v4.5.0. Không viện dẫn file cũ. |
| Hiến pháp v3.9 | SUPERSEDED |
CHANGELOG
| Version | Nội dung |
|---|---|
| v4.3.0 | +NT11. +Điều 37 BAN HÀNH. S150+. |
| v4.4.0 | +Điều 38 BAN HÀNH (Luật Văn bản Quy phạm v2.3). Mục lục Quản trị bổ sung đầy đủ Đ24,26,29,30,31. Thuật ngữ v2.2 +Section 9. 2 chiều quản lý +VB quy phạm. S157. |
| v4.5.0 | S176 BAN HÀNH. +Kiến trúc 4 Database (directus/incomex_metadata/workflow/postgres) + 3 Lớp Não-Kho-Cổng (kế thừa data-connection-law v1.1). +Ngoại lệ NT3 DOT 100% (5 ngoại lệ ghi Điều 33 §13). +Điều 33 BAN HÀNH v2.0. Sửa lỗi: HP v4.4.0 đã quên kiến trúc cũ → mất buổi chiều mò → bài học. data-connection-law.md retire chính thức. |
| v4.5.1 | S176B BAN HÀNH. +Điều 41 BAN HÀNH v1.0. Điều 41 được chuyển từ Dự thảo sang Quản trị. Bổ sung chính thức khung vận hành mã VPS khi VPS là SSOT: tách vùng dev/prod, atomic deploy, FAST/FULL mode, rollback known-good, guard drift config, SSOT ENV duy nhất. |
| v4.5.2 | S177 Fix 8 (2026-04-14). Mục lục Đ35 cập nhật v5.0 → v5.1 FINAL sau Council 2 vòng (Gemini 9.8/10 APPROVE FINAL + GPT 9.1/10 APPROVE WITH MINOR). v5.1 amend 5 khoản (§4.1 UNIQUE partial + NOT NULL + _dot_origin, §8.1 H10-H14, §8.3 birth_gate configurable, §11 retrofit clause MỚI, §5.4 dual-trigger pre-POST + cron repair). 7 fix Council R2 apply inline. Đóng bệnh 49 DOT POST-S151 vẫn 94% NULL operation. Backup v5.0: dieu35-dot-governance-law-v5-0-backup.md. |
| v4.6.0 | S178 (2026-04-16) CHỦ TỊCH CHỐT THẲNG. +NT12 DOT THEO CẶP (2 CHIỀU): động cơ chính thực hiện, động cơ phụ phát hiện lệch và xử lý/báo cáo. +NT13 ƯU TIÊN PG NATIVE: PG đã có tính năng thì dùng, muốn tự đẻ mới phải xin phép user + giải thích lý do. 2 NT này là codify pattern đã proven ổn định qua Đ35 v5.1 (paired_dot cho mọi DOT cặp) + memory long-term (Assembly First / PG-FIRST strategy). Không qua Council vì là formalize pattern đã dùng nhiều tháng, không phải thay đổi thiết kế. +Đ43 v1.0 DRAFT trong Dự thảo. Mục lục Luật 1 cập nhật "13 Nguyên tắc Nền tảng" (cần update file law-01-foundation-principles.md v3.0 → v3.1 tương ứng). |
| v4.6.1 | S178 (2026-04-16) +Đ43 BAN HÀNH. Luật Bản đồ Hệ thống v1.1 FINAL chính thức chuyển từ Dự thảo sang Quản trị sau Council 2 vòng (R1 Gemini 8.2+GPT 7.8 APPROVE WITH CHANGES → 14 patches; R2 Gemini 9.5 APPROVE FINAL+GPT 8.9 APPROVE WITH MINOR → 4 patches A/B/C/D inline). File chính thức: dieu43-system-context-law.md rev 1. Draft cũ dieu43-system-context-law-draft.md rev 4 đánh dấu SUPERSEDED (giữ trace Council). Giải bệnh "AI mất nhiều giờ mỗi phiên để hiểu kiến trúc Incomex". Triển khai: BLOCK 1 Bootstrap 14 bước §11 giao CLI ngay. |
| v4.6.2 | S178 Fix 11 (2026-04-17) Đ43 v1.1 → v1.2 FINAL (rev 2). v1.1 phát hiện vi phạm NT2/NT4/NT11 do hardcode cố định (section list, threshold, output path, health handler logic, SQL whitelist) → amend v1.2 thuần kỹ thuật, giữ 100% triết lý v1.1. Council 2 vòng lần 2: R1 Gemini 9.5 MINOR + GPT 6.9 CHANGES → 7 patches schema/config hóa (P1-P7). R2 Gemini 10 FINAL + GPT 8.8 MINOR → 2 patches P8 SQL executor security 5 guards + P9 render_config contract key whitelist. rev 2 post-enact audit: Desktop rà 13 NT sau ban hành, phát hiện 2 lỗ hổng tầng SQL DDL Council bỏ sót → P10 GRANT DEFAULT PRIVILEGES cross-DB (thay GRANT từng table) + P11 Trigger function body đọc dot_config runtime (thay bind pattern vào WHEN clause). Patch inline clarification. 11 patches total. 18 vi phạm HP đóng. Bài học ghi nhớ: rà NT phải soi 3 tầng — code bash/python, SQL DDL (trigger/grant), SQL data (INSERT seed) — tầng DDL dễ lọt nhất vì không đọc code kỹ. Backup v1.1: dieu43-system-context-law-v1-1-backup.md. Draft v1.2: dieu43-system-context-law-v1-2-draft.md SUPERSEDED. Triển khai thực tế: Phase 1+2+3+Q2 DONE trên VPS, đang soạn Phase 4a script nặng nhất (chia 7 giai đoạn P0-P6 với Desktop gate mỗi P). |
| v4.6.3 | S178 Fix 15 (2026-04-18) DOT Repair Governance v4 FINAL BAN HÀNH. Định vị ops-code vào 3 lớp; amend trực tiếp Đ22 → v1.1, Đ32 → v1.1, Đ33 → v2.1, Đ35 → v5.2, Đ41 → v1.1; giữ Đ43 v1.2 FINAL và bổ sung extension vận hành ops_code_inventory ở living-doc/context-pack theo gói enact. |
HP v4.6.3 BAN HÀNH | 13 NT (NT3 có ngoại lệ) | +Kiến trúc 4 DB + 3 Lớp + ops-code định vị trong Lớp KHO | +Đ22 v1.1 + Đ32 v1.1 + Đ33 v2.1 + Đ35 v5.2 + Đ41 v1.1 + Đ43 v1.2 FINAL/EXT | +NT12 DOT cặp + NT13 PG First | Council liên tục + Desktop post-enact NT audit