Luật Tổ chức Lớp 3 — Hạ tầng Thông tin

LUẬT v3.0 | S122 (2026-03-15) — Patch: 4 sections → 6 heading nhất quán (S120 Huyen). +Scored union "Cùng nhóm" per-facet top N (S122 Luật Nhãn). +Layer 5 navigation (S118). +Nhãn = ĐẦU VÀO, Quan hệ 5+6 = ĐẦU RA. +entity_labels junction. Đây là LUẬT PHỨC TẠP NHẤT trong hệ thống Hiến pháp Kiến trúc. Nền tảng: Điều 0 (Thực thể Quản trị) — đọc TRƯỚC: search_knowledge("luật thực thể được quản trị") Liên quan: Điều 24 (Luật Nhãn) — nhãn là đầu vào, "Cùng nhóm" + "Tương tự" là đầu ra: search_knowledge("luật nhãn label law taxonomy") v2.0: Nâng từ 6 → 8 quy tắc (thêm DEPENDS_ON + TRANSITIVE). Cơ sở lý thuyết IT. Đọc: search_knowledge("luật lớp 3 hạ tầng thông tin") Phụ thuộc: Điều 2 (Registry), Điều 3 (Metadata), Điều 8 (Dependency), Điều 20 (Semantic Linking)

---

I. TẦM NHÌN

Mỗi object có ID trong hệ thống KHÔNG CHỈ LÀ 1 dòng data trong DB — nó phải là 1 DB VỀ CHÍNH NÓ.

Nguyên tắc dữ liệu quốc gia Việt Nam: "Đúng, đủ, sạch, sống":

Nguyên tắc	Ý nghĩa	Kiểm chứng
Đúng	Data khớp thực tế, không sai lệch	Orphan Scanner + Sync Governance
Đủ	Không thiếu quan hệ nào theo 8 QUY TẮC	dot-layer3-audit → coverage report
Sạch	Không trùng, không orphan, không rác	Duplicate Engine + Orphan Scanner
Sống	Tự cập nhật khi data thay đổi	Directus Flows + scheduled scan

Vị trí: Lớp 3 = ĐẠI DIỆN của Tầng 2 (Hạ tầng Thông tin). Tầng 1 = hạ tầng kỹ thuật. Tầng 2 = hạ tầng thông tin. Lớp 3 = GIAO DIỆN cho hạ tầng đó — phục vụ MỌI nhu cầu tương lai của Tầng 4 (Business).

---

II. CƠ SỞ LÝ THUYẾT — TẠI SAO 8 QUY TẮC

8 quy tắc không phải con số tuỳ ý — chúng bắt nguồn từ 3 nhánh lý thuyết cốt lõi trong IT:

Nhánh 1: Entity-Relationship Model (Peter Chen, 1976)

Nền tảng mọi database. Mọi quan hệ giữa entities thuộc 1 trong các loại:

• Is-a (kế thừa) → bao phủ bởi classification/PEERS
• Has-a (sở hữu) → bao phủ bởi CONTAINS
• Part-of (thuộc về) → bao phủ bởi BELONGS_TO
• Uses (sử dụng) → bao phủ bởi DEPENDS_ON ★
• Used-by (bị sử dụng) → bao phủ bởi USED_BY
• Associated-with (liên kết) → bao phủ bởi SIMILAR

Nhánh 2: Graph Theory (Euler → hiện đại)

Mọi hệ thống entities = 1 đồ thị (graph). Mỗi entity = node, mỗi quan hệ = edge.

• Direct edge (A→B) → 6 quy tắc trực tiếp (1-5, 7)
• Transitive closure (A→B→C ⟹ A~C) → bao phủ bởi TRANSITIVE ★
• Bidirectional → BELONGS_TO + CONTAINS là cặp ngược
• Weighted → SIMILAR có confidence score

Nhánh 3: Ontology / Semantic Web (OWL/RDF)

• TransitiveProperty: nếu A partOf B và B partOf C → A partOf C
• Directus relations = direct edges. Cần TÍNH TOÁN để có transitive.

Kết luận: 8 quy tắc bao phủ TOÀN BỘ lý thuyết quan hệ đã biết. Bất kỳ quan hệ thực tế nào cũng rơi vào 1 trong 8 loại.

---

III. 8 QUY TẮC QUAN HỆ PHỔ QUÁT

Nhóm A: BẢN THÂN (1 quy tắc)

Quy tắc 1: IDENTITY — "Tôi là ai?"

Metadata gốc: code, name, description, classification, status, owner, layer, dates.

• Nguồn: Registry collection item
• Luôn có: Mọi entity tuân thủ Điều 2+3
• Tự động: Đọc record by code → hiển thị

Nhóm B: QUAN HỆ CẤU TRÚC — Trực tiếp trong schema (3 quy tắc)

