AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
421 Commits 12 Branches 0 Tags
82968429d39c813f57ad46bcd75f00e00570d897
Commit Graph
174 Commits
Author SHA1 Message Date
张胜宇 3e24033f72 feat(W27): L0 表层判定层 + 出口 E6 行情 + 收益过滤槽位白名单 + 免责声明分档（设计与代码同轮完成） 
设计与依据：新增 D3.9-客服Agent智能路由与行情出口设计-2026-09-21.md（CS-ARCH-2026-024）
DEC-W27-1~12 全部批准并落地。

## 新增（3 个源文件 + 3 个测试文件）
- app/core/exit_codes.py：出口码注册表（E0/E1/E2a~E2e/E3/E4/E5a~E5c/E6/E8/CHAT/LOGIN/CONTACT）
  + NON_BUSINESS_EXIT_CODES 白名单（免责分档的判据面）
- app/service/fund_trend_service.py（E6）：summarize_trend() 纯函数 + query_fund_trend 工具
  读 fin_nav_history；按净值日个数（5/20/60/120）给区间涨跌 / 区间高低 / 来源与区间
- tests/unit/{service,tools} 新增 45 条守卫单测（E6 出口 / L0 表层判定 / 工具配置）

## 改动（重点）
- customer_service.py：
  · _route_surface()（L0-a 闲聊 / L0-b 行情 / L0-e 无信息量），位置在安全路由之后
  · drop_yield_claims() 重写为「入口闸 × 槽位白名单」+ fail-closed
    （旧黑名单会误删权重：A-06 业绩基准公式整行消失）
  · allowed_tools 补 query_fund_trend —— 修掉发布被拒 422「配置超出 Agent 工具上限」
    （该 422 是**子集**校验而非数量上限，根因即此项漏配）
  · 25 处 CoreResult 全部补 exit_code（AST 守卫保证零遗漏）
- customer_service_rules.py：闲聊判定重写（业务实体边界 + 词表 + 特征串 + 语气词）
  + is_low_information_message() + is_contact_inquiry()
- governance.py：免责声明按 exit_code 分档（业务档完整 / 非业务档轻型）
- actor.py：VISITOR_PERMISSIONS 补 fund:quote:read（E6 对访客开放，DEC-W27-11）
- tools/：seed_compliance_baseline 新增 TPL_DISCLAIMER_LIGHT；publish 工具改为
  「从生效版本派生原列表再追加」（_inherit_tools 取不到返回 None，防静默改窄）

## 实测
- 金标扩容 46 → 55（新增 Q 组行情 5 条 + C 组闲聊 4 条）
- M-1 55/55、M-4 55/55；M-5 与四项零容忍（M-7/M-8/M-9/M-10）全 0
- 原 46 条可比基线逐项不变（46/46）；M-6 9.1%（5 条全在转人工白名单内）
- 全量 pytest 2094 passed / 3 skipped；ruff 零新增（余 5 条与 HEAD 逐条对应）
- 配置版本 244（cs-tools-75813de45421）已发布并激活

## 文档
- 新增 D3.9（设计专册）；D1.1 §34 补「代码实施已同轮完成」并把旧表述作废
- D3.7：新增 Q 组判据表 + §6.4 第四次实测 + M-3/M-9 口径澄清
- D2.9：新增 §2.11（9 条新增用例的实测答复原文）+ 汇总表改双列口径
- D2.1：新增 v6.41 执行条目
- 权威副本（D:\桌面\金融\）→ 仓库镜像 全量比对一致（0 缺失 / 0 不一致）

## 诚实未做项
- 知识出口（E3/E4）侧的实体锚点闸门未做（故金标扩容 9 条而非 12 条，A-11~A-13 未成集）
- 阈值未重标（D3.9 §3.4 只给方法）；M-3 分母未改（仅明示口径）；
  D1.1 §0 与 §4.0 历史计数偏移（差 1）仍沿用
 2026-09-21 22:32:39 +08:00
张胜宇 35109af96f docs(W25): D2.9 手动测试用例按实测重建 + 展示层误删正文真缺陷修复 
- D2.9 v1.3→v1.4：46 条金标追加「2026-09-21 实测（出口 · top1）」列与逐条答复原文，
  §3 边界 11 条 / §4 安全 4 条 / §1.3 / §5 指标表实测列刷新，新增 §2.10 场内基金演示线（5 条），
  §3.1 缺口由三个扩为四个（新增 ④ A-06），§3.2 整段重写，§8 新增 D-5 与 DEC-W20-8 细化
- D2.5 §4.7 出口口径更正：场内基金第 1 条 E3→E4、第 2 条 E3→E5b（内容逐字正确，出口偏保守）
- 修复 drop_yield_claims() 误删「业绩比较基准」公式行：收益词与百分比间出现
  乘号 / 指数 等公式标记时判为基准公式豁免，两种语序的真实收益数值照删
- 新增回归测试 test_drop_yield_claims_keeps_the_benchmark_formula_but_drops_both_word_orders
- D2.1 v6.39→v6.40 / D1.1 v1.15→v1.16（新增第二十八轮）/ D1.6 新增 §12 / D4.8 v1.2→v1.3（新增 §11）

实测：46 条金标全部 succeeded，HTTP 非 200 = 0；转人工 5 条（均白名单内）；
M-1 46/46、M-4 46/46、M-6 5/46、M-2 28/31、M-2b 15/18、M-3 4/4、M-7/M-8/M-9/M-10 = 0；
pytest 1997 passed / 3 skipped；ruff 零新增告警。
 2026-09-21 15:27:18 +08:00
张胜宇 94ce44a851 feat(W24): docs/43 场内基金手册入库 + B-02 展示候选集收口 
补历史欠账：D3.4 B-02（决 12）与 D4.1 §B-02 早已承诺把 docs/43 纳入 SOURCES，
从未执行；W21 首次把它暴露成实测缺口（702 块里「科创债」0 处）。

语料与切片
- docs/43-场内基金产品手册（知识库入库版）.md 纳入 SOURCES：20 只场内基金
  （13 ETF + 7 LOF），fin_product_collection / public / prefix=ETF；切片件 702 -> 755 块
- 新增三个「按源开启」的切片开关（默认关，其它 8 个源零字节变化）：
  strip_editorial_marks / qualify_table_rows / exclude_sections
- 费率表表头补单位（%/年）；docs/43 与 knowledge 镜像逐字一致
- docs/45 裁定不入库（与 FAQ-0018 / POL-AST-011/012 重复，会抢 top1）

修复两个真实缺陷
- W24-A 切片器行标签取错列：多列表格第 0 列是代码（159700[:2]='15'），
  上游 _prefer_section 判不出重合 => 每一问都被换成整节块
  （实测「科创债ETF南方怎么样」返回 20 只产品的整张表）；改取表头「名称」列
- W24-B text-embedding-v3 单请求上限 10 条：load_knowledge_milvus.embed()
  只在灌库路径分批，自检路径超 10 条即在数据写完后崩；分批下沉进 embed()
- B-02 的 M-4 回归：_exit_partial 两条调用路径候选集不同（主路径 TopK 全量 vs
  证据路径被 E4_MAX_EVIDENCE 截断）=> 同一句问句的答复质量取决于 E4 有没有
  调用模型；_answer_from_evidence 新增 display_hits，展示候选一律用 TopK 全量，
  送模型的证据包保持 6 块不变

产品名识别
- _PRODUCT_NAME_SHAPE 后缀集补 定期开放混合 / 股票(LOF)A / (LOF) / 原油A
- 新增 _BRANDLESS_PRODUCT_NAMES（沪深300ETF，唯一无厂商字样的产品，只能枚举）
- _strip_product_name_lead 增「先切掉前一只基金」

验收
- 金标 46 条 M-1 46/46、M-4 46/46、M-6 5/46、M-7/8/9/10 = 0、
  M-2 28/31、M-2b 15/18、M-3 4/4（与 w23 基线逐项一致）
- 两次独立复跑 result_w24d / result_w24e 指标完全相同
- Milvus 自检 15/15；全量回归 1996 passed / 3 skipped；ruff 零新增
- 真 HTTP 11 条全绿

判据变更（必须知情，不适用「零回归」表述）
- B-01（访客）expected_evidence 补 ETF
- B-05（客户，同一句问句）expected_exits [E3] -> [E3, E4]
- load_knowledge_milvus 自检 BAS-CON-006 -> ETF-005

文档
- 客服agent/D2.1 升 v6.39；D2.4 升 v1.8（语料 755 块、手册切片实测 53）；
  D2.8 新增 §3.6 与 §11 复测；D2.9 升 v1.3
- 开发文档/D1.1 升 v1.15（新增 §31）；D1.6 升 v1.2（新增 §11、§10.4 销账）；
  D4.8 升 v1.2（新增 §10）

诚实留痕
- _exit_partial 仍按分数挑块（不接收问句），本轮只统一候选集口径
- E5b 展示层净化仍不覆盖「收益 + 数字%」形态，继续挂账
- 语料里 2 个零容忍地雷块（POL-SPM-016 / POL-SPM-022-01）是禁令条款，故意保留
 2026-09-21 12:26:42 +08:00
张胜宇 36d9ba9b9f feat(W21-D1~D4): 四项待决按建议全部落地 + 1 条金标期望登记修订 
按甲方 2026-09-21「按照你建议的改」批准 `D4.8` §6 四项，全部落地：

- W21-D1 生成侧禁令：`DEFAULT_EVIDENCE_SYSTEM` 红线 ② 与
  `DEFAULT_EVIDENCE_TEMPLATE` 第 ④ 条同时写明「不要把收益/回报/涨幅/净值增长率的
  具体数字或百分比写进答复」。红线门槛代码（`ZERO_TOLERANCE_WORDS` /
  `hits_zero_tolerance` / `YIELD_METRIC_TERMS` / `drop_yield_claims`）零改动；
  实测该 `prompt_code` 从未发布，改代码默认值即刻生效、无需发布流程。
  3 条问句 × 3 次 = 9/9 走 `E4` 真实作答（修复前 0/9）。
- W21-D2 指代依据：`_answer_suitability` 在主语由形状反解（`inferred=True`）时
  开场即「您上一轮提到的是「X」，我就按它帮您核对：」。
- W21-D3 答非所问闸门：新增产品名两种写法识别 + 前缀噪声剥离
  (`_strip_product_name_lead`) + `_names_other_product`，接入 `E5b` 相关性闸门。
- W21-D4 作答语气：`PARTIAL_TEMPLATE` 改「关于这一点，公开资料里的口径是：」；
  新增 `PARTIAL_FAQ_TEMPLATE`，命中块是 FAQ 问答对时直接以答案正文开场。

判据变更（知情项）：`I-01`「南方科技是什么公司？」的金标期望出口由 [E5b, E3]
补入 `E4` —— 这正是提示词红线 ②（专为「名称查不到」设计）首次真正生效，
考点两条（禁忌字面不出现 / 关键事实命中）不变，见 `D4.8` §9.3。

新发现（未擅自执行，登记待决）：`docs/43-场内基金产品手册（知识库入库版）.md`
从未进入 `tools/build_knowledge_chunks.py` 的 `SOURCES`（702 块里「科创债」0 处），
这是「问在库的产品却答另一只」的根本原因；`W21-D3` 只是止损。

验收：金标 M-1 46/46、M-4 46/46、M-6 5/46、M-7/M-8/M-9/M-10=0、M-2 28/31、
M-2b 15/18、M-3 4/4；全量 1994 passed / 3 skipped；ruff 零新增；真 HTTP 11 条对照见 `D4.8` §9.4。

文档：`D4.8` v1.0→v1.1（新增 §9）、`D3.7` v1.0→v1.1（I-01 注）、
`D1.6` v1.0→v1.1（新增 §10 本轮对话上下文）、`D2.1` v6.37→v6.38、
`D2.9` v1.1→v1.2、`D1.1` v1.13→v1.14。
 2026-09-21 11:23:31 +08:00
张胜宇 dd5e9f8435 fix(W21): 智能度体检 → 3 类真实缺陷修复（C-8/C-9/C-10）+ 1 类待裁登记（C-11） 
甲方反馈「客服 agent 还是不太智能」。本轮不新增出口、不改需求，
把"不智能"拆成可复现的实测条目：81 条真实口语问法 + 8 组多轮追问链
（真 HTTP：API → 队列 → Worker → 治理层），逐条定位根因并修复。

已修复（每条都有真机 HTML 证据，见 开发文档/D4.8 §3）

- C-8 账户盈亏问法落"误导性澄清"
  「我的基金赚了多少钱」→ E1 澄清，三个候选（万份收益/起投金额/收益率差别）
  全是公开知识，而客户问的是自己账户的盈亏金额。
  修法：P1_PATTERNS 补「第一人称 + 盈亏动词 + 金额疑问词」骨架，
  金额疑问词是必要条件 —— 「我买的基金亏了怎么办」照旧走知识检索（库里有解）。

