BÁO CÁO NGHIÊN CỨU THỰC TẾ: ĐIỀU 26 v2.1.1 — Claude Code Lần 1

Agent: Claude Code CLI (SSH access) Phiên: S141 Đối tượng: Điều 26 v2.1.1 (trước khi nâng v3.4)

---

1. HIỆN TRẠNG PG SCHEMA (từ code dot-pg-views-ensure v12.0.0)

Table v_registry_counts: id serial PK, cat_code text, entity_type text, record_count int DEFAULT 0, orphan_count int DEFAULT 0, count_b int DEFAULT 0, count_c int DEFAULT 0, cross_check text DEFAULT '', composition_level text DEFAULT 'atom', active_count int DEFAULT 0 (← Điều 26 v2.1.1)

Table v_registry_summary: id serial PK, total_atoms int, total_types int, total_orphans int, count_atom int, count_molecule int, count_compound int

Function refresh_registry_counts():

• ANALYZE 15 tables → TRUNCATE + INSERT 16 entries (CAT-000 tới CAT-015)
• Line 223-225: UPDATE v_registry_counts SET active_count = record_count (placeholder)
• Line 228-229: Sync meta_catalog.active_count từ v_registry_counts
• Summary dùng SUM(active_count) thay SUM(record_count)

Function test_counting_contract():

• T1-T7 (8 tests): active=record, CAT-ALL sums, record≥0, level sums, SUSPECT origins, CAT-ALL guard
• THIẾU T8 trong code thực tế (comment nói có nhưng SQL chỉ có T1-T7)

2. DIRECTUS SCHEMA (dot-schema-meta-catalog-ensure v1.2.0)

meta_catalog fields (18 total): code, name, name_en, entity_type, source_model, source_location, registry_collection, sync_script, sync_frequency, record_count, active_count, actual_count, orphan_count, last_scan_date, ui_page, status, description, layer

active_count field: type=integer, nullable=true, default=0, note="Active records (excludes retired). Điều 26 v2.1.1"

3. API ENDPOINT (refresh-counts.post.ts)

• Fetches active_count trong fields list (line 50)
• Patch: { record_count: newCount, active_count: newCount } (line 110-112)
• CAT-ALL: Comment says PG trigger handles it, API PATCH blocked by guard (line 139-143)
• CAT-ALL không được update qua API — chỉ qua SSH/PG trigger

4. INTEGRITY CHECK (dot-registry-integrity-check v1.1.0)

9 checks, quan trọng nhất:

• Check 7: _dot_origin coverage (query Directus API per collection)
• Check 9: active_count = record_count cho mọi entry

5. GAPS XÁC ĐỊNH

#	Gap	Mức độ	Chi tiết
G1	status field chưa deploy trên managed collections	BLOCKER cho Điều 26 v3	Hiện tại KHÔNG có field status (active/retired) trên 16 managed tables. active_count = record_count là placeholder
G2	T8 trong test_counting_contract() không tồn tại trong SQL	Minor	Changelog v12.0.0 nói "T8: check all triggers enabled" nhưng code SQL chỉ có T1-T7
G3	v_registry_summary thiếu count_material	Minor	Changelog v12.0.0 nói "add count_material column" nhưng ALTER TABLE chỉ có atom/molecule/compound
G4	Guards (fn_guard, fn_validate_dot_origin, triggers) KHÔNG có trong SQL block	Nghiêm trọng	Changelog v10-12 nói tạo guards/triggers nhưng SQL trong file chỉ có: CREATE TABLE + refresh function + test contract. Guards/triggers không được deploy qua script này
G5	CAT-ALL update mechanism	Design gap	API blocked by guard, PG trigger mentioned nhưng không trong code. CAT-ALL chỉ update khi chạy refresh_registry_counts()
G6	16 collections trong UNION ALL nhưng 18 managed trong meta_catalog	Counting gap	Changelog v12.0.0 nói "add CMT + CAT-018 + CAT-019" nhưng UNION ALL chỉ có 16 entries (CAT-000 → CAT-015)

6. LỘ TRÌNH CỤ THỂ

Phase 1 — Fix gaps hiện tại (v12 → v13):

1. Thêm missing UNION ALL entries cho CMT, CAT-018, CAT-019 (G6)
2. Thêm T8 test case vào test_counting_contract() (G2)
3. Thêm count_material column vào v_registry_summary (G3)
4. Verify guards/triggers đã tồn tại trên PG hay chưa (SSH query) (G4)

Phase 2 — Điều 26 v3 (S128): Deploy status field:

1. Tạo DOT script: dot-schema-status-field-ensure — add status field (active/retired/archived) lên tất cả 18+ managed collections
2. Migration: SET tất cả existing records → status = 'active'
3. Update refresh_registry_counts(): active_count = COUNT(*) WHERE status != 'retired'
4. Update test_counting_contract(): T1 change → active_count <= record_count
5. Update refresh-counts.post.ts: active_count tính riêng (không = record_count)
6. Update integrity check 9: active_count <= record_count (thay =)

Phase 3 — CAT-ALL automation:

1. PG trigger trg_refresh_virtual_summaries phải tồn tại (verify or create)
2. Remove "deploy step" dependency — CAT-ALL auto-update khi refresh_registry_counts() chạy

---

Kết luận

Điều 26 v2.1.1 đã LIVE nhưng ở trạng thái placeholder (active = record). Gap lớn nhất là G4 (guards/triggers có thể không deploy đúng) và G1 (thiếu status field trên managed collections). Cần SSH verify PG thực tế trước khi tiến hành Phase 2.