AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
381 Commits 12 Branches 0 Tags
01e4e6a68792b52fe5cba88810106f12db542e24
Commit Graph
100 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
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 9490e5043b 记忆系统演示文档 + 修掉两处会让演示断链的真问题 
## 新增：docs/演示用/记忆系统演示文档-2026-09-14.md
按"操作 → 看到什么 → 这体现什么"写，五个场景（探针看存储 / 记住一件事 / 谁能读谁读不到 /
画像版本与投影 / 停 Worker），每个场景配可复现命令与**实测输出**，另附建议顺序与时长、
六条问答话术、演示前自检清单、受控信号词表摘录。

配套两个新工具（都已实跑）：
- `tools/memory_demo_chain.py`：一键走完"客户说 → 候选 → 客户确认 → 管理员批准 →
  记忆与画像自动收敛"，打印演示前后对比（实测 2 秒收敛）。
- `tools/memory_recall_demo.py`：同一客户换六个身份召回，当场看出"客户只读自己 /
  员工要权限码+归属 / 运营读不到 / 管理员有权限码但没归属也读不到"。

## 修掉两处会让演示当场断链的问题（都是真机复现的）

1. **候选批准后画像字段不收敛**
   `CustomerProfileCandidateService._promote` 只写画像快照、**不投**
   `profile.rebuild_requested`，而 `user_facts` 与画像字段是 `ProfileAssemblyService`
   的重建链路写的。后果：批准后记忆变 active、快照版本 +1，但**画像字段停在旧值**
   （客户说"三年以内"，画像里还是"十年以上"），要等一次无关的重建才收敛 ——
   而"客户说完 → 批准 → 画像变了"正是演示主线。
   现补一条重建事件（走事件而不是就地重建：本方法所在事务还没提交，
   另开 session 看不到刚写入的记忆）。

2. **画像快照的唯一键从来没起作用，而且埋雷**
   `uk_profile_snapshot_current` 建在列 `current_customer_id` 上（不是 `is_current`），
   但 `ProfileAssemblyService._write_snapshot` 旧行只置 `is_current=False`（不清该列）、
   新行**不写**该列（实测 13 行该列全 NULL）。
   后果：只要客户**先被重建过一次**，旧 current 行仍占着 `current_customer_id=9001`，
   下一次"批准画像候选"就会撞 `Duplicate entry '9001' for key
   uk_profile_snapshot_current` → **整次批准 500**（本次实测踩到）。
   现按唯一键的真实语义写：清旧行的该列、新行显式写客户号。
   （`ProfileGenerationService` / 候选路径本来就是这么写的，只有这一处没对齐。）

## 守卫
新增 `tests/integration/test_profile_snapshot_current_invariant_mysql.py`：
按真实顺序"先重建再批准候选"，断言 ① 只有一条 current 且它占着唯一键、
② 历史版本已归还该列、③ 批准不再 500、④ 批准投出了重建事件。
修复前这条用例会在第 ② 步失败。

## 验证
- `pytest tests/unit tests/contract` → 1490 passed, 2 skipped, 0 failed
- 新增集成用例通过；真机实测演示主线：候选 → verified → active → **2 秒内**
  `user_facts` 与 `fin_customer_profile.investment_horizon` 都变成新值
- `mypy tools/memory_demo_chain.py tools/memory_recall_demo.py` → 0 错；ruff 全绿

## 文档
`docs/44-演示流程.md`：配套文档清单与"记忆链路"备选场景都指向新演示文档。
 2026-09-15 00:55:44 +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 ed59e93b53 管理员配置发布：点「内容」后在视口里看不到变化（面板渲染在 20 条列表下方），改为渲染后滚动定位 + 标题用发布编号 + 空列表给显式空态 2026-09-15 00:21:24 +08:00
lzf_0626 0e68271a81 docs/44：把一份被移动过的引用改成不依赖目录（代码库全面审查报告） 2026-09-15 00:16:56 +08:00
lzf_0626 449d078a02 新增《记忆架构与底座 Worker 工作流程 · 大白话版》 
两部分，各讲一件事，接口处互相对齐：

第一部分 · 记忆架构
- 四个存储的分工：MySQL 是唯一账本（memory_unit / memory_evidence / memory_conflict /
  user_facts / fin_customer_profile / profile_snapshots），Neo4j 存关系、Milvus 存向量
  （集合 user_long_term_memory_v1 是代码常量）、Redis 只做加速（召回热缓存 300 秒 /
  客服短期会话 30 分钟滑动）
- 一条记忆的一生七步；为什么画像重建要绕事件；investor_type 只来自风险测评
- 客服走"候选画像"两把钥匙（客户确认 verified → 管理员批准 active）；不抽记忆的三种情形
- 召回三路（MySQL 结构化 + Milvus 语义 0.7 权重 + Redis 热缓存），没有"图召回"这一路；
  当前只有风控 Agent 消费召回结果
- 可读范围一个文件说了算（客户只自己；员工要 memory:read:customer 且归属；上限 10）
- 失效/删除链路与"清不掉就如实留痕"
- 实测表行数 + 一条要如实说明的观察：9001 的向量在 Milvus 里，但 memory_sync_outbox
  当前没有它的行，不能据此断言投影链路正常
- 八条已知遗留逐条核实（episode 幂等哈希不覆盖记忆内容、投顾两处不发 memory_sources、
  风控 system 上下文召回恒空、current_customer_id 从不写入致唯一键形同虚设、user_facts
  无唯一键、两个未接线组件、文档过期）

第二部分 · 底座 Worker
- 三段式（受理 202 → 排队 → Worker 执行）与"不跑就没有任何报错"
- 一轮 run_once 的四件事与顺序、单轮上限、每 30 轮才做的片段聚合、失败隔离
- 五条工作线逐个讲：Agent 运行（状态机/领取加锁/租约 60s+心跳 20s/重试 3 次/取消收口/
  执行前重新解析身份）、领域事件（12 类、幂等两层、重试 5 次进死信、退避公式）、
  记忆与画像投影、会话片段与知识向量、场外收件（四道闸门 + 游标租约 + blocked）
- 显式降级清单（不伪造成功）
- 怎么判断它活着/卡住/积压：看表 + 看日志关键词 + 当前死信实况（570 条 dead 的构成）
- 三个常被搞错的边界（风控定时扫描是独立进程且默认关；AgentRunWorker 生产未用；
  GraphProjectionWorker / ProjectionReconciliationService 未接线）+ 一页速查
 2026-09-15 00:16:35 +08:00
lzf_0626 42a330c4c9 docs/44 演示流程按 2026-09-14 实测同步：今日盈亏可讲、投顾自助审核、管理员八页签、权限数与已知空数据 2026-09-15 00:14:20 +08:00
lzf_0626 776b504ee6 新增《全平台功能流程 · 大白话版》：从登入讲到六门户全部流程 
- 读者是第一次接触平台的人：全文不用"链路/编排/收敛"这类词，讲"点一下之后发生了什么"
- 结构：三个角色（浏览器/API/Worker）→ 访客 → 登入与角色落地 → 客户 8 页 → 风控 →
  投顾 → 运营三条线 → 管理员 8 个页签 → 底座 9 件事 → 一条主线时间线 → 常见疑问 → 速查
- 每节都标了文件/接口依据，并写清"已知空数据"与"已知小偏差"（通知类型下拉未接线、
  NL2SQL 错误信息列恒为 --、推广页无 form 导致 required 不生效、场外默认 dry-run 等）
- 顺带纠正三处易误传的说法：幂等键只防"同一次请求重发"（连点仍会下两笔）、
  客户侧前端权限门是装饰性的（后端 403 才是拦截）、FM-03 熔断目前只在前端拦
- 风控演示数据那 6 行 RISKDEMO 场外申购/赎回：代码注释与今日盈亏说明改口径为
  "风控异常交易演示的触发材料，刻意保留"，不再当脏数据；今日盈亏按 transaction_type 语义排除它们
 2026-09-15 00:10:23 +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 48b43cfad5 投顾推荐空候选池：把"为什么没有产品"讲清楚，而不是一句"没有通过校验的产品" 
"当前没有通过适当性与证据校验的产品。" 这句话对运营毫无信息量：既不知道是谁的问题，
也不知道下一步该做什么。现在空态会说明证据门口径（每个产品都要求 ①销售机构的**已验证**
适当性证据 ②基金合同快照，且都要带可核查的来源链接与文档 sha256，缺一即整只排除，
fail closed），并给出本轮候选/入选/排除的数量，以及两条可执行路径：

- 真实方案：先由产品治理线导入适当性证据与合同快照
  （	ools/import_product_governance_reference.py，CSV 需带 source_url 与 document_sha256）；
- 呈现效果：切到页面顶部「本地演示数据」，那里的方案会标注"规则模拟、不构成真实推荐"。

同时说明本环境为空的原因：dvisor_product_suitability_reference 与
dvisor_product_contract_snapshot **均为 0 行**（26 个上市产品因此全部被证据门排除，
candidate_count=0，所以连"排除原因"也没有可展示的条目）。
 2026-09-14 23:34:36 +08:00
lzf_0626 467d2b5169 投顾可自助审核/发布自己生成的推荐方案（原先只有管理员能推进草案） 
## 现象与根因

投顾工作台生成推荐方案后，草案停在 `pending_review` 且投顾无法推进：

- 服务层 `review` / `publish` 都带 **`admin=True` 角色闸门**
  （`product_recommendation_service.py:286/317`），即使投顾角色**已经持有**
  `product-recommendation:review` / `:publish` 两个权限码也一律 403；
- 审核/发布端点只注册在 **admin 路由**下（`/api/v1/admin/advisor/...`），
  投顾侧根本没有对应入口；
- 投顾工作台也没有审核/发布按钮（`published-module.js` 原注释即写着
  "发布动作要求管理员，投顾侧只读"）。

于是业务上"让投顾自己审核"完全做不到，必须切管理员账号。

## 修法（三处配套，安全边界保留）

1. `app/service/product_recommendation_service.py`
   - `review` / `publish` 去掉 `admin=True`，**只按权限码判定**
     （`product-recommendation:review` / `:publish`，目前仅 advisor 与 admin 持有）；
   - `reviewer_user_id` 照旧如实落库，审计可追；
   - 注释写明：若要回到"四眼原则/管理员专属"，把 `admin=True` 加回即可。
2. `app/api/controllers/recommendations.py`
   - 新增投顾侧路由 `POST /api/v1/advisor/recommendations/{id}/reviews`
     与 `.../publications`（与 admin 路由调用同一服务方法）。
3. 前端
   - `common/api-client.js`：注册 `ADVISOR_REVIEW_RECOMMENDATION` /
     `ADVISOR_PUBLISH_RECOMMENDATION`；
   - `employee-advisor/dashboard/actions-module.js`：结果区在拿到 `content_id` 后
     给出「审核通过 / 驳回 / 发布给客户」按钮（结果区是 `innerHTML` 重建的，
     所以每次渲染后重新绑定）；审核通过后就地换成「发布给客户」；
   - `published-module.js`：监听 `advisor:published-refresh`，发布成功后列表自动刷新。

## 未放宽的部分（有意保留）

- **管理面复核队列** `GET /api/v1/admin/advisor/pending-contents` 仍为
  `admin=True` 专属 —— `tests/integration/test_advisor_review_queue_mysql.py`
  里"投顾读不到该队列"的断言**未改动**；
- 客户/风控/运营角色不持有这两个权限码，因此不受影响。

## 验证（真实 HTTP，9020 身份）

```
① 生成推荐方案（客户 9001）→ content_id=19, pending_review
② 投顾自助审核通过          → HTTP 200 status=approved     （改前 403）
③ 投顾自助发布              → HTTP 200 status=published
④ 已发布列表                → 含 id=19 ✅
```

新增回归测试 `test_advisor_can_review_and_publish_own_recommendation`
（客户缺测评/目标时 `pytest.skip` 并说明是数据前置，不误判为权限失败）。

## 门禁

- `pytest tests/unit tests/contract` → 1458 passed；
- `pytest tests/integration` → 111 passed + 1 例
  `test_worker_runtime_mysql::...repeat[False]` 失败，**经复跑确认是 AGENTS.md 记载的
  "常驻 Worker 抢队列"，停掉常驻 Worker 后该用例 2 passed**，与本次改动无关；
- `ruff` 干净；三个 JS 文件 `node --check` 通过。
 2026-09-14 23:27:44 +08:00
lzf_0626 5da2fb5790 投顾代客三项的权限码缺失：整片 403（与 9057-9059 同一个坑的第二批） 
## 现象

投顾工作台（`advisor_t`，9020）一选客户就整片失败，页面只显示
「请求失败，请检查权限或稍后重试」。API 访问日志给出真相：

```
POST /api/v1/advisor/recommendations     403
POST /api/v1/advisor/asset-allocation    403
POST /api/v1/advisor/portfolio-analysis  403
GET  /api/v1/advisor/recommendations/published  200   ← 只有它不需要代客权限
```

## 根因：三个 `*:customer` 权限码在库里根本不存在

三个服务在"代客"（`customer_id != context.user_id`）时要求的是**动态拼出来的
`:customer` 变体**：

- `product_recommendation_service.py:71` → `product-recommendation:generate:customer`
- `asset_allocation_service.py:57`       → `asset-allocation:generate:customer`
- `portfolio_analysis_service.py:46`     → `portfolio-analysis:read:customer`

而 `sys_permission` 里 `:customer` 后缀**只有 4 个**（`memory:read:customer`、
`investment-goal:{read,write,confirm}:customer`）—— 这三个从来没登记过。
`AuthorizationService.require()` 第一步就查不到该码 ⇒ 直接 403。

这与种子里 **9057-9059 的注释是同一个坑**（"动态拼出来的权限码，对账工具抓不到字面量，
于是投顾查/建/确认客户目标全部 403"），前人修了 investment-goal 那三个，这三个漏了。

## 修法（按仓库纪律：种子定义权限码 → grant 脚本绑定角色）

1. `tools/seed_test_rbac.py`：新增 **9066-9068** 三个码，`data_scope=own_customers`
   （`require_customer_scope` 只放行 `all`，或 `own_customers` 且客户确在
   `context.customer_ids` = 归属客户内 —— 这正是投顾该有的最小权限），
   并写明三处调用点，避免后人再漏；
2. `tools/grant_advisor_role.py`：把三个码加入 `ADVISOR_GRANTED_CODES`
   （admin 因 `ADMIN_PERMISSIONS = 全部种子权限` 自动获得）。

已执行：`seed_test_rbac.py` → `grant_advisor_role.py`
（advisor 新增 3 项，共 31 项；admin 62 项）。

## 验证（真实 HTTP，9020 身份）

| 客户 | 推荐方案 | 资产配置 | 组合分析 |
|---|---|---|---|
| 9101（演示客户） | 200 `profile_required` | 200 `profile_required` | 200 `no_positions` |
| **9001（真实客户）** | **200 已生成方案**（content_id=5, pending_review） | **200 ready**（含配置比例） | **200 ready**（7 个持仓，市值 10698.60） |

**403 全部消失**；对真实客户三项均返回真实结果。

## 同时补的归属数据

`sys_customer_assignment` 原有 9020→9001 一行；工作台把演示客户的 id
（9101-9104）当真实 `customer_id` 发给后端，而 `own_customers` 要求客户在投顾名下，
因此用 `tools/assign_customer_scope.py` 补了 4 行（9020 → 9101/9102/9103/9104），
回验 `customer_ids = ('9001','9101','9102','9103','9104')`。

## 仍未解决（属**数据**缺口，不是权限）

1. **9101-9104 在库里没有任何数据**：`advisor-config.js:126` 注释指向的
   `_seed_demo_customers.py` 在仓库、git 历史与桌面上**都不存在**（从未提交），
   所以这四位没有账号 / 风险测评 / 投资目标 / 持仓 —— 只能返回 `profile_required`。
2. **推荐候选恒为 0**：`AdvisorProductRepository.authoritative_tradable_products`
   要求**已验证**的适当性证据与合同快照（`review_status='verified'` 且
   `source_url` / `document_sha256` 非空，fail closed），而
   `advisor_product_suitability_reference` / `advisor_product_contract_snapshot`
   均为 0 行。这需要产品治理线提供可核查证据，**不应伪造**。

