diff --git a/docs/40-前端验收清单.md b/docs/40-前端验收清单.md index ab699f8..7274899 100644 --- a/docs/40-前端验收清单.md +++ b/docs/40-前端验收清单.md @@ -1,51 +1,75 @@ # 前端验收清单（正式门户） > **被测对象**：**正式前端** `app/static/portal/`，由 `app/main.py` 挂载在 **`/portal/`** -> **启动**：`python -m uvicorn app.main:app --host 127.0.0.1 --port 8000` -> （模块级变量是 **`app`**，不是 `application`） -> **入口**：（`/` 会 307 跳到 `/portal/guest/home/`） -> **时点**：2026-09-13 +> **入口**：（`/` 与 `/portal/` 都会 307 跳到 `/portal/guest/home/`） +> **时点**：2026-09-13（第三次更新：补入投顾/运营两套页面、访客客服浮窗、Worker 前置） +> +> **证据口径** +> **✅实测** = 我用真实 HTTP 请求打过，数字是那次响应的真实值； +> **⚠️待点验** = 只能从代码与接口推断的**页面交互**，需要你在浏览器里点一遍。 > -> **证据口径**：标 ✅实测 的项目**由我用真实请求打过**；标 ⚠️待点验 的是**页面交互层面**， -> 我只能从代码与接口推断，需要你在浏览器里点一遍。 > 交付方自述的路由与数据源见 `app/static/portal/README.md`。 --- -## 0. 启动与前置 +## 0. 启动与前置 ⚠️ 这一节最容易踩 | # | 项 | 命令 / 检查 | 预期 | |---|---|---|---| -| 0-1 | 依赖服务 | MySQL、Redis 可用 | 平台能起，无 500 | +| 0-1 | 依赖服务 | MySQL、Redis 可用；Milvus 需要 Docker Desktop 在运行 | 平台能起，无 500 | | 0-2 | RBAC 种子 | `python tools/seed_test_rbac.py` | 五个演示账号可登录 ✅实测 | | 0-3 | 演示口令 | `python tools/set_user_password.py` | 口令生效（**非幂等**，重跑等于改密）✅实测 | -| 0-4 | **虚拟资金账户** | `python -m tools.seed_sim_account_demo` | 客户 9001 开 10 万初始资金 + 2 只持仓。
**不跑这一步，`/customer/dashboard/` 与 `/customer/cash-ledger/` 必然打不开**（404「客户未开户」）✅实测 | -| 0-5 | 风控 Agent 配置 | `python tools/publish_risk_agent_config.py` | `risk_overview` / `risk_search` / `risk_evidence` 三个工具生效 ✅实测 | -| 0-6 | 停常驻 Worker | 确认没有 `python -m app.worker` | 否则客服对话 / Agent Run 会被抢队列 | +| 0-4 | **虚拟资金账户** | `python -m tools.seed_sim_account_demo` | 客户 9001 开 10 万初始资金 + 2 只持仓。
**不跑这步，`/customer/dashboard/` 与 `/customer/cash-ledger/` 必然打不开**（404「客户未开户」）✅实测 | +| 0-5 | 风控 Agent 配置 | `python tools/publish_risk_agent_config.py` | `risk_overview`/`risk_search`/`risk_evidence` 三个工具生效 ✅实测 | +| 0-6 | **Agent Worker（必开！）** | `python -m app.worker` | **不启动它，所有客服对话都会"超时"** —— 见下方说明 | + +### ⚠️ 0-6 为什么是"必开"而不是"必停" + +Agent 请求是**三段式**：API 受理（返回 202）→ **Worker 领单执行** → 落结果。 + +**没有 Worker 时**，`agent_run` 会一直停在 `status='queued'`、`worker_id` 为空， +前端轮询到底只会显示"客服繁忙/超时" —— **看起来像链路慢，实际是没人处理**。 +（2026-09-13 的访客浮窗"回答超时"就是这么来的。） + +> `docs/20` 里写的是"跑验收**脚本**前先停 Worker"（免得抢队列）—— 两件事不矛盾： +> **要跟 Agent 对话就必须开着；要跑验收脚本就关掉。** + +排查第一步永远是：查 `agent_run` 最新那行的 `status` 是不是 `queued`。 ```powershell -# 一次性把前置跑齐 +# 一次性把前置跑齐（两个终端） python tools/seed_test_rbac.py python tools/set_user_password.py python -m tools.seed_sim_account_demo python tools/publish_risk_agent_config.py + +# 终端 1：API python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 +# 终端 2：Worker（客服对话依赖它） +python -m app.worker ``` +> 模块级变量是 **`app`**，不是 `application`。 + --- -## 1. 路由与静态资源 ✅实测 +## 1. 页面路由与静态资源 ✅实测 -| # | 路径 | 预期 | 实测 | -|---|---|---|---| -| 1-1 | `/` | 307 → `/portal/guest/home/` | ✅ | -| 1-2 | `/portal/` | 307 → 同上 | ✅ | -| 1-3 | `/portal/guest/home/` | 200 | ✅ 5740 B | -| 1-4 | `/portal/guest/products/` | 200 | ✅ | -| 1-5 | `/portal/guest/product-detail/` | 200 | ✅ | -| 1-6 | `/portal/customer/login/` | 200 | ✅ | -| 1-7 | `/portal/employee-console/login/` | 200 | ✅ | -| 1-8 | `common/api-client.js`、`auth.js`、`permission-guard.js`、`app-shell.js`、`base.css`、`tokens.css`、`mock-data.js` | 全部 200 且 content-type 正确 | ✅ 9/9 | +**18 个路径全部 200**（`/` 与 `/portal/` 记的是跟随重定向后的最终 200）： + +| 分组 | 路径 | 实测 | +|---|---|---| +| 跳转 | `/` → `/portal/guest/home/`
`/portal/` → 同上 | ✅ | +| 访客 | `/portal/guest/home/`（5740 B）、`products/`（2153 B）、`product-detail/`（2317 B） | ✅ | +| 客户 | `customer/login/`、`dashboard/`、`holdings/`、`orders/`、`transactions/`、`profit-loss/`、`cash-ledger/`、`risk-questionnaire/` | ✅ 8/8 | +| 员工 | `employee-console/login/`、`employee-console/workspace/` | ✅ | +| 风控 | `employee-risk/dashboard/`（11872 B） | ✅ | +| **投顾** | `employee-advisor/dashboard/`（2449 B） | ✅ 本轮新增 | +| **运营** | `employee-operations/dashboard/`（1968 B） | ✅ 本轮新增 | + +**12 个关键静态资源全部 200**：`api-client.js` / `auth.js` / `login-controller.js` / `permission-guard.js` / +`layout/app-shell.js` / `mock-data.js` / `customer-service-widget/widget.js` / `widget.css` / +`base.css` / `tokens.css` / `operations.css` / `auth-layout.css` ✅ --- @@ -54,14 +78,31 @@ python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 | # | 操作 | 预期 | 证据 | |---|---|---|---| | 2-1 | 打开 `/portal/guest/home/` | 首屏含品牌与产品摘要 | ⚠️待点验 | -| 2-2 | **看页面的数据来源提示** | 显示"公开产品接口尚未提供，本页使用与 `fin_product`、`fin_nav_history` 模型同字段的演示数据" | ⚠️待点验
`MOCK_SOURCE_NOTICE` 常量已确认存在 | -| 2-3 | 进产品列表 / 详情 | 能筛选、能按排名排序、详情有净值走势 | ⚠️待点验（数据来自 `mock-data.js`，**非真实接口**） | +| 2-2 | **看页面的数据来源提示条** | 产品列表页与详情页顶部都有浅色提示条，写明"公开产品接口尚未提供…演示数据，**非真实行情**" | ✅ 页面 HTML 与三个 JS 资源实测都带 `data-source-notice` / `MOCK_SOURCE_NOTICE`
⚠️ 渲染位置待点验 | +| 2-3 | 进产品列表 / 详情 | 能筛选、能按排名排序（`?view=ranking`）、详情有净值走势 | ⚠️待点验（数据来自 `common/mock-data.js`，**非真实接口**） | | 2-4 | 点登录入口 | 进 `/portal/customer/login/` | ⚠️待点验 | -> **关于 mock**：这三页用的是 `common/mock-data.js`，因为**公开产品 HTTP 接口尚未实现**。 -> 页面显著标注了来源，README 也写明"不得与登录后的真实账户数据混用"。 -> **这不是 17- 文档禁止的"为业务演示造数据"**，而是接口缺位时的显式降级； -> 真正的解法是补公开产品接口。 +> **关于 mock**：访客三页用 `common/mock-data.js`，因为**公开产品 HTTP 接口尚未实现**。 +> 页面显著标注了来源 —— 这个标注**不能删**：删掉不会让数据变真，只会让客户以为看到的是真实净值。 + +### 2.5 访客智能客服浮窗 ⭐ 本轮重点 + +公开首页、产品列表页、产品详情页右下角都有客服浮窗。 + +| # | 操作 | 预期 | 证据 | +|---|---|---|---| +| 2-5 | 点浮窗，问一个**知识库里有**的问题 | 约 4 秒内给出答案 | ✅实测端到端 **4.11s**
问「基金定投是什么」→ score 0.8203 → 直接答 | +| 2-6 | 问一个**知识库里没有**的问题 | 引导拨打客服热线（**这是正确行为**，见第 9 节） | ✅实测 **4.09s / 4.82s** | +| 2-7 | 问个人账户相关问题（如"我的风险等级是多少"） | 提示"该服务需要登录后才能查询您的个人信息" | ⚠️待点验（代码路径已确认：`_guide_to_login`） | +| 2-8 | 浮窗里点"登录后查询账户" | 跳客户登录页 | ⚠️待点验 | + +**访客令牌机制**：`POST /api/v1/visitor-tokens`（无鉴权） +→ 返回短期令牌，身份是 `roles=("visitor",)`、`permissions=("agent:run","knowledge:query")` ✅实测 + +> ⚠️ **访客与客户走的是不同的检索工具名**：访客走 `query_knowledge`（要 `knowledge:query`）， +> 登录客户走 `search_knowledge`（要 `knowledge:reference:read`）。两者**必须同时**在发布配置 +> `agent_tools/customer_service:` 的白名单里 —— 缺哪一条，对应人群就一问即失败。 +> 2026-09-13 修过一次：当时白名单只有 `search_knowledge`，访客一问就抛 `ForbiddenAgentError`。 --- @@ -71,23 +112,26 @@ python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 | # | 操作 | 预期 | 证据 | |---|---|---|---| -| 3-1 | 用 `cust_t` / `123456` 登录（A034） | 200，拿到令牌，跳 dashboard | ✅ A034 200，`user_id=9001`，`expires_in=1800` | -| 3-2 | dashboard（T001 `GET /users/me/account/dashboard`） | 总资产 / 可用资金 / 持仓市值等 | ✅ 200（**修前置前是 404「客户未开户」**） | -| 3-3 | 持仓（T006 `GET /users/me/holdings`） | 持仓表 | ✅ 200 | +| 3-1 | 登录（A034） | 200，拿到令牌，跳 dashboard | ✅ 200，`user_id=9001`，`expires_in=1800` | +| 3-2 | dashboard（T001） | 总资产 / 可用资金 / 持仓市值 | ✅ 200（**修前置前是 404「客户未开户」**） | +| 3-3 | 持仓（T006） | 持仓表 | ✅ 200 | | 3-4 | 交易流水（T007） | 流水表 | ✅ 200 | -| 3-5 | 资金流水（T009 `GET /users/me/cash-ledger`） | 资金明细 | ✅ 200（同 3-2，修前置前 404） | -| 3-6 | 订单列表（T003 `GET /users/me/orders`） | 空列表不报错 | ✅ 200（0 条） | -| 3-7 | 下单（T002 `POST /users/me/orders`） | 报文 `{product_code, order_side, quantity}`，`order_side ∈ {buy, sell}` | ⚠️待点验
需用真实 product_code（`7002` 是 product_id 不是 code） | +| 3-5 | 资金流水（T009） | 资金明细 | ✅ 200 | +| 3-6 | 订单列表（T003） | 空列表不报错 | ✅ 200 | +| 3-7 | 下单（T002） | 报文 `{product_code, order_side, quantity}`，`order_side ∈ {buy, sell}` | ⚠️待点验
需真实 `product_code`（`7002` 是 product_id 不是 code） | | 3-8 | 盈亏（T001） | 收益曲线 | ⚠️待点验 | | 3-9 | 风险测评（ONB001） | 返回问卷定义 | ✅ 200 | -| 3-10 | 提交问卷（ONB002） | 提交后状态变更；**未提交测评时部分接口会 403/409** | ⚠️待点验（写操作） | +| 3-10 | 提交问卷（ONB002） | 提交后状态变更 | ⚠️待点验 | -### 3.2 客服 +### 3.2 客户客服浮窗 | # | 操作 | 预期 | 证据 | |---|---|---|---| -| 3-11 | 与客服 Agent 对话（R001 + R002/R003） | 受理 202 → SSE 出结果 | ⚠️待点验（需停常驻 Worker） | -| 3-12 | 转人工 | 工单进管理员队列 | ✅ 我之前实测过 `POST /conversations/{sid}/handover-requests` → 202，前提是**先调 C001 真实创建会话** | +| 3-11 | 在客户工作台用浮窗提问 | 与访客同一浮窗，但身份是登录客户 | ⚠️待点验（需 Worker 在跑） | +| 3-12 | 点"转人工客服" | `POST /conversations/{sid}/handover-requests` → 202，工单进管理员队列 | ✅ 实测 202（**前提：先由 C001 真实创建会话**） | + +> **转人工的实现口径**：按你的要求，**只回话术引导拨客服热线，不创建工单**用于"答不上来"的场景； +> 上面 3-12 是客户**主动**点"转人工"按钮才建工单，两者不是一回事。 --- @@ -95,68 +139,196 @@ python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 | # | 操作 | 预期 | 证据 | |---|---|---|---| -| 4-1 | `/portal/employee-console/login/` 登录 | 进 workspace | ✅ A034 200 | +| 4-1 | 员工入口登录 | 进 workspace | ✅ 200 | | 4-2 | 配置发布列表（A002） | 版本列表 | ✅ 200 | -| 4-3 | 模型端点（A012） | 端点列表 | ✅ 200 | +| 4-3 | 模型端点（A012） | 端点列表 | ✅ 200（`deepseek-flash`、`qwen-embedding`） | | 4-4 | 审计查询（A033） | 时间/动作/操作者/结果 | ✅ 200 | -| 4-5 | 角色列表 / 权限 / 用户角色（A035–A038） | 角色与权限明细 | ✅ 200（`customer` 角色 26 项权限） | +| 4-5 | 角色 / 权限 / 用户身份（A035–A038） | 角色与权限明细 | ✅ 200（`customer` 26 项、`advisor` 28 项、`admin` 59 项、`operator` 2 项、`risk_operator` 10 项） | | 4-6 | 画像候选审核（A039） | 候选列表 | ✅ 200 | | 4-7 | 客服转人工工单（ADMIN_HANDOVERS） | 工单队列，**不返回客户标识与原始正文** | ✅ 200 | | 4-8 | 配置发布四态（A004/A005/A006） | 校验→审核→激活，**必须带 `Idempotency-Key`** | ⚠️待点验（写操作） | -> **平台只提供 RBAC 只读查询**：没有改权限的写接口，权限变更走 `config_release` 发布。 -> 这是设计，不是功能缺失。 +> **平台只提供 RBAC 只读查询**：没有改权限的写接口，权限变更走 `config_release` 发布。这是设计。 --- -## 5. 风控（`risk_t` / `666666`）—— 按 `docs/风控业务演示文档/17-*.md` 对齐 +## 5. 风控（`risk_t` / `666666`）—— 对齐 `docs/风控业务演示文档/17-*.md` | # | 操作 | 预期 | 证据 | |---|---|---|---| -| 5-1 | 风险概览（RK001） | 总量 / 等级 / 待处理 / 超时 / 重点预警 | ✅ 200（total=2 pending=1 overdue=2 levels{高风险:2}） | -| 5-2 | 预警队列（RK002） | **每页 5 条**、风险等级优先、筛选、分页 | ✅ 200（2 条：`ALDEMO0002` 高、`ALDEMO0001` 高）
⚠️ `limit` **上限就是 5**，传 20 会 422 且表格渲染不出来 | -| 5-3 | 队列筛选 | 关键词 / 客户号 / 风险等级 / 规则码 / 产品 / 时间 | ✅ `rule_code=RW-015 → ALDEMO0002`、`customer_no=T-CUST → 2 条`
⚠️ **风险等级要填「高/中/低」**：预警对象用「高」，概览 `levels` 用「高风险」 | -| 5-4 | 预警详情（RK003） | 编号 / 状态 / 规则 / 证据 / 回执 / 客户 | ✅ 200（alert 23 字段 + customer 13 字段） | -| 5-5 | 八类证据（RK004） | `customers`/`products`/`transactions`/`capital_flows`/`holdings`/`login_records`/`alerts`/`notifications` | ✅ 8/8 全 200
⚠️ 路径是 **`holdings`**，写 `positions` 会被 422 | -| 5-6 | 通知记录（RK005） | 预警编号 / 类型 / 发送状态 | ✅ 200 | +| 5-1 | 风险概览（RK001） | 总量/等级/待处理/超时/重点预警 | ✅ 200（total=2 pending=1 overdue=2 levels{高风险:2}） | +| 5-2 | 预警队列（RK002） | **每页 5 条**、筛选、分页 | ✅ 200（2 条：`ALDEMO0002`、`ALDEMO0001`）
⚠️ `limit` **上限就是 5**，传 20 会 422 且表格渲染不出来 | +| 5-3 | 队列筛选 | 关键词/客户号/风险等级/规则码/产品/时间 | ✅ `rule_code=RW-015 → ALDEMO0002`、`customer_no=T-CUST → 2 条`
⚠️ **风险等级填「高/中/低」**：预警对象用「高」，概览 `levels` 用「高风险」 | +| 5-4 | 预警详情（RK003） | 编号/状态/规则/证据/回执/客户 | ✅ 200（alert 23 字段 + customer 13 字段） | +| 5-5 | 八类证据（RK004） | `customers`/`products`/`transactions`/`capital_flows`/**`holdings`**/`login_records`/`alerts`/`notifications` | ✅ 8/8 全 200
⚠️ 是 **`holdings`**，写 `positions` 会被 422 | +| 5-6 | 通知记录（RK005） | 预警编号/类型/发送状态 | ✅ 200 | | 5-7 | 手动扫描（RK006） | 200 `code=0`，**要带 `Idempotency-Key`** | ✅ 200 | -| 5-8 | 确认接收（RK007） | **二次确认**；状态不符返回 409 | ✅ 409「只有待处理的预警才能确认解决」 | +| 5-8 | 确认接收（RK007） | 二次确认；状态不符返回 409 | ✅ 409「只有待处理的预警才能确认解决」 | | 5-9 | 进入调查（RK008）/ 关闭误报（RK009） | 误报**必须填理由** | ⚠️待点验（写操作） | | 5-10 | 结案（RK010）/ 升级（RK011） | 结案填 `resolution`、升级填 `reason`；**需先确认接收** | ⚠️待点验（顺序：确认 → 调查/误报/升级/结案） | | 5-11 | 证据上传（RK012） | **`multipart/form-data`** | ⚠️待点验 | -| 5-12 | 日报（RK013 / RK014 / RK015） | 生成 / **SSE 流式** / 多邮箱发送 | ✅ RK013 200；SSE 事件类型实测为 `start`/`progress`/`replace` | +| 5-12 | 日报（RK013/RK014/RK015） | 生成 / **SSE 流式** / 多邮箱发送 | ✅ RK013 200；SSE 事件类型实测 `start`/`progress`/`replace` | --- -## 6. 通用预期（跨页面） +## 6. 投顾（`advisor_t` / `abc12345`）⭐ 本轮新增页面 + +登录入口同样是**员工登录页** `/portal/employee-console/login/`，登录后自动落到投顾工作台。 + +| # | 操作 | 预期 | 证据 | +|---|---|---|---| +| 6-1 | 用 `advisor_t` 登录 | 跳 `/portal/employee-advisor/dashboard/` | ✅ 实测守卫生效（此前会**静默弹回登录页**，已修） | +| 6-2 | 工作台列表 | 显示"**投资目标方案书 · 客户 9001**"卡片 + 发布时间 + 方案内容 | ✅ 接口实测返回 1 条（`content_id=1`、`customer_id=9001`、`type=investment_goal_book`、`published_at=2026-09-13T10:50:17`） | +| 6-3 | 点"刷新" | 重新拉取 `ADVISOR_PUBLISHED` | ⚠️待点验 | +| 6-4 | 用别的角色访问该页 | `risk_operator` 会被弹回风控页；`operator` 弹回运营页 | ✅ 实测守卫矩阵 | + +**数据口径**（`ProductRecommendationService.published`）： +按「**本人 + `sys_customer_assignment` 里名下归属客户**」过滤，且覆盖两类内容 —— +`investment_goal_book`（方案书，发布后 `review_status='published'`）与 +`advisor_recommendation_plan`（推荐方案，审核后 `'approved'`）。 + +> **不用 `data_scope`** 的原因：投顾持有 `promotion:*` 这类 all 级权限， +> `IdentityService` 会把整个身份的 scope 抬到 `all`，按它判定会放开到**全部客户**。 +> 归属关系来自 `sys_customer_assignment`（逐条授权 + 时间窗校验），比 scope 更窄。 +> +> **本机归属数据**：`sys_customer_assignment` 只有一行 `(customer_id=9001, employee_id=9020, advisor)`。 +> 所以投顾现在能看到客户 9001 的交付物；**换环境这条数据不跟着走，页面会是空态**。 + +### 6.5 方案书的审核与发布必须由管理员做 + +``` +客户确认目标 → 管理员审核方案书 → 管理员发布方案书 +``` + +`review_book` 与 `publish_book` 都带 `admin=True`（`investment_goal_service.py:174/216`）—— +**投顾虽然有 `investment-goal:review` 权限码也做不了**。这是有意的复核环节，不是缺陷。 +实测：投顾调用审核 → 403；管理员调用 → 200 ✅ + +--- + +## 7. 运营（`offsite_t` / `offsite123`）⭐ 本轮新增页面 + +| # | 操作 | 预期 | 证据 | +|---|---|---|---| +| 7-1 | 用 `offsite_t` 登录 | 跳 `/portal/employee-operations/dashboard/` | ✅ 实测守卫生效（此前同样静默弹回） | +| 7-2 | 场外邮件列表（`OFFSITE_MAILS`） | 分页列表：主题/发件人/时间/状态 | ✅ 200 `data=dict{items,page,page_size,total}` | +| 7-3 | 收件箱状态（`OFFSITE_MAILBOX`） | 邮箱 / 游标状态 / 阻塞标记 | ✅ 200 `data=dict{mailbox,status,blocked,last_uid,…}` | +| 7-4 | 用客户/风控访问这两个接口 | 被拦 | ✅ 客户 `code=403 当前角色不能操作场外基金流程`；风控 `code=403 缺少场外基金操作权限` | + +> 场外线按**角色**收口（`operator`/`risk_operator`/`admin`/`super_admin`），不是按权限码。 + +--- + +## 8. 通用预期（跨页面） | # | 情形 | 预期 | |---|---|---| -| 6-1 | **业务失败也返回 HTTP 200** | 本平台把业务错误放在 `body.code`（如生成失败 `HTTP 200 + code=422`），前端按 `error-codes.js` 解析 ✅实测 | -| 6-2 | 403 | "没有当前操作权限"；按钮可见性应与服务端权限一致 ✅实测（客户访问 `/admin/roles` → 403） | -| 6-3 | 404 | 注意 `SESSION_NOT_FOUND` 被**三个异常类共用**，可能是"会话不存在"、"客户不可访问"或"知识文档不存在"，只能看 message ✅实测 | -| 6-4 | 幂等 | 写请求必须带唯一 `Idempotency-Key`（`api-client.js` 已用 `idempotent: true` 标记）✅实测 | -| 6-5 | 多标签 | 各页面独立，会话互不干扰 ⚠️待点验 | -| 6-6 | 排版 | 文字不重叠、内容不溢出、表格行高稳定 ⚠️待点验 | +| 8-1 | **业务失败也返回 HTTP 200** | 平台把业务错误放在 `body.code`（如生成失败 `HTTP 200 + code=422`），前端按 `error-codes.js` 解析 ✅实测 | +| 8-2 | 403 | "没有当前操作权限"；按钮可见性应与服务端权限一致 ✅实测 | +| 8-3 | 404 | `SESSION_NOT_FOUND` 被**三个异常类共用**（会话不存在 / 客户不可访问 / 知识文档不存在），只能看 message ✅实测 | +| 8-4 | 幂等 | 写请求必须带唯一 `Idempotency-Key`（`api-client.js` 用 `idempotent: true` 标记）✅实测 | +| 8-5 | 多标签 | 各页面独立。**注意**：`auth.js` 现在以 cookie 为权威（跨标签同步），所以**同一浏览器两个账号不能并存** ✅实测代码逻辑 | +| 8-6 | 排版 | 文字不重叠、内容不溢出、表格行高稳定 ⚠️待点验 | +| 8-7 | 缓存 | 产品列表/详情页的 CSS/JS 已带 `?v=20260913-4`；若改了资源仍看不到效果，请硬刷新 ⚠️待点验 | --- -## 7. 我做了什么验证（可复现） +## 9. ⚠️ 看起来像 bug、其实是设计（测试时最容易被误判的三件事） + +### 9-1 "客服答不上来，总是引导转人工" —— 这是置信度防线在工作 + +客服命中知识后要过两道阈值（`customer_service.py:148-150`）： + +``` +HIGH_SCORE = 0.75 # ≥ 0.75 直接答 +MID_SCORE = 0.55 # 0.55~0.75 之间，必须同时满足 MIN_GAP +MIN_GAP = 0.07 # top1 领先次优的最小间隙 +``` + +**实测三条，逐条对上**： + +| 提问 | top1 分数 | 次优 | 间隙 | 判定 | +|---|---|---|---|---| +| 基金定投是什么 | **0.8203** | 0.5886 | 0.2317 | ≥0.75 → **直接答** ✅ | +| 南方沪深300ETF的起投金额是多少 | 0.6818 | 0.6784 | **0.0034** | 间隙 < 0.07 → **转人工** | +| 购买基金需要什么条件 | 0.5221 | 0.5162 | 0.0059 | 分数 < 0.55 → **转人工** | + +第二问如果硬答，会答成"**南方结构性存款（挂钩型）：起投金额 20 万元**" —— 那是另一个产品， +而且客户问的是场内 ETF。**转人工在这里是正确行为**，符合你定的"不会的就转人工，首先要保证稳定性"。 + +> 真正要改的是**知识库内容**，不是代码：检索命中的是一套"南方科技有限公司 个人理财产品手册" +> 的素材（`PROD-*`/`FAQ-*`/`POL-*`），**里面没有本项目的场内 ETF 条目**，所以问 ETF 注定分数上不去。 + +### 9-2 "客户能读投顾的接口" —— 不是越权 + +`GET /api/v1/advisor/recommendations/published` 客户调用返回 200，但 SQL 里按 +`customer_id IN (本人 + 归属客户)` 过滤，**读的是自己的**。风控返回 403 是因为没有 +`product-recommendation:read:self` 权限码。用"能访问"判断越权会误判。 + +### 9-3 "投顾发布不了方案书" —— 是有意的复核环节 + +见 6.5。审核与发布都要求 `admin=True`。 + +--- + +## 10. 我做了什么验证（可复现） | 项 | 方式 | 结果 | |---|---|---| -| 16 个页面路由 + 9 个静态资源 | 逐个 GET | 全部 200 / 307 符合预期 | -| 49 个端点里的 26 个（客户域 / 风控域 / 管理面 / Agent） | 用五个角色真实登录后逐个请求 | 除 3 个（见下）全通 | -| 登录链路 | `POST /api/v1/auth/tokens` × 5 角色 | 全部 200 | -| 平台门禁 | ruff / mypy / pytest / 表审计 | ruff 干净 / **mypy 249 文件 0 错** / 单元+契约 **1376 passed** / 集成 **104 passed** / **89 张业务表** | +| 18 个页面路径 + 12 个静态资源 | 逐个 GET | 全部 200 | +| 五个角色登录 | `POST /api/v1/auth/tokens` × 5 | 全部 200 | +| 各角色登录后落点与越权矩阵 | **真实执行 `auth.js` 的守卫函数**（node + DOM 桩） | advisor→投顾页、operator→运营页、risk→风控页、admin→工作台；交叉误入能弹回自己家 | +| 访客客服问答端到端 | 与浮窗同链路（V001 → R001 → 轮询 R002） | **4.11s / 4.09s / 4.82s**，三条全部 succeeded | +| 投顾页数据 | 走完整业务流（客户确认→管理员审核→管理员发布）后复查 | 投顾读到归属客户 9001 的方案书；客户只读到自己的；风控 403 | +| 平台门禁 | ruff / mypy / pytest / 表审计 / 文档检查 | ruff 干净 · **mypy 249 文件 0 错** · 单元+契约 **1376 passed** 2 skipped · 集成 **104 passed** · **89 张业务表** · 文档 55 份无编号冲突 | +| 前端 JS 语法 | 7 个文件按 ESM 解析检查 | 全部通过 | -**联调时发现并已修的问题**： +**联调中发现并已修的问题**： -1. **`T001` / `T009` 恒 404「客户未开户」** —— 根因是 `tools/seed_test_rbac.py` 把 - `fund_account_status` **硬编码成 `'closed'`**，与 `tools/create_test_user.py` 的 - `{customer: 已开户, employee: closed}` 口径不一致。已改为按 `user_type` 取状态； - 再配合 `python -m tools.seed_sim_account_demo` 开虚拟资金账户后，T001/T006/T007/T009 全部 200。 -2. **`rule_code` 筛选恒为空** —— `risk_repository.py` 用 `.contains([code])`，SQLAlchemy 会把它 - 编译成 `LIKE`，而 `trigger_rule_codes` 是 JSON 数组，等于匹配字符串 `'["RW-015"]'`。 - 已改为 `func.json_contains(...)`；扫描去重处的同一写法也一并修了。 -3. **误提交的 `.agents/skills`（15 个文件）** —— AI 助手配置，与本项目无关，已从仓库移除并加入 `.gitignore`。 +1. **`T001`/`T009` 恒 404「客户未开户」** —— `tools/seed_test_rbac.py` 把 `fund_account_status` + 硬编码成 `'closed'`，与 `create_test_user.py` 的 `{customer: 已开户, employee: closed}` 不一致。 + 已改为按 `user_type` 取；配合 `seed_sim_account_demo` 后 T001/T006/T007/T009 全部 200。 +2. **`rule_code` 筛选恒为空** —— `risk_repository.py` 用 `.contains([code])`，SQLAlchemy 编译成 `LIKE`， + 而 `trigger_rule_codes` 是 JSON 数组。已改为 `func.json_contains(...)`，扫描去重处同一写法一并修。 +3. **误提交的 `.agents/skills`（15 个文件）** —— AI 助手配置，与本项目无关，已移除并加入 `.gitignore`。 +4. **投顾/运营登录后静默弹回登录页** —— `staffHomeForRoles` 缺这两个角色的落点， + 进 workspace 后被 `requireAdmin` 弹回且**不带任何提示**，看起来像"登录没反应"。 + 已补两个落点与 `requireAdvisor`/`requireOperator` 守卫。 +5. **访客客服浮窗一问即失败** —— 客服代码让访客走 `query_knowledge`，但发布配置的三个知识意图 + 只发了 `search_knowledge`，工具白名单直接抛 `ForbiddenAgentError`。已补发 `query_knowledge` + （保留 `search_knowledge` 给登录客户）。 +6. **访客页的"演示数据"声明被删掉、但假数据还在渲染** —— 已恢复 `MOCK_SOURCE_NOTICE`、 + 两个页面的提示条与样式，并给 `link`/`script` 加版本参数（此前会被浏览器缓存）。 +7. **发布脚本会静默丢提示词** —— `publish_customer_service_config.py` 只继承 + `platform_config_item`，把 `customer_service_chitchat` 提示词漏在了旧版本里。 + 已改用 `effective_snapshot()` 读全三张受管表、补提示词搬运与条数硬校验；丢失的提示词已按原文恢复。 + +--- + +## 11. 已知问题（未修） + +| 项 | 说明 | +|---|---| +| **知识库没有场内 ETF 内容** | 检索命中的是"南方科技理财产品手册"素材，问 ETF 类问题必然分数不足而转人工。**属知识内容工作，需业务提供素材后灌库** | +| `fin_knowledge_meta` 表为空 | **Milvus 里有知识**（`FAQ-*`/`PROD-*`/`POL-*` 都能检索到），但 MySQL 元数据表 0 行 ⇒ 管理端列表（`GET /api/v1/knowledge/list`）看不到内容、也无从删除。元数据与向量不一致 | +| 品牌名三处不一致 | 后端 Agent 自称"**奶龙基金**"（`customer_service_rules.py`、`risk_agent.py`），前端全站是"**南方财富**"，闲聊提示词与知识素材写的是"**南方科技**"。**需要你定对外用哪个**；注意 `fund_manager` 字段值是"南方基金"且被同步服务用作过滤条件，**不能改** | +| `ADVISOR_GOAL` / `ADVISOR_ANALYSIS` 声明未用 | 投顾页只调了 `ADVISOR_PUBLISHED`；且 `portfolio-analysis` 的 body 必须是 `{}`（空模型 + `extra="forbid"`） | +| `widget.js` 里的 `portal:auth-changed` 监听 | 是死代码 —— `auth.js` 从不派发该事件（它用 BroadcastChannel） | +| 同一浏览器不能并存两个账号 | 见 8-5，是跨标签同步的代价，若不符合预期需要改回 | + +--- + +## 附：演示账号 + +| 角色 | 用户名 | 密码 | user_id | 入口 | +|---|---|---|---|---| +| 客户 | `cust_t` | `123456` | 9001 | `/portal/customer/login/` | +| 风控专员 | `risk_t` | `666666` | 9002 | `/portal/employee-console/login/` | +| 管理员 | `admin_t` | `88888888` | 9003 | 同上 | +| **运营** | `offsite_t` | `offsite123` | 9006 | 同上（→ 运营工作台） | +| **投顾** | `advisor_t` | `abc12345` | 9020 | 同上（→ 投顾工作台） | + +> ⚠️ `tools/set_user_password.py` 的内置演示规则**只写了 9001/9002/9003**； +> 9006 与 9020 的口令是建号时单独设的，**换环境重建时会没有密码**，需要用 +> `python tools/set_user_password.py --user 9006 --password <口令>` 补设。 +> 另：9004 `review_t`、9005 `offsite_worker` 是占位符，**登不了**。