Nợ Kỹ Thuật — Tech Debt Registry
Cập nhật: 2026-04-19 S178 Fix 17. +3 TD từ M2 migration (collection_registry/meta_catalog issues).
NGUYÊN TẮC (S127 Huyen): Mọi vấn đề xử lý 1 lần dứt điểm.
§0-AU (S141 Huyen): Cấm hardcode. Hệ thống TỰ MỞ RỘNG.
🆕 S178 Fix 17 — M2 MIGRATION DISCOVERY (2026-04-19)
Context: M2 seed apr_action_types/request_types + register Đ36 → phát hiện 3 lỗi hạ tầng collection_registry/meta_catalog. Workaround in-session, cần fix gốc.
| TD |
Mô tả |
Priority |
Target |
Fix hint |
| TD-S178-20 |
seq_collection_registry_code + seq_meta_catalog_code lệch so với actual max — INSERT nextval trùng |
🟡 |
S179 |
setval() khớp actual max hoặc gen function robust hơn |
| TD-S178-21 |
v_registry_counts view có id NOT NULL → trigger fn_auto_sync_v_registry_counts chặn meta_catalog INSERT |
🔴 |
S179 |
Fix view hoặc trigger logic |
| TD-S178-22 |
gen_code_meta_catalog dùng lpad(3) → tràn khi > CAT-999 (đã dùng CAT-998). Future auto-insert fail |
🔴 |
S179 |
Nâng lpad(4) hoặc naming scheme mới |
🆕 S178 Fix 9 — AGENT DATA OPTIMIZATION (2026-04-17)
Context: Mission "Công cụ Agent Data hoàn hảo" — cắt LLM GPT-4o synthesize DEPLOYED LIVE. /chat 3.28s → 1.31s (warm 0.21s), /mcp 0.45s → 0.27s, /mcp get_document 0.08s. 10 TD sinh ra trong quá trình, HOÃN để quay lại.
Handoff: Artifact handoff-s178-fix9 (Claude Desktop).
| TD |
Mô tả |
Priority |
Target |
Fix hint |
| TD-S178-01 |
/chat cold call 1.7s — embed cold không có cache, query mới luôn gọi OpenAI |
🟡 |
Sau GĐ E |
LRU cache embed query, TTL 1h, max 10k entries |
| TD-S178-02 |
response field thô "đoạn A / đoạn B / đoạn C" cắt cú pháp — UX với user đọc trực tiếp có thể lạ. Em + Gemini + Codex OK, GPT Actions OK |
🟢 |
Backlog |
Tinh chỉnh _build_raw_reply thêm heading Source: <doc_id> |
| TD-S178-03 |
agent-data-repo trên VPS git diverge 5 ahead / 112 behind origin GitHub |
🟡 |
Manual |
Huyên commit+pull manual khi rảnh; không phải việc agent |
| TD-S178-04 |
Concurrency ceiling ~2 — 2 uvicorn workers × sync handler × 25s LLM block. Scale 100× sẽ tắc |
🔴 |
Sau GĐ E |
Nâng workers 2→4 (VPS 6 CPU dư) + xem xét async handler |
| TD-S178-05 |
OpenAI embed không timeout (SDK default 600s) → rủi ro treo worker khi OpenAI lag |
🔴 |
Sau GĐ E |
Set OpenAI(timeout=10.0) trong vector_store.py |
| TD-S178-06 |
Không cache embed query — query trùng vẫn gọi OpenAI lại |
🟡 |
Sau GĐ E |
LRU cache trong _embed(), key=query_normalized |
| TD-S178-07 |
Không circuit breaker — OpenAI/Qdrant lag 30s × 3 retry = 90s worst |
🟡 |
Sau GĐ E |
Thêm circuit breaker (fail-fast sau N lỗi liên tiếp) |
| TD-S178-08 |
1156 localhost calls /mcp trong 48h — chưa xác định ai gọi (nghi uptime-kuma health probe) |
🟢 |
Backlog |
Grep user-agent header trong docker log nginx + trace container source |
| TD-S178-09 |
Vector mồ côi 26 ghost + 4 orphan (kế thừa audit 2026-04-05) — đường đẻ orphan mới chưa bịt |
🟡 |
Sau mission công cụ |
Điều tra nguyên nhân gốc sinh ra orphan, bịt đường đẻ; TD-131 đã fix 1 lần nhưng tái phát |
| TD-S178-10 |
Luật NT15 WHITELIST-FIRST chưa ban hành — well-known fix B2 đã deploy nhưng không có luật nền |
🟡 |
Sau mission công cụ |
Ban hành NT15 HP v4.7.0 hoặc Đ44 (pending Council quyết định format) |
Rollback sẵn sàng cho deploy cắt LLM (S178 Fix 9):
- Image:
docker tag agent-data-local:pre-s178-cutllm agent-data-local:latest && docker compose up -d agent-data
- Source:
cp /opt/incomex/docker/agent-data-repo/agent_data/server.py.bak-s178-20260417-040440 .../server.py
- Env toggle:
SEARCH_SYNTHESIZE_MODE=summarized trong .env → restart (không rebuild)
✅ KIẾN TRÚC — §0-AV RESOLVED (Mission 2.5 PR #642)
| TD |
Mô tả |
Priority |
Target |
| TD-413 |
pivot_definitions raw PG → CLOSED: registered Directus (18 fields, permissions set) |
✅ |
S141 |
| TD-414 |
refresh-counts chưa dùng pivot_count() → CLOSED: refresh_meta_catalog_from_pivot() created |
✅ |
S141 |
🔴 CHÍ MẠNG — ĐỒNG BỘ (Huyên S140)
| TD |
Mô tả |
Priority |
Target |
| TD-398 |
27 Directus Flows liveness MÙ |
🔴🔴 |
S170 |
| TD-399 |
Event system liveness MÙ |
🔴🔴 |
S170 |
| TD-400 |
Content sync MÙ (AD 595 vs Directus 382 = 213 drift!) |
🔴🔴 |
S170 |
| TD-401 |
Lớp 2 Safety Net CHƯA TRIỂN KHAI |
🔴🔴 |
S170 |
| TD-402 |
AD→Directus sync MÙ |
🔴 |
S170 |
🔴 HARDCODE DEBT — §0-AU (Huyên S141)
| TD |
Mô tả |
Priority |
Target |
| TD-408 |
Scanner hardcode 5/20 entity tables → meta-driven |
🔴 |
S170 |
| TD-409 |
CI guard hardcode files → derive từ contracts |
🟡 |
S170 |
| TD-410 |
Smoke test hardcode endpoints → derive từ routes |
🟡 |
S170 |
| TD-411 |
DOT origin whitelist hardcode array → table-driven (S169B ghi TODO) |
🟡 |
S170 |
| TD-412 |
D26 measurements hardcode → CLOSED: pivot_count() LIVE (PR #640) |
✅ |
S141 |
🟡 ACTIVE
| TD |
Mô tả |
Priority |
Target |
| TD-407 |
L1 API caching: PG thay đổi nhưng API stuck |
🟡 |
S170 |
| TD-403 |
meta_catalog cleanup path broken |
🟡 |
S170 |
| TD-404 |
smoke-test.sh chưa deploy VPS |
🟡 |
S170 |
| TD-395 |
Vector tool liveness + orphan visibility |
🔴 |
S170 |
| TD-083 |
Duplicate detection (Điều 14) |
🔴 |
Backlog |
| TD-396 |
Safe Delete mechanism |
🟡 |
Backlog |
| TD-394 |
Edge guard PG trigger |
🟡 |
Backlog |
| TD-359 |
Điều 31+ Gương Soi |
🔴 |
TBD |
| TD-354 |
Điều 32 Luật Registries → CLOSED: gộp vào Điều 26 v3.5 |
✅ |
S141 |
✅ ĐÃ GIẢI QUYẾT (gần nhất)
S169B (PR #639): TD-405 ✅ (C1 regression), TD-406 ✅ (scanner phantom+NULL).
S141 Mission 2.5 (PR #642): TD-413 ✅ (pivot_definitions→Directus, 18 fields, CAT-024), TD-414 ✅ (refresh_meta_catalog_from_pivot()). Luồng PG→Directus→Nuxt verified.
S141 Mission 2 (PR #641): DOT-113 dot-pivot-declare ✅, DOT-114 dot-pivot-health ✅. 6/7 PASS (1 expected WARNING).
S141 Mission 1 (PR #640): TD-412 ✅ (pivot_count() LIVE, 30 triggers #DISABLED). ⚠️ Nhưng phát hiện vi phạm §0-AV: pivot_definitions chưa register Directus → TD-413, TD-414.
S141 Mission 0.5: B1 ✅ (TRUNCATE privilege), B2 ✅ (count_material), B3 ✅ (code sync v13). 8/8 contract tests PASS. TD-354 CLOSED (gộp Điều 32→Điều 26).
S141 Hiến pháp: v3.8→v3.9. Điều 26 v3.5 BAN HÀNH. Sửa nhẹ Điều 19/21/28.
S168 (PR #638): TD-382 ✅. D26 method=2. Cron 3 entries.
Điều 30 (PR #637): Guard 13→23 files.
Chuỗi S163-S169B: 17 PRs. Chaos 2/21→23-26/31 (nhưng FLAT sau S168).