风控 P3 收尾与适当性豁免额度校验 #4
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: AI260626/group_fqcd_jr#4
Reference in New Issue
Block a user
合并 qyqy_develop_1 的第二轮工作：
基座层面的两处缺陷，都属于"静默失败"——排查成本高，且本项目已经各踩过一次。 1. tool_executor.py 的拒绝原因原先无法区分： - "意图压根没发布白名单"与"白名单里没这个工具"共用一句「工具不在当前意图白名单」， 运维不知道该去补发布配置、还是改白名单内容（客服与风控的意图码都要求三处对齐， 两次都因此多花排查时间）； - 权限与角色两处只说「缺少工具权限」，不说是哪一个。 现在四种情况各有独立 message，各自指向不同的处置动作。 同时把**审计与异常分离**：白名单内容、权限码、角色集属于内部配置，只写进审计； 异常 message 会随 API 响应返回给调用方，保持通用、不泄漏配置。 2. model_gateway.py 的 TASK_CAPABILITY 补齐风控的几处 task_type （risk_agent_chat / risk_analysis / risk_script / risk_summary / daily_report_suggestion）。 它们要的都是文本生成端点；不登记就会落到"未映射 → 返回全部 active 端点"的分支， 而能否选对端点取决于 model_endpoint_config 的**行顺序**——实测风控能跑通，仅仅因为 deepseek-flash(id=3) 恰好排在 qwen-embedding(id=5) 前面。这个隐式依赖现在消掉了。 未登记的 task_type 仍退回全部端点（保持原有保守策略：让故障表现为调用失败而不是 解析为空），但会记 warning，不再静默。 新增 tests/unit/service/test_tool_executor_denials.py（4 条），锁住"四种拒绝可区分" 与"内部细节只进审计、不进 message"。 ruff / mypy(135 文件) / 607 unit+contract 全绿。**为什么造探针**：ToolExecutor 的四种拒绝在真实链路上很难安全触发——要么改客服、风控的 生效配置，要么动 RBAC，两条路都会影响正在工作的 Agent。platform_probe 是个只读、无副作用 的探针：它只声明 probe 一个意图（所以意图分类只可能返回它）、没有发布工具白名单 （天然处于"未配置"状态）、工具只回显参数不碰业务数据。 **它立刻查出一个死分支**：探针报的是「工具不在当前意图白名单」，而不是我新加的 「该意图未配置工具白名单」。原因是 governance.resolve 会为每个 supported_intents **预填条目**（governance.py:55-61），未配置时得到的是**空元组**——所以 intent not in configured_tools 在运行期**永远不成立**，那个分支是死代码。 单元测试没能发现它，因为我在测试里手工构造了 configured={}，而真实链路不产生这个形状。 **这正是端到端测试的价值**：单元测试验证的是我设想的形状，端到端验证的是真实形状。 修法：改判"白名单为空"而非"缺键"，文案改为"该意图的工具白名单为空"，并注明经过 governance 装配后"完全没配"与"配了空列表"无法区分、也不假装能区分（两者运维动作相同）。新增一条按 **真实形状**（{"faq": ()}）构造的用例把它锁住。 实测：探针调用 → failed / AGENT_PERMISSION_DENIED，stderr 为 ForbiddenAgentError: 该意图未配置工具白名单（tool_executor.py:108）。 ruff / mypy(136 文件) / 611 unit+contract 全绿。分支 4 是最难构造的一种，两个前提缺一不可： 1. **工具的角色集合必须比 Agent 的更窄**。Agent 层的 validate_access（base.py:101）会先按 AgentDefinition.allowed_roles 拦截，两者一致时永远进不到工具层的角色校验。所以把 probe_alt 收窄为 ("risk_operator",)，而 Agent 仍允许 admin。 2. **调用者必须有工具要求的权限**，否则会先命中权限分支。所以脚本临时给 admin 授 probe:read，验证后撤销。 过程中又修掉一处自己写错的地方：探针的 handle 原先硬编码调用 PROBE_TOOL，导致分支 4 （需要调 probe_alt）与分支 2（需要调白名单之外的那一个）互相干扰——第一次跑出来的结果 是"工具不在当前意图白名单"。改为按消息里的 "alt" 选择要调的工具。 四种分支的实测结果，message 各自独立、指向不同处置动作： - 白名单为空 → 该意图未配置工具白名单 - 工具不在白名单 → 工具不在当前意图白名单 - 缺少工具权限 → 缺少工具权限 - 角色不符 → 角色不能使用工具 目标的另一半也验证了：审计里是完整细节（reason = "角色 ['admin'] 与工具允许的角色 ['risk_operator'] 无交集"，并带 tool_name / intent / trace_id），而异常 message 只有 "角色不能使用工具"、不含角色集合。**内部配置只进审计，不进客户可见响应。** 环境复原：生效配置 9 条（与起点一致）；sys_permission / sys_role_permission 中 probe:read 的行数为 0。**问题**：POST /api/v1/risk/daily-report/mail 原先只取 context 做 401 判定， **没有任何授权校验**；RiskDailyReportMailService.send 既拿不到 context、也不调用 AuthorizationService。收件人、标题、正文**全部由客户端决定** —— 一旦运维开启 SMTP （RISK_DAILY_REPORT_MAIL_ENABLED），它就是一个未授权的邮件发送器。 默认关闭（ENABLED 默认 false + DRY_RUN 默认 true）让它至今没出事，但那不是可依赖的保护。 **改动**： - send 改为 async 并接收 context，入口处 wait AuthorizationService.require( context, "risk:report:mail")。校验放在 **service 层**而不是 controller —— 本项目风控 端点的授权一律落在 service（risk_query / risk_action / risk_scan 等都是这样）， controller 只负责取 context；这个端点是唯一的例外，现在补齐。 - controller 相应改为 wait ...send(..., context=context)。 - 权限 isk:report:mail 已在上一轮随另外三个一起创建并授予 risk_operator 与 admin。 **实测**： - 9002(risk_operator) → **200** + {"status":"disabled","recipient_count":1}（默认关闭） - 9001(customer) → **403** AGENT_PERMISSION_DENIED「缺少操作权限」 **测试**：3 个既有用例改为 async 并传入带权限的 context；**新增** est_mail_service_requires_the_permission，断言无权限身份必须被拒 —— 钉住本次修复。 ruff / mypy(136 文件) / 623 unit+contract / 29 integration 全绿。docs/25 P2。核实后发现这两条其实是**同一处的两个表现**，所以一起修。 **① 列表级无条件放行** _assess_list_rule 收到 item 参数**却完全不看它**，对 RW-018 一律返回"可考虑放行"， 连理由文本都是硬编码的"现有摘要显示交易来自有效定投工单"。于是渠道不匹配、或证据里 根本没有工单信息的预警，在列表层就被标成可放行 —— 而列表正是风控专员最先看到的一屏 （详情层另有判断，但那要等人点进去）。 现在按 item["evidence_snapshot"]["channel"] 判断。快照里确实有渠道：扫描侧写入了它 （risk_scan_service.py:308），列表行也带出了整个 snapshot（risk_repository.py:955）， 所以这个校验是可行的，此前只是没做。 **② 详情级与扫描侧口径不一致** 扫描按 work_order.channel in {"定投", "自动定投"} 生成预警（risk_scan_service.py:294）， 详情级却只认 "定投"。于是"自动定投"的预警会出现**"扫描认为有效、详情认为未确认"**的 自相矛盾。 抽出 DIRECT_INVESTMENT_CHANNELS = frozenset({"定投", "自动定投"}) 作为唯一口径， 列表级与详情级都改用它；改这份常量即同时影响两侧。 新增 tests/unit/service/test_risk_judgement_rw018.py（6 条）：常量覆盖扫描侧全部渠道、 列表级在无渠道 / 渠道不符时**不得**放行、两个合法渠道在列表级与详情级都放行、 详情级对无关渠道不放行。 ruff / mypy(136 文件) / 629 unit+contract 全绿。docs/25 P2。核实后比报告描述的更麻烦一点：合并后的 evidence_snapshot 只留 product_id 与 merged_alerts，**各条规则原有的证据键被塞进了嵌套结构** （risk_scan_service._merge_same_transaction_alerts:398-404）。而各研判函数读的是 **顶层键**（snapshot.get("ratio") 之类），于是合并过的预警一律读不到证据、降级成 "缺证据无法复核" —— 合并本来是为了少几条噪音，结果把这些预警的研判全废了。 修法：在**研判入口统一摊平**，而不是让每条规则各自去认嵌套结构。 - 新增 _flatten_merged_evidence(detail)：顶层已有的键优先（来自 priority_score 最高的 主预警），再按顺序补入各子条目 evidence 里的键；merged_alerts 本身保留， 可追溯性不受影响；非合并结构原样返回。 - 列表级（_assess_list_rule）与详情级（_assess_detail_rule）两个入口都调用它， 所有规则（RW-003/007/012/015/018）一并受益。 新增 tests/unit/service/test_risk_judgement_merged_evidence.py（5 条）：非合并结构原样返回、 嵌套键被抬到顶层、冲突时顶层优先、多子条目全部抬平，以及**报告症状的回归** —— 对比"没有 ratio"与"ratio 藏在 merged_alerts 里"两种输入，摊平后 RW-003 的研判结果 不再相同（原先两者都会降级成同一句话）。 ruff / mypy(136 文件) / 637 unit+contract 全绿。docs/25 P2。核实确认报告准确，而且这一处缺口造成两个症状： _alert_row 是**列表 / 详情 / 日报共用**的行构造器 （risk_repository.py:174 / :276 / :321），而它的字段列表里没有 close_reason。于是： - 日报的"误报原因"分布恒为"未填写" （risk_daily_report_service.py:139 用 item.get("close_reason") or "未填写"）； - :243 的明细里同一字段同样拿不到值。 断的是"关闭误报时写入原因"这条链路的**下半段**：risk_action_service.py:70 把原因赋给 lert.close_reason、也确实存进了库（app/model/fund.py:368 有该字段），只是读取时没带出来。 修法是一行：在 _alert_row 里补上 close_reason。三个调用点同时受益；读取方都是风控侧 接口（需要 risk:alert:read），不涉及客户可见面。 新增 tests/unit/repository/test_risk_alert_row_close_reason.py（2 条）：关闭原因出现在行里； 未关闭时为 None 但**键必须在** —— 读取方靠 or "未填写" 兜底，键一旦缺失就永远只能走 兜底分支，那正是修复前的状态。 ruff / mypy(136 文件) / 639 unit+contract / 29 integration 全绿。原描述把三件事混成一条，逐项复核： **a. exclude 不要求"调查中"** —— 这是**业务规则**，不是技术缺陷。exclude 要求 "已确认 + 未闭环"（:63-66），resolve 额外要求"调查中"（:90）；不对称是事实，但 "误报关闭是否必须先经调查"属于业务裁定，代码里那两道门是有意设置的，看不出实现偏差。 需业务方定，不由技术侧单方面加门禁。 **b. min(20, score_before)** —— **误报**。BEHAVIOR_SCORE_INITIAL = 20 是**满分**（:18）， 扣分表 {"低":3, "中":5, "高":20}（:19）与之自洽（高危扣满归零），所以这个 min 是把越界 数据拉回合法上限的数据清洗；而且它**不是静默的** —— 审计里同时记了 behavior_score_before / deduction / after（:118-120）。原描述"静默改写"不成立。 **c. 真缺陷（原报告没写）**：ehavior_score 的初始值是 0 而不是满分 20， **导致扣分机制整体失效**。实测：fin_customer_profile.behavior_score 定义为 int NOT NULL（无默认值），现有画像 customer_id=9001 的值是 **0**。 于是 :103 的计算恒为 min(20, 0) - deduction = -deduction → max(0, ...) = 0： **扣分永远扣不动，行为分恒为 0**。且全仓只有 :109 一处给 behavior_score 赋值 （写入方只有风控结案），说明初始 0 来自插入画像时的显式赋值，没有任何地方初始化成 20。 影响：行为分是"预警结案 → 客户行为评分下降"这条链路的落点，现在这条链路**产出为零**。 修复点在**画像创建侧**（初始值应为满分），不在风控的扣分逻辑里。docs/05 §3.3 的列表样例是 data 为**纯数组**、 ext_cursor 与 has_more 放在 meta 里， 并明确「业务接口不得增加其他顶层字段」。而 RiskQueryService._page 返回的 {items, next_cursor, has_more} 被**整体塞进 data** —— 游标因此出现在**业务数据**里， meta 只剩 trace_id，两处都不符合契约。 改动： - 新增 _list_envelope(page, context)：把 _page 的结构拆成 data = items、 meta = {trace_id, next_cursor, has_more}。**service 侧不动** —— 它继续返回那个内部 结构，只是不再直接当 data 用。 - 3 个列表端点改用它：/alerts、/evidence/{source}、/notifications。 非列表端点（overview、详情、各类写操作）保持原样，不带游标。 **影响调用方**：这是接口形状变更。组员若写了前端读 data.items，需要改成读 data、 并从 meta 取分页元数据。改动依据是 docs/05 这个唯一权威接口文档（§20 也要求实现与 文档同步）。**合并时要提醒组员。** **实测**（9002 身份）： - /alerts?limit=2 → 顶层键 ['data','meta']、data 是 list（2 条真实数据）、 meta 键 ['has_more','next_cursor','trace_id'] - /evidence/customers 与 /notifications 同形状 - 对照 /overview（非列表）→ meta 只有 trace_id、不带游标 **测试**：3 处断言从 data["items"] 改为 data；/notifications 那处补上对 meta 的断言； 新增 test_list_endpoints_follow_the_documented_envelope，直接断言"data 是纯数组、 meta 恰好三个键、顶层恰好 data/meta"，把 §3.3 的契约钉住。 过程里踩了两个自己的坑：① 忘了 rom typing import Any（与 customer_service.py 同一失误， 被 ruff/mypy 当场抓住）；② 漏了 /evidence/{source} 这个列表端点，是测试先失败才发现的。 ruff / mypy(136 文件) / 640 unit+contract / 29 integration 全绿。docs/05 §3.8 要求游标绑定用户、查询条件、排序字段和方向，此前实现只把 offset 用 base64 包了一层：任何登录用户拿到别人的游标都能继续翻，换个筛选条件也能继续翻 （偏移量对不上就静默返回错页）。现在游标里携带 SHA-256 指纹： - 指纹口径 = user_id + data_scope/customer_ids + 查询条件（排除 limit/cursor） - 刻意排除 limit：它是分页参数、不是查询条件，算进去只会让翻页时改页大小失效 - /evidence/{source} 的 source 是路径参数，单独并入指纹，否则 customers 的 游标能直接拿去翻 products - 指纹不符一律 InvalidCursorError -> 400 INVALID_CURSOR（docs/05 §3.6） 新增 2 个单测：换用户/换筛选/换 data_scope 失效、改 limit 仍有效、 不同证据类型游标不互通。#23：413 是上传超限的标准语义，前端文档（风控业务演示文档 17）也已按 413 做提示 映射，所以不把代码降成 422，而是在 docs/05 §3.5 状态码表补登 413 —— 契约以"补齐" 而不是"改动"的方式对齐。 #24：/api/v1/risk/daily-report/stream 此前既不校验 Accept，又把鉴权留在 async generator 内部。后者更隐蔽：StreamingResponse 已经返回、响应头已经发出，403 只能 变成"200 + 半截流"。现在 controller 先 await service.authorize(context) 再判定 Accept，顺序与 §6.4 一致（鉴权先行，不用状态码差异做探测）。SSE 协商逻辑抽到 app/api/dependencies/negotiation.py，与 /agent-runs/{run_id}/events 共用同一口径， 避免同一种客户端在一个端点上 200、另一个端点上 406。 #25：复核后确认前半段不成立 —— §19 末尾写明业务域接口由各自业务文档登记，风控 15 条 端点已在 06-模块接口与字段映射.md 逐条登记。真问题是 §12 表里写的 /api/v1/risk-scans/**、/api/v1/risk-alerts/** 与实际实现 /api/v1/risk/** 不符， 按实际实现更新 §12 并加说明；顺带把风控文档里 /daily-report/mail 的权限从 "按主项目邮件策略执行"改为实际的 risk:report:mail。 新增 tests/unit/api/test_risk_stream_negotiation.py（7 例）。