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

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

状态：v0.1 已实现（2026-09-08） · 519 pytest 绿
范围：未接 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 对齐）。

脱敏（2026-09-08 拍板）：

项	v0.1	真库阶段
开关	settings.platform_response_desensitize（env：PLATFORM_RESPONSE_DESENSITIZE，默认 false）	生产/真 Core 切 true
行为	关闭：L0 字段原样返回（模拟库联调）	开启：出参经 app/utils/desensitize.py（姓名/手机/证件/银行卡；customer_id 不脱敏）
实现位置	Platform Service 层统一处理（REST 与日后 Agent 适配共用同一出口）	同上

2.4 Service / 代码包（实现侧 · 分层说明）

代销平台采用 三层，避免「REST 里写 SQL」或「Agent 合并时再抄一遍查数逻辑」：

  HTTP 请求
      ↓
  app/api/customers.py 等     ← 薄路由：鉴权、参数校验、ok() 包装、HTTP 状态码
      ↓
  app/service/platform/*.py   ← Platform Service：归属无关的业务组装、脱敏开关、分页口径
      ↓
  app/repository/core_ro.py   ← 只读 SQL，不感知 HTTP/Agent

层	职责	谁调用
api/	FastAPI 路由；Depends(get_platform_auth_context)；调 Service	前端、Postman
service/platform/	封装 core_ro；统一脱敏、列表分页、字段映射	REST 只调这一层；合并 Agent 时也调这一层（或同进程 import）
repository/core_ro	SELECT Core 模拟库	仅 Service / 风控等特殊路径

「REST 只调 Service」 = customers.py 里不出现 CoreReadOnlyRepository() 直调，而是 platform_service.get_customer_l0(...)。这样 Agent Tool 日后改调 Service 时，与 App 仪表盘 同一套逻辑，不会两套口径。

路由文件：app/api/customers.py products.py advisors.py compliance.py staff.py
Service 文件：app/service/platform/customer_service.py product_service.py …（按域拆分，可合并为一个 platform_service.py 若保持简单）

---

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 行情扩展（草案 · 未实现）： 见 接口契约-代销平台API-v0.2-行情扩展草案.md（GET /api/products/nav-snapshot、sync_market_nav）。

其他 v0.2 候选： GET /api/customers/{customer_id}/cash-flows（需补 RO）。

C-05 数据源选型： C-05-行情数据源选型对比.md

---

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 · 平台 API）

2026-09-08 统筹拍板： 各角色权限不同；平台读接口 不要求 X-Agent-Type（实现侧用 get_platform_auth_context）。

角色	读 customers/{id} 及子资源
customer	仅 auth.customer_id == customer_id
advisor	仅 core_customer_advisor active 归属名下客户
analyst	全量只读（支撑 D-01 内勤查数）
risk_officer	全量只读（与现有 G-01 一致）
risk_manager	v0.1 全量只读（与台账只读定位一致；无写接口）
risk_demo	全量只读（与 risk_officer 一致，支撑 simulate/演示联调）
compliance / 其他 staff	403（客户 L0 不在其业务范围）

产品/净值（/api/products*）：任意已登录 staff 或 customer 可读（公开产品事实，无客户归属语义）。

理财师客户列表（/api/advisors/{advisor_id}/customers）：advisor 仅 advisor_id == auth.actor_id；analyst / risk_officer / risk_manager 可查任意 advisor。

/api/staff/me： 仅 token_type=staff；customer token → 403。

---

6. 修订记录

日期	说明
2026-09-08	check_source ENUM 增 platform（DDL + scripts/agent/migrate-check-source-platform.sql）
2026-09-08	实现前拍板：整包交付 · 适当性新旧并存 · analyst 全量只读 · 平台 JWT 免 X-Agent-Type
2026-09-08	脱敏：PLATFORM_RESPONSE_DESENSITIZE 默认 false；真库再开 · risk_demo 全量只读
2026-09-09	指向 v0.2 行情草案与 C-05 数据源选型对比