## 门禁

`tools/check_rbac_seed_consistency.py` 通过（种子内 id 唯一、各 grant 脚本与种子逐条一致）；
`pytest tests/unit tests/contract` 全绿。
 2026-09-14 22:56:42 +08:00
lzf_0626 d8e47df20c 推介材料：勾选「展示排名」后无法填写来源 → 必然合规阻断（死锁）的修复 
## 现象（你的截图）

任务 `PM-20260914-0007` 的合规检查结果为：

```
业绩排名来源不满足要求
补充三年期以上公开评价数据来源 · block
```

输入快照里的实证：

```json
ranking = {"enabled": true, "ranking_text": null, "public_source": null,
           "institution_name": null, "evaluation_period_years": null}
```

## 根因：勾选框有了，填来源的地方没有

`promotion_compliance.py:82-91` 的规则是：

```python
if ranking.get("enabled"):
    years = _years(ranking.get("evaluation_period_years"))
    if years < 3 or not ranking.get("institution_name") or not ranking.get("public_source"):
        → block "performance.ranking_source_invalid"
```

而前端**只有**一个复选框 `performance_info.ranking.enabled`：

- 表单里**没有** `institution_name` / `public_source` / `evaluation_period_years` /
  `ranking_text` 四个输入（实测枚举全部 `data-promo-field` 只有那一个 ranking 字段）；
- `inputsPayload()` 也只提交 `ranking: { enabled }`。

⇒ 运营一旦勾选「展示排名」，来源四项永远是 null，规则必然阻断，
而界面上**无处可填** —— 要么取消勾选，要么永远生成不了。这是**死锁**，不是数据问题。

## 修法（前后端契约字段本就有，只补界面与提交）

1. `promotion/index.html`：在展示选项上方新增一组输入（`data-ranking-source`）：
   评价期间（年，需 ≥3）/ 评价机构 / 公开来源 / 排名文本；
2. `promotion/promotion.js`：`inputsPayload()` 的 `ranking` 补上这四个字段
   （契约 `RankingInfo` 本就定义了 `institution_name` / `evaluation_period_years`
   / `ranking_text` / `public_source`，`evaluation_period_years` 是字符串，如 "3年"）。

## 验证

- 用**真实任务 0007 的输入**跑 `PromotionComplianceChecker.check_inputs()`：
  - 现状：3 条阻断（`history_short` + **`ranking_source_invalid`** + `data_attachment_missing`）；
  - 把来源填全后：**`ranking_source_invalid` 消失**（其余两条由"未上传业绩文件"引起，上传即解）；
  - 反例：评价期间改成 2 年 → 仍拦；3 年但缺公开来源 → 仍拦（规则没有被放松）；
- 从源文件抽出 `inputsPayload()` 用桩真实调用：四个来源字段都进 payload；未勾选时 `enabled=false`；
- `index.html` 标签净增 +1 `<div>` / +1 `</div>`（结构平衡）；`node --check` 通过；
- `pytest tests/unit tests/contract` → 1458 passed, 2 skipped, 0 failed。

## 附带说明

你看到的是"2 条"是因为**点了两次生成**：每次生成都会把该次的 findings 落库，
页面"读取合规结果"会把历史记录一并列出（不是一次调用重复产出）。
 2026-09-14 22:45:57 +08:00
lzf_0626 e6147bb6ec 推介材料：中文文件名让上传请求头非法 → 两个附件都"网络连接失败"（服务端一条记录都没有） 
## 现象

上传 `业绩数据1.xlsx` 与 `基金经理1号王建龙.png`（扩展名都在白名单内）：
页面提示 `业绩数据文件上传失败：网络连接失败；基金经理照片上传失败：网络连接失败`，
而库里、盘上、审计里**都没有任何上传痕迹**。

## 排查与根因

1. API 是健康的（`/portal/` 200、129 条路由在、8000 正常监听）；
2. `api_client` 里 "网络连接失败" 的触发条件是 **`fetch` 抛了非超时的异常**（超时会显示"请求超时"）；
3. **`api_request_receipt` 里没有任何上传记录** —— 同一时段的建任务/存资料/生成三条都有 receipt
   （连"生成未通过合规校验"这种业务失败也落 receipt）⇒ **上传请求根本没到应用**；
4. `promotion.js` 给上传传的幂等键是 `` `${taskNo}-${type}-${file.name}-${file.size}` `` ——
   **把中文文件名拼进了 HTTP 头 `Idempotency-Key`**；
5. HTTP 头值只能由 ≤0xFF 的码点组成：实测同一请求用标准客户端发送时抛
   `UnicodeEncodeError: 'ascii' codec can't encode characters in position 34-45`；
   浏览器更严格，`fetch` 在**构造请求头时直接抛 `TypeError`**，请求一个字节都没发出去，
   却被 `api-client.js` 的 catch 包装成"网络连接失败"——**"参数非法"伪装成了"网络故障"**。
6. 反证：换成纯 ASCII 的幂等键，同两个文件、同一端点**立刻 200 成功**
   （attachment_id=67/68，`performance_summary` 正常返回）。

## 修法

1. `employee-operations/promotion/promotion.js`
   - 新增 `asciiOnly()` / `uploadKey()`：幂等键改为 `任务号-类型-字节数-最后修改时间`
     （**刻意不用文件名** —— 中文名即非法头值），纯 ASCII 且同一文件重传得到同一键（幂等回放）；
2. `common/api-client.js`
   - 对幂等键做**前置校验**（平台规范：16-128 位可打印 ASCII），不满足时抛
     `IDEMPOTENCY_KEY_INVALID` 并**带上端点与键值** —— 下一次这类问题 10 秒可定位，
     不必再从"网络故障"倒推。

## 验证

- 从源文件抽出 `asciiOnly`/`uploadKey` 用 Node 断言：中文文件名 → 键全 ASCII 且通过校验、
  同一文件两次同键、不同文件不同键、任务号含中文也被转义、旧写法会被拦下（全部通过）；
- `node --check` 两个文件通过；
- 真实 HTTP（带令牌、真实文件）验证：ASCII 键 → **HTTP 200**，中文键 → 客户端抛 `UnicodeEncodeError`；
- 该账号的两个附件已成功入库（id=67/68），业绩摘要 = `as_of_date 2025-12-31 /
  history_months 23 / product_return 17.1% / max_drawdown -1.15%`；
- `pytest tests/unit tests/contract` 全绿。
 2026-09-14 22:36:49 +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 5b97475950 场外前端：单据核对区显示不出字段 —— 邮件详情的单据只是摘要，须与识别接口按 task_id 合并 
## 现象

"单据核对与运营动作"里的单据信息全是 `--`：

```
20260914-001-A01
subscription · -- · --
申请日期 --        申购金额 / 赎回份额 -- / --
机构     --        基金代码            --
```

而 OCR 识别字段里这些值都**有**（基金代码 15911 / 申请日期 2026-09-11 /
申购金额 5000.00 / 机构 星澜财富服务中心）。所以不是"没保存"，是**渲染时取错了数据源**。

## 根因：同一个单据，两个接口给的不是同一份字段

| 接口 | `attachments[].documents[]` 的字段 |
|---|---|
| `GET /mails/{id}`（`_mail_detail`） | **只有摘要 4 个键**：`task_id` / `document_type` / `status` / `operator_decision` |
| `GET /mails/{id}/recognition-fields`（`_recognition_payload`） | **全部标准化字段**：`fund_code` / `fund_name` / `application_no` / `application_date` / `agency` / `subscription_amount_yuan` … |

`renderDocuments()` 渲染单据 kv 用的是 `state.documents`，而 `loadMail()` 只从
**邮件详情**那一份构建它 ⇒ 标准化字段根本不在对象里，只能显示 `--`。

前端其实**已经有** `syncDocumentsFromRecognition()` 想做这件事，但 `loadMail()` 里
是「先 `syncDocumentsFromRecognition(...)`、紧接着又用邮件详情重建 `state.documents`」
—— 合并结果被后一行覆盖掉了（这也是保存识别字段后那次同步没生效的原因）。

## 修法

1. `loadMail()`：构建完 `state.documents`（邮件侧摘要）之后**再调用一次**
   `syncDocumentsFromRecognition(state.recognition)`，把识别侧的标准字段合并进来；
2. `syncDocumentsFromRecognition()` 由"整段替换"改为**逐条按 `task_id` 合并**：
   - 两侧都有 → 识别侧字段优先，摘要里独有的键（`status` / `operator_decision`）保留；
   - 只有摘要侧 → 原样保留（不因为识别接口没提到就丢单据）；
   - 只有识别侧 → 也补进来（例如刚生成、摘要还没刷新）；
   - 识别接口无 attachments（请求失败等）→ 早退，**不清空**已有单据。

## 验证

`node --check offsite.js` 通过；并用 Node **从源文件抽出该函数**（不另抄一份逻辑）灌入
线上两个接口的真实载荷形态，6+4+3+1 项断言全部通过：

- 摘要 + 识别侧全字段 → `fund_code=15911` / `application_date=2026-09-11` /
  `agency=星澜财富服务中心` / `subscription_amount_yuan=5000.0000`，且
  `status=planned`、`operator_decision=未处理` 未被覆盖，`attachment_id` 已补上；
- 识别接口返回空 → 邮件侧摘要仍在；
- 邮件侧独有单据保留、识别侧独有单据出现。

前端相关测试：`tests/unit/api/test_portal_frontend.py` → 45 passed, 1 failed
（仍是组员在改的投顾页，与本次无关）；`pytest tests/unit/api -k "offsite or operations"`
→ 1 passed。

## 说明：为什么没改后端

也可以让 `_mail_detail` 直接带上标准化字段，但那会改动已被文档化的接口载荷形状；
而前端本来就有合并函数、意图明确（`save-ocr` 路径早就在调用它），
因此按"恢复原有意图 + 按 task_id 正确合并"来修，零接口契约风险。
 2026-09-14 22:23:49 +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 292acd2e2c 新增「补客户归属」工具，并订正一处因迁移而过期的注释 
## 新增 tools/assign_customer_scope.py

`sys_customer_assignment` 是**全平台**的"谁负责哪个客户"口径，不是记忆私有：
记忆召回（app/core/memory_scope.py）、`memory:read:customer` /
`investment-goal:*:customer` 的 `own_customers` 授权判定、投顾"已发布方案"的可见客户
都读它。所以"给某人补归属"是一句**授权动作**，不该用一次性 SQL 随手写进库。

本工具把它做成幂等、可复跑、默认只预览（--apply 才写），并**当场用真实身份链路回验**
（IdentityRepository.load_context → customer_memory_scope），还会在目标账号缺少
`memory:read:customer` 时明确提示"归属关系不等于授权"。

内置两个已踩过的坑：
1. `assigned_at` 不能写"当前时间" —— MySQL DATETIME(0) 四舍五入到秒可能落进未来，
   于是 `assigned_at <= now` 判定"尚未生效"，归属拿不到**且不报错**；统一往前留 5 秒；
2. `employee_role` 是 NOT NULL 且参与唯一键 `(customer_id, employee_role)`，
   故从 RBAC 反查员工真实角色码，不靠手填。

`id` 在 9901+ 段分配（避开业务号段）。另外修掉一个写入期 bug：校验查询已经开了隐式事务，
再 `async with session.begin()` 会抛 `InvalidRequestError: A transaction is already begun`。

用法：
    python tools/assign_customer_scope.py                 # 预览：9002(风控) ← 9001
    python tools/assign_customer_scope.py --apply
    python tools/assign_customer_scope.py --show          # 只读：每个员工的实际可见范围

## 订正 tools/seed_advisor_demo.py 的过期注释

该文件原写"`sys_customer_assignment.id` 没有自增（EXTRA 为空），必须自己给" ——
这条**已被 20260914_baseline_auto_increment 迁移改变**（实测 EXTRA 现为 auto_increment）。
注释改为记录现状，并说明仍然显式给 id 的理由（保持号段约定 + 让种子可复现，
自增会让同一份种子在不同环境落到不同 id）。

## 本轮实际执行

- 补入一行归属：员工 9002（risk_operator）→ 客户 9001（id=9902，幂等复跑正确跳过）；
- 回验：风控 9002 的记忆可读范围从 `()` 变为 `(9001,)`，召回从 0 条变为 2 条；
  投顾 9020 仍 2 条；
- 该动作**只影响记忆召回**：9002 其余权限都是 `data_scope='all'`，
  `scope_from_context()` 见 all 直接放行、不看 customer_ids。
 2026-09-14 21:46: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 89b15f32cb 忽略 .env 自动备份：它含真实密钥却不在 .gitignore 里，git add -A 会把它带进版本库 2026-09-14 21:33:48 +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 2c5fe9cdef 把风控扫描演示数据接进一键准备（第 12 步），并让编排支持给步骤传参 
## 改动（`tools/seed_demo_data.py`）

1. **`STEPS` 增加第四个字段「额外命令行参数」**。这不是可有可无的装饰：
   `seed_risk_demo_data.py` **不带参数时只打印计划、不连数据库**（默认是干跑模式），
   不给它传 `--apply` 的话，接进编排只会打印一句"确认无误后使用 --apply 正式写入"
   然后退出码 0 —— **看起来像成功，实际什么都没准备**。这类"假成功"最难查，
   所以参数必须能传得进去。
2. **新增第 12 步「风控扫描演示数据」**，带 `--apply --dry-run-scan`：先写入上游
   业务数据，再跑一次规则干跑并把结果回滚。净效果是「写入上游数据 + 顺带验证
   5 个场景都真的命中预期规则」。
3. `run_step` / `--list` / 主循环相应支持第四项；执行时把参数**打印出来**，
   这样手跑时一眼能看出这一步到底会不会落库。

## 为什么放第 12 步，而不是插在「风控预警样本」旁边

避免**改动后续步骤的编号**。文档与肌肉记忆里已经有 `--only 4,10`、`--from 4`
这类用法，插队会让它们全部错位。而且它本身是独立号段（客户 12001-12005、
产品 159991-159995），放最后不影响任何既有步骤。

## 第 6 步与第 12 步不是重复（docstring 已写明）

- 第 6 步 `seed_risk_alert_demo_data.py`：**直接摆好**三条现成预警，
  保证风控页面一打开就有东西可看；
- 第 12 步 `seed_risk_demo_data.py`：**只造上游**，刻意不写 `fin_risk_alert`，
  让风控扫描器按规则生成 —— 演示覆盖的是**规则 → 证据 → 通知**完整链路，
  而不是"预先摆好的假预警"。

## 实测

- `--list` -> **12 步**，第 12 步末尾显示 `[--apply --dry-run-scan]`
- `--only 12 --dry-run` -> 只打印、不执行（并且打印出了参数）
- `--only 12` -> **真跑通**，退出码 0：

      [12/12] 风控扫描演示数据  用时 3.8s  退出码 0
      [命中] 客户 12001：RW-003 (高)
      [命中] 客户 12002：RW-007 (高)
      [命中] 客户 12003：RW-007 (中)
      [命中] 客户 12004：RW-012 (高)
      [命中] 客户 12005：RW-015、RW-018 (低)

- `ruff check tools/seed_demo_data.py` -> All checks passed
 2026-09-14 20:50:55 +08:00
lzf_0626 e00c4ad51d 风控演示数据脚本：造上游业务数据，让风控扫描器自己生成预警 
## 来源

组员通过腾讯会议发来的 `seed_risk_demo_data.py`，按约定放入 `tools/`。
**脚本内容是组员写的**，我只做了两件事：放进仓库、把 docstring 里的用法示例
统一成实际文件名（组员原文写的是 `seed_risk_scan_demo_data.py`，与文件名不符，
已改成 `tools/seed_risk_demo_data.py`），**未改动任何逻辑**。

## 它做什么

固定号段：客户 **12001–12005**、产品 **159991–159995**（独立号段，不覆盖人工数据
与其他演示数据）。写入客户 / 画像 / 产品 / 账户 / 持仓 / 交易 / 资金流水 / 登录 /
工单，**刻意不写 `fin_risk_alert` 与 `fin_risk_notification`** —— 预警必须由风控
扫描器按规则生成，这样演示才能真实覆盖规则、证据、通知三条链路。

