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 / 集成检查清单

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

8.4 KiB Raw Blame History Unescape Escape