group_xinghuo_jinrong/docs/项目管理/04-从需求到公共API开发方法.md

# 从需求到公共 API 开发方法

> 路径：`docs/项目管理/04-从需求到公共API开发方法.md`  
> 性质：**方法论文档 / 项目产出**（非会议纪要）  
> 适用：统筹（P1）搭公共底座与 Platform API；各 Agent 负责人联调接入  
> 制定：2026-09-08  
> 关联：[02-项目开发计划.md](./02-项目开发计划.md) · [03-表设计文档.md](./03-表设计文档.md) · [../需求拆解/数据交互矩阵.md](../需求拆解/数据交互矩阵.md) · [../memory/REQUIREMENTS.md](../memory/REQUIREMENTS.md)

---

## 0. 一句话

**先定需求 → 做数据交互矩阵 → 矩阵推出公共存储层 → 封装公共 Service/Repository → 暴露公共 API → 四个 Agent 按契约接入。**  
公共 API **不可能一次满足全部 Agent 脑洞**；第一批只覆盖 **Core L0 公共底座** 与 P0 场景。

---

## 1. 主流程（标准顺序）

```text
① 定需求（场景 ID、验收、禁止项）
        ↓
② 数据交互矩阵（谁采集 / 谁使用 / 读写 / 优先级）
        ↓
③ 公共数据底座 · 存储层（Core + agent 库 + Redis/Milvus/Neo4j）
        ↓
④ 公共底座函数（Repository / Platform Service，如 core_ro）
        ↓
⑤ 公共 API（REST + JWT + 归属；仪表盘与 Agent Tool 共用底层 Service）
        ↓
⑥ 四个 Agent（LangGraph + Tool；编排与 L1/L2/L3 enrich）
```

### 1.1 本仓库对应文档

| 步骤 | 产出 / 文档 |
| --- | --- |
| ① 定需求 | `docs/需求拆解/业务场景优先级清单.md` · `docs/memory/REQUIREMENTS.md` |
| 合规约束 | `docs/需求拆解/Agent风险与合规约束汇总.md` |
| ② 数据交互矩阵 | `docs/需求拆解/数据交互矩阵.md` |
| ③ 存储层 | `jinrong_core` / `jinrong_agent` · `docs/项目框架设计/表设计/` · Core 模拟底座 |
| ④ 公共函数 | `app/repository/core_ro.py` · `app/model/suitability.py` · `scripts/sync/` |
| ⑤ 公共 API | `app/api/auth.py` · **代销平台** `customers/products/advisors/compliance`（契约见《接口契约-代销平台API-v0.1》）· `simulate` · Agent 对话 `chat`（队友） |
| ⑥ Agent | 各负责人 `app/service/agent_service.py` 及 Tool |

---

## 2. 两个门闸（矩阵之后、写 API 之前）

### 门闸 A · 合规 / 架构硬规则

在搭接口前必须固定，避免各 Agent 各写一套：

| 规则 | 说明 |
| --- | --- |
| L0 权威 | Core 正式 C1~C5、持仓/交易真账；Agent **只读** |
| 画像边界 | L1/L2/L3 enrich **不得覆盖** L0 风评 |
| 唯一阻断 | **仅 R-02 适当性** 可阻断进入交易流程 |
| Agent 隔离 | 四 Agent **不互调 LLM**；跨 Agent 走画像表与预警表 |
| 审计 | `audit_log` 等 **只 INSERT** |
| 合规 | 不代客交易、不营销式推荐、代理人草稿不自动外发 |
| 平台出参脱敏 | `PLATFORM_RESPONSE_DESENSITIZE`（默认 **关**）；v0.1 模拟库原样返回；接真 Core 再开（Service 层统一出口） |

### 门闸 B · Wave / P0 裁剪

矩阵是全量的；**公共 API 只做 P0 + Core 已有能力**，其余联调驱动补充：

