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
55 Commits
Author SHA1 Message Date
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 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 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 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
yuancong_0626 2548c39c6b 袁聪的最后一次完善更新 2026-09-14 18:13:10 +08:00
张胜宇 f5d1b24618 merge qyqy_develop and retain risk review updates 2026-09-14 01:41:02 +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 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
zhangshy 2f3138113f Merge remote-tracking branch 'origin/qyqy_develop' into RM2_develop 2026-09-13 23:52:17 +08:00
zhangshy 2a3146e050 增加风控列表总数并优化站内提醒 2026-09-13 23:51:45 +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 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
张胜宇 e3c316aafb Enforce trading authorization and suitability checks 2026-09-13 19:24:59 +08:00
zhangshy 001ba065df Merge remote-tracking branch 'origin/qyqy_develop' into RM2_develop 2026-09-12 16:12:02 +08:00
zhangshy eb4e895e4e 修复高风险预警邮件通知并补充测试 2026-09-12 15:56:50 +08:00
张胜宇 ebc3fe4cbe feat(§T): 账户看板 + 场内模拟交易 9 端点（用户自助首版） 
新增 §T 用户自助段（docs/05 §19 新号段 7 个 = A×40/C×7/K×4/M×4/O×3/R×4/T×9）：

- T001 GET /api/v1/users/me/account/dashboard  — 账户/资金/持仓/盈亏汇总

- T002 POST /api/v1/users/me/orders  — 委托提交（首版 market 立即全额成交）

- T003 / T004 / T005  委托列表/详情/撤单

- T006 GET /api/v1/users/me/holdings  — 持仓列表（含市值/盈亏/当日盈亏）

- T007 / T008  成交记录列表/详情

- T009 GET /api/v1/users/me/cash-ledger  — 资金账本

要点（与 docs/00 §6.6 一致）：

- 首版市价委托立即全额成交，不实现撮合队列/部分成交；T005 撤单首版对任何在场委托返回 ORDER_NOT_CANCELLABLE (409)

- 价格来源复用 base FundQuoteService；service 层不二次封装（满足 AGENTS 第 2 条）

- 首版风控 3 条硬性：产品可交易、客户适当性、持仓比例上限（fin_market_price 缺失或过期 → 拒绝买入）

- 数据库零修改：10 张 fin_* 表全部 docs/00 既定，本批 PR 改列类型与可空性均 0；底座实际偏差（id 无 AUTO_INCREMENT、所谓'生成列'是普通 NOT NULL）由 service _next_id / 业务派生值补偿

注册 API：9 端点均注册进 app.main；user=9001(cust)'s id 写账

权限码（tools/seed_test_rbac.py 同步登记 + CUSTOMER 全量）：

  9047 account:read:self

  9048 trade:order:create

  9049 trade:order:read

  9050 trade:order:cancel

  9051 holding:read:self

  9052 trade:txn:read

错误码（app/core/errors.py + docs/05 §3.6 + tests/unit/core/test_errors.py DOCUMENTED 三方同步）：

  404 ACCOUNT_NOT_FOUND / ORDER_NOT_FOUND

  409 ORDER_NOT_CANCELLABLE

  422 INSUFFICIENT_FUNDS / INSUFFICIENT_HOLDING / HOLDING_RATIO_EXCEEDED / SUITABILITY_MISMATCH / PRODUCT_NOT_TRADABLE

  503 FUND_QUOTE_UNAVAILABLE（可重试）

新增：app/api/controllers/trading.py / app/api/schemas/trading.py / app/service/trade_service.py / tools/seed_sim_account_demo.py / tests/unit/service/test_trade_service.py(unit×8) / tests/contract/test_trading_endpoint_contract.py(contract×11)

修改：app/main.py(挂载 controller) / app/core/errors.py(10 新异常类) / tools/seed_test_rbac.py / docs/05-接口文档.md(§19 T001-T009 + §3.6 9 新码) / tests/unit/core/test_errors.py(DOCUMENTED 同步)

门禁：pytest tests/unit tests/contract 1313 passed (+19 新增) / ruff all clean / 三道守卫全过
 2026-09-12 15:50:37 +08:00
