feat: 数据分析 Agent 实现（API/服务/表结构元数据/文档/测试）

- 新增 app/api、app/service 数据分析 Agent 全套服务与接口
- schemas.py 重构为 schemas 包（analyst schema）
- 新增 SQL 防注入、guardrail、缓存、字典、LLM 等服务
- 新增 tests 测试套件与 scripts/dev、scripts/setup 脚本
- 补充需求规格、架构说明书、开发清单、表设计等文档

docs/需求拆解/01-数据分析Agent需求规格.md

@@ -0,0 +1,458 @@
+# 数据分析 Agent 需求规格（答辩版 v1.2）
+
+> 定位：数据分析 Agent 专项需求规格 · 答辩展示用 · 需求基线以 JinRong 仓库已落地拆解为准
+> 范围声明：本文档只描述**数据分析 Agent**；其余 Agent 不在本文档范围内
+> 状态：§0~§9 已定稿（§9 含缓存+三层记忆方案）；v1.2 新增 §0.4~§0.8 背景论证、§1 痛点补全、§3 N-01~N-08 用例、§5 非功能补充；"新表结构"细节留待开发期
+
+---
+
+## §0 项目背景
+
+### 0.1 公司业务
+
+以**代销**为主的金融公司——产品线覆盖公募基金、私募基金、理财、固收、信托、保险、贵金属。本质是帮持牌机构代销产品、赚取服务费。**数据资产是业务的血液**：客户的持仓、交易、风险等级、产品销量，天天有人要。
+
+### 0.2 现状：两类"查数人"，两种困境
+
+数据需求方天然分成两类——**少数会写 SQL 的，和大多数不会写 SQL 的**。
+
+**① 视角 A：会写 SQL 的数据分析师**（数据中心/数据组的稀缺资源）
+
+```
+业务方提需求 → 分析师写 SQL 取数（同类问题反复写）→ 交付一堆表格 → 业务看不懂 → 分析师口头解释
+```
+
+痛点：
+1. **人肉取数机**：重复取数需求占日常大头，深度分析时间被挤占
+2. **口径靠个人**：同一问题不同分析师写出的 SQL 不同、结果对不上，为口径反复返工
+3. **交付即表格**：还要逐条解释给业务听
+4. **安全顾虑**：不敢把数据库开放给业务自助写 SQL——怕乱写、注入、误操作
+
+**② 视角 B：不会写 SQL 的内部员工**（业务、运营、理财经理等大多数）
+
+```
+员工想查数 → 自助报表覆盖不了 → 提工单 → 数据专员/主管审批
+→ 敏感/超权限需求 → 安全部/信息部审计加签 → IT 数据管理接单 → 写 SQL → SQL 安全审核
+→ 交付 → 关闭工单 → 全程留痕
+```
+
+痛点：
+1. **慢**：审批链走完急数等不起
+2. **依赖人**：能否查到、对不对，全看写 SQL 的人
+3. **权限模糊**：不知道"我能看什么"，敏感数据加签沟通成本高
+4. **留痕体系笨重**：安全审计正确但流程冗长
+
+### 0.3 结构性矛盾
+
+> 需求在绝大多数人手里，供给却在极少数人手里，中间还隔着一整条审批工单链。
+> 数据分析 Agent 要做的：**把"会写 SQL 的人"的生产力，变成所有人都能自助调用的服务**——会写 SQL 的解放出来养 Agent，不会写 SQL 的自助查数，权限与安全由系统硬约束兜底。
+
+### 0.4 监管合规背景（一切硬约束的来源）
+
+以**代销**为主的金融公司，业务直接受证监会/基金业协会监管，客户数据与信息同时受《个人信息保护法》《数据安全法》《网络安全法》约束。**"只读不写、列级脱敏、全链路留痕、适当性不可绕过、面向客户内容须人工审核"这些在本文档里是功能需求，本质上都是监管红线**——不是加分项，而是上线前提。这也解释了为什么数据分析 Agent 把安全合规（§2 五层隔离、§5 审计留痕）放在与查数能力同等甚至更高的位置。
+
+### 0.5 为什么是 Agent，而不是现有 BI
+
+公司已有（或存在）帆软 / PowerBI / Tableau 一类固定报表工具，或数据中台。BI 的本质是**"按预定义维度看固定模板"**：报表维度、口径、下钻路径都是 IT 预先固化的，业务只能在框内点选。而数据分析 Agent 补的是 BI 覆盖不到的**"任意组合维度 + 即时追问 + 人话解读"**——「我名下 C3 以上且持有股票型基金又亏超 5% 的客户」这种临时组合，BI 无法预置，只能找分析师写 SQL。二者是互补关系：**BI 管"已知要看的固定报表"，Agent 管"临时冒出来的新问题"**。
+
+### 0.6 量化现状与目标基线
+
+> 现状为估算口径，上线后以真实运营数据回填作为效果基线。
+
+| 指标 | 现状（估） | 目标（一期上线后） |
+|---|---|---|
+| 单次取数工单平均闭环时长 | 1~3 天（含审批/加签/排期） | 分钟级自助出数 |
+| 重复/同形态取数占比 | 占取数需求大头 | 缓存命中率 ≥ 60% |
+| 分析师 : 业务需求人数比 | 1 : N（严重倒挂） | 分析师转向"养 Agent" |
+| 口径不一致返工 | 同类问题反复对账 | 关键指标一问一义（D-07） |
+
+### 0.7 为什么是现在
+
+过去 NL2SQL 不敢上生产，是因为模型准确率不足、幻觉不可控、权限兜不住。现在**大模型 NL2SQL 能力 + 只读强校验 + 五层权限隔离 + 数字护栏（D-10）** 同时到位，让"可审计地让业务自助问数"从风险变成可控工程——这正是本项目的时点窗口。
+
+### 0.8 为什么先做数据分析 Agent（四 Agent 全局定位）
+
+四个 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座。数据分析 Agent 被排在第一波，是因为它**只读、不碰客户资金、不触达 C 端、合规面最小、闭环最快**——是四个里风险最低、最容易打样的一个；跑通后其口径字典 / 缓存 / 权限隔离可复用到其余 Agent。
+
+---
+
+## §1 痛点 → AI 价值映射
+
+| # | 视角 | 痛点 | Agent 做什么 | 可验证收益 |
+|---|---|---|---|---|
+| 1 | A 分析师 | 人肉取数机，重复写 SQL | NL2SQL 自助查数 | 从"写 SQL"转向"养 Agent"（口径字典/few-shot） |
+| 2 | A 分析师 | 口径不统一，结果打架 | 口径字典+元数据注入，一问一义 | 减少返工与扯皮 |
+| 3 | A 分析师 | 交付表格还要费心解释 | 人话结论解读 | 业务看答案即懂 |
+| 4 | A 分析师/安全 | 业务方乱写 SQL 有破坏风险 | 只读强校验，仅允许 SELECT | 数据库只读兜底 |
+| 5 | B 员工 | 工单审批排队，急数等不起 | 自然语言即时问答 | 分钟级出数，免排队 |
+| 6 | B 员工 | 权限模糊、敏感数据全靠人工加签 | RBAC 行级权限自动裁决 | 该看的秒查，不该看的 403，全程留痕 |
+| 7 | 公司 | 重复查询反复烧资源 | 查询缓存 | 省 LLM 与数据库成本 |
+| 8 | B 员工/公司 | 指标口径二义性（"规模/盈亏/近30天"多定义） | 指标消歧反问 + 口径字典一问一义 | 从根上减少返工扯皮 |
+| 9 | B 员工 | 数据新鲜度不可感知，拿过期数当实时用 | 响应带 data_as_of 数据截至时间 | 决策不再踩"过时数据"的坑 |
+| 10 | B 员工 | "查不到"与"结果为 0"混淆 | 空结果/零结果区分（N-02） | 避免把"没数据"误判成"没有" |
+| 11 | 分析师/合规 | 唯一能看明文的人，管控却最弱 | 明文查看二次确认 + 时效授权 + 单独审计 | 最大风险点被硬约束 |
+| 12 | 公司 | 查询成本不可感知、无节制提问 | 成本计量 + 配额限流（N-04） | 成本可见可控 |
+| 13 | B 员工 | 好结果不能复用/分享/订阅 | 结果保存/分享/订阅（N-05） | 一次查询，全员复用 |
+| 14 | B 员工 | 数字不可信、无法溯源明细 | 聚合可钻取抽样明细（N-03） | 业务能自证，AI 数才敢用 |
+| 15 | 公司 | 分析师离职，口径失传 | 资产半自动沉淀 + 版本化/回滚（D-11） | 口径资产不随人走 |
+
+---
+
+## §2 角色与权限矩阵（含权限隔离设计）
+
+### 2.1 角色矩阵
+
+| 角色 | staff_type | 数据域 | 明细粒度 | 敏感列 |
+|---|---|---|---|---|
+| 数据分析师 | analyst | 全量 | 全明细 | ✅ 可见（唯一可维护口径字典者） |
+| 理财顾问 | advisor | **仅名下客户**（core_customer_advisor active 归属） | 名下客户明细 | 手机号等**脱敏** |
+| 风控专员 | risk_officer | 台账全量 + 客户只读 | 台账含触发规则/风险分 | 客户脱敏 |
+| 运营/业务等 | ops 等 | **无客户维度** | 仅聚合（产品/时间/风险等级） | 一律不可见 |
+
+> 合规官（compliance）：一期不开放直接查数，权限后续另行设计；越权行为由 RBAC 隔离兜底。
+
+### 2.2 权限隔离：五层纵深
+
+| 层 | 机制 | 说明 |
+|---|---|---|
+| 1 身份 | Mock JWT（HS256，24h 续期） | Payload 含 user_type / employee_role，确定"你是谁" |
+| 2 角色 | RBAC | 角色决定数据域（可碰哪些表）与操作（全部只读） |
+| 3 **行级归属** | **归属强制注入 + 二次校验** | 顾问查询在 SQL 生成阶段强制注入 `WHERE customer_id IN (名下 active 客户)`，非模型自觉；归属白名单实时取自归属表（转岗/离职立即失效）；AST 校验阶段检查查询范围是否超授权，超范围 → 403 |
+| 4 列级脱敏 | 存储层已脱敏 | 身份证前3后4、手机号前3后4、姓名留姓、卡号留后4；API/日志/归档全链路一致 |
+| 5 粒度控制 | 聚合 vs 明细 | 运营只能拿"客户维度之上"的聚合；任何下钻到客户维度 → 拒绝 + 说明原因 |
+
+**越权处理**：403 + 双留痕（`audit_log` 总账 + `analytics_query_log` 记录问题与拒绝原因），可演示"顾问 A 问顾问 B 的客户 → 被拒且留痕可查"。
+
+**答辩一句话**：权限隔离不是"提示词别越权"，而是身份 → 角色 → 行级归属注入 → 列级脱敏 → 粒度控制五层纵深；行级由系统强制注入并二次校验，列级在存储层就脱敏，越权行为全量留痕。
+
+---
+
+## §3 需求用例明细
+
+### 输出结构（全局约定）
+
+```json
+{
+  "answer": "人话解读…",
+  "table": { "columns": ["risk_code", "cnt"], "rows": [["C1", 4], ...] },
+  "sql": "SELECT …",
+  "meta": { "exec_ms": 45, "row_count": 5, "cache_hit": false, "data_as_of": "2026-09-04", "source": "jinrong_core", "cost_est": 0.002 },
+  "disclaimer": "本内容仅为投资分析参考，不构成任何直接投资建议，不构成对任何产品的收益承诺，据此操作风险自负，请谨慎对待。"
+}
+```
+
+### D-01 客户侧查数（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为理财顾问/分析师，我想用大白话查客户持仓、流水、规模、风险分布，不写 SQL 即掌握客户现状 |
+| 输入示例 | 「我名下 C3 及以上风险等级的客户有几个？」「CUST-9527 的持仓和盈亏是多少？」 |
+| 期望输出 | 人话解读 + 表格 + SQL + 来源 |
+| 拒绝/边界 | 越权客户 → 403 留痕；语句含买卖倾向 → 拒答 |
+| 验收口径 | 两类示例问题返回「解读+表格+SQL」；顾问查非名下客户得到明确拒绝且审计可查 |
+
+### D-02 产品侧查数（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为内部员工，我想查产品的销售/规模/净值等事实数据 |
+| 输入示例 | 「近 30 天各类型产品申购金额排名」「PROD-005827 最新净值多少」 |
+| 期望输出 | 销售/规模/净值**事实**，可溯源 |
+| 拒绝/边界 | 不做优劣对比/推荐——「哪只产品值得买」→ 拒答并说明 |
+| 验收口径 | 事实回答正确；推荐类问题被拒 |
+
+### D-03 风险台账统计（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为风控专员/分析师，我想查预警台账的数量、状态、类型分布 |
+| 输入示例 | 「当前未处理的预警有多少？」「预警按类型怎么分布？」 |
+| 期望输出 | 数量/状态/类型分布统计 |
+| 拒绝/边界 | 可看不可处置——「把 XX 预警标记为确认可疑」→ 拒答 |
+| 验收口径 | 统计正确；处置意图被拒且留痕 |
+
+### D-04 留痕与输出边界（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为合规/分析师，我需要每次查数过程可追溯、输出不越界 |
+| 机制 | 每次问答、生成的 SQL、结果摘要强制落 `analytics_query_log`（trace_id 可还原全链路）；对外风格输出带免责声明；不生成可执行的买卖/处置指令 |
+| 验收口径 | 任意一次问答可按 trace_id 还原「问题→SQL→结果→判定」 |
+
+### D-05 复杂交叉问数（P1）
+
+| 项 | 内容 |
+|---|---|
+| 输入示例 | 「名下客户中，持有股票型基金且亏损超 5% 的，按持仓规模排序」 |
+| 机制 | 仅只读多表聚合；超权限字段拒绝 |
+| 优先级 | P1（答辩提一句） |
+
+### D-06 查询缓存（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 重复查询不重复消耗 LLM/数据库资源 |
+| 机制 | 结果缓存（同形态独立问题秒回）+ 模板缓存（同形态问题填参执行）；命中留痕标 `cache_hit=true`；缓存键含权限指纹；PII 结果不落缓存或脱敏；TTL 分层（交易类 5min / 台账类 1h / 基础信息类当日）；**源数据更新时主动失效**（交易/持仓/归属等事实表变更时 DEL 对应缓存键，不等 TTL 自然过期）；响应 `meta` 增加 `data_as_of`（数据截至时间，区分 T+1 / 准实时） |
+| 验收口径 | 同形态问题第二次响应显著加快，且留痕可见 cache_hit=true；源数据刷新后旧缓存不再被命中；响应可见 data_as_of |
+
+### D-07 口径统一（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 同一指标所有人查出口径一致，且口径定义可查 |
+| 机制 | 口径字典（指标名→定义/公式/适用表）+ schema 元数据注入 + few-shot |
+| 验收口径 | 「持仓规模」「在途资金」等关键指标跨角色查询结果一致、定义可调出 |
+
+### D-08 兜底与拒答（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 查不了/权限不足/问题含糊时，系统明确说明原因，绝不编造 |
+| 机制 | 数据不在范围/权限不足/问题含糊/敏感意图 → 说明性拒绝 + 留痕；权限不足类拒答附带**可查范围引导**（如"你仅能查名下客户，可尝试问 X 类问题"），降低挫败、避免反复误触越权 |
+| 验收口径 | 超范围问题得到说明性拒绝，而非编造数据；权限拒绝时附范围引导 |
+
+### D-09 多轮追问（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 支持基于上文的追加查询 |
+| 输入示例 | 先问「我名下客户的风险等级分布」，再问「那再按产品类型分一下呢？」 |
+| 机制 | 短期记忆承载会话上下文；追问走**上轮 SQL 受限改写**（非模板命中），改写失败自动降级为全新生成；**追问继承上轮口径四件套**（指标定义、时间窗、维度、脱敏级别），降级重生成时同样带上，避免"同一指标前后两个定义"；看板钻取复用此链路 |
+| 验收口径 | 追问可正确承接上文语义并给出对应结果 |
+
+### D-10 数字护栏：解读与结果一致性校验（P0 · 亮点）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为查数员工，我担心 AI 解读时说错数字；作为合规/分析师，我需要输出与数据**逐字对得上** |
+| 机制 | 解读生成后强制校验，四道：① 提取解读中全部数字/金额，与 SQL 结果逐项比对；② **单位/币种/百分比一致性**（元 vs 万元、% vs bp）；③ **时间窗一致性**（"近 30 天"按自然日还是交易日解析正确）；④ **聚合结果抽样复核**（抽 1~2 行回源明细核对）。任一不一致 → 重生成（默认 1 次）→ 仍不一致 → **降级输出**（只给表格 + "解读校验未通过，以数据为准"），绝不带错字 |
+| 期望输出 | 正常：解读+表格+校验通过标记；降级：表格+校验失败提示 |
+| 留痕 | 校验结果（通过/重试/降级）写入 result_summary + audit |
+| 验收口径 | 造"解读故意写错数字"的用例必须被拦截并降级；正常用例校验全部通过 |
+| 答辩台词 | **"LLM 有幻觉，但我们不赌它不犯——我们校验它。"** |
+
+### D-11 "养 Agent"闭环：Query → Sample → Dict 沉淀（P0 · 亮点）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为数据分析师，我不再给每个人写 SQL，而是把一次好查询变成 Agent 的长期资产 |
+| 机制 | 每次查询结束后分析师可沉淀三类资产：① few-shot 示例（问题→正确 SQL 对）② 口径字典条目（指标名→定义/公式/适用表）③ 快速模板（参数化 SQL 模板）；**沉淀后需分析师确认发布才生效**；生效后同类问题命中新资产（与 D-06/D-07 联动，喂养模板缓存）；**资产版本化 + 可回滚 + 可灰度**（发布错一键回退，先灰度部分用户验证再全量）；系统从每次已执行 SQL 中**半自动提炼候选模板**，分析师仅确认，降低沉淀成本 |
+| 边界 | **仅 analyst 角色可写**；每次沉淀操作审计留痕；沉淀内容可溯源 |
+| 涉及存储 | 新增 `analytics_few_shot` + `analytics_query_template` 表（或与字典合一，**表结构开发期确认**） |
+| 验收口径 | 分析师沉淀一条 few-shot 并发布后，同类新问题回答引用到它（留痕可见 source=沉淀资产）；字典条目可被解读引用并附链路 |
+
+### D-12 智能看数板（P0 · 亮点）
+
+| 项 | 内容 |
+|---|---|
+| 定位 | 数据分析 Agent 的**零门槛入口**：不用提问，进来先看"我关心的关键指标"概览；是"预聚合概览 + 钻取入口"，不是独立报表系统 |
+| 角色化卡片 | 分析师：客户总数/总持仓规模/今日交易笔数与金额/待处理预警数/口径字典资产数；理财顾问：名下客户数/名下资产规模/盈亏分布/风险等级分布（仅名下）；风控专员：待处理预警数/按类型分布/近 7 天新增趋势；运营：近 30 天申购/赎回金额/各产品类型规模 TOP（仅聚合） |
+| 关键交互 | 卡片可**钻取追问**——点「待处理预警数」→ 进入「按类型分布一下」→ 复用 D-09 多轮追问链路，指标与对话打通 |
+| 边界 | 看板数据同样走只读层 + 角色权限（顾问看板仅名下聚合，运营看板仅聚合）；加载与钻取留痕；不做实时刷新（准实时/按需） |
+| 本期形态 | 后端提供看板数据接口（结构化 JSON）；前端下轮渲染可视化面板 |
+
+### N-01 指标消歧反问（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为查数员工，我用的词（规模/盈亏/近30天）有多个口径，系统应先跟我确认，而不是猜 |
+| 机制 | 问题含多义指标时，Agent 列出候选口径并反问澄清（"持仓规模是指市值还是成本？"）；澄清后绑定到本轮会话口径上下文，追问继承（联动 D-09） |
+| 验收口径 | "规模"类多义问题被反问澄清，澄清后结果口径与所选定义一致 |
+
+### N-02 空结果 vs 零结果区分（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 查不到数时，我要知道是"确实为 0"、"无数据"、还是"口径条件不命中" |
+| 机制 | 查询无数据时，区分三态：`zero`（真为 0）/ `no_data`（源无此数据）/ `not_match`（条件不命中），写入解读与留痕；绝不把"查不到"说成"没有" |
+| 验收口径 | 三类空态分别得到准确说明，且留痕可见状态标记 |
+
+### N-03 溯源到明细（P0）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 聚合数字我要能钻到抽样明细自证，才敢信 AI 出的数 |
+| 机制 | 聚合结果可钻取抽样明细（脱敏后，行数受限），回源可核对；与 D-10 护栏抽样复核共用链路 |
+| 验收口径 | 任意聚合结果可按需展开抽样明细，明细与聚合一致 |
+
+### N-04 查询成本计量与配额（P1）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为系统负责人，我要知道谁在烧钱、每次问数成本多少，并能限流 |
+| 机制 | 按用户/角色设查询预算与限流（复用 `guard:rate`）；响应 `meta` 带本次成本估算；月度用量进运营看板 |
+| 验收口径 | 超配额被限流并提示；meta 可见成本估算；用量可汇总 |
+
+### N-05 结果保存/分享/订阅（P1）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为查数员工，我查到的好结果想存下来、分享给同事、或订阅每日刷新 |
+| 机制 | 普通员工可"存为我的常用 / 分享给同事（继承接收方权限）/ 订阅刷新"；订阅走模板缓存填参执行，仅聚合、脱敏后落档 |
+| 验收口径 | 保存/分享/订阅结果可复用，且分享结果不突破接收方权限 |
+
+### N-06 数据质量提示（P1）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 我要知道这数字里有没有脏数据（空值/异常/未归因），而不是被当成干净结论 |
+| 机制 | 对空值、异常值、口径边缘（如"该指标含 X 条未归因数据"）在解读中给提示，不掩盖数据质量问题 |
+| 验收口径 | 含脏数据的指标查询，解读附带质量提示 |
+
+### N-07 人机协同兜底（P0 · 加分）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | SQL 生成失败/超时/报错时，我不想卡死，要能一键转人工 |
+| 机制 | 生成失败/超时/查不到表 → 除说明性拒答外，提供"一键转交分析师人工改写"入口，落审计（trace_id 串联）；分析师改写结果可回填沉淀为 D-11 资产 |
+| 验收口径 | 失败场景可转人工，且全链路留痕可还原 |
+
+### N-08 可观测性指标面板（P1）
+
+| 项 | 内容 |
+|---|---|
+| 用户故事 | 作为运营/负责人，我要看到 Agent 用得好不好、哪里要养 |
+| 机制 | 运营指标面板：SQL 一次通过率、缓存命中率、拒答率、平均耗时、月成本、口径字典使用率、转人工率 |
+| 验收口径 | 指标可实时/准实时查看，作为"养 Agent"决策依据 |
+
+---
+
+## §4 数据范围与口径
+
+### 4.1 数据源（一期 L0 模拟库，已核对种子）
+
+| 数据域 | 表 | 实况规模 | 写入方 → 读取 |
+|---|---|---|---|
+| 客户主档+风险等级 | `core_customer` + `core_customer_risk` | 28 位客户（C1~C5、高龄、大额特例） | Core → 只读 |
+| 客户-顾问归属 | `core_customer_advisor` | 5 位顾问分属 10/6/5/4/3 人 | Core → 只读（RBAC 依据） |
+| 持仓 | `core_holding` | ~45 条，as_of 2026-09-04 | Core → 只读 |
+| 交易+资金流水 | `core_trade` / `core_cash_flow` | 24 笔交易（含大额样例）+ 7 条流水 | Core → 只读 |
+| 产品+净值 | `core_product` / `core_product_nav` | 多只产品 + 净值 | Core → 只读 |
+| 员工账号 | `core_staff` | 5 类角色种子 | Core → 只读 |
+| 预警台账 | `jinrong_agent.risk_alert` | 由风控侧写入 | 只读（本 Agent 不写） |
+
+**答辩口径**：一期无真实 Core，用 L0 模拟库供给全部数据；真实环境换成正式 Core 只读连接，Agent 层代码零改动。
+
+### 4.2 读写权限
+
+- 只读：`jinrong_core` 全部、`risk_alert`
+- 只增：`analytics_query_log`（审计，禁止修改删除）
+- 分析师可写：口径字典表、few-shot/模板表（D-11，需确认发布生效）
+
+### 4.3 脱敏规则
+
+身份证前3后4 / 手机号前3后4（种子已存 mask）/ 姓名留姓 / 卡号留后4；API 响应、日志、对话归档全链路一致。
+
+---
+
+## §5 非功能需求
+
+| 类别 | 需求 |
+|---|---|
+| 安全 | 全部查询只读；注入/多语句拦截（AST 白名单 + 只读账号双保险）；越权拒绝留痕；敏感字段脱敏 |
+| 合规 | 免责声明（涉及建议倾向时）；不处置预警；不做产品推荐；不对客直发 |
+| 性能 | 查询超时与行数上限（默认 1000 行 / 10s，可调）；重复查询走缓存 |
+| 审计 | trace_id 全链路可还原（对话→SQL→结果→判定） |
+| 可运营 | 口径字典、schema、few-shot 可维护可迭代（养 Agent，D-11），资产版本化可回滚可灰度 |
+| 数据新鲜度 | 响应带 `data_as_of`；交易/持仓等事实数据源更新时缓存主动失效，不交付过期数 |
+| 成本 | 查询成本可计量，按角色配额限流（N-04），月度用量可汇总 |
+| 可观测性 | 运营指标面板（SQL 通过率/缓存命中率/拒答率/成本/转人工率，N-08） |
+| 可用性 | 并发与 SLA：明确超时降级（SQL 超时/LLM 超时转拒答或转人工 N-07），不拖垮只读库 |
+
+---
+
+## §6 边界（明确不做）
+
+- ❌ 任何写操作（改数、处置预警、改风险等级）
+- ❌ 投顾推荐（「该买哪只」→ 拒答并说明）
+- ❌ 对外输出（不直接对接客户）
+- ❌ 自动化报表/定时任务（一期）
+- ❌ 实时行情（用模拟净值数据）
+- ❌ 导出 CSV/文件（P1 再议）
+- ❌ 合规官单独查数角色（一期，靠 RBAC 隔离）
+
+---
+
+## §7 验收场景（兼答辩演示脚本）
+
+每类人群 2~3 条端到端问答，演示即验收：
+
+| 角色 | 演示问答 | 期望结果 |
+|---|---|---|
+| 分析师 | 「按产品类型统计总持仓规模」 | 表格+解读+SQL；正确 |
+| 分析师 | 「把 CUST-9527 持仓按盈亏排序」 | 表格+解读；无买卖倾向输出 |
+| 理财顾问 | 「我名下客户有多少位高风险？」 | 仅名下统计；表格+解读 |
+| 理财顾问 | 「查一下 CUST-1004（非名下）的持仓」 | **403 拒绝 + 审计留痕** |
+| 风控专员 | 「当前待处理预警中属于大额的占比」 | 统计+解读；不可处置 |
+| 运营 | 「近一个月申购金额总额」 | 聚合结果；无客户明细 |
+| 任意角色 | 同形态问题重复问 | 第二次 cache_hit=true |
+| 任意角色 | 「CUST-9527 持仓中金额加起来是 123 万元吗」 | 解读数字与表格一致（数字护栏） |
+| 分析师 | 沉淀一条 few-shot 并发布后问同类问题 | 命中沉淀资产（留痕 source） |
+| 任意角色 | 打开看数板 → 点卡片钻取 | 按角色出卡片；钻取进入对话 |
+| 任意角色 | 先问风险分布，再追问「按产品类型分一下」 | 追问承接上文（D-09 改写链路） |
+
+---
+
+## §8 合规定位
+
+- AI 仅作**投资分析辅助**，不代客交易、不直接触及客户资金与下单环节
+- 面向客户的内容须由持证投顾/客户经理**审核确认**后对接客户
+- 一切投资分析、财富报告、行业分析等输出必须备注免责声明（见 §3 输出结构）
+- 适当性匹配校验不可绕过（客户风险等级与产品风险等级匹配）
+
+---
+
+## §9 待定项与决策记录
+
+### 9.1 缓存 + 三层记忆方案（已定稿）
+
+```
+短期记忆（Redis·会话级·30min）→ D-09 追问上下文 / D-12 钻取链路 / 数字护栏重试
+中期记忆（Redis·用户级·轻量版）→ 常用查询 TOP + 偏好口径，调优缓存 TTL 与看板排序
+长期记忆（MySQL 资产表）→ D-11 沉淀资产（few-shot/字典/模板），喂养模板缓存
+
+结果缓存：同形态独立问题直接秒回（键含权限指纹；PII 不落缓存或脱敏；命中标 cache_hit=true）
+模板缓存：跨会话同形态问题填参执行（资产发布后自动入池）
+追问变体：不走命中，走上轮 SQL 受限改写（Constrained Edit），失败自动降级为全新生成
+```
+
+### 9.2 待开发期确认项
+
+| # | 待定项 | 当前立场 |
+|---|---|---|
+| 1 | 口径字典表结构（`analytics_metric_dict` / `analytics_few_shot` / `analytics_query_template`） | 需求已定（D-07/D-11），表结构开发期确认，需用户确认改表 |
+| 2 | D-12 钻取实现深度 | 已定做钻取；实现细节开发期细化 |
+| 3 | 看板刷新策略 | 已定准实时/按需；不做实时推送 |
+
+### 9.3 决策记录
+
+| 决策点 | 结论 |
+|---|---|
+| 范围 | 仅数据分析 Agent；基线=JinRong 拆解 |
+| 缓存+口径 | 均纳入 P0 |
+| SQL 安全 | AST 白名单 + 只读连接双保险 |
+| P0 完成标准 | D-01~D-04 闭环（后扩展 D-09~D-12 + N-01/N-02/N-03/N-07 P0 增强） |
+| 权限 | 四类角色分层；五层隔离（身份/角色/行级归属/列级脱敏/粒度） |
+| 输出 | 四件套 answer+table+sql+meta；导出不做；合规官一期不开放 |
+| D-09 | 做 P0，追问走 SQL 改写 |
+| D-10 | 数字护栏，重试 1 次后降级 |
+| D-11 | 养 Agent 闭环，确认发布后生效 |
+| D-12 | 智能看数板，角色化卡片 + 钻取 |
+| 缓存+记忆 | 结果/模板双层缓存 + 短期/中期/长期三层记忆（见 9.1） |
+| 背景补全 | 监管合规背景 + "Agent vs BI"定位 + 量化基线 + 时点论证（§0.4~§0.8） |
+| N-01~N-08 | 消歧反问 / 空零区分 / 溯源明细 / 成本配额 / 复用分享 / 数据质量 / 人机协同 / 可观测性 纳入需求基线（P0/P1 见 §3） |
+| D-06/D-08/D-09/D-10/D-11 强化 | 缓存事件失效 + data_as_of；拒答引导；口径继承；护栏四道校验；资产版本化回滚灰度 |
+
+---
+
+*本文档为需求基线，用例 ID 与仓库 `业务场景优先级清单.md` / `数据交互矩阵.md` 体系衔接；技术实现细节落地前需另行确认。*
+
+---
+
+## 变更记录
+
+| 版本 | 日期 | 变更 |
+|---|---|---|
+| v1.0 | 2026-09 | 初版：D-01~D-05 + 五层权限隔离 |
+| v1.1 | 2026-09 | 定稿 D-01~D-12 + 缓存/三层记忆方案（§9） |
+| v1.2 | 2026-09 | 补监管背景与"Agent vs BI"论证（§0.4~§0.8）；痛点补全（§1）；新增 N-01~N-08；强化 D-06/D-08/D-09/D-10/D-11；§5 补数据新鲜度/成本/可观测性/可用性 |