五个场景各自瞄准一条规则：

| 客户 | 场景 | 预期规则 |
|---|---|---|
| 12001 | 大额快进快出（3 天内入金 80 万后赎回 75 万，比例 93.75%） | RW-003 |
| 12002 | 高风险适当性错配（缺风险揭示 + 二次确认） | RW-007 |
| 12003 | 中风险适当性错配（等级差 1 且缺风险揭示） | RW-007 |
| 12004 | 72 岁客户赎回 75 万，达历史均值 3 倍且用非常用设备 | RW-012 |
| 12005 | 凌晨 2:15 小额自动定投（关联有效工单，预期合并预警） | RW-015、RW-018 |

模式：`--check`（只读核对）、默认 `--dry-run`（只打印计划、**不连数据库**）、
`--apply`（写入）、`--dry-run-scan`（跑规则引擎后回滚）。

## 我跑了什么、核到什么

按约定的命令 `--apply --dry-run-scan`：

    [命中] 客户 12001：RW-003 (高)
    [命中] 客户 12002：RW-007 (高)
    [命中] 客户 12003：RW-007 (中)
    [命中] 客户 12004：RW-012 (高)
    [命中] 客户 12005：RW-015、RW-018 (低)
    规则干跑完成，共命中 5 条演示预警，已回滚，不会写库。

**"已回滚"这句话我没有只信它的打印**，而是直接查了库：

- 上游数据确实写入：客户 5 / 产品 5 / 账户 5 / 持仓 5 / 委托 6 / 成交 6 /
  资金流水 1 / 登录 1 / 工单 3，演示产品行情 5 行（`source=custom_seed`）；
- **`fin_risk_alert` = 0、`fin_risk_notification` = 0** —— 回滚确实生效。

跑之前还先确认了它承诺回滚是**成立**的：`RiskRuleEngine.refresh_alerts()`
（`risk_scan_service.py:101`）到 565 行之间**没有 `commit()`**，全文件仅有的
`commit/rollback` 在 `:566-568`，属于另一个方法（正式扫描 `scan()`）。
否则 `dry_run_scan` 的 `session.rollback()` 根本回滚不掉，那就是"假干跑"。

## 复用与兼容

脚本 import 了 `tools/seed_custom_holdings.py` 的 `ensure_user` / `ensure_account` /
`ensure_holding` / `ensure_product` / `ensure_nav_history` / `ensure_market_price`，
我逐个核对了签名，**全部匹配**（组员看过那个脚本）。

它自己的 `_next_id` 用 `SELECT MAX(id)+1` 发号：单线程脚本里没问题，且
`sys_user` 与 `fin_product` 本来就没有 AUTO_INCREMENT（被外键引用，迁移
`20260914_baseline_auto_increment` 已说明为何排除）。**这不是缺陷**，不改。

## 实测

- `ruff check tools/seed_risk_demo_data.py` -> All checks passed
- `--apply --dry-run-scan` -> 5/5 场景命中预期规则，退出码 0
- `pytest tests/unit tests/contract` -> **1428 passed, 2 skipped, 1 failed**
  （那个失败是投顾工作台页面被替换所致，与本次无关）
 2026-09-14 20:48:18 +08:00
lzf_0626 e85e958389 排障表补一条：所有页面一起卡 → Milvus 抖动 + 同步调用阻塞事件循环 
## 为什么补这一条

把审查报告的 P1–P3 共 45 项按 8 个演示场景筛完，**"会砸演示"的是 0 条**
（P0 四条已全修）。剩下的分两类：37 项演示路径根本走不到，8 项是"边缘"
（平时无感、特定条件才暴露）。

这 8 项里只有 **P1-2** 属于"一处慢、全平台卡"：检索层用的是**同步** Milvus 客户端，
单次 `search` 卡 3 秒会让整个 API 进程停摆 3 秒，连 Worker 心跳一起停。

它同时也是**最容易被误判**的一个 —— 现象是"客服、风控、看板一起变慢"，
而排障表原有的 6 条全是**单点**故障（503 行情 / Worker 没起 / 浏览器缓存 /
知识库没同步 / MySQL 没起 / 风控样本用完），**没有一条对得上"全场同时变慢"**。
没有这一条，现场会往"服务挂了"的方向查，而它其实是外部依赖抖动、不需要改代码、
也不需要重启。

所以这条的价值不在改代码，而在**把一个边缘隐患变成一眼能认出的现象**：
演示版本选择不修 P1-2（Milvus 正常时完全无感），代价就是必须知道它长什么样。

## 依据（都是会话内实际核过的）

- 客服链路确认：`app/service/knowledge_tool.py:29` 的 `search_knowledge` 工具
  → `get_knowledge_search_service().search(...)`；
  而 `knowledge_search_service.py:207-213 / 224 / 229` 调的是**同步** `MilvusClient`
  （`app/infrastructure/vector_memory.py` 的 `def search(...)`，非 `async def`）。
- 对照：项目在其它 10+ 处已用 `asyncio.to_thread`（如
  `app/infrastructure/fund_market_adapter.py:273/382`），说明异步规范已建立，
  这 4 处是遗漏 —— 但**不是演示阻塞项**，本次不改。
- "风控日报会不会砸"（P1-6，报告标了【确定】）也核过了：`_distribution` 的
  `counts` 键是字段**值**，两个调用点用的 `risk_level`（中文高/中/低）与
  `alert_type` 都是字符串，`str(key) == key` 恒成立，**触发不了** —— 场景 6 安全。

## 改动范围

只改 `docs/44-演示流程.md` 的 §4 排障表，**新增一行**，未动其它内容。
 2026-09-14 20:41:34 +08:00
lzf_0626 36c7a9d8d2 文档：审查报告入库 + 全量校对补注 
## 新入库（`docs/演示用/`）

- `代码库全面审查报告-2026-09-14.md`
- `代码修改方案-2026-09-14.md`
- `记忆系统排查报告-2026-09-14.md`
- `记忆系统修复文档-2026-09-14.md`
- `文档一致性审计报告-2026-09-14.md`
- `多Worker接入方案-2026-09-14.md`

## 全量校对（32 个既有文档 + `AGENTS.md`）

跨 39 个文件、**1125 insertions / 148 deletions**。

⚠️ **这批改动同样不是本次会话写的**。我抽样核对过性质：是**实质内容补充**而不是
格式/换行转换。例如 `docs/44-演示流程.md` 新增两条"2026-09-14 补注"：

- `启动金融Agent平台.bat` 只在**桌面**上，仓库里只有 `启动平台.bat` 这一份
  （两份由同一个 `tools/make_launcher_bat.py` 产出，改完 `start.ps1` 重跑它一起更新）；
- `advisor_t`(9020) 与 `offsite_t`(9006) **不在 `tools/seed_test_rbac.py` 的演示用户里**
  （那里只有 `cust_t`/`risk_t`/`admin_t`/`review_t` 四个），由 `grant_*.py` 系列创建，
  **重跑种子不会重建它们** —— 换机器时这两个账号登录失败，要先查 `sys_user` 有没有这两行，
  而不是查密码。

这两条都是对的地方，与我这一路踩到的现象一致（我确实用到了 `advisor_t`/`offsite_t`）。

**我没有逐字审阅全部 39 个文件**，只抽样确认了改动性质与规模。若其中有需要复核的段落，
请指明文件，我逐处核对。
 2026-09-14 20:36:00 +08:00
lzf_0626 c0e5c80929 记忆系统：recall 结果接入 prompt + 可观测性（既有改动，代为提交） 
## 说明

**这批改动不是本次会话写的**，它们在会话开始前就已在工作区里、一直未提交。
我做的是**验证**它确实成立，然后按你的指示代为提交。

出处：`docs/演示用/记忆系统排查报告-2026-09-14.md` 与同目录
`记忆系统修复文档-2026-09-14.md`（两份都在本次一并入库）。
排查报告的结论是「记忆系统没有坏」——库里有真实数据、170 条抽取事件全部消费成功；
真正的问题是「观测不到」+「召回结果没人消费」。

## 改动内容（按两份文档的编号）

- **F1 `RecalledMemory.content` 断头路**：`base.py` 新增 `memory_context_text()`，
  `risk_agent._agent_system_prompt` 接收并注入记忆段。无记忆时返回空串，
  因此 prompt 逐字不变 —— 这也是它能安全接线的理由。
- **F3 `governance.recall` 员工身份恒空**：补一条明确的语义日志。
  员工身份下召回的是"该用户自身作为客户"的记忆，恒为空属预期，
  但此前没有任何提示，运维看到 `count=0` 只会以为记忆坏了。
- **F4 可观测性**：`GET /api/v1/users/me/memories`（`stored` / `recalled` /
  `downstream` / `pending_events` 四段）+ 抽取与召回的 6 处日志 +
  三个只读探针 `tools/probe_memory_state.py`、`probe_memory_detail.py`、
  `probe_agent_types.py`。

**未实施**（文档明确留作待决，我也不代为决定）：F2 `known` 引用校验永不触发
（需架构确认 memory 类 `source_references` 由业务填还是底座统一附加）、
F5 客服是否读写长期记忆（涉脱敏与复核，需产品+合规）。

## 我做的验证（会话内实测，非照录文档）

- 新接口 `GET /users/me/memories` 以 `cust_t` 调用 -> **HTTP 200**：

      stored:    total=2, by_status={'active': 2}
      recalled:  count=2, degraded=False
      两条记忆：preference:horizon='约三年'(0.95)、preference:risk_level='稳健型'(0.98)

  与排查报告 §〇 列出的那两条**完全吻合**。
- `pytest tests/unit tests/contract` 全绿（这批改动没有破坏既有测试）。

## 未验证的部分

`memory_context_text()` 接进 prompt 后的**端到端效果没有实测** —— 文档自己说明了
原因：当前 `risk` Agent 的召回恒空（员工身份不是客户），所以接线后行为不变，
要用测试替身才能验证注入。我没有为此编造证据。
 2026-09-14 20:35:46 +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 a337cca31a 修复 T002 下单的两个 P0：无幂等保护、读账户/持仓无行锁 
## P0-1 下单没有幂等保护（实测复现过重复扣款）

`app/api/controllers/trading.py` 的 T002 此前**没有任何幂等保护** —— 全仓 7 个
controller 共 29 处声明了 `Idempotency-Key`，**唯独 trading.py 一处都没有**，
而 `docs/05` §5.2 要求写端点必须带。

**修复前实测**（同一 key 连发两次）：

    两个不同 order_no：SO...FD48A488 / SO...2FB182C0
    委托 +2、可用现金 -910.50（2×455.25）、510300 持仓 3500 -> 3700
    ⇒ 重复扣款 + 重复建仓

**改法**：接 `ApiTransactionService.execute_in` —— 业务写入与幂等回执**同一个事务**
（`docs/05` §5.2），同键同 body 的第二次请求直接回放上次响应。

- `trade_service.submit_order` 新增 `commit: bool = True`：包装层调用时传
  `commit=False`，由 `execute_in` 统一提交。**不做这一步就会"内层提交外层事务"**，
  幂等回执与业务写入分处两个事务，回执写失败时业务已落库，重放失去意义。
- 响应经 `model_dump(mode="json")` 统一 JSON 化后再 `model_validate` 还原 ——
  保证"首次"与"重放"两条路径返回**同一形状**，且对外结构不变
  （金额仍是字符串化 Decimal）。

**修复后实测**（同一 key 连发两次）：

    两次 order_no 完全相同：SO202609141216512C7166D4
    两次响应逐字段相同（真正的回放）
    可用现金 -455.25（单次）、510300 持仓 +100（单次）
    T003 核对：43 条委托里只多出 1 条

## P0-3 下单读账户/持仓无行锁（并发可扣穿余额）

`trade_service.py` 全文 **零 `with_for_update`**，而项目其它 15 个 service 共 38 处
用了它 —— 规范早已建立，这里是遗漏。

**改法**：`_load_account` / `_load_holding` 增加 `for_update` 开关（默认关，
只读路径不加锁、不牺牲并发），`submit_order` 以 `for_update=True` 调用。
**加锁顺序固定「账户 → 持仓」**：并发事务按同一顺序取锁才不会成环，
这一点写在两处 docstring 里，改顺序前必须先想清楚。

**实测**（真并发 2 笔，各 45520 元，合计 91040 > 余额 49103）：

    第 1 笔：201 成交 SO...59568811
    第 2 笔：422 INSUFFICIENT_FUNDS「可用余额 3578.91 不足」
    成交 1/2，最终余额 3578.91 >= 0

**关键证据**：被拒那笔读到的是 **3578.91（已扣减后）**而不是初始的 49103.46 ——
证明两个事务被行锁串行化了。无锁时两笔都会读到 49103.46 而双双通过，
余额会变成 -41936。

## 实测汇总

- `pytest tests/unit tests/contract` -> **1427 passed, 2 skipped, 2 failed**
  （那 2 个是既有的：投顾页面被替换、docs/05 §19 分组行，均与本提交无关）
- `ruff check` -> All checks passed
- 两次实测的完整证据见上；两份验证脚本在 %TEMP%（未入库）

## 顺带修正一个我自己脚本的 bug

验证脚本里用 `GET /users/me/orders?limit=200` 读委托数，而 T003 的 `limit` 上限是
**100**（`Query(le=100)`）→ 422 → 读到 0 条，一度让我误判"委托没增加"。
改用 `limit=100` 后确认委托确实只 +1。
 2026-09-14 20:19:55 +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
lzf_0626 e9539ae1be Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-14 18:24:24 +08:00
lzf_0626 857c106faf 投顾工作台：三接口支持按客户出方案 + 动作按所选客户分流 
后端（向后兼容，customer_id 缺省即原行为）：
- 三个请求契约新增可选 customer_id（推荐/资产配置/持仓诊断）
- AuthorizationService 新增 require_customer_scope（权限码 + 数据范围）
- 推荐/资产配置/持仓诊断服务支持指定被分析客户
- InvestmentGoalService 新增 current_for_customer

前端（employee-advisor/dashboard/index.html）：
- 删除「本人」虚拟条目，客户列表改为 4 位真实客户
- 动作与自然语言入口均按所选客户带 customer_id 调真实后端
- 新增风评超期熔断闸门（FM-03，流水线停在 ② 画像）
- 统一对话入口从硬编码占位改为自然语言意图路由
 2026-09-14 18:22:56 +08:00
lzf_0626 484cccc145 记录三个演示文档的移动，并把 .workbuddy/ 加进 .gitignore 
## 文档移动（docs/ -> docs/演示用/）

`代码结构与关键逻辑梳理-2026-09-14.md`、`后端接口文档-2026-09-14.md`、
`软件需求文档-2026-09-14.md` 移入 `docs/演示用/`。
git 识别为 **rename**（状态 `R`），三份文档的历史完整保留，不是"删掉再新建"。

## .workbuddy/ 加入 .gitignore

它与文件里已有的 `.agents/`、`skills-lock.json` 属同一类 —— AI 编码助手的工具产物，
不是项目内容。放在同一节下，避免以后 `git add -A` 时误提交。

## 未包含（有意留下）

`docs/23-记忆分层与画像设计.md` 的工作区改动**没有**一并提交：那不是我改的，
也不在这次确认的范围内，留在工作区由作者决定何时提交。
（暂存时被 `git add docs` 一并带上，已 `git restore --staged` 退回。）
 2026-09-14 12:09:23 +08:00
lzf_0626 3df6671ce3 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-14 12:07:18 +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
lzf_0626 e59a9905a0 把「今日盈亏是硬编码 0」提级为待业务确认项（SRS Q22） 
## 问题

`today_profit_loss` / `today_profit_loss_ratio` 在 `app/service/trade_service.py` 里是
**硬编码 `ZERO`**（持仓列表 L678、账户看板 L748-749），客户看板、持仓页、盈亏分析页的
「今日盈亏」永远显示 0.00。同一函数里的「持有盈亏」是**真算的**
（`market_value - cost_amount`，L660 / L726），所以只有这一项是占位。

