# Dashboard Mail Module Planning / Dashboard 邮件模块规划

## Overview / 概览
This document outlines the proposed dashboard mail module that integrates a multi-tenant
email experience with tenant-scoped AI assistance. The design aligns with the user's
requirement of keeping the mail capabilities cohesive inside the dashboard and enforcing
tenant isolation end-to-end. / 本文档概述了在 Dashboard 中集成多租户邮件体验和租户级
AI 助手的规划方案，满足“邮件子模块”高内聚的目标，并在前后端全链路落实租户隔离。

## Frontend Structure (Next.js) / 前端目录结构（Next.js）
```
dashboard/app/
│  ├ mail/
│  ├─ (tenant)/[tenantId]/mail/
│  │  ├─ page.tsx                # Inbox view 列表 + 过滤 + 分页
│  │  ├─ compose/page.tsx        # Compose / Reply / Forward
│  │  ├─ settings/page.tsx       # Account mapping, signatures, aliases, keys
│  │  └─ message/[id]/page.tsx   # Message detail with AI summary & smart reply
│  └─ api/
│     └─ mail/                   # Edge proxy or upload signature (optional)
├─ components/mail/
│  ├─ Inbox.tsx
│  ├─ MessageItem.tsx
│  ├─ MessageView.tsx
│  ├─ ComposeForm.tsx
│  └─ Toolbar.tsx
├─ lib/
│  ├─ apiClient.ts               # Fetch helper with tenant context
│  ├─ auth.ts                    # OIDC/JWT parsing, inject tenantId/userId
│  └─ types.ts                   # Shared TS types (Message, Thread, Label, etc.)
└─ store/
   └─ mail.store.ts              # Lightweight state for query/filter/page
```

### Frontend Guidelines / 前端要点
- URL paths carry the `tenantId` explicitly and are validated against the `tid` field in
  the authenticated JWT. / URL 显式携带 `tenantId` 并与 JWT 中的 `tid` 校验一致。
- Every backend request attaches an `x-tenant-id` header; the backend re-checks the
  header against JWT claims. / 所有后端请求都加 `x-tenant-id` 头部，后端二次比对。
- Large attachments use S3 direct uploads. The frontend obtains a pre-signed URL from the
  backend, then performs a `PUT` directly to S3 to avoid saturating the backend. /
  大附件通过后端获取预签名 URL 后直接 PUT 到 S3，减少后端带宽占用。
- Components keep AI-specific render logic (summary, reply suggestions) inside
  `MessageView` while surfacing controls via `Toolbar`. / AI 摘要与智能回复逻辑在
  `MessageView` 内封装，通过 `Toolbar` 暴露交互控件。

## Backend Service Layout (Go) / 后端服务目录结构（Go）
```
cmd/mailapi/main.go
internal/
  auth/
    middleware.go          # JWT/OIDC validation, inject tid/uid into context
  imap/
    client.go              # Dovecot IMAPS (emersion/go-imap)
    fetch.go               # Listing, fetch, read-state updates
    flags.go               # Star, archive, delete
  smtp/
    sender.go              # SMTPS 465 (emersion/go-smtp or SMTP AUTH)
  s3/
    presign.go             # Upload/download presigned URLs
  ai/
    summarizer.go          # Summaries, highlights, action items
    classifier.go          # Auto labeling & priority tagging
    reply_suggest.go       # Smart replies (few-shot prompts)
    namespace.go           # Tenant-scoped models, quotas, vector stores, logs
  search/
    indexer.go             # Optional metadata indexing (PG/Meilisearch)
  http/
    server.go              # chi/fiber/gin wrapper
    handlers.go            # HTTP route registration
  core/
    types.go               # Message, Thread, Attachment, AIResult, etc.
    config.go              # TLS/S3/IMAP/SMTP/AI configuration
    logger.go              # Shared structured logging helpers
```

### Backend Operations / 后端运行模型
- Communicate with Dovecot via IMAPS (port 993) and with Postfix via SMTPS (port 465 or
  587 + STARTTLS). / 与 Dovecot 通过 IMAPS:993，Postfix 通过 SMTPS:465 或 587+STARTTLS。
- The backend never exposes raw IMAP/SMTP credentials to the frontend; all mail access is
  proxied through the API. / 后端不向前端泄露 IMAP/SMTP 凭证，通过 API 统一代理。
- Each tenant receives an isolated AI namespace managed in `ai/namespace.go`, covering
  model choice, temperature, rate limits, vector indices, and audit logging. / 每个租户在
  `ai/namespace.go` 中拥有独立的模型、温度、速率限制、向量索引与日志策略。
