group_fqcd_jr/docs/场外外部服务灰度与回滚方案.md

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

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、失败原因和回滚结论。