三份 2026-09-14 文档其实**都记录了这个事实**（接口文档第 11 条、SRS 第 212 / 458 / 615 行），
但**都埋在「注意事项」里，没有进第 0 章那份「★ 请先回答本章」的待确认清单** ——
业务翻文档时看不到，演示现场被问到就答不上来。而且 SRS 第 212 行还把它**错引到了 Q7**
（Q7 讲的是场外阈值，与此无关）。

## 改动

**docs/软件需求文档-2026-09-14.md**
- 新增 **0.5 节「占位实现与本期边界」**，登记 **Q22**：客户看板的「今日盈亏」本期是否实现。
  该节专门收这类「接口有、值还没真算」的偏差（不报错、单元测试全绿、只有业务看得出不对），
  以后同类问题继续往这里追加。
- 第 0 章项数 21 -> 22；阻塞项清单补上 Q22。
- 修正 F-4.2 的错误引用（见 Q7 延伸 -> 见 Q22）。
- R2 状态改为「已提级为待决项 -> 见 Q22」。
- **R1 状态改为已修复**：组员提交 `4b7ee13`「修复管理员工作台函数缺少闭合大括号」
  已解决 `workspace.js` 的语法错误。按该条自己要求的方式复验过 ——
  `node --experimental-vm-modules` + `vm.SourceTextModule` 遍历 `app/static/portal`，
  **44 个模块全部通过**（`node --check` 会假通过，不能用来判定）。

**docs/44-演示流程.md**（演示现场用）
- §3「可能被问到的问题」新增话术：直说这是占位值、指出持有盈亏是真算的、
  指向 SRS Q22 与两条口径的结论；并建议「时间紧就避开这一栏，被问到不要含糊也不要现编」。
- 场景 2（客户资产）加现场提示：讲「持有盈亏 / 总市值 / 可用资金」，不要指着「今日盈亏」讲。

**docs/后端接口文档-2026-09-14.md**
- 第 11 条补上代码行号与交叉引用，并点明同一响应里的 `profit_loss` 是**真算的**。

## 顺带交给业务：两条口径的可行性（实测，非推测）

业务要决定的是「要不要做」，但「能不能做」也得一起给，否则业务选完还要再问一轮：

| 口径 | 数据现状 | 结论 |
|---|---|---|
| 用行情算（今收 − 昨收） | `fin_market_price` **只在同步时才写行**，实测每个产品**只有 2 行**（515450 只有 09-11 与 09-14，还跨了周末） | ❌ 取不到连续「昨收」 |
| 用净值算（今净值 − 上一交易日净值） | `fin_nav_history` 每个产品 **120~160 行连续交易日净值** | ✅ 建议按这个口径 |

⇒ 文档建议按**净值口径**实现，并提醒业务一并确认语义：净值是日终数据，
该指标实际是「最近一个交易日的盈亏」，**不是盘中实时**。

## 入库说明

三份 `docs/*-2026-09-14.md` 此前是**未跟踪文件**，本次一并入库（同一批文档交付物且互相引用）。
`.workbuddy/`（工具会话记忆）属工作区过程产物，**未入库**。
 2026-09-14 11:24:51 +08:00
lzf_0626 eb89ffd0b4 按需造数据：给指定客户建持仓，并保证产品有可查的最新净值 
## 需求

产品 15911、客户 10001 / 10002；最终要能查到这两户持有 15911 的持仓，
以及 15911 的最新净值。

## tools/seed_custom_holdings.py（新）

参数化脚本，不写死这次的代码与账号。手工写 SQL 会连踩一串坑，每一条都在本仓库真实发生过：

1. `fin_*` 的 `id` 列**没有 AUTO_INCREMENT**，不显式给 id 就报
   `Field 'id' doesn't have a default value`；
2. `fin_holding.shares` / `current_value` 文档标注为"生成列"，实测是普通 NOT NULL 列，
   不写插不进去；
3. 只建 `sys_user` 不绑角色 -> 登录成功但查持仓 403；
4. 只建用户不设密码 -> `password_hash` 是占位符，**根本登不进来**；
5. 净值散在三处（`fin_product.current_nav`、`fin_nav_history` 最新一条、
   `fin_market_price.close_price`），只写一处就会"产品页有净值、持仓页市值为空"；
6. 往 `fin_market_price` 写"今天"的编造行情会**盖住真实行情** —— 下单按 `trade_date DESC`
   取，编造行排在前面，过了 `MAX_QUOTE_AGE`（15 分钟）整个产品就一律 503
   （周末尤其明显）。

脚本把这些一次做对，并保证上面第 5 条的三处严格一致（持仓市值恒等于 数量 x 最新净值）。

## 开户风险测评：走接口，不插表

这是这次最关键的发现。数据都建好之后，客户能登录，但访问 T001 / T006 一律 403，
报的是 `AGENT_PERMISSION_DENIED`「请先完成开户风险测评问卷」——
那是合规前置（`app/api/dependencies/auth.py` 的 `OnboardingRequiredError`），
不是 RBAC 没配好，两者表象一模一样，很容易查错方向。

`RiskQuestionnaireService.is_required` 只查 `fin_risk_assessment.valid_until > now`，
所以插一行就能过检查。**没有那样做**：插表不会生成画像快照、画像标签和记忆同步事件，
而投顾分析、适当性检查、Agent 对话都要读那些。改走真实接口
`POST /api/v1/onboarding/risk-questionnaire/submissions`，让业务链路自己把关联数据建全。

内置 13 题答案按 `_SCORE_RULES` 折总分 46 -> C4 成长型（产品是 R3，C4 有余量）。
等级**不从接口读**：提交返回里故意没有它（`_SCORE_RULES` 是服务端机密，注释写明
never included in customer responses），所以从库里读回并打印。实测读到 C4 / 46 分，
与手算完全吻合。

## 实测（接口层，不只是查库）

- P001 访客产品列表：21 个产品，★ 命中 15911，`current_nav=1.000000`
- P002 净值走势：30 个点，最近 3 条 2026-09-10 / 09-11 / 09-14
- 10001 / 10002 登录 -> T001 资产看板 200：总资产 101000.00、总市值 1000.00
- 10001 / 10002 -> T006 持仓 200：15911 数量 1000、最新价 1.000000、市值 1000.00
- 幂等复核：第二次执行不重复建记录、不覆盖持仓数量、不重复提交测评、不重置密码
- `ruff check app tests tools alembic hq.py` -> All checks passed

## 已知限制

产品代码 `15911` 是 **5 位**，而系统现有 20 个产品**全是 6 位**，且下单要求行情落在
`FundQuoteRuntimeConfig.allowed_codes`（六位数字）白名单里。
所以它**能建、能查持仓、能查净值，但不能下单**。
若是笔误，用 `--product-code 159911` 重跑即可。
 2026-09-14 10:03:07 +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
lzf_0626 d95ef09627 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-14 02:00:59 +08:00
lzf_0626 c5bfc2c998 钉住 .bat 的换行：新增 .gitattributes（*.bat text eol=crlf） 
本机 core.autocrlf=true，git 在 add 时会把工作区的 CRLF 静默存成 LF；
换个 autocrlf=false 的环境 clone 出来就是 LF，而 cmd 对 LF-only 的 .bat
会行边界错乱（把 echo 的说明文字当命令执行，实测报
"AT 命令已弃用"、"']' 不是内部或外部命令"，甚至真的去跑脚本）。

.gitattributes 里钉 `*.bat text eol=crlf`：仓库统一按 LF 存储、检出时转回 CRLF，
不依赖任何人的本地 git 配置。

验证方式（不是"我觉得会转"）：删掉工作区的 bat 再 `git checkout --` 取回来，
实测 2090 字节、62 个 CRLF、无裸 LF，与写文件时的形态一致。

仓库里目前只有 `启动平台.bat` 一个批处理，影响面仅此。
 2026-09-14 02:00:41 +08:00
lzf_0626 404f8f6aa5 固化接口体检脚本，并交付双击即用的启动 bat 
## tools/portal_api_check.py（新）

把 2026-09-13 那轮"照着接口内容把前端测一遍"的验证固化成可重复跑的脚本。
当时靠这套验证查出 6 个真缺陷，但它们只存在于一次会话里，下次改动没人会重跑：

- `K002`/`K003` 是裸信封，前端按 `payload.data` 取 -> 知识库页显示"已入库 0 块 / 为空"
- 委托/成交详情页照着建表字段写，而接口返回视图没带那些列 -> 5 行永远显示 `--`
- 配置项/路由规则的 `PUT` 要 `If-Match`，却没有端点能返回该 digest -> 首次编辑必然 409
- 回复模板 `scene` 只校验长度不校验枚举 -> 非法值撞数据库 CHECK、冒成 500
- 路由规则表单固定 `max_attempts=2` 且 `fallbacks` 为空 -> 后端必然 422
- 模型端点手填 ID -> 未激活的 ID 直接 422

与 `e2e_smoke_test.py` 分工互补：后者测**业务链路通不通**，本脚本测**接口契约对不对**
（状态码、信封形状、字段名与前端期望是否一致）。

三档，默认只跑第一档：
- 默认只读 41 项（不动数据）
- `--write` 加测写操作：配置项 ETag 链路、`max_attempts` 越界、知识库上传+失效、
  回复模板非法枚举、敏感词、推广物料全链路
- `--dangerous` 再加测会改生效配置的操作（激活配置版本会整版本替换，默认不跑，
  脚本内注明了恢复办法）

实测：只读 39/39、写入档 54/54 全绿。

## 桌面一键启动（双击即用）

桌面 `启动金融Agent平台.bat` + 仓库 `启动平台.bat`，由
`tools/make_launcher_bat.py` 生成，只负责"双击"这一层，启动逻辑复用 `start.ps1`
（不重复实现，避免两边漂移）。参数可透传：`-Port 8100` / `-NoBrowser` / `-SkipPriceSync`。

不要手写这个 bat：必须同时满足 **GBK 编码 + CRLF 换行 + 无 BOM**。生成器自己
读回来校验这三条。踩过的坑：用 `write_bytes` 直接落盘时没转 CRLF，cmd 对 LF-only
批处理会行边界错乱，把 `echo` 的说明文字当命令执行（实测报
`AT 命令已弃用`、`']' 不是内部或外部命令`）。

## start.ps1 的三处修复

1. **解释器探测选错环境（真机双击失败的主因）**
   原先只验证 `--version` 成功就选中，结果挑到一个 Python 3.10 环境：
   本项目用了 `datetime.UTC`（3.11+）且依赖 `asyncmy`，启动当场 ImportError ——
   而报错发生在**行情刷新**那一步，看起来像"行情源坏了"。
   现在实测两项：**版本 >= 3.11** + `import fastapi, sqlalchemy, asyncmy, pydantic` 通过，
   并在跳过时打印具体原因。

2. **`Select-Object -First 1` 掐断 native 管道**
   `& $exe -c ... 2>&1 | Select-Object -First 1` 拿到首个对象后停掉上游管道，
   等于把进程掐了、`$LASTEXITCODE` 变脏，于是**每个候选都被误判成"无法执行"**
   （连装好的 jr_py313 也被跳过）。改为先整体接住输出、再在结果上取行。

3. **幂等 + 就绪探测 + Docker 自动拉起**
   重复双击不再起第二个 API/Worker（API 按端口、Worker 按进程判断）；
   起完等 `/internal/health/ready` 真正应答才报成功；Milvus 不可达时尝试拉起
   Docker Desktop 并最多等 60 秒（它不常驻，是"知识检索静默降级"最常见的原因）。

## 实测

- `启动平台.bat` 重复执行：解释器正确选中 jr_py313、依赖检查全 OK、行情已刷新、
  两个服务识别为已在跑并跳过、就绪探测 1 秒
- `-Port 8199` 冷启动：新起 API 窗口，8199 的 `/internal/health/ready` 与 `/portal/` 均 200，
  测试后已清理
- `ruff check app tests tools alembic hq.py` -> All checks passed
- `start.ps1` 语法解析通过（BOM 已保留）、bat 三项编码约束校验通过

文档同步：`AGENTS.md`（启动方式、bat 生成器、解释器探测两个坑）、
`docs/44-演示流程.md` §0.3/§0.4（双击启动、两条自检线的分工）。
 2026-09-14 01:59:46 +08:00
lzf_0626 3cbfe10d62 fix(portal): 补齐运营三个新页面的同名 css 入口，修复合并进来的红灯契约测试 
合并组员的运营工作台提交后，`test_every_portal_page_has_local_js_and_css_entry`
红了：门户每个页面都要有与目录同名的 `js`/`css` 入口，而新加的
`nl2sql` / `offsite` / `promotion` 三个页面**只有 js**，样式统一引 `operator-workspace.css`。

## 改动

给三个页面补上同名样式入口，并在各自 `index.html` 里引用（放在共用的
`operator-workspace.css` 之后，便于页面覆盖）：

- `employee-operations/nl2sql/nl2sql.css`
- `employee-operations/offsite/offsite.css`
- `employee-operations/promotion/promotion.css`

三个文件当前**没有规则**，只写了用途说明 —— 它们的价值是把"页面专属样式"的位置
**确定下来**：这个约定的意义正在于此，否则将来只会继续往共用文件里堆。

⚠️ 只在每个 `index.html` 的 `<head>` 里**加了一行 link**，未改动组员的其它内容。

验证：`tests/unit/api/test_portal_frontend.py` 37 passed；
unit+contract **1398 passed**；integration **110 passed**；ruff 通过；
mypy 251 文件 0 错；三个页面与三个 css 均 200；e2e 冒烟 **40/40**。
 2026-09-14 01:42:21 +08:00
lzf_0626 4c1e84b5a2 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-14 01:35:54 +08:00
lzf_0626 eded5896cd fix(admin): 回复模板的 scene 加枚举校验，非法值不再冒成 500 
## 问题

`agent_reply_template.scene` 有数据库 CHECK 约束 `chk_template_scene`，只允许
`disclaimer` / `low_confidence` / `compliance_block` / `transfer` / `model_failure` /
`system_busy` / `clarification` 七个值。

而 `ReplyPayload.scene` 只校验长度（`min_length=1, max_length=32`）——
传一个不在列内的场景会**穿过接口校验、撞上数据库约束**，最终以
`500` 冒出：

    (3819, "Check constraint 'chk_template_scene' is violated.")

那本该是一次 `422` 参数校验失败。**500 与 422 的差别不只是状态码**：
前者会让调用方以为服务端故障、触发重试与告警，而实际是自己参数错了。

## 改动

`ReplyPayload.scene` 改为 `Literal[...]`（新增 `ReplyScene` 类型别名），
取值与 `chk_template_scene` **逐字对齐**，并在注释里写明这个对齐关系与本次事故。

实测：非法 scene → `422 AGENT_INPUT_INVALID`（不再是 500）；合法 scene → `201`。

## 发现方式

这一处是**按接口逐条调用、逐个核对返回**时暴露的 —— 只看代码很难注意到
"schema 的宽松校验"与"数据库的严格约束"之间那道缝。同类风险仍存在：
凡是**表上有 CHECK 而 schema 只做长度校验**的字段，都有同样的 500 风险。

验证：unit+contract 1397 passed；integration 110 passed；ruff 通过；
mypy 251 文件 0 错；e2e 冒烟 40/40。
 2026-09-14 01:35:34 +08:00
lzf_0626 daf73a2865 fix(portal): 照接口逐条核对前端，修掉 5 处「照着表结构写、看着像对」的缺陷 
做法：把前端 `api-client.js` 注册的端点**按前端完全相同的方式**（同样的路径、参数、
身份）逐个调用，再拿真实返回去核对前端 render 用到的字段。
**这类问题纯读代码看不出来** —— 只有把真实返回和期望字段摆在一起才会暴露。

## 1. 知识库功能实际是坏的（K002 / K003 是裸信封）

`K002` 的成功体是 `{knowledge_ids, filename, chunk_count}`、`K003` 是 `{items, count}`，
**都没有 `data` 信封**。而 `request()` 默认取 `payload.data`（undefined），于是：

- 上传后前端显示「已入库 **0** 块」，而库里其实切了 23 块；
- 列表永远显示「知识库为空」。

端点表里标 `raw: true` 后（与 `V001` 同一做法）两者都正常。
实测：上传 4805 字符的产品手册 → 切 23 块并出现在列表里。

## 2. 委托/成交详情页有 5 行永远显示「--」

