group_fqcd_jr/docs/风控业务演示文档/21-主项目合并后后端必改清单.md

风控模块合并后自身待办清单

文档定位

本文只记录风控模块自身在合并后需要处理的问题和联调动作。

公共底座、公共事务能力、公共数据范围、公共鉴权基座和公共 SSE 协商等问题不纳入本文， 由主项目统一修复和发布。

本轮已完成

1. 证据查询时间口径统一

已完成：

• /api/v1/risk/evidence/transactions
• /api/v1/risk/evidence/capital_flows
• /api/v1/risk/evidence/login_records
• /api/v1/risk/evidence/notifications

以上入口收到不带时区的开始时间和结束时间时，按北京时间解释，再转换为 UTC 数据库查询时间，避免误查前后 8 小时的数据。

2. 通知记录查询时间口径统一

/api/v1/risk/notifications 已与本模块其他 REST 查询保持一致：

• 客户端裸时间按北京时间解释。
• 查询前统一转换为 UTC。
• 分页游标继续绑定用户、筛选条件和路径。

3. Agent 截断提示已补齐

奶龙风控智能助手在工具结果出现以下标记时，必须明确说明当前证据不完整：

• data_truncated=true
• evidence_truncated 非空
• truncated=true

Agent 不能把截断结果表述成覆盖全部数据，也不能据此给出确定性的全量结论。

4. 风控验收脚本密钥路径统一

以下脚本已改为读取 JWT_PRIVATE_KEY_PATH：

• tools/risk_agent_e2e.py
• tools/risk_agent_business_e2e.py

不再硬编码 config/jwt/jwt-private.pem。

5. 权限初始化脚本说明修正

tools/grant_risk_permissions.py 的文档字符串已改为实际文件名， 避免执行人员按错误路径操作。

联调前需要执行的动作

以下内容属于环境准备或数据初始化，不是代码缺陷：

1. 执行 python tools/grant_risk_permissions.py，确认风控角色具备：
   • risk:alert:read
   • risk:alert:write
   • risk:alert:scan
   • risk:report:mail
2. 执行 python tools/publish_risk_agent_config.py，确认奶龙风控智能助手的工具白名单和意图配置已发布。
3. 按主项目发布的迁移流程执行 Alembic 升级，确认 trigger_rule_codes 多值索引已生效。
4. 演示前准备足够的客户、交易、资金、持仓、登录和预警数据。
5. 使用前确认日报邮件开关、SMTP 配置和收件人范围符合演示要求。

当前保留限制

• 私有前端适配不纳入本文，等后端事项稳定后单独处理。
• read_at 和 acknowledged_at 只保留数据库能力，通知接口不返回，前端不展示。
• 定时扫描 Worker 启动后的首轮执行语义与 RISK_SCAN_RUN_IMMEDIATELY 的旧说明存在差异， 当前代码优先保证“开关启用后不会永不扫描”。如后续要恢复严格的首次执行开关语义， 需要单独设计执行时间的持久化和恢复方案。

验证要求

合并或联调前至少完成：

1. 风控专项测试通过。
2. Ruff 检查通过。
3. 全量测试无新增失败。
4. Agent 实际对话、证据查询、通知查询和日报邮件分别完成一次人工联调。