feat: chat integration, tenant admin spec, backend chat service, miniprogram updates, DEMO moved to tmp, XCX-TEST removed, migrations & docs
This commit is contained in:
@@ -465,6 +465,150 @@ MVP 全链路验证端点，从 `test."xcx-test"` 表读取数据。
|
||||
|
||||
---
|
||||
|
||||
## 16. 小程序配置 `/api/xcx/config`
|
||||
|
||||
所有端点需 JWT（approved 状态）。
|
||||
|
||||
### GET `/api/xcx/config/skill-types`
|
||||
项目类型筛选器配置（CONFIG-1）。返回前端筛选器选项列表。
|
||||
|
||||
数据源：`app.v_cfg_area_category`（基于 `dws.cfg_area_category` 去重到 category 级别，排除 SPECIAL/OTHER，按 sort_order 排序）。
|
||||
|
||||
响应头部自动插入"不限"选项（key=ALL），不存储在数据库中。
|
||||
|
||||
响应：`SkillTypeItem[]`
|
||||
```json
|
||||
[
|
||||
{ "key": "ALL", "label": "不限", "emoji": "🔍", "cls": "" },
|
||||
{ "key": "BILLIARD", "label": "🎱 中式/追分", "emoji": "🎱", "cls": "" },
|
||||
{ "key": "SNOOKER", "label": "斯诺克", "emoji": "斯", "cls": "" },
|
||||
{ "key": "MAHJONG", "label": "🀄 麻将/棋牌", "emoji": "🀄", "cls": "" },
|
||||
{ "key": "KTV", "label": "🎤 团建/K歌", "emoji": "🎤", "cls": "" }
|
||||
]
|
||||
```
|
||||
|
||||
降级行为：查询失败时返回空数组 `[]`。
|
||||
|
||||
---
|
||||
|
||||
## 17. 小程序三看板 `/api/xcx/board`
|
||||
|
||||
所有端点需 JWT + 对应权限。
|
||||
|
||||
### GET `/api/xcx/board/coaches`
|
||||
助教看板（BOARD-1）。返回助教列表，支持排序×技能×时间三重筛选。
|
||||
|
||||
查询参数：
|
||||
- `sort`：排序维度（`perf_desc`/`perf_asc`/`salary_desc`/`salary_asc`/`sv_desc`/`task_desc`，默认 `perf_desc`）
|
||||
- `skill`：技能筛选（`ALL`/`BILLIARD`/`SNOOKER`/`MAHJONG`/`KTV`，默认 `ALL`）
|
||||
- `time`：时间范围（`month`/`quarter`/`last_month`/`last_3m`/`last_quarter`/`last_6m`，默认 `month`）
|
||||
|
||||
约束：`time=last_6m` + `sort=sv_desc` 互斥，返回 400。
|
||||
|
||||
权限：`view_board_coach`
|
||||
|
||||
响应：`CoachBoardResponse`（含 `items` + `dimType`）
|
||||
|
||||
### GET `/api/xcx/board/customers`
|
||||
客户看板（BOARD-2）。返回客户列表，支持维度×项目筛选 + 分页。
|
||||
|
||||
查询参数：
|
||||
- `dimension`：客户维度（`recall`/`potential`/`balance`/`recharge`/`recent`/`spend60`/`freq60`/`loyal`，默认 `recall`）
|
||||
- `project`：项目筛选（`ALL`/`BILLIARD`/`SNOOKER`/`MAHJONG`/`KTV`，默认 `ALL`）
|
||||
- `page`：页码（默认 1）
|
||||
- `page_size`：每页条数（默认 20，最大 100）
|
||||
|
||||
权限：`view_board_customer`
|
||||
|
||||
响应：`CustomerBoardResponse`（含 `items`/`total`/`page`/`pageSize`）
|
||||
|
||||
### GET `/api/xcx/board/finance`
|
||||
财务看板（BOARD-3）。返回 6 大板块（经营一览/预收资产/营收结构/现金流/支出/助教分析）。
|
||||
|
||||
查询参数：
|
||||
- `time`：时间范围（`month`/`lastMonth`/`week`/`lastWeek`/`quarter3`/`quarter`/`lastQuarter`/`half6`，默认 `month`）
|
||||
- `area`：区域筛选（`all`/`hall`/`hallA`/`hallB`/`hallC`/`mahjong`/`teamBuilding`，默认 `all`）
|
||||
- `compare`：环比开关（0=关闭/1=开启，默认 0）
|
||||
|
||||
约束：`area≠all` 时 `recharge` 板块为 null；`compare=0` 时响应不含环比字段。
|
||||
|
||||
权限：`view_board_finance`
|
||||
|
||||
响应：`FinanceBoardResponse`（含 `overview`/`recharge`/`revenue`/`cashflow`/`expense`/`coachAnalysis`）
|
||||
|
||||
---
|
||||
|
||||
## 18. 小程序 CHAT `/api/xcx/chat`
|
||||
|
||||
所有端点需 JWT（approved 状态）。替代原 `xcx_ai_chat`（`/api/ai/*`），统一迁移到 `/api/xcx/chat/*` 路径。
|
||||
|
||||
### GET `/api/xcx/chat/history`
|
||||
对话历史列表（CHAT-1）。返回当前用户的对话列表，按最后消息时间倒序。
|
||||
|
||||
查询参数：
|
||||
- `page`：页码（默认 1）
|
||||
- `page_size`：每页条数（默认 20，最大 100）
|
||||
|
||||
响应：`ChatHistoryResponse`（含 `items`/`total`/`page`/`pageSize`）
|
||||
|
||||
每条对话包含：`id`（对话 ID）、`title`（对话标题）、`customerName`（关联客户姓名，可选）、`lastMessage`（最后消息摘要）、`timestamp`（最后消息时间）、`unreadCount`（未读数）。
|
||||
|
||||
### GET `/api/xcx/chat/messages`
|
||||
通过上下文查询消息（CHAT-2b）。根据 `contextType` + `contextId` 自动查找或创建对话。
|
||||
|
||||
查询参数：
|
||||
- `contextType`：上下文类型（`task`/`customer`/`coach`/`general`，必填）
|
||||
- `contextId`：上下文 ID（必填）
|
||||
- `page`：页码（默认 1）
|
||||
- `page_size`：每页条数（默认 50，最大 100）
|
||||
|
||||
对话复用规则：`task` 始终复用（无时限）；`customer`/`coach` ≤ 3 天复用、> 3 天新建；`general` 始终新建。
|
||||
|
||||
响应：`ChatMessagesResponse`（含 `chatId`/`items`/`total`/`page`/`pageSize`）
|
||||
|
||||
### GET `/api/xcx/chat/{chat_id}/messages`
|
||||
通过 chatId 查询消息（CHAT-2a）。消息按 `created_at` 正序。
|
||||
|
||||
路径参数：
|
||||
- `chat_id`：对话 ID
|
||||
|
||||
查询参数：
|
||||
- `page`：页码（默认 1）
|
||||
- `page_size`：每页条数（默认 50，最大 100）
|
||||
|
||||
响应：`ChatMessagesResponse`
|
||||
|
||||
每条消息包含：`id`、`role`（`user`/`assistant`）、`content`、`createdAt`、`referenceCard`（可选，含 `type`/`title`/`summary`/`data` 键值对）。
|
||||
|
||||
### POST `/api/xcx/chat/{chat_id}/messages`
|
||||
发送消息并获取同步 AI 回复（CHAT-3）。chatId 归属验证：不属于当前用户返回 403。
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{ "content": "消息内容" }
|
||||
```
|
||||
|
||||
响应：`SendMessageResponse`（含 `userMessage` 和 `aiReply`，各含 `id`/`content`/`createdAt`）
|
||||
|
||||
AI 失败降级：用户消息仍保存，`aiReply.content` 返回错误提示，HTTP 200。
|
||||
|
||||
### POST `/api/xcx/chat/stream`
|
||||
SSE 流式对话端点（CHAT-4）。chatId 归属验证在流开始前完成。
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{ "chatId": 1, "content": "消息内容" }
|
||||
```
|
||||
|
||||
响应：`text/event-stream`（不经过 ResponseWrapper 包装）
|
||||
|
||||
SSE 事件类型：
|
||||
- `event: message` — `data: {"token": "文本片段"}`
|
||||
- `event: done` — `data: {"messageId": 123, "createdAt": "ISO8601"}`
|
||||
- `event: error` — `data: {"message": "错误描述"}`
|
||||
|
||||
---
|
||||
|
||||
## 15. 维客线索 `/api/member-retention-clue`
|
||||
|
||||
替代原 `member-birthday` 端点，提供维客线索管理能力。
|
||||
|
||||
Reference in New Issue
Block a user