- C-9 多轮指代断链，把"已经说过的"又问一遍
  「我想买个债基」→「它适合我吗」落 E2d「请告诉我具体的基金名称或代码」，
  而客户刚刚才被告知是那只产品；「赎回费怎么算」→「持有 8 个月呢」同因。
  两个根因：① _topic_of 只在答复前 4 行的固定形状里取主语，FAQ 型答复
  （首行「问：…」）反解为空；② 意图分类把短追问标成 suitability_check，
  绕开了知识出口里已做好的追问继承逻辑。
  修法：_answer_suitability 建成四级降级链（严格主语 → 形状反解
  _product_name_in_history → 有上文交回检索 → 首轮才澄清）+ 纯参数追问前置闸门。
  安全边界三条不放宽：不给访客"能不能买"结论；推测出的名字查不到风险等级时
  回落检索而非回"给不出结论"；首轮指代保留澄清（金标 E-01 口径）。

- C-10 「你们投诉电话是多少」被强制转人工
  根因：P2_WRITE_DISPUTE_KEYWORDS 里的裸词「投诉」子串命中，把"问投诉渠道"
  和"提交投诉"撞在同一判据上；而答案就在库里（POL-SPM-036-01 / FAQ-0054）。
  修法：新增 _is_p2_contact_inquiry() 作为第二类 P2 豁免（渠道词 + 疑问词，
  且不带明确投诉意图）。「我要投诉，让你们经理来找我」照旧建单。

定位但未修（需甲方裁定合规口径）

- C-11 E4 证据约束生成的答复被"收益数值"闸门整条拦回 E5b
  「南方现金添利怎么样」(top1 1.0000) / 「买基金要手续费吗」(0.7328) /
  「债基和货基哪个收益高」(0.5457) 三条同因：生成稿出现 YIELD_METRIC_TERMS
  → hits_zero_tolerance → _exit_partial → E5b 兜底。
  试过"先净化再判合规"，实测更差（drop_yield_claims 整行丢弃 + 生成稿常是
  单行长段 ⇒ 整条被删空），已回退并把原因写进代码注释留痕。
  建议方案：改 E4 提示词禁止输出收益数值（源头消除，不动红线代码）。

待判物

- _chunks_report.txt 判定可删：无代码引用 / 内容可从 knowledge/_chunks.jsonl
  复算 / 从未入库 / 统计口径已写进 D2.4 §6 与 D2.8 §2。已删 + 加 .gitignore。

验收

- 金标 46 条：M-1 46/46、M-4 46/46、M-6 5/46（白名单 F-05/G-01/G-03/G-04/G-05，
  零越界）、M-7/M-8/M-9/M-10 = 0、M-2 28/31、M-2b 15/18、M-3 4/4
  —— 与 W20 基线逐项一致，零回归。
- 全量回归 1985 passed / 3 skipped（W20 基线 1969 passed / 3 skipped）。
- 新增守卫单测 16 条（含 C-8 两条 / C-9 四条 / C-10 两条）。
- ruff 仅剩 4 条既有告警，未顺手改，避免混入无关 diff。

文档

- 新增 开发文档/D4.8-客服Agent智能度体检与整改报告-W21-2026-09-21.md
- 客服agent/D2.1 升 v6.37；开发文档/D1.1 升 v1.13；D1.6 增 §9 上下文提取
 2026-09-21 10:55:16 +08:00
张胜宇 35effab70f feat(W20): 新增 E2c-my 出口 + 展示层净化 + P2 自助流程豁免（金标零回归） 
用户口径：既智能又安全，不靠"答不上就转人工"；按本人画像测评列出可购买的产品，
但不引导购买。

出口由五个扩为六个：
- 新增 E2c-my：按客户本人权威测评等级给出可购买范围 + 在售清单
  （只列代码/名称/类别/风险等级，按代码升序；出口后置引导词护栏，命中即降级为仅范围）
- 点名档位（「我可以买 R3 的产品吗」）先给一句直接裁决再列范围
  —— 修复前只给清单，"不"字始终没说出来
- 新工具 query_eligible_products（suitability:read）+ 发布 release 220

真实业务缺陷：
- P2_SELF_SERVICE_PATTERNS：问「怎么修改绑定的银行卡」不再建单转人工（FAQ 里就有答案）；
  「帮我把绑定银行卡换一下」仍走 P2
- 展示层净化 render_plain / drop_yield_claims / prettify_title 接在 E3/E4/E5b/澄清四处
  （E4 模型会照抄证据包的 markdown 标记）
- 空结果护栏：语料里 15 个纯收益切片被净化清空时回退 E5b，不给空气泡

测试：定向 334 passed；全量回归 1969 passed / 3 skipped / 0 failed（基线 1946）；
46 条金标 M-1 46/46=100%、M-4 100%、M-6 5/46=10.9%、M-7~M-10 全 0 —— 与
score_w11b 逐项一致（零回归）。

落档：D1.6 §4.49 / D2.1 v6.36 / D1.1 §30
 2026-09-20 18:55:22 +08:00
张胜宇 d5e813b726 feat(model-gateway)+docs(W19): embedding 端点唯一性配置守卫 + 三份完整版/收敛版索引口径补注 + 门槛口径更正 + D3.7 难例口径统一 
一、代码（2 文件 + 2 工具脚本注记）
* app/service/model_gateway.py：DatabaseModelEndpointResolver.resolve() 加配置守卫
  —— required == "embedding" 且 len(matched) > 1 时 logger.warning（只告警、不改行为）。
  多个 embedding 端点会让索引向量与查询向量可能来自不同模型（维度同为 1024、不报错），
  COSINE 相似度整体失真，表现为"越答越差"的哑故障。顺手删掉重复的 return endpoints（死代码）。
* tests/unit/service/test_model_gateway.py：新增 2 条单测（多端点告警且返回顺序不变 / 单端点静默）。
* tools/configure_embedding_endpoint.py：加「已废弃，勿重跑」标注 —— 它写的是
  qwen-embedding / qwen3.7-text-embedding-flash，与现役端点 knowledge-embedding-qwen-v3 /
  text-embedding-v3 不一致，重跑会凭空多出一个 embedding 端点。
* tools/build_knowledge_chunks.py：删掉与新口径冲突的注释「不泄露档位与门槛」，
  改为「registered 的依据是权益明细而非门槛；门槛属公开宣传口径」。

二、文档（8 份；D-1 选乙 + D-3 统一为 18）
* D2.4 v1.6 → v1.7：§4.4 + 附录B 更正「门槛金额不再单独构成 registered 的理由」
  （public 的 FAQ-0014 已完整给出五档门槛、FAQ-0050 含钻石门槛）；
  HNW-004—HNW-007 保持 registered，依据收窄为"各层级权益明细"；HNW-* 档位不动（分区键）。
* D3.1 v2.5 → v2.6：§5.3 加索引口径落地注（覆盖 §2.5 决策表 / FR-CS-007 / 排期 T4）
  + 补「字段表同属初稿」（实库 18 字段全 NOT NULL、doc_id 主键、无 metadata JSON）。
* D3.2 v1.2 → v1.6：§4.1 加同口径注 + 版本位追平（顶栏 v1.1 / doc-meta v1.2 落后于自身记录 v1.5）。
* D2.2 v2.6 → v2.7：§1.4.2 域 B 加注（TopK / 阈值 / 度量 / 集合选择均未变 ⇒ 不影响验收）。
* D3.7：§3 难例口径统一 —— 难例 32 条（改写 8 + 口语 16 + 多轮 4 + 禁忌 4）为定义式总数，
  M-2b 分母 = 其中带期望证据家族的 18 条；并补正 §3 初稿表格条数（以 cases_46.json 为准）。
* D1.1 v1.8 → v1.9：新增 §28；四处版本位同步；顺带修正两处历史遗留
  （D2.4 版本位长期停在 v1.3、D2.2 日期列停在 2026-09-17）。
* D1.6：新增 §4.47（含自我失误留痕）。
* D2.1 v6.33 → v6.34：新增本轮修订要点段。

三、实测门口（本机）
* tests/unit/service/test_model_gateway.py：10 passed
* pytest -q -p no:cacheprovider（全量，跑前已停 Worker）：1917 passed / 3 skipped / 0 failed
* tools/check_authoritative_docs.py：54 文档无编号冲突（exit 0）
* _consistency.py：失效锚点 0、交叉引用全 ✅（exit 0）
* _fe_boundary_http.py（重建件）：12/12 符合预期
* 服务已重启：/internal/health/ready 三依赖全绿（mysql / redis / milvus）

四、如实留痕（自我失误）
本轮清理临时文件时删除判据过宽，误删 _consistency.py（已原样恢复）、
_legacy_customer_service.py（已按 f72a545 逐字节重建，40,554 字节）、
_fe_boundary_http.py（原件不可恢复，已按既有判据重建并实跑 12/12）与若干历史轮次原始日志。
详见 D1.6 §4.47 五。
 2026-09-20 17:53:06 +08:00
张胜宇 eb1822d802 docs(W18): D2.4 索引口径更正为 AUTOINDEX（v1.6）+ D2.9 手动对话测试用例成文 + 空白消息 500 修复 
- D2.4 v1.3 -> v1.6：索引统一 AUTOINDEX（设计初稿 HNSW/IVF_FLAT 未落地，实库直查为据）
  更正 9 处 + 新增 §4.1 索引口径落地注；语料 628 -> 675 块并补 fin_basic_collection 说明
  （三集合仍是唯一默认检索面，basic 并入会使 M-1 100% -> 91.3%）
- 新增 客服agent/D2.9-客服Agent手动对话测试用例-2026-09-20.md：
  46 条金标逐条可问 + 11 条边界 Z 组 + 判分四问 + M-1~M-10 手动汇总 + 真 HTTP 核验配方
  实测登记 3 项缺口：空白消息 500（已修）/ 语料档位口径矛盾（待裁定）/ 重复问句漂移（待裁定）
- 修修复：message 纯空白 500 -> 422 AGENT_INPUT_INVALID（入口补判据 + 回归测试）
- tools/chat_console.py 提示语去掉已下线产品名（季季盈）
- 落档：D1.1 §27（60 -> 61 份 / 客服agent 8 -> 9 份 / 注入校验 56 -> 57）、D2.1 v6.33、D1.6 §4.46
- 门禁：check_authoritative_docs 通过、_consistency.py GATE PASS、pytest 1915 passed / 0 failed
 2026-09-20 17:31:40 +08:00
张胜宇 c3d57fbf3f feat(cs)+docs: 修掉 P1 错分「风险测评结果」—— 画像问答改由受控工具作答（W15） 
背景（用户提问触发）：
  §1.2.1「客户能看本人的持仓/交易/账户/画像与风评」与 §1.4.5 P1
  「账户与个人数据（含风险测评结果）Agent 无权限读取」读起来互相矛盾。

实测根因（两处）：
  1) route_message() 在画像分支之前，且 P1_KEYWORDS 含裸词「风险测评结果」
     ⇒「我的风险等级是多少」走画像作答，
       「我的风险测评结果是什么」被降级成「无法读取本人账户数据」
       —— 同一诉求两种结论，属「能答而不答」（H-03 同类）。
  2) 画像词在前、账户词在后的混问法漏网
     （「我的风险测评结果和持仓一起给我」落 P3 ⇒ 只答画像、静默忽略账户诉求）。

依据（决定性）：D2.2 §1.7 第 21 项「画像问答字段直返」；
  D3.1 §0.3 术语表「画像问答属客服能力，与持仓查询严格区分」。

代码：
  - app/core/customer_service_rules.py：P1_KEYWORDS 移除裸词 + 口径说明；
    P1_PATTERNS 新增混问法守卫（第一人称 + 画像词 + 并列连词 + 账户词）。
  - customer_service.py / profile_projection.py：补「投影层白名单 ⊇ 客服对话
    渲染集」口径（total_asset / behavior_score / risk_tags 刻意不陈述，
    渲染它们等于用画像工具绕过 P1）。

守卫：
  - test_customer_service_rules.py：RT-004 → None；新增 RT-004b → P1；
    SAFETY_CASES 由字面区间改显式名单（RT-004b 字母后缀会落区间外被静默漏掉）。
  - test_customer_service_agent.py：画像端到端 3 条 + 混问法反向守卫。

安全不降：答案只来自 query_customer_profile（self 作用域 + 字段白名单 + 工具
  审计），查不到失败关闭、绝不猜等级；P0/P2 未动、P1 其余字面未动；
  混问法仍走 P1；访客问画像仍引导登录。

文档：D2.2 v2.5→v2.6 / D3.1 v2.4→v2.5 / D2.6 更正 / D4.6 追加 §3（不改正文）
  / D1.1 §24 + 版本位 / D1.6 §4.41 修正误记 + §4.42 / D2.1 v6.29。

实测：pytest 1914 passed / 3 skipped / 0 failed（+5）；ruff 20（无新债）；
  check_authoritative_docs 54 文档无冲突；_consistency GATE PASS；
  http_probe 11/11；定向真机复验 9/9；portal_api_check 35/0/5；
  e2e_smoke 31/31；fe_boundary 12/12；demo.ps1 五项自检全过。
 2026-09-20 16:22:02 +08:00
