group_fqcd_jr/to_do_list.md

场外基金申购赎回后续任务清单

更新方式：完成一项实时打勾，并补充验证结果。 范围：场外基金申购赎回独立接口、独立表、真实能力配置入口和可回归测试。

• 1. 阅读项目规范、现有代码、调用链、数据流、权限和影响面。 备注：已阅读根目录与子项目 AGENTS、CLAUDE、AI 阅读/执行/测试/输出规范、MVC 规范、Agent 接入说明、数据库基线、建表设计、接口文档、NL2SQL 接入说明、场外流程图和本 SKILL。
• 2. 明确本次需求并拆分邮件、识别、核对、统计、通知、审计任务。 备注：本轮按用户确认分两阶段推进：先做当前业务闭环兼容完善，再按上线方案接入真实 IMAP/OCR/SMTP；不改变现有成功链路和接口路径。
• 3. 完善邮件接收、补偿、幂等、编号和原始文件保存。 备注：新增独立 OffsiteMailWorker，按 INBOX UID 增量扫描，持久化游标、失败 UID、重试时间和租约；成功邮件才推进游标，失败邮件停留并可重启补偿。当前采用健康检查 + 轮询补偿，IMAP IDLE 事件循环仍未实现，不能据此直接进入正式生产。
• 4. 完善附件分类、OCR/LLM 一次识别和识别异常处理。 备注：保持 summary 拆分、other 归档；新增字段缺失、低置信识别状态分流，不覆盖原始识别字段。
• 5. 完善 NL2SQL、Plan and Execute 和查询失败隔离。 备注：恢复并复用 nl2sql_yc.query_dict；新增场外专用适配器隔离调用参数和副作用；触发查询后独立保存每条规则查询记录并回填查询阶段计划状态。
• 6. 完善确定性计算、申购规则和赎回规则。 备注：继续使用确定性规则引擎；已覆盖申购金额 0.99/1.00/1.01 元、20% 比例边界、赎回可用份额等于和超出边界。
• 7. 完善人工确认、汇总统计、邮件返回和独立通知路由。 备注：已补充人工确认审计、统计扩展字段、通知发送前状态约束、脱敏 payload 和发送中超时接管；邮件整体完成判定、资金清算触发及完整混合邮件路由仍未闭环。
• 8. 完善配置、权限、日志、重试、审计和数据安全。 备注：场外写接口在 Service 层增加角色和权限二次校验；人工确认、NL2SQL 触发、通知创建写入 interaction_audit；通知 payload 对账户标识脱敏。
• 9. 新增真实 IMAP 收信适配层，默认关闭并支持健康检查、自动重连和增量补偿扫描。 备注：新增 OffsiteImapReceiver，默认由 OFFSITE_IMAP_ENABLED=false 关闭；支持健康检查、缺配置识别、只选 INBOX、按 UID 增量扫描、白名单发件人过滤、扫描边界记录和连接关闭后下一轮重连。IMAP IDLE 仍未实现，当前由 Worker 轮询补偿。
• 10. 新增原始 MIME 邮件和附件受控保存流程，保留 UID、Message-ID、附件哈希、路径、失败原因和重试记录。 备注：新增 OffsiteMailStorage 保存原始 .eml 与附件；附件路径包含 SHA256 前缀，避免同名不同内容覆盖；Worker 失败时持久化游标和邮件级错误/重试字段，并保留原始文件。真实对象存储、容量治理、备份和保留期限仍需上线前配置。
• 11. 新增阿里云 OCR/Document AI 与 DeepSeek 识别适配层，默认 Mock，可配置真实调用、超时、降级和脱敏日志。 备注：新增 OffsiteDocumentRecognitionAdapter，默认 OCR/DeepSeek 均关闭并走本地 Mock；开启后通过配置化 HTTP endpoint 调用 OCR 网关，通过 DeepSeek OpenAI-compatible /chat/completions 进行分类和字段 JSON 映射；支持超时、缺配置识别、失败关闭、Mock 降级、结构化字段、字段置信度、缺失字段和低置信字段输出。阿里云官方直连签名/SDK 接入仍需在真实联调阶段确认，不在本轮新增依赖。
• 12. 新增 SMTP 邮件发送适配层，默认 dry-run，发送前必须运营确认，记录发送状态、provider message ID、失败原因和重试次数。 备注：新增 OffsiteSmtpSender，默认 OFFSITE_SMTP_ENABLED=false 且 OFFSITE_SMTP_DRY_RUN=true；发送前强制检查 operator_confirmed，支持回复原邮件、重新附加原附件、返回发送状态、失败原因和重试次数。新增发送中超时接管为“发送失败 + 人工核验”，不自动判断外部是否已投递；真实 SMTP 灰度尚未执行。
• 13. 为真实外部服务补齐 Mock 单元测试、集成测试、灰度验证步骤和上线回滚方案。 备注：新增 IMAP/原始文件保存、OCR/DeepSeek 识别、SMTP dry-run/真实发送 Mock 单元测试；新增通知成功幂等、失败状态回写和正常回复完成状态集成测试；新增 docs/场外外部服务灰度与回滚方案.md。真实生产灰度尚未执行，需上线前按文档人工执行。
• 14. 执行代码检查和自动化验证。 备注：本轮迁移后 pytest 全量 183 passed；ruff、mypy、权威文档检查和数据库结构审计均通过，当前数据库为 59 张业务表。
• 15. 再次阅读本 SKILL，核查是否有遗漏的内容和任务未生成到清单执行。 备注：已再次阅读桌面 SKILL；真实 IMAP/OCR/SMTP、真实发送状态机和邮件完成判定保留在后续未完成任务中。
• 16. 对功能和 BUG 进行测试。 备注：新增并通过场外专项测试，覆盖 nl2sql_yc.query_dict 适配、计划查询状态回填、低置信识别异常、缺权限拦截、IMAP 健康检查、只读收件箱增量扫描、白名单过滤、原始文件防覆盖保存、Worker UID 断点/失败恢复/身份拒绝/附件接线、SMTP dry-run、通知成功幂等、失败状态回写、发送中超时接管和正常回复完成状态。