yuancong_0626 a501060e50 merge: merge yc into qyqy_develop 2026-09-12 12:50:14 +08:00
yuancong_0626 91f5373cfb 袁聪的第三次提交，API接口完善 2026-09-12 12:20:01 +08:00
张胜宇 e85989b344 merge: integrate latest qyqy_develop (auth login + RBAC read) into ZSY branch 
Incremental merge on top of ef701c8, which already integrated the earlier qyqy base bbf623a. qyqy_develop only added commits on top of bbf623a, so this merge is conflict-free. Incoming: account/password login (POST /api/v1/auth/tokens), RBAC read-only query API, rate limit dependency, login test console and user management tools. Additive changes in app/main.py, requirements.txt and pyproject.toml from both sides are all preserved. ZSY side capabilities (visitor tokens, customer service agent, knowledge retrieval, profile projection) are unchanged.
 2026-09-12 10:37:53 +08:00
张胜宇 ef701c844c merge: integrate ZSY customer service and profile capabilities 2026-09-11 22:31:51 +08:00
lzf_0626 c4a73b735e Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop 
# Conflicts:
#	app/main.py
 2026-09-11 21:41:04 +08:00
lzf_0626 6812fbe317 B1：RBAC 只读查询接口（4 个）+ docs/05 登记 A035-A038 
在此之前，权限只能靠脚本改，平台里**没有任何地方能看"谁能访问什么"**。
B1 先把"看得见"做出来：

- GET /api/v1/admin/roles                            角色清单 + 权限数 + 在用人数
- GET /api/v1/admin/roles/{role_code}                角色详情
- GET /api/v1/admin/roles/{role_code}/permissions    权限清单（按权限码排序，
                                                     便于与各 Service 的 require() 对照）
- GET /api/v1/admin/users/{user_id}/roles            某人**实际解析出来**的角色/权限/数据范围

几个刻意的决定：

1. 权限码复用 `audit:read` 而不新增 `rbac:read`：这份清单本身就是审计材料，且复用是零数据
   改动、立刻可用（新增权限码要先改 sys_permission，而它目前由 seed_test_rbac.py 以
   DELETE 重建语义管理）。将来要细分再加，不冲突。
2. `/users/{id}/roles` 直接复用 IdentityService.resolve，不自己拼 SQL —— 那正是请求进来时
   走的链路（status 检查、assigned_at/expires_at 时间窗、data_scope 取最高、客户分配）。
   自己写一遍必然漂移，而"这里查出的权限"与"实际能用的权限"不一致比没有这个接口更糟。
   测试里加了一条交叉验证：该接口的 roles/data_scope 必须与登录响应完全一致。
3. 停用账号返回**空权限集**而不是 404 —— 用户存在但拿不到权限，如实呈现比 404 更利于排障。
4. 角色详情与权限清单分开：权限为空的角色不该被误判成"角色不存在"。
5. 全部只读、不写审计（它们返回的就是审计材料本身），docs/05 §19 登记时审计列标"否"。

权限变更（提权/降权）仍无接口 —— docs/05 §19 已注明那不是遗漏，而是需要单独评审
（审计留痕 + 禁止自我提权 + 保护内置角色三条红线）。

另：确认了 load_context 对 sys_user_role.expires_at 是有过滤的（assigned_at<=now AND
(expires_at IS NULL OR expires_at>now)），我上一轮只读了半段 SQL 差点误报。

验证：ruff 干净 / mypy 185 文件 0 错 / 文档守卫 38 份无编号冲突 /
unit+contract 1140 passed / integration 98 passed（本批新增 8 个）。
 2026-09-11 21:22:56 +08:00
Windows bbf623a464 merge: integrate advisor capabilities on latest qyqy base 2026-09-11 21:03:58 +08:00
lzf_0626 01ee68034d 新增登录接口：账号密码换访问令牌（POST /api/v1/auth/tokens） 
背景：客户 / 员工 / 管理员三种身份此前无法区分。但区分逻辑其实早就完备 ——
bootstrap.py 里各 Agent 的 allowed_roles 一直是分开的（CustomerServiceAgent 只要
customer、RiskAgent 要 risk_operator/admin、PlatformProbeAgent 只要 admin），
唯独缺"怎么证明你是谁"；sys_user.password_hash 字段也一直存在，只是全是占位符
（种子写 'x'、worker 身份写 !worker-only-no-password-login!），从没写过真实密码。

