Semantic Linking Engine — Kiến trúc Vòng lặp Vô tận

SSOT v2.0 | S122 (2026-03-15) — Patch: 4 sections → 6 heading nhất quán (S120). +Layer 5 navigation (S118). +"Cùng nhóm" = scored union per-facet top N (S122 Luật Nhãn v1.3). +"Tương tự" = vector search + nhãn signal. +Nhãn = ĐẦU VÀO, Quan hệ heading 5+6 = ĐẦU RA. Lưu ý: Document này mô tả technical implementation. Nguyên tắc phổ quát (8 quy tắc): search_knowledge("luật lớp 3 hạ tầng thông tin") Liên quan: Luật Nhãn (Điều 24): search_knowledge("luật nhãn label law taxonomy") Đọc: search_knowledge("semantic linking engine vòng lặp") Phụ thuộc: Điều 2 (Registry), Điều 3 (Metadata), Điều 8 (Dependency), Điều 14 (Chống trùng), Điều 19 (Orphan Scanner)

1. BÀI TOÁN

Hệ thống đã có ID cho mọi thực thể (Tầng 1-3 trong 4 tầng kiểm soát). Nhưng ID một mình = danh sách rời rạc. Giá trị thực sự xuất hiện khi ID được KẾT NỐI — mỗi thực thể biết mình liên quan tới ai, click vào → trang mới → link mới → vòng lặp không bao giờ kết thúc, giống Wikipedia.

Mô hình Wikipedia: Mỗi bài viết (entity) chứa link tới bài khác. Mỗi bài khác link ngược lại. Không có "trang cuối cùng". Đi tới đâu cũng có đường đi tiếp. Mạng lưới tri thức tự mở rộng vô tận.

2. VỊ TRÍ TRONG HỆ THỐNG KIỂM SOÁT

┌─────────────────────────────────────────────────────────────────┐
│ TẦNG 1: BIRTH REGISTRY       "Sinh ra phải có ID"      ✅ DONE │
│ TẦNG 2: ORPHAN SCANNER       "Tìm mồ côi"             ✅ DONE │
│ TẦNG 3: DUPLICATE ENGINE     "Không trùng"             🔴 OPEN │
│ TẦNG 4: SEMANTIC LINKER      "Nếu liên quan → kết nối" 🔴 MỚI │
└─────────────────────────────────────────────────────────────────┘

Tầng 1-3 = MỌI THỨ CÓ ID + KHÔNG MỒ CÔI + KHÔNG TRÙNG. Tầng 4 = BIẾN ID THÀNH MẠNG LƯỚI. Đây là đích đến thực sự.

3. MAPPING: 3 LỚP KẾT NỐI → 8 QUY TẮC QUAN HỆ

Document trước đây mô tả 3 lớp kết nối (A: Explicit, B: Classification, C: Semantic). Luật Lớp 3 v2.0 nâng cấp thành 8 quy tắc phổ quát. Mapping:

3 Lớp cũ	8 Quy tắc mới	Ghi chú
Lớp A: Explicit Relations	Quy tắc 2 (BELONGS_TO) + 3 (CONTAINS) + 4 (DEPENDS_ON) + 5 (USED_BY)	Tách chi tiết hơn
— (thiếu)	Quy tắc 6 (TRANSITIVE)	★ MỚI — bắc cầu
Lớp B: Classification	Quy tắc 7 (PEERS)	Giống nhau
Lớp C: Semantic	Quy tắc 8 (SIMILAR)	Giống nhau
—	Quy tắc 1 (IDENTITY)	Luôn có

Mỗi entity có 3 loại liên kết, từ cứng → mềm:

Lớp A: EXPLICIT RELATIONS (Quan hệ cứng — Directus relations)

Quan hệ trực tiếp trong schema: parent/child, M2O, M2M, FK.

Ví dụ	Quan hệ	Cơ chế
CP-005 → CPS-001	checkpoint nằm trong set	`checkpoint_set_items` M2M
ND-0007 → WF-001	node thuộc workflow	`workflow_steps.workflow_id` M2O
CPS-001 → ND-0007	set gắn vào node	`workflow_steps.checkpoint_set_id` FK

