1文档概述
本文档为云灵汐涉旅电商分销子系统PC端基础功能及权限中心模块的产品需求文档,覆盖平台运营后台、供应商后台、分销商后台三端的账号、权限与安全能力。文档面向前端开发工程师、后端开发工程师、测试工程师及产品经理,用于指导设计、开发、测试与验收。
文档用途
- 明确权限中心模块的功能边界、业务逻辑与交互规则
- 统一三端(平台/供应商/分销商)在账号、权限、审计上的实现标准
- 作为研发拆分任务、接口设计、测试用例编写的直接输入
- 作为后续迭代与功能扩展的基线文档
术语定义
- 平台运营后台:平台方运营人员使用的PC管理后台,具备全局数据查看与管理权限
- 供应商后台:旅游资源供应商(景区/酒店/车队等)使用的PC管理后台
- 分销商后台:分销商使用的PC管理后台,分为个体分销商、B端分销商、OTA分销商三类
- RBAC:基于角色的访问控制(Role-Based Access Control)
- 数据权限:控制用户可见数据范围的权限维度,包括全部、本部门、本人、自定义
- 敏感字段:手机号、身份证号、银行卡号等需脱敏或隐藏处理的字段
1A术语表
本文档涉及的全部专业术语与业务名词,统一定义如下。禁止使用未定义的术语。
1A.1 多租户与组织相关
| 术语 | 英文/编码 | 定义 |
|---|---|---|
| SaaS多租户 | Multi-Tenant SaaS | 同一套软件实例服务多个租户(平台/供应商/分销商),通过租户隔离字段保证数据互不可见 |
| 商家身份类型 | merchant_type | 多选(逗号分隔存储),取值 PLATFORM(平台运营)/ SUPPLIER(供应商)/ DISTRIBUTOR(分销商)。PLATFORM 互斥(选 PLATFORM 不可选 SUPPLIER/DISTRIBUTOR);SUPPLIER 和 DISTRIBUTOR 可同时选(如 SUPPLIER,DISTRIBUTOR 表示既是供应商又是分销商)。决定菜单树加载、路由准入、登录跳转 |
| 租户实例ID | tenant_id | 具体租户的主键标识。同一 merchant_type 下区分不同租户实例(如供应商A与供应商B),是ORM层行级数据隔离的唯一注入字段 |
| 分销商子类型 | distributor_type | 仅当 merchant_type 含 DISTRIBUTOR 时填写(单选),取值 INDIVIDUAL(个体)/ B(B端)/ OTA。决定分销商菜单树、子账号、结算模式差异 |
| 供应商子类型 | supplier_type | 仅当 merchant_type 含 SUPPLIER 时填写,多选(逗号分隔存储),取值 TICKET(票务)/ HOTEL(酒店)/ VEHICLE(车辆)/ SPECIALTY(特产)/ ROUTE(线路),至少选1项。决定商品管理菜单、资质上传、订单品类筛选、财务报表维度、分销授权范围、营销活动商品范围(详见5C.1A) |
| 租户隔离 | Tenant Isolation | 所有业务表通过 tenant_id 条件在ORM层自动注入SQL(merchant_type 为多选逗号分隔,不支持等值查询,由应用层校验),确保跨租户数据不可见 |
| 组织架构 | Department / Org Tree | 租户内部的部门树,是"本部门数据"权限的判定基础 |
| 部门负责人 | Department Leader | 部门的 leader_id 指向的用户,硬性获得本部门及子部门数据查看权限 |
1A.2 权限模型相关
| 术语 | 英文/编码 | 定义 |
|---|---|---|
| RBAC | Role-Based Access Control | 基于角色的访问控制:用户↔角色↔权限的多对多关系,用户通过角色间接获得权限 |
| 四层权限模型 | 4-Layer Permission | 菜单权限 + 按钮权限 + 行级数据权限 + 列级敏感字段权限,从粗到细的四级控制 |
| 菜单权限 | Menu Permission | 控制登录后左侧导航栏可见菜单项,按端类型隔离 |
| 按钮权限 | Button Permission | 控制页面内具体操作的可见性,编码格式 模块:操作(如 user:create),前后端双层校验 |
| 行级数据权限 | Row-Level Data Permission | 控制列表查询可见的数据行范围,四档:全部/本部门/本人/自定义 |
| 列级敏感字段权限 | Column-Level Sensitive Field | 控制字段展示形式:明文/脱敏/隐藏,明文需二次验证 |
| 权限并集 | Permission Union | 多角色用户权限取并集(最大范围),如同时拥有"全部数据"和"本部门数据",结果为"全部数据" |
| 权限缓存 | Permission Cache | 用户权限集合缓存到Redis,避免每次请求查DB;权限变更时主动失效 |
| ORM拦截 | ORM Interceptor | 在ORM层自动拼接租户和数据权限SQL条件,对业务代码透明 |
1A.3 角色与业务相关
| 术语 | 英文/编码 | 定义 |
|---|---|---|
| 平台运营 | Platform Operator | 系统运营方,可看全局数据,负责商家入驻审核、商品审核、财务清分等 |
| 供应商 | Supplier | 商品供给方,仅管理自有商品/订单/财务,与分销商签订授权协议。按经营品类选择子类型(supplier_type 多选),不同组合的商品管理菜单不同(详见5C.1A) |
| 个体分销商 | Individual Distributor | 自然人分销员,佣金模式(按成交比例获佣),不开放子账号,不显示"用户管理"菜单 |
| B端分销商 | B-End Distributor | 企业分销商,底价模式(底价采购+自行加价),可创建子账号、授权菜单 |
| OTA分销商 | OTA Distributor | 接口型分销商,通过API对接,可创建子账号、配置接口运营角色 |
| 底价模式 | Base Price Model | B端分销商以供应商底价采购,自行加价销售,赚取差价 |
| 佣金模式 | Commission Model | 个体分销商以平台售价销售,按成交比例获得佣金 |
| 三端 | Three Ends | 平台运营后台、供应商后台、分销商后台,通过同一登录入口按 merchant_type 多选值合并加载菜单并自动路由 |
1A.4 安全与审计相关
| 术语 | 英文/编码 | 定义 |
|---|---|---|
| 敏感字段 | Sensitive Field | 手机号/身份证号/银行卡号/法人身份证/联系人手机号/游客姓名 共6项,需脱敏或隐藏 |
| 脱敏 | Desensitization | 字段部分遮挡展示,如手机号 138****8888,是敏感字段的默认展示级别 |
| 二次验证 | Secondary Verification | 查看敏感字段明文时需输入短信验证码或登录密码,限时5分钟,每日上限20次 |
| JWT | JSON Web Token | 登录态载体,有效期24小时(记住我7天),同账号互踢机制依赖Token黑名单 |
| 软删除 | Soft Delete | 通过 deleted_at 字段标记删除,保留数据关联,超级管理员可恢复 |
| 操作日志 | Audit Log | 记录用户全链路操作,含操作前后值diff、敏感标记,保留365天后归档 |
| 导出脱敏 | Export Desensitization | 所有导出按角色敏感字段配置强制脱敏,无导出权限按钮隐藏,导出操作记入日志 |
2需求背景
2.1 业务背景
云灵汐涉旅电商分销子系统采用SaaS多租户架构,服务四类核心角色:平台运营、供应商、分销商(个人/B端/OTA)、C端消费者。系统包含运营端PC和分销商城移动端两个前端,后端统一提供商品供应链、订单履约、分销管理、财务清分结算五大核心能力。
在多租户、多角色、多业态的复杂业务场景下,权限中心是整个系统的安全基石。不同角色的用户在同一个系统中操作,必须确保:
- 平台运营能看到全局数据,但无法越权操作供应商或分销商的私有数据
- 供应商只能管理自己的商品、订单和财务数据
- 分销商(尤其是B端和OTA)可以创建子账号并分配不同权限
- 个体分销商暂不开放子账号,避免过度复杂化
- 敏感数据(手机号、身份证、银行卡)根据角色自动脱敏,查看明文需二次验证
2.2 当前痛点
痛点1:权限与业务配置混杂
旧系统中权限配置(如角色、菜单)与业务配置(如商品分类、价格策略)放在同一页面,导致运营人员误操作频繁,权限变更影响业务配置。
痛点2:数据隔离粒度不足
旧系统仅支持"全部/本人"两种数据范围,无法满足"本部门数据可见"、"指定对象范围"等精细化的数据隔离需求,导致敏感数据泄露风险。
痛点3:敏感字段无分级保护
手机号、身份证号等敏感字段在全系统中明文展示,缺乏脱敏策略和查看审计,不符合数据安全合规要求。
痛点4:操作追溯能力弱
旧系统操作日志仅记录"谁做了什么",缺乏操作前后值对比、敏感操作标记、导出审计等能力,出现问题难以追溯。
2.3 不解决的后果
若上述痛点不解决,将直接导致以下风险:
- 数据安全风险:供应商A可查看供应商B的订单和财务数据,引发商业机密泄露
- 合规风险:用户个人信息明文展示且无审计,违反《个人信息保护法》
- 运营效率低下:权限变更需研发介入修改代码,无法由业务人员自助配置
- 系统不可维护:权限逻辑散落在各业务模块,新增功能时需多处修改,技术债务累积
3目标与范围
3.1 总体目标
构建一套统一、灵活、安全、可审计的权限中心体系,支撑云灵汐涉旅电商分销子系统三端(平台运营后台、供应商后台、分销商后台)的账号管理、权限控制、数据隔离与安全审计需求。
1. 权限配置与业务配置分离,不混入商品、订单、财务页面
2. 支持菜单权限、按钮权限、行级数据权限、列级敏感字段权限四层控制
3. 三端共用同一套权限模型,但菜单和数据范围按租户类型动态隔离
4. 所有敏感操作留痕,支持操作前后值对比与追溯
3.2 模块范围
本次PRD覆盖以下四个子模块:
| 子模块 | 功能项 | 适用后台 | 优先级 |
|---|---|---|---|
| 登录与账号安全 | 账号密码登录 | 平台/供应商/分销商 | P0 |
| 修改密码/忘记密码/重置密码 | 平台/供应商/分销商 | P0 | |
| 单点登录与防暴力破解 | 平台/供应商/分销商 | P1 | |
| 用户管理 | 用户账号管理 | 平台/供应商/B端分销商/OTA分销商 | P0 |
| 组织架构管理 | 平台/供应商/B端分销商/OTA分销商 | P1 | |
| 角色权限 | 菜单权限 | 平台/供应商/B端分销商/OTA分销商 | P0 |
| 按钮权限 | 平台/供应商/B端分销商/OTA分销商 | P0 | |
| 行级数据权限 | 平台/供应商/B端分销商/OTA分销商 | P0 | |
| 列级敏感字段权限 | 平台/供应商/B端分销商/OTA分销商 | P0 | |
| 安全审计 | 操作日志审计 | 平台/供应商/分销商 | P1 |
| 明文查看二次验证 | 平台/供应商/分销商 | P1 | |
| 导出强制脱敏 | 平台/供应商/分销商 | P1 |
3.3 不在本次范围内的功能
- 与外部IAM系统(如企业微信、钉钉、飞书)的对接登录
- 生物识别登录(指纹、人脸)
- 多因素认证(MFA)的硬件令牌支持
- 个体分销商的子账号管理(已确认本期不做)
- AI全场景助手相关的权限控制(已确认暂缓)
4用户与角色
4.1 角色定义
系统按租户类型划分为三端,每端内部再细分角色:
| 端 | 租户类型 | 内置角色 | 角色说明 |
|---|---|---|---|
| 平台运营后台 | PLATFORM | 超级管理员 | 系统初始化时创建,具备所有权限,不可删除,可创建其他管理员 |
| 平台管理员 | 管理平台用户、角色、组织架构、系统配置等基础功能 | ||
| 商家运营 | 负责供应商/分销商入驻审核、商家档案管理、合同管理 | ||
| 客服/风控/财务 | 按职能划分的业务角色,数据权限范围不同 | ||
| 供应商后台 | SUPPLIER | 供应商管理员 | 供应商入驻后默认创建,管理本供应商下的所有子账号和权限 |
| 商品专员 | 负责商品创建、库存维护、价格调整 | ||
| 财务专员 | 负责结算单确认、对账差异处理、提现审核 | ||
| 分销商后台 | DISTRIBUTOR | 分销商管理员 | B端/OTA分销商入驻后默认创建,管理本分销商下的子账号 |
| 分销运营 | 负责推广工具使用、选品、订单跟踪 | ||
| 财务专员 | 负责账户中心查看、提现申请、对账 | ||
| 接口运营 | OTA/B端分销商专属,负责ERP/OTA接口配置与异常处理 |
4.2 角色权限差异规则
1. 个人分销商不显示"用户管理"一级菜单,暂不开放创建子账号
2. B端分销商和OTA分销商显示"用户管理"一级菜单,可创建子账号并分配角色
3. 权限配置和业务配置必须分离,不混入商品、订单、财务页面
4. 同一租户内的用户数据互相隔离,跨租户数据不可见
5功能需求总览表
以下表格枚举权限中心模块的全部功能点,为研发任务拆分和验收提供索引。
| # | 模块 | 功能项 | 功能描述 | 优先级 |
|---|---|---|---|---|
| 1 | 登录与账号安全 | 账号密码登录 | 支持手机号/账号密码登录,含错误提示、账号锁定提示、安全退出。首次登录强制修改默认密码。 | P0 |
| 2 | 修改密码/忘记密码/重置密码 | 用户自助修改密码、运营人员强制重置密码、短信验证码重置密码、首次登录改密引导。 | P0 | |
| 3 | 单点登录与防暴力破解 | 同账号多设备互踢机制、连续失败次数锁定、自动解锁配置、登录IP/设备记录。 | P1 | |
| 4 | 用户管理 | 用户账号管理 | 用户列表查询、新增用户、编辑用户信息、停用/启用账号、锁定账号、重置密码、查看用户详情、导出用户列表。 | P0 |
| 5 | 组织架构管理 | 部门树创建与维护、岗位定义、成员归属部门、部门负责人配置、组织架构图展示。 | P1 | |
| 6 | 角色权限 | 菜单权限 | 基于菜单树的授权,支持父子菜单联动选择、半选状态、按端类型隔离菜单、角色-菜单绑定。 | P0 |
| 7 | 按钮权限 | 页面内按钮级权限控制,支持新增、编辑、删除、审核、导出、敏感操作等按钮的显隐与禁用。 | P0 | |
| 8 | 行级数据权限 | 控制数据行可见范围:全部数据、本部门数据、本人数据、自定义对象范围(如指定供应商/分销商)。 | P0 | |
| 9 | 列级敏感字段权限 | 对手机号、身份证号、银行卡号等字段配置脱敏规则:明文/脱敏/隐藏三级控制,查看明文需二次验证。 | P0 | |
| 10 | 安全审计 | 操作日志审计 | 记录操作人、操作对象、操作类型、操作前后值、操作时间、IP地址、操作结果,支持敏感操作标记。 | P1 |
| 11 | 明文查看二次验证 | 查看敏感字段明文时触发二次验证(短信验证码/登录密码),限时展示明文,自动恢复脱敏,操作留痕。 | P1 | |
| 12 | 导出强制脱敏 | 导出数据时根据用户权限自动脱敏敏感字段,无导出权限时禁用导出按钮,导出操作留痕。 | P1 |
5.5核心数据模型定义
明确部门(组织架构)、用户、角色三者之间的实体关系与字段约束,作为后端设计和数据库建表的依据。
5.5.1 部门表(Department)
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | String(32) | PK | 部门唯一标识 |
| name | String(30) | NOT NULL | 部门名称,同一父级下唯一 |
| parent_id | String(32) | 可为空,FK->Department.id | 父级部门ID,为空表示顶级部门 |
| leader_id | String(32) | 可为空,FK->User.id | 负责人用户ID,必须为本部门成员(user.dept_id = 当前部门id) |
| sort | Integer | DEFAULT 0 | 排序权重,值越小越靠前 |
| tenant_id | String(32) | NOT NULL | 租户实例ID,区分同 merchant_type 下的不同租户(如供应商A与B),是ORM行级隔离唯一注入字段 |
| merchant_type | String(50) | NOT NULL | 商家身份类型(多选逗号分隔):PLATFORM / SUPPLIER / DISTRIBUTOR。PLATFORM 互斥;SUPPLIER 和 DISTRIBUTOR 可同时选。决定菜单树加载与路由准入 |
| status | String(20) | DEFAULT 'active' | 部门状态:active / inactive,inactive 对所有用户不可见 |
| create_by | String(32) | 可为空,FK->User.id | 创建人用户ID |
| created_at | DateTime | NOT NULL | 创建时间 |
| updated_at | DateTime | 可为空 | 最后修改时间 |
| deleted_at | DateTime | 可为空 | 软删除时间,非空表示已删除 |
5.5.2 用户表(User)
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | String(32) | PK | 用户唯一标识 |
| name | String(20) | NOT NULL | 姓名 |
| account | String(32) | NOT NULL | 登录账号,同一 tenant_id 内唯一 |
| mobile | String(11) | NOT NULL | 手机号,同一 tenant_id 内唯一 |
| password | String(128) | NOT NULL | 密码,bcrypt 加密存储,禁止明文 |
| String(64) | 可为空 | 邮箱,标准格式校验 | |
| dept_id | String(32) | 可为空,FK->Department.id | 所属部门ID,为空表示未分配(归入"未分配"虚拟部门) |
| status | String(20) | DEFAULT 'normal' | 状态:normal(正常)/ disabled(停用)/ locked(锁定) |
| tenant_id | String(32) | NOT NULL | 租户实例ID,ORM层行级隔离唯一注入字段 |
| merchant_type | String(20) | NOT NULL | 租户类型:PLATFORM / SUPPLIER / DISTRIBUTOR |
| distributor_type | String(20) | 可为空 | 分销商子类型:INDIVIDUAL / B / OTA(单选),仅 merchant_type 含 DISTRIBUTOR 时填写,决定分销商菜单树与子账号权限 |
| supplier_type | String(100) | 可为空 | 供应商子类型(多选,逗号分隔):TICKET / HOTEL / VEHICLE / SPECIALTY / ROUTE,仅 merchant_type 含 SUPPLIER 时填写,至少选1项。决定商品管理菜单、资质上传、订单品类筛选、财务报表维度、分销授权范围、营销活动商品范围(详见5C.1A)。示例:TICKET,HOTEL,VEHICLE 表示该供应商同时经营票务、酒店、车辆三类商品 |
| fail_count | Integer | DEFAULT 0 | 连续登录失败次数,达5次触发锁定 |
| lock_until | DateTime | 可为空 | 锁定到期时间,非空且大于当前时间则禁止登录 |
| last_login_at | DateTime | 可为空 | 最近登录时间 |
| last_login_ip | String(45) | 可为空 | 最近登录IP(兼容IPv6) |
| create_by | String(32) | 可为空,FK->User.id | 创建人用户ID |
| created_at | DateTime | NOT NULL | 创建时间 |
| updated_at | DateTime | 可为空 | 最后修改时间 |
| deleted_at | DateTime | 可为空 | 软删除时间 |
5.5.3 角色表(Role)新增
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | String(32) | PK | 角色唯一标识 |
| name | String(50) | NOT NULL | 角色名称,如"平台管理员" |
| code | String(50) | NOT NULL,UNIQUE | 角色编码,如 R101,同一 tenant_id 内唯一 |
| tenant_id | String(32) | NOT NULL | 租户实例ID |
| merchant_type | String(20) | NOT NULL | 租户类型 |
| data_scope | String(20) | DEFAULT 'self' | 行级数据范围:all(全部)/ dept(本部门)/ self(本人)/ custom(自定义) |
| is_system | Boolean | DEFAULT false | 是否系统预置角色,true 表示不可删除、不可改 code |
| status | String(20) | DEFAULT 'active' | 角色状态:active / inactive |
| description | String(200) | 可为空 | 角色描述 |
| create_by | String(32) | 可为空 | 创建人用户ID |
| created_at | DateTime | NOT NULL | 创建时间 |
| updated_at | DateTime | 可为空 | 最后修改时间 |
| deleted_at | DateTime | 可为空 | 软删除时间 |
5.5.4 角色-权限关联表(5张)新增
RBAC 的多对多关系通过以下5张关联表落地,所有关联表均冗余 tenant_id 用于隔离校验。
| 表名 | 关键字段 | 唯一约束 | 说明 |
|---|---|---|---|
role_menu | role_id, menu_id, tenant_id | UNIQUE(role_id, menu_id) | 角色-菜单多对多,控制菜单权限 |
role_button | role_id, button_code, tenant_id | UNIQUE(role_id, button_code) | 角色-按钮多对多,button_code 如 user:create |
role_sensitive_field | role_id, field_code, level, tenant_id | UNIQUE(role_id, field_code) | 角色-敏感字段配置,level:plaintext/desensitized/hidden |
role_data_custom | role_id, object_type, object_id, tenant_id | UNIQUE(role_id, object_type, object_id) | 角色-自定义数据范围,object_type 见 8.4.5 |
user_role | user_id, role_id, tenant_id | UNIQUE(user_id, role_id) | 用户-角色多对多,支持一人多角色(取权限并集) |
5.5.5 操作日志表(OperationLog)新增
| 字段名 | 类型 | 约束 | 说明 |
|---|---|---|---|
| id | String(32) | PK | 日志唯一标识 |
| operator_id | String(32) | NOT NULL,FK->User.id | 操作人用户ID |
| operator_name | String(50) | NOT NULL | 操作人姓名(冗余便于查询,避免join) |
| tenant_id | String(32) | NOT NULL | 租户实例ID,用于日志隔离查询 |
| merchant_type | String(20) | NOT NULL | 租户类型 |
| operation_type | String(30) | NOT NULL | 操作类型:login/query/create/update/delete/audit/export/reset_pwd/view_plaintext |
| target_type | String(30) | 可为空 | 操作对象类型:user/role/dept/product/order/... |
| target_id | String(32) | 可为空 | 操作对象ID |
| target_desc | String(200) | 可为空 | 操作对象描述(如"用户:张三") |
| before_value | Text | 可为空 | 操作前值(JSON),编辑/审核操作必填 |
| after_value | Text | 可为空 | 操作后值(JSON),编辑/审核操作必填 |
| ip | String(45) | NOT NULL | 操作来源IP(兼容IPv6) |
| user_agent | String(255) | 可为空 | 设备/浏览器信息 |
| result | String(20) | NOT NULL | 操作结果:success / fail |
| is_sensitive | Boolean | DEFAULT false | 是否敏感操作(删除/审核/重置密码/明文查看/导出= true) |
| created_at | DateTime | NOT NULL | 操作时间,索引核心字段 |
5.5.6 ER关系图 新增
erDiagram
DEPARTMENT ||--o{ USER : "1部门N用户(dept_id)"
DEPARTMENT ||--o{ DEPARTMENT : "自关联(parent_id)"
USER ||--o{ OPERATION_LOG : "1用户N日志(operator_id)"
DEPARTMENT {
string id PK
string name
string parent_id FK
string leader_id FK
string tenant_id
string merchant_type
}
USER {
string id PK
string account
string mobile
string dept_id FK
string tenant_id
string merchant_type
string distributor_type
string status
}
USER ||--o{ USER_ROLE : "1用户N角色"
ROLE ||--o{ USER_ROLE : "1角色N用户"
ROLE {
string id PK
string name
string code
string tenant_id
string data_scope
boolean is_system
}
ROLE ||--o{ ROLE_MENU : "1角色N菜单"
ROLE ||--o{ ROLE_BUTTON : "1角色N按钮"
ROLE ||--o{ ROLE_SENSITIVE_FIELD : "1角色N敏感字段"
ROLE ||--o{ ROLE_DATA_CUSTOM : "1角色N自定义范围(custom时)"
USER_ROLE {
string user_id FK
string role_id FK
string tenant_id
}
ROLE_MENU {
string role_id FK
string menu_id FK
string tenant_id
}
ROLE_BUTTON {
string role_id FK
string button_code
string tenant_id
}
OPERATION_LOG {
string id PK
string operator_id FK
string tenant_id
string operation_type
string target_type
text before_value
text after_value
boolean is_sensitive
}
5.5.7 索引设计 新增
| 表名 | 索引名 | 索引字段 | 类型 | 说明 |
|---|---|---|---|---|
| department | idx_dept_tenant | (tenant_id) | NORMAL | 租户内查询部门树(merchant_type为多选逗号分隔,不纳入联合索引) |
| department | idx_dept_parent | (parent_id, sort) | NORMAL | 按父级查询子部门并排序 |
| user | uniq_user_account | (tenant_id, account) | UNIQUE | 同租户内账号唯一 |
| user | uniq_user_mobile | (tenant_id, mobile) | UNIQUE | 同租户内手机号唯一 |
| user | idx_user_dept | (tenant_id, dept_id) | NORMAL | 按部门查询成员 |
| role | uniq_role_code | (tenant_id, code) | UNIQUE | 同租户内角色编码唯一 |
| operation_log | idx_log_query | (tenant_id, created_at, operation_type) | NORMAL | 日志按时间+类型查询 |
| operation_log | idx_log_operator | (operator_id, created_at) | NORMAL | 按操作人查询 |
5.5.8 数据隔离SQL示例(ORM拦截效果) 新增
业务代码原始SQL
SELECT * FROM user WHERE status = 'normal'
ORM拦截后实际执行SQL(自动注入租户+数据权限条件)
平台管理员(data_scope=all):
SELECT * FROM user WHERE status = 'normal' AND tenant_id = 'PLATFORM_001'
供应商商品专员(data_scope=dept,dept_id=D003及其子部门D005,D006):
SELECT * FROM user WHERE status = 'normal' AND tenant_id = 'SUPPLIER_A' AND dept_id IN ('D003','D005','D006')
普通专员(data_scope=self):
SELECT * FROM user WHERE status = 'normal' AND tenant_id = 'SUPPLIER_A' AND create_by = '当前用户ID'
• 删除部门时,必须先确保该部门下
dept_id 关联的用户数为0,否则拒绝删除(返回409冲突)。• 设置部门负责人时,必须校验该用户的
dept_id 等于当前部门ID,否则拒绝操作。• 租户隔离铁律:所有业务表查询必须在ORM层注入
tenant_id 条件(merchant_type 为多选逗号分隔,不支持SQL等值查询,由应用层在菜单加载和路由守卫处校验),禁止业务代码手写跨租户查询。• 负责人特权:用户若为某部门
leader_id,即使其角色 data_scope=self,仍硬性获得该部门及子部门数据查看权限。
5A系统架构图
权限中心模块采用分层架构,从客户端到数据存储共四层。各层职责清晰、单向依赖,权限校验在网关层与业务服务层双重执行。
flowchart TB
subgraph CL["客户端层"]
P1["平台运营后台
Vue2 + ElementUI"]
P2["供应商后台
Vue2 + ElementUI"]
P3["分销商后台
(个体/B端/OTA)"]
end
subgraph GL["网关与认证层"]
GW["API Gateway
路由/限流/IP黑白名单"]
AUTH["JWT 认证服务
Token签发/校验/黑名单(互踢)"]
RBAC["RBAC 权限校验
菜单+按钮+数据+敏感字段"]
end
subgraph BL["业务服务层"]
US["用户服务
User CRUD/锁定/重置"]
RS["角色服务
Role/权限配置"]
DS["组织架构服务
Department树/负责人"]
PS["权限聚合服务
多角色并集/缓存读写"]
LS["审计日志服务
OperationLog异步写入"]
SS["敏感字段服务
脱敏/明文二次验证"]
end
subgraph DL["数据存储层"]
DB[("MySQL
user/role/dept/log表")]
RC[("Redis
权限缓存/Token黑名单")]
end
P1 --> GW
P2 --> GW
P3 --> GW
GW --> AUTH
AUTH --> RBAC
RBAC --> US
RBAC --> RS
RBAC --> DS
PS --> RC
US --> DB
RS --> DB
DS --> DB
LS --> DB
SS --> DB
PS --> DB
5A.1 各层职责说明
| 层级 | 核心组件 | 职责 | 关键约束 |
|---|---|---|---|
| 客户端层 | 三端PC后台 | 渲染UI、发起请求、按钮权限前端控制 | 前端按钮权限为辅助,不可作为唯一防线 |
| 网关认证层 | Gateway + JWT + RBAC | 路由、限流、Token校验、权限预校验 | 所有请求必经网关,禁止直连业务服务 |
| 业务服务层 | 6个微服务 | 业务逻辑、ORM拦截、权限聚合、日志异步写入 | 数据权限在ORM层拦截,对业务代码透明 |
| 数据存储层 | MySQL + Redis | 持久化、权限缓存 | Redis仅缓存权限集合,不存敏感数据明文 |
5B核心业务流程图
本节定义权限中心两大核心闭环流程:权限初始化闭环(新租户上线)和登录授权闭环(用户日常登录)。两个流程均包含异常回流路径。
5B.1 权限初始化闭环(新租户上线)
适用场景:新供应商/分销商入驻通过审核后,系统为其初始化权限数据。
flowchart TD
A([新租户入驻审核通过]) --> B[按merchant_type多选值合并加载预置菜单树]
B --> C{菜单树加载成功?}
C -->|否| ERR1[记录错误,通知运营人工介入]
C -->|是| D[创建顶级部门-租户根部门]
D --> E{部门创建成功?}
E -->|否| ERR2[回滚菜单,通知运营]
E -->|是| F[按merchant_type多选值加载对应身份预置角色模板]
F --> G[创建预置角色并绑定菜单+按钮权限]
G --> H{角色权限绑定成功?}
H -->|否| ERR3[回滚部门+菜单,记录失败]
H -->|是| I[创建管理员账号并绑定主角色]
I --> J{账号创建成功?}
J -->|否| ERR4[回滚角色+部门+菜单]
J -->|是| K[发送初始密码短信]
K --> L{短信发送成功?}
L -->|否| WARN[记录重试队列,运营可手动重发]
L -->|是| M([初始化完成,租户可登录])
ERR1 --> N([异常终止-人工介入])
ERR2 --> N
ERR3 --> N
ERR4 --> N
WARN --> M
5B.2 登录授权闭环(用户日常登录)
适用场景:三端用户日常登录到页面访问的完整闭环。
flowchart TD
A([用户访问后台地址]) --> B{已登录Token有效?}
B -->|是| WORK[跳转工作台]
B -->|否| LOGIN[展示登录页]
LOGIN --> INPUT[输入账号/手机号+密码]
INPUT --> LOCK{账号是否锁定?}
LOCK -->|是,lock_until未到期| ERR1[提示:账号已锁定,剩余N分钟]
ERR1 --> LOGIN
LOCK -->|否| VALIDATE[校验账号密码]
VALIDATE -->|账号不存在| ERR2[提示:账号不存在]
ERR2 --> INPUT
VALIDATE -->|密码错误| ERR3[提示:密码错误,剩余N次]
ERR3 --> FAILCHK{失败次数达上限?}
FAILCHK -->|是| LOCKED[锁定30分钟,写lock_until]
LOCKED --> LOGIN
FAILCHK -->|否| INPUT
VALIDATE -->|校验通过| TENANT[按merchant_type多选值合并路由]
TENANT --> KICK{同账号已有活跃会话?}
KICK -->|是| OLDTOKEN[旧Token加入黑名单,踢掉旧会话]
KICK -->|否| JWT[签发新JWT Token]
OLDTOKEN --> JWT
JWT --> CACHE[加载权限集合并写入Redis]
CACHE --> MENU[按权限渲染菜单树]
MENU --> FIRST{首次登录或重置后?}
FIRST -->|是| CHANGEPWD[强制改密页]
CHANGEPWD --> WORK
FIRST -->|否| WORK
WORK --> PAGE[访问具体页面]
PAGE --> CHECKBTN{按钮权限校验}
CHECKBTN -->|无权限| HIDE[按钮隐藏/禁用]
CHECKBTN -->|有权限| SHOW[按钮可见可操作]
SHOW --> API[调用后端接口]
API --> BACKCHECK{后端二次校验权限}
BACKCHECK -->|无权限| REJECT[返回403]
BACKCHECK -->|有权限| BIZ[执行业务逻辑+ORM拦截数据]
5C全局通用规则
本节定义适用于权限中心所有功能页面的通用规则。功能模块详解中不再重复描述,仅注明"遵循全局规则5C.X"。
5C.1 三端差异对照表
| 维度 | 平台运营 | 供应商 | 个体分销商 | B端分销商 | OTA分销商 |
|---|---|---|---|---|---|
| merchant_type | PLATFORM | SUPPLIER | DISTRIBUTOR | DISTRIBUTOR | DISTRIBUTOR |
| distributor_type | - | - | INDIVIDUAL | B | OTA |
| supplier_type | - | TICKET/HOTEL/VEHICLE/SPECIALTY/ROUTE(多选) | - | - | - |
| 商品管理菜单 | 全部 | 按 supplier_type 多选组合差异显示(详见5C.1A) | - | - | - |
| 登录入口 | 同一登录页,按 merchant_type 多选值合并加载菜单并路由到对应后台(多身份时菜单合并展示) | ||||
| 菜单树 | 平台运营菜单树 | 供应商菜单树 | 个体分销商菜单树(无用户管理) | B端分销商菜单树 | OTA分销商菜单树 |
| 子账号创建 | 支持 | 支持 | 不支持 | 支持 | 支持 |
| 用户管理菜单 | 显示 | 显示 | 隐藏 | 显示 | 显示 |
| 数据范围默认 | 全平台 | 本供应商 | 本人 | 本分销商 | 本分销商 |
| 角色模板 | 6个内置角色 | 3个内置角色 | 1个内置角色 | 3个内置角色 | 4个内置角色(含接口运营) |
| 结算模式 | - | 供货价 | 佣金模式 | 底价模式 | API对接 |
5C.1A 供应商子类型功能影响差异对照表 新增
供应商按经营品类选择子类型(supplier_type 多选,逗号分隔存储如 TICKET,HOTEL,VEHICLE)。supplier_type 不仅决定商品管理子菜单可见性,还影响资质上传、订单品类筛选、财务报表维度、分销授权范围、营销活动商品范围共6个方面,逐一说明如下。
5C.1A.1 商品管理子菜单可见性
仅影响"商品管理"一级菜单下的子菜单可见性,其他菜单(工作台/用户管理/商家管理/分销管理/订单履约/售后处理/营销活动/财务对账/消息中心/系统设置/内容管理)所有供应商均可见。
| 商品管理子菜单 | 显示条件 | 说明 |
|---|---|---|
| 票务资源 | supplier_type 含 TICKET | 景区门票商品管理 |
| 酒店资源 | supplier_type 含 HOTEL | 酒店住宿商品管理 |
| 车辆资源 | supplier_type 含 VEHICLE | 租车/接送商品管理 |
| 特色商品 | supplier_type 含 SPECIALTY | 地方特产商品管理 |
| 线路管理 | supplier_type 含 ROUTE | 旅游线路产品管理 |
| 组合产品(套票/套餐) | supplier_type 含 2个及以上品类 | 需多品类资源才能组合,如票务+酒店组合为套票 |
| 库存价格 | 始终显示 | 所有供应商子类型均可见,管理各品类库存与价格 |
merchant_type 含 SUPPLIER,加载供应商基础菜单树,再将 supplier_type 按逗号拆分为数组,遍历数组逐一匹配上表条件,合并可见子菜单项返回前端。前端路由守卫校验 supplier_type 是否包含对应品类,直接访问无权限的商品路由时跳转 403。多选示例:某供应商
supplier_type=TICKET,HOTEL,VEHICLE,则可见"票务资源+酒店资源+车辆资源+组合产品(含3个品类≥2)+库存价格",不可见"特色商品+线路管理"。
5C.1A.2 资质上传要求(入驻审核环节)
不同品类的供应商法定资质不同,多选时需同时上传所有已选品类对应的资质,平台按品类逐一审核。资质管理页面展示该供应商需维护的全部资质清单。
| supplier_type 含 | 必需资质 | 审核方 | 有效期 |
|---|---|---|---|
TICKET | 营业执照、景区经营许可证、旅行社业务经营许可证(如代售) | 平台运营 | 按证件原件有效期 |
HOTEL | 营业执照、特种行业许可证(住宿业)、消防安全检查合格证、卫生许可证 | 平台运营 | 消防3年/卫生2年/特行1-2年 |
VEHICLE | 营业执照、道路运输经营许可证、车辆运营证、驾驶员从业资格证 | 平台运营 | 道路运输证年审 |
SPECIALTY | 营业执照、食品经营许可证(涉及食品类特产时) | 平台运营 | 食品经营许可证5年 |
ROUTE | 营业执照、旅行社业务经营许可证、责任险保单 | 平台运营 | 旅行社许可证3年/责任险1年 |
supplier_type=TICKET,HOTEL 时,需上传"营业执照(共用)+景区经营许可证+旅行社业务经营许可证+特种行业许可证+消防安全检查合格证+卫生许可证"全部6项资质,缺任一项不可提交入驻申请。资质过期提醒:资质到期前30天/15天/7天分3次推送站内信提醒供应商更新,逾期未更新则对应品类的商品强制下架,直至资质补传审核通过。
5C.1A.3 订单/售后品类筛选
订单和售后单天然按 supplier_id 隔离(供应商只能看到自己的订单),但品类筛选选项受 supplier_type 限制,不展示未经营品类的筛选选项。
| 功能点 | supplier_type 影响 | 示例 |
|---|---|---|
| 订单履约-品类筛选器 | 只展示 supplier_type 含的品类选项 | TICKET,HOTEL 的供应商,筛选器只有"门票订单""酒店订单"两项,无"车辆订单" |
| 订单履约-默认品类 | 默认展示第一个品类的订单列表 | TICKET,HOTEL 的供应商,默认展示"门票订单" |
| 售后处理-品类筛选器 | 同订单逻辑,只展示已经营品类的售后单 | 同上 |
| 订单/售后导出 | 导出报表的品类Sheet页只含已经营品类 | 导出Excel只有"门票订单"和"酒店订单"两个Sheet |
5C.1A.4 财务报表品类维度
财务对账页面按 supplier_type 含的品类分项展示收入明细,不展示未经营品类的收入项(值为0也不展示列)。
| 报表项 | supplier_type 影响 | 示例 |
|---|---|---|
| 收入明细表-品类列 | 只展示已经营品类的收入列 | TICKET,HOTEL 的供应商,报表列:门票收入/酒店收入/合计(无车辆收入列) |
| 结算单-品类分组 | 按已经营品类分组展示结算明细 | 结算单分"门票结算"和"酒店结算"两组 |
| 对账汇总 | 合计行汇总已经营品类,不统计未经营品类 | 合计=门票收入+酒店收入 |
5C.1A.5 分销授权按品类
供应商在"分销管理"中授权分销商时,可指定授权哪些品类的商品给该分销商销售。未被授权的品类商品不会出现在分销商的商品上架列表中。
| 功能点 | supplier_type 影响 | 示例 |
|---|---|---|
| 授权-可授权品类范围 | 授权表单的品类多选框只列出 supplier_type 含的品类 | TICKET,HOTEL 的供应商,授权表单只有"门票""酒店"两个选项 |
| 分销商-可见商品 | 分销商只能上架被授权品类的供应商商品 | 被授权"门票"的分销商,只能上架该供应商的门票商品,不可上架酒店商品 |
| 授权变更 | 追加/收回品类授权即时生效,已上架商品相应可用/下架 | 追加"酒店"授权后,分销商可立即上架该供应商的酒店商品 |
5C.1A.6 营销活动商品范围
供应商创建营销活动(促销/优惠券/满减等)时,参与商品选择器只展示 supplier_type 含的品类的商品,不展示未经营品类的商品。
| 功能点 | supplier_type 影响 | 示例 |
|---|---|---|
| 活动-商品选择器 | 只加载已经营品类的商品列表 | TICKET,HOTEL 的供应商,选择器只有门票和酒店商品可选 |
| 活动-品类筛选 | 筛选器只展示已经营品类 | 同上 |
| 活动-批量添加 | 按品类批量添加参与商品时只可操作已经营品类 | "批量添加所有门票商品"按钮可用,"批量添加所有车辆商品"按钮不显示 |
supplier_type 多选值控制。后端在供应商入驻时确定 supplier_type(平台审核时可修改),后续所有涉及品类过滤的功能模块均读取该字段。供应商如需新增经营品类,需提交品类变更申请,平台审核通过后更新 supplier_type 并同步刷新菜单、资质、订单筛选、财务维度、分销授权、营销范围。多选示例汇总:供应商
supplier_type=TICKET,HOTEL,VEHICLE → 商品菜单可见票务+酒店+车辆+组合+库存;资质需上传票务3项+酒店4项+车辆4项(营业执照共用);订单筛选只有门票/酒店/车辆3个选项;财务报表分3列+合计;分销授权可勾选门票/酒店/车辆3个品类;营销活动可选门票/酒店/车辆3类商品。
5C.2 通用交互规则
| 场景 | 规则 |
|---|---|
| 分页 | 默认每页20条,可选10/20/50/100;分页参数 page(页码从1开始)、page_size;分页响应含 total、list |
| 筛选 | 支持多条件组合筛选;筛选条件变更时重置分页到第1页;URL同步 ?filter=key:value 支持刷新保留 |
| 加载状态 | 列表查询、表单提交均显示 loading 遮罩;按钮点击后立即 disable 防重复提交 |
| 操作确认 | 删除/停用/重置密码/审核等不可逆操作,必须二次确认弹窗(标题+正文+取消/确认按钮) |
| 反馈提示 | 成功:绿色 Message 3秒自动消失;失败:红色 Message 需手动关闭;敏感操作:MessageBox 询问 |
| 批量操作 | 列表选中≥1行时顶部显示批量操作栏;批量操作前必须二次确认并显示影响行数 |
| 空状态 | 无数据时显示空状态插图 + "暂无数据" + 引导操作按钮 |
| 表单校验 | 前端实时校验(blur触发)+ 提交前全量校验;后端返回字段级错误时定位到对应字段红框+提示 |
| 时间展示 | 统一格式 YYYY-MM-DD HH:mm:ss;相对时间展示需鼠标悬停显示绝对时间 |
| 金额展示 | 保留2位小数,前置货币符号;大额(≥10000)千分位分隔 |
5C.3 通用业务规则
- 多租户隔离铁律:所有业务表查询必须注入
tenant_id条件(merchant_type 为多选逗号分隔,由应用层校验),禁止业务代码手写跨租户查询,违反即数据泄露 - 权限并集规则:用户多角色时,菜单/按钮/数据权限取并集;敏感字段取最宽松级别(如角色A脱敏、角色B明文,结果为明文)
- 软删除规则:删除操作一律软删除(设
deleted_at),保留数据关联;超级管理员可在"回收站"查询并恢复,恢复需记录日志 - JWT Token规则:有效期24小时(记住我7天);签发时同时写入Redis白名单;同账号互踢通过旧Token加入Redis黑名单实现
- 权限缓存规则:用户权限集合缓存到Redis,Key=
perm:{user_id},TTL=30分钟;权限变更时主动DEL该Key触发下次请求重新加载 - 创建人留痕:所有业务记录必须填写
create_by,用于"本人数据"权限判定和审计追溯
5C.4 通用异常处理规则
| 异常类型 | HTTP码 | 前端表现 | 后端行为 |
|---|---|---|---|
| 未登录/Token过期 | 401 | 跳转登录页,保留原URL用于登录后跳回 | 不记录日志(高频) |
| 权限不足 | 403 | 红色Message"无权限",记录前端日志 | 记录操作日志,标记为敏感 |
| 租户隔离违规 | 403 | 红色Message"数据不存在"(不暴露隔离规则) | 记录安全日志,告警通知超管 |
| 参数校验失败 | 400 | 字段级红框+错误提示 | 返回字段级错误明细 |
| 业务冲突(如删除部门有成员) | 409 | 红色Message"请先转移成员后再删除" | 返回冲突原因说明 |
| 网络超时 | - | 10秒超时,提示"网络异常,请稍后重试" | 网关层30秒超时,触发限流 |
| 服务器错误 | 500 | 红色Message"系统繁忙,请联系管理员"+错误ID | 记录错误ID到日志,便于追溯 |
5D全局页面流转说明
以表格形式描述权限中心核心页面的路由关系、权限要求和跳转目标,所有路由必须经路由守卫校验 merchant_type 是否包含对应身份 和菜单权限。
| 页面路径 | 对应菜单 | 权限要求 | 入口条件 | 跳转目标 |
|---|---|---|---|---|
/login | - | 无需权限 | 未登录 | 按merchant_type合并路由到工作台(多身份时跳主身份工作台,菜单合并展示) |
/platform/dashboard | 工作台 | menu:dashboard | merchant_type 含 PLATFORM | 待办任务、用户管理、角色管理 |
/platform/user/list | 基础管理-用户账号管理 | menu:user + user:view | merchant_type 含 PLATFORM | 新增弹窗、编辑弹窗、详情抽屉 |
/platform/user/org | 基础管理-组织架构管理 | menu:org + dept:view | merchant_type 含 PLATFORM | 新增部门弹窗、成员管理弹窗 |
/platform/role/list | 基础管理-角色权限管理 | menu:role + role:view | merchant_type 含 PLATFORM | 权限配置页(4个Tab) |
/platform/log/operation | 基础管理-操作日志审计 | menu:log + log:view | merchant_type 含 PLATFORM | 日志详情抽屉 |
/supplier/dashboard | 工作台 | menu:dashboard | merchant_type 含 SUPPLIER | 商品管理、订单管理 |
/supplier/user/list | 用户管理 | menu:user + user:view | merchant_type 含 SUPPLIER | 新增/编辑弹窗(数据范围限本供应商) |
/supplier/role/list | 角色权限管理 | menu:role + role:view | merchant_type 含 SUPPLIER | 权限配置页(仅供应商菜单树) |
/supplier/product/ticket | 商品管理-资源产品-票务资源 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 TICKET | 票务商品列表、新增/编辑弹窗 |
/supplier/product/hotel | 商品管理-资源产品-酒店资源 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 HOTEL | 酒店商品列表、新增/编辑弹窗 |
/supplier/product/vehicle | 商品管理-资源产品-车辆资源 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 VEHICLE | 车辆商品列表、新增/编辑弹窗 |
/supplier/product/specialty | 商品管理-资源产品-特色商品 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 SPECIALTY | 特色商品列表、新增/编辑弹窗 |
/supplier/product/route | 商品管理-线路管理 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 ROUTE | 线路产品列表、新增/编辑弹窗 |
/supplier/product/combo | 商品管理-组合产品-套票/套餐 | menu:product + product:view | merchant_type 含 SUPPLIER, supplier_type 含 2个及以上品类 | 套票/套餐列表、创建向导 |
/supplier/product/inventory-price | 商品管理-库存价格 | menu:product + product:view | merchant_type 含 SUPPLIER(所有子类型) | 库存维护、调价、库存流水 |
/distributor-b/dashboard | 工作台 | menu:dashboard | merchant_type 含 DISTRIBUTOR, distributor_type=B | 选品、采购、订单 |
/distributor-b/user/list | 用户管理 | menu:user + user:view | merchant_type 含 DISTRIBUTOR, distributor_type=B | 新增/编辑弹窗(限本分销商) |
/distributor-ota/user/list | 用户管理 | menu:user + user:view | merchant_type 含 DISTRIBUTOR, distributor_type=OTA | 新增/编辑弹窗(限本分销商) |
/distributor-individual/dashboard | 工作台 | menu:dashboard | merchant_type 含 DISTRIBUTOR, distributor_type=INDIVIDUAL | 分销推广、佣金查看(无用户管理菜单) |
/change-password | - | 已登录 | 首次登录或运营重置后强制跳转 | 改密成功后跳工作台 |
/403 | - | 已登录 | 访问无权限路由时触发 | 返回上一页或工作台 |
/platform/* 路由校验 merchant_type 含 PLATFORM;/supplier/* 校验 merchant_type 含 SUPPLIER;/supplier/product/* 额外校验 supplier_type 是否包含对应品类(详见5C.1A);/distributor-*/* 校验 merchant_type 含 DISTRIBUTOR + 对应 distributor_type。校验失败跳转 403 页。个体分销商 (distributor_type=INDIVIDUAL) 强制隐藏 /distributor-*/user/* 所有用户管理路由。供应商商品路由按 supplier_type 多选值校验,如 supplier_type=TICKET,HOTEL 的供应商访问 /supplier/product/vehicle 时跳转 403(因不含 VEHICLE)。多身份商家(merchant_type=SUPPLIER,DISTRIBUTOR)可同时访问 /supplier/* 和 /distributor-*/* 路由,菜单合并展示。
6登录与账号安全
登录与账号安全模块是三端(平台运营后台、供应商后台、分销商后台)的公共入口,确保用户身份合法性与账号安全性。
6.1 账号密码登录
6.1.1 业务逻辑
- 用户访问PC端后台地址,未登录状态下自动跳转至登录页
- 登录方式支持手机号+密码或账号名+密码两种
- 系统根据用户所属的租户类型(PLATFORM/SUPPLIER/DISTRIBUTOR)自动判断进入哪个后台
- 首次登录(密码为初始密码或运营重置后的密码)强制跳转修改密码页
- 登录成功后生成JWT Token,有效期24小时,支持"记住我"(7天)
6.1.2 交互逻辑
flowchart TD
START([用户访问后台]) --> CHECK{已登录?}
CHECK -->|是| DASH[跳转工作台]
CHECK -->|否| LOGIN[展示登录页]
LOGIN --> INPUT[输入账号/手机号+密码]
INPUT --> VALIDATE{校验账号密码}
VALIDATE -->|账号不存在| ERR1[提示:账号不存在]
ERR1 --> INPUT
VALIDATE -->|密码错误| ERR2[提示:密码错误,剩余N次]
ERR2 --> INPUT
VALIDATE -->|账号锁定| ERR3[提示:账号已锁定,请XX分钟后重试]
VALIDATE -->|校验通过| FIRST{首次登录?}
FIRST -->|是| CHANGE_PWD[强制修改密码页]
CHANGE_PWD --> DASH
FIRST -->|否| DASH
6.1.3 规则约束
| 字段 | 类型 | 规则 | 错误提示 |
|---|---|---|---|
| 账号/手机号 | 文本 | 必填;账号为2-32位字母数字组合;手机号为11位手机号 | 请输入账号或手机号 |
| 密码 | 密码 | 必填;6-32位;支持字母、数字、特殊字符 | 请输入密码 |
| 记住我 | 复选框 | 可选;默认未勾选 | - |
6.1.4 边界与异常
- 连续密码错误锁定:连续5次密码错误后自动锁定账号,锁定时间30分钟,由运营人员在用户管理中手动解锁或等待自动解锁
- 账号停用:已停用账号登录时提示"账号已停用,请联系管理员"
- 多设备登录:同一账号在新设备登录时,旧设备Token失效(互踢机制)
- 网络异常:登录请求超时(10秒)时提示"网络异常,请稍后重试",保留已填写的账号
6.1.5 状态说明表
登录功能的用户账号状态与页面表现对照如下,状态覆盖登录前、登录中、登录后全链路,共 8 种状态。
| 状态 | 页面表现 | 触发条件 | 允许操作 | 备注 |
|---|---|---|---|---|
| 未登录 | 访问任意后台路由,全局路由守卫拦截,重定向至 /login;登录页展示账号/手机号+密码输入框、"记住我"复选框、忘记密码链接、测试账号折叠区 | 用户首次打开后台地址 / Token 为空 / Token 已过期 / Token 被互踢失效 | 输入账号密码登录、跳转忘记密码页、切换测试账号 | 路由守卫白名单:/login、/forgot-password、/reset-password |
| 登录中(加载) | 登录按钮显示 loading 图标并禁用;输入框只读;页面不响应重复点击 | 用户点击"登录"按钮后,请求未返回前 | 无(等待响应) | 请求超时 10 秒自动取消 loading 状态 |
| 密码错误(未锁定) | 密码输入框下方红字提示"账号或密码错误,剩余 N 次尝试机会";密码框清空并获焦;剩余次数 ≤ 1 时文案变红加粗 | 账号存在但密码与库中 hash 不匹配;当日连续错误次数 < 5 | 重新输入密码、点击登录、跳转忘记密码 | 错误次数按 user.login_fail_count 累计,0 点(Asia/Shanghai)自动归零 |
| 账号锁定 | 登录按钮置灰;账号输入框红字提示"账号已锁定,请于 HH:mm 后重试或联系管理员解锁";提供"联系管理员"跳转 | 连续密码错误达 5 次 / 运营在用户管理手动标记锁定 / 安全风控触发 | 仅可联系管理员解锁、等待 30 分钟自动解锁 | 解锁后 login_fail_count 清零;解锁前任何密码输入均返回"账号已锁定" |
| 账号停用 | 提示"账号已停用,请联系管理员";不显示剩余次数;登录按钮恢复可点 | user.status = DISABLED(运营在用户管理停用) | 重新输入账号 / 联系管理员 | 停用账号不计入错误次数累计 |
| 首次登录(待改密) | 登录成功后不进工作台,强制跳转 /change-password 页;页面提示"检测到初始密码/重置密码,请修改后继续使用";仅显示改密表单 | user.must_change_password = true(首次登录 / 运营重置后 / 密码过期 90 天) | 提交新密码(输入原密码+新密码+确认新密码);取消则登出 | 改密成功后 must_change_password 置 false,刷新 Token,跳工作台 |
| 登录成功 | 隐藏 loading;Toast 成功提示"登录成功";按 merchant_type 合并路由到工作台首页(多身份时按优先级 PLATFORM > SUPPLIER > DISTRIBUTOR 跳主身份工作台,但菜单合并展示所有身份的菜单组):仅PLATFORM→/platform/dashboard、仅SUPPLIER→/supplier/dashboard、仅DISTRIBUTOR→/distributor-b/dashboard(B)/distributor-ota/dashboard(OTA)/distributor-individual/dashboard(INDIVIDUAL)、SUPPLIER,DISTRIBUTOR→/supplier/dashboard(菜单含供应商组+分销商组) |
账号密码校验通过 + 非首次登录 + 账号未停用 + 未锁定 | 正常使用后台;右上角展示用户头像/姓名/角色/租户;可登出 | Token 有效期 24h,勾选"记住我"为 7 天;写入 user.last_login_at |
| 多设备互踢 | 旧设备任意接口返回 401 token_kicked;前端全局拦截弹框"您的账号在另一设备登录,如非本人操作请修改密码";3 秒后自动跳 /login | 同一账号在新设备登录成功,触发旧 Token 失效 | 点击"重新登录"跳 /login、点击"修改密码"跳 /forgot-password | 互踢针对相同账号(user_id),不分 merchant_type;同账号在新设备登录即踢旧会话 |
6.1.6 异常处理
登录功能异常处理包含异常处理流程图与异常处理表两部分,覆盖网络层、业务层、安全层全部异常分支及恢复路径。
6.1.6.1 异常处理流程图
flowchart TD
START([用户点击登录]) --> REQ[发起 POST /api/auth/login]
REQ --> NET{网络响应?}
NET -->|超时/断网| NET_ERR[前端提示: 网络异常, 请稍后重试]
NET_ERR --> RETRY{用户重试?}
RETRY -->|是| REQ
RETRY -->|否| END1([结束, 留在登录页])
NET -->|响应返回| BIZ{业务码?}
BIZ -->|200 成功| CHECK_FIRST{首次登录?}
CHECK_FIRST -->|是| REDIRECT_PWD[跳转改密页]
CHECK_FIRST -->|否| REDIRECT_DASH[跳转工作台]
BIZ -->|40001 账号不存在| E1[提示: 账号不存在]
E1 --> INPUT[等待用户重新输入]
BIZ -->|40002 密码错误| E2[提示: 密码错误, 剩余N次]
E2 --> CHECK_LOCK{剩余次数=0?}
CHECK_LOCK -->|是| LOCK[账号锁定 30 分钟]
LOCK --> INPUT
CHECK_LOCK -->|否| INPUT
BIZ -->|40003 账号锁定| E3[提示: 账号已锁定, 请HH:mm后重试]
E3 --> INPUT
BIZ -->|40004 账号停用| E4[提示: 账号已停用, 联系管理员]
E4 --> INPUT
BIZ -->|40005 租户已禁用| E5[提示: 租户已被禁用, 联系平台]
E5 --> INPUT
BIZ -->|40101 旧Token被踢| E6[弹框: 账号在另一设备登录]
E6 --> LOGOUT[清除本地Token]
LOGOUT --> REDIRECT_LOGIN[跳转登录页]
BIZ -->|500 服务器异常| E7[提示: 服务异常, 请稍后重试]
E7 --> INPUT
INPUT --> START
6.1.6.2 异常处理表
| 异常场景 | 前端表现 | 后端行为 | 处理方案 |
|---|---|---|---|
| 网络超时/断网 | 10 秒未响应,登录按钮恢复可点;Toast 提示"网络异常,请稍后重试";账号输入框保留已填值 | 请求未到达后端或后端未在 10 秒内响应;不累计 login_fail_count | 用户可重试登录;连续 3 次超时引导用户检查网络或联系运维 |
| 账号不存在 | 账号输入框下方红字"账号不存在";账号框获焦并选中已有值 | 按 account/mobile 查询无记录;返回 40001;不累计错误次数(防爆破枚举) | 用户重新输入账号;或引导跳转注册/联系管理员开通 |
| 密码错误(未达锁定阈值) | 密码框下方红字"账号或密码错误,剩余 N 次机会";密码框清空获焦;N≤1 时文案变红加粗 | 密码 hash 比对失败;login_fail_count+1;剩余次数 = 5 - fail_count;返回 40002 + remain_count | 用户重新输入密码;或点击"忘记密码"走短信验证码重置流程 |
| 密码错误达阈值锁定 | 提示"账号已锁定,请于 HH:mm 后重试";登录按钮置灰;提供"联系管理员"链接 | login_fail_count 达 5;user.locked_until = now + 30min;返回 40003 + unlock_time | 等待 30 分钟自动解锁(解锁时 fail_count 清零);或运营在用户管理手动解锁 |
| 账号已被停用 | 提示"账号已停用,请联系管理员";不显示剩余次数 | user.status = DISABLED;返回 40004;不累计错误次数 | 用户联系所属租户管理员;管理员在用户管理重新启用后可登录 |
| 租户被禁用 | 提示"您的企业账号已被平台禁用,请联系平台运营";提供平台客服联系方式 | 按 user.tenant_id 查 tenant 表 status=DISABLED;返回 40005;写 operation_log | 仅可由平台运营在租户管理中重新启用;启用后用户可正常登录 |
| 多设备登录被踢下线 | 全局 401 拦截;弹框"您的账号在另一设备登录,如非本人请修改密码";3 秒后自动跳 /login | 新设备登录成功时旧 Token 标记失效;旧设备下次请求返回 40101 token_kicked | 用户重新登录或走忘记密码;如确认非本人操作应立即改密并通知管理员 |
| Token 过期 | 任意接口返回 401 token_expired;静默清本地 Token;跳 /login(URL 携带 redirect 参数) | JWT 解析 exp 超时;返回 401 + reason=token_expired | 用户重新登录后跳回原 redirect 路由;"记住我"用户 7 天内免登 |
| 服务器内部异常 | Toast 提示"服务异常,请稍后重试";登录按钮恢复可点 | 后端未捕获异常或 DB 连接失败;返回 500;写 error_log 并告警 | 用户稍后重试;运维收到告警后 5 分钟内介入处理 |
6.2 修改密码/忘记密码/重置密码
6.2.1 业务逻辑
提供三种密码变更路径:
- 用户自助修改密码:登录后在个人中心修改,需输入原密码+新密码+确认新密码
- 忘记密码重置:未登录状态下,通过手机号+短信验证码重置密码
- 运营强制重置:平台/供应商/分销商管理员在用户管理中强制重置某用户密码,重置后用户下次登录强制修改
6.2.2 交互逻辑
flowchart TD
subgraph 自助修改["自助修改密码"]
A1[个人中心-账号安全] --> A2[输入原密码]
A2 --> A3[输入新密码]
A3 --> A4[确认新密码]
A4 --> A5{原密码正确?}
A5 -->|否| A6[提示原密码错误]
A6 --> A2
A5 -->|是| A7[修改成功,重新登录]
end
subgraph 忘记密码["忘记密码"]
B1[登录页-忘记密码] --> B2[输入手机号]
B2 --> B3[获取短信验证码]
B3 --> B4[输入验证码]
B4 --> B5{验证码正确?}
B5 -->|否| B6[提示验证码错误]
B6 --> B4
B5 -->|是| B7[设置新密码]
B7 --> B8[重置成功,跳转登录]
end
subgraph 运营重置["运营强制重置"]
C1[用户管理-用户列表] --> C2[选择用户-重置密码]
C2 --> C3[二次确认弹窗]
C3 --> C4[生成随机密码或自定义密码]
C4 --> C5[重置成功,用户下次登录强制修改]
end
6.2.3 规则约束
| 字段 | 规则 |
|---|---|
| 原密码 | 必填;必须与实际密码一致 |
| 新密码 | 必填;8-32位;必须同时包含字母+数字;不能与最近3次历史密码相同 |
| 确认新密码 | 必填;必须与新密码完全一致 |
| 短信验证码 | 必填;6位数字;有效期5分钟;每个手机号每天最多发送10次 |
6.3 单点登录与防暴力破解
6.3.1 业务逻辑
- 同账号互踢:同一账号在同一端(PC端)只能有一个活跃会话,新登录自动踢掉旧会话
- 失败次数锁定:连续5次登录失败后锁定30分钟,支持运营手动解锁
- 登录日志记录:记录每次登录的时间、IP地址、设备信息、登录结果(成功/失败)
- 异常登录提醒:检测到异地登录或非常用设备登录时,向用户发送站内信/短信提醒
6.3.2 规则约束
| 配置项 | 默认值 | 可调范围 | 说明 |
|---|---|---|---|
| 最大失败次数 | 5次 | 3-10次 | 连续登录失败达到此次数后触发锁定 |
| 锁定时长 | 30分钟 | 15-1440分钟 | 账号锁定后自动解锁的等待时间 |
| 会话有效期 | 24小时 | 1-168小时 | JWT Token有效期,"记住我"模式下为7天 |
| 最大并发会话 | 1个 | 1-5个 | 同一账号同一端最大同时在线数 |
7用户管理
用户管理模块提供组织内用户账号的全生命周期管理,包括用户创建、编辑、停用、锁定、密码重置等操作。该模块在平台运营后台、供应商后台、B端分销商后台、OTA分销商后台中均有体现,但数据范围严格隔离。
7.1 用户账号管理
7.1.1 业务逻辑
- 用户列表展示当前租户下的所有用户账号,支持分页、筛选、排序
- 新增用户时,由管理员填写基本信息并分配角色,系统自动生成初始密码(随机8位,含字母+数字)
- 编辑用户时,可修改基本信息、所属部门、角色分配,不可修改租户类型
- 停用用户后,该用户无法登录,但历史数据保留
- 锁定用户后,该用户无法登录,需管理员手动解锁(区别于密码错误导致的自动锁定)
- 删除用户为软删除,标记删除状态,保留数据关联,超级管理员可恢复
7.1.2 页面原型
7.1.3 交互逻辑
- 点击"新增用户"按钮,弹出新增用户弹窗(Form类型,宽度560px)
- 点击"编辑",弹出编辑用户弹窗,回显当前用户信息
- 点击"重置密码",弹出确认弹窗,确认后生成随机密码并显示(仅显示一次)
- 点击"停用",弹出确认弹窗,确认后用户状态变为"停用",无法登录
- 点击"锁定",用户状态变为"锁定",需手动解锁
- 批量操作:选中多个用户后,顶部显示批量操作栏(批量停用、批量删除)
7.1.4 规则约束
| 字段 | 类型 | 规则 |
|---|---|---|
| 姓名 | 文本 | 必填;2-20位;支持中文、英文、数字 |
| 账号 | 文本 | 必填;4-32位;字母开头,支持字母、数字、下划线;同一租户内唯一 |
| 手机号 | 文本 | 必填;11位手机号;同一租户内唯一 |
| 邮箱 | 文本 | 选填;标准邮箱格式 |
| 所属部门 | 下拉树 | 选填;从组织架构树中选择 |
| 角色 | 多选 | 必填;至少选择一个角色;支持多角色(取权限并集) |
| 状态 | 单选 | 默认"正常";选项:正常/停用 |
7.1.5 权限逻辑
- 平台管理员可管理平台运营后台的所有用户
- 供应商管理员可管理本供应商下的所有用户,不可查看其他供应商的用户
- B端/OTA分销商管理员可管理本分销商下的所有用户
- 个体分销商不显示"用户管理"菜单,不可创建子账号
- 用户只能编辑/删除自己下级创建的用户,不能操作同级或上级创建的用户(超级管理员除外)
7.2 组织架构管理
组织架构以部门树形式维护,是用户归属和数据权限(本部门数据)的基础。以下内容为本次深化重点。
7.2.1 业务逻辑
- 组织架构以部门树形式维护,支持无限层级(建议不超过5层以保证性能)。
- 每个部门可设置部门负责人,负责人自动获得该部门及子部门的数据查看权限。
- 用户必须归属于一个部门(如未分配,系统自动归入"未分配"虚拟部门)。
- 删除部门时,若该部门下存在用户或子部门,提示"请先转移部门成员/子部门后再删除",并阻止操作。
- 支持部门拖拽排序和层级调整(通过修改
parent_id和sort实现)。
7.2.2 页面原型
7.2.3 规则约束(深化补充)
| 操作 | 前置校验条件 | 业务规则 |
|---|---|---|
| 新增部门 | 父部门必须存在 | 部门名称 2-30位,同一父级下唯一;sort 默认为0 |
| 编辑部门(更换上级) | 新上级不能为自身或自身的子部门 | 需递归校验部门树,防止循环引用 |
| 删除部门 | 部门下 dept_id 关联的用户数为0;子部门列表为空 |
若任一条件不满足,弹窗提示并禁用删除按钮 |
| 设置/变更部门负责人 | 所选用户必须属于本部门(user.dept_id === currentDeptId) |
一个部门仅能有一个负责人;旧负责人自动取消标记 |
| 从部门移除成员 | 若成员是部门负责人,必须先行取消负责人身份 | 移除后,该用户的 dept_id 置为 null(归入未分配) |
7.2.4 数据流转与接口依赖(新增详细说明)
接口交互时序
- 加载部门树:前端请求
GET /api/dept/tree,后端返回当前租户下的完整部门树结构(包含id, name, parentId, leaderId, sort, children)。 - 新增部门:
POST /api/dept提交{ name, parentId, leaderId, sort }→ 后端生成ID,写入数据库,更新父级children集合(逻辑维护),返回新节点。 - 编辑部门:
PUT /api/dept/{id}→ 后端校验新parentId合法性,若变更上级,需执行"从原父级移除 → 追加至新父级"的原子操作,同时更新sort。 - 删除部门:
DELETE /api/dept/{id}→ 后端先查询User表中dept_id = id的数量,以及子部门数量。若 >0,返回错误码409(冲突),提示转移;否则执行软删除。 - 加载部门成员:
GET /api/dept/{id}/members→ 查询User表中dept_id = id的用户列表。 - 添加成员到部门:
PUT /api/user/{userId}/dept→ 更新该用户的dept_id为当前部门ID。 - 移除成员:
PUT /api/user/{userId}/dept→ 将该用户的dept_id置为null。 - 设置负责人:
PUT /api/dept/{id}/leader→ 后端校验userId的dept_id是否等于id,若是则更新leader_id,否则返回400错误。
7.2.5 业务操作顺序规则(新增)
1. 先建部门:创建顶级部门及子部门树,确保部门数据存在。
2. 再建角色:创建角色并配置菜单/按钮/数据权限(此时可勾选"本部门数据",但需依赖部门结构存在)。
3. 最后建用户:创建用户时,必须选择所属部门(下拉数据源为步骤1的部门树)和分配角色(下拉数据源为步骤2的角色列表)。
删除顺序则严格相反: 先移除用户 → 再删除角色(可选)→ 最后清空部门后才能删除部门。
8角色权限(权限中心)
角色权限模块是整个权限中心的核心,采用RBAC(基于角色的访问控制)+ 数据权限的混合模型,支持菜单权限、按钮权限、行级数据权限、列级敏感字段权限四层控制,确保不同角色在不同场景下的最小权限原则。
8.1 权限模型架构
flowchart TB
subgraph 用户层["用户层"]
U1[用户A]
U2[用户B]
end
subgraph 角色层["角色层"]
R1[角色:平台管理员]
R2[角色:商家运营]
R3[角色:财务专员]
end
subgraph 权限层["权限层"]
M[菜单权限]
B[按钮权限]
D[行级数据权限]
F[列级敏感字段权限]
end
subgraph 资源层["资源层"]
RES1[菜单/页面]
RES2[按钮/操作]
RES3[数据行]
RES4[数据列/字段]
end
U1 --> R1
U2 --> R2
R1 --> M
R1 --> B
R1 --> D
R1 --> F
R2 --> M
R2 --> B
R2 --> D
R3 --> M
M --> RES1
B --> RES2
D --> RES3
F --> RES4
8.2 菜单权限
8.2.1 业务逻辑
- 菜单权限控制用户登录后左侧导航栏可见的菜单项
- 菜单树按端类型隔离:平台运营后台、供应商后台、分销商后台各有独立的菜单树
- 菜单支持三级层级:一级菜单 → 二级菜单 → 三级菜单
- 角色与菜单的绑定关系为多对多:一个角色可绑定多个菜单,一个菜单可被多个角色绑定
- 父子菜单联动:选中父菜单自动全选子菜单;取消父菜单自动取消所有子菜单;子菜单部分选中时父菜单为半选状态
8.2.2 页面原型
8.2.3 规则约束
- 菜单树按端类型(PLATFORM/SUPPLIER/DISTRIBUTOR)隔离,不同端登录后加载对应菜单树
- 菜单项包含:菜单ID、菜单名称、父菜单ID、菜单路径、菜单图标、排序、状态(启用/禁用)
- 禁用状态的菜单对所有用户不可见,无论角色是否授权
- 若用户没有任何角色,或角色未绑定任何菜单,登录后左侧导航栏为空,页面提示"暂无权限,请联系管理员"
8.3 按钮权限
8.3.1 业务逻辑
- 按钮权限控制页面内具体操作的可见性与可用性
- 按钮权限与菜单权限关联:只有拥有父菜单权限的角色,才能配置该菜单下的按钮权限
- 按钮权限类型包括:新增、编辑、删除、审核、导出、导入、重置密码、停用/启用、锁定/解锁等
- 前端根据用户按钮权限动态渲染页面:无权限的按钮隐藏或禁用(建议隐藏,避免界面冗余)
8.3.2 按钮权限编码清单(完整版,7大模块) 深化
按钮权限编码格式统一为 模块:操作,同一模块的按钮编码前缀必须一致。超级管理员(is_system=true 的角色)自动拥有全部编码,无需单独配置。以下清单与前端 RoleManage.vue 的 initBtnPerms 完全对齐。
① 用户管理模块(user:*)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
user:view | 查看用户列表 | 用户管理页可见性 | 所有可访问用户管理的角色 |
user:create | 新增用户 | 用户管理页-新增用户按钮 | 平台/供应商/分销商管理员 |
user:edit | 编辑用户 | 用户管理页-编辑按钮 | 平台/供应商/分销商管理员 |
user:delete | 删除用户(软删除) | 用户管理页-删除按钮 | 仅超管/平台管理员 |
user:resetPwd | 重置密码 | 用户管理页-重置密码按钮,敏感操作 | 平台/供应商/分销商管理员 |
user:export | 导出用户 | 用户管理页-导出按钮,强制脱敏 | 仅超管/平台管理员 |
user:lock | 锁定/解锁用户 | 用户管理页-锁定/解锁按钮 | 平台/供应商/分销商管理员 |
user:enable | 停用/启用用户 | 用户管理页-停用/启用按钮 | 平台/供应商/分销商管理员 |
② 角色管理模块(role:*)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
role:view | 查看角色列表 | 角色管理页可见性 | 所有可访问角色管理的角色 |
role:create | 新增角色 | 角色管理页-新增角色按钮 | 平台/供应商/分销商管理员 |
role:edit | 编辑角色 | 角色管理页-编辑按钮 | 平台/供应商/分销商管理员 |
role:delete | 删除角色(仅非系统角色) | 角色管理页-删除按钮 | 仅超管/平台管理员 |
role:assignPerm | 配置角色权限 | 角色管理页-权限配置按钮(4个Tab:菜单/按钮/数据/敏感字段) | 平台/供应商/分销商管理员 |
③ 组织架构模块(dept:*)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
dept:view | 查看部门树 | 组织架构管理页可见性 | 所有可访问组织架构的角色 |
dept:create | 新增部门 | 组织架构页-新增部门按钮 | 平台/供应商/分销商管理员 |
dept:edit | 编辑部门(含改上级) | 组织架构页-编辑按钮,改上级需校验防循环引用 | 平台/供应商/分销商管理员 |
dept:delete | 删除部门(需先转移成员/子部门) | 组织架构页-删除按钮 | 仅超管/平台管理员 |
dept:leader | 设置/取消部门负责人 | 成员列表-设为负责人按钮,自动获得本部门数据权限 | 平台/供应商/分销商管理员 |
dept:member | 管理部门成员(添加/移除) | 成员列表-添加成员/移除按钮 | 平台/供应商/分销商管理员 |
④ 操作日志模块(log:*)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
log:view | 查看操作日志 | 操作日志页可见性,按租户隔离查询 | 审计员/超管/平台管理员 |
log:export | 导出操作日志 | 操作日志页-导出按钮,敏感操作 | 仅审计员/超管 |
⑤ 商品管理模块(product:*,后续商品PRD细化)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
product:view | 查看商品 | 商品列表页可见性 | 商品专员及以上 |
product:create | 新增商品 | 商品管理页-新增按钮 | 供应商商品专员 |
product:edit | 编辑商品 | 商品管理页-编辑按钮 | 供应商商品专员 |
product:audit | 审核商品 | 商品审核页-通过/驳回按钮,敏感操作 | 平台商品运营 |
product:shelf | 上架/下架商品 | 商品管理页-上架/下架按钮 | 供应商商品专员 |
⑥ 订单管理模块(order:*,后续订单PRD细化)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
order:view | 查看订单 | 订单列表页可见性 | 订单专员及以上 |
order:audit | 审核订单 | 订单审核页-通过/驳回按钮,敏感操作 | 平台订单运营 |
order:refund | 退款处理 | 订单详情-退款按钮,敏感操作,需二次确认 | 平台客服/财务 |
order:export | 导出订单 | 订单列表-导出按钮 | 平台订单运营/财务 |
⑦ 财务管理模块(finance:*,后续财务PRD细化)
| 编码 | 按钮名称 | 典型应用场景 | 默认角色 |
|---|---|---|---|
finance:view | 查看财务 | 财务列表页可见性 | 财务专员及以上 |
finance:transfer | 打款操作 | 财务页-批量打款按钮,敏感操作,需二次确认+审批 | 平台财务专员 |
finance:reconcile | 对账 | 财务页-对账按钮 | 平台财务专员 |
finance:export | 导出财务数据 | 财务页-导出按钮,强制脱敏 | 平台财务专员 |
coupon:*),再开发对应按钮;②编码一经发布不可修改(影响已配置数据),仅可停用;③敏感操作(删除/审核/重置密码/打款/退款/导出/明文查看)的编码在日志中标记 is_sensitive=true。
8.3.3 权限逻辑
- 按钮权限编码格式为
模块:操作,如user:create - 前端在页面加载时获取当前用户的按钮权限列表,渲染时判断按钮是否在列表中
- 后端接口同样需要校验按钮权限,防止前端绕过(双层校验)
- 超级管理员自动拥有所有按钮权限,无需单独配置
8.4 行级数据权限
8.4.1 业务逻辑
- 行级数据权限控制用户可见的数据行范围,适用于列表查询场景
- 数据权限范围分为四种:
- 全部数据:可查看本租户下的所有数据(如平台管理员)
- 本部门数据:可查看用户所属部门及子部门的数据
- 本人数据:仅可查看自己创建或负责的数据
- 自定义范围:可查看指定对象的数据(如指定供应商、指定分销商)
- 数据权限在ORM层拦截,自动拼接SQL条件,对业务代码透明
8.4.2 数据权限范围详解
| 范围类型 | 说明 | 适用场景 |
|---|---|---|
| 全部数据 | 不限制数据范围,可查看本租户下所有数据 | 平台管理员、供应商管理员、分销商管理员 |
| 本部门数据 | 仅可查看用户所属部门及所有子部门的数据 | 部门主管、团队协作场景 |
| 本人数据 | 仅可查看create_by = 当前用户ID的数据 | 普通专员、个人负责的业务数据 |
| 自定义范围 | 管理员指定该角色可查看的数据对象范围 | 平台运营查看指定供应商的数据 |
8.4.3 "本部门数据"的实现逻辑(新增)
- 当角色配置的数据范围为 "本部门数据" 时,系统在ORM层执行数据查询时,自动执行以下逻辑:
- 获取当前用户的
dept_id。 - 递归查询部门树,获取该部门下所有子部门的ID集合(包含自身)。
- 在SQL查询条件中自动拼接
WHERE dept_id IN (id1, id2, ...)或WHERE create_by_dept IN (...)。
- 获取当前用户的
- 负责人特权:若当前用户是某个部门的负责人,系统自动赋予其该部门及所有子部门的数据查看权限,无论其角色如何配置(硬性逻辑)。
- 多角色并集:若用户拥有多个角色,且其中一个角色为"全部数据",另一个为"本部门数据",则最终权限取并集(即"全部数据")。
8.4.4 权限逻辑
- 数据权限与角色绑定,一个角色对应一个数据权限范围
- 若用户拥有多个角色,数据权限取并集(最大范围)
- 数据权限仅影响查询操作,不影响新增、编辑、删除(这些由按钮权限控制)
- 自定义范围支持按对象类型(供应商、分销商、商品)配置多个对象ID
8.4.5 自定义范围对象类型枚举 深化
当角色 data_scope=custom 时,通过 role_data_custom 表配置可查看的数据对象。object_type 必须从以下枚举中选择,禁止新增未定义类型。
| object_type | object_id 含义 | 典型场景 | 配置规则 |
|---|---|---|---|
supplier | 供应商ID(对应 supplier.id) | 平台运营查看指定供应商的数据 | 可配置多个,查询时 WHERE supplier_id IN (...) |
distributor | 分销商ID(对应 distributor.id) | 平台/供应商查看指定分销商的订单、佣金 | 可配置多个,B端/OTA可选,个体不可选 |
product | 商品SPU ID | 商品专员查看指定商品的销售数据 | 建议不超过100个,超过建议改用分类授权 |
order | 订单ID | 客服查看指定订单的处理进度 | 仅用于临时授权,不推荐长期配置 |
contract | 合同ID | 法务查看指定合同的履行情况 | 仅法务/超管可配置 |
category | 商品分类ID | 商品专员查看某分类下所有商品 | 支持父子分类继承(含子分类) |
WHERE object_id IN (该角色配置的ID集合);③未配置任何 object_id 的 custom 角色,查询结果为空(防止误配置导致全量泄露)。
8.4.6 权限缓存策略(Redis) 新增
为避免每次请求查询DB导致性能问题,用户权限集合缓存到 Redis。缓存对业务代码透明,由权限聚合服务统一读写。
缓存Key与结构
Redis Key 设计
perm:{user_id},例如 perm:U001023
缓存结构(JSON Value)
{"menus":["dashboard","user_list","role_list",...],"buttons":["user:create","user:edit","role:view",...],"data_scope":"dept","custom_objects":{"supplier":["S001","S002"]},"sensitive_fields":{"mobile":"desensitized","idCard":"hidden"},"dept_id":"D003","leader_depts":["D003","D005"]}
TTL
30分钟,到期自动失效,下次请求重新从DB加载
缓存读取流程
flowchart TD
A([请求到达,需校验权限]) --> B[查Redis Key=perm:user_id]
B --> C{缓存命中?}
C -->|是| D[直接使用缓存的权限集合]
C -->|否,未命中或已失效| E[查DB聚合权限]
E --> F[多角色并集计算]
F --> G[写入Redis,TTL=30分钟]
G --> D
D --> H([返回权限集合用于校验])
缓存失效时机
| 触发场景 | 失效Key | 原因 |
|---|---|---|
| 用户登录成功 | perm:{user_id} | 防止旧权限残留,强制重新加载 |
| 角色权限变更(菜单/按钮/数据/敏感字段) | 所有绑定该角色的 perm:{user_id} | 权限已变更,旧缓存失效 |
| 用户角色绑定变更(增减角色) | perm:{user_id} | 角色集合变化,权限需重新聚合 |
| 用户部门变更(dept_id 改变) | perm:{user_id} | 部门数据权限范围变化 |
| 用户被设为部门负责人 | perm:{user_id} | 新增 leader_depts 特权数据 |
| 运营手动刷新权限 | 指定 perm:{user_id} | 紧急修复权限配置错误时使用 |
| TTL到期 | 自动失效 | 被动失效,下次请求重新加载 |
8.4.7 权限变更审批流 新增
高风险权限变更需经审批流,防止运营误操作或恶意提权。审批流仅适用于数据范围从窄放宽的变更(如 self→all、dept→all、custom→all),窄范围内部变更不触发审批。
flowchart TD
A([运营发起权限变更]) --> B{变更是否放宽数据范围?}
B -->|否,如self到dept| DIRECT[直接生效,失效缓存]
B -->|是,如dept到all| C[角色状态置为pending]
C --> D[通知直属上级审批]
D --> E{审批结果}
E -->|通过| F[更新角色权限]
F --> G[失效相关用户缓存]
G --> H[记录变更日志 before/after]
H --> I([变更生效])
E -->|驳回| J[恢复角色原状态active]
J --> K[通知发起人,记录驳回原因]
K --> L([变更取消])
E -->|超时未处理,72小时| M[自动驳回,恢复原状态]
M --> L
审批规则
| 规则项 | 规则 |
|---|---|
| 审批触发条件 | data_scope 从窄放宽(self→dept、self→all、dept→all、custom→all) |
| 审批人 | 发起人的直属上级;若发起人为超管,则由另一超管审批(双超管互审) |
| 审批中角色状态 | pending,不可分配给新用户,已绑定用户继续使用旧权限 |
| 审批超时 | 72小时未处理自动驳回,角色恢复 active,原权限不变 |
| 审批通过后 | 更新角色 data_scope + custom_objects,失效所有绑定用户的 perm:{user_id} 缓存,记录变更日志 |
| 变更日志字段 | operator_id、role_id、before_scope、after_scope、approver_id、approve_time、approve_result |
8.5 列级敏感字段权限
8.5.1 业务逻辑
- 列级敏感字段权限控制用户可见的数据列(字段)及其展示形式
- 敏感字段分为三级控制:
- 明文:字段原值展示,无遮挡
- 脱敏:字段部分遮挡展示(如手机号显示为138****8888)
- 隐藏:字段完全不展示,表格列或详情页字段不可见
- 查看明文需触发二次验证(短信验证码或登录密码),限时展示(如5分钟后自动恢复脱敏)
8.5.2 敏感字段定义
| 字段名称 | 字段编码 | 脱敏规则 | 默认级别 |
|---|---|---|---|
| 手机号 | mobile |
中间4位隐藏:138****8888 | 脱敏 |
| 身份证号 | idCard |
中间8位隐藏:110**********1234 | 脱敏 |
| 银行卡号 | bankCard |
仅显示后4位:**** **** **** 1234 | 脱敏 |
| 法人身份证 | legalIdCard |
中间8位隐藏 | 脱敏 |
| 联系人手机号 | contactMobile |
中间4位隐藏 | 脱敏 |
| 游客姓名 | visitorName |
仅显示姓氏:张** | 脱敏 |
8.5.3 二次验证流程
flowchart TD
A[用户点击查看明文按钮] --> B{用户是否有明文权限}
B -->|无权限| C[提示:无权限查看明文]
B -->|有权限| D[弹出二次验证弹窗]
D --> E[输入短信验证码或登录密码]
E --> F{验证是否通过}
F -->|否| G[提示验证失败,显示剩余次数]
G --> E
F -->|是| H[明文展示该字段]
H --> I[记录明文查看日志]
H --> J[启动5分钟倒计时]
J -->|5分钟结束| K[自动恢复脱敏展示]
8.5.4 规则约束
- 敏感字段权限按角色配置,支持为不同角色设置不同的字段展示级别
- 二次验证方式可选:短信验证码或登录密码,由系统配置决定
- 明文查看操作记录到操作日志,包含:操作人、字段名、查看时间、IP地址
- 每个用户每天最多进行20次明文查看操作,超限后提示"今日明文查看次数已达上限"
- 导出数据时,敏感字段自动按角色配置的级别脱敏,无导出权限的用户无法导出
9安全审计
安全审计模块提供系统操作的全链路留痕能力,包括操作日志记录、敏感字段明文查看审计、数据导出审计,确保所有关键操作可追溯、可审计,满足合规要求。
9.1 操作日志审计
9.1.1 业务逻辑
- 操作日志记录用户在系统中的所有操作行为,包括查询、新增、编辑、删除、审核、导出等
- 敏感操作(如删除、审核通过/驳回、重置密码、明文查看、导出)在日志中标记为高敏感
- 编辑操作记录操作前后的值变化(diff),便于追溯数据变更
- 日志保留期限:默认365天,超期自动归档,超级管理员可查询归档数据
9.1.2 日志字段定义
| 字段 | 说明 | 示例 |
|---|---|---|
| 操作人 | 执行操作的用户ID及姓名 | 张三(zhangsan001) |
| 操作类型 | 操作的分类,如登录、查询、新增、编辑、删除、导出等 | 编辑 |
| 操作对象 | 被操作的数据对象类型及ID | 用户(ID: 10023) |
| 操作内容 | 操作的具体描述 | 修改用户状态:正常 → 停用 |
| 操作前值 | 编辑操作前的原始值(JSON格式) | {"status": "normal"} |
| 操作后值 | 编辑操作后的新值(JSON格式) | {"status": "disabled"} |
| 操作时间 | 操作发生的精确时间 | 2026-07-01 14:32:18 |
| IP地址 | 操作来源IP | 192.168.1.100 |
| 操作结果 | 操作是否成功 | 成功 / 失败 |
| 敏感标记 | 是否为敏感操作 | 是 / 否 |
9.1.3 页面原型
9.1.4 敏感操作定义
| 操作类型 | 是否敏感 | 说明 |
|---|---|---|
| 登录/登出 | 否 | 常规操作,但需记录IP和设备信息 |
| 查询/列表 | 否 | 常规操作,高频发生 |
| 新增 | 否 | 常规操作 |
| 编辑 | 是(部分) | 修改敏感字段(手机号、身份证)时标记为敏感 |
| 删除 | 是 | 数据删除操作,一律标记为敏感 |
| 审核通过/驳回 | 是 | 影响业务状态的关键操作 |
| 重置密码 | 是 | 影响账号安全的操作 |
| 明文查看 | 是 | 查看敏感字段明文 |
| 导出 | 是 | 数据导出操作,一律标记为敏感 |
9.2 明文查看二次验证
详见 8.5 列级敏感字段权限 中的二次验证流程。
9.3 导出强制脱敏
9.3.1 业务逻辑
- 所有列表页的导出功能,导出前校验用户是否拥有导出按钮权限
- 导出数据中的敏感字段(手机号、身份证、银行卡等)根据用户角色的敏感字段配置自动脱敏
- 无导出权限的用户,导出按钮隐藏或禁用
- 每次导出操作记录到操作日志,包含:导出人、导出对象、导出条数、导出时间、脱敏状态
- 导出文件命名规范:{对象名称}_{日期}_{随机6位}.xlsx,如 user_20260701_a3f8b2.xlsx
9.3.2 导出确认弹窗
您即将导出 23 条用户数据,其中敏感字段将按您的权限自动脱敏。
10数据与指标
10.1 核心指标
| 指标名称 | 指标定义 | 计算方式 | 目标值 |
|---|---|---|---|
| 登录成功率 | 成功登录次数占总登录请求次数的比例 | 成功登录次数 / 总登录请求次数 × 100% | ≥ 95% |
| 密码错误锁定率 | 因密码错误导致账号锁定的用户占比 | 锁定用户数 / 活跃用户数 × 100% | ≤ 5% |
| 权限配置覆盖率 | 已配置权限的角色占总角色数的比例 | 已配置权限角色数 / 总角色数 × 100% | = 100% |
| 敏感操作审计覆盖率 | 敏感操作被记录到日志的比例 | 已记录敏感操作数 / 总敏感操作数 × 100% | = 100% |
| 明文查看合规率 | 敏感字段明文查看均经过二次验证的比例 | 合规明文查看次数 / 总明文查看次数 × 100% | = 100% |
10.2 追踪需求
| 事件名称 | 触发时机 | 属性字段 | 用途 |
|---|---|---|---|
| login_success | 用户成功登录 | user_id, merchant_type, supplier_type, distributor_type, role, ip, device | 统计登录成功率、活跃用户 |
| login_fail | 用户登录失败 | user_id, fail_reason, fail_count, ip | 监控暴力破解、密码错误分析 |
| pwd_reset | 密码重置 | user_id, reset_type, operator_id | 监控密码重置频率、异常重置 |
| role_permission_change | 角色权限变更 | role_id, operator_id, change_type, before, after | 审计权限变更、追溯越权 |
| sensitive_field_view | 敏感字段明文查看 | user_id, field_name, object_id, verify_method | 监控敏感数据访问、合规审计 |
| data_export | 数据导出 | user_id, object_type, row_count, desensitized | 监控数据导出频率、泄露风险 |
11系统初始化与依赖顺序(部署清单)
本节专门针对新租户(如新入驻的供应商或分销商)上线时的系统初始化操作步骤进行规范,确保数据一致性,避免因顺序错误导致功能不可用。
| 步骤 | 操作模块 | 具体内容 | 依赖说明 |
|---|---|---|---|
| 1 | 系统预制 | 初始化菜单树、按钮编码、敏感字段定义。这些是系统的"骨架",不依赖任何业务数据。 | 无 |
| 2 | 组织架构 | 创建顶级部门(如"XX科技有限公司"),并根据业务规划创建子部门(如"运营部"、"技术部"、"财务部")。 | 无(独立搭建) |
| 3 | 角色权限 | 创建角色(如"管理员"、"商品专员"、"财务专员"),并配置菜单权限、按钮权限、行级数据权限(此时可勾选"本部门数据")及敏感字段可见级别。 | 依赖步骤2:勾选"本部门数据"时,需要部门树结构存在才能明确数据范围含义。 |
| 4 | 用户账号 | 创建管理员账号及普通员工账号。填写基本信息,必须选择所属部门(来源步骤2),必须分配角色(来源步骤3)。系统自动生成初始密码。 | 强依赖步骤2和步骤3:部门下拉框和角色下拉框必须有数据。 |
| 5 | 登录验证 | 用户首次登录,强制修改初始密码,进入工作台。验证菜单可见性(依赖角色)和数据可见性(依赖部门归属)。 | 依赖步骤4生成的账号。 |
• 禁止先创建用户再创建部门(用户表的外键
dept_id 无处指向)。• 禁止先给用户分配角色再创建角色(角色必须存在才能被选择)。
• 禁止先删除部门再转移成员(会导致用户
dept_id 指向已删除的部门,产生孤儿数据)。
11.2 租户预置数据清单(系统初始化数据) 新增
系统初始化或新租户上线时,必须预置以下数据。预置数据与前端 mock 完全对齐(src/mock/menus.js、src/mock/base.js),后端初始化脚本直接据此生成。
11.2.1 预置菜单树(按 merchant_type)
系统预置 5 套菜单树,按租户类型隔离。菜单项数据来源:菜单结构整理版 v1.3。
| merchant_type | distributor_type | 菜单树标识 | 预置一级菜单 | 用户管理菜单 | 菜单项总数 |
|---|---|---|---|---|---|
| PLATFORM | - | menu_platform | 工作台/基础管理/商家管理/商品管理中心/分销管理/营销中心/订单中心/财务管理/数据运营/系统配置 | 显示(含组织架构/角色权限/用户账号/操作日志4个子菜单) | ~80项 |
| SUPPLIER | - | menu_supplier | 工作台/商品管理/订单管理/分销管理/财务管理/系统管理 | 显示(含用户/角色/部门子菜单) | ~45项 |
| DISTRIBUTOR | INDIVIDUAL | menu_dist_individual | 工作台/分销推广/订单管理/佣金中心/个人中心 | 隐藏(个体不开放子账号) | ~20项 |
| DISTRIBUTOR | B | menu_dist_b | 工作台/选品中心/采购管理/订单管理/分销管理/财务管理/系统管理 | 显示(含用户/角色子菜单) | ~40项 |
| DISTRIBUTOR | OTA | menu_dist_ota | 工作台/接口管理/订单同步/财务管理/系统管理 | 显示(含用户/角色/接口运营子菜单) | ~35项 |
id, name, parent_id, path, icon, sort, merchant_type, supplier_type, distributor_type, status;②禁用状态的菜单对所有角色不可见;③个体分销商菜单树必须不含任何"用户管理"入口,从数据层禁止分配。
11.2.2 预制角色清单(11个内置角色)
系统预置 11 个内置角色(is_system=true,不可删除、不可改 code)。与前端 base.js 的 MOCK_ROLES 完全对齐。
| 角色编码 | 角色名称 | merchant_type | distributor_type | data_scope | 预置菜单 | 预置按钮 | 敏感字段默认级别 |
|---|---|---|---|---|---|---|---|
R101 | 平台超管 | PLATFORM | - | all | 全部平台菜单 | 全部按钮(自动) | 全部明文 |
R102 | 平台管理员 | PLATFORM | - | all | 全部平台菜单 | user:* / role:* / dept:* / log:* / product:audit | mobile明文/其余脱敏 |
R103 | 商家运营 | PLATFORM | - | dept | 工作台/商家管理/商品管理 | supplier:* / product:audit | 全部脱敏 |
R104 | 风控专员 | PLATFORM | - | dept | 工作台/风控相关 | risk:* / log:view | mobile明文/idCard明文/其余脱敏 |
R201 | 供应商管理员 | SUPPLIER | - | all | 全部供应商菜单 | user:* / role:* / dept:* / product:* | mobile明文/其余脱敏 |
R202 | 商品专员 | SUPPLIER | - | self | 工作台/商品管理 | product:create / product:edit / product:shelf | 全部脱敏 |
R203 | 财务专员 | SUPPLIER | - | self | 工作台/财务管理 | finance:view / finance:reconcile | bankCard脱敏 |
R301 | 个体分销商 | DISTRIBUTOR | INDIVIDUAL | self | 全部个体分销菜单(无用户管理) | distribution:* / commission:view | mobile脱敏/其余隐藏 |
R401 | B端分销商管理员 | DISTRIBUTOR | B | all | 全部B端分销菜单 | user:* / role:* / dept:* / purchase:* | mobile明文/其余脱敏 |
R402 | 分销运营 | DISTRIBUTOR | B | dept | 工作台/选品/订单 | product:view / order:view / order:export | 全部脱敏 |
R501 | OTA渠道管理员 | DISTRIBUTOR | OTA | all | 全部OTA分销菜单 | user:* / role:* / api:* / order:sync | mobile明文/其余脱敏 |
is_system=true;②新租户上线时,按 merchant_type+distributor_type+supplier_type 复制对应预置角色到该租户(多身份租户复制多组角色)(tenant_id 填新租户ID,is_system=false 允许租户管理员二次配置);③R101平台超管仅有一个,不可新建第二个。
11.2.3 预置按钮编码清单
系统预置 7 大模块共 35 个按钮编码,完整清单见 8.3.2 节。初始化时将所有编码写入 button_code_dict 字典表,供角色配置时下拉选择。
| 模块 | 编码前缀 | 编码数量 | 敏感操作编码 |
|---|---|---|---|
| 用户管理 | user:* | 8 | delete / resetPwd / export |
| 角色管理 | role:* | 5 | delete / assignPerm |
| 组织架构 | dept:* | 6 | delete / leader |
| 操作日志 | log:* | 2 | export |
| 商品管理 | product:* | 5 | audit |
| 订单管理 | order:* | 4 | audit / refund / export |
| 财务管理 | finance:* | 4 | transfer / export |
11.2.4 预置敏感字段清单(6项)
系统预置 6 个敏感字段,与前端 RoleManage.vue 的 sensitiveFields 完全对齐。新增字段需登记到本表并走变更流程。
| field_code | 字段名称 | 脱敏规则 | 默认级别 | 适用业务表 |
|---|---|---|---|---|
mobile | 手机号 | 中间4位隐藏:138****8888 | 脱敏 | user / supplier / distributor / visitor |
idCard | 身份证号 | 中间8位隐藏:110**********1234 | 脱敏 | user / visitor |
bankCard | 银行卡号 | 仅显示后4位:**** **** **** 1234 | 脱敏 | finance_account / withdrawal |
legalIdCard | 法人身份证 | 中间8位隐藏 | 脱敏 | supplier / distributor(企业资质) |
contactMobile | 联系人手机号 | 中间4位隐藏 | 脱敏 | supplier / distributor |
visitorName | 游客姓名 | 仅显示姓氏:张** | 脱敏 | order_visitor |
11.2.5 三端预置数据对照(初始化脚本依据)
平台运营端初始化(系统首次部署)
①插入 PLATFORM 菜单树(~80项)→ ②插入顶级部门"云灵汐平台"→ ③插入11个预制角色(is_system=true)→ ④插入R101平台超管账号 → ⑤发送初始密码短信
供应商端初始化(新供应商入驻审核通过后)
①复制 SUPPLIER 菜单树,tenant_id 填新供应商ID → ②创建该供应商顶级部门(部门名=供应商简称)→ ③复制 R201/R202/R203 角色到该租户(is_system=false)→ ④创建供应商管理员账号绑定 R201 → ⑤发送初始密码短信
分销商端初始化(新分销商入驻审核通过后)
①按 distributor_type 复制对应菜单树(INDIVIDUAL/B/OTA),tenant_id 填新分销商ID → ②B端/OTA创建顶级部门(个体无部门)→ ③复制对应预制角色 → ④创建分销商管理员账号绑定主角色 → ⑤发送初始密码短信
operation_type=init。
11AAPI接口清单
本节定义权限中心全部 RESTful 接口,与前端 src/api/ 调用对齐。所有接口遵循统一规范。
11A.1 接口规范
统一响应格式
成功响应
{"code":0,"message":"success","data":{...},"trace_id":"a3f8b2..."}
失败响应
{"code":40001,"message":"账号不存在","data":null,"trace_id":"a3f8b2..."}
统一错误码
| 错误码 | 含义 | HTTP状态 |
|---|---|---|
| 0 | 成功 | 200 |
| 40001 | 参数校验失败 | 400 |
| 40101 | 未登录/Token过期 | 401 |
| 40301 | 权限不足 | 403 |
| 40302 | 租户隔离违规 | 403 |
| 40401 | 资源不存在 | 404 |
| 40901 | 业务冲突(如删部门有成员) | 409 |
| 42301 | 账号锁定 | 423 |
| 50001 | 服务器错误 | 500 |
鉴权规范
- 除
POST /api/auth/login、POST /api/auth/sms-code、POST /api/auth/reset-password外,所有接口必须在 Header 携带Authorization: Bearer {JWT} - Token校验 + 权限校验 + 租户隔离校验均在网关层完成,业务服务不重复校验
11A.2 登录鉴权接口
| 方法 | 路径 | 描述 | 请求参数 | 响应 | 权限 | 敏感 |
|---|---|---|---|---|---|---|
| POST | /api/auth/login | 账号密码登录 | account/mobile, password, remember_me | token, user{merchant_type, supplier_type, distributor_type, roles} | 无需 | 否 |
| POST | /api/auth/logout | 登出,Token加入黑名单 | - | code:0 | 已登录 | 否 |
| POST | /api/auth/refresh | 刷新Token(记住我续期) | refresh_token | 新token | 已登录 | 否 |
| GET | /api/auth/userinfo | 获取当前用户信息+权限集合 | - | user + menus + buttons + data_scope + sensitive_fields | 已登录 | 否 |
| POST | /api/auth/sms-code | 发送短信验证码(忘记密码/明文查看) | mobile, scene | code:0(不返回验证码明文) | 无需 | 否 |
| POST | /api/auth/reset-password | 忘记密码重置 | mobile, sms_code, new_password | code:0 | 无需 | 否 |
| PUT | /api/auth/password | 自助修改密码 | old_password, new_password | code:0 | 已登录 | 是 |
| POST | /api/auth/view-plaintext | 敏感字段明文查看二次验证 | verify_type, verify_code, field_code, object_id | plaintext_value, expire_at | 已登录+按钮权限 | 是 |
11A.3 用户管理接口
| 方法 | 路径 | 描述 | 请求参数 | 响应 | 权限 | 敏感 |
|---|---|---|---|---|---|---|
| GET | /api/user | 用户列表(分页+筛选) | page, page_size, keyword, status, role_id, dept_id | total, list[{id,name,account,mobile(脱敏),dept,roles,status,last_login_at}] | user:view | 否(自动脱敏) |
| POST | /api/user | 新增用户 | name, account, mobile, password(可选,不填生成随机), email, dept_id, role_ids[] | id, initial_password(仅一次) | user:create | 是(返回密码) |
| GET | /api/user/{id} | 用户详情 | - | user全字段(敏感按权限脱敏) | user:view | 按权限 |
| PUT | /api/user/{id} | 编辑用户 | name, email, dept_id, role_ids[](account/mobile不可改) | code:0 | user:edit | 否 |
| DELETE | /api/user/{id} | 软删除用户 | - | code:0 | user:delete | 是 |
| PUT | /api/user/{id}/status | 停用/启用/锁定/解锁 | action: disable/enable/lock/unlock | code:0 | user:lock 或 user:enable | 是 |
| PUT | /api/user/{id}/password | 运营强制重置密码 | new_password(可选,不填生成随机) | new_password(仅一次) | user:resetPwd | 是 |
| GET | /api/user/export | 导出用户列表(异步) | 同list筛选参数 | task_id,异步生成文件 | user:export | 是(强制脱敏) |
| PUT | /api/user/{userId}/dept | 变更用户所属部门 | dept_id(可为null表示移除) | code:0 | dept:member | 否 |
11A.4 部门管理接口
| 方法 | 路径 | 描述 | 请求参数 | 响应 | 权限 |
|---|---|---|---|---|---|
| GET | /api/dept/tree | 部门树(含子节点递归) | - | list[{id,name,parent_id,leader_id,sort,children[]}] | dept:view |
| POST | /api/dept | 新增部门 | name, parent_id, leader_id, sort | id | dept:create |
| PUT | /api/dept/{id} | 编辑部门(含改上级) | name, parent_id, sort(改上级需防循环) | code:0 | dept:edit |
| DELETE | /api/dept/{id} | 删除部门(需先转移成员/子部门) | - | 失败返回40901+原因 | dept:delete |
| GET | /api/dept/{id}/members | 部门成员列表 | - | list[{id,name,account,role,is_leader}] | dept:view |
| PUT | /api/dept/{id}/leader | 设置/取消部门负责人 | user_id(取消传null) | code:0 | dept:leader |
11A.5 角色管理接口
| 方法 | 路径 | 描述 | 请求参数 | 响应 | 权限 |
|---|---|---|---|---|---|
| GET | /api/role | 角色列表 | keyword, status | list[{id,name,code,data_scope,is_system,status}] | role:view |
| POST | /api/role | 新增角色 | name, code, description, data_scope | id | role:create |
| PUT | /api/role/{id} | 编辑角色(系统角色仅可改description) | name, description, data_scope | code:0 | role:edit |
| DELETE | /api/role/{id} | 删除角色(系统角色不可删,绑定用户的角色不可删) | - | 失败返回40901 | role:delete |
| PUT | /api/role/{id}/permissions | 配置角色权限(4个Tab统一接口) | type: menu/button/sensitive/data, values[] | code:0(触发权限缓存失效) | role:assignPerm |
| GET | /api/role/{id}/permissions | 查询角色当前权限配置 | type | values[] | role:view |
| POST | /api/role/{id}/change-request | 发起权限变更审批(放宽数据范围) | new_data_scope, reason | request_id | role:assignPerm |
| PUT | /api/role-change/{request_id}/approve | 审批权限变更 | result: approve/reject, comment | code:0 | 直属上级 |
11A.6 权限查询接口(前端权限初始化用)
| 方法 | 路径 | 描述 | 响应 | 用途 |
|---|---|---|---|---|
| GET | /api/permission/menus | 当前用户菜单树 | list[{id,name,path,icon,children[]}] | 渲染左侧导航 |
| GET | /api/permission/buttons | 当前用户按钮权限编码集合 | list["user:create","role:view",...] | 前端按钮显隐控制 |
| GET | /api/permission/sensitive-fields | 当前用户敏感字段级别映射 | {mobile:"desensitized", idCard:"hidden",...} | 字段脱敏渲染 |
| GET | /api/permission/data-scope | 当前用户数据范围+自定义对象 | {scope:"dept", custom_objects:{...}} | ORM拦截参数(前端只读) |
GET /api/auth/userinfo(一次性返回用户+权限聚合)→ 前端缓存到 vuex/localStorage → 路由守卫和按钮渲染据此判断。权限变更后需重新调用 userinfo 刷新。
11A.7 操作日志接口
| 方法 | 路径 | 描述 | 请求参数 | 响应 | 权限 |
|---|---|---|---|---|---|
| GET | /api/log/operation | 操作日志列表(分页+筛选) | page, page_size, operator, operation_type, target_type, is_sensitive, start_time, end_time | total, list[{id,operator,operation_type,target_desc,ip,result,is_sensitive,created_at}] | log:view |
| GET | /api/log/operation/{id} | 日志详情(含前后值diff) | - | log全字段(before_value, after_value) | log:view |
| GET | /api/log/export | 导出操作日志(异步) | 同list筛选 | task_id | log:export |
11A.8 接口设计约束
- 分页统一:所有列表接口参数
page(≥1)、page_size(默认20,上限100),响应含total和list - 筛选统一:模糊查询用
keyword,状态用status,时间范围用start_time/end_time - 批量操作:用
POST /api/{module}/batch,body含ids[]和action - 导出统一:所有导出接口异步处理,返回
task_id,前端轮询GET /api/export/task/{task_id}获取下载链接 - 幂等性:新增/编辑接口支持
Idempotency-KeyHeader,防止前端重复提交 - 租户隔离:所有接口在网关层自动注入
tenant_id,业务代码不可手写跨租户查询
12依赖与风险
12.1 技术依赖
| 依赖项 | 说明 | 影响 |
|---|---|---|
| 短信网关 | 忘记密码、明文查看二次验证需发送短信验证码 | 高;短信网关不可用时,上述功能降级为登录密码验证 |
| JWT认证框架 | 登录态管理、Token生成与校验 | 高;需统一三端Token规范 |
| ORM框架(数据权限拦截) | 行级数据权限(本部门数据) 需在ORM层动态拼接SQL条件 | 高;需支持递归查询部门子节点并注入 IN 条件 |
| 组织架构服务 | 部门树的CRUD、成员归属、负责人配置 | 高;用户管理和数据权限的前置基础 |
12.2 风险列表
| 风险 | 概率 | 影响 | 缓解策略 |
|---|---|---|---|
| 权限配置错误导致数据泄露 | 中 | 高 | 权限变更需二次确认;提供权限预览功能;关键权限变更通知超级管理员 |
| 暴力破解攻击 | 中 | 高 | 登录失败锁定、IP限流、验证码机制、异常登录提醒 |
| 敏感字段脱敏规则遗漏 | 低 | 高 | 建立敏感字段清单,新增字段时自动审核;定期安全审计 |
| 日志数据量过大影响性能 | 高 | 中 | 日志异步写入;定期归档(超过365天自动归档);归档数据可查询 |
| 多角色权限冲突 | 中 | 中 | 权限取并集;提供权限冲突检测工具;限制互斥角色同时绑定 |
| 部门树循环引用(编辑上级时选错) | 低 | 高 | 后端接口必须校验新 parent_id 不能为自身或子节点;前端下拉框过滤掉不可选项。 |
| 负责人离职未及时交接 | 中 | 中 | 系统提供"部门负责人变更"审批流程(二期);当前版本支持管理员手动转移。 |
| 未分配部门用户无法查看数据 | 中 | 中 | 创建用户时强制选择部门;管理员后台提供"未分配部门"成员筛选,及时提醒补填。 |
13验收标准
13.1 功能验收标准
| 功能模块 | 验收项 | 验收标准 | 优先级 |
|---|---|---|---|
| 登录与账号安全 | 账号密码登录 | 支持手机号/账号登录;错误提示清晰;首次登录强制改密;Token有效期24小时 | P0 |
| 密码修改 | 原密码校验通过才能修改;新密码8-32位且含字母+数字;不能与最近3次密码相同 | P0 | |
| 忘记密码 | 手机号验证通过后可重置密码;验证码5分钟有效;每天最多10次 | P0 | |
| 防暴力破解 | 连续5次失败锁定30分钟;同账号互踢;登录日志记录完整 | P1 | |
| 用户管理 | 用户CRUD | 新增/编辑/停用/锁定/删除功能完整;账号手机号唯一性校验;软删除可恢复 | P0 |
| 组织架构 | 部门树支持无限层级;删除部门前校验成员;负责人自动获得部门数据权限 | P1 | |
| 角色权限 | 菜单权限 | 菜单树按端隔离;父子联动选择;角色绑定后登录可见对应菜单 | P0 |
| 按钮权限 | 无权限按钮隐藏;后端接口双层校验;超级管理员拥有全部权限 | P0 | |
| 行级数据权限 | 全部/本部门/本人/自定义四种范围生效;ORM自动拼接条件;多角色取并集 | P0 | |
| 列级敏感字段 | 敏感字段默认脱敏;查看明文需二次验证;5分钟后自动恢复脱敏;操作留痕 | P0 | |
| 安全审计 | 操作日志 | 所有操作记录完整;敏感操作标记;编辑操作记录前后值;支持筛选查询 | P1 |
| 明文查看审计 | 每次明文查看记录到日志;包含字段名、时间、IP、验证方式 | P1 | |
| 导出审计 | 每次导出记录到日志;导出文件自动脱敏;无权限用户无法导出 | P1 |
13.2 组织架构验收标准(新增)
| 模块 | 验收项 | 验收标准 |
|---|---|---|
| 组织架构 | 部门CRUD | 新增/编辑/删除部门功能完整;删除时校验成员和子部门,不符合条件时给出明确提示并阻止。 |
| 负责人设置 | 只能从本部门成员中选择负责人;取消负责人后,该成员保留在部门中;一个部门只有一个负责人。 | |
| 成员管理 | 添加成员时下拉列表排除已在本部门的用户;移除成员时校验是否为负责人。 | |
| 数据权限联动 | 角色配置"本部门数据"后,用户仅能查看本部门及子部门数据;负责人自动获得本部门及子部门数据权限。 |
13.3 性能验收标准
| 场景 | 指标 | 目标值 |
|---|---|---|
| 登录请求 | 接口响应时间 | ≤ 500ms(P99) |
| 用户列表查询 | 接口响应时间 | ≤ 300ms(P99) |
| 角色权限保存 | 接口响应时间 | ≤ 500ms(P99) |
| 操作日志查询 | 接口响应时间 | ≤ 800ms(P99) |
| 数据导出 | 导出耗时(1万条) | ≤ 10秒 |
13.4 安全验收标准
- 密码传输采用HTTPS加密,禁止明文传输
- Token存储在HttpOnly Cookie中,防止XSS攻击
- 登录接口增加验证码机制(图形验证码或滑块验证)
- 敏感操作(删除、审核、重置密码)需二次确认弹窗
- SQL注入防护:所有用户输入参数化查询,禁止拼接SQL
- 越权访问防护:后端校验用户是否有权访问目标数据,不依赖前端隐藏