feat(api): 添加代销平台 API 契约文档及相关更新

- 新增《接口契约-代销平台API-v0.1.md》，定义代销平台 REST API 的路由风格、命名规范及端点清单。 - 更新 AGENTS.md，包含代销平台 API 契约的路径信息。 - 修改 ITERATION.md 和 MEMORY.md，反映代销平台 API 的实施进度及相关文档的状态。 - 更新 TODO.md，明确代销平台 API 的实现优先级。此更新为代销平台 API 的开发提供了清晰的指导，确保各模块间的接口一致性与可维护性。
2026-09-08 20:18:00 +08:00
parent f87e11f104
commit f0bce1270b
7 changed files with 157 additions and 20 deletions
@@ -16,6 +16,7 @@
 ## 原文与深度文档

 - 业务需求：`docs/需求拆解/`
+- **代销平台 API 契约：** `docs/项目框架设计/接口契约-代销平台API-v0.1.md`（canonical 路径 · 命名 · Agent 迁移表）
 - 表结构 SQL：`docs/项目框架设计/表设计/`
 - 技术选型 / JWT：`docs/项目框架设计/技术选型和版本/`
 - Core 模拟底座：`docs/项目框架设计/Core模拟底座/`
@@ -15,4 +15,4 @@
 | 2026-09-07 | **阶段二 C4~C6 完成**（FR-8/9/10）：集中度 `fe4801b` · 时效升级 `90d0660` · 代理人行为链 `66ec7eb` · 挂账 #1~#9 核对无违规 · tag `risk-m4` · 482 pytest 绿 | PRD v1.1 追加需求落地 | MEMORY / TODO / REQUIREMENTS / PRD / 开发计划 |
 | 2026-09-08 | **前端接入方案 B/C**：chat 拉侧三端点 `8328c24` · SSE 流式 `01ec5fc` · 503→502 测试基线 | 前端联调前置 | MEMORY / TODO / chat / session_repository / agent_service |
 | 2026-09-08 | **AL-09 合并接线完成**（`merger` 分支）：JWT 统一 · 模块 chat/agent/memory 恢复 · auth_adapter S2 接缝 · trace 中间件 ApiError re-raise · test_module_boundary 绿 · **502 passed 1 skipped** | 风控模块并入宿主 Wave 0 | MEMORY / TODO / FRAMEWORK / FLOW / REQUIREMENTS / ENVIRONMENT / 合并注意事项 |
-| 2026-09-08 | **《04-从需求到公共API开发方法》首版**：固化需求→矩阵→存储→Service→API→Agent 主线及 Phase A 分批策略 | 统筹 P1 下一步搭公共 REST API | docs/项目管理/04 / README |
+| 2026-09-08 | **代销平台 API 口径拍板**：路由 A（业务域）· 重复功能以平台 API 为准 · 《接口契约-代销平台API-v0.1》 | 统筹 P1 实现前定契约 | 04 / MEMORY / TODO / 接口契约 |
@@ -44,7 +44,8 @@
 | `docs/PRD/PRD-风控监测Agent.md` | **已冻结（v1.1）** | 风控 PRD v1.0 + v1.1 追加 FR-8/9/10（§4A）+ 规则表附录 |
 | `docs/项目框架设计/实现方案-风控追加需求v1.1-C4C6.md` | **已定稿** | C4~C6 编码依据（经独立 AI 评审修订闭环）；分支/进度速览另见项目根 `交接文档.md` |
 | `docs/项目框架设计/合并注意事项-风控模块并入main.md` | **AL-09 已执行（2026-09-08）** | 合并接线完成；接缝见《风控Agent模块边界与合并接缝标注.md》 |
