# 在线客服系统权限控制页面需求文档

## 1 需求背景与目标

当前在线客服系统已具备工作台、客户管理、对话记录、知识库、快捷回复、黑名单、数据统计、系统设置八大模块。随着客服团队规模扩大，需要为不同岗位配置差异化的功能访问与操作权限，避免普通客服误改系统配置，同时让主管能够管理团队数据而不触及租户级配置。

### 1.1 业务目标

- 建立 管理员、客服主管、客服 三级角色体系，覆盖租户内全部功能模块。
- 提供可视化的 角色管理与权限配置页面，管理员可自定义角色权限并分配给账号。
- 明确每个角色的 菜单可见范围、页面操作权限、数据隔离范围，降低越权风险。

### 1.2 范围说明

本期权限控制聚焦于租户内部的角色与账号管理，不包含平台级多租户运营权限。默认内置三个角色：管理员、客服主管、客服。管理员可新建自定义角色，但系统保留对内置角色的保护（不可删除、不可修改角色标识）。

## 2 角色定义

| 角色  | 定位  | 数据范围 | 核心能力 |
| --- | --- | --- | --- |
| 管理员 | 租户最高权限，通常是企业客服负责人或 IT 管理员 | 全租户数据 | 管理账号与角色、配置系统设置、查看全部数据、操作所有模块 |
| 客服主管 | 一线客服团队管理者 | 全租户数据（查看），操作受限于权限项 | 监控团队会话、管理团队绩效、维护知识库与快捷回复、管理黑名单 |
| 客服  | 一线接待人员 | 仅自己的会话与客户数据 | 使用工作台接待访客、使用知识库/快捷回复、维护自己接待的客户资料 |

## 3 系统模块清单

根据现有系统设计，本次权限控制需要覆盖以下模块与页面。每个模块拆分为「查看」与「操作」两类权限，部分模块还需细分数据范围。

| 一级模块 | 二级页面/功能 | 权限项说明 |
| --- | --- | --- |
| 工作台 | 会话列表、聊天区、客户信息面板 | 查看会话、回复消息、转接会话、结束会话、添加内部备注、标记优先级 |
| 客户管理 | 客户列表、客户详情抽屉 | 查看客户、新增客户、编辑客户、导出客户、管理客户标签、查看全部/仅自己客户 |
| 对话记录 | 会话记录列表、会话详情 | 查看对话记录、导出记录、批量归档、查看全部/仅自己记录 |
| 知识库 | 知识分类、知识条目 | 查看知识库、新建条目、编辑条目、发布/下架、删除条目、管理分类 |
| 快捷回复 | 团队快捷回复、我的快捷回复 | 查看快捷回复、新建团队回复、编辑团队回复、删除团队回复、管理个人回复 |
| 黑名单 | 黑名单列表 | 查看黑名单、拉黑访客/设备、解除黑名单 |
| 数据统计 | KPI 看板、趋势图、绩效排行 | 查看数据统计、导出报告、查看团队/个人数据 |
| 系统设置 | 基本设置、渠道管理、坐席账号、客服分配规则、客户标签、自动回复、工作时间、通知设置 | 查看设置、修改各子项配置 |
| 权限控制 | 角色管理、权限配置、成员账号 | 查看角色、创建/编辑角色、删除自定义角色、分配角色给账号 |

## 4 角色权限矩阵

下表定义三个内置角色的默认权限。符号说明：**√** 表示拥有权限，**○** 表示仅查看/仅自己数据，**×** 表示无权限。

