P3D3 — User Notification Board — Directus Exposure Design

Date: 2026-05-08 Status: DESIGN — chờ review. Chưa implement.

1. Mục tiêu

User (anh Huyên) cần xem cùng bảng thông báo mà AI dùng:

• Comment mới trên miếng nào
• Draft nào cần review
• Update/apply mới
• AI/agent nào đã đọc, ai chưa đọc

2. Kiến trúc boundary

PG (source of truth)
  ├── iu_notification_event
  ├── iu_notification_read
  ├── fn_iu_unread / fn_iu_mark_read / fn_iu_notification_board
  └── PG view (nếu cần)
       ↓
Directus (exposure layer)
  ├── Collection / custom endpoint backed by PG view/table
  ├── Permissions per role
  └── API endpoint
       ↓
Nuxt (render only)
  ├── Đọc từ Directus API
  ├── Không business logic
  └── Không kết nối PG trực tiếp

3. Đường truy cập theo vai trò

• AI/Agent truy cập trực tiếp qua PG functions (fn_iu_unread, fn_iu_mark_read, fn_iu_notification_board). SQL là giao diện chính.
• Human user truy cập qua Directus/Nuxt exposure sau này. User không cần và không nên được kỳ vọng chạy SQL.
• Hai đường khác nhau, cùng một source of truth (PG).

4. PG exposure primitive — so sánh

Option	Ưu	Nhược
PG View	Directus tự discover, collection-like, permissions dễ	Khó truyền actor param
PG Function qua Directus custom endpoint	Linh hoạt, truyền actor param	Cần Directus extension hoặc custom flow
Directus Flow + PG query	Không cần extension	Performance, maintenance

Khuyến nghị Phase 1: PG View cho board overview (không per-actor filter). Directus custom endpoint cho per-actor unread/board.

5. Actor identity convention

Actor	Ý nghĩa
gpt	GPT-5.5 Thinking
opus	Claude Opus
agent:codex	Codex agent
reviewer:gpt	GPT as reviewer
user:huyen	Anh Huyên

Tất cả dùng chung read-state model. Human read state cũng per-actor.

6. Human user experience

• User xem board → thấy tất cả events
• User thấy: "GPT đã đọc, Opus chưa đọc, tôi chưa đọc"
• User mark read → chỉ user:huyen hết unread
• AI actors không bị ảnh hưởng

7. Chưa implement trong P3D3

• ❌ PG view chưa tạo
• ❌ Directus collection/endpoint chưa config
• ❌ Nuxt component chưa code
• ❌ Hermes chưa bật
• ✅ Design note này là blueprint cho P3D4+

This design does not commit to a new Nuxt page. Any human-facing display must first try existing Directus/Nuxt assembly and requires later review.

8. Next steps

Pack	Nội dung
P3D4	Directus exposure design review + implementation (nếu approved)
P3D5	Optional display assembly review — no code-first Nuxt work
Hermes	Reviewer automation (separate review)