Quy tắc 2: BELONGS_TO — "Tôi thuộc về ai?" (↑ lên parent)

Quan hệ M2O hướng LÊN. Entity này là CON của ai?

• Nguồn: Directus relations — FK fields trỏ tới parent collection
• Ví dụ: ND-0001 → WF-001 (node thuộc workflow). Task → Module M-002.
• Phát hiện: Quét relations WHERE collection = entity's collection AND type = m2o

Quy tắc 3: CONTAINS — "Tôi chứa gì?" (↓ xuống children)

Quan hệ O2M ngược. Entity nào là CON của entity này?

• Nguồn: Directus relations — FK fields ở collections KHÁC trỏ về entity này
• Ví dụ: WF-001 chứa ND-0001..ND-0010. CPS-001 chứa CP-003, CP-005, CP-008.
• Phát hiện: Quét relations WHERE related_collection = entity's collection

Quy tắc 4: DEPENDS_ON — "Tôi cần gì để hoạt động?" (→ xuôi, functional) ★ MỚI

Quan hệ phụ thuộc CHỨC NĂNG hướng XUÔI. Khác BELONGS_TO (cấu trúc) — đây là "tôi SỬ DỤNG gì?".

• Nguồn: entity_dependencies WHERE source_code = entity's code
• Ví dụ: PG-015 depends_on collection workflows (đọc data từ đó). DOT-042 depends_on Admin token. DirectusTable depends_on table_registry config.
• Phát hiện: Query entity_dependencies WHERE source = entity
• Tại sao cần (tách khỏi BELONGS_TO): BELONGS_TO = "tôi NẰM TRONG parent" (cấu trúc cây). DEPENDS_ON = "tôi CẦN entity khác để HOẠT ĐỘNG" (đồ thị phụ thuộc). Page DEPENDS_ON collection nhưng KHÔNG BELONGS_TO collection. Nếu collection bị xoá → page hỏng → phải biết TRƯỚC.

Nhóm C: QUAN HỆ PHỤ THUỘC — Qua entity_dependencies (2 quy tắc)

Quy tắc 5: USED_BY — "Ai đang dùng tôi?" (← ngược)

Ngược của DEPENDS_ON. Entity nào phụ thuộc vào entity này?

• Nguồn: entity_dependencies WHERE target_code = entity's code
• Ví dụ: Collection workflows used_by PG-015, PG-020, DOT-042.
• Phát hiện: Query entity_dependencies WHERE target = entity
• Quan trọng cho deprecate/retire: Trước khi retire entity → query USED_BY → nếu > 0 → CHẶN retire, phải migrate trước.

Quy tắc 6: TRANSITIVE — "Ai liên quan tới tôi qua trung gian?" (→→→ bắc cầu) ★ MỚI

Quan hệ BẮC CẦU: A→B→C ⟹ A liên quan C. Đây là "quan hệ thứ cấp" Huyen nêu.

• Nguồn: TÍNH TOÁN từ entity_dependencies — duyệt đồ thị N bước (max depth = 3)
• Ví dụ: CP-005 → CPS-001 (belongs_to) → ND-0007 (used_by) → WF-001 (belongs_to). Vậy CP-005 liên quan WF-001 qua 3 bước. Hiển thị: "CP-005 → ... → WF-001 (qua CPS-001, ND-0007)".
• Phát hiện: BFS/DFS trên entity_dependencies graph, depth ≤ 3
• Hiển thị: "Liên quan gián tiếp" — danh sách entities + path ngắn nhất
• Tại sao cần: Đây chính là mô hình Wikipedia. User click CP-005 → thấy ngay WF-001 liên quan (dù không trực tiếp) → click WF-001 → thấy modules liên quan → vòng lặp. Nếu chỉ có direct relations → phải click 3 lần mới tới WF-001. Transitive cho phép NHÌN THẤY toàn cảnh ngay.
• Giới hạn: Max depth = 3 (đủ cho 99% cases, tránh explosion). Chỉ hiện top-10 entities gần nhất.

Nhóm D: QUAN HỆ NGẦM — Phát hiện tự động (2 quy tắc)

Quy tắc 7: PEERS — "Ai giống tôi?" (↔ ngang)

Entity cùng NHÓM: cùng classification, category, layer, owner, parent.

• Nguồn: Query cùng collection WHERE field = same value AND id ≠ self
• Ví dụ: CP-005 cùng category="ci" → CP-001, CP-003, CP-012.
• Phát hiện: Đọc entity's classification fields → query peers
• Không cần entity_dependencies: Query realtime, không cần lưu trước.

Quy tắc 8: SIMILAR — "Ai liên quan ngữ nghĩa?" (~ gần)

