ℹ️ TAI LIEU NAY DUNG — CHI TIEU DE GHI SAI PHIEN BAN

Day LA ban dang hieu luc. normative_registry ghi Dieu 0-B v3.1 enacted va kb_path tro dung vao tai lieu nay.

⚠️ Nhung dong tieu de H1 ben duoi ghi "v3.0" trong khi than tai lieu ghi "LUẬT v3.1" va mo ta day du cac thay doi cua v3.1. Tieu de sai, noi dung dung.

=> Doc noi dung, dung tin dong tieu de. Neu can trich dan phien ban thi ghi v3.1.

Chua sua tieu de: dot 2026-07-29 chi dan nhan, khong sua noi dung tai lieu. HAN DUNG: tu 2027-01-29 nhan nay la GIA THUYET — DO LAI. CHI TIET: docs/BAN-DO-HE-THONG-20260729.md

ĐIỀU 0-B: LUẬT PHÂN TẦNG CẤU TẠO VẬT CHẤT THÔNG TIN v3.0

(Bổ sung Điều 0 Hiến pháp — Phân loại thực thể theo cấu tạo)

LUẬT v3.1 | S111 (2026-03-13) | Huyen phê duyệt + GPT/Gemini review Round 2 Điều 0 = Luật NHẬN DIỆN thực thể được quản trị (có ID + registry + metadata + Lớp 3) Điều 0-B = Luật PHÂN TẦNG CẤU TẠO của thực thể được quản trị v3.1: +Dọn legacy Điều 0. +3 lớp quản lý (managed/native/sub-atomic). +CI/CD Guard tầng 4. +FK=cấu trúc, DEP=chức năng. +Natural key cho Field. +DEP=atom quan hệ. Mọi nguyên tử, phân tử, hợp chất đều là "thực thể được quản trị". Nhưng KHÔNG phải mọi thực thể đều là "nguyên tử". Đọc: search_knowledge("luật phân tầng cấu tạo vật chất thông tin") Đọc kèm: search_knowledge("luật nguyên tử thông tin") (Điều 0 — nhận diện)

QUY ƯỚC THUẬT NGỮ (Huyen quyết định S117 — 2026-03-13)

Khái niệm	Từ ĐÚNG	Ví dụ
6 cấp cấu tạo (Điều 0-B)	Lớp	Lớp nguyên tử, Lớp phân tử, Lớp hợp chất
5 cấp kiến trúc (Điều 5)	Tầng	Tầng 1 Hạ tầng, Tầng 2 Registry

KHÔNG lẫn lộn. "Tầng nguyên tử" = SAI. "Lớp nguyên tử" = ĐÚNG.

I. HOÀ GIẢI ĐIỀU 0 VÀ ĐIỀU 0-B

Hai luật, hai vai trò:

	Điều 0	Điều 0-B
Vai trò	Luật NHẬN DIỆN	Luật PHÂN TẦNG CẤU TẠO
Câu hỏi	"Thứ này có được quản trị không?"	"Thứ này thuộc tầng nào?"
Tiêu chí	Có ID + registry + metadata + Lớp 3	Cấu tạo: chứa gì bên trong?
Thuật ngữ	Thực thể được quản trị (managed entity)	Nguyên tử / Phân tử / Hợp chất / ...
Áp dụng	MỌI entity có PREFIX-NNN	Phân loại entity đó vào đúng tầng

"Nguyên tử" CHỈ dùng cho Tầng 1 — entity không chứa entity khác. WF-001 là thực thể được quản trị (Điều 0) và là hợp chất (Điều 0-B). KHÔNG gọi là "nguyên tử".

Hai field trong meta_catalog:

Field	Vai trò	Giá trị
`identity_class`	Điều 0 — nhận diện	managed (được quản trị), log (nhật ký), virtual (ảo)
`composition_level`	Điều 0-B — cấu tạo	atom, molecule, compound, material, product, building

I-B. BA LỚP QUẢN LÝ (GPT Round 2 — Huyen + Claude đồng ý)

Không phải mọi "nguyên tử cấu tạo" đều cần quản lý giống nhau:

Lớp	Tên	ID	Registry	Lớp 3	Ví dụ
1	Managed Entity chuẩn	PREFIX-NNN (PG TRIGGER)	meta_catalog	Trang riêng per entity	CP-005, WF-001, DOT-042
2	Native-managed Resource	Natural key (Directus quản lý)	Đếm bằng PG VIEW	Lớp 3 bulk per collection	Field (`collection.field_name`)
3	Sub-atomic Artifact	Không có ID	Không registry	Không Lớp 3	Field values, activity logs

