From b0624126adafb88e379203d65ad86ee83f2717e6 Mon Sep 17 00:00:00 2001 From: marsal Date: Thu, 9 Jul 2026 10:53:08 +0800 Subject: [PATCH] docs: add system menu redesign spec --- .../2026-07-09-system-menu-redesign-design.md | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-09-system-menu-redesign-design.md diff --git a/docs/superpowers/specs/2026-07-09-system-menu-redesign-design.md b/docs/superpowers/specs/2026-07-09-system-menu-redesign-design.md new file mode 100644 index 0000000..a7c9875 --- /dev/null +++ b/docs/superpowers/specs/2026-07-09-system-menu-redesign-design.md @@ -0,0 +1,182 @@ +# 消息中台管理后台菜单重构设计 + +> **日期**：2026-07-09 +> **状态**：已确认，待实现 +> **关联文档**：[消息与客户互动中台架构设计](../architecture/2026-07-06-message-customer-interaction-design.md) + +--- + +## 1. 背景与问题 + +当前管理后台采用 14 项平铺菜单，功能随需求逐步叠加，导致： + +- **职责割裂**：同一业务对象（如渠道账号）的初始化、状态监控、登录操作分散在不同页面。 +- **工作流不连贯**：运营人员完成一次“发消息”需要跳转发送记录、测试发送、发送策略等多个平级菜单。 +- **设计不统一**：部分页面是对象管理 CRUD，部分是流程编排，部分是工具页面，缺少统一的信息架构。 + +本设计从三类用户（平台管理员、租户管理员/技术人员、运营人员）的实际工作流出发，重新梳理菜单层级与功能定义。 + +--- + +## 2. 设计目标 + +1. **按工作流组织顶层菜单**：让用户按“接入 → 维护资产 → 运营发送 → 编排流程 → 系统管理”的路径找到功能。 +2. **按业务对象聚合二级功能**：同一对象（渠道账号、会话、联系人）的关联操作放在同一模块下。 +3. **明确功能边界**：每个菜单项都有清晰的功能定义、面向角色和与现有页面的映射关系。 +4. **预留扩展位**：IVR 流程等 2092 阶段功能先不实现，但保留模块位置说明。 + +--- + +## 3. 设计决策 + +采用 **混合式组织（候选 C）**： + +- 顶层按 **工作流/职责域** 划分，降低日常操作路径长度。 +- 模块内按 **业务对象** 分组，保持数据模型与 UI 结构一致。 +- 权限按角色控制菜单可见性，而不是为每个角色单独一套菜单。 + +--- + +## 4. 角色定义 + +| 角色 | 说明 | 典型操作 | +|------|------|---------| +| 平台管理员 | 中台平台级管理 | 创建租户、维护平台角色 | +| 租户管理员 | 业务系统技术人员/管理员 | 配置渠道、管理用户、配置流程 | +| 运营人员 | 日常消息运营 | 发送、查看记录、维护联系人/群 | + +> 说明：运营人员缺少部分租户内容管理，其他权限与租户管理员相同。具体可见性通过角色权限控制，不由菜单结构区分。 + +--- + +## 5. 菜单结构 + +### 5.1 一级菜单总览 + +| 一级菜单 | 定位 | 可见角色 | +|---------|------|---------| +| 概览 | 运营总览、快捷入口 | 全部 | +| 渠道接入 | 渠道资源与账号接入 | 租户管理员、运营人员 | +| 客户与群 | 联系人、会话、标签资产 | 租户管理员、运营人员 | +| 消息运营 | 发送、记录、策略、消息查询 | 租户管理员、运营人员 | +| 流程编排 | 入站消息处理配置 | 租户管理员 | +| 系统管理 | 租户、用户、角色 | 平台管理员、租户管理员 | + +### 5.2 概览 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 运营总览 | 展示今日发送量、成功/失败/待发送统计、最近异常、关键指标卡片 | 复用并增强现有 Dashboard | +| 快捷入口 | 提供常用功能的一键跳转（测试发送、发送记录、渠道账号） | 新增 | + +### 5.3 渠道接入 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 渠道主体 | 维护企业在各渠道的主体信息：企微 corp_id/secret、钉钉/飞书主体；支持会话存档开关 | 现有 ChannelSubject 页面迁移 | +| 渠道账号 | 维护用于收发消息的载体账号：新增、编辑、启用/停用、查看在线/登录/风控状态、强制下线 | 现有 ChannelAccount 页面迁移 | +| 账号初始化 | 统一入口引导初始化：企微员工/应用、个微扫码登录、机器人 webhook | 从 ChannelAccount 页面拆分出的引导流程 | +| 应用管理 | 企微应用等渠道应用的配置：agent_id、agent_secret、应用消息推送能力 | 新增（原散落在渠道账号中） | + +### 5.4 客户与群 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 联系人 | 维护 Person（业务身份），含 person_code、person_type、phone、institution_id、supplier_id、contract_id；支持新增/编辑/启用停用 | 现有 Person 页面增强 | +| 渠道身份 | 管理 Person 在各渠道的身份映射：企微 external_userid、个微 wxid、钉钉 userid、飞书 open_id | 新增独立入口 | +| 标签体系 | 树形标签管理：新增/编辑/删除、查看人员与会话标签分布；标签表达角色/合同/机构/供应商等业务属性 | 现有 Tag 页面升级为体系化管理 | +| 会话/群聊 | 维护 Conversation：新增、编辑、同步群成员、查看历史消息、绑定业务字段（contract_id 等） | 现有 Conversation 页面迁移 | +| 账号-会话绑定 | 为会话配置发送主备号、接收主备号及优先级；单聊约束需校验 channel_type 一致性 | 从 Conversation 页面拆分出的独立管理 | + +### 5.5 消息运营 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 发送记录 | 按任务查询发送明细、状态、结果、重试记录；支持取消待发送任务 | 现有 SendRecord 页面迁移 | +| 测试发送 | 模拟发送，不实际调用渠道，用于业务系统联调和发送逻辑验证 | 现有 MessageTest 页面迁移并改名 | +| 发送策略 | 策略组配置：频率控制、时间窗口、黑名单、重试、主备切换 | 现有 SendPolicy 页面迁移 | +| 消息查询 | 统一查询入站/出站消息事件（MessageEvent），支持按会话、人员、账号、来源（realtime / session_archive）筛选 | 新增 | + +### 5.6 流程编排 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 入站 Webhook | 配置业务系统接收入站消息的 webhook URL、签名方式、测试连通性 | 现有 InboundWebhook 页面迁移 | +| 入站流程 | 轻量画布配置入站消息处理流程：receive → intent → condition → webhook/reply | 现有 InboundFlow 页面迁移 | + +> **本期不做**：IVR 流程（2092 阶段接入）。 + +### 5.7 系统管理 + +| 二级菜单 | 功能定义 | 页面/备注 | +|---------|---------|----------| +| 租户管理 | 平台管理员创建/编辑租户；租户管理员维护本租户基础信息、认证配置、入站 webhook | 现有 TenantManagement 页面增强 | +| 用户管理 | 中台用户增删改查、重置密码、启用/停用、绑定角色 | 现有 UserManagement 页面迁移 | +| 角色权限 | 平台角色 admin/operator/viewer 的权限配置与分配 | 新增（首期角色固定，可配置权限列表） | + +--- + +## 6. 现有菜单调整映射 + +| 当前菜单 | 调整方式 | 新位置 | +|---------|---------|--------| +| 概览 | 保留并增强 | 概览 → 运营总览 | +| 渠道主体 | 保留 | 渠道接入 → 渠道主体 | +| 渠道账号 | 拆分 | 渠道接入 → 渠道账号 / 账号初始化 / 应用管理 | +| 会话/群聊 | 拆分 | 客户与群 → 会话/群聊 / 账号-会话绑定 | +| 联系人 | 保留，增强 | 客户与群 → 联系人 | +| 标签 | 升级为体系 | 客户与群 → 标签体系 | +| 发送记录 | 保留 | 消息运营 → 发送记录 | +| 消息测试 | 保留，改名 | 消息运营 → 测试发送 | +| 发送策略 | 保留 | 消息运营 → 发送策略 | +| 入站流程 | 保留 | 流程编排 → 入站流程 | +| IVR 流程 | 本期移除 | — | +| 入站 Webhook | 保留 | 流程编排 → 入站 Webhook | +| 流程追踪 | 合并 | 消息运营 → 发送记录（详情）/ 消息查询 | +| 用户管理 | 保留 | 系统管理 → 用户管理 | +| 租户管理 | 保留 | 系统管理 → 租户管理 | + +--- + +## 7. 新增页面清单 + +| 页面 | 所属模块 | 功能说明 | +|------|---------|---------| +| 账号初始化 | 渠道接入 | 引导式初始化各渠道账号 | +| 应用管理 | 渠道接入 | 企微应用等渠道应用配置 | +| 渠道身份 | 客户与群 | 管理 Person 在各渠道的身份映射 | +| 账号-会话绑定 | 客户与群 | 会话与收发账号的绑定管理 | +| 消息查询 | 消息运营 | 统一查询入站/出站消息事件 | +| 角色权限 | 系统管理 | 中台角色与权限配置 | + +--- + +## 8. 不在本期范围内的功能 + +| 功能 | 原因 | 后续阶段 | +|------|------|---------| +| IVR 流程 | 属于 2092 IVR 语音配置需求，本期聚焦 1851 企微场景 | 2092 阶段 | +| 模板管理 | 中台不保存模板，由业务系统自行维护 | 不涉及 | +| 业务触发规则 | 中台不承载业务系统触发规则 | 不涉及 | + +--- + +## 9. 实现要点 + +1. **前端路由**：按新菜单结构重排 `admin-web/src/router/index.ts`，路径建议保持语义化，如 `/channel-subject`、`/channel-account/init`、`/customer/person`、`/message/record`。 +2. **布局组件**：`Layout.vue` 从平铺 `el-menu-item` 改为分组 `el-sub-menu`，支持一级展开/收起。 +3. **权限控制**：菜单可见性通过 `authStore.roleCodes` 或后端返回的权限列表控制；URL 级权限同步调整。 +4. **页面拆分**： + - `Conversation.vue` 中的“绑定账号”功能拆出为 `ConversationAccountBinding.vue`。 + - `ChannelAccount.vue` 中的初始化流程拆出为 `ChannelAccountInit.vue`。 +5. **空状态处理**：新增页面先实现最小可用版本，避免阻塞菜单上线。 + +--- + +## 10. 验收标准 + +- [ ] 左侧导航按新 6 大模块分组展示，无 IVR 流程入口。 +- [ ] 每个二级菜单有明确页面，无 404。 +- [ ] 租户管理员、运营人员、平台管理员看到的菜单符合角色定义。 +- [ ] 现有功能在迁移后行为保持一致。 +- [ ] 新增页面至少具备列表/查询能力，复杂编辑可二期补齐。