前端按 `fin_sim_order` / `fin_transaction` 的**建表字段**写了 `quote_source`、
`nav`、`fee_rate_snapshot`、`confirmed_at`、`auto_confirmed` ——
但这些字段**接口的返回视图没有带**（表里有、返回里没有）。已按实际返回重写字段表，
并在注释里写明"以接口返回为准，不要照表写"。

## 3. 配置项与路由规则的**编辑功能不可能成功**（接口缺口）

`PUT` 硬性要求 `If-Match`，校验的是该行内容的 digest；而这两个资源是 `detail=False`
—— **没有任何端点能返回这个 digest**（列表的 `meta` 只有 trace_id）。
乐观并发在"读不到版本"的前提下等于死锁：**首次编辑必然 409**。
（配置发布能用，是因为它有详情端点 `A003`。）

- 新增详情端点 `A048` / `A049`（`detail=True`），已登记 `docs/05` §19；
- 前端编辑前先 GET 详情取 etag，再带 `If-Match` 提交。
- 实测：编辑配置项与路由规则均 200；**不带 `If-Match` 仍返回 409**，
  说明乐观并发没有被削弱。

## 4. 路由规则表单**必然提交失败**

前端固定写 `max_attempts: 2` 且 `fallbacks: []`，而后端要求
`max_attempts ≤ 端点总数`（主 + 兜底）→ 422「重试次数超过端点数量」。
改为 `1` 并注明约束。

## 5. 主端点手填 ID 会 422

后端对不存在/未激活的 `primary_endpoint_id` 直接 422「模型端点不存在或未激活」。
把输入框改成**下拉**，只列 `status='active'` 的端点（数据复用已有的端点列表）。

## 顺带

- `apiClient` 增加 `del()` / `put()`：发出的方法一直由端点表决定，所以 `post('K004')`
  也能发 DELETE —— 语义太绕，现在意图与行为一致。
- 清理了测试期间上传的 31 条知识残留（客服会检索到它们），库内恢复到 23 条产品手册。

## 关于"逐条核对"的方法论

前两轮跑出来的 9 个和 5 个"失败"里，**多数是我测试脚本自己的假设错了**，不是前端问题：
`T001` 是 `{account, summary}` 嵌套、`RK002` 的字段叫 `risk_level`、
`RK002/RK004/RK005` 的 limit 上限是 5/10/10（前端传的正是 5/10/10）、
`AD011/A002/A047` 的 data 是裸 list。每一处都回到前端源码确认后才下结论 ——
**先把"我以为"改成"代码里写的"**，否则报告出去的就是假 bug。

验证：unit+contract **1397 passed**；integration **110 passed**；ruff 通过；
mypy 251 文件 0 错；§19 现 93 个端点无重复；e2e 冒烟 **40/40**。
前端等价测试：只读 31 项全绿、写操作（含 ETag 链路）9 项 8 绿 1 项因测试数据过短。
 2026-09-14 01:19:22 +08:00
lzf_0626 e31420df29 feat(portal): 补齐四个前端缺口——客户详情、知识库管理、配置项与路由编辑 
先审计了全部 **141 个后端端点**：前端注册 68 个，注册的**全部有效**（没有一个打不通）。
本提交补的是其中真正影响可用性的四类。

## 1. 客户端：委托详情（T004）与成交详情（T008）

两个接口后端一直存在，但订单页 / 成交明细页**只接了列表（T003 / T007）** ——
客户点不进任何一条记录，看不到成交价、费用构成、确认时间与行情来源。

改为**行内展开**（点「详情」在原行下方展开，再点收起），不跳页：

- 复用新加的公共样式 `.list-detail`（`common/customer-list.css`），两页共用而不各写一份
- 详情取不到时**不整页报错**：列表本身是好的，只恢复按钮并记一次错误

## 2. 管理员：知识库管理（K002 / K003 / K004）

客服的**全部回答都来自已入库的知识**，而此前**没有任何页面能管理知识库** ——
只能靠命令行脚本 `tools/seed_knowledge_demo.py` 灌数据，管理员既看不到也改不了。

新增「知识库」标签页：文档列表 + 上传（.txt/.md/.docx）+ 失效。两处要点：

- **K003 的成功体是裸的** `{items, count}`、**没有 `data` 信封** ——
  `request()` 仍会去取 `payload.data`（那是 undefined），所以列表要两面都兜，
  否则永远显示"知识库为空"、而库里其实有数据；
- 上传是 **JSON + base64**，不是 multipart（一期契约如此，见 `knowledge_management.py`）。

## 3. 管理员：配置项与模型路由（A001 / A008–A010 / A018–A020）

此前只能对**已存在**的版本走"校验→审核→激活"，**既不能新建版本、也不能往里加配置项**
—— 新建的版本永远是空的、校验必然失败；模型路由规则同样既看不到也改不了。

- 新增「新建配置版本」表单（版本号 / 标题 / 变更说明）
- 每个版本加「内容」按钮（**与状态无关**：草稿阶段就要能加，否则版本永远空）→
  展开该版本的**配置项**与**模型路由规则**，两者都支持新增与编辑
- 配置项的「值」按 JSON 输入并在前端校验：与其让后端 422，不如就地拦住并说清哪里不对
- `fallbacks` 暂不在界面编辑（提交空数组），需要时用接口补

这些端点**都已在 `docs/05` §19 有编号**，直接复用，无需新增编号。

## 4. 两个"死端点"查证后**保留**

初查发现 `RK013`（风控日报非流式，已被 RK014 流式取代）与 `ADVISOR_GOAL`
（投顾自己的目标；投顾是员工、没有目标 → 永远 404）注册了却无人调用，一度删除。
但 `tests/unit/api/test_portal_frontend.py` 立刻失败 —— 它把"页面会用到的端点"
固定成一张清单，**注册与调用是两件事**。已恢复注册，并就地注明它们当前无人调用、
但受契约保护。

顺带发现：**`RK013`–`RK015`（风控日报）也不在 §19**，与投顾 AD 段原先的情况相同，
属文档缺口（未在本提交内补）。

## 辅助改动

`apiClient` 增加 `del()` 与 `put()`：真正发出的方法一直由端点表里的 `method` 决定，
所以 `post('K004')` 也能发出 DELETE —— 但读代码的人会以为发的是 POST。
现在意图与行为一致。

验证：unit+contract **1397 passed**（含前端契约 37）；integration **110 passed**；
ruff 通过；mypy 251 文件 0 错；e2e 冒烟 **40/40**；相关页面与静态资源全部 200。
 2026-09-14 00:51:13 +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 de55c5c60c feat(advisor): 登记 17 个投顾端点并补管理员复核入口（A047 待审队列） 
## 1. docs/05 §19 补登 17 个投顾端点

这批端点此前**只存在于代码中**，§19 一条都没登记；而 §12 写的入口
`/api/v1/advisory-plans/**` 与实际路径 `/api/v1/advisor/**` 也不符（已修正）。

- **A041–A046**：管理员治理（配置回测、画像标签与漂移复核、推荐方案审核与发布）
- **AD001–AD011**：投顾自用。**新开 `AD` 号段**的理由：它与 A 段是两个不同的权限面
  —— A 段是 `/api/v1/admin/**` 管理面，AD 段是 `/api/v1/advisor/**` 投顾自用；
  混在一个号段里，"这条到底谁能调"就得逐条去读权限列。
- 另加 AD 段说明块：`investment-goal` 的两套权限码（`...:self` / `...:customer`）、
  AD006/AD007 虽在投顾路径下却要求 `admin`、灰度开关 `enforce_advisor_rollout` 前置、
  幂等范围（AD008/AD009 无幂等头）、以及 404/409 的失败口径。

§19 现为 **90 个端点 / 9 个号段**，无重复。

## 2. 管理员复核入口 + A047 待审队列

**发现一个让审核链路不可达的缺口**：`review` / `publish` 都要求调用方先拿到键
（推荐方案是 `content_id`、方案书是 `goal_no`），而此前**没有任何端点能列出待审内容**
—— 管理员拿不到键，投顾生成的东西就永远停在待审状态。

- 新增 `GET /api/v1/admin/advisor/pending-contents`（编号 **A047**）：一次返回两类待审内容。
  两类内容的"待审"取值不同（推荐方案 `pending_review`、方案书 `pending`），
  只判其中一个会整类漏掉，所以用 `PENDING_STATES` 一并匹配。
- **为方案书一并查出 `goal_no`** —— 它的审核/发布端点（AD006/AD007）按 `goal_no` 寻址，
  只给 `content_id` 的话管理员拿到列表也调不动。已由 integration 测试守住这一点。
- 管理员工作台新增「投顾复核」标签页：列出待审内容，支持审核通过 / 驳回 / 发布；
  前端按 `content_type` 自动选择端点、寻址键与载荷
  （方案书发布要 `{publish: true}`，推荐方案发布不读 body）。
- 发布前校验状态：未审核通过不允许发布，与 `publish_book` 的 `IllegalState` 一致。

## 3. ⚠️ 同时发现：投顾的三个分析功能对投顾本人不可用

`ProductRecommendationQuery` **没有 `customer_id`** 字段，而 `generate` 用的是
`int(context.user_id)`（`product_recommendation_service.py:69`）—— 即**把投顾自己**
当成了服务对象。投顾是员工、没有风险测评与持仓，于是实测：

    POST /api/v1/advisor/recommendations   → {"status": "profile_required"}
    POST /api/v1/advisor/asset-allocation  → {"status": "profile_required"}

**组合分析、资产配置、生成推荐草案这三个功能，投顾调用必然拿不到结果。**
这是"投顾功能很奇怪"的直接来源之一。修它要改接口契约（加 `customer_id`、
并确定"投顾能对哪些客户生成"的权限口径），属产品决策，未在本提交内改动。

验证：unit+contract **1397 passed**；新增 integration 用例 2 passed；ruff 通过；
mypy 251 文件 0 错；A047 实测管理员 200（带出方案书的 `goal_no`）、投顾 403。
 2026-09-14 00:17:46 +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
lzf_0626 7c3a832104 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-13 23:56:44 +08:00
lzf_0626 421fed8569 feat(advisor): 补全投顾流程入口（确认目标 → 查看方案书），并修复页面缺缓存版本 
## 1. 投顾流程此前是断的

投顾工作台只有 4 个「生成草案」操作 + 1 个只读列表，而**确认目标**与**查看方案书**
这两个端点虽然存在却**没有入口** —— 于是目标永远停在 `pending_confirmation`、
方案书永远停在 `pending`。

实测客户 9001 正是如此：`confirmed_at: null`、方案书 `review_status=pending`。
而「录入客户目标」成功后的提示是"已提交，等待确认与审核"，**没有下一步可点**。

改动：

- 新增操作卡「目标确认与方案书」：输入客户 ID → 查询目标 → 显示目标状态、
  方案书状态、收益区间 / 回撤 / 期限 / 基准 / 确认时间 → **确认目标** / **查看方案书**。
- **录入目标后自动跳到目标状态页**，把确认按钮摆在眼前，而不是停在"已提交"。
- `ADVISOR_CONFIRM_GOAL` / `ADVISOR_GOAL_BOOK` 补登记进 `api-client.js`
  （`ADVISOR_CUSTOMER_GOAL` 早已注册却从未被使用）。
- 404「当前投资目标不存在」按**正常情况**处理（给下一步提示），不当故障报警。

⚠️ **审核与发布不在此范围**：`review_book` / `publish_book` 都要求 `admin=True`
（见 `investment_goal_service`），那是管理员的动作，投顾侧到"确认 + 看方案书"为止。
方案书仍会停在 `pending`，除非管理员侧也补上入口。

## 2. 9 个页面的 script 标签缺缓存版本参数

投顾工作台的 script 是 `dashboard.js`（**没有 `?v=`**），另有 8 个页面同样如此
（客户的持仓/下单/流水/盈亏/测评/成交明细、管理员工作台、运营工作台）。
浏览器会一直用缓存的旧 JS —— **改了代码也看不到效果**，这是"功能很奇怪"的一部分。

已统一补上 `?v=20260913`，投顾页的 js/css 提到 `-2`。

## 3. 过程中我损坏过 8 个文件，已恢复

第一次批量补版本参数时我用了 PowerShell `Get-Content -Raw` + `Set-Content`：
**PS 5.1 默认按 ANSI/GBK 读**，把 UTF-8 中文读成乱码再写回
（`角色与权限` → `瑙掕壊鏉冮檺`）并写入 BOM。`tests/unit/api/test_portal_frontend.py`
的断言当场抓到了它（找不到「角色与权限」）。

已 `git checkout` 恢复全部 8 个文件，改用 Python 重做（显式 UTF-8、不写 BOM、
保持原换行），现在每个文件的改动都是 **1 增 1 删**。

验证：`tests/unit/api/test_portal_frontend.py` 35 passed；unit+contract **1395 passed**；
ruff 通过；mypy 251 文件 0 错；确认目标实测 200
（`pending_confirmation` → `confirmed`，写入 `confirmed_at`），
重复确认被状态机以 409 拒绝。
 2026-09-13 23:56:27 +08:00
lzf_0626 3ada1f6c87 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-13 23:38:57 +08:00
lzf_0626 7208713c17 feat(portal): 接入历史净值，产品详情页恢复真实走势图 
`fin_nav_history` 一直是**空表**，所以产品详情页画不出走势图 —— 此前那条曲线是
前端 `mock-data.js` 里编的 12 个点位，接入公开产品接口时把它去掉了
（走势图最容易被当成真实业绩），页面改为显示"尚未接入"。本次补上完整链路。

## 1. 取数（app/infrastructure/fund_market_adapter.py）

新增 `fetch_nav_history()`：东方财富历史净值接口（`api.fund.eastmoney.com/f10/lsjz`）
分页取序列。

- **为什么不复用 `fetch_kline`**：它走 `push2his.eastmoney.com`，
  该域名在本环境实测连接被拒（`RemoteProtocolError`）；
- **为什么不复用 `hq.get_southern_fund_nav_history`**：那个函数校验**南方基金白名单**，
  而 `fin_product` 里有非南方基金的产品（510300 是华泰柏瑞的），调它会直接 `ValueError`。

⚠️ 实现里踩到一个坑：接口**会忽略请求中的 `pageSize`**（实测固定每次返回 20 条）。
最初按硬编码的 30 判断"是否最后一页"，于是 `len(items) < 30` 永远成立、只取到第一页 ——
走势图看上去"有数据"，其实只有最近 20 天，而且毫无报错。
改为按首屏**实际条数** + `TotalCount` 推算页数后，同样区间取到 124 条。

## 2. 落库（tools/sync_nav_history.py，新增）

写入 `fin_nav_history`，按 `(product_id, nav_date)` 幂等 upsert。
实测：20 只产品 / **2513 行** / 2026-03-17 ~ 09-13；重跑**新写入 0 行**。

## 3. 接口（P002）

`GET /api/v1/products/{product_code}/nav-history`，编号 **P002**，已登记 `docs/05` §19。
鉴权口径与 P001 相同（要求有效令牌、不校验权限码，访客令牌可用）；`days` 有界 1–365。

**表为空时返回 `count=0` 与空数组，而不是报错** —— 调用方据此显示"尚未接入"，
**不得回退到编造曲线**。产品不存在或未上市 → `404`（否则前端分不清"没有数据"
和"没有这只产品"）。

## 4. 前端

详情页按序列画 SVG 折线，期数标题改为动态（"近 N 个交易日"）。
表为空时仍显示"尚未接入"占位，并补上此前缺失的 `.detail-chart__empty` 样式。
`product-detail.js` / `.css` / `index.html` 的缓存版本参数一并 bump 到 `-7`。

## 5. 演示数据

`tools/seed_demo_data.py` 增加第 5 步「历史净值」（现 **11 步**），
否则换台机器演示时走势图又会是空的。

验证：P002 实测 515450 / 510300 各 120 个净值点；ruff 通过；mypy 251 文件 0 错；
unit+contract 1391 passed；integration 108 passed；e2e 冒烟 40/40。
 2026-09-13 23:38:13 +08:00
