88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
|
# 接口契约发群稿（2026-09-09 · merger 分支）
|
|||
|
|
|
|||
|
|
> 可直接复制到协作群；canonical 文档：`docs/项目框架设计/接口契约-代销平台API-v0.1.md` · 问数接缝：`docs/项目框架设计/数据分析Agent-合并说明.md`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 登录与鉴权
|
|||
|
|
|
|||
|
|
| 项 | 约定 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 登录 | `POST /api/auth/login` → JWT（issuer/audience 与模块 API 统一） |
|
|||
|
|
| 平台只读 API | `Authorization: Bearer` **即可**，**不要** `X-Agent-Type` |
|
|||
|
|
| 四 Agent 对话 | `POST /api/chat` / `POST /api/chat/stream` **必须**带 `X-Agent-Type: customer \| advisor \| risk \| analyst` |
|
|||
|
|
| 问数（数据分析） | `POST /api/analyst/chat` 等 **不要** `X-Agent-Type`（平台鉴权 `get_platform_auth_context`） |
|
|||
|
|
| 风控 REST | `GET/POST /api/risk/*` **必须** `X-Agent-Type: risk`（前端 `web/src/api/risk.ts` 已补） |
|
|||
|
|
| 模拟交易 | `POST /api/simulate/trade` 需 `X-Agent-Type`（customer 本人或 risk 线）；业务角色须 **risk_demo** 或 **客户本人** |
|
|||
|
|
|
|||
|
|
Demo 账号（前端登录页）：CUST-9527 · STAFF-10086 · STAFF-20001 · STAFF-30001
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 平台读 API（v0.1 · 重复能力以此为准）
|
|||
|
|
|
|||
|
|
| 域 | 路径前缀 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 客户 | `/api/customers` | 档案 / 持仓 / 流水 |
|
|||
|
|
| 产品 | `/api/products` | 列表 + `/{id}/nav` 净值 |
|
|||
|
|
| 顾问 | `/api/advisors` | 名下客户 roster |
|
|||
|
|
| 员工 | `/api/staff` | 内部员工只读 |
|
|||
|
|
| 合规 | `/api/compliance/suitability-check` | **canonical 适当性**（过渡：`/api/risk/suitability/check` 仍可用） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 数据分析问数四件套
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| POST | `/api/analyst/chat` | NL→SQL→表格+解读；customer 仅 self 域；尾部「AI 分析有风险」 |
|
|||
|
|
| GET | `/api/analyst/dashboard` | 角色域 metrics 卡片 |
|
|||
|
|
| POST | `/api/analyst/assets` | 口径/few-shot 资产沉淀（P2 UI 待做） |
|
|||
|
|
| GET | `/api/analyst/ops/metrics` | 运维指标 |
|
|||
|
|
|
|||
|
|
前端：`/#/app/analytics/query`（四角色权限内问数）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 风控与模拟
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| GET | `/api/risk/alerts` | 台账筛选/分页 |
|
|||
|
|
| POST | `/api/risk/alerts/{id}/handle` | 人工处置 |
|
|||
|
|
| POST | `/api/simulate/trade` | 模拟交易 → 规则引擎出预警（演示须 risk_demo 或客户本人） |
|
|||
|
|
|
|||
|
|
前端：`/#/app/risk/alerts` · `/#/app/risk/simulate`（演示页 + 角色说明）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 对话与会话
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| POST | `/api/chat/visitor` | 游客试聊（无 JWT） |
|
|||
|
|
| GET | `/api/chat/sessions` | 会话列表 |
|
|||
|
|
| GET | `/api/chat/sessions/{id}/messages` | 历史消息 |
|
|||
|
|
| POST | `/api/chat/sessions/{id}/close` | 关闭会话 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 本地验收
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python -m pytest # 773 passed
|
|||
|
|
python scripts/dev/smoke_analyst.py
|
|||
|
|
cd web && npm run build && npm run test
|
|||
|
|
uvicorn app.main:app --reload # :8000；改代码后须重启
|
|||
|
|
cd web && npm run dev # :5173 代理 8000
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Redis：`scripts/dev/start-redis.ps1` → **6380**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 拍板记录（2026-09-09）
|
|||
|
|
|
|||
|
|
- **STAFF-30001/30002 已追加 `risk_demo`** → 前端模拟交易页可造预警
|
|||
|
|
- **customer Chat 已接 SSE** → stream 走 `customer_service.prepare_customer_stream`（非 agent_service）
|