docs: add comprehensive admin-web auth, flow diagram and message testing design
This commit is contained in:
@@ -0,0 +1,199 @@
|
||||
# sino-mci 管理后台补全设计：登录/租户、页面完善、入站流程图、消息测试模块
|
||||
|
||||
## 背景与当前缺口
|
||||
|
||||
当前 `admin-web` 管理后台存在以下核心缺口，导致无法真正面向不同企业使用：
|
||||
|
||||
1. **无登录/鉴权**：前端写死 fallback 租户 `default`，后端 `login` 接口只返回用户信息、不返回 token，没有会话管理。
|
||||
2. **页面都是空壳**：Dashboard 统计写死为 0；渠道主体、渠道账号、会话/群聊、联系人页面只创建不查询；会话缺少账号绑定 UI；发送记录需要手动拼 JSON。
|
||||
3. **入站流程没有流程图**：`入站流程` 页面只有表单和表格，没有可视化节点编排，也看不到消息实际走过的路径。
|
||||
4. **没有独立的消息测试模块**：测试发送藏在发送记录页，缺少对多种目标类型、渠道、入站消息的一站式测试能力。
|
||||
|
||||
## 目标
|
||||
|
||||
补齐以上四个缺口，使管理后台达到可交付状态：
|
||||
|
||||
- 不同企业（租户）可以独立登录、独立管理自己的渠道资源和数据。
|
||||
- 各管理页面具备完整的创建 + 列表展示能力。
|
||||
- 入站流程可拖拽编排，并能追踪单条消息的处理路径。
|
||||
- 提供统一的消息测试模块，支持出站测试发送和入站消息模拟。
|
||||
|
||||
## 设计
|
||||
|
||||
### 一、登录与多企业管理
|
||||
|
||||
#### 1.1 后端鉴权
|
||||
|
||||
采用 **JWT + 轻量 Interceptor** 方案，不引入 Spring Security 完整链路。
|
||||
|
||||
**新增依赖**：`io.jsonwebtoken:jjwt`（Java 21 用 0.12.x 版本）。
|
||||
|
||||
**Token 设计**：
|
||||
- 签发：登录成功后生成 JWT，payload 包含 `tenantCode`、`userId`、`username`、`roleCodes`。
|
||||
- 有效期：24 小时。
|
||||
- 传输：前端放在 `Authorization: Bearer <token>` 请求头。
|
||||
|
||||
**新增组件**：
|
||||
- `JwtTokenProvider`：生成/解析/校验 token。
|
||||
- `AuthContext`：ThreadLocal 保存当前登录用户的 `tenantCode`、`userId`、`roleCodes`。
|
||||
- `AuthInterceptor`：拦截 `/api/v1/**`（除了 `/api/v1/account/login` 和 `/api/v1/account/tenant` 创建租户），校验 token 并填充 `AuthContext`。
|
||||
- `TenantArgumentResolver`：将 Controller 中的 `X-Tenant-Code` 改为从 `AuthContext` 读取（兼容旧接口可先保留 header，新鉴权下不再依赖 header）。
|
||||
|
||||
**改造 Controller**：
|
||||
- 保持现有 `/api/v1/account/login` 路径，返回结构改为 `{token, userInfo}`。
|
||||
- 新增 `/api/v1/account/me` 获取当前登录用户信息。
|
||||
- 新增 `/api/v1/account/user/list` 查询当前租户用户列表。
|
||||
- 新增 `/api/v1/account/tenant/list` 查询租户列表（平台管理员可用）。
|
||||
|
||||
**角色权限（首期简化）**：
|
||||
- `platform_admin`：可创建租户、查看所有租户。
|
||||
- `tenant_admin`：可管理本租户用户、渠道资源、发送记录。
|
||||
- `operator` / `viewer`：先保留角色表数据，权限校验二期细化。
|
||||
|
||||
#### 1.2 前端登录与路由守卫
|
||||
|
||||
**新增页面**：
|
||||
- `Login.vue`：租户编码 + 用户名 + 密码登录。
|
||||
|
||||
**路由改造**：
|
||||
- 默认路由 `/login`。
|
||||
- 已登录跳 `/dashboard`。
|
||||
- `router.beforeEach` 检查 `localStorage` 中 `mci-token`，无 token 或 token 失效则跳转登录。
|
||||
|
||||
**API 客户端改造**：
|
||||
- `client.ts` 从 `localStorage` 读取 `mci-token` 并写入 `Authorization: Bearer <token>`。
|
||||
- `X-Tenant-Code` 仍然可写，但优先以 token 中的 tenantCode 为准（后端以 token 为准）。
|
||||
|
||||
**新增管理页面**：
|
||||
- `TenantManagement.vue`：平台管理员创建/查看租户。
|
||||
- `UserManagement.vue`：租户管理员创建/查看本租户用户。
|
||||
|
||||
#### 1.3 登录与租户初始化流程
|
||||
|
||||
首次部署时：
|
||||
1. 通过 `/api/v1/account/tenant` 创建平台租户（如 `platform`）。
|
||||
2. 通过 `/api/v1/account/user` 创建平台管理员用户。
|
||||
3. 后续各业务系统申请租户后，平台管理员为其创建租户和用户。
|
||||
4. 业务系统管理员登录后管理自己的渠道资源。
|
||||
|
||||
### 二、管理后台页面完善
|
||||
|
||||
#### 2.1 后端新增列表/统计接口
|
||||
|
||||
| 接口 | 方法 | 说明 |
|
||||
|---|---|---|
|
||||
| `/api/v1/channel-subject/list` | GET | 当前租户渠道主体列表 |
|
||||
| `/api/v1/channel-account/list` | GET | 当前租户渠道账号列表 |
|
||||
| `/api/v1/conversation/list` | GET | 当前租户会话列表 |
|
||||
| `/api/v1/person/list` | GET | 当前租户联系人列表 |
|
||||
| `/api/v1/send/list` | GET | 当前租户发送任务/日志列表（最近 50 条） |
|
||||
| `/api/v1/dashboard/stats` | GET | 主体数 / 账号数 / 会话数 / 今日发送数 |
|
||||
|
||||
实现：在对应 Service 新增 `listXxx(tenantCode)`，使用 MyBatis-Plus `LambdaQueryWrapper` 按 `tenant_code` 查询。
|
||||
|
||||
#### 2.2 前端页面改造
|
||||
|
||||
**Dashboard.vue**
|
||||
- `onMounted` 调用 `/api/v1/dashboard/stats`。
|
||||
- 4 个统计卡片显示真实数字。
|
||||
|
||||
**ChannelSubject.vue**
|
||||
- 补充 `corpId`、`agentId`、`agentSecret` 输入框。
|
||||
- `onMounted` 加载列表。
|
||||
- 创建成功后刷新列表。
|
||||
|
||||
**ChannelAccount.vue**
|
||||
- 补充 `subjectId` 下拉选择（从主体列表加载）、`sessionArchiveEnabled` 开关。
|
||||
- `onMounted` 加载账号列表和主体列表。
|
||||
|
||||
**Conversation.vue**
|
||||
- 补充 `ownerAccountId` 下拉选择。
|
||||
- 增加「绑定账号」操作列：弹窗选择账号 + 绑定类型（发送主号/备用号、接收主号/备用号）。
|
||||
- `onMounted` 加载会话列表和账号列表。
|
||||
|
||||
**Person.vue**
|
||||
- `onMounted` 加载人员列表。
|
||||
- 增加「渠道身份」快捷绑定（可选，首期至少做列表）。
|
||||
|
||||
**SendRecord.vue**
|
||||
- 目标类型为「会话」时，目标值改为下拉选择会话。
|
||||
- 内容类型为 `text` 时，内容改为普通文本框，自动包装 JSON。
|
||||
- 保留「高级 JSON」开关（可选）。
|
||||
- 列表页默认展示最近发送记录。
|
||||
|
||||
**Tag.vue**
|
||||
- 以树形或表格展示层级路径。
|
||||
- 创建时支持选择父标签。
|
||||
|
||||
### 三、入站消息处理流程图
|
||||
|
||||
#### 3.1 依赖
|
||||
|
||||
安装 `@vue-flow/core` 和 `@vue-flow/background`（或 `@vue-flow/additional-components`）。
|
||||
|
||||
#### 3.2 流程定义可视化
|
||||
|
||||
改造 `InboundFlow.vue`：
|
||||
- 使用 Vue Flow 展示节点：
|
||||
- `receive`（接收消息）
|
||||
- `intent`（意图识别）
|
||||
- `webhook`（推送业务系统）
|
||||
- `reply`（自动回复）
|
||||
- `end`（结束）
|
||||
- 支持拖拽添加节点、连接边、配置节点参数。
|
||||
- 保存时把节点/边数组序列化为 JSON，调用 `/api/v1/flow/definition`。
|
||||
|
||||
#### 3.3 流程执行追踪
|
||||
|
||||
新增后端接口：
|
||||
- `/api/v1/inbound/{eventId}/trace`：返回该入站消息经过的节点列表、每个节点的输入输出、耗时、状态。
|
||||
|
||||
在 `FlowEngine` 中记录执行轨迹：
|
||||
- 新增 `FlowExecutionTrace` 表（`event_id`、`node_type`、`node_config`、`input`、`output`、`status`、`duration_ms`、`create_time`）。
|
||||
- 每个节点执行前后写入轨迹。
|
||||
|
||||
前端新增「消息追踪」弹窗/页面：
|
||||
- 输入 `eventId`，展示流程图高亮路径 + 每个节点详情。
|
||||
|
||||
### 四、消息测试模块
|
||||
|
||||
新增一级菜单「消息测试」和页面 `MessageTest.vue`。
|
||||
|
||||
#### 4.1 出站测试
|
||||
|
||||
- 选择目标类型：会话 / 人员 / 人员列表 / 标签。
|
||||
- 根据目标类型动态选择具体目标（下拉选择或文本输入）。
|
||||
- 选择渠道：企微 / 个人微信 / 钉钉 / 飞书（首期先做企微和个人微信）。
|
||||
- 选择内容类型：text / image / markdown / 文件等（首期先做 text）。
|
||||
- 点击「测试发送」，调用 `/api/v1/send/test`。
|
||||
- 展示返回的 `taskId` 和发送记录。
|
||||
|
||||
#### 4.2 入站模拟
|
||||
|
||||
- 表单字段：eventId、channelType、eventType、messageSource、conversationId、accountId、personId、content。
|
||||
- 点击「模拟入站」，调用 `/api/v1/inbound/receive`。
|
||||
- 展示返回的 event 信息和流程执行结果（调用 trace 接口）。
|
||||
|
||||
#### 4.3 Webhook 测试接收器（可选）
|
||||
|
||||
- 提供一个 `/api/v1/webhook-test/receive` 端点，把收到的 payload 写入内存或 Redis。
|
||||
- 前端可查看最近 10 条被推送的 webhook 内容，用于调试入站流程。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不做真正的企微/钉钉/飞书渠道适配器（仍保持 mock 或骨架）。
|
||||
- 不做编辑/删除（只补创建 + 列表 + 绑定）。
|
||||
- 不做复杂的 RBAC 权限点控制（先按角色粗分）。
|
||||
- 不做真正的 LLM 意图识别（保持 mock）。
|
||||
|
||||
## 成功标准
|
||||
|
||||
- 登录页可登录，未登录无法进入管理页面。
|
||||
- 不同租户登录后只能看到自己的数据。
|
||||
- Dashboard 显示真实统计。
|
||||
- 渠道主体、账号、会话、联系人页面创建后能在列表中显示。
|
||||
- 会话页面可直接绑定发送/接收账号。
|
||||
- 入站流程页面可拖拽编排节点并保存。
|
||||
- 单条入站消息可通过 eventId 查看执行路径。
|
||||
- 消息测试模块可完成出站测试发送和入站模拟。
|
||||
- `npm test`、`mvn test`、`pytest`、外部 API 脚本全部通过。
|
||||
Reference in New Issue
Block a user