ARCHITECTURE AUDIT — Claude — 2026-03-15

Phạm vi: Đánh giá toàn diện hệ thống Incomex sau S105→S123 (~65 PRs) Tài liệu đã đọc: 14 documents (Hiến pháp, Operating Rules, 12 architecture laws + SSOT docs) Phương pháp: Đọc tài liệu → so sánh production → đánh giá 5 góc

TÓM TẮT

🔴 Critical: 5 vấn đề
🟡 Warning: 8 vấn đề
🟢 OK: 7 lĩnh vực

I. NHẤT QUÁN GIỮA CÁC TÀI LIỆU

🟢 Hiến pháp 25 Điều — Nhất quán nội bộ

Không phát hiện mâu thuẫn logic giữa các Điều. Điều 0 (Thực thể) → Điều 0-B (Cấu tạo) → Điều 21 (Quan hệ) → Điều 24 (Nhãn) tạo thành chuỗi logic liền mạch: nhận diện → phân tầng → quan hệ → phân loại.

🟡 Operating Rules v4.22 vs Hiến pháp

§II Assembly Gate ghi 6 câu hỏi nhưng .claude/skills/incomex-rules.md ghi 5 câu. Lệch 1 câu.
§VI DOT 100% ghi "MỌI thao tác schema qua DOT" nhưng S122-S123 thực tế phải ALTER TABLE trực tiếp vì Directus API không tạo đủ columns (field searchable required). Operating Rules chưa ghi nhận ngoại lệ này.
§IV 2-Mũ ghi "KHÔNG dừng giữa chừng" nhưng thực tế PG changes phải apply TRƯỚC deploy (vì schema phải có sẵn). Quy trình thực tế = 3 giai đoạn (PG → code → deploy), chưa phản ánh trong rules.

🔴 Số liệu giữa tài liệu KHÔNG KHỚP

Roadmap ghi "1380 atoms" (S111) nhưng production hiện có 1438 entity codes (v_all_entity_codes). Chênh 58 — do S122-S123 thêm 55 taxonomy + workflow/table_registry. Roadmap CHƯA cập nhật cho S122-S123.
Roadmap ghi "84+ Directus flows" nhưng production có 127 flows (123 active). Chênh 43 — do S122-S123 thêm 15 changelog flows + không rõ khi nào cập nhật.
Tech-debt ghi TD-157 "22 entities thiếu labels" nhưng S123-FIX đã fix. TD status = 🟡 nhưng nên ✅.
Current-state index.md chưa cập nhật S121-S123. Last entry = S120.

🟡 Thuật ngữ "Lớp"/"Tầng"/"Layer"