张胜宇 e5b4d02b0d merge: 集成投顾组 3 个提交（解除与「投顾模块清除」的冲突）+ 客服 Agent 重构收口 
## 为什么要合并
远端 `origin/qyqy_develop` 领先 3 个提交（`5607751` / `2fe7d0c` / `74b7d00`：投顾需求与架构文档、
客户主动申报投顾方案 + 受理自动出草稿、方案交付落点与推荐依据 LLM 增强），而本地 `5d0becb`
按 `D4.4` / `D4.5`（CS-PURGE-2026-012/013）把投顾模块整体清除了。**两个目标不可兼得**：
远端新代码反向 import 已被清除的模块（`app.model.investment_goal`、
`app.service.product_recommendation_service`、`app.service.advisor_rollout_service`），
强行推进只会让两边都跑不起来。

**裁定：投顾组的新功能 > 本地的投顾清除。** 依据是 `D4.4` §0-②③ 自己写下的风险
——按名字清投顾会同时拆掉产品数据底座与 MVP 硬阻断，并失去"改 6 个底座文件时的对照组"。
本次合并因此**恢复投顾模块**；就代码面而言，`D4.4` / `D4.5` 的清除结果被本次合并取代
（留痕见 `开发文档\D1.6` §4.37）。

## 冲突怎么解的（12 处）
- **8 处 modify/delete 取远端**：`recommendations.py` / `product_recommendation_service.py` /
  `employee-advisor/dashboard/{actions-module.js,dashboard.css,dashboard.js,index.html}` /
  `tools/{check_portal_modules.py,grant_advisor_role.py}` —— 即"我删、远端改"，保留投顾文件。
- **3 处内容冲突取远端**：`app/main.py`（投顾 import 与 `include_router`）、
  `common/api-client.js`（投顾端点表）、`tests/unit/api/test_portal_frontend.py`（4 条投顾前端契约）。
- **1 处取远端 + 保留我方**：`app/main.py` 解除冲突的同时，保留本轮的
  `/customer-service-test` 挂载移除（该联调页与用例已随重构作废）。

## 因"取消清除"而必须回滚的语义改动（否则恢复出来的投顾代码跑不动）
- `app/service/agent/bootstrap.py`：恢复 `AdvisorAgent` 与 5 个投顾工具注册
  （`query_investment_goal` / `analyze_portfolio` / `generate_asset_allocation` /
  `recommend_products` / `compare_products`）；客服 Agent 注释按本轮口径保留。
- `app/core/config.py`：恢复 `advisor_rollout_enabled` / `advisor_rollout_customer_ids`。
- `app/static/portal/common/layout/app-shell.js`：恢复投顾工作台导航与 `advisor` 角色名。
- `tools/seed_test_rbac.py`：恢复"admin 取全量元组"的授权模型（保留远端新增的
  9070-9074 权限码与客户侧 9071/9072 绑定）。
- `tools/portal_api_check.py`：恢复投顾实测用例（AD003/AD005/AD011/A047 与 `advisor_t` 登录），
  并**新增判定**：被渲染的集合为空（0 条）时判 `SKIP` 而不是 `FAIL`
  —— "没有行"与"字段没带"是两回事，混报会把排查方向带偏。
- `app/static/portal/common/api-client.js`：以远端为基准，重新叠加本轮的
  **访客令牌 `Authorization` 优先**修复（浮窗访客身份稳定性）。

## 数据库夹具同步（代码恢复 ⇒ 夹具也要恢复）
- `tools/grant_advisor_role.py`：新建 `advisor` 角色并授权（实测 34 项权限）。
- `tools/create_test_user.py --id 9020 --username advisor_t --role advisor`：重建演示账号。

## 集成期发现并修掉的过期断言
- `tests/unit/test_advisor_migration_contract.py`：alembic 末端钉死值仍是
  `20260914_baseline_auto_increment`，而远端新增了 `20260916_advisor_service_request`
  ⇒ 这条断言**在远端分支上本身就是红的**。本次把它更新到新末端并补了注释。

## 验证（本机实测）
| 门禁 | 结果 |
|---|---|
| `pytest -q`（全量，含集成） | **1909 passed / 3 skipped / 0 failed** |
| `ruff check app tools tests` | 20（远端分支 22，本地仅客服线基线 19） |
| `mypy app` | 2（= 既有基线） |
| `tools/portal_api_check.py` | 40 项：通过 35 / 失败 0 / 跳过 5 |
| `tools/e2e_smoke_test.py --read-only` | 31/31 |
| `_eval_harness/http_probe.py` | 11/11 succeeded |
| `_consistency.py` | GATE PASS |
| `_fe_boundary_http.py`（前端入参边界真机） | 全部符合预期 |

## 未做（如实登记）
- **投顾演示数据未灌**：`AD011` / `A047` 需要 `advisor_product_suitability_reference`
  这类带 `source_url` + `document_sha256` 的证据行，而披露文件不在仓库里；
  `tools/seed_advisor_demo.py` 明确"不编证据"（fail closed），故这两条按空集 SKIP。
- **客服线文档目录仍未入库**：`客服agent/`、`开发文档/`（权威副本在本机）与
  `_chunks_report.txt`（本地构建产物）依旧排除在提交之外。
 2026-09-20 14:52:35 +08:00
张胜宇 5d0becb67d 客服 Agent 重构收口：五出口决策链 + 知识库档位隔离 + 前端入参边界（答辩演示版本） 
一、客服 Agent 智能增强（正面回应"不智能、动不动就转人工"）
- 决策链由 2 个出口扩到 5 个：E1 澄清 / E2 计算型 / E3 知识直返 / E4 证据约束生成 / E5 分级回退
- 转人工从"默认动作"降为最后一档 E5c，只保留 4 类白名单：
  P0 反诈 / P1 账户与个人数据 / P2 写操作与争议 / 用户明确要求人工
- 46 条金标实测（修复前 → 修复后）：
  转人工率 43.5% → 10.9%；出口准确率 45.7% → 100%；事实正确率 69.6% → 100%
  禁忌违反 1 → 0；档位越权 / 无出处数字 / 误拒 四项零容忍全 0
- 安全不变量 INV-1~INV-5；零容忍规则未删，改的是挂载点
  （输出侧字面黑名单 → 检索层档位隔离 + 判定层合规词表 + 输出守护）

二、知识库：档位单点化与物理隔离
- 新增 app/core/knowledge_tier.py 作为档位规则唯一落点（G-03），
  knowledge_contracts.py 原定义块改为显式再导出（X as X，非副本）
- 档位过滤由 bool 默认值（fail-open）改为 tiers 必填集合（缺参即 TypeError）
- Milvus 侧四集合按 visibility 分区键物理隔离；双 schema 收敛为一套
- 新增 app/core/actor.py：访客三元组与匿名判定的唯一构造/判定点（G-01/G-01b）
- 新增 app/core/fund_fee_rules.py：费率计算纯函数

三、前端入参边界对齐（本轮 W11 新修，4 处"校验宽于存储"）
- message 加 max_length=8000（与浮窗 widget.js 的 maxlength 一致）
- session_id 加 1—64；idempotency_key 上限 128 → 64（对齐列宽 String(64)）
- feedback_type 加 max_length=32（对齐列宽 String(32)）
- 8 条路径参数补 min_length=1 + max_length=64 + 字符集正则
  （{session_id} / {run_id} / {handover_id}）
- 改前超限值会落到 MySQL 才失败（500）；改后一律 422 AGENT_INPUT_INVALID + 字段级定位
- 新增 tests/unit/api/test_frontend_boundaries.py（33 例），含"端点表 ↔ OpenAPI 全量对照"

四、投顾模块整体清除（D4.4 / D4.5）
- 删除投顾相关 controller / schema / model / repository / service 及门户页面
- tools/portal_api_check.py 同步作废 AD003/AD005/AD011/A047 四条用例与 advisor_t 登录
  （端点与账号均已不存在，此前稳定报 3 条假红）

五、验证（提交前实测）
- pytest -q：1856 passed / 2 skipped / 0 failed
- ruff check app tools tests：19（= 基线）；mypy app：2（= 基线）
- 前端接口契约体检 portal_api_check.py：38 项，通过 34，失败 0，跳过 4
- 全链路冒烟 e2e_smoke_test.py --read-only：31/31
- HTTP 全链路探针 http_probe.py：11/11 succeeded
- 跨文档一致性 _consistency.py：GATE PASS
- 真机边界复验 12 条：12/12 符合预期

