From f0bce1270b7a99886a5faa4ce0b9302c1abc7915 Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 8 Sep 2026 20:18:00 +0800 Subject: [PATCH] =?UTF-8?q?feat(api):=20=E6=B7=BB=E5=8A=A0=E4=BB=A3?= =?UTF-8?q?=E9=94=80=E5=B9=B3=E5=8F=B0=20API=20=E5=A5=91=E7=BA=A6=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=8F=8A=E7=9B=B8=E5=85=B3=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增《接口契约-代销平台API-v0.1.md》，定义代销平台 REST API 的路由风格、命名规范及端点清单。 - 更新 AGENTS.md，包含代销平台 API 契约的路径信息。 - 修改 ITERATION.md 和 MEMORY.md，反映代销平台 API 的实施进度及相关文档的状态。 - 更新 TODO.md，明确代销平台 API 的实现优先级。 此更新为代销平台 API 的开发提供了清晰的指导，确保各模块间的接口一致性与可维护性。 --- AGENTS.md | 1 + docs/memory/ITERATION.md | 2 +- docs/memory/MEMORY.md | 10 +- docs/memory/TODO.md | 4 +- .../项目框架设计/接口契约-代销平台API-v0.1.md | 126 ++++++++++++++++++ docs/项目管理/04-从需求到公共API开发方法.md | 33 +++-- docs/项目管理/README.md | 1 + 7 files changed, 157 insertions(+), 20 deletions(-) create mode 100644 docs/项目框架设计/接口契约-代销平台API-v0.1.md diff --git a/AGENTS.md b/AGENTS.md index 685c976..a297fcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,7 @@ ## 原文与深度文档 - 业务需求：`docs/需求拆解/` +- **代销平台 API 契约：** `docs/项目框架设计/接口契约-代销平台API-v0.1.md`（canonical 路径 · 命名 · Agent 迁移表） - 表结构 SQL：`docs/项目框架设计/表设计/` - 技术选型 / JWT：`docs/项目框架设计/技术选型和版本/` - Core 模拟底座：`docs/项目框架设计/Core模拟底座/` diff --git a/docs/memory/ITERATION.md b/docs/memory/ITERATION.md index ae9075e..b6b78db 100644 --- a/docs/memory/ITERATION.md +++ b/docs/memory/ITERATION.md @@ -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 / 接口契约 | diff --git a/docs/memory/MEMORY.md b/docs/memory/MEMORY.md index 232b7c1..1edc77f 100644 --- a/docs/memory/MEMORY.md +++ b/docs/memory/MEMORY.md @@ -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 同名补回，**禁止空模板盖进度**。 diff --git a/docs/memory/TODO.md b/docs/memory/TODO.md index 1cc0172..d9b8a95 100644 --- a/docs/memory/TODO.md +++ b/docs/memory/TODO.md @@ -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 负责人联调节奏 diff --git a/docs/项目框架设计/接口契约-代销平台API-v0.1.md b/docs/项目框架设计/接口契约-代销平台API-v0.1.md new file mode 100644 index 0000000..c439f6c --- /dev/null +++ b/docs/项目框架设计/接口契约-代销平台API-v0.1.md @@ -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 优先 · 命名规范 · 端点清单 · 迁移表 | diff --git a/docs/项目管理/04-从需求到公共API开发方法.md b/docs/项目管理/04-从需求到公共API开发方法.md index 2818562..0a65d6f 100644 --- a/docs/项目管理/04-从需求到公共API开发方法.md +++ b/docs/项目管理/04-从需求到公共API开发方法.md @@ -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》 | diff --git a/docs/项目管理/README.md b/docs/项目管理/README.md index 2ae46fb..bc16c2a 100644 --- a/docs/项目管理/README.md +++ b/docs/项目管理/README.md @@ -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 重复接口 | ---