Trạng thái: ĐÃ CÓ phần lớn trong Directus relations. Cần audit đầy đủ + bổ sung thiếu. Kỹ thuật đọc: directus_get_items với fields parameter, deep filter. Hiển thị: Section "Quan hệ trực tiếp" trên trang Lớp 3 — link click được.

Lớp B: CLASSIFICATION RELATIONS (Cùng nhóm = liên quan)

Entities cùng classification, category, layer, owner, status → tự động "liên quan".

Ví dụ	Tiêu chí	Kết quả
CP-005 + CP-012	Cùng `category: "ci"`	"Cùng nhóm CI"
DOT-042 + DOT-043	Cùng `category: "health"`	"Cùng nhóm Health"
ND-0007 + ND-0032	Cùng `layer: 1`	"Cùng tầng 1"

Trạng thái: Schema đã có classification, category, layer fields. Cần LOGIC trên UI. Kỹ thuật đọc: Directus filter: GET /items/{collection}?filter[category][_eq]={same_category}&filter[id][_neq]={self_id} Hiển thị: Section "Cùng nhóm" trên trang Lớp 3 — grouped by tiêu chí.

Lớp C: SEMANTIC RELATIONS (AI phát hiện — Vector Search)

Qdrant (vector DB) đã chạy trên VPS. Mỗi entity có description → embed → tìm entity tương tự bằng cosine similarity.

Ví dụ	Mô tả source	Kết quả tìm thấy	Score
CP-005 "Code Review Passed"	"kiểm tra code trước merge"	DOT-042 "dot-health-check"	0.89
PG-015 "/knowledge/workflows"	"trang quản lý quy trình"	WF-001 "Quy trình duyệt"	0.82

Trạng thái: Qdrant ĐÃ CÓ + Agent Data API có vector search. Cần: embed entity descriptions + API endpoint cross-reference. Kỹ thuật:

Embed: Mỗi entity có description → OpenAI/local embedding → store Qdrant collection entity_embeddings
Query: search_knowledge hoặc Qdrant API direct → top-K similar entities (khác type ưu tiên = cross-domain)
Cache: Kết quả pre-compute hàng ngày, store trong entity_cross_references (Directus collection) hoặc JSON field Hiển thị: Section "Liên quan ngữ nghĩa" trên trang Lớp 3 — với confidence score.

4. KIẾN TRÚC UI — TRANG "WIKIPEDIA" (LỚP 3 NÂNG CẤP)

4.1 Nguyên tắc thiết kế Lớp 3 — SECTION-BASED, CONFIG-DRIVEN

Mỗi trang detail entity (/knowledge/registries/[entityType]/[id]) gồm nhiều SECTION (mảng) ghép lại. Mỗi section là 1 khối UI độc lập, đọc data từ Directus API.

5 nguyên tắc bất biến:

Config, không code: Thêm entity type mới = thêm config object. KHÔNG viết Vue component mới.
Sections tự lắp ráp: Mỗi section type (fields, relation, dependency, classification, semantic) là 1 component tái sử dụng. Config chỉ nói "dùng section type nào, đọc collection nào, filter gì".
Links tự sinh: Mọi giá trị có format PREFIX-NNN tự động thành link clickable tới /knowledge/registries/[type]/[code]. Không khai báo link thủ công.
Permissions tự động: Mỗi section đọc từ 1 Directus collection → Directus permission tự quyết hiển thị hay ẩn. Super admin thấy mọi section, nhóm hạn chế chỉ thấy section có quyền. KHÔNG code permission riêng.
Vòng lặp tự nhiên: Mỗi link trong section → trang Lớp 3 khác → có sections riêng → link tiếp → vô tận.

4.2 Section Types (5 loại chuẩn)

Type	Mô tả	Data source	Ví dụ
`fields`	Hiển thị thông tin cơ bản của entity	Trực tiếp từ item hiện tại	code, name, description, status, owner
`relation`	Danh sách entities liên quan qua Directus relation (M2O, M2M)	Query collection con với filter	CP-005 nằm trong CPS-001, CPS-005
`dependency`	Danh sách entities liên kết qua entity_dependencies	Query `entity_dependencies` WHERE source/target = current	ND-0007 dùng CP-005, WF-001 chứa ND-0007
`classification`	Entities cùng nhóm (cùng category, layer, owner...)	Query cùng collection WHERE field = same value	Cùng category=ci: CP-001, CP-003, CP-012
`semantic`	Entities tương tự ngữ nghĩa (Qdrant vector search)	Agent Data search_knowledge hoặc Qdrant API	DOT-042 score 0.89, PG-015 score 0.82

