# 投顾 Agent 需求文档（PRD）

> 文档版本：v1.0（2026-09-16）
> 文档状态：**已实现反推稿** —— 本章所记需求均已在本仓库落地并本地验证，非前瞻设计
> 适用范围：投顾 Agent（投顾工作台 + 客户端「我的投顾方案」+ 客户主动申报）
> 依据材料（均为仓库内既有文档与代码，非本文件臆造）：
>   · 设计：`docs/01`（通用 Agent 平台）、`docs/03`（端到端流程）、`docs/05`（接口文档）、
>     `docs/22`（四大 Agent 拆解）、`docs/30`（投顾迁移 TODO）、`docs/31`（投顾灰度与回滚）、
>     `docs/43`（场内产品手册）、`docs/44`（演示流程）
>   · 代码：`app/service/product_recommendation_service.py`、`advisor_service_request_service.py`、
>     `advisor_reason_service.py`、`app/api/controllers/recommendations.py`、`advisor_service_requests.py`、
>     `app/static/portal/employee-advisor/dashboard/*`、`app/static/portal/customer/advisor-plans/*`

---

## 1. 背景与目标

### 1.1 问题陈述

投顾业务的真实痛点在于「**选品可解释 + 交付可追溯**」：

- 投顾给客户荐品，必须能说清**为什么是这几只**（适当性匹配、期限/流动性匹配、证据可核查）；
- 方案从生成到到达客户手里，必须**留痕**、且**未经审核不得对客户可见**；
- 客户侧长期是单向接收，缺少「主动提出需求」的入口。

此前系统里推荐能力存在，但存在三处断点：

| 断点 | 表现 |
|---|---|
| 交付无落点 | 投顾「发送给客户」只改数据状态，客户端没有任何页面/接口能读到已发布方案 |
| 文案不可读 | 每只产品的「推荐依据」是同一句套话，客户看不出差异 |
| 客户无入口 | 客户只能被动等方案，无法主动申报 |

### 1.2 目标（G）

| 编号 | 目标 | 衡量方式 |
|---|---|---|
| G1 | 推荐**可解释**：每只入选产品都能给出基于真实参数的依据 | 方案里每只产品都有独立依据，且含风险等级/匹配关系 |
| G2 | 交付**可追溯**：审核与发布分离，未发布对客户不可见 | 状态机 + `published_at` 双条件；客户接口只返回已发布 |
| G3 | 呈现**可感知**：客户能看到走势图、指标与组合构成 | 客户端可展示净值折线图、环形配置图、区间收益与最大回撤 |
| G4 | 客户**能发起**：客户可主动申报，投顾后台受理后出方案 | 申报→受理→生成草稿→审核→发送 全链路打通 |
| G5 | 合规**不越线**：不得承诺收益，证据缺失即整只排除 | 硬约束 fail-closed + 文案合规守卫 |

### 1.3 非目标（本期明确不做）

| 非目标 | 说明 |
|---|---|
| 真实下单 | 推荐方案**不产生交易指令**，客户仍需在交易页自行下单 |
| 收益预测 | 不预测未来收益，只呈现历史区间收益与最大回撤 |
| 自动投资 | 无自动调仓、无定投、无代客操作 |
| 场外基金 | 投顾范围限定场内基金，场外走独立模块（见 `docs/22`） |

---

## 2. 角色与场景

### 2.1 角色定义

| 角色 | 角色码 | 入口 | 核心诉求 |
|---|---|---|---|
| 投顾 | `advisor` | `/portal/employee-advisor/dashboard/` | 代客出方案、审核发布、处理客户申报 |
| 客户 | `customer` | `/portal/customer/advisor-plans/` | 接收方案、主动申报、查看申报进度 |
| 管理员 | `admin` / `super_admin` | 管理面 | 审核、发布、故障处置（不受灰度限制） |

### 2.2 核心场景

| 编号 | 场景 | 触发方 |
|---|---|---|
| SC-01 | 投顾选择名下客户 → 生成推荐方案 → 审核通过 → 发送给客户 | 投顾 |
| SC-02 | 投顾查看历史方案记录（含草稿）→ 抽查内容详情 | 投顾 |
| SC-03 | 客户登录 → 在「我的投顾方案」查看已收到的方案 | 客户 |
| SC-04 | 客户提交投顾方案申报 → 投顾受理 → 自动出草稿 | 客户→投顾 |
| SC-05 | 投顾受理后审核、发布，客户看到方案变为「已发送方案」 | 投顾→客户 |