Field = Lớp 2 (Native-managed Resource):

Nguyên tử VỀ CẤU TẠO (Điều 0-B Tầng 1)
NHƯNG Directus đã quản lý sẵn (directus_fields)
Natural key = collection.field_name (đã unique — Gemini đề xuất)
Đếm bằng PG VIEW v_field_atoms (không gán FLD prefix)
Lớp 3 = danh sách fields per collection (bulk, không per-field page)
Focus ~400-500 fields nghiệp vụ (Huyen xác nhận)

Quy tắc: Khi Directus (hoặc PG system) đã quản lý 1 loại entity → dùng Lớp 2. Không tạo hệ thống song song.

I-C. RULE QUAN HỆ: FK/M2M vs ENTITY_DEPENDENCIES (Gemini Round 2)

Loại quan hệ	Cơ chế	Khi nào dùng	Độ tin cậy
Cấu trúc (Structural)	FK/M2M native trong Directus	"A chứa B", "B thuộc A" — cùng DB	100% (DB enforce)
Chức năng (Functional)	entity_dependencies	"Page X hiển thị Collection Y", "Script Z đọc Secret W" — cross-type	Soft (DOT scan)

Rule: Ưu tiên FK/M2M native. CHỈ dùng entity_dependencies khi không thể tạo FK (cross-database, trỏ vào file/secret, cross-type không có FK).

Câu hỏi duy nhất: Entity này chứa gì bên trong?

Chứa gì	→ Lớp	Badge
Chỉ chứa hạ nguyên tử (metadata, field values)	🟢 Nguyên tử (Atom)	Lớp 1
Chứa nguyên tử, KHÔNG có quy trình/logic	🔵 Phân tử (Molecule)	Lớp 2
Chứa phân tử + nguyên tử + CÓ quy trình/logic	🟣 Hợp chất (Compound)	Lớp 3
Hợp chất đã chuẩn hoá, tái sử dụng	🟠 Vật liệu (Material)	Lớp 4
Vật liệu đang chạy cho đối tượng cụ thể	🔶 Sản phẩm (Product)	Lớp 5
Toàn bộ mảng kinh doanh	🔷 Công trình (Building)	Lớp 6

Edge cases — Quy tắc quyết định:

Entity	Nếu chỉ config/data →	Nếu có logic/quy trình →
ND (Node)	🔵 Phân tử (hiện tại)	🟣 Hợp chất (khi thêm guards/state logic)
PG (Page)	🔵 Phân tử (hiện tại)	🟣 Hợp chất (khi có loader/orchestration)
M (Module)	🔵 Phân tử (presentational)	🟣 Hợp chất (có điều phối — M-001, M-002)

Cho phép NÂNG CẤP tầng khi complexity tăng. Ghi nhận trong meta_catalog. Giống vật lý: thay đổi trạng thái khi điều kiện thay đổi.

Rule đổi tầng (GPT Round 2):

Đề xuất đổi tầng → ghi WCR (đề xuất thay đổi)
Review: entity có thêm logic/quy trình? → duyệt
Sửa composition_level trong meta_catalog
Lớp 3 tự động thay đổi hiển thị (theo tầng mới)
CHỈ NÂNG, KHÔNG HẠ (phân tử không quay lại nguyên tử — complexity chỉ tăng)

III. PHÂN LOẠI CHÍNH THỨC

Lớp 0: HẠ NGUYÊN TỬ (Quark)

Thành phần bên trong nguyên tử. Không có ID riêng. Thuộc về cha.

Loại	Ví dụ	PG có sẵn
Field values	CP-005.status = "active"	Collection tables
Field metadata	format, interface, validation	`directus_fields` ★ Directus quản lý sẵn
Sự kiện sửa/add	"User sửa CP-005 lúc 10:30"	`directus_activity` + `directus_revisions` ★

★ Assembly First: Directus + PG đã quản lý. KHÔNG tạo hệ thống mới.

Lớp 1: NGUYÊN TỬ (Atom) — 🟢

Đơn vị nhỏ nhất CÓ ID, tồn tại ĐỘC LẬP, KHÔNG chứa entity khác.