| 模块  | 权限项 | 管理员 | 客服主管 | 客服  |
| --- | --- | --- | --- | --- |
| 工作台 | 查看会话列表 | √   | √   | √   |
| 回复访客消息 | √   | √   | √   |
| 转接会话给其他客服 | √   | √   | ×   |
| 结束会话 | √   | √   | √   |
| 添加内部备注 | √   | √   | √   |
| 标记会话优先级 | √   | √   | ○（仅自己） |
| 客户管理 | 查看客户列表 | √   | √   | ○（仅自己） |
| 新增客户 | √   | √   | √   |
| 编辑客户资料 | √   | √   | ○（仅自己） |
| 导出客户 | √   | √   | ×   |
| 管理客户标签 | √   | √   | ○（仅自己客户） |
| 对话记录 | 查看对话记录 | √   | √   | ○（仅自己） |
| 查看会话详情 | √   | √   | ○（仅自己） |
| 导出对话记录 | √   | √   | ×   |
| 批量归档记录 | √   | √   | ×   |
| 知识库 | 查看知识库 | √   | √   | √   |
| 新建知识条目 | √   | √   | ×   |
| 编辑知识条目 | √   | √   | ×   |
| 发布/下架条目 | √   | √   | ×   |
| 删除知识条目/分类 | √   | ○（主管可删除自己创建） | ×   |
| 快捷回复 | 查看快捷回复 | √   | √   | √   |
| 新建团队快捷回复 | √   | √   | ×   |
| 编辑/删除团队回复 | √   | √   | ×   |
| 管理我的快捷回复 | √   | √   | √   |
| 黑名单 | 查看黑名单 | √   | √   | ×   |
| 拉黑访客/IP/设备 | √   | √   | ×   |
| 解除黑名单 | √   | √   | ×   |
| 数据统计 | 查看数据统计 | √   | √   | ○（仅个人） |
| 导出报告 | √   | √   | ×   |
| 查看客服绩效排行 | √   | √   | ○（仅自己排名） |
| 系统设置 | 基本设置 | √   | ×   | ×   |
| 渠道管理 | √   | ×   | ×   |
| 坐席账号 | √   | ×   | ×   |
| 客服分配规则 | √   | ×   | ×   |
| 客户标签 | √   | √   | ×   |
| 自动回复 | √   | √   | ×   |
| 工作时间 | √   | ×   | ×   |
| 通知设置 | √   | ×   | ×   |
| 权限控制 | 查看角色列表 | √   | ×   | ×   |
| 创建/编辑角色 | √   | ×   | ×   |
| 删除自定义角色 | √   | ×   | ×   |
| 给账号分配角色 | √   | ×   | ×   |

**数据隔离原则**：客服角色在所有模块中默认只能看到「自己接待的会话」和「自己创建/跟进过的客户」；客服主管与管理员可查看全租户数据，但主管的操作权限受限于矩阵中的勾选范围。

## 5 页面原型设计

权限控制模块包含三个核心页面：角色管理列表、角色权限配置、成员账号管理。以下原型展示页面布局、字段与主要交互，开发时可作为视觉与交互参考。

### 5.1 角色管理列表页

管理员进入「系统设置 > 权限控制 > 角色管理」后，看到租户内所有角色卡片。内置角色不可删除、不可修改标识，仅可调整权限范围；自定义角色支持完整编辑与删除。

角色管理列表

客服云

工作台

客户管理

对话记录

知识库

快捷回复

黑名单

数据统计

系统设置

角色管理

\+ 新建角色

角色列表

成员账号

操作日志

内置 管理员

配置权限

租户最高权限，可管理账号、角色与全部系统设置。不可删除。

成员数：1权限项：38/38最后更新：系统默认

内置 客服主管

配置权限

管理一线团队，可查看全部数据并维护知识库、快捷回复、黑名单等。

成员数：3权限项：24/38最后更新：2026-07-18

内置 客服

配置权限

一线接待人员，仅可查看和操作自己相关的会话、客户与个人数据。

成员数：12权限项：14/38最后更新：系统默认

自定义 VIP 专属客服

配置权限

删除

基于客服角色扩展，可查看被分配为高优先级客户的资料，但不可导出数据。

成员数：2权限项：16/38最后更新：2026-07-15

**列表页字段说明**：角色名称、类型（内置/自定义）、成员数、已启用权限项数量、最近更新时间、操作按钮。点击「配置权限」进入角色权限配置页。

### 5.2 角色权限配置页

