# 场外基金外部服务灰度与回滚方案

## 1. 当前实现边界

当前代码已经提供 IMAP、OCR/DeepSeek 和 SMTP 适配层，但所有真实外部调用均由配置开关控制：

- `OFFSITE_IMAP_ENABLED=false`：不连接收件邮箱。
- `OFFSITE_MAIL_WORKER_ENABLED=false`：不启动场外邮件自动编排。
- `OFFSITE_OCR_ENABLED=false`：OCR 使用本地 Mock。
- `OFFSITE_DEEPSEEK_ENABLED=false`：字段识别使用本地 Mock。
- `OFFSITE_SMTP_ENABLED=false`：不创建真实 SMTP 发送连接。
- `OFFSITE_SMTP_DRY_RUN=true`：即使发送接口被调用，也只生成待发送结果，不标记发送成功。

通知创建接口只创建待发送记录。真正发送必须调用独立发送接口，并传递运营确认状态。

场外 Worker 另受以下安全条件约束：

- `OFFSITE_MAIL_WORKER_ENABLED=true` 只是允许编排，不代表可以绕过身份校验。
- `OFFSITE_WORKER_USER_ID` 必须是数据库中已存在、经过实时角色和权限解析的操作用户；为空或无权限时自动写入失败关闭。
- Worker 使用 `offsite_mail_cursor` 持久化 INBOX UID、失败 UID、重试时间和租约；失败邮件不推进后续 UID。
- 当前实现使用健康检查、可配置 IMAP IDLE 和 UID 增量补偿；真实邮箱联调前仍必须按灰度阶段验证服务端对 IDLE 的支持。

## 2. 上线前检查

上线前必须由技术和运营共同确认：

1. 收件邮箱、授权码、发件人白名单和 SMTP 发件地址均使用密钥管理系统注入，不写入代码、日志或 Git。
2. IMAP 账号只能访问指定收件箱，服务账号不使用登录密码，使用邮箱授权码。
3. 原始 `.eml` 和附件目录有容量、权限、备份和保留期限方案。
4. OCR 网关已确认请求格式、签名方式、超时和费用上限。
5. DeepSeek 模型、配额、超时、结构化 JSON 格式和敏感数据处理策略已确认。
6. SMTP 收件人、回复原邮件规则、附件重新附加规则已经过运营验收。
7. 监控至少能发现 IMAP 连接失败、邮件解析失败、OCR/模型失败、SMTP 失败、重试耗尽和磁盘写入失败。

## 3. 灰度顺序

### 阶段一：离线验证

保持所有真实开关关闭，使用 Mock 邮件、OCR、DeepSeek 和 SMTP。验证重复邮件、白名单、附件哈希、识别异常、规则核对和审计。

### 阶段二：真实 IMAP、业务发送关闭

仅打开 `OFFSITE_IMAP_ENABLED=true`，保持 `OFFSITE_MAIL_WORKER_ENABLED=false`、OCR、DeepSeek 和 SMTP 关闭。此阶段只允许执行收件箱健康检查、只读 UID 增量扫描和 IDLE 事件等待，不启动业务 Worker，避免真实邮件误用 Mock 识别结果写入业务库。确认 UID 不回退、IDLE 超时/断线后能补偿、非白名单邮件不进入业务队列；若邮箱服务端不支持 IDLE，则将 `OFFSITE_IMAP_IDLE_ENABLED=false`，使用轮询模式。业务 Worker 只有在阶段三真实 OCR 和 DeepSeek 均健康后才允许开启。

### 阶段三：真实识别、发送保持 dry-run

打开 `OFFSITE_OCR_ENABLED=true` 和 `OFFSITE_DEEPSEEK_ENABLED=true`，保持 `OFFSITE_SMTP_ENABLED=false` 或 `OFFSITE_SMTP_DRY_RUN=true`。使用已脱敏测试附件验证字段、置信度、页面证据、缺失字段和失败降级。

### 阶段四：单收件人真实 SMTP

打开 `OFFSITE_SMTP_ENABLED=true`，保持 `OFFSITE_SMTP_DRY_RUN=false`，只允许运营选择的一封测试邮件和一个确认收件人。核对 `Message-ID`、`In-Reply-To`、附件内容、发送状态和 provider message ID。

### 阶段五：小流量业务灰度

先限定单个业务时段或有限业务邮件，持续观察一个完整业务周期。未完成发送、失败重试和人工确认记录不得直接计入资金清算统计。

### 阶段六：正式运行

只有阶段五无未解释失败、重复发送、错发收件人、原始文件覆盖或统计污染后，才扩大到正式业务范围。

## 4. 回滚操作

发生错发、重复发送、认证失败、外部费用异常、识别结果大面积异常或存储故障时：

1. 立即将 `OFFSITE_SMTP_ENABLED=false`，停止新的真实发送。
2. 如收件范围或解析异常，将 `OFFSITE_IMAP_ENABLED=false`，暂停收件扫描。
3. 如识别服务异常，只关闭 `OFFSITE_OCR_ENABLED` 或 `OFFSITE_DEEPSEEK_ENABLED`，保留原始邮件和附件，禁止用不完整识别结果自动核对。
4. 保留 `offsite_notification`、原始 `.eml`、附件和审计记录，不执行删除、覆盖或数据库降级迁移。
5. 将发送中的通知交由运营核对邮箱实际投递结果；不得仅依据本地请求超时再次发送。
6. 修复后先回到 dry-run 和单收件人灰度，再恢复正式发送。

## 5. 回滚后的数据处理

- `发送成功` 不自动重发，重复调用只返回已有成功状态。
- `发送失败` 只按剩余重试次数重试，超过上限转人工处理。
- `待发送` 记录保留，恢复服务后由运营重新确认。
- 原始识别值、原始查询值、程序计算值和运营最终发送正文不得互相覆盖。
- 统计必须重新执行并核对范围，未成功正常返回的邮件不纳入资金清算统计。

## 6. 验收记录

每次灰度至少记录：部署版本、配置开关、测试邮件标识、测试附件哈希、操作人、开始结束时间、实际收件人、发送状态、provider message ID、失败原因和回滚结论。