Hiến pháp Điều 0-B dùng "Lớp" (Lớp nguyên tử, Lớp phân tử) cho composition levels.
5-layers.md dùng "Tầng" cho architecture layers (Tầng 1-5).
Operating Rules dùng cả "Tầng" lẫn "Lớp".
S117 (PR #501) đã sửa UI dùng "Lớp" thay "Tầng" cho composition levels — ĐÚNG.
Nhưng 5-layers.md vẫn dùng "Tầng" cho architecture layers — cũng đúng vì đây là nghĩa khác.
Kết luận: Đã tốt hơn, nhưng cần ghi rõ trong glossary: "Lớp" = composition level, "Tầng" = architecture layer.

II. LỖ HỔNG KIẾN TRÚC

🔴 fn_auto_label_assignment vẫn hardcode field names

S123-FIX đã fix COALESCE(code, process_code, table_id). Nhưng nếu tương lai có collection dùng field khác (ví dụ slug, key, identifier) thì function lại phải ALTER. Luật Nhãn v1.3 Section V.3 ghi "data-driven to_jsonb" nhưng code field mapping vẫn hardcoded.

Đề xuất: Thêm cột code_column vào meta_catalog (đã có trong v_registry_counts), function đọc từ đó thay vì COALESCE 3 tên cứng.

🟡 Entity lifecycle: MODIFY/DELETE chưa có script

Entity-lifecycle.md Section "QUY TRÌNH SỬA" và "QUY TRÌNH XOÁ" mô tả chi tiết nhưng dot-entity-deprecate, dot-entity-retire CHƯA TỒN TẠI. Đây là Điểm gãy #3 từ automation-gaps — vẫn chưa fix sau 10 sessions.

🟡 Scale concern: entity_labels JOIN performance

1893 entity_labels hiện tại OK. Nhưng "Cùng nhóm" query hiện làm client-side (2 Directus API calls + JS aggregation). Khi scale 20K+ labels, client-side scoring sẽ chậm. Cần server-side PG function hoặc materialized view.

🟡 v_all_entity_codes VIEW — manual maintenance

Luật Nhãn v1.3 ghi "ALTER VIEW mỗi khi thêm table mới" — chấp nhận được. Nhưng KHÔNG CÓ guard: nếu ai thêm managed collection mới mà quên ALTER VIEW → entity orphan ẩn. Cần DOT check hoặc CI guard.

🟢 PG Constraints — Solid

Composite FK same-facet, cycle detection, replaced_by validation, NULL bypass sealed (GPT R3). Tất cả đều tested OK.

🟢 system_issues lifecycle

open/resolved/archived + partial index + count trigger counting only open. Thiết kế solid.

III. NỢ KỸ THUẬT

🔴 738 system_issues ALL status='open' — Zero triage

Tất cả 738 issues đều status='open'. Không có resolved, không có archived. Điều này cho thấy:

Hệ thống phát hiện issues nhưng KHÔNG AI review/resolve chúng
Hoặc issues cũ từ trước khi có lifecycle cần bulk triage
Số 738 hiển thị trên Layer 1 sẽ gây "alert fatigue" — user thấy 738 → bỏ qua hết

Đề xuất: Bulk triage session: review 738 issues → resolve/archive issues cũ/không còn relevant.

🟡 Health Check fix bằng nới threshold — NOT root cause fix

S123-FIX nới sync gap 10→15. Nhưng:

Tại sao AD=188 nhưng Directus=200? 12 docs gap CHÍNH XÁC là gì?
Có phải do S122-S123 upload reports tới AD nhưng Directus không nhận?
Hay ngược lại: docs tạo trong Directus không sync về AD?
TD-165 ghi "GỐC CHƯA RÕ" — vẫn chưa rõ.

🟡 TDs đã resolve nhưng có thể chưa resolve thật

TD-136 (17 TRIGGER đếm): verify_counts()=0 MISMATCH nhưng S123-FIX phát hiện CAT-017 (system_issues) KHÔNG CÓ trong v_registry_counts ban đầu. Trigger đếm có nhưng v_registry_counts entry thiếu → verify_counts() báo OK vì không check table đó. Đã fix nhưng pattern cho thấy: verify_counts() chỉ check bảng ĐÃ ĐĂNG KÝ, không phát hiện bảng THIẾU ĐĂNG KÝ.
TD-150/151 (S121): Đánh ✅ nhưng S123-FIX phát hiện SYS-LBL=0 trên production. Agent báo PASS nhưng không verify trực quan.

🔴 Pattern lỗi lặp lại: "Agent báo PASS nhưng production sai" — 7 lần

Đây là vấn đề NGHIÊM TRỌNG NHẤT. Pattern:

Agent chạy script → script trả "OK" → agent báo PASS
Thực tế production: UI hiện sai, data thiếu, wiring chưa kết nối
User phải phát hiện bằng mắt → yêu cầu fix

Nguyên nhân gốc: Operating Rules §VERIFY TRỰC QUAN viết "ghi PASS/FAIL từng mục" nhưng KHÔNG CÓ enforcement. Agent có thể skip verify trực quan mà không bị chặn.

Đề xuất: Thêm vào Operating Rules: "Verify trực quan = CURL trang production → parse HTML → check số/text CỤ THỂ. KHÔNG chấp nhận script output = verification."

🟡 TDs thiếu (vấn đề đã thấy chưa ghi TD)

Directus field searchable required — Directus 11.x yêu cầu searchable trong field meta khi tạo collection. Không ghi trong Operating Rules hay tech-debt. Sẽ lặp lại khi tạo collection mới.
SSR vs CSR data availability — Layer 1 taxonomyCount failed SSR vì permission. Chưa có rule: "data hiển thị trên SSR pages PHẢI accessible bằng service token hoặc public."
v_registry_counts sequence conflict — INSERT vào v_registry_counts gặp PK conflict vì sequence không sync. Cần setval() guard.

IV. AUTOMATION GAPS

🟡 Điểm gãy #3 (MODIFY/DELETE scripts) — Vẫn chưa fix (10 sessions)

Entity-lifecycle.md mô tả chi tiết quy trình Sửa/Xoá nhưng dot-entity-deprecate, dot-entity-retire chưa tạo. Khi cần deprecate entity → agent làm tay → vi phạm Điều 4 (DOT 100%).

🟡 Điểm gãy #10 (Self-healing) — Chỉ DETECT, không APPLY

Pipeline hiện: DETECT → ALERT (tạo system_issues). Thiếu: CLASSIFY → PROPOSE → APPLY → VERIFY. 738 open issues chứng minh: detect nhiều, fix không.

🟢 DOT Scanning — Coverage đã tốt

4 PG audit functions: verify_counts(), check_registry_coverage(), audit_relationships(), audit_dead_links(). 18 auto-label triggers. 108 DOT tools registered. Coverage reasonable cho Phase 2.

🟡 Auto-assign labels — Functional nhưng incomplete

18 triggers covering 18 tables (16 original + workflows + table_registry)
Nhưng title field check added cho UPDATE guard nhưng nhiều tables không có title — guard sẽ không bao giờ fire cho name-only tables bị rename-only UPDATE. Minor issue vì name changes trigger fire correctly.
checkpoint_instances và registry_changelog trigger = AFTER INSERT only (no name/desc) — chỉ collection rules, không keyword. Đúng theo design.

V. ĐỀ XUẤT CẢI TIẾN

Nên ĐƠN GIẢN HOÁ

v_registry_counts: Hiện tại là TABLE + manually managed entries. Nên là VIEW hoặc function tự generate entries từ meta_catalog — tránh sequence conflicts và missing entries.
Directus Flows: 127 flows (123 active). Nhiều flows có thể gộp bằng generic webhook. Nhưng Directus 11.x limitations (no isolated-vm) makes this impractical now.

Nên GỘP hoặc XOÁ

Current-state/index.md chưa cập nhật S121-S123. Nên auto-generate từ PG data thay vì manual.
Roadmap metrics (1380 atoms, 84 flows) outdated. Nên link to live PG counts.
5-layers.md và Hiến pháp index.md có overlap. 5-layers tóm tắt, Hiến pháp chi tiết. OK giữ cả hai nhưng cần cross-reference rõ hơn.

Nên THÊM quy trình

Collection creation checklist (CI-enforceable): Khi DOT script tạo collection mới → CI check: meta_catalog entry? v_registry_counts entry? count trigger? changelog flows? AI Agent permissions? v_all_entity_codes updated?
Visual verification protocol: curl production → parse specific numbers → assert in CI.

TOP 10 KIẾN NGHỊ (xếp theo ưu tiên)

#	Kiến nghị	Lý do	Mức
1	Bulk triage 738 system_issues — resolve/archive old issues	738 all-open = alert fatigue, số trên Layer 1 gây hoang mang	🔴
2	Cập nhật current-state + roadmap + tech-debt cho S121-S123	3 docs outdated, số liệu lệch thực tế 30-40%	🔴
3	Thêm "Collection Creation Checklist" vào Operating Rules	7 lần collections mới thiếu wiring (trigger/count/changelog/permissions/VIEW)	🔴
4	Fix sync gap root cause (TD-165) thay vì nới threshold	Nới threshold = giấu vấn đề. Gap sẽ tăng dần → lại đỏ	🔴
5	Codify visual verification trong Operating Rules	Pattern "agent báo PASS sai" 7 lần — cần enforcement	🔴
6	fn_auto_label_assignment đọc code_column từ meta_catalog	COALESCE hardcode 3 tên → sẽ lại thiếu khi thêm collection mới	🟡
7	Tạo dot-entity-deprecate + dot-entity-retire	Điểm gãy #3 chưa fix 10 sessions, entity chỉ biết sinh không biết xoá	🟡
8	Gộp verify_counts() + check_registry_coverage() thành 1 health function	Nhiều scripts riêng lẻ, cần 1 unified health check PG function	🟡
9	v_registry_counts → auto-generate từ meta_catalog	Manual INSERT gây PK conflicts, missing entries	🟡
10	Thêm glossary "Lớp vs Tầng" vào Operating Rules	Dễ lẫn, cần 1 định nghĩa chính thức	🟢

PHỤ LỤC: METRICS SNAPSHOT (2026-03-15 post-S123)

Metric	Value
Total PRs (S105-S123)	~65
meta_catalog entries	27
v_registry_counts entries	19
entity_labels	1,893
taxonomy labels	55
label_rules	32
entity_dependencies	254
DOT tools	108
system_issues (open)	738
v_all_entity_codes	1,438
Directus flows (active/total)	123/127
PG auto-label triggers	18
verify_counts() mismatches	0
Hiến pháp version	v3.5 (25 Điều)
Operating Rules version	v4.22

Audit completed: 2026-03-15 by Claude Opus 4.6. No changes made — report only.