2026-09-09 18:04:45 +08:00
|
|
|
|
# 数据分析 Agent · 开发 TODO 清单
|
|
|
|
|
|
|
|
|
|
|
|
> 依据：`docs/需求拆解/01-数据分析Agent需求规格.md`（v1.2）+ `docs/项目框架设计/数据分析Agent架构说明书.md`（v1.1）
|
|
|
|
|
|
> 用途：开发启动后的施工顺序清单；完成一项打钩、验证通过再往下。
|
|
|
|
|
|
> 状态图例：⬜ 待办 · 🚧 进行中 · ✅ 完成
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 0. 开工前须知
|
|
|
|
|
|
|
|
|
|
|
|
1. **先看依赖**：阶段 0 的 4 项是平台组的地基，没做完，分析 Agent 动不了（对应仓库 `docs/memory/TODO.md` 的 T-01/T-02/T-05/T-06）。
|
|
|
|
|
|
2. **只读铁律**：所有查数只 `SELECT`；`analytics_query_log` 与 `audit_log` 只 INSERT；分析师才能写资产表。
|
|
|
|
|
|
3. **每完成一个阶段**：对照最下方「验收对照表」跑一遍演示用例，全过再进下一阶段。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 0 · 前置地基（平台组，需先完成）
|
|
|
|
|
|
|
|
|
|
|
|
| 编号 | 任务 | 对应需求 | 验收要点 | 状态 |
|
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
|
| P0-1 | JWT + RBAC 中间件（Mock JWT HS256） | F-01 | 越权 403 + 留痕；`X-Agent-Type: analyst` 准入 | ⬜ |
|
|
|
|
|
|
| P0-2 | 审计贯通：`trace_id` 全链路 + `audit_log` | F-02 | 任意问答可按 trace_id 还原 | ⬜ |
|
|
|
|
|
|
| P0-3 | 灌库：Core 模拟 + 共用底座 11 表 + sync | R0-CORE/R0-DB | `jinrong_core` 有种子；`customer_advisor_rel` 有归属 | ⬜ |
|
|
|
|
|
|
| P0-4 | 挂载路由 + LangGraph `agent_service` 骨架 | — | `/health` 之外能走通空 chat 链路 | ⬜ |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 1 · P0 最小闭环（D-01~D-04）
|
|
|
|
|
|
|
|
|
|
|
|
**目标：能问、能查、能答、能留痕。**
|
|
|
|
|
|
|
|
|
|
|
|
| 编号 | 任务 | 对应需求 | 架构落点 | 验收要点 | 依赖 | 状态 |
|
|
|
|
|
|
|---|---|---|---|---|---|---|
|
|
|
|
|
|
| A-01 | 建分析专用表（含 3 张新表） | D-11 | `03-mysql-analyst专用.sql` | 4 张 `analytics_*` 表可查 | P0-3 | ⬜ |
|
|
|
|
|
|
| A-02 | SQL 五层校验 `sql_guard` | D-04 / §2.2 | `service/sql_guard.py` | 只 SELECT；越权 403；归属注入 | P0-1 | ⬜ |
|
|
|
|
|
|
| A-03 | 只读执行 `sql_tool` + `core_ro_tool` | D-01~D-03 | `tool/sql_tool.py` `core_ro_tool.py` | 行数≤1000、超时 10s、空态标记 | A-02 | ⬜ |
|
|
|
|
|
|
| A-04 | 主链路 `analyst_agent`（StateGraph 节点串联） | D-01 | `service/analyst_agent.py` | NL→SQL→执行→解读 串通 | P0-4 | ⬜ |
|
|
|
|
|
|
| A-05 | 路由 `/api/analyst/chat` | D-01 | `api/analyst.py` | 请求进出、错误码规范 | A-04 | ⬜ |
|
|
|
|
|
|
| A-06 | 输出四件套 + 免责声明 | §3 全局约定 | `model/schemas/analyst.py` | answer+table+sql+meta+disclaimer | A-04 | ⬜ |
|
|
|
|
|
|
| A-07 | 留痕（query_log + tool_call + audit） | D-04 | `service/analytics_repo.py` | trace_id 串联可还原 | A-05 | ⬜ |
|
|
|
|
|
|
|
|
|
|
|
|
**阶段 1 验收**：D-01 两类问数正确；顾问查非名下客户 403 且可查；预警只读不可处置。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 2 · P0 增强（D-05~D-09）
|
|
|
|
|
|
|
|
|
|
|
|
| 编号 | 任务 | 对应需求 | 架构落点 | 验收要点 | 依赖 | 状态 |
|
|
|
|
|
|
|---|---|---|---|---|---|---|
|
|
|
|
|
|
| A-08 | 口径字典 + schema 元数据注入 | D-07 | `service/dict_service.py` | 关键指标跨角色一问一义 | A-01 | ⬜ |
|
|
|
|
|
|
| A-09 | 结果/模板双层缓存 + data_as_of | D-06 | `service/cache_service.py` | 二答秒回、`cache_hit=true`、主动失效 | A-03 | ⬜ |
|
|
|
|
|
|
| A-10 | 多轮追问（Constrained Edit 改写） | D-09 | `analyst_agent` 改写节点 | 追问承接上文，口径继承 | A-04 | ⬜ |
|
|
|
|
|
|
| A-11 | 兜底拒答 + 可查范围引导 | D-08 | `analyst_agent` deny 分支 | 超范围说明性拒绝，权限类附引导 | A-02 | ⬜ |
|
|
|
|
|
|
| A-12 | 复杂交叉问数（多表只读聚合） | D-05 | `analyst_agent` | 交叉维度正确、超权限字段拒绝 | A-02 | ⬜ |
|
|
|
|
|
|
|
|
|
|
|
|
**阶段 2 验收**：D-06 缓存命中可见；D-07 口径一致；D-09 追问正确；D-08 拒答清晰。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 3 · P0 亮点（D-10~D-12 + N-01/02/03/07）
|
|
|
|
|
|
|
|
|
|
|
|
| 编号 | 任务 | 对应需求 | 架构落点 | 验收要点 | 依赖 | 状态 |
|
|
|
|
|
|
|---|---|---|---|---|---|---|
|
|
|
|
|
|
| A-13 | 数字护栏四道校验 | D-10 | `service/guardrail.py` | 错数字被拦截，重试 1 次后降级 | A-06 | ⬜ |
|
|
|
|
|
|
| A-14 | 养 Agent 资产沉淀（few-shot/字典/模板） | D-11 | `analytics_repo` + assets 路由 | 沉淀后同类问题命中，可回滚可灰度 | A-08 | ⬜ |
|
|
|
|
|
|
| A-15 | 智能看数板后端接口 | D-12 | `/api/analyst/dashboard` | 按角色出卡片、钻取进对话 | A-04 | ⬜ |
|
|
|
|
|
|
| A-16 | 指标消歧反问 | N-01 | `analyst_agent` ambiguity 节点 | 多义词先反问，澄清后口径一致 | A-08 | ⬜ |
|
|
|
|
|
|
| A-17 | 空/零/不命中三态区分 | N-02 | `sql_tool` | 三种空态分别准确说明 | A-03 | ⬜ |
|
2026-09-11 17:07:22 +08:00
|
|
|
|
| A-18 | 聚合抽样明细溯源 | N-03 | `/api/analyst/query/{trace_id}/sample` | 明细与聚合一致 | A-07 | ✅ 2026-09-11 |
|
|
|
|
|
|
| A-19 | 转人工兜底 | N-07 | `/api/analyst/escalate` | 失败场景一键转人工、留痕可还原 | A-07 | ✅ 2026-09-11 |
|
2026-09-09 18:04:45 +08:00
|
|
|
|
|
|
|
|
|
|
**阶段 3 验收**：D-10 造错用例被拦；D-11 沉淀生效；D-12 卡片钻取；N-01/02/03/07 各跑通。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 4 · P1（N-04/05/06/08）
|
|
|
|
|
|
|
|
|
|
|
|
| 编号 | 任务 | 对应需求 | 架构落点 | 验收要点 | 依赖 | 状态 |
|
|
|
|
|
|
|---|---|---|---|---|---|---|
|
|
|
|
|
|
| A-20 | 成本计量 + 配额限流 | N-04 | `meta.cost_est` + `guard:rate` | 超配额限流、成本可见 | A-07 | ⬜ |
|
|
|
|
|
|
| A-21 | 保存/分享/订阅 | N-05 | save/share/subscribe 路由 | 分享不突破接收方权限 | A-09 | ⬜ |
|
|
|
|
|
|
| A-22 | 数据质量提示 | N-06 | `answer_compose` | 脏数据附带质量提示 | A-06 | ⬜ |
|
|
|
|
|
|
| A-23 | 运营指标面板 | N-08 | `/api/analyst/ops/metrics` | 通过率/命中率/拒答率/成本/转人工率可查 | A-07 | ⬜ |
|
|
|
|
|
|
|
|
|
|
|
|
**阶段 4 验收**：N-04~N-08 各自跑通。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 验收对照表（演示即验收）
|
|
|
|
|
|
|
|
|
|
|
|
| 演示问答 | 期望 | 对应阶段 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| 分析师「按产品类型统计总持仓规模」 | 表格+解读+SQL，正确 | 1 |
|
|
|
|
|
|
| 顾问「查 CUST-1004（非名下）持仓」 | 403 + 审计留痕 | 1 |
|
|
|
|
|
|
| 风控「当前待处理大额预警占比」 | 统计+解读，不可处置 | 1 |
|
|
|
|
|
|
| 运营「近一月申购金额总额」 | 仅聚合，无客户明细 | 1 |
|
|
|
|
|
|
| 同形态问题重复问 | 第二次 `cache_hit=true` | 2 |
|
|
|
|
|
|
| 「数字加起来是 123 万吗」 | 数字护栏拦截或通过 | 3 |
|
|
|
|
|
|
| 沉淀 few-shot 后问同类问题 | 命中沉淀资产 | 3 |
|
|
|
|
|
|
| 点看板卡片钻取 | 进入对话、承接上文 | 3 |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 附：如何推进（建议节奏）
|
|
|
|
|
|
|
|
|
|
|
|
1. **先钉阶段 0**：平台组 4 项是硬前置，未完成前分析组只做 A-01（建表）等不依赖接口的准备工作。
|
|
|
|
|
|
2. **阶段 1 打通就"能用"**：D-01~D-04 是最小闭环，建议作为第一个里程碑对外演示。
|
|
|
|
|
|
3. **阶段 2/3 是亮点**：缓存、口径、数字护栏、养 Agent、看数板是答辩得分点，务必做扎实。
|
|
|
|
|
|
4. **阶段 4 可后置**：P1 项不影响一期上线，按人力排期。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 变更记录
|
|
|
|
|
|
|
|
|
|
|
|
| 版本 | 日期 | 变更 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| v1.0 | 2026-09 | 初版：按需求 v1.2 + 架构说明书 v1.1 拆解为 0~4 阶段 23 项任务 |
|
