AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
158 Commits 12 Branches 0 Tags
cf70ac49e9482c0ea655abbc3f054d360485a049
Commit Graph
82 Commits
Author SHA1 Message Date
wangjianlong_0626 8a0cbab636 fix(memory-projection): 订正 outbox 取值口径并接通画像投影链路 
背景：memory_sync_outbox 这条链此前**完全没有消费者**，且生产端照 docs/00 §6.4.6
写成大写 MILVUS/NEO4J + 中文「待处理」，而消费端按 target_store 的**值**分派 handler、
且只领 status in {pending, failed} —— 两个条件都不满足，事件任何消费者都领不到、
永久滞留且不报错（唯一键 (event_uuid, target_store) 对大小写无约束，MySQL 也不报错）。
根因是代码与测试都硬编码字面量，所以测试跟着一起错、谁也没拦住。

订正
- profile_generation_service：取值改为全仓一致的小写（milvus/neo4j/upsert/pending）
- 测试改为引用常量并断言消费端契约，不再硬编码（硬编码是本次跑偏的直接原因）
- 新增契约回归测试：断言大写值分派不到 handler、会进死信，谁改回大写立刻红
- 新增 tools/normalize_memory_sync_outbox.py：订正历史脏行（默认 dry-run、幂等）

接通投影链路（此前零消费者）
- 新增 Milvus 集合 user_long_term_memory_v1 及建集合工具（幂等、不覆盖已有集合）
- 新增 MilvusProfileProjection / MilvusProfileVectorClient，并修掉移植带来的两处必炸点：
  customer_id 由「必须 int」放宽为接受数字字符串（本仓所有生产者都写 str，
  不放宽则每个事件必然失败）；不可投影的 memory_key 由「整批 raise」改为跳过留痕
  （否则一条 constraint: 记忆毒死该客户整批，而受控词表 13 个键里有 7 个不满足前缀）
- 新增 MemorySyncOutboxWorker（领取/指数退避/死信骨架保留原样）并接入 WorkerRuntime
- milvus → 向量投影；neo4j → 复用主干 ProfileGraphProjectionService（方案 A，
  不引入第二套投影，避免同一事实在图中两种说法、违反主干既有的只投影已确认事实的不变式）
- 生产端从 memory_unit(status=active) 组装 memory_sources，随事件带上确定快照
- 前置移植 conversation_privacy：写外部存储前脱敏手机号/证件号/银行卡等

验证
- 新增 17 个单测；全量 2 failed, 1307 passed, 2 skipped
  （2 个失败为既有环境项：断言请求体中文原文而 httpx 序列化成 \uXXXX，非本次引入）
- mypy app → 0 错（227 文件）；audit_schema → 89 张业务表无缺失/意外，未改动表结构
- 真机：真实 embedding(1024 维) + 真实 Milvus 写入并回读通过
- 整合链路（测试记忆 → 生产端组装 → outbox → 消费端投递 → Milvus 回读）通过，
  且 MySQL 已回滚、Milvus 无残留

文档
- 新增 docs/32-记忆投影链路实现说明.md：真实口径、根因、契约与验证证据（供接手）
- AGENTS.md：新增该易错点；新增 Windows 中文输出乱码的正确命令（-X utf8）；
  校正测试基线与 mypy 文件数

未做：未改 docs/00 基线、未动数据库迁移、未改投顾线代码、未启动常驻 Worker。
遗留：投顾线两处生产者的 payload 缺 memory_sources，会被消费至死信，待架构师确认是否投影。
 2026-09-12 10:45:40 +08:00
wangjianlong_0626 cc6ae87f26 Merge remote-tracking branch 'origin/qyqy_develop' into nl-merge-colleague 2026-09-11 21:18:30 +08:00
qyqy a7e2d3eac0 fix(customer-service): 统一客服热线来源；补 transfer_required 出参（docs/05 §6.3 未兑现的一半） 
两个都是"代码里存在但没接对"的缺陷，都不是新功能。

## A1 客服热线在代码里有两个值（一个出口给假号码）

- `app/core/customer_service_rules.py:35` `CONTACT_PHONE = "15936583816"` ← 真号码，安全路由 6 处在用
- `app/service/agent/implementations/customer_service.py:155` `HOTLINE = "400-XXX-XXXX"` ← 占位符，兜底出口在用

后果：**同一个客服给客户两个不同的电话号码**。问"风险等级怎么划分"被安全路由处理时给真号码；
问一个知识库答不了的问题走兜底时给 `400-XXX-XXXX` —— 客户按这个号码永远打不通。

修法：`HOTLINE` / `SERVICE_HOURS` 改为**转发** `customer_service_rules` 的两个常量
（不是"改成相同的值"，而是引用同一对象，避免日后再次漂移）；工作时间也随之从
"每日 7:00-22:00" 统一为 "工作日 09:00-18:00"（与安全路由出口一致）。
新增守卫测试用 `is` 断言对象同一性 —— 值相等挡不住"两边各写一份恰好相同"的漂移。

## A2 `transfer_required` 既没落库也没出参

