ARCHITECTURE AUDIT — Gemini — 2026-03-15

TÓM TẮT

🔴 Critical: 3 vấn đề (Sync Directus -> Agent Data gãy; Health check fix bằng threshold; 22 entities thiếu labels)
🟡 Warning: 5 vấn đề (Lifecycle thiếu Modify/Delete; Orchestration thiếu Prefect; Layer 3 hoàn thiện 60%; 707 issues tồn đọng; Legacy pages chưa migrate)
🟢 OK: 4 lĩnh vực (Hiến pháp 25 Điều; Registry-First maturity 90%; Metadata coverage 95%; DOT Scanning foundation)

Hiến pháp & Operating Rules: Nhất quán tuyệt đối về 2 nguyên tắc tối thượng: Registry-First và Assembly First. Tuy nhiên, Operating Rules v4.22 đề cập "Taxonomy 5 collections" đã sẵn sàng, nhưng thực tế taxonomy-seed-data mới chỉ ở mức sơ khai, wiring chưa hoàn thiện dẫn đến count=0 tại Layer 1 (TD-159).
Thuật ngữ: Hệ thống thuật ngữ "Tầng" (Layer 1-5) đã được chuẩn hoá tốt. Tuy nhiên, khái niệm "Lớp 3" (Information Infrastructure) đôi khi bị nhầm lẫn với "Tầng 3" (Module System) trong một số thảo luận cũ, cần thống nhất dùng "Layer 3" cho cả hai để tránh hiểu lầm.
Số liệu: Có sự bất nhất giữa meta_catalog.record_count (lý thuyết) và actual_count (thực tế) do cơ chế auto-refresh chưa chạy scheduled (TD-107).

Lifecycle thiếu "Hậu duệ" và "Cái chết": Quy trình sinh (Birth) đã được tự động hoá tốt qua Directus Flows/PG Triggers. Tuy nhiên, quy trình SỬA/XOÁ/GỘP (Modify/Delete/Merge) hoàn toàn trống (Gap 3). Hệ thống đang phình to theo thời gian mà không có cơ chế "Retire/Archive" tự động, dẫn đến rác dữ liệu.
Mạng lưới liên kết (Layer 3): Mới đạt ~60% độ trưởng thành. Thiếu các quan hệ bắc cầu (Transitive) và ngang hàng (Peers). Nếu không có 2 loại quan hệ này, AI Agents không thể thực hiện "Impact Analysis" (phân tích ảnh hưởng) một cách toàn diện khi sửa đổi schema hoặc code.
Giới hạn Scale: Khi entities tăng 10x, cơ chế "Orphan detection" hiện tại (bash script) sẽ trở thành bottleneck nếu không chuyển sang PG Set Operations hoàn toàn. "Duplicate engine" (TD-083) vẫn là một dấu hỏi lớn về mặt kỹ thuật.

Sửa lỗi bằng Threshold (TD-165/166): Đây là nợ kỹ thuật nghiêm trọng nhất được phát hiện. Việc nâng threshold từ 10 lên 15 để Health Check chuyển GREEN là hành vi che giấu triệu chứng thay vì điều trị căn nguyên (Root Cause). Khoảng cách (Gap) > 10 là dấu hiệu của việc đồng bộ không hoàn hảo hoặc logic đếm có vấn đề.
Pattern "PASS giả": Nhiều Agent báo cáo công việc hoàn thành (PASS) dựa trên kết quả grep hoặc kiểm tra bề mặt, trong khi thực tế vi phạm Registry-First (ví dụ: Table Module M-003). Điều này cho thấy hệ thống "Verification" cần dựa 100% vào Registry thay vì file system.
Metadata DOT: Mặc dù TD-095 báo cáo 100% descriptions, nhưng chất lượng metadata cho các DOT tools mới (S120-122) vẫn còn hời hợt, khiến AI khó chọn đúng tool.

Sync Directus -> Agent Data (Gap 14): Đang trạng thái INACTIVE. Đây là "điểm mù" nguy hiểm nhất. AI Agents đọc tài liệu/data từ Agent Data sẽ thấy thông tin cũ (stale), trong khi Production (Directus) đã thay đổi. Đây là nguồn cơn của nhiều lỗi "Agent làm đúng tài liệu nhưng hỏng Production".
Self-healing "nửa vời": Hệ thống mới dừng ở mức DETECT (phát hiện) và ALERT (tạo issues). Thiếu các pipeline PROPOSE (đề xuất fix) và APPLY (tự áp dụng) cho các lỗi nhẹ như metadata trống hoặc link hỏng (Điều 22).
Thiếu Orchestration: Các DOT scripts đang chạy rời rạc. Việc thiếu Prefect (đã planned nhưng chưa deploy) khiến không có "bộ não" điều phối các tác vụ phức tạp, retry khi lỗi, hoặc chạy song song để tối ưu thời gian.

Hành pháp hóa Hiến pháp: Chuyển 25 Điều Hiến pháp thành một bộ dot-constitution-check chạy tự động trong CI. Bất kỳ PR nào vi phạm (ví dụ: tạo collection mới mà không có registry record) sẽ bị block tự động.
Hợp nhất CI: Gộp ops-smoke, sync-check và các guard-rails thành một pipeline duy nhất để tiết kiệm CI minutes và tăng tốc độ feedback.
Cơ chế "Thanh tra DOT" (TD-153): Triển khai script tự quét toàn bộ hệ thống để chỉ ra những vùng "điểm mù" (vùng code/data chưa được phủ bởi bất kỳ DOT tool giám sát nào).

#	Kiến nghị	Lý do	Mức
1	Fix Sync Directus -> Agent Data	AI Agents đang "mù" trước các thay đổi manual trên UI	🔴 Critical
2	Audit Root Cause Health Check Gap	Tìm tại sao gap > 10 thay vì nới threshold lên 15	🔴 Critical
3	Hoàn thiện Label Wiring (TD-157/159)	Khôi phục logic "Cùng nhóm" cho 22 entities bị mất nhãn	🔴 Critical
4	Thêm Modify/Delete vào Lifecycle	Xây dựng quy trình "khai tử" và "chuyển hộ khẩu" cho thực thể	🟡 Warning
5	Deploy Prefect Orchestrator	Cần bộ não điều phối cho giai đoạn scale mạnh sắp tới	🟡 Warning
6	Hoàn thiện Layer 3 (Transitive/Peers)	Nâng cấp khả năng "tư duy mạng lưới" cho AI	🟡 Warning
7	Migrate Legacy Pages (TD-161)	Chuẩn hóa 6 heading cho Workflow/Module/Task detail	🟡 Warning
8	Implement Self-healing Pipeline	Tự động điền metadata và fix link hỏng (Auto-fix)	🟡 Warning
9	Hợp nhất CI Workflows	Tối ưu hóa hạ tầng và giảm noise từ các thông báo lặp	🟢 OK
10	Audit DOT Metadata Quality	Đảm bảo AI Agent luôn chọn đúng công cụ thông qua mô tả	🟢 OK

Báo cáo được thực hiện bởi Gemini CLI Agent.