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

从需求到公共 API 开发方法

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

---

0. 一句话

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

---

1. 主流程（标准顺序）

① 定需求（场景 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 已有能力，其余联调驱动补充：

矩阵（全量） → 筛 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
API 草案： 接口契约-代销平台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
拍板（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，不直连库

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

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 数据源选型对比