实现：
- app/service/auth_service.py：bcrypt 校验 + 签发只含 sub 的 JWT + 审计。令牌里只放 sub
  是刻意的：角色/权限/数据范围由 IdentityService 每次请求查库解析
  （identity_repository.load_context），权限变更因此立即生效，现有鉴权链路一行未改。
- app/api/controllers/auth.py + app/api/schemas/auth.py：POST /api/v1/auth/tokens，
  响应含 roles/data_scope 供前端决定进哪个界面（鉴权仍以库里实时数据为准）。
- tools/set_user_password.py：设密码（客户 123456 / 员工 666666 / 管理员 88888888）。
  ⚠️ 脚本与文档均标注"仅限演示环境"，这三种弱口令上线前必须更换。
- pyproject / requirements 加 bcrypt（cryptography 只用于 JWT，不提供密码哈希）。

安全约定（逐条有实现与测试）：失败不区分原因 —— 用户不存在/密码错/账号停用返回同一条
401，否则接口就成了账号枚举器；用户不存在时也跑一次 bcrypt 以抹掉时序差异；
成功与失败都写 interaction_audit（actor_id 可空正是为失败场景准备的）；绝不记录密码。

过程中踩到一个自己挖的坑：给登录路由挂了通用的 enforce_rate_limit，而它声明依赖
build_request_context ⇒ 变成"要登录先登录"，所有登录都 401。改为新增
enforce_login_rate_limit：按客户端 IP 独立限流（60 秒 10 次）、不依赖认证上下文。
集成测试据此调整：注入恒放行替身隔离跨用例的计数累积，同时保留一个恒超限用例验证闸门
确实会拦 —— 不能因为加了替身就把这道防线测丢。

接口登记：docs/05 §19 加 A034；并更新 §11 —— 那里原写"JWT 签发、刷新、注销由统一身份
认证模块负责，Agent 平台不重复实现"，现注明平台只做登录这一步，刷新/注销仍归该模块。

验证：ruff 干净 / mypy 183 文件 0 错 / 文档守卫 37 份无重号（此前因 docs/21 重号失败）/
unit+contract 1140 passed / integration 90 passed。
 2026-09-11 20:43:21 +08:00
Windows f5dd5b8ba2 feat: add advisor rollout gate and rollback playbook 2026-09-11 20:28:21 +08:00
qyqy 636dcbbe7e chore: 修我文件里的 mypy 类型错误（8 处） 
源自评审 §1.4「数字不可比」引发的核查，结论比预想更有价值：

**mypy 报错的主因不是代码质量，而是本机缺 SQLAlchemy 2.0 的类型信息。**
装上 `sqlalchemy2-stubs` 后 181 → 43（该类存根是 2.0 之前的旧包，会换一批新错：
`mapped_column`/`DeclarativeBase` 不存在），卸载后回到 184。**本机 mypy 数字不可作为
质量结论，双方也不可比。** 但那 184 里有 8 个是**我文件里的真实错误**，已修：

- `knowledge_retrieval_service`：返回类型 `Mapping` → `dict`（回表后要就地补写
  `score`/`intent`，而 `Mapping` 是只读协议）；`ids` 显式标注并过滤 `None`；
  去掉 3 处已失效的 `type: ignore`（strict 下 unused-ignore 本身是错误）
- `knowledge_management`：服务工厂返回类型 `Any` → `KnowledgeManagementService`
  （`TYPE_CHECKING` 期导入，运行时仍惰性，不引入循环依赖），消掉 3 个 `no-any-return`

未动的：`model_gateway` 2 处 `dict-item`（`ModelEndpointConfig` 实际具备协议要求的
全部字段，属 SQLAlchemy `Mapped[T]` 在缺存根时的消解问题，不是真缺陷，不用 cast 掩盖）。
 2026-09-11 19:13:43 +08:00
qyqy 7677aeaee1 merge: 并入同事的场外申购/推广/行情/NL2SQL 线（11 提交、334 文件） 
冲突仅 3 个文件，全部取并集（双方都没有需要丢弃的改动）：
- app/main.py：import 双方路由（我方 knowledge_management + 同事的 offsite_fund/
  promotion_material）；include_router 段本已自动合并