---

## 3. 业务流程

### 3.1 主链路 A：投顾主动出方案

```mermaid
flowchart LR
    A[投顾选择客户] --> B[合规熔断校验 FM-03]
    B -- 测评失效 --> X[熔断拦截 转人工]
    B -- 通过 --> C[生成推荐方案]
    C --> D{候选池硬约束}
    D -- 某产品缺证据 --> E[整只排除 fail-closed]
    D -- 通过 --> F[排序取 TopN]
    E --> F
    F --> G[LLM 生成推荐依据]
    G --> H[落库 pending_review]
    H --> I[投顾审核通过]
    I --> J[发布给客户]
    J --> K[客户可见]
```

### 3.2 主链路 B：客户主动申报

```mermaid
flowchart LR
    A[客户填写申报单] --> B[服务端校验风险测评有效性]
    B -- 未测评/已过期 --> X[拒绝 并提示原因]
    B -- 通过 --> C[落库 pending]
    C --> D[投顾工作台出现待办]
    D --> E{投顾受理 or 驳回}
    E -- 驳回 --> F[填理由 客户可见]
    E -- 受理 --> G[自动跑推荐逻辑 出草稿]
    G --> H[投顾审核 + 发送]
    H --> I[申报单变 已发送方案]
```

---

## 4. 功能需求

优先级：**P0** 本期必须 / **P1** 重要 / **P2** 增强。

### 4.1 客户与画像

| 编号 | 功能 | 口径 | 优先级 | 验收标准 |
|---|---|---|---|---|
| FR-01 | 投顾查看名下客户 | 范围 = 本人 + `sys_customer_assignment` 归属客户 | P0 | 非归属客户不可见，越权返回 403 |
| FR-02 | 风险测评（客户自助） | `ONB001` 取题 / `ONB002` 提交；结果落服务端权威画像 | P0 | 测评结果由服务端权威返回，前端不得自行计算风险等级 |
| FR-03 | 熔断前置校验 | 测评超过 12 个月或缺失 → FM-03 拦截 | P0 | 前端展示熔断横幅，接口返回 `blocked_by_fuse` |

### 4.2 组合诊断与配置

| 编号 | 功能 | 口径 | 优先级 | 验收标准 |
|---|---|---|---|---|
| FR-04 | 组合分析 | 集中度、行业穿透与流动性 | P1 | 返回可展示的诊断结论 |
| FR-05 | 资产配置 | 按风评与目标给出配比与偏离 | P1 | 目标缺失时返回 `investment_goal_required` |
| FR-06 | 画像评分 | 本地演示引擎计算（后端无对应接口，明确标注"规则模拟"） | P2 | 结果区必须带演示标识 |
| FR-07 | 调仓建议 | 同上，本地引擎 | P2 | 结果区必须带演示标识 |

> FR-06/FR-07 由本地演示引擎计算，前端会明确标注；**不得**被误认为真实后端结论。

### 4.3 推荐方案生成（核心）

| 编号 | 功能 | 口径 | 优先级 | 验收标准 |
|---|---|---|---|---|
| FR-08 | 生成推荐方案 | `POST /api/v1/advisor/recommendations`，需 16-128 位 ASCII 幂等键 | P0 | 同键重试返回同一方案，不重复建单 |
| FR-09 | 候选池硬约束 | 产品须同时具备：场内可交易 + 销售机构**已验证**适当性证据 + 基金合同快照；缺任一即整只排除 | P0 | 排除原因可查（前端「排除原因」提示词） |
| FR-10 | 排序与入选 | 按适当性等级、目标期限、目标流动性筛选后综合打分取 TopN（默认 3） | P0 | 返回 `selection_summary`：候选/入选/排除数 |
| FR-11 | 推荐依据生成 | 规则文案兜底；配置大模型时改写为面向客户的说明 | P0 | 文案必须含真实参数；命中收益承诺词即丢弃并回退 |
| FR-12 | 审核 | `reviews` 接口，decision ∈ {approved, rejected} | P0 | 未审核不得发布 |
| FR-13 | 发布 | `publications` 接口，置 `review_status` 与 `published_at` | P0 | 发布后客户可见；重复发布幂等 |

### 4.4 历史记录与交付

