Incomex AI Portal
KB-D307 rev 11

Quy trình Sinh thực thể — Entity Lifecycle

10 min read Revision 11
architectureentity-lifecycleregistryDOTprocess

Quy trình Sinh thực thể — Entity Lifecycle

v2.0 | 2026-03-15 S122 — Patch: +Nhãn gán tự động khi sinh entity (Luật Nhãn Điều 24, fn_auto_label_assignment). +PG TRIGGER sinh ID (TD-133, kế hoạch thay 13 Directus Flows). +system_issues lifecycle (open/resolved/archived). +Taxonomy 5 collections (S122 PR #508).

"Đẻ ra bất cứ thứ gì trên hệ thống phải theo quy trình, được cấp ID ngay, được gán nhãn tự động, được cập nhật cho cơ quan quản lý liên quan." QUAN HỆ: Mỗi entity sinh ra phải tuân thủ 8 quy tắc quan hệ (Điều 21): search_knowledge("luật lớp 3 hạ tầng thông tin") NHÃN: Mỗi entity sinh ra được gán nhãn TỰ ĐỘNG theo 3 tầng rule (Điều 24): search_knowledge("luật nhãn label law taxonomy") search_knowledge("entity lifecycle quy trình sinh thực thể")

NGUYÊN TẮC: KHÔNG AI ĐƯỢC "ĐẺ BỪA BÃI"

Hệ thống xây ra quy trình quản lý, nhưng chính những người xây lại không làm theo. Con người gọi là "lãnh đạo chưa làm gương". Từ giờ:

Mọi thực thể sinh ra trên hệ thống PHẢI qua quy trình chuẩn:

  1. Gọi DOT/script sinh chuẩn (KHÔNG viết code trực tiếp)
  2. Được cấp ID tự động
  3. Được đăng ký vào registry tự động
  4. Được gán metadata tối thiểu (name, description, classification, owner, status)
  5. Được thông báo cho "cơ quan quản lý" liên quan (registry + UI + audit log)

AI/Agent KHÔNG ĐƯỢC tạo trực tiếp. PHẢI gọi script.

QUY TRÌNH SINH THEO TỪNG LOẠI

Loại 1: TẠO COLLECTION MỚI

TRƯỚC (SAI — agent đang làm):
  → Viết DOT script tạo collection + fields
  → Chạy DOT → collection xuất hiện trong Directus
  → XONG. Không ai biết collection mới tạo, không phân loại, không metadata.

SAU (ĐÚNG — quy trình chuẩn):
  → Gọi: dot-entity-create --type=collection --name=xyz --classification=module --owner=claude_ai --layer=3
  → Script tự động:
    1. Tạo collection trong Directus (DOT schema)
    2. Tạo record trong collection_registry (phân loại, owner, tầng, status=draft)
    3. Set meta.note trên collection = description
    4. Set meta.group = classification
    5. Tạo AI Agent permissions (DOT permissions)
    6. Log vào directus_activity
    7. Trả về: collection_id + registry_id + checklist những gì cần làm tiếp

Loại 2: THÊM FIELD MỚI

SAU (ĐÚNG):
  → Gọi: dot-field-create --collection=xyz --field=abc --type=string --note="Mô tả tiếng Việt" --group="Nhóm X"
  → Script tự động:
    1. Tạo field trong Directus (DOT schema)
    2. Set meta.note = description (Vietnamese)
    3. Set meta.group = group
    4. Set field translations nếu có
    5. Log

Loại 3: TẠO BẢNG UI MỚI

SAU (ĐÚNG):
  → Gọi: dot-table-register --table_id=tbl_xxx --collection=xyz --fields="f1,f2,f3" --page="/path"
  → Script tự động:
    1. Tạo record trong table_registry
    2. Trang sử dụng <DirectusTable table-id="tbl_xxx" /> → TỰ ĐỘNG hiện
    3. Không code component mới

Loại 4: TẠO MODULE MỚI

SAU (ĐÚNG):
  → Gọi: dot-module-register --code=M-005 --name="Tên module" --description="..." --lead=claude_ai
  → Script tự động:
    1. Tạo record trong modules collection
    2. Trang /knowledge/modules TỰ ĐỘNG hiện (vì đọc từ Directus)
    3. Tạo folder planning + SSOT trong Agent Data
    4. Tạo task trong Directus

Loại 5: TẠO DOT TOOL MỚI

SAU (ĐÚNG):
  → Trước khi tạo: ls dot/bin/ | grep <keyword> (kiểm tra trùng)
  → Tạo script trong dot/bin/
  → Gọi: dot-tool-register --name=dot-xxx --category=schema --description="..."
  → Script tự động đăng ký vào dot_tools registry

Loại 6: TẠO QUY TRÌNH MỚI (WORKFLOW)

SAU (ĐÚNG):
  → Gọi qua WCR (Workflow Change Request) → AI Council review → Approve
  → Tự động tạo workflow record (WF-NNN) trong workflows collection
  → Tự động tạo workflow_steps từ narrative
  → Tự động hiện trên /knowledge/workflows

Loại 7: TẠO CHECKPOINT TYPE MỚI (S106)

SAU (ĐÚNG):
  → Gọi: dot-checkpoint-register --code=CP-NNN --name="Tên CP" --layer=1 --category="domain"
  → Script tự động:
    1. Tạo record trong checkpoint_types (CP-NNN)
    2. Gán metadata: description, requires_evidence, auto_verifiable
    3. Status = draft (chuyển active khi verify xong)
    4. Log vào activity

Loại 8: TẠO CHECKPOINT SET (TỔ HỢP) MỚI (S106)

SAU (ĐÚNG):
  → Gọi: dot-checkpoint-set-create --code=CPS-NNN --name="Bộ kiểm tra X"
  → Gắn checkpoint types: --items="CP-001,CP-005,CP-012" --required="CP-001,CP-005"
  → Script tự động:
    1. Tạo record trong checkpoint_sets (CPS-NNN)
    2. Tạo M2M records trong checkpoint_set_items
    3. Gắn vào workflow node nếu chỉ định: --attach-to-step=S-015

Loại 9: STATE MACHINE NODE — GẮN CHECKPOINT SET (S106 — Tầng 4)

SAU (ĐÚNG):
  → Workflow mode = state_machine
  → Mỗi node (state) gắn 1 checkpoint set: workflow_steps.checkpoint_set_id = CPS-NNN
  → Khi entity (khách hàng, đại lý) đến node:
    1. Hệ thống đọc checkpoint_set_id
    2. Tạo checkpoint_instances cho mọi CP types trong set
    3. Hiện checklist cho agent/user
    4. Hoàn thành set → kiểm tra condition → chuyển state (hoặc chờ trigger khác)

Loại 10: TẠO JOURNEY TEMPLATE (S106 — Tầng 4)

SAU (ĐÚNG):
  → Gọi: dot-journey-create --code=JT-NNN --name="Hành trình tiêu chuẩn"
  → Gắn nodes: --steps="ND-0001,ND-0002,ND-0003" --checkpoint-sets="CPS-020,CPS-021,CPS-022"
  → Script tự động:
    1. Kiểm tra trùng: dot-duplicate-engine --check --type=journey_template --name=...
    2. Tạo record trong journey_templates (JT-NNN)
    3. Tạo M2M records trong journey_template_steps
    4. Mỗi step gắn checkpoint_set tương ứng
    5. Status = draft (chuyển active khi review xong)
  → Gán cho entity: contacts.journey_template_id = JT-NNN
  → Hệ thống TỰ BIẾT đường đi + checkpoint cần hoàn thành cho entity đó

VÒNG ĐỜI THỰC THỂ (LIFECYCLE)

draft ──→ active ──→ deprecated ──→ retired
  ↑                      │
  └──────────────────────┘ (nếu cần phục hồi)
Status Ý nghĩa UI Data
draft Mới tạo, đang xây dựng, chưa dùng production Hiện với badge "Draft" Có trong registry
active Đang sử dụng, production-ready Hiện bình thường Có trong registry
deprecated Sắp bỏ, còn dùng nhưng không nên tạo mới Hiện với badge "Deprecated" + cảnh báo Có, flag warning
retired Đã bỏ, không dùng Ẩn khỏi UI mặc định (hiện khi filter) Giữ trong registry cho audit

Node lifecycle (S106): Nodes (workflow_steps) cũng tuân thủ vòng đời:

  • draft → active (khi workflow publish) → deprecated (khi thay thế) → retired
  • Node deprecated nhưng vẫn có entity đang ở state đó → KHÔNG ĐƯỢC retire → phải migrate entities trước
  • dot-duplicate-engine quét nodes: 2 nodes cùng logic trong cùng domain → cảnh báo merge

Enforcement: Tầng 5 quét: thực thể status=deprecated > 90 ngày → tự đề xuất retire. Thực thể status=retired nhưng vẫn có code reference → CẢNH BÁO.

QUY TRÌNH SỬA — MODIFY (Điểm gãy #3, Điều 12)

SỬA entity (rename, đổi classification, đổi owner, sửa schema):
  1. Query entity_dependencies WHERE source/target = entity → list ẢNH HƯỞNG
  2. Nếu schema change → SCR (Schema Change Request) → AI Council review → approve
  3. Nếu workflow change → WCR → review → approve
  4. Apply change qua DOT script (KHÔNG sửa tay)
  5. Cập nhật TẤT CẢ registries + dependencies TỰ ĐỘNG
  6. dot-relation-discover chạy → phát hiện quan hệ thay đổi
  7. Verify: Lớp 3 của entity + entities bị ảnh hưởng hiển thị đúng

Ví dụ: Đổi tên field assigned_to → owner trong collection tasks:

  • Query DEPENDS_ON: page PG-010 đọc field assigned_to → sẽ hỏng
  • Query USED_BY: DOT-055 ghi data vào assigned_to → sẽ hỏng
  • Phải sửa cả page + DOT tool ĐỒNG THỜI → verify → mới xong

QUY TRÌNH XOÁ — DELETE/RETIRE (Điều 12)

XOÁ entity:
  1. Query USED_BY → danh sách entities đang dùng
  2. Nếu USED_BY > 0 → CHẶN XOÁ. Phải deprecate trước.
  3. Deprecate: status → "deprecated". UI hiện cảnh báo.
  4. Thông báo mọi entities trong USED_BY list → tạo migration tasks
  5. Chờ USED_BY = 0 (mọi nơi đã migrate sang entity thay thế)
  6. Retire: status → "retired". Ẩn khỏi UI (hiện khi filter).
  7. KHÔNG xoá khỏi registry (giữ audit trail). Data archive nếu cần.

Rule: entity có USED_BY > 0 → KHÔNG BAO GIỜ xoá trực tiếp. Vi phạm = phá hệ thống.

QUY TRÌNH GỘP — MERGE (Điều 14 Chống trùng)

GỘP 2 entities trùng (vd: CP-005 ≈ CP-012):
  1. Chọn entity GIỮ (primary) và entity BỎ (secondary)
  2. Migrate data: mọi reference tới secondary → trỏ về primary
  3. Merge metadata: description kết hợp, giữ classification tốt hơn
  4. Update entity_dependencies: secondary → primary
  5. Deprecate secondary: status → "deprecated", note: "Merged into [primary]"
  6. Verify: Lớp 3 của primary hiện đầy đủ data sau merge
  7. Retire secondary sau 30 ngày (chờ verify clean)

CHECKLIST "SINH THỰC THỂ" — BẮT BUỘC

Mọi agent PHẢI qua checklist này khi tạo BẤT KỲ thứ gì mới:

┌──────────────────────────────────────────────────────────┐
│ ENTITY BIRTH CHECKLIST — Không qua = không tạo           │
├──────────────────────────────────────────────────────────┤
│ 1. Đã gọi DOT/script chuẩn chưa? (không code trực tiếp)│
│ 2. Thực thể có ID/mã chưa? (PREFIX-NNN)                 │
│ 3. Đã đăng ký vào registry chưa?                         │
│ 4. Metadata tối thiểu đã điền? (name, desc, class, owner)│
│ 5. Status = draft (chuyển active khi verify xong)?       │
│ 6. UI đã tự hiện chưa? (nếu có UI liên quan)            │
│ 7. Audit log ghi nhận chưa?                              │
└──────────────────────────────────────────────────────────┘