4.3 Section Config Schema

// Lưu trong Directus collection `detail_section_configs` HOẶC JSON file
// Mỗi entity type = 1 array sections

const sectionConfig = {
  checkpoint_types: [
    { id: "info", type: "fields", label: "Thông tin cơ bản",
      fields: ["code","name","description","layer","category","status","owner"] },
    { id: "sets", type: "relation", label: "Thuộc tổ hợp",
      collection: "checkpoint_set_items", foreignKey: "type_id",
      displayField: "set_id.code", displayName: "set_id.name",
      linkType: "checkpoint_set", linkPrefix: "CPS" },
    { id: "nodes", type: "dependency", label: "Nodes dùng checkpoint này",
      direction: "reverse", matchField: "target_code" },
    { id: "instances", type: "relation", label: "Instances đã verify",
      collection: "checkpoint_instances", foreignKey: "checkpoint_type_id",
      count: true },
    { id: "same_category", type: "classification", label: "Cùng nhóm",
      groupBy: ["category", "layer"] },
    { id: "related", type: "semantic", label: "Liên quan ngữ nghĩa" }
  ],
  
  workflow_steps: [
    { id: "info", type: "fields", label: "Thông tin Node",
      fields: ["code","name","description","step_type","sort_order","status"] },
    { id: "workflow", type: "relation", label: "Thuộc quy trình",
      collection: "workflows", foreignKey: "workflow_id",
      displayField: "process_code", linkType: "workflow", linkPrefix: "WF" },
    { id: "checkpoint_set", type: "relation", label: "Bộ checkpoint gắn kèm",
      field: "checkpoint_set_id",
      displayField: "code", linkType: "checkpoint_set", linkPrefix: "CPS" },
    { id: "deps_forward", type: "dependency", label: "Liên kết với",
      direction: "forward", matchField: "source_code" },
    { id: "deps_reverse", type: "dependency", label: "Được liên kết bởi",
      direction: "reverse", matchField: "target_code" },
    { id: "same_workflow", type: "classification", label: "Cùng quy trình",
      groupBy: ["workflow_id"] }
  ],

  dot_tools: [
    { id: "info", type: "fields", label: "Thông tin DOT Tool",
      fields: ["code","name","description","category","token_type","status"] },
    { id: "deps", type: "dependency", label: "Liên quan",
      direction: "both", matchField: "source_code" },
    { id: "same_category", type: "classification", label: "Cùng nhóm",
      groupBy: ["category"] }
  ]
  // ... thêm entity type = thêm block config
}

4.4 Auto-Link Rule (PREFIX-NNN → clickable link)

Mọi giá trị text match pattern ^[A-Z]{2,4}-\d{3,4}$ tự động thành link:

CP-005 → /knowledge/registries/checkpoint_type/CP-005
CPS-001 → /knowledge/registries/checkpoint_set/CPS-001
ND-0007 → /knowledge/registries/workflow_step/ND-0007
DOT-042 → /knowledge/registries/dot_tool/DOT-042

Mapping PREFIX → entityType: Đọc từ meta_catalog (đã có id_prefix hoặc suy từ entity_type).

4.5 Permission Model — ID + Directus = Tự động

Directus Roles:
  super_admin  → READ ALL collections, ALL fields → thấy MỌI section
  admin        → READ most collections          → thấy hầu hết section
  editor       → READ content collections       → thấy sections liên quan content
  viewer       → READ public collections        → thấy sections public
  public       → READ cho phép collections      → thấy basic info only

UI Logic (đơn giản):
  for each section in config:
    data = await directus.items(section.collection).readByQuery(...)
    if data.length > 0 → render section
    if data empty/403 → hide section (user không có quyền)
  
  → KHÔNG CẦN code permission. Directus API tự kiểm soát.

Tương lai khi scale: Thêm role mới = config Directus permissions. UI tự điều chỉnh. Không sửa code.

4.6 Wireframe Lớp 3

