Incomex AI Portal
KB-68EA rev 16

Sync Governance — Đồng bộ + Phát hiện Bất đồng bộ

11 min read Revision 16
architecturesyncgovernancemonitoringlayer-5

Sync Governance — Đồng bộ + Phát hiện Bất đồng bộ

v1.4 | 2026-03-12 S111 — Phase 2 cập nhật: Crosscheck v3 + Changelog 636+entries + system_issues 31 + dot-catalog-sync auto. 5 lệch + 2 CAT-ALL bugs → TD-132. Migration workflows DONE (S109b). "Hàng chục ngàn thứ cần đồng bộ mà chả ai quan tâm." search_knowledge("sync governance đồng bộ bất đồng bộ")

VẤN ĐỀ GỐC

Trước giờ tư duy "chạy theo vụ việc": gặp vấn đề đồng bộ Agent Data ↔ Directus → lao vào fix. Xong. Nhưng hệ thống có HÀNG CHỤC NGÀN CẶP cần đồng bộ — chỉ fix 1 cặp thì 9.999 cặp khác vẫn sai.

Nguyên tắc kiến trúc: Bất kỳ 2 nguồn thông tin nào về cùng 1 thực thể mà KHÁC NHAU = bất đồng bộ = PHẢI phát hiện TỰ ĐỘNG.

DANH SÁCH CẶP ĐỒNG BỘ

Đang hoạt động (Tầng 1 — đã giải quyết)

Nguồn A Nguồn B Cơ chế Trạng thái
Agent Data documents Qdrant vectors Realtime embedding ✅
Agent Data documents Directus knowledge_documents Event system webhook ≤15s ✅
GitHub repo VPS Docker image CI/CD pipeline ✅
Directus tasks Agent Data operations/tasks/ Directus Flow [DOT] Tasks Create/Update/Delete ✅
Directus task_comments Agent Data operations/tasks/ Directus Flow [DOT] Comments Create/Update/Delete ✅

ĐÃ FIX (S105 CHECKPOINT 1 + S106 REGISTRY-ENGINE)

