feat(api): 升级开放 API 并支持投递回调

- 为 `/api/open/v1` 引入 Token scope、分页游标、幂等发信、发送事件与重试/取消能力。
- 新增投递事件签名回调与状态 webhook outbox，补充相关配置、迁移和测试。
- 同步更新 Web 端 API 类型、个人中心 Token 权限管理，以及中英文文档和 OpenAPI 契约。

deploy/.env.example

@@ -97,6 +97,16 @@ LANQIN_SMTP_PASSWORD=
 # 外部 SMTP 要求 STARTTLS / TLS 时改 true；本机 Postfix 默认 false。
 LANQIN_SMTP_REQUIRE_TLS=false
 
+# 开放 API 最终投递事件回调的 HMAC-SHA256 密钥。生产环境请使用高强度随机值。
+# 未配置时 /api/open/v1/delivery-events 返回 503。
+LANQIN_DELIVERY_WEBHOOK_SECRET=
+
+# 可选：把发送队列与最终投递状态主动推送给外部系统。URL 默认必须为公网 HTTPS。
+LANQIN_STATUS_WEBHOOK_URL=
+LANQIN_STATUS_WEBHOOK_SECRET=
+# 仅可信内网或本地测试可开启；开启后也允许 HTTP 与私网目标。
+LANQIN_STATUS_WEBHOOK_ALLOW_PRIVATE_HOSTS=false
+
 # 第三方客户端 SMTP 提交，由 LanQin API 监听 587/465；启用前必须配置可读 TLS 证书。
 LANQIN_SUBMISSION_ADDR=
 LANQIN_SUBMISSION_TLS_ADDR=

deploy/README.md

@@ -174,6 +174,24 @@ LANQIN_SMTP_PORT=25
 LANQIN_SMTP_REQUIRE_TLS=false
 ```
 
+如需把上游服务商或 DSN 处理器的最终送达、退信、投诉、拒收事件写回开放 API，请设置：
+
+```env
+LANQIN_DELIVERY_WEBHOOK_SECRET=replace-with-a-long-random-secret
+```
+
+回调地址、签名算法和事件格式见仓库中的 `docs/API.md` 与 `docs/openapi.json`。该接口未配置密钥时返回 `503`。
+
+如需把状态变化主动推送到集成方，可额外设置：
+
+```env
+LANQIN_STATUS_WEBHOOK_URL=https://integration.example.com/hooks/lanqin
+LANQIN_STATUS_WEBHOOK_SECRET=replace-with-another-long-random-secret
+LANQIN_STATUS_WEBHOOK_ALLOW_PRIVATE_HOSTS=false
+```
+
+事件先写入 SQLite outbox，再由后台 worker 投递；非 2xx 响应会按退避策略重试，最多 10 次。默认只允许公网 HTTPS，禁止重定向、URL 用户信息和私网/本机目标。只有可信内网或本地测试才应开启 `LANQIN_STATUS_WEBHOOK_ALLOW_PRIVATE_HOSTS`。
+
 Split stack 使用 `docker-compose.stack.yml` 时，API 容器默认会把 `LANQIN_SMTP_HOST` 覆盖为 `postfix`，让 Webmail 和 SMTP 提交都 relay 到 Postfix service。只有改用外部 SMTP 时才需要在 `.env` 明确填写 `LANQIN_STACK_SMTP_HOST` / `LANQIN_STACK_SMTP_PORT`。
 
 如果发送队列里出现 relay 失败，通常是 Postfix 会话被中断或外部 SMTP 配置错误。优先检查：