┌─────────────────────────────────────────────────────────────────┐
│ [PREFIX-NNN] "Tên thực thể"                              [status] │
├─────────── SECTION: info (type=fields) ─────────────────────────┤
│   Code: CP-005    Name: Code Review Passed                      │
│   Description: Kiểm tra code đã được review trước khi merge    │
│   Classification: governance    Layer: 1    Owner: Claude Code  │
│   Status: active    Created: 2026-03-05    Updated: 2026-03-06 │
├─────────── SECTION: sets (type=relation) ───────────────────────┤
│   Thuộc tổ hợp:                                                 │
│    → [CPS-001] Bộ CI/CD              (click → Lớp 3 CPS-001)   │
│    → [CPS-005] Bộ deploy chuẩn       (click → Lớp 3 CPS-005)  │
├─────────── SECTION: nodes (type=dependency) ────────────────────┤
│   Nodes dùng checkpoint này:                                     │
│    → [ND-0007] Task Submitted / WF-001 (click → Lớp 3 ND-0007) │
│    → [ND-0032] Deploy Ready / WF-002   (click → Lớp 3 ND-0032) │
├─────────── SECTION: instances (type=relation, count) ───────────┤
│   47 instances đã verify              (click → danh sách filter) │
├─────────── SECTION: same_category (type=classification) ────────┤
│   Cùng category=ci: [CP-001] [CP-003] [CP-012]                 │
│   Cùng layer=1:     [CP-001] [CP-002] [CP-008] ... +15         │
├─────────── SECTION: related (type=semantic) ────────────────────┤
│   [DOT-042] dot-health-check          (score: 0.89)            │
│   [PG-015]  /knowledge/workflows      (score: 0.82)            │
│   [TBL-003] Bảng CI status            (score: 0.78)            │
└─────────────────────────────────────────────────────────────────┘

Mỗi [link] → trang Lớp 3 tương ứng → sections riêng → link tiếp → VÔ TẬN
Section trống/403 → TỰ ĐỘNG ẩn (Directus permissions)

5. CƠ CHẾ KỸ THUẬT

5.1 Cross-Reference Config (per entity type)

Mỗi entity type có config riêng cho Lớp A:

// crossRefConfig — config-driven, KHÔNG code per type
const crossRefConfig = {
  checkpoint_types: {
    explicit: [
      { label: "Thuộc Sets", collection: "checkpoint_set_items", 
        filter: { type_id: "{id}" }, display: "set_id.code", link: "checkpoint_sets" },
      { label: "Instances", collection: "checkpoint_instances",
        filter: { checkpoint_type_id: "{id}" }, count: true, link: "tasks" },
      { label: "Nodes dùng", collection: "workflow_steps",
        filter: { checkpoint_set_id: "{sets_containing_this}" }, display: "code", link: "workflow_steps" }
    ],
    classification: ["category", "layer"],  // fields dùng cho Lớp B
    semantic: true  // bật Lớp C
  },
  checkpoint_sets: {
    explicit: [
      { label: "Chứa Checkpoints", collection: "checkpoint_set_items",
        filter: { set_id: "{id}" }, display: "type_id.code", link: "checkpoint_types" },
      { label: "Gắn vào Nodes", collection: "workflow_steps",
        filter: { checkpoint_set_id: "{id}" }, display: "code", link: "workflow_steps" }
    ],
    classification: ["applicable_to"],
    semantic: true
  },
  dot_tools: {
    explicit: [
      { label: "Thuộc Category", field: "category", link: "dot_tools?filter=category" }
    ],
    classification: ["category", "token_type"],
    semantic: true
  },
  // ... config cho mỗi entity type
}

Nguyên tắc: Thêm entity type mới = thêm config block. KHÔNG viết component mới.

5.2 Semantic Embedding Pipeline

DAILY JOB (hoặc on-change):
  1. Query ALL entities có description từ MỌI registry collections
  2. Embed description → vector (dùng Agent Data Qdrant hoặc OpenAI)
  3. Store: { entity_type, entity_id, entity_code, vector }
  4. Pre-compute top-5 cross-type similar cho mỗi entity
  5. Cache kết quả vào field `semantic_links` (JSON) hoặc collection riêng

