完善角色权限与数据隔离

docs/权限.md

@@ -0,0 +1,358 @@
+# 在线客服系统权限控制页面需求文档
+
+## 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  | 边界保护 | 无法删除最后一个管理员，删除自定义角色时提示迁移账号，越权操作被拦截 |