`docs/05` §6.3 一直规定 `GET /agent-runs/{run_id}` 的 `result` 里有
`transfer_required` / `transfer_reason`，但实现里两个都没有：前端判断"这轮要不要转人工"
只能靠**猜正文里有没有兜底话术的开头**（`docs/24` 自己把这称为权宜之计）。

- 写入侧：`conversation_message` **没有** `transfer_required` 列，加列要迁移且规则 4 禁止改既有
  字段定义 ⇒ 放进 `tool_calls` 这个现成 JSON 列，作为 `calls` 的兄弟键
  （`{"calls": [...], "transfer_required": bool, "transfer_reason": str|None}`）
- 读取侧：`RunQueryService.get` 取出来放进 `result`；**兼容历史行**（`calls` 裸列表 / None →
  按 False/None 处理，不抛异常、也不凭正文猜）

刻意**没做**的一半：`docs/05` §6.3 的 `result` 里还有 `degraded` / `degradation_reason`，
但 `CoreResult` 里根本没有这两个字段（降级信息目前只在工具出参里）—— 补它要改
`CoreResult` 并让各 Agent 传递降级状态，属另一个改动范围。**已在交付说明里注明这一半仍缺。**

## 真机验证

| 问题 | transfer_required | transfer_reason | 正文电话 |
|---|---|---|---|
「请介绍一下量子纠缠在基金估值中的应用」 | **True** | 置信度不足：score=0.571 gap=0.004 | 15936583816 ✅ |
「请帮我计算一下三体问题的数值解」 | **True** | 置信度不足：score=0.499 gap=0.011 | 15936583816 ✅ |
「基金申购后多久确认」（正常知识直返） | False | — | 无（正确） |
「你们公司明天会下雪吗」（闲聊出口） | False | — | 无（正确） |

（第一次我用"下雪"当兜底用例，结果它被闲聊出口正确接住了 —— 是我的期望值写错，不是代码问题。）

门禁：测试 1223 passed（新增 4 个用例）/ 3 failed（均为已知非代码缺陷）/ mypy 0 错。
 2026-09-11 21:17:47 +08:00
Windows bbf623a464 merge: integrate advisor capabilities on latest qyqy base 2026-09-11 21:03:58 +08:00
Windows f5dd5b8ba2 feat: add advisor rollout gate and rollback playbook 2026-09-11 20:28:21 +08:00
lzf_0626 f09ea9e988 Merge origin/NL_develop：客服画像出口、知识管理三端点、合规语境与知识向量链路 
NL 线（含其并入的袁聪场外/推广域）。唯一冲突是 .gitignore —— 双方都往同一区域加了
.workdir/，取对方版本（他的更完整，含 .tmp/ 与说明），顺带修掉我之前用
Add-Content -Encoding utf8 造成的编码混合（read 工具当时报 invalid UTF-8）。

合并后修的问题 —— 都不是"改别人业务逻辑"，是让门禁能绿：

1. 缺运行依赖 python-docx。document_parser.py 解析 .docx 用它，但 requirements.txt 与
   pyproject.toml 都没声明 —— 别人环境跑知识入库会直接
   ModuleNotFoundError: No module named 'docx'。已补声明。
2. ruff 7 项：其中 tests/conftest.py 的 F821 Undefined name 'Path'（他的 tmp_path 修复
   写了字符串注解 "Path" 却漏 import，运行时不求值所以没炸，但 mypy/ruff 会抓）、
   tools/publish_customer_service_config.py 的 F841 inherited_keys 死变量（他改同 key
   覆盖、换成 inherited_only 后忘删旧的）、3 处 E501，另 2 项 ruff --fix 自动修复。
3. 合规基线种子未跑：integration 的 test_compliance_seed_mysql 4 个用例要求
   agent_negative_word 有 7 条 active 且已复核、agent_reply_template 覆盖 6 场景。
   跑 tools/seed_compliance_baseline.py（11 条 active 规则 / 6 个场景模板）后 80 passed。

验证：ruff 干净 / mypy 180 文件 0 错 / unit+contract 1140 passed /
integration 80 passed / 表数 68（alembic 已在 20260911_merge_risk_heads）。

唯一失败 tests/unit/repository/test_fund_readonly_contract.py 是双方一致的既有缺陷：
它断言 Base.metadata 里的 fin_* 表集合，而实测为空集 —— 即该测试依赖别的测试先导入模型的
副作用，单独跑必失败。NL 方也明确"不修不报"，此处照办，仅记录。
 2026-09-11 20:22:59 +08:00
Windows 2376585898 feat: add dual-source quote health orchestration 2026-09-11 19:47:14 +08:00
zhangshy beb67f0a26 优化奶龙字段语义理解 2026-09-11 19:37:26 +08:00
Windows b6429e0e9c feat: add advisory product comparison tool 2026-09-11 19:20:32 +08:00
qyqy 7677aeaee1 merge: 并入同事的场外申购/推广/行情/NL2SQL 线（11 提交、334 文件） 
冲突仅 3 个文件，全部取并集（双方都没有需要丢弃的改动）：
- app/main.py：import 双方路由（我方 knowledge_management + 同事的 offsite_fund/
  promotion_material）；include_router 段本已自动合并
