NỢ KỸ THUẬT: Agent Data Event System — ✅ RESOLVED

Ngày ghi nhận: 2026-02-25 Ngày xử lý: 2026-02-27 (WEB-88) Trạng thái: ✅ RESOLVED — Config fix, không cần code mới

---

Vấn đề (ĐÃ FIX)

Agent Data là bộ não chỉ huy nhưng event system không hoạt động do thiếu DIRECTUS_ADMIN_TOKEN trong container env.

Giải pháp (WEB-88)

Config fix: thêm DIRECTUS_ADMIN_TOKEN + DIRECTUS_URL vào docker-compose.yml agent-data service → restart → listener registered → CRUD sync ≤15s.

Verification checklist (Operating Rules §XI)

[ ] curl /events/status → enabled=true, listeners>=1
[ ] Tạo test doc → ≤30s xuất hiện trong Directus
[ ] Xóa test doc → ≤30s biến mất khỏi Directus

Hệ quả hiện tại:

• Directus knowledge_documents lỗi thời (sync bị TẮT)
• Nuxt không hiển thị nội dung mới
• User phải dùng "trí nhớ sinh học" nhắc agents
• 143+ documents trên Agent Data bị "mù" với Directus/Nuxt

Hệ quả tương lai nếu không giải quyết:

• Giao việc qua ai_tasks → kết quả ghi vào Agent Data → không ai biết xong chưa
• Chat với nhân viên/khách hàng → tin nhắn ghi mà không trigger notification
• External tools (Larkbase, Kestra...) có event riêng → không có webhook để kiểm tra/giám sát
• Orchestrator phải poll liên tục thay vì event-driven → lãng phí resources

---

Giải pháp: Webhook on Write

Nguyên tắc: Mỗi lần Agent Data thay đổi data → HTTP POST thông báo đến subscribers.

Kiến trúc

Agent Data API (create/update/delete document)
    ↓ (after successful write)
    ↓ Fire webhook(s)
    ↓
    ├→ Directus: CRUD tương ứng trên knowledge_documents
    ├→ [Tương lai] Notification service
    ├→ [Tương lai] Orchestrator event trigger
    └→ [Tương lai] External tool webhooks

Scope tối thiểu (Phase 1)

1. Hook after write trong Agent Data FastAPI:

   • Sau mỗi create_document / update_document / delete_document thành công
   • Gọi registered webhook URLs với payload: {event, document_id, path, title, timestamp}

2. Webhook registry — config file hoặc database:

   {
     "webhooks": [
       {
         "name": "directus-sync",
         "url": "https://directus.incomexsaigoncorp.vn/items/knowledge_documents",
         "events": ["create", "update", "delete"],
         "auth": "Bearer $DIRECTUS_ADMIN_TOKEN",
         "active": true
       }
     ]
   }
   

3. Directus sync handler: Map Agent Data doc → Directus knowledge_documents record

   • Create → POST knowledge_documents
   • Update → PATCH knowledge_documents (match source_id)
   • Delete → DELETE knowledge_documents (match source_id)

Scope mở rộng (Phase 2+)

• Webhook retry (failed → queue → retry 3x)
• Webhook health monitoring
• Event log (audit trail)
• Subscription API (agents tự đăng ký webhook)
• Filter by path/tags (chỉ sync specific folders)

---

Thông tin kỹ thuật

• Repo: Huyen1974/agent-data-test
• Code cần sửa: main.py hoặc tương đương (FastAPI endpoints)
• Merge protocol: gh pr merge <ID> --squash --delete-branch
• Bối cảnh lịch sử: Trước đây trên GCP dự kiến dùng Pub/Sub. Giờ trên VPS → tự xây webhook system
• One-way sync: Agent Data → Directus ONLY. Directus KHÔNG ghi ngược Agent Data (tránh circular loop)

---

Liên kết

• Operating Rules v1.6: knowledge/dev/ssot/operating-rules.md (Mục X ghi "reconcile mỗi 6h" → cần sửa thành "event-driven" sau khi triển khai)
• Data Sync Architecture: knowledge/dev/ssot/data-sync-architecture.md (cần cập nhật)
• Current limitation: knowledge/current-state/known-limitations.md

---

Ghi nhận bởi Claude Desktop — WEB-81 session — 2026-02-25