lzf_0626 0b82053ca2 fix(rbac): 交易权限的 data_scope 写成了动作名，导致下单/成交静默 403 
`tools/seed_test_rbac.py` 的 `PERMISSIONS` 行形状是
`(id, 权限码, resource, action, data_scope)`，而 T 段那四条写成了
`(9061, "trade:order:create", "trade", "order", "create")` ——
「resource, action」多写了一段，于是 action 落进了 `data_scope` 的位置。

## 后果是静默失效，不是放宽

`IdentityRepository.load_context` 只收集 `data_scope ∈ {self, own_customers, all}`
的权限，其余**整条丢弃**：

    if row["permission_code"] and row["data_scope"] in rank:

于是客户在库里**明明有**这四个权限，`POST /api/v1/users/me/orders`、
`GET /api/v1/users/me/orders`、`GET /api/v1/users/me/transactions` 等 T 段端点
却全部返回 `403 AGENT_PERMISSION_DENIED`「缺少操作权限」。
而同一批里 `account:read:self`、`holding:read:self` 的 scope 是 `self`，照常 200 ——
现象特别像"只有交易坏了"，几乎不会有人去怀疑**权限行本身写错了字段**。

因为 seed 是 `DELETE FROM sys_permission WHERE id BETWEEN 9001 AND 9099` 的**重建**语义，
**每跑一次种子就重现一次**，而 `tools/seed_demo_data.py` 的第 1 步正是它。

## 修复与守卫

- 四条改为 `"self"`，并就地写清第 5 个字段是 `data_scope`、只能取三种值；
- `tools/check_rbac_seed_consistency.py` 增加**第 5 条检查**：每行字段数必须是 5，
  且 `data_scope` 取值合法。已用模拟对象确认它能抓住事故写法
  （非法 scope 报 2 条、字段数不足报 1 条、合法写法通过），
  并由 `tests/unit/tools/test_rbac_seed_consistency.py` 纳入门禁。

修复后实测：库内非法 `data_scope` 归零（`self` 22 → 26）；
`/users/me/{account/dashboard,holdings,transactions,orders}` 全部 200；
下单成交价 4.579（真实行情）；e2e 冒烟 40/40；integration 106 passed。
 2026-09-13 22:57:59 +08:00
lzf_0626 9cb0f6e474 feat(portal): 公开产品接口（P001）落地，访客三页改读真实数据 
访客首页推荐、产品列表、产品详情此前读的是前端手写的
`app/static/portal/common/mock-data.js`：只有 8 只，且**其中 6 只根本不在
`fin_product` 里**（159915 / 512100 / 513100 / 511360 / 159645 / 159925），
还把海富通的 `511360` 标成"南方短融ETF"、把 `510500` 净值写成 6.742（真实 7.6027）。
`README.md` 把它记为"公开产品 HTTP 接口尚未实现"的临时方案。

## 接口

新增 `GET /api/v1/products`（编号 **P001**，已在 `docs/05` §19 总目录与 §19 说明中登记）：

- **要求有效令牌但不校验权限码**：访客令牌的角色是 `visitor`、不带任何权限，
  这与 `/api/v1/agent-runs`、`/api/v1/conversations` 面向访客的口径一致；
  产品信息本身是公开信息。数据面只暴露 `fin_product`（`status='上市'`）与
  `fin_market_price` 的最新一行，**不含任何账户/客户字段**（由 integration 测试守着）。
- 字段与 `mock-data.js` 对齐，因此前端渲染与筛选逻辑**一行未改**。
- `change_pct` **可能是 `null`**：当日涨跌需要两个交易日的收盘价，行情只同步过一天时
  算不出来。前端对 `null` 显示"暂无" —— `formatPercent(null)` 会渲染成 `+0.00%`，
  那等于对客户说"今天平盘"，是编出来的结论。

## 前端

- 新增 `common/visitor-token.js`：访客令牌的**唯一实现**（这段逻辑原先只写在客服浮窗里，
  现在四处要用；复制四份的话存储 key 与过期判断迟早不一致）；`widget.js` 改为复用它。
- 新增 `common/product-notes.js`：产品级披露文案。510300"非本公司发行"那条是**合规披露**，
  不能随 mock 一起删掉。
- 三个访客页改读接口，并显式区分 loading / error 状态。
- **删除 `common/mock-data.js`**。
- 产品详情页**不再画走势图**：`fin_nav_history` 目前 0 行，此前那条曲线是 mock 里
  12 个编造点位 —— 走势图最容易被当成真数据，宁可不画，并显式说明"尚未接入"。

## 顺带修正

`min_amount` 在库里全是 0.00（那本是场外"最小认购金额"的概念，对场内按手交易的 ETF
不适用），页面不再显示"¥0.00"（会被读成零元起购），改为"1 手（100 份）起"。

验证：接口实测 `count=20`；ruff 通过；mypy 251 文件 0 错；unit+contract 1387 passed；
integration 106 passed；e2e 冒烟 40/40。
 2026-09-13 22:57:48 +08:00
lzf_0626 f6bfcc26b3 fix(demo): 把未上市的 160129 换成真实挂牌的 515450，并修掉种子假行情盖住真行情 
## 1. 160129 本就不该在场内清单里

`160129`（南方金利定开债券C）是 `160128`（金利定开债券 **A** 类）的 C 类份额，
而 C 类份额只在场外销售、**不在交易所挂牌** —— 行情源对它永远返回空，下单只能走
净值降级（`source=eastmoney_nav_fallback`），既掩盖了"该产品并不交易"这一事实，
又让成交价带上折溢价偏差。

选型依据：把南方基金全部 **882 个代码**逐个问过腾讯行情源（该源只对交易所上市证券
返回数据），确认真实上市交易的只有 **109 个**；其中 R1/R2 的场内产品
（159700、160128、511070、511810）**原先已在清单内**，所以替换品只能来自 R3 及以上。
选定 **`515450` 红利低波50ETF南方**：仍是南方基金旗下、成交额约 1.3 亿元流动性充足、
红利低波定位偏稳健，与它替换掉的债券 LOF 定位最接近；客户风险等级已覆盖 R3
（原有 `510300` 即 R3）。

改动：`hq.py` 的 `FUND_TYPE_GROUPS`、`tools/import_hq_test_products.py` 的场内映射，
两处都留了注释防止被加回来；`docs/42` / `docs/43` 的产品表与费率表同步
（净值 1.4027、管理费 0.50%、托管费 0.10%）；`docs/42` 另加了一条决策记录。

库内用**复用 `fin_product.id = 9100005`** 的方式替换，使 `fin_holding` /
`fin_sim_order` / `fin_transaction` / `fin_market_price` 的既有引用自动跟随，
不产生孤儿数据。那笔历史成交保留 `quote_source='eastmoney_nav_fallback'` ——
它确实是当时的事实，不该被粉饰。同时清掉了 `fin_market_price` 里那条净值降级行，
全库净值降级行情行数归零。

## 2. 种子假行情会盖住真实行情（更严重，且会反复出现）

`seed_sim_account_demo.py` 原来按"今天"upsert 一条假行情（510300=4.50、
510500=6.20，`source='eastmoney_demo_seed'`），而真实行情来自行情源、日期是
**最近交易日**。下单按 `trade_date DESC` 取行情，这条种子行**永远排在真实行情前面**；
它的 `source_updated_at` 只是 seed 运行时刻，过了 `MAX_QUOTE_AGE`（15 分钟）就让整个
产品变成 `503 行情已过期` —— 而库里明明躺着一条刚同步好的真实行情。周末尤其明显：
`trade_date` 落在**非交易日**，价格还是编的。

实测表现：`tools/seed_demo_data.py` 跑完第 4 步刚同步过真实行情，冒烟脚本的下单仍报
`503`，且本该 4.579 的成交价被查到 4.50。

改为：**已有任何行情行就绝不插手**（真实行情优先，种子不参与竞争）；
一条都没有时才补，且 `trade_date` 退到最近交易日。

验证：`tools/e2e_smoke_test.py` → **40/40**（下单成交价 4.579 = 真实行情）；
ruff 通过；mypy 250 文件 0 错；unit+contract 1381 passed / 0 failed。
 2026-09-13 22:28:42 +08:00
lzf_0626 4629e7d5dd docs(44): 补一步风控助手演示（意图分派已修复，实测置信度 1.0） 2026-09-13 22:08:39 +08:00
lzf_0626 468ae0bd47 fix(admin): 激活意图不再归档同 Agent 的其他意图（风控 4 意图曾只剩 1 条生效） 
两个相关的缺陷，都属于**静默失效**型。

1. `admin_service._transition_intent_config`（真正的 bug）

   激活一个意图时按 `agent_type` 过滤旧 active 版本并归档，但唯一键是生成列
   `active_key = concat(agent_type, ':', intent_code)` —— 同一 `agent_type` 下
   **不同意图码本就允许并存**。于是激活 `general` 会把
   `risk_overview` / `risk_search` / `risk_evidence` 一并归档：风控运行期只剩 1 条
   active 意图，问"查看当前风险概览"被分到 `general`（confidence 0.5），
   而**没有任何报错**。该函数自己的 docstring 写的正是正确行为，实现与它不符。

2. `tools/publish_risk_agent_config.py`（使脚本无法自愈）

   按 `intent_code` 单键建 dict 收集现有意图，而列表**按 id 倒序**返回且同一意图码
   有多个版本，于是**旧版本覆盖新版本**；取到 v1 后再"版本 +1"算出的正是已被占用的
   v2，创建必然 409 IDEMPOTENCY_CONFLICT。现象是 4 条意图全部"创建失败"而库里
   其实都有，`tools/seed_demo_data.py` 第 7 步因此必然失败。

修复后实测：

- 库里 4 个风控意图全部 active；
- 问"查看当前风险概览" → `intent=risk_overview`、`confidence=1.0000`
  （修复前为 `general` / 0.5）；
- `tools/seed_demo_data.py` 10/10 步完成、退出码 0（修复前第 7 步退出码 1）。

回归测试：`test_activating_one_intent_does_not_archive_sibling_intents`。
已确认把修复回退后该用例**确实失败**（`['beta'] != ['alpha', 'beta']`），
不是永远通过的空测试 —— 原有用例盖不住这个缺陷，因为它建的第二个意图始终停在 draft、
从未激活过。

门禁：ruff 通过；mypy 250 文件 0 错；unit+contract 1381 passed / 0 failed；
integration 104 passed；e2e 冒烟 40/40。
 2026-09-13 22:08:04 +08:00
lzf_0626 760d960762 docs(AGENTS): 补一键启动/演示入口，并记下 BOM 与行情 15 分钟两个易错点 2026-09-13 21:56:59 +08:00
lzf_0626 bfd3964ef8 feat(demo): 演示数据一键准备、启动脚本与演示流程文档 
交付"别人能自己把系统跑起来做演示"所需的四件东西：

- tools/seed_demo_data.py      演示数据一键准备：10 步按依赖排序
  （此前散在 10 个脚本里，没人知道该跑哪些、按什么顺序跑，且知识库那步
  根本没有脚本、靠手工调接口）
- tools/seed_knowledge_demo.py 知识库演示素材灌入，幂等（先删同 source_file 再灌）
- start.ps1                    启动 API + Worker，含依赖检查与**自动刷新行情**
- docs/44-演示流程.md           8 个主线场景的照读流程 + 排障表 + 账号/命令速查

两条硬约束同时写进了脚本和文档：

1. **Worker 必须常驻**：没有它客服对话一直停在 queued（前端只显示"超时"）、
   新知识不进 Milvus 且**没有任何报错**。
2. **行情有效期仅 15 分钟**（`trade_service.MAX_QUOTE_AGE`）：超时后所有委托
   直接 503「行情已过期」，而系统**没有自动刷新机制**。故 start.ps1 启动时刷一次，
   文档另给"演示中途 503 时补刷、无需重启服务"的处置方法（已实测）。

实测证据：
- start.ps1 在 8099 完整启动，`/docs` 与 `/portal/` 均 HTTP 200（测试进程已清理）
- `tools/e2e_smoke_test.py` → 40/40 通过
- `tools/seed_demo_data.py --dry-run` → 10 步全部正常列出
- 文档中的下单命令实跑：510300 成交价 4.579、金额 457.90、手续费 0.05
 2026-09-13 21:56:27 +08:00
lzf_0626 f37fd922a1 fix(seed): 演示预警的状态口径与代码对齐，并补 closed_at 
## 结论：risk_action_service 没问题，我先前是误判


esolve（完成结案）写全了 status="已结案" + closed_at + handle_result（risk_action_service.py:105-107），
exclude 同样（:67-71）。我报的"结案没写 closed_at"看到的那条 ALDEMO0003
其实是**种子预置样本**，不是我以为的自己创建的那条 —— 我的冒烟脚本用
ALDEMO{时分秒} 命名，**撞上了种子的 ALDEMO0001-0003**，"已存在则跳过"把创建挡掉，
随后处置全 409，串起来就像"结案没写时间"。

真正的问题在种子数据，两处：

1) **状态口径与代码不一致**：ALDEMO0003 写成 status="已关闭"，而
   
isk_action_service 里**没有任何动作会产生这个状态**（状态机只有
   待处理 / 调查中 / 已排除 / 已结案）。演示时会被当成系统行为，排查时又查不到出处。
   按它的 close_reason 语义（低风险 + 已核验为正常交易），它就是**关闭误报** → 改为"已排除"。

2) **终态缺 closed_at**：那条有 close_reason 却没有 closed_at，自相矛盾；
   而且 
isk_repository 按 closed_at 统计"当日结案"，缺了它会被漏掉。
   INSERT 补上该列，样本用 closed_at_offset_minutes 给值。

## 顺带修掉冒烟脚本的撞号

预警编号前缀 ALDEMO → E2E，注释里写明原因 —— 免得下次又操作到种子样本、
还把现象当成新 bug。

## 验证

- ALDEMO0003 现为 status=已排除 + closed_at 有值
- 库里所有终态预警（已排除/已结案）都带 closed_at；进行中的（调查中）不带 —— 口径一致
- 自己创建的两条走 resolve 后 status=已结案 且 closed_at/handle_result 都有值
- 冒烟重跑：40/40 通过，新造预警编号 E2E134351，处置闭环三段全 PASS

门禁：ruff 通过 / mypy 250 文件 0 错 / 单元+契约 1381 passed 2 skipped。
 2026-09-13 21:44:08 +08:00
lzf_0626 2fcc4939e7 feat(tools): 新增全流程端到端冒烟脚本 e2e_smoke_test.py 
把验收清单里"能用接口判定"的部分自动化：6 条线 40 项，打真实 HTTP、逐条打印 PASS/FAIL。
不是 pytest 的替代 —— 单测看代码正确性，它看"部署后底座是不是活的"。

覆盖：
  A 访客  令牌 → 提问 → 收到回答 → 未转人工
  B 客户  登录 → 看板/持仓/流水 → 真实下单成交 → 委托详情 → 会话与转人工
  C 风控  概览/队列/详情/八类证据/通知/扫描 → 处置闭环（确认→调查→结案）
  D 投顾  已发布方案     E 运营  场外邮件与邮箱状态
  F 管理员 角色/权限/身份/配置发布/模型端点/审计/转人工工单/画像候选

两个实现细节值得留意：
- **各端点 data 形状不统一**（角色列表裸数组、持仓在 holdings、成交明细在 transactions、
  资金流水在 entries、知识列表不套 data），所以这里用 listed(payload, *keys) 依次尝试，
  并在注释里写明"别猜字段名"—— 我自己写联调脚本时连续猜错三次。
- 库里没有"待处理"预警时**自动造一条**再验证处置闭环，否则该环节只能跳过
  （实测库里的预警常常都已被处置过，第一次跑就跳过了）。

新增 --read-only：跳过所有写操作，用于生产或不想动数据时。

实测：40/40 通过（含真实下单 201 已成交、风控处置闭环三段全 PASS）。

docs/40 补上"一键冒烟"一节。
 2026-09-13 21:39:37 +08:00
lzf_0626 06f0dee39f feat(sync): 行情源覆盖不到的产品改用净值源降级（160129 现在也可下单） 
160129（南方金利定开债券C）在腾讯行情源上**查不到** —— 返回体只有 1 个字符，
换 sh/无前缀、换代码写法都不行；而它的 A 类 160128 正常返回 88 个字段。
判断它很可能未上市交易。但它在东财历史净值（1.0240 @09-11）与 pingzhongdata
（规模 3.91 亿）里都有数据，所以按"换一个源"处理：