- app/service/agent/bootstrap.py：import 与工具注册均取并集
  （query_customer_profile + query_financial_data 都注册）
- tests/integration/test_config_release_mysql.py：outbox 清理同时保留
  架构师的 event_type 限定（防误删其它域 outbox 行）与同事新增的 peer_release_id

同事这轮带入：11 个 alembic 迁移（建 offsite_* / promotion_* 等表）、
场外申购与推广素材 Agent、financial NL2SQL 工具。
注意：本库尚无 offsite_*/promotion_* 表，跑相关测试前需要执行 alembic upgrade。

边界核对：同事的场外代码未写入场内交易表（fin_sim_order/fin_capital_flow/fin_cash_ledger），
符合 AGENTS.md 规则 8。
 2026-09-11 18:56:26 +08:00
qyqy 928d0bcea3 chore: 按评审恢复 5 份文档、审计补 agent_type、修订环境口径 
评审意见落地（§3.3 驳回删除 / §3.1 审计补充 / §1.4 解释器 / §2 编号）：
- docs/04、06、10、13、99 全部恢复（评审：删除收益为零、保留成本同样为零）；
  AGENTS.md 改为"保留但仅作历史参考"并列入 D 类，ARCHIVE 归档说明加作废声明
- 治理审计补留痕：interaction_audit.detail 增加 agent_type 与 governance_rewrite
  （治理层会改写对外输出，事后必须能追溯到是哪个 Agent 触发的；不改表结构，detail 是 JSON 列）
  新增 tests/unit/service/test_agent_persistence_audit.py 锁住该契约
- AGENTS.md 修订环境口径：解释器各用本机可用的那个（.venv 被 gitignore、不进仓库）；
  config_release 与 Milvus schema 均属环境数据、不随代码合并，相关结论必须带环境限定；
  测试基线 1034；mypy 数字双方不可比（本机未装 sqlalchemy2-stubs，报错集中在模型层）
- docs/26 JWT 文档：因 21 已被风控迁移清单占用而改名，PR 描述里会单独说明
 2026-09-11 18:42:46 +08:00
qyqy 5f82ac5107 feat(knowledge): 检索字段名改为运行时探测，两套集合 schema 都能跑 
评审意见 §1.3 要求的修法。背景（双方实测共同确认）：同一批集合名在两个开发环境里是两套不同 schema：
  我方：knowledge_id / snippet（无 visibility），行数 106/177/73
  架构师：doc_id / content / chapter / section / doc_no / visibility，行数 125/297/214
上一轮我把字段名硬编码成我方那套，在架构师环境会让 Milvus 报 field doc_id not exist
→ 三集合全失败 → 客服一律转人工（反向亦然）。硬编码任一套都会打挂另一套。

改法（采纳评审建议）：
- 新增 app/core/knowledge_schema.py：describe_collection → 逻辑名到物理名映射，按集合缓存；
  缺必需字段的集合明确判为不可用并如实记 degraded，不静默零召回
- 检索服务改为逐集合探测：output_fields 只请求实际存在的字段；visibility 过滤有该字段才拼
- KnowledgeHit 对外形状不变，检索逻辑（字面召回/父子块/去重/置信判定）一行未改

测试：新增 17 个探测单测；架构师的关键词召回测试参数化为两套 schema 各跑一遍。
 2026-09-11 18:42:42 +08:00
Windows 930dd59d67 feat: complete advisory market data refresh pipeline 2026-09-11 18:39:57 +08:00
yuancong_0626 3f7c5ca74f merge: 同步 origin/qyqy_develop（风控扫描、知识检索、客服 Agent、协商等） 
冲突处理：均为双方各自新增，按并集保留——
- .gitignore：本地 data/logs 忽略项 + 远端 .dsh-drop/
- app/core/config.py：offsite/promotion 与 risk_scan 配置项并存
- app/service/agent/bootstrap.py：场外/推介/风控/NL2SQL/知识检索 工具与 Agent 全部注册
- app/worker/__main__.py：场外邮件 Worker 接线 + runtime 关系服务/投影清理注入并存

收尾：新增 20260911_merge_risk_heads 收敛迁移双 head；按 docs/21 生成 config/jwt/dev 开发密钥。
 2026-09-11 17:32:47 +08:00