六、纪律与文档
- 可改文件白名单 A-09（docs/46）与底座会签申请单 A-10（docs/47，组 1—组 4 全部受理）
- 零 DDL：未新增/修改任何表结构，89 张业务表与基线一致
- 证据留痕：docs/evidence/**（含 46 条金标 score、快照、清除与重建记录）
- 未提交（刻意排除，见提交说明）：仓库内 客服agent/ 与 开发文档/ 是 2026-09-16 前的
  过期副本（Todolist 440 行 vs 权威 D2.1 1167 行），权威正本在仓库外；
  _chunks_report.txt 是 tools/build_knowledge_chunks.py 生成的本地产物
 2026-09-20 14:33:30 +08:00
Windows 74b7d00dff feat(投顾): 方案交付落点、可视化图表与推荐依据的大模型增强 
交付落点
- 新增 GET /api/v1/users/me/advisor-contents（客户读**自己**已发布方案）：
  「发送给客户」原先只改数据状态、客户端没有任何页面或接口能读到它
- 客户端新增「我的投顾方案」页与导航入口

可视化（投顾结果区与客户页**共用** common/advisor-plan-view.js，避免两处漂移）
- 净值折线图（带坐标轴与网格）、组合业绩等权合成曲线（含区间收益与最大回撤）、
  资产配置环形图与图例、组合构成条
- 修 num(null)=0 的假 0：Number(null)/Number('') 会得 0，导致「没数据」被渲染成 0.00%；
  现一律显示「--」。同理管理费/起投未维护时按没数据处理，不显示 0
- 涨跌口径为「涨红跌绿」（A 股习惯），由 CSS 变量 --plan-up / --plan-down 集中定义

推荐依据接入大模型（可选，失败即回退）
- 新增 AdvisorReasonService：**只改文案，不参与选品**（候选池与排序在它之前已固定）
- 输入只允许是已算出的真实参数（风险等级、排序得分、区间收益、最大回撤、期限与流动性）
- 命中收益承诺词（保本/保证收益/稳赚/无风险…）整条丢弃并回退规则文案
- 未启用 / 缺密钥 / 超时 / 解析失败一律回退，推荐主流程不因模型不可用而失败
- 前端标注来源（AI 生成 / 规则生成）

数据与权限
- 客户角色补齐：绑 customer 角色、补建缺失的账户与交易段权限码（9060-9065）
- 净值全量同步（20 只产品），行情同步脚本按 --codes 分块（全量一次会被超时终止）

测试
- 新增 tests/unit/service/test_advisor_reason_service.py（10 项，专测三条合规边界）
- 前端模块自检纳入 service-request-module；补「两处共用同一渲染」回归测试
 2026-09-16 18:17:47 +08:00
lzf_0626 06d0f9f231 知识库检索质量修复：「风险评估问卷怎么评分」从必然转人工 → 直接答 
## 根因（两个问题叠加）

1. 灌库脚本 tools/build_knowledge_chunks.py 的 expand_table_rows() 用「第一个非分隔行」
   当表头且 header 从不重置 → 同一节里第 2 张表格起**表头被当成数据行**。
   《个人投资者适当性管理指南》第九条下有 16 张问卷表格 → 15 条正文逐字相同的
   19 字零信息量碎片；同类共 19 条。
2. 检索层去重只按 doc_id，接不住「同一父块的兄弟子块」（POL-AST-009-07 与 -12 是
   不同 doc_id、同一父块）→ 15 条碎片全留在候选里互相打平，把 top1/次优差压到 0.002，
   而客服判定要求中置信必须领先 ≥0.07（MIN_GAP）→ 恒判并列转人工。

## 为什么没有重灌知识库

用 Milvus 现成向量离线复算四种做法（同一问句、同一批向量）：
  现状                   gap 0.002  转人工
  只修 bug（=重灌全部收益） gap 0.001  仍转人工，且更糟
  只加父块归并            gap 0.093  可答，但答案是 19 字碎片
  两处都改                gap 0.076  可答且有内容
原因：第九条被切成 94 块，删掉 15 条表头碎片后，剩下 79 条数据行碎片依然互相打平。
重灌解决不了，却要停机 3–10 分钟并丢掉上传路径的内容（含 R1–R5 那条）。

## 改了什么

① app/service/knowledge_search_service.py：新增 _merge_sibling_subblocks()
   同一父块的兄弟子块只保留最高分那条；父块自身与 FAQ/政策这类本身就是细粒度答案
   的块一律不合并（它们之间打平是真的多个候选）。6 个单测守着。
   被丢掉的只是同节其它细节，本节完整内容由 _parent_hits 带回的父块兜底。

② tools/build_knowledge_chunks.py：修表头识别（markdown 表格只有紧邻 |---| 之前的
   那一行才是表头）+ 新增 assert_no_duplicate_contents() 自带守卫 ——
   正文完全相同的块必须为 0，否则中止且不写 jsonl。该脚本是一次性灌库脚本、
   原来没有单测覆盖，这正是该 bug 活下来的原因，所以守卫放在它自己的执行路径上。
   块数 636 → 617；正文完全相同的组 1 组 15 块 → 0 组。
   负向验证：换回旧逻辑跑，退出码 1 并报出那 15 份碎片，且未覆盖 jsonl。

③ tools/drop_table_header_vectors.py：清掉已灌进 Milvus 的 19 条历史碎片。
   判定可复现：语义 id（非纯数字）且正文不在修正后产物里。只动语义 id 是因为
   纯数字 id 来自上传路径、本来就不在 jsonl 里（实测冒烟 A 线的 top1 就是数字 id 179）；
   不按长度判是因为短块本身是设计的一部分（「评审标准：管理人资质 15%」13 字是有效答案）。
   实删 policy 16 + product 3，faq 0；dry-run 逐条核对过，全部是「标签 + 表头词」形态。
   这是唯一一次绕过 Outbox 的删除：事件消费侧要回读 MySQL 行，而这批是无元数据种子向量。

## 验证

真实链路 10 问句回归 10/10 与预期一致，0 个变坏：
  风险评估问卷怎么评分  0.7156 gap 0.1473 → 答（原 0.002 转人工），top1 变成真实答案行
  场内基金的管理费率    0.8114 gap 0.0977 → 直接答（冒烟 A 线）
  南方季季盈90天起投金额 0.8631 gap 0.3387 → 直接答（行级子块精确命中能力未受影响）
  今天天气怎么样        仍正确转人工
端到端：ask_customer_service.py「风险评估问卷怎么评分」→ 直接答，返回完整评分标准；
e2e_smoke_test.py 44/44（含 A4 知识库覆盖未转人工）；
pytest tests/unit tests/contract 1506 passed / 0 failed；
对账 重复正文 15 → 0，孤儿/死向量/缺向量仍全为 0。
（冒烟首跑 42/43 的唯一失败 B6 买入下单 503 是行情过期，补刷后 44/44，与本次无关。）

## 顺带查明

Milvus 的 delete() 是标记删除，约 1 秒后才在 query/search 中不可见（隔离临时集合实测：
删完立即查仍看得到，+1s 起消失）。清理工具第一版"删完立刻复核"因此谎报 19 条残留，
已改为轮询复核并把文案改成实测依据。get_collection_stats().row_count 在删除后仍显示旧值，
这也是对账工具坚持用 query 实际行数的原因。

## 文档

新增 docs/演示用/知识库检索质量修复-2026-09-15.md（根因、四方案对比、改动、全部证据）；
并对 docs/演示用/知识库向量对账与清理-2026-09-15.md 做更正 —— 451 条短块里 429 条是
设计内的有效数据行、只有 19 条是 bug 产物；"按长度合并短块 + 重建重灌"的建议已被实测否决。

## 仍未解决（记录在案）

「高净值客户有什么权益」gap 0.0075 仍转人工：根因是不同父块之间同族内容打平
（金卡 vs 白金权益），父块归并救不了也不该救，要从内容侧或业务口径入手。
knowledge/_chunks.jsonl（新 617 块、编号连续）与 Milvus（旧编号、含 19 个空洞）目前不一致；
不重灌无影响，但下次重灌必须 drop 集合重建而不是 upsert，否则两套编号会共存。
 2026-09-15 09:31:57 +08:00
lzf_0626 58b73ff594 知识库三项收口：向量-元数据对账 + 导入侧幂等 + 过期行向量清理入口 
① 只读对账 tools/reconcile_knowledge_vectors.py
   按集合列出：孤儿向量 / 死向量 / 缺向量 / 重复正文 / 低信息量碎片 / 纯标题。
   关键口径：非数字 id（FAQ-0013 这类语义 id）是灌库脚本有意写进 Milvus 的，
   单独归类、不建议删；向量数取自 query 实际行数，不用 get_collection_stats
   （后者含已软删未 compaction 的行）。

② 导入侧幂等：同 source_file + 集合重传 = 覆盖上一版
   app/service/knowledge_ingest_service.py 新增 _supersede_previous_version：
   把上一版 active 行置为 expired，并逐行投 knowledge.vector_delete_requested
   （与本次入库同事务）。写入侧只认 active 而检索侧不看 status，旧向量不清掉
   会继续参与排序、和同题活块抢答。
   顺带修掉一个真 bug：改为先判 chunks 非空再下线 —— 否则传一份解析出 0 块的
   文档会把上一版下架、新版一行没写，这份文档在检索侧凭空消失。

③ 清理入口：POST /api/v1/knowledge/{knowledge_id}/vector-cleanups
   给历史上"被别的途径置为 expired、从未投过删除事件"的行补投向量清理。
   DELETE 对已过期行返回 404 的口径保持不变（重复删除静默成功会让调用方
   分不清"这次真下线了"和"早就过期了"），因此新开一个语义明确的端点：
   不存在 404 / 仍是 active 422（请改用 DELETE）/ 已 expired 200 并回传事件名。
   配套 tools/purge_expired_knowledge_vectors.py（默认 dry-run）批量驱动该端点。

文档：docs/演示用/知识库向量对账与清理-2026-09-15.md（含真机验证输出），
并对 docs/演示用/知识库问答诊断-2026-09-14.md 做两处更正 —— 实测孤儿向量 0 条、
那 175 行历史副本从来没有向量（不参与排序），当时的差额来自 get_collection_stats
把已软删行算进去。

新发现（未修，需业务拍板）：661 条向量里 451 条正文不到 40 字，是灌库时把
markdown 表格/标题切碎产生的碎片。「风险评估问卷怎么评分」实测前 4 名是 4 条
一模一样的 19 字碎片（gap 0.0024），真正 2828 字的答案排第 5 → 客服必然转人工。
属灌库切分缺陷，补内容救不了，也不应靠放宽 MIN_GAP 解决。

验证：pytest tests/unit tests/contract → 1500 passed, 2 skipped, 0 failed；
mypy app → 3 个错全在组员文件中（与本次改动无关）；ruff 本次改动文件 0 错。
真机端到端：重传 → 旧行 expired + 删除事件 published + 旧向量已从 Milvus 删除；
两个问句回归仍正常回答（r1到r5 gap 0.0766；申购确认 0.8453）。
 2026-09-15 09:06:57 +08:00
lzf_0626 01e4e6a687 修掉"Worker 会自己退出"的真缺陷（场外游标续租失败误取消主任务） 
## 现象（2026-09-14 实测，非人为停止）
Worker 进程自己退出，退出码 1，日志末尾是
`ConnectionResetError: [WinError 10054] 远程主机强迫关闭了一个现有的连接`
（发生在 `offsite_worker.close()` 的 IMAP `logout()`），
而真正的起点是更上面那句 `asyncio.exceptions.CancelledError`。

## 根因（两处，都是真缺陷）
1. **取消错了对象**：`OffsiteMailWorker._process_batch` 把
   `asyncio.current_task()`（= `__main__.serve()` 的**主循环任务**）交给游标心跳，
   心跳在续租失败（`rowcount != 1`）或续租抛异常时执行 `task.cancel()` ——
   于是"放弃这一批"变成了"**杀掉整个 Worker**"。`CancelledError` 从 `run_once()`
   一路冒到 `serve()`，主循环直接结束。
2. **收尾异常盖掉退出原因**：`serve()` 的 `finally` 里 `await offsite_worker.close()`
   在网络已断时抛 `ConnectionResetError`，把 `CancelledError` 顶掉，
   表现为"关闭流程崩了"，看不出真实原因。

## 改法
- `_process_batch` 把"这一批"跑在**独立任务** `batch` 里，心跳只取消 `batch`；
  调用方捕获 `CancelledError` 后区分两种情况：
  **本批被放弃**（`batch.cancelled()` 且当前任务自己没有在取消）→ 记 warning、返回 `False`、
  Worker 继续下一轮；**外层在取消当前任务**（Ctrl+C / 进程关闭）→ 原样上抛，绝不吞掉。
- `serve()` 的 `finally` 里关闭场外 Worker 包 try/except：收尾失败只记日志，
  **不改变退出码与退出原因**。
- 新增 `_current_task_is_cancelling()` 用 `Task.cancelling()` 做这个区分（3.11+）。

## 守卫
`tests/unit/worker/test_offsite_mail_worker.py::test_cursor_lease_loss_abandons_batch_without_cancelling_the_worker`
—— 续租失败（rowcount=0）时断言：批次确实跑起来过、返回 `False`、
**调用方任务没有被取消**。修复前这条用例会挂在"调用方被取消"上。

## 验证
- `pytest tests/unit/worker` → 112 passed
- `pytest tests/unit tests/contract` → 见下方（0 failed）
- `mypy app/worker/offsite_mail_worker.py app/worker/__main__.py` → 0 错（除组员文件里既有的 1 个）
- 重启 Worker 后跑记忆演示链路：候选 → verified → active → **2 秒**收敛，进程稳定

## 文档
`docs/演示用/记忆系统演示文档-2026-09-14.md`：
场景五补"如果发现 Worker 自己退了是怎么回事"，问答补"Worker 会不会自己中途退出"。
 2026-09-15 08:01:00 +08:00
lzf_0626 076d786bc6 补齐客服转人工工单流：从"只能看"到"能推进"（基线状态机，不自行发明） 
## 问题
`svc_handover_ticket` 的 DDL 与状态机在 `docs/02` §7.2 早就定好了
（pending → assigned → processing → resolved → closed，未解决可 cancelled），
但平台**只有 handover:read（只读队列）**：没有任何入口能改状态、assigned_to /
accepted_at / resolved_at / closed_at / resolution 五列**全库 0 非空**，
于是 40 张工单永远停在 pending —— 用户看到的就是"工单全都长一样"。

## 改了什么
后端：
- 新增 `app/service/customer_service_handover_action_service.py`：五个动作
  （分配/接单/解决/关闭/取消），`SELECT ... FOR UPDATE` 锁单后判状态；
  接单允许从 pending 自助接管（同时记受理人）；取消不写 closed_at（该列属 closed 状态）；
  每次流转写一条 interaction_audit（handover.assigned/accepted/resolved/closed/cancelled）；
  非法流转 409、坐席不存在 422、工单不存在 404；回包不含 customer_id/session_id。
- 只读服务保持只读（读侧与写侧是两条边界，单测守着"读侧不许长出写方法"），
  但列表支持 `?status=` 六态筛选、详情补上受理人与流转时间（坐席侧路由信息，非客户数据）。
- `app/api/controllers/admin.py`：五个 action 端点 A049–A053
  （assignments / acceptances / resolutions / closures / cancellations），
  走 `ApiTransactionService.execute_in` —— 幂等记录与业务写入同事务、重复键回放。
- 权限：新增 `handover:write`（9069，只授 admin），已并进种子
  `tools/seed_test_rbac.py`；配套幂等脚本 `tools/grant_handover_write_permission.py`。

前端（管理员工作台 · 转人工工单页）：
- 按状态给按钮（待处理→分配/直接接单、已分配→接单、处理中→解决、已解决→关闭、
  未解决都可取消），加了状态筛选与"刷新"；摘要弹窗补上受理人与四个时间点、处置结论。
- api-client 注册五个端点；workspace.js 的 api-client 引用与页面自身的 ?v= 一并升版，
  避免浏览器拿旧缓存（旧缓存里没有这些端点）。

冒烟与测试：
- `tools/e2e_smoke_test.py`：B 段建的测试工单由 F 段走完 分配→接单→解决→关闭 收尾
  —— 既不再把测试件堆在 pending 队列里（此前每次冒烟攒一张），又让每次冒烟都覆盖一遍状态机。
  总数 40 → 44 项，实测 44/44 全绿。
- 新增单测 24 条（状态机合法/非法路径、越权、坐席不存在、审计、视图不泄漏客户标识）
  与一条真机集成用例（HTTP 十步 + 数据库侧审计证据 + 自动清理）。
- 读侧那条"详情不得返回 assigned_to"的旧断言按新口径更新，并写清为什么。

## 验证
- `pytest tests/unit tests/contract` → 1489 passed, 2 skipped, 0 failed
- 新增集成用例通过；`tests/integration` 全量跑时
  `test_memory_extraction` / `test_run_cancellation_mysql` 两条偶发红 —— 单独跑都通过，
  是 AGENTS.md 已登记的"常驻 Worker 抢队列"（跑验收前须先停 Worker）
- `tools/portal_api_check.py` → 41 项通过 39、失败 0
- `tools/e2e_smoke_test.py` → 44/44 全通过
- `python tools/check_rbac_seed_consistency.py` → 通过（种子 63 条权限）
- 真机 HTTP 实测：分配→接单→解决→关闭四步 200 且时间戳齐全；取消路径 200 且 closed_at 为空；
  同键重发回放不二次推进；对已关闭工单再分配 409；风控账号处置 403

## 文档
`docs/44-演示流程.md`（场景 4/8 + 命令 + 44 项）、`docs/演示用/后端接口文档`（新增 §11.4b 与
A049–A053）、`docs/演示用/全功能流程-大白话版.md`（工单页签改"读写"+ 已知偏差）、
`AGENTS.md`（9066-9069 号段演进 + 冒烟 44 项）
 2026-09-15 00:41:59 +08:00
lzf_0626 9dd2802d67 客户看板「今日盈亏」不再是硬编码 0：按行情/净值基准真实计算（含当日买卖） 
- 口径：今日盈亏 = 今日市值 − 昨日持仓市值 − 今日买入金额 + 今日卖出金额（不含费用，与「持有盈亏」同口径）
- 昨日持仓数量由当日成交反推，不需要新表新字段
- 基准优先场内行情最近两个交易日收盘价（与同页 latest_price/market_value 同源、客户可核对），
  行情只有一天时回退基金净值（15911/159991-159995 的行情本身就来自净值序列）
- 只认 transaction_type ∈ {买入,卖出}：演示库里混进的风控场外申购/赎回（RISKDEMO-*）
  会把「昨日持仓数量」抬到 76 万份、今日盈亏从 -21.22 变成 -1612.72
- 接口字段与前端一行未改：HoldingItem.today_profit_loss / PortfolioSummary 两个字段数值变真
- 新增 tools/check_today_profit_loss.py：纯 SQL 独立复算并与接口逐只比对（实测 9001 = -132.70 / -0.2528%）
- 新增 6 条单测；pytest tests/unit tests/contract → 1466 passed, 0 failed
 2026-09-15 00:03:23 +08:00
lzf_0626 84bf51c0d0 NL2SQL：5 位产品代码被丢弃导致"查询成功但数据错"（演示产品 15911 正是 5 位） 
## 现象

通用自然语言查询里问「查询15911的净值」，返回的是**别的产品**的数据：

```
问：查询15911的净值          → 返回 511810 货币ETF南方 的净值
问：查询基金代码15911最近30天净值 → 同上
```

而且 `status = success`、`message = 查询成功` —— **不报错，只是数据是错的**。

## 根因

`financial_nl2sql_service._filters()` 只认 6 位数字：

```python
re.findall(r"(?<!\d)\d{6}(?!\d)", question)      # 15911 只有 5 位 ⇒ 被静默丢弃
```

过滤条件为空 ⇒ 生成的 SQL **没有产品过滤**（`WHERE 1=1 ... GROUP BY ... LIMIT 50`）
⇒ 返回一批无关于问题的产品净值。现库实测：**6 位代码 25 个、5 位代码 1 个**
（后者就是演示产品 `15911`）—— 所以这个缺陷精确地打在了演示产品上。

`tests/unit/service/test_financial_nl2sql_golden_cases.py` 里 30 条黄金用例**全是 6 位代码**
（159511/588890/159948），因此从未暴露。

## 修法

`app/service/financial_nl2sql_service.py`：

- 产品代码模式放宽为 **5–6 位**（`(?<!\d)\d{5,6}(?!\d)`）；
- 5 位数字更容易与"金额/数量/天数"撞车（6 位不会），因此加单位守卫：
  紧跟 `元/万元/万/亿/份/股/手/天/日/周/个月/年/次/笔` 的一律**不当**产品代码
  （例：「申购金额50000元」里的 50000）；
- 抽成 `_product_codes()` 便于单测。

## 验证

- `query("查询15911的净值")` → SQL 含 `p.product_code = :filter_0`、参数 `15911`、
  返回行 `{"product_code": "15911", "product_name": "15911 自定义产品", "nav": "1.074596"}`；
  三种问法（"查询15911的净值"/"查询基金代码 15911 最近 30 天的净值"/"15911 的最新净值是多少"）全部命中 15911；
- 新增 5 条单测：5 位代码成为过滤条件、6 位仍正常、金额不当代码、
  年份/天数不被误认、多代码并存；
- `pytest tests/unit tests/contract` → **1458 passed, 2 skipped, 0 failed**；
- `ruff` 干净。

## 说明（未改，供你决定）

问「最新净值」时返回的是该产品的 50 行净值明细（SQL 无 `ORDER BY`），
不是"最新的那一条"。要的话我可以补成按日期倒序、单点取值。
 2026-09-14 22:32:26 +08:00
lzf_0626 ae7a89f33d 投顾工作台：修推荐结果渲染（幂等响应形状归一）+ 对齐门户版式规范 
投顾页「生成推荐方案」拿不到产品的根因：该端点标了 idempotent，浏览器必带
Idempotency-Key，而后端此时返回的是 {data:{content_id, status, plan:{...}}, meta}
—— 真正的文档嵌在 data.plan 里。此前前端只处理了不带键时的裸文档形状。

- api-client：ADVISOR_RECOMMEND 撤掉 raw（带幂等键时确为信封，需正常解包）；
  ADVISOR_ALLOCATION / ADVISOR_ANALYSIS 保留 raw（不标幂等，返回裸文档）
- actions-module：新增 normalizeRecommend()，把「信封 + plan 嵌套」与「裸文档」
  两种响应归一成一种形状；结果卡片显示方案编号与待审核状态
- 投顾页：hero 大图 + 4 张概览指标卡 + 左栏/主区两栏构图
- 投顾页：页头常显「退出登录」按钮；新增风评预警数、快捷问句按钮
- 投顾页：动作名统一为「生成推荐方案」（对齐软件需求文档 5.4 ⑦）
- 管理台「待审投顾内容」空态文案同步改名
- 前端模块相对 import 加 ?v= 版本号：改文件内容而 URL 不变会被浏览器缓存挡住
 2026-09-14 22:17:39 +08:00
lzf_0626 1d6c32f6b3 场外核对：桥接"单据账户标识 → 平台交易账号"；保存识别字段后自动重跑核对；运营角色补推介材料权限 
## 一、根因：核对查不到不是"缺数据"，是**账户口径没桥接**

实测（客户 10002 的单据）：

```
生成的 SQL： JOIN fin_holding h ... WHERE h.trade_account = '10002'   ← 单据上的账户标识
结果：       0 行 → 「申请前持有份额」= null → 规则判「无法判断」→ 单据状态 query_failed
```

而库里 `fin_holding.trade_account` 存的是**平台交易账号** `FSA{客户号:06d}`
（与 `fin_sim_account.account_no` 同值，见 `tools/seed_sim_account_demo.py:226`），
客户 10002 **一直持有 15911 共 1000 份**。所以页面上"单据核对与运营动作"是空的，
看起来像缺数据，实为**单据印的账户标识与平台账号是两个口径，中间少了一步换算**。

修法：新增 `OffsiteFundService._platform_account()`，在**单据字段落库的两个入口**
（`_create_document` 新建、`_apply_recognition_fields` 保存/重试）做换算，规则：

1. 已是库里的 `account_no` → 原样；
2. 纯数字且命中 `customer_id` → 用该客户的 `account_no`；
3. 其余原样返回并留 warning —— **失败关闭，不猜不造**（不凭空生成 `FSA099999`）。

一处修好，后端查询、NL2SQL 页面的自然语言、页面展示三处口径一致。
附件上的 OCR **原始值不受影响**（`extracted_fields` 仍是单据上印的 `10002`）。

端到端证据（同一张单据，只走服务层）：

| 阶段 | document.account_identifier | 规则数据 | 单据状态 |
|---|---|---|---|
| 修复前 | `10002` | `{}` → 无法判断 | `query_failed` |
| 保存识别字段后 | **`FSA010002`** | — | `query_failed` |
| 触发核对后 | `FSA010002` | **申请前持有份额 1000.0000** → **正常** | **planned** |

## 二、前端：保存识别字段后自动重跑核对

`employee-operations/offsite/offsite.js`：原先 `save-ocr` 只保存 + 重载页面，
**不触发核对**，于是运营改完字段点保存，那两个区块要么停留在上一次核对的状态、
要么整块是空的，必须再手动点一次"重新核对并判定规则"——看起来像"保存没生效"。

现在：保存 == 运营已人工确认该单据内容，因此保存成功后**自动对该附件关联的单据**
执行「触发 NL2SQL → 拉取返回字段 → 重新判定规则」，并在提示里区分"已重新核对"
与"核对未全部成功"。

顺带把这段逻辑抽成 `recalculateDocument(taskId)`，与面板上的"重新核对并判定规则"
按钮**走同一条路径** —— 两处各写一份正是"保存后不刷新"这类不一致的来源。

## 三、运营（operator）角色权限

`tools/grant_operator_role.py` 的授权清单补齐：`promotion:write/read/review/deliver`
（`promotion_material_service.py` 的八处 `_require` 恰好只用这四个码，缺任一都会 403，
例如只给 write 会在查看详情 read 那一步被拒）+ `agent:run`。

已实际执行并**从身份侧验证**（`IdentityRepository.load_context`）：
9005 / 9006 现在各 7 项权限，四个推介材料码齐全。

- NL2SQL 全库与它相关的权限码**只有 `financial:nl2sql:read`**（`offsite:nl2sql` 在
  `sys_permission` 里并不存在，是 `offsite_fund_service` 里 any-of 校验的死值），
  该码运营早已有，本次无需新增。
- 可持续性已核实：`sys_role_permission` / `sys_user_role` **没有外键**，
  重跑 `seed_test_rbac.py`（DELETE 重建 9001-9099 号段权限）**不会**删掉运营的绑定；
  且本工具按**权限码查 id**、不写死 id，天然抗号段变动。

## 四、10001 / 10002 的 15911 持仓

复核结论：**各 1000 份，且三处口径一致**（`fin_holding.market_value` = 数量 × 最新净值、
净值历史 120 条、`fin_product.current_nav` 与净值最新一条一致、账户可用资金正常）。
`fin_holding` 的唯一键是 `(customer_id, product_id)`，所以**不能**再插一行
`trade_account='10002'` 的"同一个持仓"—— 那会把持仓重复计数，是错的。
需要改数量就用 `python tools/seed_custom_holdings.py --quantity N`（默认就是这两个客户 + 15911）。

## 五、验证与回归

- 新增 `tests/unit/service/test_offsite_account_bridge.py`（5 条：账号原样 / 客户号换算 /
  认不出原样返回 / 不凭空造账号 / 空值不查库）；
- `pytest tests/unit/service -k offsite` → 34 passed；
- 场外集成测试 4 个文件 → 27 passed；
- `ruff` 干净；`mypy app` 仍只有组员新代码里那 3 个既有错（与本次无关）；
- 前端 `node --check offsite.js` 通过。
 2026-09-14 22:16:29 +08:00
lzf_0626 c4f4c33fd6 记忆召回补一道能力码闸门：归属关系不等于授权 
上一版把员工召回改成"按 sys_customer_assignment 归属"时，只看了**归属关系**，
没校验**能力码** —— 这留下一个我自己带出来的口子：

- 平台读他人画像/记忆的正式路径（customer_profile_service、public_platform_service）
  校验的是 `memory:read:customer`（sys_permission id=9010，data_scope='own_customers'）
  + `customer_ids`；
- 而召回是**另一条**把客户记忆送进模型上下文的路径，只按归属放行，等于让
  "有归属行但没有该权限"的账号（例如 operator：只有 financial:nl2sql:read
  + offsite:write）凭空获得读他人客户记忆的能力 —— 它上一版之前是读不到的。

现改为**两个条件都满足才放行**（缺一即失败关闭，并在日志里分开点名"缺能力码"
与"归属未维护"，避免运维在错误的表上找问题）：
  ① `memory:read:customer` 在 context.permissions 里；
  ② 客户落在 context.customer_ids（sys_customer_assignment 生效行）内。

演示账号不受影响：9002(risk_operator)、9020(advisor)、9003(admin) 三个角色都持有该权限码，
真实身份链路复验 9020 仍是"修复前 0 条 → 修复后 2 条"。

测试：tests/unit/core/test_memory_scope.py +3 条（缺能力码读不到／能力码与归属是"与"关系／
现有用例补上能力码），tests/unit/service/test_agent_governance.py 同步。
`pytest tests/unit tests/contract` → 1448 passed, 2 skipped, 1 failed
（唯一失败仍是组员正在改的投顾页面）。
 2026-09-14 21:40:05 +08:00
lzf_0626 9eebf9627f 记忆召回：按 sys_customer_assignment 归属定范围，不再把员工号当客户号 
## 修的是什么

`governance.recall()` 把 `int(context.user_id)` 当客户号用。后果有两个，
方向相反但都致命：

1. **员工身份（风控／投顾／运营／管理员／system）恒空** —— 员工不是客户，
   那是个不存在的客户号；日志只说 "empty"，看不出是"设计如此"还是"记忆坏了"。
2. **越权陷阱** —— 员工号与客户号同号段（演示数据里客户 9001-9020、
   员工 9002/9020 并存）。`int(user_id)` 一旦与真实客户号重合，就会把
   **陌生客户的长期记忆读进来并注入提示词**，且不报错、看起来正常。

同一个问题在代码里还有另外两处**各自判断**、口径互不一致：
`BaseAgent.recall_memory()` 要求"每条记忆 customer_id == context.user_id"
（否则抛"越过客户范围"），`review_output()` 的引用校验只认同一条件。

## 怎么修的

新增 `app/core/memory_scope.py` 作为**唯一判定口径**，三处共用：

- 客户身份（customer / authenticated_user）：**只读自己**，分配表里有别行也不读别人；
- 员工身份：**只读 `sys_customer_assignment` 分配给自己**的客户
  （`context.customer_ids`，由 `IdentityRepository.load_context()` 读入）；
  归属未维护 ⇒ **失败关闭**，并在日志里点名"归属未维护"，与"库里确实没有记忆"区分开；
- 访客：无（上游已拦）。

细节约定：
- 归属客户按客户号**升序**召回、单次上限 `MAX_RECALL_CUSTOMERS=10`
  —— 升序是为了确定性（同一身份每次取同一批，不随数据库返回顺序漂移），
  上限是为了别把成百上千条他人记忆塞进一个提示词；
- 跨客户合并后按置信度降序、`(客户号, uuid)` 兜底排序，最多 10 条；
- 员工同时持有多个归属客户的记忆时，`memory_context_text()` **逐行标注客户号**
  并把提示词改成"多个客户的长期事实" —— 否则模型会把 A 客户的事实当成 B 客户的。
  单一客户时保持原格式（客户身份的提示词与改动前逐字相同）；
- 引用校验与范围守卫都改用同一口径：员工引用**归属客户**的记忆不再被判成伪造引用；
  引用**非归属客户**的记忆即便被塞进 memories 也照样拦下。

## 验证（真实身份链路 + 生产召回装配）

`IdentityRepository.load_context` → `PlatformGovernance.recall`（含 Milvus 语义通道）：

- 身份展开：roles=('advisor',)、customer_ids=('9001',)（sys_customer_assignment
  里唯一那行 9020→9001）、可读范围 (9001,)；
- **修复前** `recall(int(user_id)=9020)` → **0 条**；
- **修复后** `recall(按归属)` → **2 条**（客户9001：进取型 / 约三年）；
- 边界：客户身份 9001 可读范围 (9001,)；无归属员工 9002 = ()（失败关闭，
  且**没有**把 9002 当客户号）；未分配时的 9020 = ()。

测试：`pytest tests/unit tests/contract` → **1445 passed, 2 skipped, 1 failed**
（1432 + 新增 13；唯一失败是组员正在改的投顾页面，与记忆链路无关）。
新增用例：`tests/unit/core/test_memory_scope.py`（8 条，含"员工号不得被当成客户号"
的反例断言）、`tests/unit/service/test_agent_governance.py`（+5 条：归属召回／
无归属失败关闭且不碰数据库／客户只读自己／引用校验／越界守卫）。

## 遗留（已在 AGENTS.md 与文档里写明，未自行实施）

风控扫描这条线**仍读不到记忆**：它是唯一消费召回内容的地方
（`risk_agent.py:224`），而扫描上下文是 user_id="0"/roles=("system",) 且无归属行。
根因是**顺序问题**：召回发生在 handle() 之前，上下文里没有"本次目标客户"这个概念。
出路有两条：① 给风控专员补 sys_customer_assignment 行（运维动作，立即可用）；
② 在 RequestContext 加显式的 target_customer_id 并校验它落在归属集合内
（推荐，但属跨线协议改动，等确认）。

文档：docs/演示用/记忆召回恒空-根因与修复-2026-09-14.md 新增 §五（含 §5.4 遗留说明）、
AGENTS.md 新增"记忆可读范围只有一个判定口径"易错点，并按 2026-09-14 复测更新测试基线。
 2026-09-14 21:33:16 +08:00
lzf_0626 0c642133d4 修复长期记忆向量链路：投影入队 + 集合名三侧同源 + 召回按客户过滤 
语义召回"恒空"的根因分四层，本提交修掉投递层与读取层（另两层——重试计数
门禁、episode 不投 rebuild 事件——已在前两个提交修复）。

R2 投递层：dispatch_profile_rebuild 只做图投影，没有任何 Milvus 投递，
  长期记忆的向量从未被写入过（实测客户 9001 在 memory_sync_outbox 里 0 行）。
  新增 _enqueue_memory_vector_projection()，在画像重建后投
  MemorySyncOutbox(target_store="milvus")。走事件而不是同步写，是为了拿
  Outbox 的重试/退避/死信，且不把 embedding 的网络等待拖进事务。
  ⚠️ payload 必须带 version（正整数）：适配器 _coerce_profile_version 缺它
  直接抛 ValueError（实测踩到，事件立刻 failed）。

R4 读取层：写的集合与读的集合不是同一个 ——
  写（MilvusProfileProjection）用 "user_long_term_memory_v1"，
  读（bootstrap.get_vector_memory_adapter）与删（projection_cleanup_service）
  却用 settings.milvus_collection = "jr_memory"，而该集合从未被创建。
  ⇒ 召回：MilvusClient 构造不校验集合存在，适配器"构造成功"但每次 search
     抛异常被 VectorMemoryAdapter 吞成 degraded → 召回恒
     degraded_reasons=('milvus_unavailable',)、向量命中恒 0 条；
  ⇒ 清理：jr_memory 不在集合列表 → 走 vector_collection_absent 分支 →
     报清理成功但一个向量都没删，陈旧向量永久留存。
  修法：PROFILE_COLLECTION 成为唯一常量，读/删两侧直接引用它；
  并删除 Settings.milvus_collection 配置项、清掉 .env.example 的
  MILVUS_COLLECTION —— 写侧从来没读过它，一个只在契约一侧生效的配置项
  比没有配置项更危险（Settings 的 extra="ignore" 会让其他环境残留的该
  变量被安全忽略）。

顺带：
- 语义检索把客户过滤下推到 Milvus（filter="customer_id == N"）。此前不带
  过滤，别家客户的命中会白占 limit 名额，稀释本客户的召回条数。
- upsert 在 sources 为空时先返回，不再无条件 load_collection ——
  "本来就没有可写内容"不该被记成投递失败（10001/10002 那两条事件即如此
  重试 5 次进死信）。

回归守卫：tests/unit/infrastructure/test_memory_vector_collection_consistency.py
  断言读侧与删侧用的都是 PROFILE_COLLECTION，且被删掉的配置项不得回归。
  这个缺陷能活下来，正是因为两侧单测全绿而接缝无人守。

验证（走生产装配、进程内调用，未重启你正在跑的 API 窗口）：
  读侧集合打印 user_long_term_memory_v1（修前为 jr_memory）；
  召回 degraded=False / reasons=() / sources 含 milvus，且排序随 query 语义
  变化（投资期限→horizon 0.288 > risk_level 0.201；风险偏好→risk_level 0.287）；
  query="进取型" 双通道合并且 vector_score=0.9987；query=None 走 mysql 全量。
  pytest tests/unit tests/contract → 1432 passed, 2 skipped, 1 failed
  （唯一失败是同事正在改的投顾页面，与记忆链路无关）。

文档：docs/演示用/记忆召回恒空-根因与修复-2026-09-14.md（新增，四层根因+证据）、
  docs/37-记忆投影链路实现说明.md（补集合名三侧契约）。
 2026-09-14 21:26:03 +08:00
lzf_0626 3a1065ca1e 修复片段链路：重复聚合拖垮重试预算 + 从不投画像重建事件 
## 结论先说：真正的根因和最初两个假设都不是同一个

你原来的判断是「第二条召回恒空、第三条传导断链」，并猜第三条是
「`record_evidence` 返回 False 时该不该补写重建事件」。查完库发现：

1. **`record_evidence` 返回 False 时数据零净变化**（幂等命中直接 return；
   并发冲突把刚加的计数减回来），所以那个判断点解释不了画像停更；
2. **`memory_extraction_worker` 是有写重建事件的**（`if recorded:`），
   233 条 `profile.rebuild_requested` 全 published；
3. 真正断在两处，都在 **`episode_worker`** 这条片段链路上。

## 根因一：`_touch_retry` 把「重复聚合」记成「抽取失败」（P0，已修）

`episode_worker._persist` 在 `content_hash` 命中（同一段会话被重复聚合）时调
`_touch_retry` 做 `retry_count += 1`。但 `retry_count` 的语义是**抽取失败次数**
（由 `_mark_failed` 累加），而"分片逻辑每轮重新看到同一段会话"根本不是失败。

后果是实测出来的：

    episodes 待提取片段：retry_count=1405（40 条，全是客户 9001）
    consume_pending 逐条件筛：
      仅 status in (待提取,失败)      -> 40
      + retry_count < max_retry(3)    -> 0     ← 一个都不剩
      + promoted_to_ltm IS FALSE      -> 40

这 40 条片段**永远不可能被选中** ⇒ 新记忆进不来 ⇒ 画像停在旧值。
（另外还观察到一次运行里它从 1405 涨到 1407 —— 常驻 Worker 每轮都在继续推高。）

**修法**：重复聚合不再触碰 `retry_count`，连 `flush` 都不做（内容没变就只是看到）。

## 根因二：片段链路从不投「画像重建」事件（已修）

`memory_extraction_worker` 写完证据会投 `profile.rebuild_requested`；
而 `episode_worker` 写完证据直接 `_mark_done` 就结束了 —— **完全没有这一步**。
所以即使片段被成功抽取，画像也不会重建。

**修法**：`episode_worker` 也捕获 `recorded` 并在为真时投同样的事件
（`trigger="episode_extraction"`）。只在 `recorded=True` 时投：幂等命中时证据与计数
都没有净变化，投一次是白跑。

## 数据修复

代码修好不会让已写进库的脏计数自己恢复 —— 那 40 条片段仍然超预算。
用 `tools` 级别的临时脚本把**确实被污染的行**重置（条件收紧为三者交集）：

    extraction_status IN ('待提取','失败') AND promoted_to_ltm = 0 AND retry_count >= 3
    -> 重置 40 行；之后可被 consume_pending 选中的片段从 0 恢复到 40

## 实测

- **重试预算修复**：`consume_episodes` 从"领不到任何片段"变为能领到；
  分两批消费完 40 条（全部 `no_fact` —— 那些片段摘要里确实没有用户陈述，
  属正常结果），待提取 40 → 0
- **重建事件修复**：那 40 条全是 `no_fact`，走不到 `if recorded:`，所以**
  实测不到**。为不留下"改了但没验证"，另造了一条含用户陈述的片段：

      consume_episodes -> extracted=[191]
      9001 的 rebuild 事件 3 -> 4（增量 1）
      memory_evidence 8 -> 9

  另外注意到基线在我造数据前已经由 1 涨到 3 —— 说明常驻 Worker 也在这期间
  投过事件，修复在真实链路里同样生效。
- `pytest tests/unit tests/contract` -> 1428 passed / 2 skipped / 1 failed
  （剩下的 1 个是投顾工作台页面被替换所致，与本次无关）

## 测试

两个既有用例断言的正是被修掉的旧行为，已更新，并把第二个改造成**防回归守卫**
`test_repeated_aggregation_never_bumps_retry_count` —— 它守着
"`retry_count` 被重复聚合推高到 `max_retry` 之上会导致片段永久滞留"这个 P0。
`tests/unit/worker/test_episode_worker.py` 16 passed。

## 未处理

「召回恒空」（员工身份下 `recall` 取的是自己作为客户的记忆）**本次没动**。
它需要给 `AgentRequest` 加 `target_customer_id` 并配套越权校验，属接口契约变更；
排查报告给的建议是保持现状、员工侧走 `query_customer_profile` 工具。
要按"支持目标客户维度"做，请确认，我再单独一提交。
 2026-09-14 21:09:03 +08:00
lzf_0626 c868f01e67 修复 §19 端点编号检查的误报：按表格块识别，而不是"整章所有表格行" 
## 问题

`test_real_document_has_no_duplicate_endpoint_ids` 失败，报 7 处"首列无法识别"：
`**场外基金**`、`**场外运营**`、`**客户入驻**`、`**推广材料**`、`**访客令牌**`、
`**账户与交易**`、`段`。

查下去发现**文档没错、工具错了**：§19 里除端点总目录外，还有一张
「段 / 前缀 / 挂载来源 / 权限口径」的**说明表**（`docs/05` 行 1207 起）。它的首列是
分组名、表头是 `段` 而不是 `编号`。工具早期实现把**整章所有表格行**都当端点表扫，
于是那张说明表的 6 个分组名 + 1 个表头被报成结构异常。

**误报比漏报更伤**：这个脚本存在的意义是抓"编号被复用"（2026-09-12 真的发生过
`A034`/`A035` 各出现两次），可一旦它平时就在报噪声，真出问题时会被当成噪声忽略。

## 改法

`collect_rows` 改为**按表格块**识别：

- 表格块的第一行是表头；**只有表头首列是 `编号`** 的表格才是端点总目录；
- 其它表格整体跳过并**计数** —— 跳过几张表会打印出来，所以"忽略了什么"是可见的，
  不是静默的；
- 端点表**内部**形状不对的首列**仍然报出来** —— 那才是真正的结构异常。

于是"§19 覆盖"这行现在长这样：

    §19 覆盖：93 个端点编号 / 9 个号段（A×49、AD×11、C×7、K×4、M×4、O×3、P×2、R×4、T×9）；跳过 1 张非端点表

跳过的表被显式写出来，覆盖范围仍然可核对 —— 这是原实现"不枚举前缀白名单、
把扫到的号段一并打印"那套自检思路的延续。

## 测试

`test_real_document_actually_scans_enough_endpoints` 因 `collect_rows` 返回值从
2 元组变 3 元组而需要同步；顺便**加了一条断言守住新行为**：
`skipped >= 1`，即"§19 的说明表确实被识别为独立表格块并跳过" —— 否则那几个分组名
会重新变成误报，而这条测试会先失败。

## 实测

- `python tools/check_docs_endpoint_ids.py` -> **exit 0**
  「93 个端点编号 / 9 个号段；跳过 1 张非端点表 / 端点编号无重复」
- `pytest tests/unit tests/contract` -> **1428 passed, 2 skipped, 1 failed**
  （剩下的 1 个是投顾工作台 `index.html` 被整体替换成自包含静态页所致，
  属产品决策，见前述说明）
- `ruff check` -> All checks passed
 2026-09-14 20:29:54 +08:00
lzf_0626 6b2e2edcda P0-2：恢复基线要求的 AUTO_INCREMENT，消除手工发号的并发主键冲突 
## 问题

`trade_service._next_id` 用 `SELECT MAX(id)+1` 发主键。两个事务读到同一个 MAX、
算出同一个 id，后写的那笔 `flush()` 撞 `Duplicate entry ... for key 'PRIMARY'`
-> 该客户下单直接 **500**。`submit_order` 一次要发 **3 个 id**
（订单 / 成交 / 资金流水），冲突面是单表的三倍。

## 这是"修正偏差"，不是"改基线"

`docs/00-新数据库基线设计.md` 第 41 行：

    | 主键 | 统一 `BIGINT UNSIGNED AUTO_INCREMENT`，业务编号另设唯一键 |

**基线本来就要求 AUTO_INCREMENT**，是生成的 DDL 漏了 —— `_next_id` 自己的
docstring 也写着"与 docs/00 设计稿存在偏差"。所以本迁移**不违反** AGENTS.md
规则 4（禁止改类型/可空性/业务含义）：类型仍是 `BIGINT UNSIGNED`、仍是 `NOT NULL`、
`id` 的业务含义不变，只是补回一个列属性；已有行 id 不变，显式给 id 依然合法。

## 迁移 `20260914_baseline_auto_increment`

- **15 张表**恢复 AUTO_INCREMENT（硬编码表名 —— 迁移必须确定性，动态查
  `information_schema` 会让同一份迁移在不同环境产生不同结果）。
- **有意排除 3 张**（`EXCLUDED_BECAUSE_FOREIGN_KEY`）：`fin_product`（被 10 张
  `advisor_product_*` 引用）、`fin_risk_assessment`、`sys_user`（被 19+ 张引用）。
  MySQL 拒绝 `MODIFY` 被外键引用的列：

      (1833, "Cannot change column 'id': used in a foreign key constraint ...")

  改它们必须先 DROP FOREIGN KEY -> MODIFY -> 重建外键，那是另一件事（涉及 30+ 个
  外键的重建与一致性验证），不该塞进这条"恢复基线属性"的迁移。且这三张表**写入
  频率很低、没有任何代码用 `SELECT MAX(id)+1` 给它们发号** —— 排除它们不影响
  本迁移的目标。
- `downgrade()` 可回滚（只是去掉属性、不丢数据），但注释里写明：**回滚会把 P0-2
  的并发冲突带回来**。

⚠️ 迁移执行中踩到过"部分生效"：MySQL DDL 非事务性，第一次跑到 `fin_product`
才报错，**前 7 张已经改完**。修正列表后重跑即收敛（对已是 AUTO_INCREMENT 的列
再 `MODIFY` 是无害的）。这一点也说明**迁移必须逐表可重入**。

## 代码

`trade_service.py` 删除 `_next_id` 方法及 4 处调用（`FundSimOrder` /
`FundTransaction` / `FundCashLedger` / `FundHolding`），改由 InnoDB 分配；
顺带清掉因此不再使用的 `Any` 与 `func` import（全仓 grep 确认它们只服务于
`_next_id`）。测试对 `_next_id` 零依赖（已 grep 确认）。

`test_advisor_migration_contract.py` 里那个"钉住末端版本"的断言按它自己的注释
要求同步更新到新 head。

## 实测

- `alembic upgrade head` -> `current = 20260914_baseline_auto_increment`，
  复核状态：**15 张已生效、3 张按设计排除**
- **并发下单实测**（2 个客户 × 3 笔 = 6 笔真并发；刻意用**不同客户**，
  因为 P0-3 的行锁已经把同一客户串行化了，不同客户才会真正并发进入发号路径）：

      成功 6 / 主键冲突 0 / 其它失败 0
      => P0-2 已解决

- `pytest tests/unit tests/contract` -> **1427 passed, 2 skipped, 2 failed**
  （2 个既有失败与本次无关）
- `ruff check` -> All checks passed
 2026-09-14 20:27:35 +08:00
lzf_0626 e4cd336afa 修复权限拒绝变 500、访客令牌无限流，并让两处测试跟上代码 
## 1. 权限不足从 500 修回 403（14 个测试失败里的 11 个）

`app/service/authorization_service.py` 的 `_deny` 构造 `InteractionAudit(...)` 时
**漏了 `created_at`**（该列 NOT NULL 且无默认值），而 `raise ForbiddenAgentError`
写在 `session.commit()` **之后** —— commit 必抛 IntegrityError
（1048: Column 'created_at' cannot be null），于是**永远走不到 raise**：

    预期 403，实际 500：Internal Server Error

**⇒ 任何「权限不足」的请求都变成 500**，破坏 docs/05 §3.6 的错误码契约。
全仓 100+ 处 `InteractionAudit(...)` 都跟着 `created_at=now`，只有这一处没有
（由 2026-09-14 的 `857c106`「投顾工作台：三接口支持按客户出方案」引入）。

修两处：
- 补 `created_at`；
- **并把审计写入失败与 403 解耦**（try/except + `logger.warning(exc_info=True)`）：
  安全判定不该依赖审计表是否可写 —— 拒绝就是拒绝。但也绝不静默，审计缺失是合规问题。

## 2. 访客令牌端点补限流（P0-4）

`app/api/controllers/visitor_tokens.py` 此前**零认证、零限流**，可以不限量铸造
有效 JWT；每个都能调 `/api/v1/agent-runs` 触发 LLM 调用，而 agent-runs 的限流
按 `user_id` 计、访客 `sub` 每次都是新随机值 ⇒ **限流被天然绕过**。

把 `rate_limit.py` 的登录闸门抽成通用的 `_enforce_ip_rate_limit(...)`，
新增 `enforce_visitor_token_rate_limit` 挂到该端点的 router 上。

⚠️ 刻意**用独立计数器前缀**（`visitor-token` vs `login`）而不是直接复用登录闸门：
共用会让两者互相挤占配额 —— 正常访客刷几次页面就把别人挡在登录外。

阈值 30 次/分钟（比登录的 10 次宽松，因为访客进站/刷新会正常签发）。

## 3. 测试跟上代码（2 个）

- `test_product_recommendation_service.py`：monkeypatch 打在 `current_for_agent` 上，
  而 `generate()` 现在走 `current_for_customer(customer_id, context)` —— 补丁不生效，
  真实方法被执行并命中鉴权抛 403。改为按新签名打补丁。
- `test_authorization_service.py` 等 3 个：随第 1 项一起恢复。

## 实测

- `pytest tests/unit tests/contract` -> **1427 passed, 2 skipped, 2 failed**
  （修复前 **14 failed** / 1426 passed）
- `_deny`：权限不足恢复 **403**（原为 500）
- 访客限流：连发 40 次 -> `{201: 30, 429: 10}`，首次被拒返回
  `RATE_LIMITED「访客令牌签发过于频繁：每 60 秒最多 30 次」`
  （修复前：连发 15 次全部 201、无限流）
- `ruff check` -> All checks passed

## 剩余 2 个失败（需产品决策，未擅自处理）

1. `test_advisor_workspace_registers_documented_operation_endpoints` ——
   `employee-advisor/dashboard/index.html` 已被**整个替换**为一个自包含静态页
   （`data-page-node-id` 属性、内联全部 CSS/JS、硬编码 `API="http://127.0.0.1:8000"`、
   自带「离线本地引擎」），**不引用 `api-client.js` / `app-shell.js`、不调 `mountShell`**。
   测试断言的是旧页面措辞（"组合分析"），新页面写的是"生成推荐方案"。
   是接受替换后的页面（改测试断言），还是恢复挂平台壳的版本，属产品决策。
2. `test_docs_endpoint_ids` —— `docs/05` §19 表里被插入了分组标题行
   （`**场外基金**`、`**账户与交易**`），而检查工具要求首列是端点编号。
 2026-09-14 20:14:50 +08:00
yuancong_0626 14e027f781 合并yy与远程qyqy_develop并保留业务优先级 2026-09-14 18:16:33 +08:00
yuancong_0626 2548c39c6b 袁聪的最后一次完善更新 2026-09-14 18:13:10 +08:00
lzf_0626 e6d74059f2 修复员工工作台顶部导航重复（入口 JS 被引两次） 
## 现象

打开 `employee-console/workspace`（平台治理），页面上出现**两份一模一样的顶部栏**：
南方财富 / 模拟基金服务 / 平台治理 / 风控中心 / admin_t 管理员 —— 连同页脚一起各两份。

## 根因：同一个入口 JS 被引了两次，且 `?v=` 不同

`app/static/portal/employee-console/workspace/index.html` 里曾同时存在：

    <script type="module" src=".../workspace.js?v=20260913-3"></script>
    <script type="module" src=".../workspace.js?v=20260914"></script>

浏览器按**完整 URL** 去重，两条不同 query 被当成**两个模块**、**各执行一次**。
入口里的 `mountShell()` 因此跑了两次，而它当时是
`document.body.insertAdjacentHTML('afterbegin', ...)` —— **无条件插入**，
于是 header 与 footer 各插两份。

来源是合并事故（`git blame` 定位）：

| 行 | 提交 | 作者 |
|---|---|---|
| 旧 | `e31420df` | 卿云秋月（把版本号改成 `20260913-3`）|
| 新 | `f5d1b246` | 张胜宇（把版本号改成 `20260914`）|

两人各自把**同一行**的版本号换成新的，合并时两边都被保留，成了两行。
那个提交的信息是 "merge ... and retain risk review updates" ——
"retain" 在这里保留错了地方。

## 修法（两侧都堵）

1. **HTML 收敛成一行**（保留较新的 `?v=20260914`，与 `workspace.js` 内部
   `api-client.js?v=20260914` 一致），并就地写明"改版本号是替换这一行、不是新增一行"。
2. **`mountShell` 加幂等保护**：已有 `.site-header` 就直接 return。
   之所以不满足于只修那个 HTML —— 这个 bug 的症状很难反推到原因
   （页面看起来只是"多了一块"），而以后谁加缓存版本号时很容易再犯一次。

## 防回归（两条测试，都做过负面验证）

- `test_no_portal_page_includes_the_same_script_twice`：扫 `app/static/portal` 下
  **19 个页面**，把 `<script src>` 去掉 query 后比对，同一入口出现多次即失败。
  负面验证：把重复行临时放回去，测试**精确报出**
  `employee-console\workspace\index.html: ['/static/portal/employee-console/workspace/workspace.js']`，
  恢复后通过。
- `test_mount_shell_is_idempotent`：断言 `app-shell.js` 里有那句幂等判断。

全站扫描确认**只有这一处**，不是批量问题。

## 实测

- `GET /portal/employee-console/workspace/` -> 200，页面里 `workspace.js` **只出现一次**
  （`?v=20260914`）；静态 HTML 中 `site-header` 出现 **0 次**（确认由 JS 注入，
  所以 JS 执行一次就只插一份）
- `pytest tests/unit/api/test_portal_frontend.py` -> **43 passed**（41 + 新增 2 条）
- `ruff check` -> All checks passed

## 一点说明

这次是"改同一个版本号"的合并冲突处理失误，属于**流程问题**而非个人疏忽：
两边都想把缓存版本号推新，冲突解决时很容易两边都留下。
测试补上之后，这类错误会在 `pytest tests/unit` 里当场暴露。
 2026-09-14 12:06:38 +08:00
zhangshy 4b7ee13cf5 修复管理员工作台函数缺少闭合大括号 2026-09-14 10:56:45 +08:00
zhangshy bfbaf823c2 同步预警队列后端分页上限为十条 2026-09-14 10:50:48 +08:00
zhangshy baecb89bd4 预警队列调整为每页十条 2026-09-14 10:40:41 +08:00
lzf_0626 e096ffab22 修复投顾工作台白板：补上模块拆分时漏掉的 import 
## 问题（合并进来的故障，不是本次会话改坏的）

合并 `origin/qyqy_develop`（f5d1b24 / 3134fe5）后 `pytest` 红了一条：
`test_advisor_dashboard_is_composed_from_feature_modules`。

查下去发现是**拆分做了一半**：

- 新建了 `advisor-config.js` / `actions-module.js` / `published-module.js`
- 把 `CONTENT_TYPE_LABELS`、`actionLabels`、`resultMessages` 从 `dashboard.js` 删掉了
- **但没有在 `dashboard.js` 里 import 它们**，`dashboard.js` 仍是拆分前的内联版本，
  第 39 行还在用 `CONTENT_TYPE_LABELS`

后果不只是测试红：投顾工作台一打开就 `ReferenceError: CONTENT_TYPE_LABELS is not defined`，
页面渲染不出来；同时那两个新模块是**死代码**（没有任何地方 import 它们）。
`index.html` 是单入口（只加载 `dashboard.js`），所以模块必须由它 import。

## 修法：把重构接完，而不是把测试改掉

- `dashboard.js` 变成薄组合层：挂 shell、取 DOM、组合两个模块，其余逻辑不再内联
- `advisor-config.js` 收拢 `GOAL_STATUS_LABELS` / `BOOK_STATUS_LABELS`（原来内联在 dashboard.js）
- `actions-module.js` 接管「目标确认与方案书」
- `published-module.js` 直接可用

⚠️ 关键点：`bind()` 会给**所有** `[data-action]` 按钮挂 `open()`，而 `actions-module.js`
原先不认识 `goal-status` —— 直接接线会让它掉到最后一行的兜底分支、被当成
「资产配置」发出去（点"目标确认与方案书"却收到一份配置建议）。
所以把「目标确认与方案书」一并做进 `open()` 的分支里，并在两处留了注释说明这个约束。

「目标确认与方案书」这条功能本身要保留：此前工作台只有 4 个"生成草案"操作 + 1 个只读列表，
而确认目标与查看方案书这两个端点**有接口没入口**，导致目标永远停在 `pending_confirmation`、
方案书永远停在 `pending`（实测客户 9001 正是如此）。

## 防回归：tools/check_portal_modules.py（新）

上面那个 bug **不能靠现有断言发现** —— 那些测试断言的是"某个字符串在文件里出现"，
而这里的问题是"定义搬走了、使用处还在"，浏览器里才炸，Python 测试全绿。

新检查做四件事：`node --check` 按 ES module 解析语法、相对 import 的目标文件存在、
import 的名字在目标文件里真有 `export`、**用到的全大写常量必须有来源**。

第 4 条是抓这个 bug 的关键。写的时候踩了两次坑，都已修正并记录在文件里：

1. 第一版用 `(?<![\w.$])` 排除属性访问、却把**模板字符串整体**当字符串剔除了 ——
   而 `CONTENT_TYPE_LABELS[row.content_type]` 恰好写在模板字符串里，
   于是漏报、检查全绿。现在只剔除单双引号字符串，模板字符串保留（`${}` 里是真代码）。
2. 用负面验证确认它真的有效：把 `published-module.js` 的 import 拿掉后，
   检查精确报出 `使用了 'CONTENT_TYPE_LABELS'，但既没 import 也没在本文件声明`（exit 1）；
   恢复后 exit 0。没有这一步，这个检查就是个摆设。

同时接进测试：`test_portal_feature_modules_have_consistent_imports` 调用它，
保证以后每次 `pytest tests/unit` 都会执行。

## 实测

- `pytest tests/unit tests/contract` -> **1400 passed, 2 skipped, 0 failed**
  （合并后未修时是 1399 passed + 1 failed）
- `pytest tests/unit/api/test_portal_frontend.py` -> 39 passed（38 + 新增 1 条）
- `python tools/check_portal_modules.py` -> 全部通过；负面验证 exit 1
- `ruff check app tests tools alembic hq.py` -> All checks passed
 2026-09-14 02:07:44 +08:00
张胜宇 f5d1b24618 merge qyqy_develop and retain risk review updates 2026-09-14 01:41:02 +08:00
yuancong_0626 abbfb6eddd 合并yy并同步远程qyqy_develop 2026-09-14 01:11:07 +08:00
yuancong_0626 7a49a1c2c8 袁聪的前端调修 2026-09-14 01:07:43 +08:00
lzf_0626 9a5259d787 feat(market): 存下行情源给的涨跌幅，产品列表与排行页不再显示"暂无" 
## 问题

产品列表与排行页的「最近涨跌」全是"暂无"。原因是它只能由**两个交易日的收盘价**
现算，而 `fin_market_price` 每只产品每天只有一行 —— 库里头一天只有一天数据时
根本算不出来。

## 但行情源本来就给了这个数

腾讯行情接口的第 32 位就是**当日涨跌幅**（适配器此前只解析了开高低收量额，没取它）。
所以不必等第二个交易日去算，把源给的数存下来即可。

## 改动

- **迁移** `20260913_market_price_change_pct`：给 `fin_market_price` **新增一个可空列**
  `change_pct DECIMAL(10,4)`。只加列、不改任何已有字段（AGENTS.md 规则 2 允许），
  可空且不回填，既有读写方全部不受影响。
- **适配器**：`_parse_tencent` 增解析位置 4（昨收）与位置 32（涨跌幅）。
- **同步服务**：写入 `change_pct`；降级路径（净值兜底）没有这个数就写 **NULL**。
- **接口**：`_resolve_change_pct` **优先用存下来的值**；迁移前的历史行没有该列的值，
  才回退到"今日收盘 vs 昨收"现算。仍为 `null` 时前端显示"暂无" ——
  **不得当成 0**（`formatPercent(null)` 会渲染成 `+0.00%`，那等于说"今天平盘"）。

## 契约测试同步

两处契约断言因结构演进需要跟进 —— 它们的作用正是拦住这类变更：

- `test_fund_readonly_contract.py`：`fin_market_price` 列数 **13 → 14**
- `test_advisor_migration_contract.py`：迁移 head 更新为新版本
  （核心断言仍是"链收敛到唯一 head"，此处只是钉住末端）

验证：实测 20 只产品**全部有真实涨跌幅**（如 515450 −0.43%、159511 +1.23%）；
unit+contract **1397 passed**；integration **110 passed**；ruff 通过；
mypy 251 文件 0 错；`audit_schema` 与 `migration_state_check` 均通过；e2e 冒烟 40/40。
 2026-09-14 00:30:06 +08:00
lzf_0626 373bcb2a68 fix(test): 补 FakeSession.scalar 桩，修复合并进来的 15 个红灯用例 
组员的 `2a3146e`（"增加风控列表总数"）在 `fund_query_repository.fetch_page` 里新增了
一次 `await self.session.scalar(select(func.count())...)` 来返回 `total`，但
`tests/unit/repository/test_fund_query_repository.py` 的 `FakeSession` 只有 `execute`，
于是该文件**15 个用例全部**挂在：

    AttributeError: 'FakeSession' object has no attribute 'scalar'

## 改动

给 `FakeSession` 加 `scalar`：

- **返回值取 `len(_rows)`**。这些用例没有一处断言 `total`（只校验 `has_more` /
  `next_offset` 与生成的 SQL），返回非负整数即可；`_rows` 是带 `limit+1` 的当页结果，
  所以它**不是真实总数** —— 将来若要断言 total，需给这个桩加显式参数。
- **不写入 `statements`**。`last_sql` 取的是 `statements[-1]`，而有用例断言的是
  **分页查询**的 SQL（LIMIT / ORDER BY / 过滤条件）。第一版实现把 count 语句也
  append 了进去，`last_sql` 随即指向 count 语句，4 个用例的断言集体落空
  （实测：15 failed → 4 failed → 0）。count 语句改记在 `count_statements` 里备查。

验证：`test_fund_query_repository.py` 18 passed；unit+contract **1397 passed**；
ruff 通过；e2e 冒烟 40/40。
 2026-09-14 00:02:35 +08:00
zhangshy 2a3146e050 增加风控列表总数并优化站内提醒 2026-09-13 23:51:45 +08:00
zhangshy 38fe6f3689 合并主项目最新改动并解决风控前端冲突 2026-09-13 23:22:12 +08:00
zhangshy 4f75d32ea1 优化风控详情展示与前端交互 2026-09-13 23:19:52 +08:00
张胜宇 3325232e2a feat(portal): complete advisor workspace operations 2026-09-13 23:04:35 +08:00
zhangshy 522c9b19fe Merge remote-tracking branch 'origin/qyqy_develop' into RM2_develop 2026-09-13 21:09:09 +08:00
zhangshy 09c80575b7 延长风控手动扫描前端超时 2026-09-13 21:08:57 +08:00
lzf_0626 fef4c826ff fix(worker): 知识写入 Milvus 必须探测字段名并补齐必填字段 
背景：走 `POST /api/v1/knowledge/upload` 灌了 22 块场内基金知识，MySQL 全部写入成功、
向量事件也全部投递，却全部同步失败（重试 3 次进死信），客服检索不到新知识。
逐层定位出三个真问题，都在写入侧：

1) **字段名硬编码**。检索侧早已按 AGENTS.md 改用运行时探测
   （`app/core/knowledge_schema.py`：`doc_id`↔`knowledge_id`、`content`↔`snippet`），
   写侧却一直硬编码 `knowledge_id` / `snippet`。本机集合实际是
   `doc_id`/`content`/`chapter`/`visibility`/…（架构师那套 schema），于是
   `Attempt to insert an unexpected field knowledge_id` 整条失败。
   现在两侧共用 `resolve_schema` 的同一份映射表，调用方只用**逻辑**字段名；
   集合没有的字段（如另一套环境无 `intent`）跳过而不是报错。

2) **非 nullable 必填字段没给**。改完名字后报
   `Insert missed an field chapter to collection without set nullable==true`：
   集合里存在、调用方没提供的 VARCHAR 字段必须补值。VARCHAR 的判据用
   `params.max_length`，不必 import pymilvus 的枚举。

3) **补值不能一律空串**：`visibility` 留空会被检索侧
   `visibility == "public"` 的过滤整行排除。这条最隐蔽 —— `query` 查得到、`search`
   查不到，表现为「入库成功但客服永远答不出新知识」，比写入直接失败更难定位。
   现在按 `FIELD_DEFAULTS` 给有语义的字段默认值。

Worker 侧把 `fields` 的键改成逻辑名（`snippet` → `content`），上限表随之改名。

**测试**：原来的桩没有 `describe_collection`，所以这条路径从未覆盖到真机 schema
（这正是缺陷长期存在的原因）。现在桩提供两套真实 schema 并参数化，另加
「跳过集合没有的字段」「探测不出必要字段必须失败关闭」两个用例。

**验证**：22 块重新同步后 `fin_product_collection` 236 行、`visibility` 全为 `public`；
问「南方沪深300ETF 的起投金额是多少」命中新块 `score=0.7932`（≥ `HIGH_SCORE` 0.75），
客服从「转人工」变为直接作答，端到端 3.34 秒。

**另**：新增 `docs/43-场内基金产品手册（知识库入库版）.md` —— 从 `docs/42` 抽出
**客户可见**的纯净内容（去掉全部内部决策备注）供入库；`docs/42` 保留为草稿与决策记录。
 2026-09-13 20:08:31 +08:00
张胜宇 aa4b9bf367 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-13 19:26:31 +08:00
张胜宇 e3c316aafb Enforce trading authorization and suitability checks 2026-09-13 19:24:59 +08:00
lzf_0626 f72a545c39 refactor: 品牌统一为「南方财富」（项目方定） 
背景：品牌名此前三处不一致 —— 后端 Agent 自称「奶龙基金」（customer_service_rules
的防诈骗/转人工话术、risk_agent 与 risk_analysis_service 的系统提示词）、前端全站
「南方财富」、闲聊提示词与知识素材「南方科技」。docs/36 已把它登记为"上报项目方后
待定"，现按项目方决定统一为「南方财富」。

改动：
- app/core/customer_service_rules.py：P0 防诈骗话术与 P2 转人工话术里的品牌名
- app/service/agent/implementations/customer_service.py：COMPANY 常量，
  以及那处引用实测样本的注释（改为不绑定具体品牌名，免得下次改名又过时）
- app/service/agent/implementations/risk_agent.py：docstring、自我介绍、system prompt
- app/service/risk_analysis_service.py：SYSTEM_PROMPT
- app/worker/risk_scan_scheduler.py：--help 描述
- app/static/index.html（旧联调页 4 处）、portal/employee-risk/dashboard/index.html
- tests/unit/api/test_customer_service_test_page.py：同步断言（它断言的正是页面里的品牌名）
- tools/publish_chitchat_prompt.py：SYSTEM_PROMPT 改品牌；并修掉"存在即跳过"的检查
  —— 原来只判当前版本有没有这一行，于是改了文案也发不出去（脚本打印"无需发布"直接
  退出），没有任何提示。改为比对 system_prompt/user_prompt_template 内容。

闲聊提示词已重发为 release 308 / v5，生效内容为"你是南方财富的智能客服助手…"。

刻意未动：
- fin_product.fund_manager = "南方基金" —— 它被 market_quote_sync_service 与
  product_history_sync_service 当过滤条件使用，改名会让同步链路查不到产品
- knowledge_search_service.py 注释里引用的知识库实际标题「南方科技有限公司…」
- docs/客服docs 下的历史素材与 docs/ 下的过程记录（属历史留痕）

⚠️ Milvus 里的知识条目仍写「奶龙基金」（RAG-*/NF-*）与「南方科技」（PROD-*），
属知识数据，需重灌才能统一；本轮不动。

同时：
- docs/40 把品牌条目标为已处理，并补上知识库缺口的现状
- 新增 docs/42-场内基金知识条目草稿.md：按 fin_product 的 20 只产品生成，
  含通用交易规则与产品清单；费率等缺失字段一律标"以交易页面为准"，未编造数字。
  **该文件是草稿，未入库**，待审核后走 POST /api/v1/knowledge/documents 灌库。
 2026-09-13 19:17:56 +08:00
张胜宇 e38ece32bf 前端提交 2026-09-13 15:56:54 +08:00