kefu_cloud/docs/权限.md

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

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	边界保护	无法删除最后一个管理员，删除自定义角色时提示迁移账号，越权操作被拦截