- Tenant and user boundaries are enforced in `auth/middleware.go` by validating `tid` and
  `uid` claims on every request. / `auth/middleware.go` 统一校验 `tid` 与 `uid`，保证权限边界。

## HTTP API Contract / HTTP API 设计
All endpoints require `Authorization: Bearer <JWT>` and `x-tenant-id` headers, where the
header must match the JWT `tid`. / 所有请求必须携带 `Authorization: Bearer <JWT>` 与
`x-tenant-id`，且后者需与 JWT 中的 `tid` 一致。

### Mail Core / 邮件核心
- `GET /v1/mail/inbox?cursor=&pageSize=&label=&q=` — Returns a paginated inbox with light
  summaries and unread counts. / 返回分页收件箱、摘要与未读计数。
- `GET /v1/mail/message/:id` — Returns message body (HTML/text), attachments, cached AI
  summaries. / 返回邮件正文、附件元信息及缓存的 AI 摘要。
- `POST /v1/mail/send` — Sends mail through SMTPS and persists to the Sent folder. /
  通过 SMTPS 发送邮件并写入已发送。
- `DELETE /v1/mail/message/:id` — Moves to trash or marks deleted. / 标记删除或移动到废纸篓。

### Attachment Flows / 附件直传
- `POST /v1/mail/attachments/presign` — Request S3 upload URL for large attachments. /
  获取大附件直传 S3 的预签名 URL。
- `GET /v1/mail/attachments/:key/presign` — Fetch download URLs for existing attachments.
  / 获取附件下载签名 URL。

### AI Namespace APIs / AI 命名空间接口
- `POST /v1/ai/mail/summarize` — Summaries, bullet points, actions, tone analysis. /
  输出摘要、要点、行动项与语气分析。
- `POST /v1/ai/mail/reply-suggest` — Generates three draft replies given style and
  language preferences. / 根据风格与语言返回三条智能草稿。
- `POST /v1/ai/mail/classify` — Applies tenant-tuned labels such as Billing or Incident.
  / 自动打标签（计费、故障、人力、垃圾等）。
- `POST /v1/ai/mail/thread-digest` — Produces a thread-level digest with timeline. /
  输出会话摘要与时间线要点。
- `GET /v1/ai/namespace` — Returns the tenant's AI configuration and quota status. /
  查看租户 AI 配置与配额。
- `PUT /v1/ai/namespace` — Tenant admins update model, temperature, max tokens, and
  policies (e.g., sensitive-word restrictions). / 租户管理员修改模型、温度、最大 Token 与
  敏感词策略。

## Infrastructure Notes / 基础设施要点
- Domain separation: `smtp.svc.plus`, `imap.svc.plus`, `mail.svc.plus`, with wildcard TLS
  (`*.svc.plus`) via Let’s Encrypt or imported certificates. / 域名分离：`smtp.svc.plus`,
  `imap.svc.plus`, `mail.svc.plus`，TLS 使用 `*.svc.plus` 通配符证书。
- Adjust `stalwart.toml` to map SMTP/IMAP hostnames and keep DNS A records aligned for all
  three domains. / 在 `stalwart.toml` 中区分 SMTP/IMAP 主机名，并保持 DNS A 记录同步。
- The Web UI remains dashboard-driven; stalwart’s native UI stays disabled as a placeholder.
  / WebUI 以 Dashboard 为中心，stalwart 原生界面保持关闭占位状态。

## Integration Checklist / 集成检查清单
1. Implement the Next.js routes and components following the tenant-aware structure. /
   按租户结构实现 Next.js 路由与组件。
2. Wire `apiClient.ts` to automatically inject `Authorization` and `x-tenant-id` headers. /
   `apiClient.ts` 自动注入认证与租户头部。
3. Stand up the Go mail API with middleware enforcing tenant isolation and TLS-only
   upstream connections. / 部署 Go 邮件 API，确保中间件与 TLS-only 上游链路。
4. Configure S3 buckets, IAM roles, and stalwart connectors for attachment handling. /
   配置 S3、IAM 与 stalwart 附件处理。
5. Provision AI namespace defaults per tenant (model, temperature, quotas) and surface the
   settings page for admins. / 为每个租户设置 AI 命名空间默认值，并在设置页展示给管理员。
6. Validate end-to-end flows: inbox load, message view with AI summary, compose/send,
   attachments, and AI reply/classification actions. / 验证全链路：收件箱、AI 摘要、写信发送、
   附件、智能回复与分类。