该页面为角色勾选可访问模块与具体权限项。左侧按模块分组，右侧展示权限项；每个模块支持「查看」与「操作」两类权限，数据范围通过下拉选项单独配置。

配置角色：客服主管

客服主管

内置角色 · 标识 supervisor · 3 位成员

取消

保存

工作台 数据范围：全部会话

查看会话列表

回复访客消息

转接会话

结束会话

添加内部备注

标记优先级

客户管理 数据范围：全部客户

查看客户列表

新增客户

编辑客户资料

导出客户

管理客户标签

系统设置 仅部分子项

客户标签

自动回复

基本设置

渠道管理

坐席账号

工作时间

**交互规则：**取消「查看」权限时，该模块下所有「操作」权限自动取消勾选；勾选任意「操作」权限时，「查看」权限自动勾选。数据范围选项随模块不同而变化（全部 / 仅自己 / 指定分组）。

### 5.3 成员账号管理页

成员账号页用于查看所有系统账号、分配角色、控制账号状态。只有管理员拥有完整编辑权限；客服主管可在被授权的情况下查看成员列表（本期暂不开放给主管）。

成员账号管理

客服云

工作台

客户管理

对话记录

知识库

快捷回复

黑名单

数据统计

系统设置

成员账号

\+ 新增账号

| 账号  | 姓名  | 角色  | 状态  | 最近登录 | 操作  |
| --- | --- | --- | --- | --- | --- |
| admin@company.com | 赵总  | 管理员 | 在线  | 2026-07-19 16:52 | 编辑  |
| supervisor@company.com | 李主管 | 客服主管 | 在线  | 2026-07-19 15:30 | 编辑  |
| agent01@company.com | 王小明 | 客服  | 离线  | 2026-07-18 09:15 | 编辑  |
| vip01@company.com | 张小红 | VIP 专属客服 | 在线  | 2026-07-19 14:20 | 编辑  |

**批量操作：**选中多个账号后可批量「启用/停用」或「批量更换角色」。被停用的账号立即失去系统访问权限，已登录会话在下次请求时鉴权失败并跳转登录页。

## 6 权限逻辑规则

权限控制需要在路由、页面元素、数据查询、接口四个层面生效。以下规则确保同一套权限配置在前后端保持一致，防止越权。

### 6.1 菜单与路由控制

- 用户登录后，前端根据当前账号角色获取 可见菜单列表，未授权的菜单不在侧边栏渲染。
- 用户直接输入未授权页面的 URL 时，前端路由守卫拦截并跳转至「无权访问」提示页或工作台。
- 权限控制模块本身仅对管理员可见，其他角色即使知道路径也无法进入。

### 6.2 页面元素控制

- 每个操作按钮绑定独立权限码，前端根据权限码的布尔值决定是否渲染。
- 对客服角色，页面中「导出」「删除」「批量操作」等按钮默认隐藏，避免误操作。
- 数据范围相关的筛选器（如「全部客服 / 我的数据」）根据角色默认选中并锁定不可修改。

### 6.3 数据查询隔离

- **客服**：客户管理、对话记录、数据统计等模块的 SQL 查询必须附加 owner_id = current_user_id 条件，仅返回自己接待或跟进的数据。
- **客服主管**：默认返回全租户数据；若主管被配置为仅查看指定分组，则按分组过滤。
- **管理员**：返回全租户数据，不受额外数据范围限制。

### 6.4 后端接口鉴权

- 所有写操作接口（POST/PUT/DELETE）必须在网关层校验当前账号是否具备对应权限码。
- 接口鉴权不依赖前端隐藏，必须基于服务端角色权限表实时判断。
- 对于「查看」类接口，除了校验权限码，还需校验数据范围参数是否超出角色允许范围。

### 6.5 权限生效时机

- 角色权限保存后，下一次请求即时生效，不需要用户重新登录。
- 账号被禁用或角色被变更时，服务端 Token 可保持有效期，但在每次请求时校验账号状态与角色绑定。
- 对于长连接场景（如 WebSocket 会话通道），服务端在推送消息前校验该客服是否仍有权限接收对应会话消息。

