ĐIỀU 0-H: LUẬT ĐỒNG BỘ 5 TẦNG — 1 KHAI BÁO, 5 TẦNG TỰ BIẾT

v1.0 | S147 (2026-03-30) | MỚI Áp dụng Tuyên ngôn: ① Vĩnh viễn chưa? ② Nhầm được không?

§1. VẤN ĐỀ GỐC

Hệ thống Incomex có 5 tầng data:

PG (chân lý) → Directus (phục vụ) → Nuxt (màn hình)
                    ↓
              Agent Data (tri thức) → Qdrant (vector)

Mỗi khi THAY ĐỔI bất kỳ thứ gì (field, dòng, collection), cả 5 tầng phải ĐỒNG THỜI biết. Nếu 1 tầng không biết = "vô hình" = lệch = lỗi.

Ví dụ vi phạm: ALTER TABLE PG trực tiếp → PG có column mới → Directus không biết → API không serve → Nuxt không thấy → Agent Data không sync → field "vô hình" ở 4 tầng. Data đúng trong PG nhưng không ai nhìn thấy.

§2. NGUYÊN TẮC — DOT LÀ CỔNG DUY NHẤT

Bất kỳ thay đổi nào → PHẢI qua DOT → DOT tự xử lý TẤT CẢ 5 tầng.

Không có đường nào khác vào hệ thống. DOT = quy trình được mã hoá = dây chuyền sản xuất. Bấm nút → tất cả bước chạy → không bỏ sót, không nhầm, không quên.

§2.1. CẤM — Thao tác trực tiếp vào từng tầng

CẤM	Lý do	Hậu quả
ALTER TABLE PG trực tiếp	Directus không biết field mới	API không serve, Nuxt/Agent Data mù
INSERT directus_fields thủ công	Có thể sai special/interface/display	Field hiển thị sai trên Directus Admin
Sửa Nuxt hardcode columns	Thêm field mới → Nuxt không thấy	Vi phạm §0-BA (Nuxt = màn hình)
Gọi Agent Data API trực tiếp	Bypass Directus → mất webhook sync	Agent Data có data Directus không có
INSERT Qdrant vectors thủ công	Orphan vectors, không map source_id	Vector mồ côi, search kết quả sai

§2.2. BẮT BUỘC — Qua DOT, DOT tự xử lý 5 tầng

Thêm field:

DOT (Cấp B, có secret)
  → Directus Fields API: POST /fields/:collection
  → Directus TỰ: tạo PG column + đăng ký field + set display + permissions
  → Directus webhook → Agent Data sync → Qdrant embed
  → Nuxt readItems → tự thấy field mới (vì Nuxt readItems fields:['*'])
  = 1 khai báo → 5 tầng đồng bộ

Thêm dòng data:

DOT (Cấp B, có secret)
  → Directus Items API: POST /items/:collection
  → Directus TỰ: INSERT PG row + serve qua API
  → PG trigger → meta_catalog update
  → Directus webhook → Agent Data sync
  → Nuxt readItems → tự hiện
  = 1 khai báo → 5 tầng đồng bộ

Thêm collection:

DOT (Cấp B, có secret)
  → Directus Collections API: POST /collections
  → Directus TỰ: CREATE TABLE PG + đăng ký collection
  → Directus Fields API → fields + permissions
  → INSERT meta_catalog (registry) + birth_registry (khai sinh)
  → Directus webhook → Agent Data → Qdrant
  → Nuxt dynamic page → tự có
  = 1 khai báo → 5 tầng đồng bộ

§3. DOT 2 CẤP — MUỐN NHẦM CŨNG KHÔNG THỂ

Cấp	Loại	Secret	Quyền	Ví dụ
A	Kiểm tra, báo cáo, đọc	KHÔNG	READ only	dot-pivot-health, dot-orphan-scan, dot-schema-diff
B	Đồng bộ, thay đổi schema/data	CÓ (GSM)	WRITE 5 tầng	dot-pivot-virtual-create, dot-schema-ensure, dot-entity-create

DOT Cấp B:

PHẢI lấy SYNC_SECRET từ Google Secret Manager trước khi chạy
Script kiểm tra: if [[ -z "$SYNC_SECRET" ]]; then echo "CẤM: Thiếu secret"; exit 1; fi
Secret chỉ nằm trong GSM, chỉ DOT Cấp B biết cách lấy
Agent chạy ALTER TABLE trực tiếp → không qua DOT → không có secret → KHÔNG THỂ

Test Tuyên ngôn ②: "Agent mới vào, có thể ALTER TABLE trực tiếp không?" → KHÔNG. Vì Directus API cần admin token (trong GSM), và DOT Cấp B là cổng duy nhất có token đó. Agent không có token → không thể thao tác. Muốn nhầm cũng không thể.

