claw-email/requirements.md

PROJECT: EMAIL-OPENCLAW BRIDGE (STATEFUL, KISS)

1) Mục tiêu & phạm vi

Mục tiêu hệ thống:
- Tự động xử lý email bằng OpenClaw theo luồng:
  Ingress (IMAP) -> Dispatch (OpenClaw) -> Callback -> Egress (SMTP reply).

Phạm vi v1:
- Stateful bằng SQLite.
- Hỗ trợ email thread theo `thread_id`.
- Idempotency theo `message_id`.
- Webhook callback có xác thực bằng token đơn giản.
- Bổ sung health endpoints:
  - `GET /healthz` (liveness)
  - `GET /readyz` (readiness)
- Retry cơ bản (KISS) cho OpenClaw và SMTP:
  - Tối đa 3 lần với backoff: 1s, 5s, 15s.

Non-goals v1:
- Không rate limit.
- Không DLQ/reprocess UI.
- Không stack metrics nâng cao.

2) Công nghệ yêu cầu

- Ngôn ngữ: Go.
- Database: SQLite.
  - Khuyến nghị: `gorm.io/gorm` + `modernc.org/sqlite` (không cần CGO khi build Docker).
- IMAP: `github.com/emersion/go-imap` (+ IDLE).
- SMTP: `net/smtp` hoặc thư viện gửi mail Go tương đương.
- HTTP/Webhook: `gin-gonic/gin` hoặc `gofiber/fiber`.
- Proxy IMAP (optional): `golang.org/x/net/proxy`.
- Triển khai: Docker + Docker Compose.

3) Database schema

Bảng `tasks`:
- `id` INTEGER PRIMARY KEY AUTOINCREMENT
- `task_uuid` TEXT UNIQUE
- `thread_id` TEXT
- `message_id` TEXT
- `sender` TEXT
- `subject` TEXT
- `body_plain` TEXT
- `ai_response` TEXT
- `status` TEXT
- `attempt_openclaw` INTEGER DEFAULT 0
- `attempt_smtp` INTEGER DEFAULT 0
- `last_error` TEXT NULL
- `next_retry_at` DATETIME NULL (chỉ cần nếu retry xử lý theo scheduler/worker)
- `created_at` DATETIME
- `updated_at` DATETIME

Danh sách trạng thái hợp lệ:
- `IGNORED`
- `RECEIVED`
- `AI_PROCESSING`
- `CALLBACK_DONE`
- `SMTP_RETRYING`
- `COMPLETED`
- `FAILED`

4) Luồng xử lý chi tiết

4.1 Ingress (IMAP)
- Theo dõi mailbox qua IMAP IDLE.
- Nếu có `IMAP_PROXY_URL` thì kết nối IMAP qua proxy; nếu không thì direct.
- Khi có email mới:
  1. Anti-loop: nếu `sender` trùng email hệ thống -> `IGNORED`.
  2. Idempotency: nếu `message_id` đã tồn tại -> bỏ qua.
  3. External rules: chạy pipeline các rule configurable (whitelist, blocklist, v.v.). Nếu reject -> `IGNORED`. Rule metadata được lưu vào `dispatch_context`.
  4. Threading:
     - Nếu có `In-Reply-To`/`References`: tìm email cha trong DB, kế thừa `thread_id`.
     - Nếu không có: `thread_id = message_id`.
  5. Lưu DB với `status = RECEIVED`, bao gồm `dispatch_context` từ rules.

4.2 Dispatch (OpenClaw)
- Lấy nội dung email hiện tại và history của cùng `thread_id` (chỉ các bản ghi `COMPLETED`).
- Gọi OpenClaw API bằng HTTP client đi direct (không kế thừa proxy hệ thống).
- Payload tối thiểu:
  - `input`
  - `session_id` = `thread_id`
  - `history` (optional)
  - `callback_url`
  - `metadata.task_uuid`
  - `metadata.*` từ `dispatch_context` (rule-derived context)
- Cập nhật `status = AI_PROCESSING`.

Retry OpenClaw:
- Khi lỗi tạm thời: retry tối đa 3 lần theo backoff 1s, 5s, 15s.
- Mỗi lần retry tăng `attempt_openclaw`.
- Hết retry: `status = FAILED`, ghi `last_error`.

