LUẬT LOÀI + COLLECTION v0.5 FINAL — Chờ phê duyệt
LUẬT LOÀI + LUẬT COLLECTION — v0.5 FINAL (ĐÓNG BĂNG CHỜ PHÊ DUYỆT)
Bổ sung Hiến pháp Kiến trúc — Nền móng của nền móng
v0.5 FINAL | 2026-03-20 | Sau 3 rounds review GPT + Gemini. Cả 2 bên APPROVE FOR PILOT. Thay đổi từ v0.4: +species_code Immutable. +3 mode Cổng 2 quyết bằng metadata. +Audit queue SLA 7 ngày auto-retire. +Overlay 4 test rules. +migration_state. +discriminator_operator/config. +Pilot "khai sinh giả lập" 4 bước.
I. BỐI CẢNH
134 collections trong PG, chỉ 19 đăng ký. 2 tuần đếm không xong vì chưa định nghĩa đếm cái gì.
"Chuẩn bị mua bò → phải chuẩn bị chuồng trước. Kiểm soát từ khi sinh ra." — Huyên "Đếm là kiểm tra lại thôi. Số quân thực tế phải = danh sách khai sinh." — Huyên
II. NGUYÊN TẮC GỐC
- Loài = meta-concept TRƯỚC Điều 24. Không phải facet.
- Kiểm soát từ khi sinh ra. Cổng 1 (loài) chặt, Cổng 2 (cá thể) tự động.
- Soft enforcement. Không hard-fail. Insert → audit queue → tự phục hồi.
- Đếm = audit check chéo. Khai sinh vs thực tế. Khác = fault (system/data/model).
- Overlay ontology. Bổ sung phân loại, KHÔNG thay native source of truth.
- 3 hiện thân: Văn bản + Schema/trigger/view + Agent cheat sheet.
Overlay Ontology — 4 test rules (phải đạt cả 4):
- Overlay chỉ lưu classification, mapping, audit
- Overlay KHÔNG lưu full-copy business fields của native source
- Overlay KHÔNG phải nơi update chính cho native-managed resource
- Xóa overlay → native source vẫn chạy đúng chức năng gốc
III. LUẬT LOÀI
Mọi đối tượng trong phạm vi governance PHẢI resolve đúng 1 species. Không resolve = audit queue.
3.1 Định nghĩa
- Loài = loại đối tượng = phân loại gốc nhất
- Mỗi species PHẢI có management_mode: governed / observed / excluded
3.2 Tên — 2 lớp
| Lớp | Mục đích | Ví dụ |
|---|---|---|
| species_code | Machine-readable, IMMUTABLE (không bao giờ đổi) | dot_tool, workflow, pg_field |
| display_name | UI/AI, ngôn ngữ tự nhiên | "DOT Tool", "Quy trình" |
Mặc định species_code theo tên collection. Cho phép khác, nhưng KHÔNG ép giống.
3.3 SSOT — entity_species
| Field | Type | Ghi chú |
|---|---|---|
| code | text, unique | SPE-DOT, SPE-WKF |
| species_code | text, unique, IMMUTABLE | dot_tool, workflow |
| display_name | text | "DOT Tool", "Quy trình" |
| composition_level | text, NOT NULL | atom/molecule/.../building |
| management_mode | text, NOT NULL | governed/observed/excluded |
| prefix | text | DOT-, WKF- |
| description | text | |
| status | text | active/deprecated/retired |
KHÔNG có record_count. Đếm từ PG view.
3.4 Loài = thực thể quản trị (có code, registry, lifecycle)
IV. LUẬT COLLECTION
Mỗi collection PHẢI đăng ký + phân loại. Chuồng trước bò sau.
4.0 Namespace bắt buộc cho collection sync từ nguồn ngoài (v1.1, 2026-04-13)
Bổ sung Huyên yêu cầu phiên Lark 6. Mọi collection sync từ Lark PHẢI có prefix namespace để phân biệt với collection nội sinh.
2 namespace Lark hợp lệ:
| Prefix | Phạm vi | Species nhóm | Ví dụ |
|---|---|---|---|
larkpc_ |
Lark Phái cử — nghiệp vụ phái cử lao động Nhật (Base 88, Dữ liệu Phái cử 1, 5.5/6.5/6.6, ĐN, TT Nguồn...) | lark_phai_cu |
larkpc_thong_bao_tuyen_dung, larkpc_don_hang |
larkschool_ |
Lark Trường học — quản lý đào tạo trường nghề Incomex | lark_school |
larkschool_lop_hoc, larkschool_diem_danh |
Quy tắc:
- Collection sync từ Lark PHẢI bắt đầu bằng 1 trong 2 prefix trên. Tên
lark_*/lark88_*/larkphaicu_*→ reject (audit queue). - Schema bắt buộc tối thiểu:
code,lark_source_record_id,lark_source_table_id,lark_synced_at,data jsonb,_dot_origin,created_at,updated_at. - governance_role mặc định:
governed. Không cho phépexcluded. - Death strategy:
archive(giữ birth record +died_at). - Mỗi collection PHẢI có entry trong PG table
lark_sync_jobs(job_code, target_collection, lark_base_token, lark_table_id, field_whitelist, schedule_cron, enabled). - 2 species nhóm (
lark_phai_cu,lark_school) thêm vàoentity_speciesvới composition_level =building, management_mode =governed, prefix tương ứng. - Collection cụ thể có thể tạo species con riêng (ví dụ
lark_tbtdcho thông báo tuyển dụng) hoặc gom vào species nhóm — Huyên quyết case-by-case.
4.1 Phân loại — 2 trục + source_kind + migration_state
Trục 1: storage_role: primary | junction | log | system Trục 2: governance_role: governed | observed | excluded Metadata: source_kind: registry | native | derived | policy Metadata: migration_state: unclassified | classified | pilot | stable
Ma trận mẫu:
| Collection | storage | governance | source_kind | migration_state |
|---|---|---|---|---|
| dot_tools | primary | governed | registry | stable |
| entity_labels | junction | governed | registry | pilot |
| lifecycle_log | log | observed | native | classified |
| trigger_registry | system | governed | registry | pilot |
| directus_fields | system | observed | native | pilot |
| entity_species | system | governed | registry | pilot |
| directus_permissions | system | excluded | native | stable |
4.2 Mapping — species_collection_map
| Field | Type | Ghi chú |
|---|---|---|
| species_code | text, FK | → entity_species |
| collection_name | text | |
| is_primary | boolean | Collection chính |
| discriminator_field | text, nullable | Field phân biệt |
| discriminator_value | text, nullable | Giá trị đơn giản |
| discriminator_operator | text, nullable | eq/neq/regex/in/not_null |
| discriminator_config | jsonb, nullable | Case phức tạp |
4.3 Collection đa loài
- BẮT BUỘC có discriminator rule machine-readable
- Không có discriminator → CƯỠNG BỨC human_review mode
- Collection tự đếm số loài chứa
4.4 Collection = thực thể quản trị. Mở rộng collection_registry cover 134+.
4.5 Tự phát hiện lỗi
| Lỗi | Cơ chế |
|---|---|
| Collection mới chưa đăng ký | PG trigger / hook → system_issue |
| Loài chưa có collection | Constraint NOT NULL |
| Record mơ hồ | Soft enforcement → audit queue |
| Collection unclassified > 0 | Health check cảnh báo |
V. CƠ CHẾ SINH
5.1 CỔNG 1: SINH LOÀI (chặt)
1. Check tồn tại trong entity_species
2. QUÉT TRÙNG NGHĨA + "vì sao loài cũ không đủ" → ghi vào description
3. Chuẩn bị chuồng (collection)
4. Đặt tên: species_code (IMMUTABLE) + display_name
5. Chọn composition_level + management_mode
6. Orchestrator tạo status=Draft → User Finalize
7. DOT: dot-species-register
5.2 CỔNG 2: SINH CÁ THỂ (soft enforcement)
3 mode — QUYẾT BẰNG METADATA, không do agent cảm tính:
| Mode | Tiêu chí metadata | Cách hoạt động |
|---|---|---|
| strict_auto | Collection có đúng 1 species active, không discriminator, migration_state=stable | Auto gán species + code |
| rule_auto | Collection có >1 species HOẶC có discriminator rule | Auto gán theo rule, sai → audit queue |
| human_review | migration_state=unclassified/classified, nguồn import/legacy, HOẶC đa loài không có discriminator | Insert OK nhưng BẮT BUỘC vào audit queue |
KHÔNG hard-fail. Insert luôn thành công.
5.3 AUDIT QUEUE — entity_audit_queue
| Field | Type |
|---|---|
| id | auto |
| collection_name | text |
| record_id | text |
| species_guess | text, nullable |
| issue_type | text: unknown_species / wrong_collection / missing_code / stale_zombie |
| audit_status | text: open / auto_resolved / agent_proposed / human_finalized |
| audit_owner | text, nullable |
| audit_deadline | timestamp, nullable |
| audit_reason_code | text |
| created_at | timestamp |
| resolved_at | timestamp, nullable |
SLA: > 7 ngày không ai xử lý → auto-assign status=Unknown_Garbage, ẩn khỏi UI chính.
Xử lý 3 tầng: auto-resolve (case rõ) → agent-propose (bán mơ hồ) → human-finalize (khó).
Phân biệt: Ambiguity species → entity_audit_queue. Lỗi hạ tầng → system_issue.
5.4 Đếm = Audit Check Chéo
Khai sinh vs PG COUNT*. Khác = fault: system_fault / data_fault / model_fault. Đếm từ PG view. Performance: p95 > 500ms trong 24h → chuyển materialized view.
VI. PHƯƠNG TRÌNH
Tầng 1: Tổng PG = Σ(governed) + Σ(observed) + Σ(excluded) + Σ(unclassified)
unclassified > 0 → CẢNH BÁO
Tầng 2: Σ(governed) = Σ(6 lớp × loài) + Σ(audit queue chưa resolve)
Tầng 3: Loài X: khai sinh [a] vs thực tế [b] → a≠b → fault
VII. MIGRATION
| Giai đoạn | Nội dung | Enforce? |
|---|---|---|
| 1. Bucket | Auto-assign 134 collections = unclassified | KHÔNG |
| 2. Review | ~20 collections/ngày, gán 2 trục + source_kind | KHÔNG |
| 3. Enforce | Bật audit queue trigger sau 100% | CÓ (soft) |
Pilot trước enforce: dot_tools (primary×governed) + entity_labels (junction×governed) + directus_fields (system×observed)
Pilot "khai sinh giả lập" 4 bước:
- Manual insert 3 records vào entity_species
- Tạo entity_audit_queue
- COUNT* thực tế 3 loại → so khớp
- Dùng ca lệch test quy trình: fault → queue → resolve
Tiêu chí pilot pass:
- 100% records resolve species HOẶC vào audit queue
- Không silent failure
- Không count nóng mâu thuẫn source truth
- Nuxt hiển thị đúng
- Audit queue có owner, SLA, ≥1 vòng resolve
- directus_fields không bị registry song song
- Rollback không vỡ gốc
- Phát hiện lệch < 5 giây
- Không lỗi 500 do trigger
VIII. EXECUTION GATE — MA TRẬN ĐA CHIỀU
Tạm phẳng. Chỉ mở đa chiều khi: bucket 100% + pilot pass + resolve ≥95% + discrepancy kiểm soát.
IX. NỢ KỸ THUẬT
- TD-330: Hợp nhất đếm cũ. Làm SAU pilot ổn.
- Performance: p95 > 500ms → materialized view.
X. AGENT CHEAT SHEET
1. Mỗi object governance phải resolve đúng 1 species hoặc vào audit queue.
2. Species = ontology gốc, TRƯỚC Điều 24. Không phải facet.
3. Tạo loài mới: check trùng → giải thích vào description → Orchestrator Draft → User Finalize.
4. Species → collection (1 chiều). Chọn species trước, system chọn collection sau.
5. Collection có: storage_role + governance_role + source_kind + migration_state.
6. Collection đa loài: phải có discriminator rule. Không có → human_review.
7. Không hard-fail. Record mơ hồ → audit queue → tự phục hồi.
8. Count không trong registry. Đọc PG view.
9. meta_catalog song song. entity_species = ontology gốc.
10. Không chắc species → không đoán kín → tạo audit issue.
Phụ lục: Mode lấy từ metadata collection. Ambiguity species → entity_audit_queue. Lỗi infra → system_issue.
XI. QUAN HỆ LUẬT HIỆN CÓ
| Luật | Thay đổi |
|---|---|
| Điều 0 | +Mỗi thực thể PHẢI resolve species |
| Điều 0-B | Enforce composition_level + management_mode |
| Điều 24 | KHÔNG đổi. Species đứng trước nhãn |
| Điều 26 | Đếm = audit. Kiểm soát sinh = chính |
| meta_catalog | Giữ song song |
XII. BƯỚC TRIỂN KHAI ĐẦU TIÊN
KHÔNG viết trigger trước. Đóng băng schema contract cho 4 bảng:
- entity_species
- species_collection_map
- entity_audit_queue
- collection_registry metadata (storage_role, governance_role, source_kind, migration_state)
Sau đó mới code pilot cho 3 loại.
v0.5 FINAL | 3 rounds GPT + Gemini. APPROVE FOR PILOT. Chờ Huyên phê duyệt → ĐÓNG BĂNG.