```text
矩阵（全量） → 筛 P0 场景 → 映射 core_ro 已有方法 → API v0.1
P1/P2        → 联调提需求 → 补 Repository → 升 API v0.2+
```

---

## 3. 分层定义（避免「数据底座」与「公共服务」概念打架）

| 层 | 叫什么 | 干什么 | 谁调用 |
| --- | --- | --- | --- |
| **存储层** | Core / agent 库 / Redis / Milvus / Neo4j | 存数据；**不对外讲业务** | 仅 Service / Repository |
| **公共 Service** | Platform Service · 公共底座函数 | 封装 L0 查询、R-02 规则、归属校验 | Agent Tool、REST 控制器 |
| **公共 API** | Platform REST | HTTP 契约；三类仪表盘 + Agent 可复用 | 前端、Agent（HTTP 或同进程 Service） |
| **Agent 层** | 四 Agent | 意图理解、Tool 编排、写 L1/L2/L3 | 调公共 Service/API，**禁止直连 Core SQL** |

**概念合并（下个项目可沿用）：**

- 旧称「数据底座」→ 现称 **存储层 + 公共 Service**（Core RO 是 Service 的实现细节，不是独立业务层）
- Agent 与前端 **共享公共 API/Service**，而不是「共享一套各自理解的底座」

---

## 4. 矩阵如何推出「公共存储层」

数据交互矩阵回答三件事：

1. **哪些是 L0 权威**（多 Agent 只读、口径唯一）→ 进 `jinrong_core`
2. **哪些是 Agent enrich**（谁写谁读）→ 进 `jinrong_agent` 画像/会话/审计表
3. **哪些是跨 Agent 交换**（适当性结果、预警台账）→ agent 库 + 事件

**凡矩阵中「四 Agent 只读 + 事实口径唯一」的对象，都属于公共底座（Core L0），由统筹封装 API。**

典型 L0 对象：客户主档、正式风评、归属、产品、持仓、申赎转流水、净值、C×R 矩阵。

---

## 5. 公共 API 的分批策略（现实做法）

### 5.1 不能一次做全的原因

- 各 Agent 的 **Tool 命名、多步编排、RAG、NL→SQL** 属于 Agent 层，开工时无法全部预知
- 仪表盘聚合、产品写 Milvus、工单等属于 **业务公共服务**，可与 Agent P0 并行、分 Wave 交付

### 5.2 三批交付（统筹侧）

| 批次 | 范围 | 说明 |
| --- | --- | --- |
| **Phase A · API v0.1** | Core L0 + P0；对齐现有 `core_ro.py` | **现在优先**；不依赖 Agent 脑洞 |
| **Phase B · 联调驱动** | Agent 提缺的 Core 查询/聚合；**C-05 行情外部同步** | 加 Repository 方法后再暴露 API；行情见下 §5.4 |
| **Phase C · 业务公共服务** | 仪表盘 KPI、产品 CRUD+Milvus、清算模拟 | 与 Agent 并行，不阻塞 P0 联调 |

### 5.4 Phase B · C-05 行情（已拍板方向 · 2026-09-09）

> **数据源选型：** [C-05-行情数据源选型对比.md](../项目框架设计/C-05-行情数据源选型对比.md)  
> **API 草案：** [接口契约-代销平台API-v0.2-行情扩展草案.md](../项目框架设计/接口契约-代销平台API-v0.2-行情扩展草案.md)

| 能力 | Canonical REST | 实现要点 |
| --- | --- | --- |
| 批量净值快照 | `GET /api/products/nav-snapshot` | 替代前端 N+1 调 `.../nav`；读 `core_product_nav` |
| 外部 T+1 同步 | （无对外端点） | `scripts/sync/sync_market_nav.py` UPSERT Core；**禁止**前端/Agent 直连第三方行情 REST |

P0 前端仍用 v0.1：`GET /api/products` + 逐产品 `GET .../nav`（Core 种子静态净值）。

### 5.3 Phase A 清单（与 `core_ro.py` 对齐）