ON-PAGE-LOAD (realtime fallback):
  1. Nếu cache hết hạn → query Qdrant trực tiếp
  2. Filter: khác entity_type (ưu tiên cross-domain)
  3. Threshold: cosine similarity ≥ 0.70
  4. Return top-5 kết quả

5.3 Entity Dependencies Collection (Lớp A mở rộng)

entity_dependencies (Directus collection — Điều 8):
  id            (PK auto)
  code          (DEP-0001, auto-increment)
  source_type   (enum: checkpoint_type, checkpoint_set, workflow, workflow_step,
                        dot_tool, ui_page, collection, module, agent, document)
  source_code   (string: CP-005, DOT-042, PG-015...)
  target_type   (enum: same as source_type)
  target_code   (string: CPS-001, WF-001...)
  relation_type (enum: belongs_to, contains, uses, triggers, displays, extends, related)
  direction     (enum: forward, reverse, bidirectional)
  auto_detected (boolean: true nếu phát hiện tự động, false nếu khai báo)
  confidence    (float: 0-1, chỉ dùng cho semantic, explicit = 1.0)
  status        (enum: active, deprecated)
  date_created  (datetime auto)

Populate: DOT script dot-dependency-scan quét Directus relations + codebase imports → ghi vào entity_dependencies. Scheduled hàng ngày.

6. SỐ LIỆU KỸ THUẬT HIỆN TẠI

Metric	Giá trị	Nguồn
Registry collections	13 active	meta_catalog
Tổng entities có ID	399+	dot-orphan-scan coverage report
Checkpoint types (CP)	31	checkpoint_types
Checkpoint sets (CPS)	2	checkpoint_sets
Workflow nodes (ND)	70	workflow_steps
DOT tools	97	dot_tools
UI pages	39	ui_pages
Collections	113	collection_registry
Agents	6	agents
Modules	4	modules
Qdrant vectors	315+	Agent Data health
Auto-ID flows	13	Directus Flows
Orphan coverage	100% (399/399)	PR #455

7. LỘ TRÌNH TRIỂN KHAI

Phase A: NỀN TẢNG (FIX BLOCKING + DEPENDENCY)

Fix Registries 403 (TD-098) — trang web phải hoạt động trước
Tạo entity_dependencies collection (Điều 8)
dot-dependency-scan — quét Directus relations → populate dependencies
Tạo dot-duplicate-engine (TD-083, Điều 14) — Tầng 3

Phase B: CROSS-REFERENCE UI

Nâng cấp [entityType]/[id].vue — thêm crossRefConfig per entity type
Lớp A: Đọc entity_dependencies → hiển thị "Quan hệ trực tiếp" với link
Lớp B: Đọc cùng classification/category → hiển thị "Cùng nhóm"
Lớp A + B = VÒNG LẶP CƠ BẢN — click link → trang mới → link mới

Phase C: SEMANTIC (AI-POWERED)

Embed entity descriptions vào Qdrant (batch job)
API endpoint /api/cross-references?type=X&code=Y → return top-5
Lớp C hiển thị trên UI — "Liên quan ngữ nghĩa" với confidence score
TD-095: Fill DOT tools descriptions (100% trống) trước khi embed

Phase D: TỰ DUY TRÌ

dot-dependency-scan chạy sau mỗi deploy (auto-update dependencies)
Semantic re-embed scheduled hàng ngày
Orphan Scanner + Duplicate Engine + Dependency Scan = BỘ 3 TỰ KIỂM TRA

8. NGUYÊN TẮC DUY TRÌ

Config, không code: Thêm entity type = thêm crossRefConfig. Không viết page mới.
3 lớp độc lập: Lớp A hoạt động không cần Lớp C. Lớp C là bonus, không blocking.
Tự mở rộng: Entity mới tạo → tự có trang Lớp 3 → tự có cross-references.
Vòng lặp tự nhiên: Không cần "thiết kế link". Link sinh ra TỰ ĐỘNG từ relations + classification + vectors.
Ai nhìn cũng hiểu: Trang Lớp 3 = CV đầy đủ của entity. Mọi thông tin ở 1 nơi.

SSOT v1.0 | S107 (2026-03-07) | Tác giả: Claude (điều hành) + Huyen (tầm nhìn)