## 7 边界情况与异常处理

### 7.1 内置角色保护

管理员、客服主管、客服为系统内置角色，拥有固定角色标识（admin、supervisor、agent）。这些角色不可删除、不可修改标识、不可清空全部权限，防止系统失去基础管理能力。

### 7.2 删除自定义角色

删除自定义角色前，系统需校验该角色下是否仍有账号。若存在绑定账号，则禁止删除并提示「请先为该角色下 N 个账号更换角色」。删除后，原绑定账号默认降级为「客服」角色，需管理员二次确认。

### 7.3 唯一管理员的保护

当租户内仅剩一个管理员账号时，该账号不可被删除、不可被禁用、不可被降级为其他角色。若管理员需要离职，必须先创建或提升另一个账号为管理员。

### 7.4 账号状态与权限

- **启用**：账号正常拥有角色对应权限。
- **停用**：账号立即失去所有权限，已登录状态在下次请求时被踢出。
- **待激活**：新创建账号但未完成首次登录，角色已分配但不计入在线客服数。

### 7.5 数据越权访问

若用户通过接口篡改参数（如将 agent_id 改为他人 ID）试图查看他人数据，服务端应拒绝并记录审计日志。对于频繁越权尝试的账号，可触发风控策略临时锁定。

### 7.6 角色变更后的会话处理

管理员在客服正在接待访客时调整其角色（如从客服主管降级为客服），该客服已接待的会话不受影响，可继续处理；但变更后新进入的会话按新权限规则分配。若变更导致该客服失去工作台权限，则系统 gracefully 关闭其会话通道并提示重新登录。

## 8 非功能性需求

### 8.1 性能

- 权限列表查询接口响应时间 ≤ 200ms（P95）。
- 单次登录后权限数据可缓存于前端，权限变更时通过 WebSocket 或接口响应头通知刷新。

### 8.2 安全性

- 角色权限数据存储需与业务数据同等级别保护，防止越权篡改。
- 所有权限变更操作记录审计日志，包括操作人、时间、变更前后权限快照。
- 敏感操作（如删除角色、变更管理员角色）需二次确认或输入账号密码确认。

### 8.3 可扩展性

- 权限项采用码表形式维护，新增模块时只需插入新的权限码即可，无需修改角色表结构。
- 角色与权限之间为多对多关系，支持未来扩展更多自定义角色。
- 数据范围字段预留扩展字段，支持未来按客服分组、按渠道、按客户标签等维度隔离。

### 8.4 兼容性

- 老版本账号首次迁移至新权限体系时，默认映射为「客服」角色，管理员可后续调整。
- 未命中任何角色的账号（异常数据）默认无任何权限，登录后仅显示「联系管理员」页面。

## 9 验收标准

以下验收标准用于判断权限控制功能是否达到可上线状态。

| 编号  | 验收项 | 通过标准 |
| --- | --- | --- |
| A1  | 角色列表 | 管理员可见内置与自定义角色，非管理员无法访问权限控制菜单与页面 |
| A2  | 权限配置 | 管理员可编辑角色权限并保存，保存后下次请求即时生效；内置角色标识不可修改 |
| A3  | 菜单控制 | 客服登录后侧边栏不显示「系统设置」「权限控制」「黑名单」「数据统计」等未授权菜单 |
| A4  | 按钮控制 | 客服在工作台、客户管理、对话记录等页面看不到「导出」「批量操作」「删除」等按钮 |
| A5  | 数据隔离 | 客服只能查看自己接待的会话与跟进客户；主管可查看全租户数据；管理员可查看全部 |
| A6  | 接口鉴权 | 使用客服账号 Token 调用主管/管理员接口返回 403，并在审计日志中记录 |
| A7  | 成员管理 | 管理员可新增、编辑、停用账号并分配角色；停用账号立即无法访问系统 |
| A8  | 边界保护 | 无法删除最后一个管理员，删除自定义角色时提示迁移账号，越权操作被拦截 |