Entity có description/purpose TƯƠNG TỰ nhưng KHÁC TYPE.

• Nguồn: Qdrant vector search cross-type
• Ví dụ: CP-005 "Code Review" ≈ DOT-042 "dot-health-check" (0.89)
• Giai đoạn: Triển khai SAU khi Quy tắc 1-7 ổn định.

---

IV. BẢNG INDEX NGUYÊN TẮC QUAN HỆ

8 quy tắc phổ quát. Mọi quan hệ trong thế giới thực đều rơi vào 1 trong 8 loại.

#	Quy tắc	Nhóm	Hướng	Nguồn	Phát hiện tự động
1	IDENTITY	A: Bản thân	—	Registry item	Đọc record
2	BELONGS_TO	B: Cấu trúc	↑ lên	Directus M2O	Quét FK fields
3	CONTAINS	B: Cấu trúc	↓ xuống	Directus O2M	Quét reverse FK
4	DEPENDS_ON	C: Phụ thuộc	→ xuôi	entity_dependencies	source = entity
5	USED_BY	C: Phụ thuộc	← ngược	entity_dependencies	target = entity
6	TRANSITIVE	C: Phụ thuộc	→→→ bắc cầu	entity_dependencies graph	BFS depth ≤ 3
7	PEERS	D: Ngầm	↔ ngang	Cùng collection	Query same field value
8	SIMILAR	D: Ngầm	~ gần	Qdrant vectors	Cosine similarity ≥ 0.7

Quy trình khi phát hiện thiếu:

1. Kiểm tra 8 quy tắc → quy tắc nào bị vi phạm?
2. Quy tắc ĐỦ phổ quát → lỗi ở DOT/code → sửa DOT/code
3. Quy tắc CHƯA ĐỦ → bổ sung quy tắc → sửa áp dụng TOÀN HỆ THỐNG
4. KHÔNG BAO GIỜ sửa cho 1 object rồi bỏ qua phần còn lại

---

V. PHÂN LOẠI QUAN HỆ: TRỰC TIẾP vs BẮC CẦU vs NGẦM

┌─────────────────────────────────────────────────────────────────────┐
│                         CP-005 "Code Review"                        │
├───── TRỰC TIẾP (Nhóm B — đọc từ schema) ───────────────────────────┤
│  BELONGS_TO: CPS-001 (qua checkpoint_set_items)                     │
│  CONTAINS: — (leaf entity, không chứa con)                          │
├───── PHỤ THUỘC (Nhóm C — đọc từ entity_dependencies) ──────────────┤
│  DEPENDS_ON: — (checkpoint không phụ thuộc gì)                      │
│  USED_BY: CPS-001, CPS-005 (2 sets dùng CP này)                    │
│           ND-0007 (node gắn set chứa CP này)                       │
│  TRANSITIVE:                                                         │
│    CP-005 →[in]→ CPS-001 →[gắn]→ ND-0007 →[in]→ WF-001           │
│    ⟹ CP-005 liên quan WF-001 (depth=3, path: CPS-001→ND-0007)    │
│    CP-005 →[in]→ CPS-001 →[gắn]→ ND-0032 →[in]→ WF-002           │
│    ⟹ CP-005 liên quan WF-002 (depth=3)                             │
├───── NGẦM (Nhóm D — tính toán runtime) ────────────────────────────┤
│  PEERS: CP-001, CP-003, CP-012 (cùng category="ci")                │
│  SIMILAR: DOT-042 (0.89), PG-015 (0.82) — vector search           │
└─────────────────────────────────────────────────────────────────────┘

⟹ Chỉ từ 1 checkpoint, ta thấy TOÀN BỘ: sets, nodes, workflows,
   peers, tools liên quan. ĐÂY MỚI LÀ "1 DB VỀ CHÍNH NÓ".

---

VI. CƠ CHẾ TỰ ĐỘNG — "SỐNG"

6.1 dot-relation-discover — Phát hiện quan hệ

Quét Directus schema → populate entity_dependencies:

BƯỚC 1: Quét M2O relations → BELONGS_TO + CONTAINS
BƯỚC 2: Quét M2M junction tables → USED_BY pairs
BƯỚC 3: Quét functional dependencies (page→collection, DOT→token) → DEPENDS_ON
BƯỚC 4: So sánh → bổ sung thiếu (idempotent)

6.2 Transitive computation — Không cần lưu trước

Transitive KHÔNG lưu vào entity_dependencies (sẽ explode). Tính toán ON-DEMAND:

// API endpoint hoặc composable
async function getTransitive(entityCode, maxDepth = 3) {
  const visited = new Set()
  const results = []
  const queue = [{ code: entityCode, depth: 0, path: [] }]
  
  while (queue.length > 0) {
    const { code, depth, path } = queue.shift()
    if (depth > maxDepth || visited.has(code)) continue
    visited.add(code)
    
    // Query direct dependencies
    const deps = await directus.items('entity_dependencies').readByQuery({
      filter: { _or: [
        { source_code: { _eq: code } },
        { target_code: { _eq: code } }
      ]}
    })
    
    for (const dep of deps.data) {
      const neighbor = dep.source_code === code ? dep.target_code : dep.source_code
      if (!visited.has(neighbor)) {
        results.push({ code: neighbor, depth: depth + 1, path: [...path, code] })
        queue.push({ code: neighbor, depth: depth + 1, path: [...path, code] })
      }
    }
  }
  return results.filter(r => r.depth > 1) // Chỉ lấy indirect (depth > 1)
}

Performance: entity_dependencies ~200 records → BFS depth 3 = milliseconds. Khi 10.000 records → cache kết quả, recompute daily.

6.3 Tự mở rộng

Thêm entity MỚI:
  → Auto-ID flow gán code ✅
  → Đăng ký registry ✅
  → Lớp 3 trang TỰ HIỆN (discovery mode) ✅
  
Thêm relation MỚI (vd: gắn CP vào CPS):
  → dot-relation-discover (scheduled) → entity_dependencies cập nhật ✅
  → Lớp 3 của CẢ HAI entities tự cập nhật (USED_BY + CONTAINS) ✅
  → Transitive tự tính lại (on-demand) ✅
  
XOÁ / RETIRE:
  → Query USED_BY → nếu > 0 → CHẶN ✅
  → Retire → status = "retired" → Lớp 3 vẫn hiện nhưng đánh dấu ✅
  
KHÔNG AI SỬA CODE. HỆ THỐNG TỰ SỐNG.

6.4 dot-layer3-audit — Kiểm tra "Đúng đủ sạch sống"

Cho MỖI entity (sample per registry):
  ☐ ĐÚNG: Record tồn tại? Metadata đủ?
  ☐ ĐỦ: 8 quy tắc — bao nhiêu applicable? bao nhiêu có data?
  ☐ SẠCH: Dependencies trỏ tới entity đã retired?
  ☐ SỐNG: entity_dependencies date_updated < 24h?

Score: N/M applicable rules PASS
Output: Coverage Report per registry + tổng hợp

---

VII. LỚP 3 UI — RENDERING ENGINE

7.1 Discovery-First

1 Vue page DUY NHẤT render TẤT CẢ entity types:

entityType + id (từ URL)
  → Map → registry collection (qua meta_catalog)
  → Query entity (Quy tắc 1: Identity)
  → Query Directus relations (Quy tắc 2-3: Belongs_to + Contains)
  → Query entity_dependencies source (Quy tắc 4: Depends_on)
  → Query entity_dependencies target (Quy tắc 5: Used_by)
  → Compute transitive (Quy tắc 6: BFS depth ≤ 3)
  → Query peers (Quy tắc 7: cùng classification)
  → [Future] Vector search (Quy tắc 8: Similar)
  → Render sections — trống → ẩn

Discovery = DEFAULT. Config = OVERRIDE cho tuỳ chỉnh.

7.2 Auto-Link + Permissions

• PREFIX-NNN → NuxtLink tự động (mapping từ meta_catalog)
• Section đọc Directus API → 403/empty → ẩn. Directus permissions = đủ.

---

VIII. NGUYÊN TẮC BẢO TRÌ

1. Thiếu thông tin → kiểm tra 8 quy tắc. Không sửa 1 object. Sửa quy tắc/DOT → toàn hệ thống.
2. Entity type mới → KHÔNG viết config. Discovery tự hiện.
3. Relation type mới → kiểm tra 8 quy tắc bao phủ chưa. (Rất hiếm phải thêm.)
4. Scale 10.000 entities → không thay đổi gì. BFS cache + Directus pagination.
5. Section thêm tay → cho phép SAU khi discovery ổn. Config override cho từng entity type.
6. Link ưu tiên (S107 — Huyen): Nếu entity ĐÃ CÓ dedicated page/UI trong hệ thống (workflows có /knowledge/workflows/{id}, modules có /knowledge/modules/{id}) → Lớp 3 PHẢI hiện link tới page đó ở VỊ TRÍ ĐẦU TIÊN (ngay sau Identity). Discovery BỔ SUNG thông tin quan hệ — KHÔNG THAY THẾ UI đã xây.

---

Luật Tổ chức Lớp 3 v2.0 | S107 (2026-03-08) Cơ sở: Entity-Relationship Model (Chen 1976) + Graph Theory + Ontology (OWL/RDF) Tác giả: Huyen (tầm nhìn "Đúng đủ sạch sống", quan hệ bắc cầu) + Claude (8 quy tắc phổ quát)