- 新增净值降级路径 _nav_fallback：收盘价取 DWJZ、开高低用同值（该接口只给一个价格）、
  olume/	urnover **留空**（净值源不提供量额，不编数字）、总份额由季度规模推算。
- source 写成 eastmoney_nav_fallback，与行情源明确区分，便于日后核对。
- 降级请求放在**事务外**：最初写在落库循环里，会让网络请求拉长事务。

⚠️ **净值不等于市价**：若该产品确实在交易所交易，用它当收盘价会有折溢价偏差。
这条路径只落在"行情源没有覆盖"的产品上；且 160129 很可能本就不该出现在场内产品
列表里（同基金的 A/C 类只有 A 类上市），值得业务侧复核 —— 但按项目方要求先让它可用。

结果：20 只全部同步上（19 行 tencent_quote + 1 行 eastmoney_nav_fallback），
160129 下单 201 已成交 @1.024。

门禁：ruff 通过 / mypy 250 文件 0 错 / 单元+契约 1381 passed 2 skipped。
 2026-09-13 21:32:15 +08:00
lzf_0626 b6281ba6bc docs(40): 把行情同步列为下单前必跑的前置 
全流程验收时踩到：不跑 tools/sync_market_prices.py 就下单，只有 2 只产品有行情、
其余直接 503，而且错误信息只说"行情已过期"，看不出根因。把它写进第 0 节，
并说明数据源（腾讯行情 / 东财只有行情类域名不可达）与总份额口径。
 2026-09-13 21:15:43 +08:00
lzf_0626 369213f50d Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-13 21:14:22 +08:00
lzf_0626 87a753f7b3 feat(sync): 给 fin_market_price 补真实行情同步链路（下单前置） 
## 解决的问题

全流程验收时发现：**20 只产品里只有 2 只有行情，其余下单直接 503**；而且行情一旦过期
就**没有任何机制刷新**。根因是这张表此前**只有演示种子脚本写**，而它是下单的硬前置
（TradeService 要求 close_price>0、total_fund_shares>0、source_updated_at 在 MAX_QUOTE_AGE 内）。

## 数据源（踩了两个坑才选对）

1) **东财 push2 / push2his 两个行情域名在本环境一律连不上**
   （RemoteProtocolError: Server disconnected），而它的 api.fund（净值）与
   fundf10（概况/费率）**正常** —— 即东财只有"行情类"接口不可达。
   一开始按 K 线方案写完，20 只全失败；排查时还被我自己的 except 吞掉过异常。
2) 一度怀疑被限流，等 90 秒仍失败；做源可用性对照才确认是**域名级不可达**。

