# 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 脚本全部通过。