sino-mci/docs/superpowers/specs/2026-07-07-admin-auth-flow-testing-design.md

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