- app/service/agent/bootstrap.py：import 与工具注册均取并集
  （query_customer_profile + query_financial_data 都注册）
- tests/integration/test_config_release_mysql.py：outbox 清理同时保留
  架构师的 event_type 限定（防误删其它域 outbox 行）与同事新增的 peer_release_id

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

边界核对：同事的场外代码未写入场内交易表（fin_sim_order/fin_capital_flow/fin_cash_ledger），
符合 AGENTS.md 规则 8。
 2026-09-11 18:56:26 +08:00
张胜宇 a769130658 feat: add profile candidate review workflow 2026-09-11 17:47:06 +08:00
yuancong_0626 3f7c5ca74f merge: 同步 origin/qyqy_develop（风控扫描、知识检索、客服 Agent、协商等） 
冲突处理：均为双方各自新增，按并集保留——
- .gitignore：本地 data/logs 忽略项 + 远端 .dsh-drop/
- app/core/config.py：offsite/promotion 与 risk_scan 配置项并存
- app/service/agent/bootstrap.py：场外/推介/风控/NL2SQL/知识检索 工具与 Agent 全部注册
- app/worker/__main__.py：场外邮件 Worker 接线 + runtime 关系服务/投影清理注入并存

收尾：新增 20260911_merge_risk_heads 收敛迁移双 head；按 docs/21 生成 config/jwt/dev 开发密钥。
 2026-09-11 17:32:47 +08:00
yuancong_0626 61861cdef6 袁聪merge：合并分支 2026-09-11 17:26:18 +08:00
yuancong_0626 fd9598efdf 袁聪的第二次提交，项目已完整 2026-09-11 16:57:47 +08:00
Windows 852bafb374 feat: add profile drift governance workflow 2026-09-11 16:42:31 +08:00
张胜宇 ef098e6a4b feat: complete customer service safety and handover flow 2026-09-11 16:11:30 +08:00
qyqy cbd6de2721 Merge remote-tracking branch 'origin/qyqy_develop' into nl-merge-latest 
# Conflicts:
#	app/service/model_gateway.py
 2026-09-11 15:38:11 +08:00
Windows e8ec0af398 feat: add advisor recommendation review flow 2026-09-11 15:33:27 +08:00
lzf_0626 8d79bd9767 补齐三个成功响应缺失的 meta 信封；信封实现抽为公共（docs/05 §3.3） 
"缺 meta"很容易被误判成"有"：X-Trace-ID 是**响应头**（中间件加），和 body 里的
meta.trace_id 是两件事；错误响应一直有 meta（异常处理器统一加），漏的只有成功路径。

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

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

改动：

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

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

门禁：ruff 干净 / mypy 138 文件 / 696 unit+contract / 33 integration。
 2026-09-11 15:21:36 +08:00
Windows 13bb4f257d feat: add allocation backtest evidence 2026-09-11 15:08:37 +08:00
wangjianlong_0626 e4c4099aaa wip: 客服Agent + RAG + 画像收尾（基于 6516ccb） 2026-09-11 14:46:40 +08:00
Windows ff71a1a724 feat: add dynamic advisor asset allocation 2026-09-11 14:44:29 +08:00
lzf_0626 15866d4564 风控写接口接入平台幂等（docs/25 P3 #22） 
docs/05 §5.1 把"业务写接口"列为必须携带 Idempotency-Key 的接口，风控 6 个 POST
（手工扫描、确认接收、进入调查、关闭误报、完成结案、升级处理）此前一个都没带，
重复提交会二次驱动状态机。

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

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

测试：单测加幂等透传替身与"缺键即 422"用例；新增
tests/integration/test_risk_idempotency_mysql.py，覆盖同键回放不重复执行、同键不同
正文 409、缺键/非 ASCII 拒绝，以及端到端"重复 POST 只调用一次处置逻辑"。
 2026-09-11 14:12:56 +08:00
lzf_0626 790518114b 风控 SSE 内容协商与鉴权时序；docs/05 补齐 413 与风控入口（docs/25 P3 #23 #24 #25） 
#23：413 是上传超限的标准语义，前端文档（风控业务演示文档 17）也已按 413 做提示
映射，所以不把代码降成 422，而是在 docs/05 §3.5 状态码表补登 413 —— 契约以"补齐"
而不是"改动"的方式对齐。