Nguồn A Nguồn B Cơ chế Trạng thái
Directus table_registry Agent Data registries/table_registry/* [DOT-REG] 3 flows ✅ S105
Directus workflows Agent Data registries/workflows/* [DOT-REG] 3 flows ✅ S105
Directus workflow_steps Agent Data registries/workflow_steps/* [DOT-REG] 3 flows ✅ S105
Directus workflow_change_requests Agent Data registries/wcr/* [DOT-REG] 3 flows ✅ S105
Directus workflow_categories Agent Data registries/wcat/* [DOT-REG] 3 flows ✅ S105
Directus workflow_step_relations Agent Data registries/wsr/* [DOT-REG] 3 flows ✅ S105
Directus meta_catalog Agent Data registries/meta_catalog/* [DOT-REG] 3 flows ✅ S105 CP2
Directus modules Agent Data registries/modules/* Permissions fixed + sync ✅ S106 PR #451
Directus dot_tools Agent Data registries/dot_tools/* Auto-populated ✅ S106 PR #451
Directus collection_registry Agent Data registries/collection_registry/* Auto-populated ✅ S106 PR #451
Directus ui_pages Agent Data registries/ui_pages/* Auto-populated ✅ S106 PR #451
Directus agents Agent Data registries/agents/* Auto-populated ✅ S106 PR #451
Directus checkpoint_sets Agent Data Needs sync flows 🟡 S106 PR #454
Directus checkpoint_set_items Agent Data Needs sync flows 🟡 S106 PR #454

Auto-ID Flows (S106 — 13 total):

Collection Prefix Flow name
meta_catalog CAT [AUTO-ID] Meta Catalog
table_registry TBL [AUTO-ID] Table Registry
modules MOD [AUTO-ID] Modules
workflows WF [AUTO-ID] Workflows
workflow_steps ND [AUTO-ID] Workflow Steps
workflow_change_requests WCR [AUTO-ID] WCR
dot_tools DOT [AUTO-ID] DOT Tools
ui_pages PG [AUTO-ID] Pages
collection_registry COL [AUTO-ID] Collections
agents AGT [AUTO-ID] Agents
tasks TSK [AUTO-ID] Tasks
checkpoint_types CP [AUTO-ID] Checkpoint Types
checkpoint_sets CPS [AUTO-ID] Checkpoint Sets

CÒN INACTIVE (thiết kế đúng)

Nguồn A Nguồn B Cơ chế Trạng thái Lý do
Directus knowledge_documents Agent Data [DOT] Knowledge Sync ❌ INACTIVE Đúng: AD là SSOT cho knowledge
Directus knowledge_documents Agent Data [DOT] Knowledge Delete ❌ INACTIVE Đúng: AD là SSOT

CHƯA giám sát (Tầng 2-3 — LỖ HỔNG) + SSOT Direction (fix Điểm gãy #4)

Mỗi cặp PHẢI ghi rõ: SSOT là ai? Conflict → fix theo hướng nào?

Nguồn A Nguồn B SSOT Khi conflict Ưu tiên
Directus schema Codebase Directus Codebase adapt theo Directus 🔴
table_registry (Directus) Codebase UI Directus Codebase phải dùng registry record 🔴
modules (Directus) Codebase modules Directus Module phải đăng ký vào Directus 🔴
dot/bin/ VPS dot_tools registry VPS (thực tế) Registry sync theo VPS 🔴
Directus collections collection_registry Directus Registry cập nhật theo thực tế 🔴
Directus field meta.note Directus Trống = cần fill, KHÔNG xoá field 🔴
Agent Data SSOT docs Thực tế hệ thống Thực tế Docs phải cập nhật theo thực tế 🟡
Operating Rules text Agent hành vi Rules Agent sai → fix agent hoặc fix rule 🟡
Directus schema snapshot Actual schema Snapshot (baseline) Drift = phải giải trình, approve, hoặc rollback 🟡
table_registry config DirectusTable render Registry UI phải render đúng config 🟡

CÔNG CỤ CÓ SẴN ĐỂ PHÁT HIỆN

Directus /schema/snapshot + /schema/diff

  • Export toàn bộ schema → lưu baseline
  • Chạy diff định kỳ → phát hiện thay đổi không qua DOT
  • CHƯA DÙNG. Cần tạo cron job.

Directus directus_activity

  • Log mọi create/update/delete
  • Query: tìm actions không có user_agent = DOT → phát hiện manual changes
  • CHƯA DÙNG. Cần DOT script query.

Tester Module (M-004)

  • Quét routes, health check
  • MỞ RỘNG: thêm sync checks

Directus Flows (cron)

  • Chạy kiểm tra mỗi 30 phút
  • Kết quả → tạo task/comment nếu phát hiện vấn đề

THIẾT KẾ: SYNC MONITOR

┌─────────────────────────────────────────────────┐
│              SYNC MONITOR (Tầng 5)              │
│                                                  │
│  Cron job mỗi 30 phút:                          │
│                                                  │
│  1. Schema check:                                │
│     snapshot vs baseline → drift? → CẢNH BÁO    │
│                                                  │
│  2. Registry check:                              │
│     grep codebase → so sánh registries → lệch?  │
│     → CẢNH BÁO + tạo task                       │
│                                                  │
│  3. Metadata check:                              │
│     query fields WHERE note IS NULL → thiếu?     │
│     → CẢNH BÁO + tạo task fill metadata         │
│                                                  │
│  4. Doc freshness check:                         │
│     SSOT docs > 30 ngày → CẢNH BÁO              │
│                                                  │
│  5. Activity audit:                              │
│     actions không qua DOT → CẢNH BÁO            │
│                                                  │
│  Output: reports/ + ai_tasks (nếu cần fix)       │
└─────────────────────────────────────────────────┘

Nguyên tắc: Mỗi cặp đồng bộ trong bảng trên phải có 1 check trong Sync Monitor. Thêm cặp mới = thêm check. Không bỏ sót.

ORPHAN SCANNER — KIỂM KÊ NGƯỢC (Hiến pháp Điều 19, S106)

Sync Monitor kiểm tra CÁI ĐÃ ĐĂNG KÝ có khớp không. Orphan Scanner kiểm tra CÁI CHƯA ĐĂNG KÝ.

SIDE A (Birth Registry): Sinh ra → gán ID → đăng ký → sync
  → Lỗ hổng: agent bỏ qua, tạo thủ công, hệ thống tự sinh

SIDE B (Orphan Scanner): Quét MỌI THỨ tồn tại → so TẤT CẢ registries
  → Bắt mọi thứ Side A để lọt
  → Output: Coverage Report (% kiểm soát + danh sách orphans)

Tool: dot-orphan-scan — quét 12+ nguồn, update meta_catalog (actual_count, orphan_count, last_scan_date), auto-fix orphans đơn giản, tạo ai_task cho orphans phức tạp.

Chạy scheduled: Mỗi 6 giờ (cron VPS) + sau mỗi deploy.

TRIGGER 2 LỚP (Hiến pháp Điều 17 Khoản 6, S106)

Lớp 1 — REALTIME: Directus Flow event trigger → action ngay
  21 [DOT-REG] registry sync flows
  13 [AUTO-ID] flows
  6 [DOT] task/comment sync flows
  → Total: 40+ active flows

Lớp 2 — SAFETY NET: Scheduled scan → phát hiện diff nếu Lớp 1 fail
  dot-orphan-scan (mỗi 6h): coverage report
  dot-registry-diff: registry vs thực tế
  dot-metadata-audit: metadata trống
  → Nếu phát hiện lệch → cảnh báo + ai_task

Lớp 1 fail → Lớp 2 phát hiện trong ≤6 giờ → cảnh báo

LỘ TRÌNH

Phase 0 (✅ DONE S105): Schema baseline + Registry sync 6 collections

  • ✅ 18 [DOT-REG] flows cho 6 registry collections
  • ✅ Anti-loop verified (registries/* prefix safe)
  • ✅ DOT tool: dot-flow-setup-registry-sync (idempotent)
  • ✅ meta_catalog 13 entries, trang /knowledge/registries

Phase 1 (✅ DONE S106): Registry Engine + Checkpoint/Node Identity

  • ✅ Fix modules permission 403 + populate 4 modules (PR #451)
  • ✅ 4 collections mới: dot_tools, ui_pages, collection_registry, agents (PR #451)
  • ✅ 248 items populated retroactive
  • ✅ 10 auto-ID flows → tổng 13 auto-ID flows
  • ✅ dot-registry-diff tool — phát hiện lệch
  • ✅ 3-layer drill-down UI
  • ✅ checkpoint_sets + checkpoint_set_items (PR #454)
  • ✅ 31 checkpoint types → CP-NNN, 70 workflow steps → ND-NNNN
  • ✅ 3 auto-ID flows (CP, CPS, ND) → tổng 13

Phase 2 (ĐANG LÀM — S108→S111): Crosscheck + Counting + Self-Healing

  • ✅ dot-registry-count-refresh — 3 đếm per type (PR #469)
  • ✅ dot-registry-crosscheck v3 — xuôi vs ngược (PR #476-479)
  • ✅ registry_changelog — 51 flows, 636+ entries (PR #471-472, #483-484)
  • ✅ system_issues — 31 vấn đề tự phát hiện (PR #473)
  • ✅ dot-catalog-sync auto deploy (PR #485)
  • ✅ Crosscheck cột trong Lớp 1, nhật ký entity_name fix (PR #485)
  • 🔴 5 lệch crosscheck + 2 CAT-ALL bugs (TD-132 — Mission E)
  • 🔴 dot-duplicate-engine — chống double tổng quát (Điều 14, TD-083)
  • 🔴 Realtime orphan ≤15s (TD-113)
  • 🟡 Trigger realtime mở rộng cho collections còn thiếu (TD-089)

Phase 3: Integrated Sync Monitor + Multi-domain

  • Directus Flow (cron 30 min) trigger checks
  • domains collection + multi-domain sync
  • Self-healing pipeline: detect → classify → propose → auto-fix