yuancong_0626 61861cdef6 袁聪merge：合并分支 2026-09-11 17:26:18 +08:00
yuancong_0626 fd9598efdf 袁聪的第二次提交，项目已完整 2026-09-11 16:57:47 +08:00
Windows 852bafb374 feat: add profile drift governance workflow 2026-09-11 16:42:31 +08:00
lzf_0626 5bbf8481ef Merge pull request '信封补齐、适当性矩阵修正与 Worker 失败原因落库' (#5) from qyqy_develop_1 into qyqy_develop 
合并 qyqy_develop_1 第三轮工作：meta 信封补齐与公共化、适当性按第十二条匹配矩阵、Worker 失败原因区分固定文案与异常消息。
 2026-09-11 16:42:29 +08:00
zhangshy a122f7afba 修复风控预警记录查询与准备脚本 2026-09-11 16:40:15 +08:00
lzf_0626 fcd3eaadd6 Merge origin/qyqy_develop：风控时间口径补齐 + Agent 截断提示 
组员的 4 个提交（相对 c11e56c）：

- 4b0c148 把我这边的风控 P3 收尾与适当性豁免额度合并进 qyqy_develop（PR #4）
- 2ebe438 docs: 增加风控 Agent 工具白名单与意图配置
- 5102eaa Merge origin/qyqy_develop into RM2_develop
- d2cdbba 修复风控时间口径与 Agent 截断提示

自动合并零冲突，两侧的改动是互补而非重叠：

- 时区：我在 list_alerts 做了 from_local，他补的是 list_evidence 与通知列表；
- 截断：我加了 data_truncated / evidence_truncated，他在 risk_agent 的 system prompt
  里加了第 10 条 —— 这些标记出现时不得按全量证据下结论。方向是一致的。

验证：ruff 干净 / mypy 138 文件 / 703 unit+contract（+6，组员新增的用例）/
33 integration，均在合并后的工作树上跑过。
 2026-09-11 16:33:55 +08:00
lzf_0626 8b8883ccca Worker 失败原因不再只留类名：区分"可落库的固定文案"与"异常消息" 
起因是查 Worker 运行状态时发现库里 373 条死信的 last_error 全是裸的 "ValueError"
（工具 tools/probe_worker_state.py，证据 docs/evidence/worker-state.json）。
dispatch（run not found）、dispatch_run_completed、dispatch_memory_extraction、
dispatch_profile_rebuild 抛的都是 ValueError，只记类名等于把"哪一处失败"也一起丢了。

但"直接存 str(exc)"是错的：tests/unit/worker/test_outbox_worker.py 那条
RuntimeError("credential=do-not-log") 断言异常消息不得落库 —— 它可能含凭据、SQL 或
客户标识。第一版改动就是这么写的，被这个测试当场拦下（这测试写得值）。

折中：

- 新增 OutboxHandlerError（继承 ValueError，这些失败本就是 ValueError 语义，保持
  继承关系才不会改动既有的 except ValueError 行为与断言）。它的 reason 由代码写死、
  不含任何请求数据，因此可以落库；
- safe_error_text：OutboxHandlerError → "类名: 固定文案"（截断 500 字符），
  其余异常 → 仍只记类名；
- runtime.py 的 5 处 handler 失败改抛 OutboxHandlerError。

测试：新增"固定文案落库"用例；并把既有用例的断言收紧为 last_error == "RuntimeError"
（原先只断言"不含 do-not-log"，太松，漏掉的情况测不出来）。

顺带产出 tools/probe_worker_state.py（只读）：outbox / agent_run 各状态计数、按事件
类型分组、死信原因聚合。当前环境实测 pending 347、dead 373、published 410、
agent_run 无 queued/running。

门禁：ruff 干净 / mypy 138 文件 / 697 unit+contract / 33 integration。
 2026-09-11 16:28:19 +08:00
Windows 4088c634de feat: complete advisor conversation loop 2026-09-11 16:12:38 +08:00
qyqy cbd6de2721 Merge remote-tracking branch 'origin/qyqy_develop' into nl-merge-latest 
# Conflicts:
#	app/service/model_gateway.py
 2026-09-11 15:38:11 +08:00
Windows e8ec0af398 feat: add advisor recommendation review flow 2026-09-11 15:33:27 +08:00
qyqy 395bad25b7 fix(knowledge): 检索服务适配现库集合 schema、发布对齐的工具白名单、免责声明只由治理层注入 
合并暴露的三个真机问题（单测全绿但线上必挂）：

1. 检索服务字段名与现库集合不符 -> 静默零召回
   架构师那套按 load_knowledge_milvus.py 的 schema 读 doc_id/content/chapter/section/
   visibility，而现库三集合的真实字段是 knowledge_id/title/snippet/tags/version/intent。
   Milvus 对不存在的字段直接报错 -> 三集合全失败 -> degraded -> 客服一律转人工。
   改法：只改读取侧，用 _FIELD_ALIASES 映射；KnowledgeHit 对外形状不变（下游与测试不动）。
   代价已注明：没有 visibility 字段 -> 检索层内部资料硬隔离失效（现库 356 行均为对外知识）。

2. 发布白名单与代码上限不匹配 -> AGENT_PERMISSION_DENIED
   active 版本白名单是 query_knowledge，而合并后代码上限是 search_knowledge/check_suitability/
   query_customer_profile -> 交集为空 -> 所有知识问题 failed。
   改法：publish_customer_service_config.py 补 PROFILE_TOOL 进 faq 白名单，并让同 key 的
   继承项被本次定义覆盖（旧值原样继承会被子集校验 422 拒掉整次发布）。已激活版本 216。

3. 免责声明重复出现
   Agent 自己拼一句 + 治理层追加权威话术 -> 客户看到两条。改为只由治理层注入
   （话术属发布配置，改文案不该改代码）。风控等内部 Agent 不注入（结构化输出不被污染）。

测试：934 passed / 1 failed（test_fund_readonly_contract 既有空集缺陷，与本线无关）
真机：知识问答两问 succeeded 且只带一条声明；画像问答 succeeded；知识库三端点全绿
 2026-09-11 15:27:16 +08:00
zhangshy d2cdbbac01 修复风控时间口径与Agent截断提示 2026-09-11 15:25:45 +08:00
lzf_0626 8d79bd9767 补齐三个成功响应缺失的 meta 信封；信封实现抽为公共（docs/05 §3.3） 
"缺 meta"很容易被误判成"有"：X-Trace-ID 是**响应头**（中间件加），和 body 里的
meta.trace_id 是两件事；错误响应一直有 meta（异常处理器统一加），漏的只有成功路径。

核到三个端点在把 service 的内部结构直接当响应体返回：

- GET /conversations/{session_id}/messages → 裸 {"data": [...]}，meta 整个缺失，
  游标也没地方放（§3.3 要求列表的 data 为纯数组、next_cursor/has_more 进 meta）
- POST /conversation-messages/{id}/feedback → 同样没有 meta
- GET /knowledge-references/{token} → 直接返回资源对象

改动：

- 新增 app/api/views/envelope.py，把 envelope / list_envelope 抽成一份公共实现，
  风控链路改为复用它 —— 同一份契约写两遍的结果就是其中一处漏了 meta。
- ConversationService.messages 改为返回内部结构 {items, next_cursor, has_more}，
  用 limit + 1 判断 has_more：只看"取满没取满"会把恰好等于 limit 的最后一页说成
  还有下一页。next_cursor 取本页最后一条的 message_id —— 游标语义是"取更旧的一页"，
  天然可续，集成测试本来就是这么翻页的。
- Controller 统一套信封，data 仍是数组、字段名不变，前端不需要改。

测试：新增 tests/unit/api/test_response_envelope.py，断言 set(body) == {"data","meta"}
（多或少一个顶层字段都会红），并覆盖 has_more / next_cursor / trace_id；
另更新两处既有断言（limit 20→21、feedback 返回裸对象）。

门禁：ruff 干净 / mypy 138 文件 / 696 unit+contract / 33 integration。
 2026-09-11 15:21:36 +08:00
Windows 13bb4f257d feat: add allocation backtest evidence 2026-09-11 15:08:37 +08:00
qyqy 57c4add7d8 merge: 客服Agent+RAG+画像 与 架构师最新 qyqy_develop 合并 
- customer_service.py 以架构师实现为骨架（三档置信/适当性/会话记忆/话题矩阵），嫁接本人画像出口
- 知识检索契约合并两条链路：架构师 search_knowledge(KnowledgeSearchInput) + 本线
  query_knowledge 链路所需常量（ALLOWED_CONSTANTS/VECTOR_DIM/intent_for_qa_id）
- bootstrap 保留架构师 6 工具/3 Agent，补回 query_customer_profile 与 get_milvus_knowledge_writer
- model_gateway 能力映射修正 intent_classification→chat，保留空集回退兜底
- governance 免责声明限定面向客户 Agent（agent_type 由定义透传），风控结构化输出不再被追加
- 修 JWT 密钥路径(config/jwt/dev)、文档 21 号撞号→25
- 测试基线 934 passed / 1 failed（既有空集缺陷）
 2026-09-11 15:06:44 +08:00
lzf_0626 575b4c2baa 客服适当性改按第十二条匹配矩阵（更正我上一轮的复核结论） 
你说得对：C ≥ R 是风控的口径，客服要走政策原文的矩阵。

上一轮我复核后说"两边一致、无需改动"是错的 —— 我只对比了政策文本与
SuitabilityService，漏了第三个东西：客服自己的知识库。POL-AST-012 就是第十二条矩阵
原文，而客服为 C1-C5 补的「能买什么产品」问答答案直接取自该矩阵（docs/24 第二节）。
于是同一个客服 Agent 对同一个问题给出相反答案：

  问"C1 能买什么产品"   → 知识检索答 R1、R2 可买（矩阵口径）
  问"C1 能买这只 R2 吗" → 适当性出口答不能购买（严格 C ≥ R）

政策冲突的精确位置也不是"矩阵 vs 硬匹配"，而是第十四条**第 1 款与它自己的第 2、3 款**
矛盾：第 2 款说"低于一个等级以上"才拒绝（C1→R2 只低 1 级，够不上"以上"），第 3 款禁止
C1 买 R3+、C2 买 R4+（R2 不在禁止列表）。矩阵与第 2、3 款三方一致，孤立的是第 1 款。

改动：

- suitability_service.py 新增 MATRIX_ALLOWED / MATRIX_NEEDS_DISCLOSURE，_decide 由
  "C < R 即拒绝"改为按矩阵：C1→R2、C2→R3 直接可买；C3→R4、C4→R5 走第十五条豁免档
  （reason_code=SUITABLE_WITH_DISCLOSURE，强制揭示 + 确认 + 录音）；低两级及以上仍拒绝。
- 客服话术分档：越级档不再说"在您的风险承受能力范围内" —— 那句只对 C ≥ R 成立，
  用在 C1 买 R2 上会让客户以为自己的测评本来就覆盖这只产品。
- 风控侧不动，保留 C ≥ R：它要发现的是"越级成交且留痕不全"，这个差异是有意保留的。

测试：新增逐格对照政策原文的 25 格矩阵用例、豁免档用例、话术分档用例（+29）。
docs/25 第七节 #1 与 docs/24 第七节同步更正，包括写明我上一轮那个结论错在哪。

门禁：ruff 干净 / mypy 137 文件 / 693 unit+contract / 33 integration。
 2026-09-11 14:47:08 +08:00
wangjianlong_0626 e4c4099aaa wip: 客服Agent + RAG + 画像收尾（基于 6516ccb） 2026-09-11 14:46:40 +08:00
Windows ff71a1a724 feat: add dynamic advisor asset allocation 2026-09-11 14:44:29 +08:00
lzf_0626 ff681df143 落地第十五条豁免额度校验；登记三处业务裁定 
一、第十五条豁免规则（docs/25 第七节 #2，业务裁定：实现）

政策原文：C3→R4 签署风险揭示书后**可买**，但单只 R4 持仓不超过总资产 20%；
C4→R5 同理，上限 10%。越级购买本身不是违规，超出额度才是 —— 原先扫描侧只看
"留痕是否齐全"，于是"签了字但买超额度"这种明确违规没有预警；研判侧也把豁免的
前提条件（留痕齐全）当成了结论，直接判"疑似误报"。

- 扫描侧：新增 EXEMPTION_LIMITS 与 RiskRuleEngine._exemption_state，核算
  "单只持仓 / 总资产"并写进证据快照；触发条件改为
  gap > 0 and (missing_trace or 超出额度)。
- 研判侧：_assess_rw007 先判额度再判留痕。超限 → 证据支持风险；留痕齐全且在额度
  内 → 疑似误报；留痕齐全但快照缺总资产/持仓 → 继续复核。

数据前提（tools/probe_exemption_data.py，证据见 docs/evidence/exemption-data-probe.json）：
库内 fin_customer_profile 仅 1 行且 total_asset = 0.00、fin_holding 0 行、无任何申购
交易 —— 这条规则当前不会被触发，与 behavior_score 同源（画像与持仓由本项目之外的
流程写入）。因此刻意不把"算不出来"当成"超限"：拿 0 去算会让每一笔 C3→R4 都变成违规，
豁免规则反倒成了误报源。上游把数据写入后无需再改代码即可生效。

二、三处业务裁定（此前挂在"待裁定"）

- 模型网关 chat + tools 入口：本轮不补，按基座能力缺口记录。它要贯穿
  ModelGateway → … → BaseAgent 整条链路，属公共契约变更，演示联调期影响面大于收益。
- exclude（关闭误报）是否必须先"调查中"：保持现状，不加门禁。
- 政策冲突：以第十四条 C ≥ R 为准；客服侧 check_suitability 复核后确认本来就按
  C ≥ R 实现，无需改动。

三、其他

- 新增 tests/unit/service/test_risk_judgement_rw007.py（6 例）与扫描侧 4 例。
- 风控文档 03/05 同步 RW-007 的豁免额度条件与研判口径。
 2026-09-11 14:24:45 +08:00
lzf_0626 661b17c244 风控全量查询封顶并在响应里标注截断（docs/25 P3 #20） 
预警详情里的资金流水/持仓/登录记录、以及日报的四组预警都是"一次性取全量"。某个客户
的历史数据一旦异常膨胀，单次响应就能把内存和连接拖垮；登录记录此前更是连时间窗都
没有。

处理原则是"封顶但**不静默**"：详情证据每类最多 200 条、日报每组最多 5000 条，用
`limit + 1` 多取一行判断是否真被截断（只看"取满没取满"会把恰好等于上限的正常数据
误报成截断），被截断时：

- 详情新增 `evidence_truncated: string[]`，列出被截断的证据类型；
- 日报新增 `data_truncated: bool` —— 日报的 daily_alert_count 等数字直接来自行数，
  静默截断等于给出一份看起来正常、实际少统计的日报，那比报错更难发现。

`scalars(...)` 统一用 `list(...)` 而不是 `.all()`，实现不再依赖 ScalarResult 的专有方法。

新增 tests/unit/repository/test_risk_repository_limits.py（3 例，用 literal_binds
编译 SQL，确保断言看到的是 201 而不只是"有 LIMIT"），并补日报与详情的标记用例；
风控文档 06 同步登记两个新字段与写接口的幂等要求。
 2026-09-11 14:16:07 +08:00
Windows 8ffd08b4ce feat: add portfolio graph enrichment 2026-09-11 14:14:50 +08:00
lzf_0626 15866d4564 风控写接口接入平台幂等（docs/25 P3 #22） 
docs/05 §5.1 把"业务写接口"列为必须携带 Idempotency-Key 的接口，风控 6 个 POST
（手工扫描、确认接收、进入调查、关闭误报、完成结案、升级处理）此前一个都没带，
重复提交会二次驱动状态机。

复用平台的 api_request_receipt 与 ApiTransactionService，但新增 execute_in：原来的
execute 自己开 SessionFactory() 和 session.begin()，而 RiskActionService._finish
会在内部 commit，套进去就成了"内层提交外层事务"。execute_in 改为在调用方传入的
session 上读写幂等记录，幂等记录因此与业务写入同处一个事务（§5.2）。

scope 用实际路径（含 alert_no）而不是路由模板：§5.1 的幂等范围是
user_id + method + normalized_path + idempotency_key，把路径参数折成模板会让同一个键
在不同预警之间互相回放 —— 那是把两次不同资源的操作当成一次。

测试：单测加幂等透传替身与"缺键即 422"用例；新增
tests/integration/test_risk_idempotency_mysql.py，覆盖同键回放不重复执行、同键不同
正文 409、缺键/非 ASCII 拒绝，以及端到端"重复 POST 只调用一次处置逻辑"。
 2026-09-11 14:12:56 +08:00
Windows 47a5ca498c feat: complete advisor product suitability gates 2026-09-11 14:09:23 +08:00
lzf_0626 790518114b 风控 SSE 内容协商与鉴权时序；docs/05 补齐 413 与风控入口（docs/25 P3 #23 #24 #25） 
#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 例）。
 2026-09-11 14:08:55 +08:00
lzf_0626 a572c09a5c 风控列表游标绑定用户与查询条件（docs/25 遗留 P3） 
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 仍有效、
不同证据类型游标不互通。
 2026-09-11 14:05:37 +08:00
lzf_0626 e8b075bc7f fix(risk): 列表接口的信封对齐 docs/05 §3.3——游标从 data 挪到 meta 
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 全绿。
 2026-09-11 14:01:16 +08:00
lzf_0626 3ab7f33d64 fix(risk): 预警行带出 close_reason，日报的"误报原因"不再是空 
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 全绿。
 2026-09-11 13:51:37 +08:00
lzf_0626 b241059c2a fix(risk): 合并预警的嵌套证据在研判入口摊平，RW-003 不再一律降级 
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 全绿。
 2026-09-11 13:49:57 +08:00
lzf_0626 c1f043684c fix(risk): RW-012 研判补上"≥3 倍历史均值"复核，顺带修一处除零 
docs/25 P2。核实后发现**根因不在研判侧偷懒，而在快照缺数据**：

- 扫描侧生成 RW-012 要求 verage > 0 且 amount >= average * 3（risk_scan_service.py:224）；
- 研判侧 _assess_rw012 只看了年龄、金额、非常用设备，**完全没核均值** —— 于是达不到
  3 倍的交易也会被判"证据支持风险"。它自己的建议文本写着"继续核实一年期历史交易均值"：
  作者知道该看，只是当时确实没有数据可看。
- 原因：扫描侧写进快照的只有 product_id / age / device_id，**没有均值**
  （对比 RW-003 在 :124 就写了 ratio）。

**两侧一起改**：

1. 扫描侧补写 verage_amount 与 
atio（用 ratio 与 RW-003 的快照风格保持一致）。
2. 研判侧据此复核：
atio 缺失 → CONTINUE_REVIEW（"无法复核 3 倍门槛"，
   不再顺着"非常用设备"定案）；
atio < 3 → SUSPECTED_FALSE_POSITIVE；否则走原有逻辑。
3. **顺带修一处除零**：verage == 0 时 mount < 0*3 恒为 False，会一路走到
   mount / average 直接崩。改为同时挡住 verage_amount <= 0。

新增 tests/unit/service/test_risk_judgement_rw012.py（3 条）：ratio 缺失时不落到风险成立、
ratio < 3 判误报并给出倍数、ratio >= 3 继续往下走。三个用例都停在登录记录判断之前，
不必构造复杂的登录证据。

ruff / mypy(136 文件) / 632 unit+contract / 29 integration 全绿。
 2026-09-11 13:48:08 +08:00
lzf_0626 85a1b33eff fix(risk): RW-018 研判的两个口径缺陷——列表级不再无条件放行，详情级与扫描侧对齐 
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 全绿。
 2026-09-11 13:45:51 +08:00
lzf_0626 0d3447bde4 fix(risk): 日报邮件端点补上授权校验——它此前是风控里唯一没有校验的端点 
**问题**：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 全绿。
 2026-09-11 13:39:50 +08:00
lzf_0626 24de6c34f7 fix(risk): 扫描健壮性——脏数据不再中断整批，调度器重启后仍会执行 
docs/25 P0 的后两项，都属于"风控看起来在工作、其实没在跑"那一类。

**② 一条脏数据中断整批**
_level_value 原先直接 int(level.replace(prefix, ""))：等级字段只要有一条不是
R1-R5 / C1-C5（例如写了「中风险」），就抛 ValueError 并冒到 scan() 的兜底 → **整批
rollback**，本次扫描前面已经生成的预警全部作废。数据脏属于运维问题，不该升级成
"整个风控停摆"。

改为返回 int | None；调用点跳过该条并记 warning（带上 transaction_id 与两个原始值，
便于运维直接定位）。顺带把 
eplace 换成 
emoveprefix：原先 "R2R" 会被错当成 2，
现在只去掉开头那一个前缀字符。

**③ 调度器重启后永不执行**
last_run_at 只存在内存里，重启后为 None，而 _is_due 此时返回
config.run_immediately（默认 False）⇒ 重启后 _is_due 恒为假，**调度器形同虚设，
而且没有任何告警**。

改为"从未跑过即视为 due"：多跑一次的最坏后果是重复扫描，而扫描每条规则都先 _exists
查重、外层还有 MySQL 级锁；反过来"不跑"的后果可能是永远不跑。
config.run_immediately 不再承担"首次是否执行"的语义（它原本想表达"启动后别马上跑"，
但那与"永远不跑"在实现上无法区分），字段保留以免破坏既有配置。

新增 tests/unit/service/test_risk_scan_robustness.py（6 条）：脏数据返回 None 而不抛异常、
R2R 不被过度剥离、首次必 due（哪怕 run_immediately=False）、以及间隔前后的判定。

ruff / mypy(136 文件) / 622 unit+contract / 29 integration 全绿。
 2026-09-11 13:35:58 +08:00
lzf_0626 d331c817ac fix(risk): 通知创建失败必须能被区分出来，不再静默返回 0 
docs/25 P2「通知失败被吞」。核实后要把定性说得更准一点：它**有** logger.exception，
不是完全静默；问题在于 _create_notifications 失败时 
eturn 0，而"无需通知"
（没有高风险预警、或通知功能关闭）也返回 0 —— 调用方只拿到一个 notification_count，
**分不清"本来就不用通知"和"高风险通知创建失败"**。

风控里这个区别很要紧：通知没发出去等于处置链路的第一环断了，而扫描依旧报"完成"。
这与同一批缺陷里的"定时扫描重启后不再执行"是同一性质 —— 看起来在工作、其实有一环没跑。

改动：
- _create_notifications 返回 (条数, 失败原因)，失败原因非空即代表出了问题。
- scan() 在有失败时于返回体里带上
otification_failure，并把 message 改成
  "规则扫描完成，但高风险通知创建失败"，让上游与运维都能直接看到。
- **失败仍然不回滚预警**：预警已经生成、比通知重要，不该因为通知写失败就丢掉。

新增 tests/unit/service/test_risk_scan_notification.py（4 条），其中一条专门断言
"两种 0 必须可区分" —— 那是本次修复的全部意义。

ruff / mypy(136 文件) / 616 unit+contract 全绿。
 2026-09-11 13:33:41 +08:00
lzf_0626 e017bcc9bb fix(platform): 配置告警覆盖全部受 release 约束的表，并提供生效快照能力 
**问题**：上一轮加的"配置丢失告警"只比对 platform_config_item，而受 config_release
整版本替换影响的表有**三张**（按 information_schema 核对）：platform_config_item /
prompt_template_version / model_routing_rule。这个盲区造成过真实后果 —— 客服闲聊提示词
挂在 release 174，active 变成 181 后 load_active_prompt 读不到，而 Agent 侧有逐字段
兜底、回落到代码默认值，于是功能看着正常、没人发现、**一行告警都没有**。

**改动**（均在 app/service/config_release_service.py）：

1. 新增 RELEASE_SCOPED_TABLES：三张表 + 各自的**逻辑键**。逻辑键不含 release_id、
   不含自增 id、也**不含 version** —— 同名提示词在不同版本里可以用不同 version，
   那仍是同一份配置。清单是穷举的，并注明漏掉任何一张的后果都是静默失效。

2. 新增 effective_snapshot()：读当前生效版本在**全部三张表**里的内容，每行已剥掉
   id / 
elease_id（见 NOT_PORTABLE_COLUMNS），可直接作为新版本的写入载荷。
   发布脚本应先取它、再追加本次变更，这样"漏继承"就从"每次靠人记得"变成结构上不容易漏。

3. _warn_dropped_items 改为逐张表比对，告警里带上表名。

model_routing_rule 没有 ORM 映射，用原生 SQL 处理；它当前 0 行，但纳进来才不会将来
配了又漏。

测试：新增一条专门锁住"提示词被丢掉时也要点名"（那正是这次的盲区），并把 fake session
改成按表 + release 返回行 —— 第一版 fake 不分表，查提示词表时会拿到配置项的行、
报 KeyError，虽然真实代码是按表查的，但 fake 不真实就盖不住问题。

ruff / mypy(136 文件) / 612 unit+contract 全绿。
 2026-09-11 13:25:00 +08:00
Windows 281e76e4b1 feat: add advisor portfolio analysis 2026-09-11 13:20:09 +08:00
Windows 60c4a49b9b feat: migrate advisor investment goals 2026-09-11 13:11:58 +08:00