Prefix	Loại	Lý do = nguyên tử
CP	Checkpoint Type	1 định nghĩa kiểm tra đơn
DOT	DOT Tool	1 script đơn lẻ
AGT	Agent	1 agent đơn lẻ
DEP	Entity Dependency	1 quan hệ đơn — atom KIỂU QUAN HỆ (relationship atom), có metadata: lưu ý, điều kiện áp dụng. Nhiều DEP cho 1 mối quan hệ phức tạp → tổ hợp DEP = phân tử.
CMT	Comment	1 comment đơn lẻ, cần thống kê truy vết

Về Field (Trường): Field = nguyên tử quan trọng nhất VỀ CẤU TẠO. Tuy nhiên:

Thuộc Lớp 2 quản lý (Native-managed Resource) — Directus quản lý sẵn
Natural key = collection.field_name (unique, Gemini đề xuất VIEW v_field_atoms)
KHÔNG gán PREFIX FLD, KHÔNG sửa directus_fields system table
Đếm bằng PG VIEW, Lớp 3 hiển thị bulk per collection
Focus ~400-500 fields nghiệp vụ (Huyen), phân biệt system vs business (Gemini VIEW pattern)
Governance: bulk/template-managed (GPT review)

Lớp 2: PHÂN TỬ (Molecule) — 🔵

NHÓM nguyên tử gắn với nhau. Có ID riêng. KHÔNG có quy trình/logic phức tạp.

Prefix	Loại	Chứa nguyên tử nào
COL	Collection	Nhiều Fields
TBL	Bảng UI	Nhiều field configs
ND	Node/Bước quy trình	Config + gắn CPS (hiện tại = phân tử, có thể nâng cấp)
PG	Page/Route	Nhiều UI components (hiện tại = phân tử)
CPS	Checkpoint Set	Nhiều CP qua M2M
CPI	Checkpoint Instance	CP gắn vào context
CAT	Danh mục hệ thống	Metadata per loại
TP	Table Proposal	Danh sách fields đề xuất

Lớp 3: HỢP CHẤT (Compound) — 🟣

Chứa phân tử + nguyên tử + CÓ QUY TRÌNH / LOGIC ĐIỀU PHỐI.

Prefix	Loại	Chứa gì	Quy trình
WF	Workflow	ND + CPS + CP	State transitions, triggers
M	Module (có orchestration)	Components + logic	Render + điều phối phức tạp
TSK	Task	CMT + checkpoints + agents	Multi-agent orchestration
WCR	Đề xuất thay đổi	Nội dung + CMT + workflow duyệt	Đề xuất → thảo luận → duyệt → áp dụng

Lớp 4-6: VẬT LIỆU / SẢN PHẨM / CÔNG TRÌNH (tương lai)

Lớp	Vật lý	Incomex	Prefix	Status
4	Vật liệu	Journey Template — hợp chất chuẩn hoá	JT	❌ Chưa
5	Sản phẩm	Running Instance — đang chạy	—	❌ Chưa
6	Công trình	Business Operation — toàn mảng	DOM	❌ Chưa

IV. NGUYÊN TẮC "SỐNG" — LỚP 3 TỰ ĐỘNG CẬP NHẬT

"Đúng, đủ, sạch, SỐNG" = Thêm data → hiện. Bớt data → mất. Không cần ai cập nhật thủ công.

Cơ chế: PG FK/M2M + Query trực tiếp

Lớp 3 KHÔNG LƯU TRỮ kết quả — Lớp 3 QUERY TRỰC TIẾP từ PG:

Quan hệ	Query	Tự động?
"Tôi thuộc ai?"	JOIN FK ngược lên parent	✅
"Ai thuộc tôi?"	JOIN FK xuôi xuống children	✅
"Tôi dùng ai?"	entity_dependencies WHERE source=tôi	✅
"Ai dùng tôi?"	entity_dependencies WHERE target=tôi	✅
"Bắc cầu"	WITH RECURSIVE CTE depth ≤ 4 + CYCLE detection	✅
"Cùng loại"	WHERE collection = my_collection	✅

Quy tắc cứng:

Lớp 3 = QUERY, KHÔNG PHẢI CACHE (upgrade sang MATERIALIZED VIEW khi scale 10K+)
FK/M2M native = quan hệ chính. entity_dependencies = bổ sung cross-type.
CYCLE detection bắt buộc trong recursive CTE (CYCLE id SET is_cycle USING path — PG 14+) + WHERE depth <= 4 guardrail cứng (Gemini Round 2)
Indexes bắt buộc trên entity_dependencies (Gemini Round 2):
- idx_dep_source_target (source_id, target_id)
- idx_dep_target_source (target_id, source_id) (cho "Ai dùng tôi")
- idx_dep_type (relation_type) (filter nhanh)
Luồng: PG → Directus API → Nuxt. KHÔNG bypass Directus.

Lớp 3 thông tin KHÁC NHAU theo lớp cấu tạo:

Nguyên tử (CP-005):

Hạ nguyên tử: fields + trạng thái
Thuộc phân tử: "Nằm trong CPS-001, CPS-003" [links]
Thuộc hợp chất: "WF-001 qua ND-0007→CPS-001" [bắc cầu + links]

Phân tử (CPS-001):

Gồm nguyên tử: "CP-003, CP-005, CP-008" [danh sách + links]
Dùng ở hợp chất: "WF-001 qua ND-0007" [links]

Hợp chất (WF-001):

Cấu trúc tree: ND → CPS → CP (lồng ghép)
Tổng thành phần: "10 ND + 5 CPS + 31 CP"

V. QUẢN LÝ + SINH ID

PG TRIGGER cho collections nghiệp vụ (15 collections):

BEFORE INSERT → SEQUENCE + TRIGGER → auto-ID PREFIX-NNN
→ Không thể thiếu ID → 0 orphan by design

Field: KHÔNG dùng PG TRIGGER trên directus_fields

Directus quản lý sẵn (system table, internal cache)
Đọc từ PG, đếm bằng VIEW, hiển thị bulk per collection
Natural key = collection_name + field_name (đã unique)

Enforcement 4 tầng (Gemini Round 1+2):

DB: CHECK (composition_level IN ('atom','molecule','compound','material','product','building')) trên meta_catalog
DOT: Script bắt buộc flag --level khi tạo entity mới
Directus: Validation chặn insert meta_catalog nếu composition_level = null
CI/CD Guard (Gemini Round 2): GitHub Action chạy dot-registry-integrity-check — nếu collection mới trong schema snapshot mà không có entry + composition_level trong meta_catalog → FAIL CI

VI. ĐẾM RIÊNG TỪNG LỚP — TẤT CẢ TỪ PG

Registries hiển thị:

THỰC THỂ ĐƯỢC QUẢN TRỊ
  🟢 Lớp nguyên tử: X (5 loại)     → [danh sách chi tiết]
  🔵 Lớp phân tử: Y (8 loại)       → [danh sách chi tiết]  
  🟣 Lớp hợp chất: Z (4 loại)      → [danh sách chi tiết]
  
  📊 Fields: ~400 nghiệp vụ (Directus quản lý)
  ⚫ Log: 2 loại (không đếm vào tổng)

PG VIEW đếm per level:

SELECT composition_level, 
       COUNT(*) as type_count,
       SUM(record_count) as total_entities
FROM v_registry_counts
GROUP BY composition_level;

Dynamic SQL (Gemini đề xuất — TD tương lai):

Thay UNION ALL hardcoded bằng function đọc meta_catalog → tự build query. Scale tự động khi thêm loại mới.

VII. SẢN XUẤT = LẮP RÁP TỪ DƯỚI LÊN

Cần CÔNG TRÌNH → kiểm kho VẬT LIỆU → thiếu → sản xuất
  → Cần HỢP CHẤT → kiểm kho → thiếu → lắp ráp
    → Cần PHÂN TỬ → kiểm kho → thiếu → tổ hợp
      → Cần NGUYÊN TỬ → kiểm kho → thiếu → tạo

"Có ÍT vật liệu mà xây được NHIỀU công trình mới GIỎI." (Huyen)
Nguyên tắc Lắp ráp Tối đa bao trùm TẤT CẢ tầng.

Điều 0-B v3.1 | S111 (2026-03-13) | Huyen phê duyệt + GPT/Gemini review Round 1+2 Hoà giải Điều 0 (nhận diện) + Điều 0-B (phân tầng). 3 lớp quản lý. 4 tầng enforcement. "Nguyên tử" = CHỈ Tầng 1 cấu tạo. FK = cấu trúc, DEP = chức năng. Field = native-managed.