#24：/api/v1/risk/daily-report/stream 此前既不校验 Accept，又把鉴权留在 async
generator 内部。后者更隐蔽：StreamingResponse 已经返回、响应头已经发出，403 只能
变成"200 + 半截流"。现在 controller 先 await service.authorize(context) 再判定
Accept，顺序与 §6.4 一致（鉴权先行，不用状态码差异做探测）。SSE 协商逻辑抽到
app/api/dependencies/negotiation.py，与 /agent-runs/{run_id}/events 共用同一口径，
避免同一种客户端在一个端点上 200、另一个端点上 406。

#25：复核后确认前半段不成立 —— §19 末尾写明业务域接口由各自业务文档登记，风控 15 条
端点已在 06-模块接口与字段映射.md 逐条登记。真问题是 §12 表里写的
/api/v1/risk-scans/**、/api/v1/risk-alerts/** 与实际实现 /api/v1/risk/** 不符，
按实际实现更新 §12 并加说明；顺带把风控文档里 /daily-report/mail 的权限从
"按主项目邮件策略执行"改为实际的 risk:report:mail。

新增 tests/unit/api/test_risk_stream_negotiation.py（7 例）。
 2026-09-11 14:08:55 +08:00
lzf_0626 e8b075bc7f fix(risk): 列表接口的信封对齐 docs/05 §3.3——游标从 data 挪到 meta 
docs/05 §3.3 的列表样例是 data 为**纯数组**、
ext_cursor 与 has_more 放在 meta 里，
并明确「业务接口不得增加其他顶层字段」。而 RiskQueryService._page 返回的
{items, next_cursor, has_more} 被**整体塞进 data** —— 游标因此出现在**业务数据**里，
meta 只剩 trace_id，两处都不符合契约。

改动：
- 新增 _list_envelope(page, context)：把 _page 的结构拆成 data = items、
  meta = {trace_id, next_cursor, has_more}。**service 侧不动** —— 它继续返回那个内部
  结构，只是不再直接当 data 用。
- 3 个列表端点改用它：/alerts、/evidence/{source}、/notifications。
  非列表端点（overview、详情、各类写操作）保持原样，不带游标。

**影响调用方**：这是接口形状变更。组员若写了前端读 data.items，需要改成读 data、
并从 meta 取分页元数据。改动依据是 docs/05 这个唯一权威接口文档（§20 也要求实现与
文档同步）。**合并时要提醒组员。**

**实测**（9002 身份）：
- /alerts?limit=2 → 顶层键 ['data','meta']、data 是 list（2 条真实数据）、
  meta 键 ['has_more','next_cursor','trace_id']
- /evidence/customers 与 /notifications 同形状
- 对照 /overview（非列表）→ meta 只有 trace_id、不带游标

**测试**：3 处断言从 data["items"] 改为 data；/notifications 那处补上对 meta 的断言；
新增 test_list_endpoints_follow_the_documented_envelope，直接断言"data 是纯数组、
meta 恰好三个键、顶层恰好 data/meta"，把 §3.3 的契约钉住。

过程里踩了两个自己的坑：① 忘了 rom typing import Any（与 customer_service.py 同一失误，
被 ruff/mypy 当场抓住）；② 漏了 /evidence/{source} 这个列表端点，是测试先失败才发现的。

ruff / mypy(136 文件) / 640 unit+contract / 29 integration 全绿。
 2026-09-11 14:01:16 +08:00
lzf_0626 d896a906cd fix(risk): 规则扫描加跨进程锁——手工触发与定时扫描此前可以同时跑 
docs/25 P2 最后一项。核实后分清了两层，报告没区分：

- **定时扫描是安全的**：risk_scan_scheduler.py 已有 MySQL 连接级咨询锁
  （GET_LOCK，锁名 jr_risk_scan_schedule），跨进程互斥。
- **HTTP 端点不安全**：POST /api/v1/risk/alerts/scan → RiskScanService.scan() 只用了
  **进程内** asyncio.Lock。多 Web worker、或 Worker 与 API 同时运行时形同虚设。

而扫描的幂等只有应用层的 _exists 查重 —— fin_risk_alert 的 trigger_rule_codes 是 JSON
数组，**无法建唯一索引兜底**（同一交易可命中多条规则，唯一键本应是"交易+规则"，而规则
埋在 JSON 里）。所以两条路径并发时会同时查不到、同时插入，产生重复预警。

**改动**：

1. 把 mysql_scan_lock 与锁名移到 pp/infrastructure/db.py —— 端点与调度器**必须共用
   同一把锁**，放在基础设施层两个入口才都能引用（service 不该反向依赖 worker）。
   调度器改为从那里 import。
2. **端点层加锁**（controllers/risk.py 的 scan 端点）：取不到锁就抛 RiskScanBusyError
   （与 service 内部那把进程内锁用同一错误类型与文案）。

**为什么不加在 RiskScanService.scan() 内部**：GET_LOCK 是**连接级**的，而调度器已经在
它自己的 session 上持锁；被两个入口共用的服务方法若再取同一把锁，取锁的连接并不是持锁的
那一个、必然返回 0 —— 会**把定时扫描自己挡死**。所以锁加在入口层，每个入口只取一次。

**实测**：
- 无人持锁时扫描 → **200**「规则扫描完成」
- 本进程先取得跨进程锁后再调端点 → **409**「规则扫描正在执行，请稍后重试」
  （同一进程内不同 session 也互斥，说明它是连接级的，正是跨进程所需）
- 释放后再调 → **200**，恢复正常

顺带第 4 次遇到 409 复用错误码 RUN_NOT_CANCELLABLE，语义不符；属 P3 待处理项。

ruff / mypy(136 文件) / 639 unit+contract 全绿。
 2026-09-11 13:57:22 +08:00
lzf_0626 0d3447bde4 fix(risk): 日报邮件端点补上授权校验——它此前是风控里唯一没有校验的端点 
**问题**：POST /api/v1/risk/daily-report/mail 原先只取 context 做 401 判定，
**没有任何授权校验**；RiskDailyReportMailService.send 既拿不到 context、也不调用
AuthorizationService。收件人、标题、正文**全部由客户端决定** —— 一旦运维开启 SMTP
（RISK_DAILY_REPORT_MAIL_ENABLED），它就是一个未授权的邮件发送器。
默认关闭（ENABLED 默认 false + DRY_RUN 默认 true）让它至今没出事，但那不是可依赖的保护。

**改动**：
- send 改为 async 并接收 context，入口处 wait AuthorizationService.require(
  context, "risk:report:mail")。校验放在 **service 层**而不是 controller —— 本项目风控
  端点的授权一律落在 service（risk_query / risk_action / risk_scan 等都是这样），
  controller 只负责取 context；这个端点是唯一的例外，现在补齐。
- controller 相应改为 wait ...send(..., context=context)。
- 权限 
isk:report:mail 已在上一轮随另外三个一起创建并授予 risk_operator 与 admin。

**实测**：
- 9002(risk_operator) → **200** + {"status":"disabled","recipient_count":1}（默认关闭）
- 9001(customer)      → **403** AGENT_PERMISSION_DENIED「缺少操作权限」

**测试**：3 个既有用例改为 async 并传入带权限的 context；**新增**
	est_mail_service_requires_the_permission，断言无权限身份必须被拒 —— 钉住本次修复。

ruff / mypy(136 文件) / 623 unit+contract / 29 integration 全绿。
 2026-09-11 13:39:50 +08:00
Windows 281e76e4b1 feat: add advisor portfolio analysis 2026-09-11 13:20:09 +08:00
Windows 60c4a49b9b feat: migrate advisor investment goals 2026-09-11 13:11:58 +08:00
Windows acb9175e31 feat: migrate advisor risk questionnaire 2026-09-11 12:57:07 +08:00
张胜宇 9220b7b47c feat: integrate customer service agent into ZSY develop 
# Conflicts:
#	app/core/config.py
#	app/main.py
#	app/service/agent/bootstrap.py
 2026-09-11 10:46:56 +08:00
zhangshy a94d5c754d feat: 迁移奶龙风控业务模块与演示文档 2026-09-10 21:03:44 +08:00