最终选**腾讯行情**（qt.gtimg.cn）：一次请求可带多只，给今开/最高/最低/现价/
成交量(手)/成交额(万元)/**总市值(亿元)**，正好够写一行日行情。
K 线能力仍保留在适配器里（别的网络环境可能可达），注释写明本环境不可用。

## 实现

- EastmoneyFundAdapter.fetch_tencent_quotes：解析腾讯的位置约定格式，只取语义明确的
  字段并对价格做合理性校验；成交额万元→元、成交量按"手"（与东财 K 线口径一致，实测同为 9666652）。
- MarketPriceSyncService（新）：编排 + 落库。总份额按
  「已有值 → 腾讯总市值推算 → 季度规模兜底」的优先级确定，source 标明是否含推算成分；
  三者都拿不到就**跳过该产品**，不编份额。
- 	ools/sync_market_prices.py（新）：CLI，演示/验收前跑一次。

## 另一个坑：非交易日的假行情行

种子脚本用 	rade_date = date.today() 写行情，而 2026-09-13 是**周六**、真实行情时间是
09-11 16:14。TradeService 取 order_by(trade_date.desc()).limit(1)，于是那两行假的"今天"
永远排在真实行情前面——表现是"同步成功了、下单还说行情过期"。已删除那两行。

## 验证

- 同步：请求 20 只、落库 19 行（160129 腾讯源没有该代码）
- 下单：510300 @4.579、510500 @7.611、159948 @3.693、511810 @100.012 全部 201 已成交
  —— 用的是**真实行情价**，不再是种子编的 4.5/6.2
- 风控处置闭环：新建 ALDEMO0003 后确认接收→进入调查→到达终态，
  ack_status=已确认、handler_id=9002

## 顺带发现的疑点（未改，留给风控线确认）

ALDEMO0003 到达终态时 status='已关闭' 但 **closed_at 与 handle_result 都是 NULL**；
对照 ALDEMO0001（已排除）则 closed_at 有值。结案时间是否应该写入，需业务侧确认。

门禁：ruff 通过 / mypy 250 文件 0 错 / 单元+契约 1380 passed 2 skipped。
 2026-09-13 21:14:13 +08:00
lzf_0626 de208a039d docs(40): 补全流程验收实测到的接口形状差异 
跑全流程 E2E 时连续踩到（都是调用方视角的真实摩擦点）：

- 各端点的 data 形状不统一：账户看板 data.account + data.summary、持仓 data.holdings、
  成交明细 data.transactions、资金流水 **data.entries**、角色列表 data（裸数组）、
  知识列表 items（不套 data）。我写脚本时连续猜错三个字段名，一度误判"资金流水没记录"。
- 创建类接口返回 201 而非 200：下单 T002、创建会话 C001、访客令牌 V001 都是 201。

两条都写进"通用预期"，并说明是实测结论。
 2026-09-13 20:40:16 +08:00
lzf_0626 e9c148f005 fix(sync): 行情同步改为逐只容错，避免一只坏代码拖垮全量 
全流程验收时发现的核心故障：**所有客户都无法下单**（任意产品都返回
503 FUND_QUOTE_UNAVAILABLE），而错误信息只说"某产品行情已过期"，看不出根因。

根因链：
1) MarketQuoteSyncService.sync() 把库里 fund_manager='南方基金' 的 20 只产品
   打包交给 hq.py 的 loader；
2) 而 hq.py 的白名单校验是 ny(code not in SOUTHERN_FUND_CODES) -> raise，
   **一个代码不在名单里整批就抛错**；
3) 库里混着 510300 —— 它的真实管理人是华泰柏瑞（前面查费率时确认过），
   不在南方基金白名单里 -> 两个数据源全部 ValueError -> quotes=0；
4) 于是 in_market_price 长期不更新（当时只有 2 行、时间停在 08:19），
   下单的 MAX_QUOTE_AGE 校验全线失败。

修法：整批调用失败时**降级为逐只调用**，保留能取到的行情，把被拒代码记进
source_results（并拼进 error_type，让它在 dvisor_market_quote_source_run
审计行里可见，不必为此改表）。被拒代码通常意味着 und_manager 标注有问题，
值得人工核对。

不动 hq.py 的白名单：那是刻意的防误用设计（不许拿任意代码查南方行情），
该容错的是编排层。

验证：重跑 tools/sync_advisor_market_quotes.py 后不再是全批失败；
配合重跑 tools/seed_sim_account_demo 刷新 fin_market_price，
下单恢复 —— 510500、510300 均 HTTP=201 已成交。

⚠️ 仍未解决（数据供给缺口，需要产品/业务侧决定）：
in_market_price 目前**只有演示种子脚本写**，没有生产同步链路。
后果是 20 只产品里只有 2 只（510300/510500）有行情、其余 18 只下单报
"缺少场内行情"，而且行情一旦过期就没有任何机制刷新。
 2026-09-13 20:39:36 +08:00
lzf_0626 ff37b0b476 docs(40): 记录知识治理端点的两处接口差异 
联调时踩到并查明（更正前一版判断：不是接口故障，是调用方解包方式不对）：

1) GET /api/v1/knowledge/list **不套 data 信封**，直接返回 {"items": [...], "count": N}，
   而多数端点返回 {"code":…, "data": {…}}。按 data.items 解包会拿到 0 条，
   看着像"库里没数据"——我据此误判过一次，也因此在重灌时没能用列表接口批量删除，
   改为按 id 逐个 DELETE。
2) 上传是 POST /api/v1/knowledge/upload（/documents 会 405）；
   DELETE /api/v1/knowledge/{id} 的语义是标记 expired + 投向量删除事件，不是物理删除。

两条都写进验收清单的"通用预期"，避免下一个人重复踩。
 2026-09-13 20:26:56 +08:00
lzf_0626 7fa4b4c4a5 feat(knowledge): 手册补「购买基金需要什么条件」一节并重灌 
排查「购买基金需要什么条件」仍转人工的根因：**不是检索缺陷，是知识覆盖不足**。
实测该问法下手册 1.1 节其实排第 1（score=0.5416），但低于 MID_SCORE(0.55)，
且与次优间隙只有 0.0195 < MIN_GAP(0.07)，所以按置信度规则转人工 —— 规则本身工作正常。
对照：手册里有对应条目的问法分数是 1.0 / 0.7946 / 0.7932，链路健康。

补 1.6 节「购买基金需要什么条件」，只写有依据的事实（开户状态、风险测评与等级匹配、
按手交易的整数倍委托），不编造资金门槛或资质要求。

重灌过程顺带发现：GET /api/v1/knowledge/list 返回 0 块，而 fin_knowledge_meta 当时
有 22 行 active —— 管理端列表与实际入库不一致，所以删除只能按 id 逐个走
DELETE /api/v1/knowledge/{id}。这条接口的问题单独记，不在本次改动范围。

重灌结果：旧 22 块标记过期并投删除事件，新 23 块写入；问「购买基金需要什么条件」
命中 1.6 节 score=0.7793（≥ HIGH_SCORE 0.75），客服从转人工变为直接作答（4.08s）。
 2026-09-13 20:25: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
lzf_0626 6f397ab513 feat(data): 510300 回填真实值并在产品页披露；511810 口径查清 
按项目方决定处理三件事。

## 510300（沪深300ETF）

决定：保留 fund_manager = "南方基金" 作演示口径，**不**改成"华泰柏瑞"
（改了它会退出 MarketQuoteSyncService 的同步范围，投顾与知识条目也不该再算自家产品），
但净值与费率改成真实值，并在产品页显式披露它不是本公司产品。

- 回填（tools/backfill_product_snapshot.py --codes 510300 --apply --overwrite）：
  current_nav 4.500000 → 4.5794、current_nav_at 同步为 2026-09-11 15:00:00、
  management_fee_rate 0.5000 → 0.15、custodian_fee_rate 0.1000 → 0.05
- 产品页披露：mock-data.js 给这只加 product_note，详情页新增提示块渲染它
  （"本产品为同指数参考产品，非本公司发行的基金，仅用于功能演示"）。
  同时把 mock 里这只的净值/费率也对齐真实值，避免出现"页面显示 mock 值、
  库里是真实值"两套数字。
- 产品详情页的 css/js 版本参数提到 20260913-5，避免旧缓存。

## 511810（货币ETF南方）

之前说它"三个数量级不一致"是**我比错了接口**：QUOTE_API 返的是**场内交易价格**
（货币 ETF 约 100 元/份），而 current_nav 的口径是 DWJZ 单位净值。
查证结果：库里 0.2661 正是 09-11 的真实 DWJZ，快照时间也对得上 —— 不是脏数据，是旧值。
口径由其余 19 只的一致性确定（current_nav == DWJZ）。
要不要刷新到最新（0.2332）属运维节奏问题，**本次未执行**。

## 最小交易金额

按项目方口径：一律**以产品字段为准**（100.00 元），不用「1 手 × 净值」推算金额 ——
后者会与字段值不一致，客户会看到两套数字。docs/42 的 1.1 节据此重写。

## 工具改名

tools/backfill_product_fees.py → tools/backfill_product_snapshot.py：扩展为
净值 + 费率统一入口，新增 --codes 限定范围（避免顺手把全部快照刷成最新，
全量刷新是 ProductHistorySyncService / MarketQuoteSyncService 的职责）。
安全设计不变：默认 dry-run、默认只补 NULL（净值永不为空，所以刷净值需显式
--overwrite）、写入走单事务。

门禁：ruff 通过 / mypy 249 文件 0 错 / 单元+契约 1377 passed 2 skipped。
 2026-09-13 19:47:10 +08:00
lzf_0626 02ba1befc0 feat(data): 取真实费率并回填 fin_product；发现 510300 的身份问题 
## 取费率

项目原有的行情适配器只有 names/quotes/history，没有费率。东财也没有可用的 JSON 接口
（`FundArchivesDatas.aspx?type=jjfl` 实测正文只有一句 `var apidata=`），
所以给 EastmoneyFundAdapter 加了 fetch_fees：抓 f10 基金概况页
（fundf10.eastmoney.com/jbgk_{code}.html）去标签后匹配字段名，取管理费/托管费/
销售服务费/申赎费，并顺带带回基金全称。取不到的基金不进返回（而不是给全 None），
免得调用方把"没抓到"当成"该基金确实没有费率"。

实测 20/20 全部取到。

## 回填

新增 tools/backfill_product_fees.py，默认 dry-run、默认只补 NULL：
- 只补空值：写入 38 个字段（19 只 × 管理费/托管费），已执行
- 已有值一律不动 —— `510300` 库里的 0.5000/0.1000 保持原样，要改需显式 --overwrite
- 写入走单事务

回填前 grep 确认：`fin_product.management_fee_rate` / `custodian_fee_rate`
**目前没有任何业务代码读取**（advisor 域那两个 fee 字段属于另一张表
advisor_product_contract），所以这次回填不改变任何现有行为。
要让客户真的看到费率，还需要接口与前端读它 —— 那不在本次范围。

## 两个数据问题（都指向 510300）

1) **它不是南方基金的产品**。数据源返回的基金全称是
   「华泰柏瑞沪深300交易型开放式指数证券投资基金」，而库里 fund_manager 写「南方基金」。
   其余 19 只全称都是"南方…"开头，只有它例外。
   影响面不只是知识库：MarketQuoteSyncService 按 fund_manager='南方基金' 筛选同步对象，
   所以它会被当成自家产品一起同步、一起展示。

2) **它的费率是照抄的**。库里 0.5000/0.1000，真实 0.15/0.05；而 0.50/0.10 恰好是
   159329/159382/159511/588890 这四只的真实费率。结合它的净值快照时间是当天
   （其余 19 只停在 09-11）、净值取整数 4.500000，判断是演示用途的人为设定。

这两条都由用户决定怎么处理，本次只记录、不擅自改（510300 的 fund_manager、净值、费率
三处原值都没动）。

## 其他

- tools/fetch_live_quotes.py 增加费率核对段落与 --no-fees（费率要串行抓 45KB/只，较慢）
- docs/42 用真实费率重写 1.2 节与新增 4.3 真实费率清单，3.1 节标出 510300 的身份问题
- docs/42 的数据缺口表更新：费率不再是缺口

门禁：ruff 通过 / mypy 249 文件 0 错 / 单元+契约 1377 passed 2 skipped。
 2026-09-13 19:39:16 +08:00
lzf_0626 f3af00e645 fix(trade): 补 from None 修掉 ruff B904；附 integration 抢队列的复现结论 
两件事，都源自组员 e3c316a（下单授权与适当性校验）合并之后：

1) ruff B904：app/service/trade_service.py 在 except 分支里抛
   SuitabilityMismatchError 时没写 from None/from exc，门禁因此变红。
   这里被捕获的是"风险等级字段解析失败"，对上层没有诊断价值，
   用 from None 截断因果链即可。

2) tests/integration 出现 2 个失败，**与代码无关**，是常驻 Agent Worker 抢队列：
   - 带 Worker 跑：102 passed / 2 failed
   - 停掉 Worker 跑：104 passed（已复现两次）
   失败用例是 test_complete_run_rolls_back_every_write_on_outbox_conflict 与
   test_cancel_is_idempotent_and_terminates_original_request，都是 run 队列相关 ——
   Worker 会把测试创建的 run 领走并执行，测试自己的状态机就乱了。
   这正是 docs/20 与 AGENTS.md「跑验收前先停常驻 Worker」那条的实际复现，
   顺手把结论写进 commit 备查：判断 integration 红不红之前，先确认 Worker 在不在跑。
 2026-09-13 19:30:59 +08:00
lzf_0626 d9d3420cf0 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-13 19:28:09 +08:00
lzf_0626 131effcfae feat(tools): 新增 fetch_live_quotes 拉真实行情并核对库里快照 
项目本来就对接了东方财富真实行情（app/infrastructure/fund_market_adapter.py：
push2.eastmoney.com 的行情接口 + api.fund.eastmoney.com 的历史净值接口），
下单链路取 quote_price/quote_source 走的也是它。之前做知识草稿时用的是
fin_product 表里的快照，没有去核对真实数据源，这次补上。

新增 tools/fetch_live_quotes.py：
- 用项目自带的 EastmoneyFundAdapter 取数，不自己拼 HTTP、不引第三方行情库
- 产品范围与 MarketQuoteSyncService.sync 一致（南方基金 / SSE,SZSE / 上市）
- 逐只对比真实净值与 fin_product.current_nav，只报告差异、**不写库**
  （刷新快照是 ProductHistorySyncService / MarketQuoteSyncService 的职责）

实测结果（2026-09-13，20 只全部取到真实数据）：
- 18 只完全一致（库里 6 位小数、数据源 4 位，是同一笔数）
- 2 只不一致：
  · 510300 沪深300ETF：库里 4.500000，真实 4.5794。库里快照时间是今天 08:19:37，
    其余 19 只都停在 09-11 15:00:00 —— 说明这是被人为改过的演示值（4.5 凑"1 手 450 元"）。
    需要定：知识用真实值还是演示值；若交易按库里的 4.5 成交而知识说 4.5794，两处口径会打架。
  · 511810 货币ETF南方：库里 0.266100，NAV_API 给 0.2332，而 QUOTE_API（场内实时价）
    给 100.012 —— 差三个数量级，说明两个接口对这只的含义不同，需人工核实口径。

docs/42 随之更新：
- 产品清单改用真实净值，并加上当日涨跌与净值日期，注明取数来源与复现命令
- 3.1 节的沪深300ETF 条目改用真实值 4.5794，并列出两处待确认口径
- 新增 4.2 节记录本次核对结果与两只不一致项的判断依据
 2026-09-13 19:27:58 +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
lzf_0626 52ae38efd7 docs(40): 补齐前端验收清单（投顾/运营页、访客浮窗、Worker 前置） 
- 关键修正：第 0 节原先写「停常驻 Worker」，方向是反的 —— 客服对话**必须**有
  Worker，否则 agent_run 停在 queued，前端只显示超时。补上排查第一步（查最新
  那行的 status）与本机实测延迟（端到端 4.1-4.8 秒，受理只占 0.05 秒）。
- 新增第 6 节投顾工作台：数据口径（本人 + 名下归属客户，不用 data_scope）、
  方案书审核与发布必须由管理员做（admin=True）、归属数据不随环境走。
- 新增第 7 节运营工作台，含客户/风控访问被 403 拦的实测。
- 新增 2.5 节访客客服浮窗：访客令牌的角色与权限、访客与客户走不同检索工具名。
- 新增第 9 节「看起来像 bug、其实是设计」：置信度阈值 0.75/0.55/0.07 与三条实测
  分数逐条对应（0.8203 直接答；0.6818 但间隙 0.0034 转人工；0.5221 转人工），
  说明「总转人工」的根因在知识库内容而不是代码；另两条是投顾接口非越权、
  方案书复核环节。
- 第 1 节更新为 18 个页面路径 + 12 个静态资源，全部 200（实测值）。
- 第 10 节补入本轮修的 4 个问题（角色落点、访客白名单、mock 声明、发布脚本丢提示词）。
- 新增第 11 节已知未修：知识库无场内 ETF 内容、fin_knowledge_meta 与 Milvus 不一致
  （列表接口实测 count=0）、品牌名三处不一致、ADVISOR_GOAL/ANALYSIS 声明未用等。
- 附录补演示账号，并注明 9006/9020 的口令不在 set_user_password.py 的演示规则里。
 2026-09-13 19:10:21 +08:00
lzf_0626 680c2a0749 docs(AGENTS): 补 Worker 常驻与发布脚本继承范围的踩坑记录 
- 新增一条：客服/风控对话必须有常驻 Worker（python -m app.worker）。没有它时
  agent_run 停在 status=queued、worker_id 为空，前端只会显示"客服响应超时/繁忙"
  —— 看起来像链路慢，实际是没人处理。附排查第一步（查 agent_run 最新那行）
  与本机实测延迟（端到端 4.1-4.8 秒，其中受理只占 0.05 秒）。
- 更新发布脚本那条：继承范围必须覆盖全部三张受管表（此前只搬 platform_config_item，
  把 customer_service_chitchat 提示词静默漏在旧版本里），并写明知识类意图要同时发
  search_knowledge 与 query_knowledge。
 2026-09-13 19:04:29 +08:00
lzf_0626 2098185477 fix(portal): 客服浮窗轮询参数调整，压感知延迟并留足超时预算 
现象：访客在公开页问客服，等约 9.5 秒后报「客服响应超时」。
根因不在链路快慢 —— Agent Worker 没在跑，run 一直停在 queued，
前端把「没人处理」呈现成了「超时」。

启动 Worker 后实测同一条链路（受理 0.05s + 意图分类 + 知识检索 + 落库）：
4.11s / 4.09s / 4.82s，三条全部 succeeded。模型已经是 deepseek-flash，
延迟主要来自一次意图分类加一次 embedding，不是模型选型问题。

不过原来的轮询参数余量确实偏薄：350ms 后首次、之后每 700ms 一次、共 14 次，
约 9.5 秒封顶，后端稍一抖动就撞上；而且平均要多等半个轮询周期才看到结果。
改为 300ms 后首次、之后每 500ms 一次、共 40 次（约 20 秒）：
感知延迟压到半秒内，同时给模型与检索抖动留出余量。
超时文案也从「客服响应超时，请稍后重试」改为「客服繁忙，暂时没能给出答复」，
不再暗示是响应慢。代码注释里写明：若仍然超时，先确认 Agent Worker 已启动。
 2026-09-13 19:03:49 +08:00
lzf_0626 d4a895c643 fix: 修好访客客服浮窗、投顾工作台数据口径，恢复访客页来源声明 
组员这次提交的两套新页面方向都对，但各有一处"接不上"的地方，这里补齐。

1) 访客客服浮窗（此前一问即失败）
   客服 Agent 让访客走 query_knowledge（访客令牌的角色是 visitor、权限只有
   agent:run + knowledge:query），但发布配置里三个知识意图只发了 search_knowledge，
   于是 ToolExecutor 直接抛 ForbiddenAgentError，而客服代码对白名单失败是
   「必须冒泡」的 —— 访客拿不到任何回答，登录客户侧却完全正常。
   发布脚本的知识类意图改为同时发 search_knowledge 与 query_knowledge：
   访客走前者、客户走后者，缺任一条对应人群就失败关闭。
   （suitability_check 不发 query_knowledge：访客意图白名单不含它，访客到不了。）

2) 发布脚本会静默丢提示词
   旧写法只查 platform_config_item 就当作"继承"，而 config_release 是整版本替换
   语义，新版本没带上的行等于被删除 —— 实际把 customer_service_chitchat 提示词
   漏在了旧版本里（admin 端只在激活时打一句 stderr 警告）。
   改为走 ConfigReleaseService.effective_snapshot() 读全三张受管表，补上提示词
   搬运（version 重分配、带上 input_schema/output_schema），并在激活后硬校验
   配置项与提示词条数，条数不符即失败退出。
   （model_routing_rule 本环境为空；不为空则直接中止，不假装支持。）
   丢失的那条提示词已按原文恢复，active 版本现为 9 条配置项 + 1 条提示词。

3) 投顾工作台永远为空
   published() 取的是 customer_id == 自己 user_id，而投顾是员工账号、不可能是
   客户；且只认 advisor_recommendation_plan + approved，而投顾交付的主产物是
   investment_goal_book，发布后状态是 published。三重不匹配下页面永远显示空态。
   改为按「本人 + sys_customer_assignment 里名下归属客户」过滤（不用 data_scope：
   投顾因持有 all 级权限会把整个身份的 scope 抬到 all，那会放开到全部客户），
   并覆盖两类 content_type 与两种已发布取值。
   实测：投顾可见归属客户 9001 的方案书，客户仍只见自己的，风控仍 403。

4) 访客页把"演示数据"声明删了但假数据还在
   mock-data.js 的 MOCK_SOURCE_NOTICE 与两个页面的 data-source-notice 区块被删除，
   而 MOCK_PRODUCTS/MOCK_RANKING_CHANGE 仍在渲染（详情页含历史净值曲线）。
   恢复声明常量、页面区块与样式，并给 products/product-detail 的 link 与 script
   加上版本参数 —— 此前没有版本号，浏览器会命中旧缓存，改动看不见。

其他：投顾页显示交付物类型与客户编号（后端新返回的字段），README 补上投顾页
数据口径、访客/客户两条检索工具的差别，以及"渲染 mock 必须带来源声明"的约定。
 2026-09-13 18:54:09 +08:00
lzf_0626 4fdf1762e6 docs: 验收清单改为面向正式前端 /portal/ 2026-09-13 16:22:25 +08:00
lzf_0626 5b6eaddc4f docs: AGENTS.md 补正式前端口径与最新测试基线；portal.py 标注为调试工具 
- 新增前端一节：app/static/portal/ 挂载在 /portal/，四套页面，端点表在 common/api-client.js，
  启动用 uvicorn app.main:app（模块级变量是 app 不是 application）
- 测试基线更新为 2026-09-13 实测：mypy 249 文件 0 错 / 单元+契约 1376 passed / 集成 104 passed
- tools/portal.py 文件头标注降级为跨角色联调工具
 2026-09-13 16:20:39 +08:00
lzf_0626 f4eaa2f631 fix(seed): 客户种子改为已开户；portal.py 标注为调试工具 
- seed_test_rbac.py 把 fund_account_status 硬编码成 'closed'，与 create_test_user.py
  的 {customer: 已开户, employee: closed} 口径不一致，导致种子建的客户永远未开户
- 影响：GET /users/me/account/dashboard、/users/me/cash-ledger 恒返回 404，
  正式前端 T001/T009 两个页面打不开（端点本身是好的）
- 改为按 user_type 取状态；配合 tools/seed_sim_account_demo.py 开虚拟资金账户后
  T001/T006/T007/T009 全部 200
- tools/portal.py：正式前端已在 app/static/portal/，本工具降级为跨角色联调工具
 2026-09-13 16:19:54 +08:00
lzf_0626 f7f43742fd chore: 移除误提交的 .agents/skills 与 skills-lock.json（AI 助手配置，与项目无关） 
- 这 15 个文件随 e38ece3 前端提交一起进了仓库，内容与本项目无关
- 用 git rm --cached 从索引移除（本地文件保留），并加入 .gitignore
 2026-09-13 16:17:00 +08:00
lzf_0626 bbe575f38f fix(portal): 模态打不开时立刻 resolve，避免 await 永久挂起（表现为点击没反应） 
- askConfirm/askText 在 openModal 失败时立即 resolve(false)/resolve(null)：
  此前 Promise 永不 resolve，await 会一直挂着，用户看到的就是点了没反应
- toast/openModal 在容器缺失时给出明确提示而不是静默失败
- 顶栏显示页面构建时间（取 portal.py 修改时间），用于一眼确认加载的不是缓存旧页
 2026-09-12 16:41:26 +08:00
lzf_0626 280c8e5026 docs: 清单风控章节按 17- 前端合并约束重写（15 项，含实测证据与三个坑） 2026-09-12 16:31:55 +08:00
lzf_0626 167a4e7162 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-12 16:30:56 +08:00
lzf_0626 6155f4589e feat(portal): 按风控前端合并约束重写风控工作台 
- 概览五指标（总量/等级/待处理/超时/重点预警）
- 预警队列：每页 5 条、风险等级优先、8 项筛选、游标分页、稳定行高与省略号
- 预警详情弹窗：23 个 alert 字段 + 客户信息 + 五个处置动作
- 处置：确认接收（二次确认）/进入调查/关闭误报（必填理由）/结案（必填结论）/升级（必填原因）
- 八类证据（customers/products/transactions/capital_flows/holdings/login_records/
  alerts/notifications）+ 五项筛选；注意是 holdings 不是 positions
- 通知记录、日报 SSE 流式生成 + 内容编辑 + 多邮箱发送
- 新增 Toast + 模态框，替换全部 17 处原生 alert（17- 文档明令禁止原生弹窗）
- 风险等级筛选值改用 高/中/低（预警对象用「高」，概览 levels 用「高风险」，口径不一致）
 2026-09-12 16:30:54 +08:00
lzf_0626 cb13f9cf45 fix(types): trade_service._next_id 的 model 参数标注改为 Any（mypy: type 无 id 属性） 2026-09-12 16:30:54 +08:00
lzf_0626 6e916aab03 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-12 16:08:39 +08:00
lzf_0626 76923d7e8b fix(portal): 补齐写操作的必填 body（风控升级/解决、场外六个写接口） 
- 风控：escalations 要 reason、resolutions 要 resolution（字段名不同），
  且真实顺序是 先确认接收 才能升级/解决（否则 409 请先确认接收预警）
- 场外：六个写接口都必填 operator_id（防伪校验，须等于当前登录用户），
  confirmations 还要 decision(中文枚举)、notifications 还要 notification_type、
  recalculate 要 fund_code+application_date；门户自动带当前 user_id
- 实测：recalculate 200 code=0；不传 operator_id 必得 422（证明该字段必须）
- 清单 §3/§4 更新为实测结果并列出各写接口的必填字段表
 2026-09-12 16:08:38 +08:00
lzf_0626 552055ee2d fix(portal): 修风控预警列表 422（limit 上限是 5，改为不传）；运营邮件改用 page/page_size；审计 limit 钳制到 1-100 
- risk/alerts 传 limit=20 会 422 query.limit<=5，导致整张表格渲染不出来、
  行内确认/升级/解决按钮随之消失 —— 这正是验收清单 3-3/3-6~3-9 看不到功能的原因
- 实测列表返回 2 条预警；处置接口有状态前置条件（409 = 当前状态不允许）
- 清单 3-3/3-6 更新为实测结果并写明 limit 上限与状态机约束
 2026-09-12 16:03:22 +08:00
lzf_0626 49ebda4cb7 docs: 新增前端验收清单（64 项，逐项给出预期结果，区分实测与按契约） 2026-09-12 15:48:31 +08:00
lzf_0626 2525fbdad9 feat(portal): 推广材料补成完整流程向导，并改为按 body.code 判成败 
- 投顾视图：创建 -> 补结构化输入(含七项费率) -> 生成 -> 投递 -> 查询
  生成后自动把 material_version_id 填进投递框
- 管理员视图：新增推广材料审核（promotion:review 只给管理员，职责分离）
- 统一结果渲染改看 body.code：本平台业务失败也返回 HTTP 200
  （生成失败是 HTTP 200 + code=422 + '材料内容未通过合规校验'）
- 输入骨架刻意不预填业绩（performance_info 有 show_* 开关可关），
  费率填占位文本以便跑通流程；真实材料必须换成真实值
 2026-09-12 15:45:09 +08:00
lzf_0626 615032ab00 fix: 修 POST /api/v1/conversations 的 MissingGreenlet（会话建不出来导致转人工 404） 
- public_platform_service: 创建 ConversationSession 时显式赋值四个 server_default 时间列，
  否则 flush() 后需回读数据库生成值，在 async session 里以同步属性访问触发
  MissingGreenlet，接口 500，连带转人工一直报会话不存在
- portal: 客服改用 C001 真实建会话；转人工改传 reason_code/reason_detail（原 reason 属额外字段 422）
- portal: 投顾查客户投资目标走 customers/{id} 变体
- seed/grant: 补 investment-goal:{read,write,confirm}:customer 三个动态拼出的权限码
  （data_scope=own_customers，投顾只看名下客户）
 2026-09-12 15:37:36 +08:00
lzf_0626 14f5078491 Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 2026-09-12 15:21:36 +08:00