> **路由与命名权威文档：** [接口契约-代销平台API-v0.1.md](../项目框架设计/接口契约-代销平台API-v0.1.md)  
> **拍板（2026-09-08）：** 路由 **A · 按业务域**；与 Agent 重复时 **以本平台 API 为准**；合并期统一命名。

| Repository 方法 | Canonical REST | 主要场景 |
| --- | --- | --- |
| `get_customer_l0` | `GET /api/customers/{customer_id}` | C-01、A-01、仪表盘 |
| `list_customers_by_advisor` | `GET /api/advisors/{advisor_id}/customers` | F-01、代理人仪表盘 |
| `is_advisor_assigned` | 归属中间件 / 内 Service | F-01 |
| `get_product` | `GET /api/products/{product_id}` | C-02、A-02 |
| （待补）`list_products` | `GET /api/products` | 产品货架 |
| `get_latest_nav` | `GET /api/products/{product_id}/nav` | C-05 |
| `list_holdings` | `GET /api/customers/{customer_id}/holdings` | C-01、A-01 |
| `list_trades` | `GET /api/customers/{customer_id}/trades` | C-01、D-01、R-01 |
| `list_products_for_customer` | `GET /api/customers/{customer_id}/products` | C-11 |
| `check_suitability` | `POST /api/compliance/suitability-check` | R-02（**取代** `/api/risk/suitability/check` 为 canonical） |
| `get_staff` | `GET /api/staff/me` | F-01 |

> 正式字段、错误码、归属规则见 **《接口契约-代销平台API-v0.1》**。

---

## 6. 角色分工

| 角色 | 负责 |
| --- | --- |
| **统筹（P1）** | 需求/矩阵维护、Core 存储与灌库、公共 Service/API v0.1、接口契约、Review 禁止直连 Core |
| **Agent 负责人** | 本 Agent 场景 Tool/编排/L1~L3；按契约调 Platform；**缺 Core 能力提 Issue** |
| **前端** | 登录 + chat + 仪表盘；调公共 API，不直连库 |

### 团队硬规则（联调前宣贯）

```text
Agent Tool 只允许调 Platform Service / Platform API。
禁止各 Agent 直连 jinrong_core 写 SQL。
缺 L0 查询能力 → 向统筹提需求 → 补 core_ro + API → 再接入。
```

---

## 7. 与国内代销模块的关系

纵向 **公共业务模块**（账户、产品、交易、清算、报表、系统管理、L0 画像）的 **读路径** 应全部收敛到本流程第 ④⑤ 步；  
Agent 对话能力走第 ⑥ 步，**不重复实现 L0 查数逻辑**。

国内模块映射详见：`C:\Users\Windows\Downloads\国内代销模块与需求映射表.md`（项目外备份；后续可迁入 `docs/项目管理/`）。

---

## 8. 验收对照（统筹自查）

- [ ] P0 场景 ID 与矩阵中 L0 对象一一能映射到 `core_ro` 或已登记「Phase B 待补」
- [ ] `core_ro.py` 每个 public 方法有对应 Service 封装计划
- [ ] Phase A REST 清单有 JWT + 归属规则说明
- [ ] Agent 负责人已收到「禁止直连 Core」与 Issue 提需求流程
- [ ] 接口契约 v0.1 发群后，各 Agent Tool 名称可各异，但底层调同一 Service

---

## 9. 修订记录

| 日期 | 说明 |
| --- | --- |
| 2026-09-08 | 首版：固化「需求→矩阵→存储→Service→API→Agent」主线及分批策略 |
| 2026-09-08 | AL-09 合并完成：`merger` 分支 502 绿；下一步统筹 Phase A Core REST API v0.1 |
| 2026-09-08 | 代销平台 API 拍板：路由 A（业务域）· 重复功能以平台 API 为准 · 《接口契约-代销平台API-v0.1》 |
| 2026-09-09 | 新增 §5.4 C-05 行情 Phase B：链至 v0.2 草案与 C-05 数据源选型对比 |