group_xinghuo_jinrong/docs/项目框架设计/接口契约-代销平台API-v0.1.md

接口契约 · 代销平台 API v0.1

状态：已定口径（2026-09-08） · 实现进行中
范围：未接 Agent 前的 Core 代销平台 REST（客户 App / 理财师工作台 / 内勤只读）
关联：04-从需求到公共API开发方法.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. 路由分区

/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 优先 · 命名规范 · 端点清单 · 迁移表