| 编号 | 功能 | 口径 | 优先级 | 验收标准 |
|---|---|---|---|---|
| FR-14 | 历史方案记录 | 本人生成的全部状态方案 | P0 | 状态标签与后端状态一致，不使用枚举兜底文案 |
| FR-15 | 客户接收方案 | `GET /api/v1/users/me/advisor-contents`：只看**本人**、已审核且 `published_at` 非空 | P0 | 未发布的方案对客户不可见 |
| FR-16 | 方案可视化 | 净值折线图（带坐标轴/网格）、组合业绩（等权合成 + 最大回撤）、资产配置环形图 | P1 | 数据缺失显示「暂无数据」，不显示 0 |

### 4.5 客户主动申报

| 编号 | 功能 | 口径 | 优先级 | 验收标准 |
|---|---|---|---|---|
| FR-17 | 客户提交申报 | 金额（万元）/ 投资期限 / 风险偏好 / 备注 | P0 | 服务端校验取值与风评有效性 |
| FR-18 | 我的申报 | 只看自己的申报单与状态 | P0 | 状态含 待受理/已受理/已发送/已驳回 |
| FR-19 | 投顾申报队列 | 本人 + 归属客户的申报，待受理排前 | P0 | 非归属客户的申报不可处理 |
| FR-20 | 受理并生成方案 | 受理即调用现有推荐逻辑自动出**待审核草稿** | P0 | 生成失败给出人话原因，并保持待受理 |
| FR-21 | 驳回 | 需填理由（可选），客户可见 | P1 | 驳回后申报单不可再被受理 |

---

## 5. 业务规则

### 5.1 候选池硬约束（fail-closed）

产品必须同时满足三项，缺一即排除：

1. **场内可交易**；
2. **适当性证据**：销售机构的**已验证**适当性证据，带可核查来源链接与 `document_sha256`；
3. **合同快照**：基金合同快照，同样带来源与摘要。

按目标继续过滤：

| 维度 | 规则 |
|---|---|
| 风险等级 | 客户风评等级对应的禁投风险级直接排除 |
| 投资期限 | 短于目标期限下限的产品排除 |
| 流动性 | 不符合目标流动性要求（如 30 日内可用）的产品排除 |

### 5.2 合规红线（必须遵守，代码强制）

| # | 红线 |
|---|---|
| 1 | 不得出现收益承诺与绝对化表述（保本/保证收益/稳赚/无风险/收益承诺…） |
| 2 | 未审核发布的方案对客户不可见 |
| 3 | 推荐不产生交易指令，仅作分析参考 |
| 4 | 客户不得自行修改风险测评结果（服务端权威） |
| 5 | 全流程留痕（审核、发布、受理、驳回均记录操作人与时间） |

### 5.3 状态机

**推荐方案**

```mermaid
stateDiagram-v2
    [*] --> pending_review: 生成方案
    pending_review --> approved: 审核通过
    pending_review --> rejected: 驳回
    approved --> 已发布: 发送给客户
    rejected --> [*]
    已发布 --> [*]
```

> 「已发布」不是独立状态字段，而是 `review_status ∈ {approved, published}` **且** `published_at` 非空 —— 避免两处状态各写各的而对不上。

**客户申报单**

```mermaid
stateDiagram-v2
    [*] --> pending: 客户提交
    pending --> accepted: 投顾受理（自动生成方案草稿）
    pending --> rejected: 投顾驳回
    accepted --> 已发送: 关联方案发布后推导
```

> `已发送（delivered）` 同样**不落库**，由关联方案的 `published_at` 推导。

### 5.4 熔断 FM-03

| 条件 | 结果 |
|---|---|
| 无风险测评 | 拦截，提示先完成测评 |
| 测评超过 12 个月 | 拦截（服务端判 `valid_until`，缺失时按 12 个月兜底） |
| 熔断生效时 | 客户仅可办理赎回，流程转人工 |

---

## 6. 非功能需求

| 类别 | 要求 |
|---|---|
| 幂等 | 写接口必须带 16-128 位 ASCII `Idempotency-Key`；同键重试返回首次结果 |
| 降级 | 图谱（Neo4j）、大模型、行情任一不可用，业务**继续可用**并明确标注降级 |
| 留痕 | 审核/发布/受理/驳回写入审计；演示口径留存 ≥ 20 年 |
| 限流 | 按「用户 + 方法 + 路由」计数，超限 429；Redis 不可用时降级放行 |
| 灰度 | `ADVISOR_ROLLOUT_ENABLED` 开启后仅白名单客户与管理员可访问投顾业务 |
| 前端一致性 | 同一页面内同一模块的 `?v=` 版本号必须一致（否则双实例） |