-| `docs/项目管理/04-从需求到公共API开发方法.md` | **已定（2026-09-08）** | 需求→矩阵→存储→Service→API→Agent 主线；Phase A Core API 清单 |
+| `docs/项目管理/04-从需求到公共API开发方法.md` | **已定（2026-09-08）** | 需求→矩阵→存储→Service→API→Agent 主线；Phase A 清单 |
+| `docs/项目框架设计/接口契约-代销平台API-v0.1.md` | **已定（2026-09-08）** | 代销平台 REST canonical 路径、命名规范、Agent 迁移表 |
 | `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + agent 专用 SQL |
 | `docs/项目框架设计/Core模拟底座/` | 已定 | 无真实 Core 时的 L0 方案 |
 | `web/` | **不存在** | 前端 React 待 init |
@@ -65,7 +66,9 @@

 **AL-09 合并后架构（一句话）：** 宿主 `gateway/` + 模块 `deps.py` **双栈并存**；对外登录/token **统一**；chat/risk 均走模块鉴权；接缝 S2 用 `auth_adapter`。

-**下一步（见 TODO）：** Core 公共 API v0.1（`docs/项目管理/04` Phase A）· 前端 `web/` init · 客户/代理人/分析 Agent 业务并行。
+**下一步（见 TODO）：** 代销平台 API v0.1（契约已定：`docs/项目框架设计/接口契约-代销平台API-v0.1.md`）· 前端 `web/` init · Agent 队友并行 Tool/编排（重复能力合并期改调平台 API）。
+
+**平台 API 硬规则（2026-09-08 拍板）：** 路由 **A · 按业务域**（`/api/customers` 等）；与 Agent 功能重复时 **以本平台 API 为准**；命名见契约 §2；合并时统一改 canonical 路径。

 **禁止（改代码前必记）：** Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM。

@@ -85,7 +88,7 @@

 - **名称：** JinRong 金融四 Agent 智能管家
 - **当前阶段：** **AL-09 合并接线完成（2026-09-08，`merger` 分支）**——风控 + Wave 0 宿主共存；502 测试绿；接口实调此前已通过
- **当前优先级：** Core 公共 API v0.1（统筹 P1）/ 前端 `web/` / 客户·代理人·分析 Agent 并行
+- **当前优先级：** 代销平台 API v0.1（统筹 P1）/ 前端 `web/` / Agent 队友并行（合并期改调平台 canonical API）

 ------

@@ -175,6 +178,7 @@ RBAC 联调账号：scripts/dev/rbac-seed-reference.md
 | `docs/需求拆解/` | 业务原文（场景、矩阵、合规） |
 | `docs/项目框架设计/` | 表结构、JWT 手册、Core 模拟、技术版本 |
 | `docs/项目管理/04-从需求到公共API开发方法.md` | 搭公共底座/API 前；新人 onboarding |
+| `docs/项目框架设计/接口契约-代销平台API-v0.1.md` | 写/Review 代销平台 REST；Agent 合并对照 canonical 路径 |

 缺 `docs/memory/*` 文件：按 project-memory-kit 同名补回，**禁止空模板盖进度**。

@@ -9,8 +9,8 @@

 ## 待办（统筹 · P1 推荐顺序）

- [ ] **Core 公共 API v0.1**（见 `docs/项目管理/04` Phase A：customers/products/holdings/trades/suitability-check）
- [ ] **接口契约 v0.1** 发群（login/token/chat + Core 只读 REST）
+- [ ] **代销平台 API v0.1 实现**（契约：`docs/项目框架设计/接口契约-代销平台API-v0.1.md` — customers/products/advisors/compliance/staff + 补 `list_products` RO）
+- [ ] **接口契约发群**（login + 平台读 API + simulate/trade；强调重复功能以平台路径为准）
 - [ ] 前端 React 多 Agent 入口（HashRouter，`web/` init）
 - [ ] 同步 `MEMORY/REQUIREMENTS/FRAMEWORK` 与各 Agent 负责人联调节奏

@@ -0,0 +1,126 @@
+# 接口契约 · 代销平台 API v0.1
+
+> 状态：**已定口径（2026-09-08）** · 实现进行中  
+> 范围：**未接 Agent 前的 Core 代销平台 REST**（客户 App / 理财师工作台 / 内勤只读）  
+> 关联：[04-从需求到公共API开发方法.md](../项目管理/04-从需求到公共API开发方法.md) · [02-JWT-RBAC鉴权手册.md](./技术选型和版本/02-JWT-RBAC鉴权手册.md)
+
+---
+
+## 0. 拍板决策（合并 Agent 时遵守）
+
+| 决策 | 内容 |
+| --- | --- |
+| **路由风格** | **A · 按业务域**：`/api/customers`、`/api/products`、`/api/advisors` …（不用 `/api/platform/*` 前缀） |
+| **重复功能以谁为准** | **以本平台 API 为准**。Agent 侧已有同能力 HTTP 或 Tool 时，合并期 **改调本平台路径/同一 Service**，不保留第二套对外契约 |
+| **命名统一** | 全项目 REST 路径、合并后的 Agent 适配层，**一律按本文 §2 命名**；旧路径仅过渡，最终废弃 |
+
+---
+
+## 1. 路由分区
+
+```text
+/api/auth/*           系统·登录（已有）
+/api/customers/*      账户·客户 L0 + 资产读
+/api/advisors/*       理财师·归属
+/api/products/*       产品·净值
+/api/compliance/*     适当性等合规读/判定（平台 canonical）
+/api/simulate/*       模拟交易写（已有）
+/api/risk/*           风控后台（预警/AML 等；与 §3 重叠项见迁移表）
+/api/chat/*           Agent 对话（队友维护；L0 查数不得长期直连 Core）
+```
+
+**平台 API 鉴权：** `Authorization: Bearer` + JWT 角色 + **数据归属**（`assert_customer_access` 口径）。**不要求** `X-Agent-Type`（Agent 专用头）。
+
+**审计：** 平台路由写审计时 `agent_type=platform`（与 `simulate` 一致）。
+
+---
+
+## 2. 命名规范（全项目统一）
+
+### 2.1 路径
+
+| 规则 | 示例 | 反例 |
+| --- | --- | --- |
+| 资源集合用 **复数名词** | `/api/customers` | `/api/customer` |
+| 多词用语义段 **kebab-case** | `/api/compliance/suitability-check` | `/api/compliance/suitability_check` |
+| 子资源嵌套在父资源下 | `/api/customers/{customer_id}/holdings` | `/api/holdings?customer_id=` |
+| 路径参数名与域 ID 一致 | `{customer_id}` `{product_id}` `{advisor_id}` | `{id}` |
+| 动作型接口用 **POST + 动词名或 check** | `POST .../suitability-check` | `GET .../doCheck` |
+| 分页 query | `limit` + `offset` 或 `page` + `page_size` | 混用两套时文档写死 |
+
+### 2.2 HTTP 与方法
+
+| 操作 | 方法 | 说明 |
+| --- | --- | --- |
+| 单条/列表只读 | GET | Core L0 只读，不写库 |
+| 判定/提交（适当性、交易） | POST |  body JSON |
+| 更新/删除 Core 正式账 | **禁止** | 除 `simulate/trade` 模拟网关 |
+
+### 2.3 响应体
+
+- 成功：沿用 `utils/response.ok` 统一外壳（`code` / `message` / `data` / `trace_id`）。
+- 失败：手册 §10 结构（`ApiError`）；403 归属/角色、404 资源不存在。
+- 列表：`{ "items": [...], "total": n, "limit": ..., "offset": ... }`（与 chat sessions 对齐）。
+
+### 2.4 Service / 代码包（实现侧）
+
+| 层 | 约定 |
+| --- | --- |
+| 路由 | `app/api/customers.py` `products.py` `advisors.py` `compliance.py` |
+| 平台 Service | `app/service/platform/` 封装 `core_ro`，REST 与日后 Agent 适配 **共用一个 Service** |
+| Repository | 仍只 `core_ro.py` SELECT；缺方法先补 RO 再暴露 API |
+
+---
+
+## 3. v0.1 端点清单（canonical）
+
+| 方法 | 路径 | core_ro / 说明 | 归属 |
+| --- | --- | --- | --- |
+| POST | `/api/auth/login` | 已有 | 公开 |
+| GET | `/api/customers/{customer_id}` | `get_customer_l0` | customer 本人 / advisor 名下 / risk_officer 全量 |
+| GET | `/api/customers/{customer_id}/holdings` | `list_holdings` | 同上 |
+| GET | `/api/customers/{customer_id}/trades` | `list_trades` | 同上；query: `limit` `offset` 或日期范围（后续） |
+| GET | `/api/customers/{customer_id}/products` | `list_products_for_customer` | 同上；可购产品货架（C×R） |
+| GET | `/api/advisors/{advisor_id}/customers` | `list_customers_by_advisor` | advisor 本人或 supervisor；返回 customer_id 列表或摘要 |
+| GET | `/api/products` | **`list_products`（待补 RO）** |  authenticated；产品货架 |
+| GET | `/api/products/{product_id}` | `get_product` | authenticated |
+| GET | `/api/products/{product_id}/nav` | `get_latest_nav` | authenticated |
+| GET | `/api/staff/me` | `get_staff(auth.actor_id)` | staff token |
+| POST | `/api/compliance/suitability-check` | `check_suitability` | G-01 归属；**canonical 适当性** |
+| POST | `/api/simulate/trade` | 已有 trade_gateway | risk_demo 或 customer 本人 |
+
+**v0.2 候选（非 v0.1 阻塞）：** `GET /api/customers/{customer_id}/cash-flows`（需补 RO）。
+
+---
+
+## 4. 与 Agent / 旧路径的迁移表（合并时改）
+
+> **原则：** 功能重复 → **调用 §3 canonical 路径或同一 Platform Service**；旧路径标记 deprecated 后删除。
+
+| 现有（Agent / 风控 / Tool） | Canonical（本平台） | 合并动作 |
+| --- | --- | --- |
+| `POST /api/risk/suitability/check` | `POST /api/compliance/suitability-check` | 风控路由转发或删；Agent Tool 改调 platform |
+| Tool `query_customer_profile` | `GET /api/customers/{id}` | chat Tool 改 HTTP 或 `platform_service.get_customer` |
+| Tool `query_holdings` | `GET /api/customers/{id}/holdings` | 同上 |
+| Tool `query_recent_trades` | `GET /api/customers/{id}/trades` | 同上 |
+| Tool `suitability_check`（risk chat_tools） | `POST /api/compliance/suitability-check` | 同上 |
+| `GET /api/risk/alerts` | **暂保留** `/api/risk/alerts` | 后台域，非 L0 重复；不与 §3 冲突 |
+
+---
+
+## 5. 归属规则摘要（G-01）
+
+| 角色 | 读 customer 维度数据 |
+| --- | --- |
+| `customer` | 仅 `auth.customer_id == customer_id` |
+| `advisor` | `customer_advisor_rel`  active 归属 |
+| `risk_officer` / 演示 | 全量（只读） |
+| 其他 staff | 403 + audit |
+
+---
+
+## 6. 修订记录
+
+| 日期 | 说明 |
+| --- | --- |
+| 2026-09-08 | v0.1 口径：路由 A · 平台 API 优先 · 命名规范 · 端点清单 · 迁移表 |
@@ -40,7 +40,7 @@
 | ② 数据交互矩阵 | `docs/需求拆解/数据交互矩阵.md` |
 | ③ 存储层 | `jinrong_core` / `jinrong_agent` · `docs/项目框架设计/表设计/` · Core 模拟底座 |
 | ④ 公共函数 | `app/repository/core_ro.py` · `app/model/suitability.py` · `scripts/sync/` |
-| ⑤ 公共 API | `app/api/auth.py` · `app/api/chat.py` · 规划中的 `app/api/platform/` |
+| ⑤ 公共 API | `app/api/auth.py` · **代销平台** `customers/products/advisors/compliance`（契约见《接口契约-代销平台API-v0.1》）· `simulate` · Agent 对话 `chat`（队友） |
 | ⑥ Agent | 各负责人 `app/service/agent_service.py` 及 Tool |

 ---
@@ -118,20 +118,24 @@ P1/P2        → 联调提需求 → 补 Repository → 升 API v0.2+

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

-| Repository 方法 | 建议 REST（草案） | 主要场景 |
-| --- | --- | --- |
-| `get_customer_l0` | `GET /api/customers/{id}` | C-01、A-01、仪表盘 |
-| `list_customers_by_advisor` | `GET /api/advisors/{id}/customers` | F-01、代理人仪表盘 |
-| `is_advisor_assigned` | 归属中间件 / 内 Service | F-01 |
-| `get_product` | `GET /api/products/{id}` | C-02、A-02 |
-| `get_latest_nav` | `GET /api/products/{id}/nav` | C-05 |
-| `list_holdings` | `GET /api/customers/{id}/holdings` | C-01、A-01 |
-| `list_trades` | `GET /api/customers/{id}/trades` | C-01、D-01、R-01 |
-| `list_products_for_customer` | `GET /api/customers/{id}/products` | C-11 |
-| `check_suitability` | `POST /api/compliance/suitability-check` | R-02 |
-| `get_staff` | `GET /api/staff/{id}` 或鉴权上下文 | F-01 |
+> **路由与命名权威文档：** [接口契约-代销平台API-v0.1.md](../项目框架设计/接口契约-代销平台API-v0.1.md)  
+> **拍板（2026-09-08）：** 路由 **A · 按业务域**；与 Agent 重复时 **以本平台 API 为准**；合并期统一命名。

-> 正式字段、错误码、归属规则见后续 **《接口契约 v0.1》**（待 P1 单独出稿）。
+| 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》**。

 ---

@@ -178,3 +182,4 @@ Agent 对话能力走第 ⑥ 步，**不重复实现 L0 查数逻辑**。
 | --- | --- |
 | 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》 |
@@ -14,6 +14,7 @@
 | 2 | [02-项目开发计划.md](./02-项目开发计划.md) | 项目级 5 周计划：Wave×Phase 双视角、依赖链、周验收门、第1周天级、风险、答辩准备 | 每周初、里程碑评审 |
 | 3 | [03-表设计文档.md](./03-表设计文档.md) | 给人看的表设计字典：MySQL双库/Redis/Neo4j/Milvus 分层、谁写谁读、关键字段中文释义、建表顺序 | 写代码查表、联调对字段 |
 | 4 | [04-从需求到公共API开发方法.md](./04-从需求到公共API开发方法.md) | **方法论文档**：需求→矩阵→存储→Service→API→Agent 主线、分批策略、统筹分工、Phase A 接口清单 | 搭公共底座/API 前；新人 onboarding |
+| 5 | [../项目框架设计/接口契约-代销平台API-v0.1.md](../项目框架设计/接口契约-代销平台API-v0.1.md) | **代销平台 REST 契约**：业务域路由、命名规范、v0.1 端点、Agent 合并迁移表 | 写平台 API / Review Agent 重复接口 |

 ---