§4. CƠ CHẾ 2 ĐỘNG CƠ

§4.1. Động cơ chính (lượt đi) — KIỂM SOÁT ĐẦU VÀO

DOT = cổng duy nhất. 1 khai báo → 5 tầng tự đồng bộ.

Chuỗi đồng bộ tự nhiên đã có:

PG ↔ Directus: Directus quản lý PG. 1 hệ. Luôn khớp (nếu dùng Directus API).
Directus → Nuxt: Nuxt readItems. Directus đúng → Nuxt đúng.
Directus → Agent Data: Directus Flows webhook → Agent Data sync (21 flows ĐÃ CÓ).
Agent Data → Qdrant: Agent Data embed → Qdrant (ĐÃ CÓ).

Điều kiện: Tất cả thay đổi PHẢI đi qua Directus API (thông qua DOT). Bypass = đứt chuỗi.

§4.2. Động cơ phụ (lượt về) — ĐO SỨC KHOẺ THIẾT KẾ

dot-sync-5-layer-check (DOT Cấp A):
  ① PG columns vs Directus fields → mismatch?
  ② Directus items vs Agent Data → search verify?
  ③ Agent Data docs vs Qdrant vectors → orphan?
  ④ Nuxt endpoints → response có đủ fields?

  Tìm 0 issues → IDLE → thiết kế TỐT ✅
  Tìm issues → BÁO CÁO → ghi system_issues (severity=critical)
    → Message: "AI ĐÓ ĐÃ BYPASS DOT. Hệ thống đang hỏng."
    → Tìm NGUYÊN NHÂN bypass → Fix GỐC (chặn đường bypass)
    → Scanner lại IDLE

DOT kiểm tra phải làm việc = nhiệt kế lên cao = bệnh nhân đang ốm = thiết kế có lỗ hổng. Chữa bệnh = fix gốc thiết kế. Không phải hạ sốt (fix data).

§4.3. Điều 31 giám sát CẢ 2 ĐỘNG CƠ

Điều 31 phải trả lời 3 câu hỏi:

Câu hỏi	Kiểm tra	Nguy hiểm nếu
Động cơ chính còn hoạt động?	DOT còn là cổng duy nhất? Webhooks còn fire? Cron còn chạy?	Bypass DOT → lệch âm thầm
Động cơ phụ còn sẵn sàng?	Scanner lần cuối chạy bao giờ? Kết quả ghi system_issues?	Scanner down → không biết có lệch
Hệ thống phòng cháy hoạt động?	Scanner down > 24h mà không ai biết?	Nguy hiểm nhất: không biết mình không biết

§5. BÁO CÁO DOT — MINH BẠCH

Mọi DOT kiểm tra khi chạy xong PHẢI ghi kết quả vào system_issues:

INSERT system_issues:
  issue_type = 'dot_health_check'
  source_dot = 'DOT-xxx'
  result = 'pass' / 'found_issues'
  details = JSON chi tiết
  created_at = NOW()

Cả 2 trường hợp đều GHI — để biết DOT ĐÃ CHẠY.

Dashboard (tương lai): "DOT nào phải LÀM VIỆC?" → trend → 0 = mục tiêu. Trend tăng = thiết kế xấu đi.

§6. VERIFY — TEST TUYÊN NGÔN

Mỗi khi thiết kế giải pháp liên quan đến data:

Test	Câu hỏi	Nếu FAIL
Tuyên ngôn ①	"Ngày mai thêm field/dòng/collection mới — vấn đề lệch còn xảy ra không?"	Giải pháp sai. Làm lại.
Tuyên ngôn ②	"Agent mới vào — có thể bypass DOT và thao tác trực tiếp không?"	Thiết kế sai. Chặn bằng hạ tầng.
Động cơ chính	"1 khai báo DOT → 5 tầng đều biết?"	Thiếu bước. Bổ sung.
Động cơ phụ	"Scanner down 1 tuần — ai biết?"	Thiếu giám sát. Bổ sung Điều 31.

§7. ANTI-PATTERNS

AP-15: ALTER TABLE trực tiếp bypass Directus (S147) Sai: Agent viết ALTER TABLE ADD COLUMN trong PG. Directus không biết → field vô hình. Fix: Mọi thay đổi schema → Directus Fields API qua DOT Cấp B.

AP-16: DOT kiểm tra tìm issues nhưng không tìm gốc (S147) Sai: Scanner tìm mismatch → fix data cho khớp → xong. Gốc (bypass DOT) vẫn còn. Fix: Tìm issues = tìm AI BYPASS → chặn đường bypass. Không fix data.