---

## 7. 异常处理

| 场景 | 返回 | 前端呈现 | 可恢复动作 |
|---|---|---|---|
| 客户无风险测评 | `profile_required` | 结果区提示 | 先做风险测评 |
| 无已确认投资目标 | `investment_goal_required` | 结果区提示 | 先录入并确认目标 |
| 推荐数量越界 | 422 `RECOMMENDATION_PARAM_INVALID` | 结果区提示 | 改为 1-3 |
| 权限不足 | 403 | 「当前账户暂不可访问 / 权限不足」+ toast | 换有权限的账号 |
| 未开户（资金类） | 404 | 「客户未开户」 | 先建模拟账户 |
| 行情/净值缺失 | 503 / 空数据 | 「暂无净值数据」 | 跑 `tools/sync_nav_history.py` |
| 大模型不可用 | 无异常 | 依据回退为规则文案 | 关闭开关或换 key |
| 熔断 | `blocked_by_fuse` | 熔断横幅 | 转人工 |

---

## 8. 权限矩阵

| 能力 | 客户 | 投顾 | 管理员 |
|---|---|---|---|
| 提交/查看**自己的**申报 | ✅ `advisor-request:write:self` / `read:self` | — | — |
| 查看**自己的**已发布方案 | ✅ `product-recommendation:read:self` | — | — |
| 生成/查看/删除推荐方案 | — | ✅ | ✅ |
| 审核 / 发布方案 | — | ✅（自助） | ✅ |
| 查看客户申报队列 | — | ✅ `advisor-request:read` | ✅ |
| 受理 / 驳回申报 | — | ✅ `advisor-request:review` | ✅ |
| 灰度限制 | — | 受白名单限制 | 不受限 |

> 权限码定义源：`tools/seed_test_rbac.py`；投顾角色的授权工具：`tools/grant_advisor_role.py`。

---

## 9. 数据需求

| 表 | 用途 | 关键字段 |
|---|---|---|
| `client_facing_content` | 方案与方案书 | `content_type` / `customer_id` / `review_status` / `published_at` / `draft_content` |
| `advisor_service_request` | 客户申报单 | `request_no`(唯一) / `customer_id` / `amount_wan` / `horizon` / `risk_preference` / `status` / `result_content_id` |
| `sys_customer_assignment` | 投顾-客户归属 | 决定投顾可见范围 |
| `fin_product` / `fin_market_price` / `fin_nav_history` | 产品、行情、净值 | 图表与指标的数据源 |
| `api_request_receipt` | 幂等 | `user_id` / `scope_hash` / `idempotency_key` / `request_hash` |
| `interaction_audit` | 审计留痕 | 操作人、动作、明细 |

---

## 10. 验收清单

| # | 验收项 | 方法 |
|---|---|---|
| 1 | 投顾生成方案 → 结果区出现卡片与图表 | 工作台执行「生成推荐方案」 |
| 2 | 审核通过后发布 → 客户可见 | 客户页出现该方案 |
| 3 | 未发布方案对客户不可见 | 客户页不出现草稿 |
| 4 | 同幂等键重试不重复建单 | 连续两次提交同键 |
| 5 | 客户申报 → 投顾队列出现 → 受理后自动出草稿 | 两端对照 |
| 6 | 文案命中收益承诺词被丢弃 | 单测 `test_advisor_reason_service.py` |
| 7 | 大模型不可用时回退规则文案 | 关闭开关后重生成 |
| 8 | 越权客户不可见/不可处理 | 换非归属客户验证 403 |

---

## 11. 待确认问题

| # | 问题 | 影响 |
|---|---|---|
| Q1 | 适当性证据与合同快照的**真实数据来源**何时接入？当前候选为 0（证据缺失 fail-closed） | 阻塞：决定演示用真实方案还是本地引擎 |
| Q2 | 推荐依据是否允许出现历史业绩之外的表述（如基金经理风格）？ | 影响文案提示词 |
| Q3 | 客户申报是否需要额度/频率限制（防刷）？ | 影响 FR-17 |
| Q4 | 申报单与投资目标的关系：受理后是否自动创建投资目标？ | 影响 FR-20 之后流程 |
| Q5 | 灰度白名单的最终放量范围？ | 影响验收范围 |