4.3 Callback + Egress (SMTP)
- Webhook nhận callback từ OpenClaw.
- Tìm task theo `metadata.task_uuid`.
- Nếu task đã `COMPLETED`: trả 200 và không cập nhật gì thêm (idempotent callback).
- Nếu hợp lệ: cập nhật `ai_response`, `status = CALLBACK_DONE`.

Gửi email phản hồi:
- Subject/Body theo kết quả AI.
- Bắt buộc set `In-Reply-To` và `References` khớp message liên quan để giữ thread phía người nhận.

Retry SMTP:
- Nếu lỗi tạm thời: chuyển `SMTP_RETRYING`, retry 3 lần theo 1s, 5s, 15s.
- Mỗi lần retry tăng `attempt_smtp`.
- Hết retry: `status = FAILED`, ghi `last_error`.
- Thành công: `status = COMPLETED`.

5) API contract & bảo mật

5.1 Callback contract (từ OpenClaw)
Required:
- `metadata.task_uuid`
- `result` (text)
- `status`

5.2 Xác thực webhook (KISS)
- Yêu cầu header: `X-Bridge-Token`.
- Giá trị kỳ vọng lấy từ `.env`, ví dụ: `BRIDGE_CALLBACK_TOKEN`.
- Thiếu/sai token -> trả `401 Unauthorized`.

5.3 Health endpoints
- `GET /healthz` -> `200 {"status":"ok"}` nếu process sống.
- `GET /readyz`:
  - kiểm tra DB writable,
  - kiểm tra cấu hình bắt buộc có đủ (IMAP/SMTP/OpenClaw/token),
  - nếu lỗi bất kỳ check nào -> `503`.

6) Logging & observability (mức tối thiểu)

- Structured logging ra stdout.
- Mỗi log liên quan xử lý email phải có:
  - `task_uuid`
  - `thread_id`
  - `message_id`
  - `status`
  - `attempt`
  - `error` (nếu có)

7) Cấu hình môi trường

Đọc từ `.env`:
- `IMAP_HOST`, `IMAP_PORT`, `IMAP_USER`, `IMAP_PASS`
- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`
- `OPENCLAW_URL`, `OPENCLAW_API_KEY` (nếu dùng)
- `BRIDGE_CALLBACK_TOKEN`
- `WHITELIST_EMAILS` (comma-separated)
- `BLOCKLIST_EMAILS` (comma-separated, optional)
- `SYSTEM_EMAIL`
- `IMAP_PROXY_URL` (optional)

Ví dụ:
- `WHITELIST_EMAILS="user1@example.com,user2@example.com"`
- `IMAP_PROXY_URL="socks5://user:pass@proxy-host:port"`

8) Docker triển khai

- Multi-stage build để tối ưu image size.
- `docker-compose.yml` mount volume cho SQLite DB (vd `database.db`).
- Xem log bằng: `docker logs -f <container_name>`.

9) Acceptance criteria (bắt buộc đạt)

1. Email hợp lệ đi hết pipeline và kết thúc `COMPLETED`.
2. Thread reply giữ đúng `In-Reply-To`/`References`.
3. OpenClaw/SMTP retry đúng thứ tự 1s -> 5s -> 15s.
4. Hết retry thì `FAILED` và có `last_error`.
5. Callback sai token trả 401 và không đổi state task.
6. Anti-loop + idempotency + external rules hoạt động đúng thứ tự.

10) Test matrix tối thiểu

1. Happy path: mail mới -> callback hợp lệ -> SMTP thành công -> `COMPLETED`.
2. OpenClaw fail 2 lần, lần 3 thành công -> `COMPLETED`, `attempt_openclaw = 3`.
3. SMTP fail hết retry -> `FAILED`, có `last_error`.
4. Callback sai token -> 401, state không đổi.
5. Duplicate `message_id` -> không tạo task mới.
6. Sender là chính hệ thống -> `IGNORED`.
7. Sender ngoài whitelist -> `IGNORED` bởi external rules.
8. Sender trong blocklist -> `IGNORED` bởi external rules.
9. Rule metadata được truyền qua dispatch context đến OpenClaw.