crm-backend-matt/.qoder/repowiki/zh/content/数据模型/数据模型.md

数据模型

**本文引用的文件** - [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java) - [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java) - [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java) - [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java) - [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java) - [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java) - [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java) - [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java) - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java) - [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java) - [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java) - [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java) - [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java) - [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) - [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java) - [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java) - [RoleController.java](file://crm-auth/src/main/java/com/crm/auth/controller/RoleController.java) - [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java) - [application.yml](file://crm-app/src/main/resources/application.yml) - [application.yml](file://crm-auth/src/main/resources/application.yml)

更新摘要

变更内容

• 增强了角色管理系统的验证规则和约束条件
• 新增数据范围限制（1-4范围），排除自定义数据范围（CUSTOM=5）
• 实现内置角色保护机制，防止删除和修改内置角色编码
• 强化角色编码唯一性校验，支持跨ID的唯一性检查
• 新增VALID_DATA_SCOPE_VALUES集合用于API操作的数据范围验证
• 完善角色管理的错误码定义和业务异常处理

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件为 CRM 后端的数据模型文档，面向数据库管理员与后端开发者。内容覆盖用户、角色、菜单、部门、身份认证、文件等核心实体的字段定义、数据类型、约束与业务含义；提供实体关系图（ER）与类图；说明主键策略、外键关联、索引设计、数据完整性约束；给出数据字典、枚举值定义、默认值设置；并补充数据迁移策略、版本兼容性与备份恢复方案。

更新 本次更新重点反映了角色管理系统的增强功能，包括新的验证规则、数据范围限制、内置角色保护机制和角色编码唯一性强制校验。

项目结构

本项目采用多模块架构：

• crm-base：基础能力（通用实体、配置、工具、异常、分页、结果封装等）
• crm-auth：认证授权与系统管理（用户、角色、菜单、部门、权限、数据范围等）
• crm-file：文件服务（上传、分片、预览、清理任务等）
• crm-app：应用启动入口与全局配置

graph TB
subgraph "基础层"
base["crm-base<br/>通用实体/配置/工具"]
end
subgraph "认证授权"
auth["crm-auth<br/>用户/角色/菜单/部门/权限"]
end
subgraph "文件服务"
file["crm-file<br/>文件元数据/分片/预览"]
end
subgraph "应用"
app["crm-app<br/>启动与配置"]
end
app --> auth
app --> file
auth --> base
file --> base

图表来源

• application.yml
• application.yml

章节来源

• application.yml
• application.yml

核心组件

• 通用基类
  • BaseEntity：统一审计字段（如创建时间、更新时间等），配合自动填充处理器实现默认值与审计信息注入
  • OwnedEntity：扩展数据所有权字段（如创建人、所属组织等），用于数据可见性控制
• 主键生成器
  • SnowflakeIdWorker：雪花算法分布式ID生成
  • CustomIdGenerator：MyBatis-Plus 自定义ID生成器，将雪花ID注入到实体主键
• 自动填充与SQL注入
  • MetaObjectFillHandler：MyBatis-Plus 自动填充处理器，统一处理审计字段与默认值
  • CrmSqlInjector：MyBatis-Plus SQL 注入器，启用逻辑删除、乐观锁等增强功能
  • InsertBatchOnDuplicateKeyUpdate：批量插入去重更新支持

章节来源

• BaseEntity.java
• OwnedEntity.java
• SnowflakeIdWorker.java
• CustomIdGenerator.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• InsertBatchOnDuplicateKeyUpdate.java

架构总览

下图展示核心实体之间的关系与职责边界，包括用户、角色、菜单、部门、身份与文件的关联。

erDiagram
AUTH_USER {
bigint id PK
string username UK
string nickname
string email
string phone
int status
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
SYS_ROLE {
bigint id PK
string role_code UK
string role_name
int data_scope
int sort
boolean builtin
int status
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
SYS_MENU {
bigint id PK
string menu_code UK
string menu_name
int type
string path
string component
int sort
int status
bigint parent_id
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
SYS_DEPT {
bigint id PK
string dept_code UK
string dept_name
int sort
int status
bigint parent_id
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
AUTH_IDENTITY {
bigint id PK
string identity_type
string identity_value
bigint user_id FK
string provider
string open_id
string union_id
int status
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
FILE_INFO {
bigint id PK
string bucket
string object_key
string file_name
long file_size
string mime_type
string md5
int status
bigint create_by
bigint update_by
datetime create_time
datetime update_time
}
SYS_USER_ROLE {
bigint id PK
bigint user_id FK
bigint role_id FK
unique uk_user_role
}
SYS_ROLE_MENU {
bigint id PK
bigint role_id FK
bigint menu_id FK
unique uk_role_menu
}
SYS_USER_DEPT {
bigint id PK
bigint user_id FK
bigint dept_id FK
unique uk_user_dept
}
AUTH_USER ||--o{ AUTH_IDENTITY : "拥有"
AUTH_USER ||--o{ SYS_USER_ROLE : "属于"
SYS_ROLE ||--o{ SYS_USER_ROLE : "分配给"
SYS_ROLE ||--o{ SYS_ROLE_MENU : "包含"
SYS_MENU ||--o{ SYS_ROLE_MENU : "被包含"
AUTH_USER ||--o{ SYS_USER_DEPT : "归属"
SYS_DEPT ||--o{ SYS_USER_DEPT : "包含"

图表来源

• AuthUser.java
• SysRole.java
• SysMenu.java
• SysDept.java
• AuthIdentity.java
• FileInfo.java
• SysUserRole.java
• SysRoleMenu.java
• SysUserDept.java

详细组件分析

用户实体（AuthUser）

• 字段与类型
  • 主键：id（bigint，雪花ID）
  • 用户名：username（varchar，唯一）
  • 昵称：nickname（varchar）
  • 邮箱：email（varchar，可选唯一）
  • 手机：phone（varchar，可选唯一）
  • 状态：status（int，参考 StatusEnum）
  • 审计字段：create_by、update_by、create_time、update_time（继承自 BaseEntity）
• 约束与索引
  • 主键：id
  • 唯一索引：username
  • 可选唯一索引：email、phone（按业务需要开启）
• 业务含义
  • 系统登录与鉴权的核心主体，支持第三方身份绑定（通过 AuthIdentity）
• 默认值与填充
  • 审计字段由 MetaObjectFillHandler 自动填充
  • 主键由 CustomIdGenerator + SnowflakeIdWorker 生成

章节来源

• AuthUser.java
• BaseEntity.java
• MetaObjectFillHandler.java
• CustomIdGenerator.java
• SnowflakeIdWorker.java

角色实体（SysRole）- 已更新

• 字段与类型
  • 主键：id（bigint，雪花ID）
  • 角色名称：roleName（varchar(50)，非空）
  • 角色编码：roleCode（varchar(50)，非空，唯一）
  • 数据范围：dataScope（tinyint，默认1，范围1-4）
  • 排序：sort（int，默认0）
  • 备注：remark（varchar(200)）
  • 内置标记：builtin（boolean，默认false）
  • 审计字段：create_by、update_by、create_time、update_time
• 约束与索引
  • 主键：id
  • 唯一索引：roleCode
  • 默认值：dataScope=1, sort=0, builtin=false
• 业务含义
  • 权限集合的载体，与菜单进行多对多关联
  • 支持数据范围控制（本人、本部门、本部门及子部门、全部数据）
  • 内置角色保护机制，防止误删和编码修改
• 新增验证规则
  • dataScope必须在1-4范围内，禁止使用CUSTOM（5）
  • 内置角色（builtin=true）禁止删除和修改roleCode
  • 创建角色时不允许设置builtin=true
  • roleCode必须全局唯一（跨ID检查）

更新 角色实体新增了builtin字段和增强的验证规则，包括数据范围限制和内置角色保护机制。

章节来源

• SysRole.java
• SysRoleServiceImpl.java

菜单实体（SysMenu）

• 字段与类型
  • 主键：id（bigint，雪花ID）
  • 菜单编码：menuCode（varchar，唯一）
  • 菜单名称：menuName（varchar）
  • 类型：type（int，参考 MenuTypeEnum）
  • 路径：path（varchar）
  • 组件：component（varchar）
  • 排序：sort（int）
  • 状态：status（int，参考 StatusEnum）
  • 父级：parentId（bigint，自引用树形结构）
  • 审计字段：createBy、updateBy、createTime、updateTime
• 约束与索引
  • 主键：id
  • 唯一索引：menuCode
  • 建议索引：parentId（树形查询优化）
• 业务含义
  • 前端路由与按钮权限的控制点，支持多级菜单

章节来源

• SysMenu.java
• MenuTypeEnum.java

部门实体（SysDept）

• 字段与类型
  • 主键：id（bigint，雪花ID）
  • 部门编码：deptCode（varchar，唯一）
  • 部门名称：deptName（varchar）
  • 排序：sort（int）
  • 状态：status（int，参考 StatusEnum）
  • 父级：parentId（bigint，自引用树形结构）
  • 审计字段：createBy、updateBy、createTime、updateTime
• 约束与索引
  • 主键：id
  • 唯一索引：deptCode
  • 建议索引：parentId（树形查询优化）
• 业务含义
  • 组织架构维度，用于数据范围与资源归属

章节来源

• SysDept.java

用户-角色-菜单-部门关联表

• SysUserRole（用户-角色）
  • 主键：id（bigint）
  • 外键：userId（AUTH_USER.id）、roleId（SYS_ROLE.id）
  • 唯一约束：(userId, roleId)
• SysRoleMenu（角色-菜单）
  • 主键：id（bigint）
  • 外键：roleId（SYS_ROLE.id）、menuId（SYS_MENU.id）
  • 唯一约束：(roleId, menuId)
• SysUserDept（用户-部门）
  • 主键：id（bigint）
  • 外键：userId（AUTH_USER.id）、deptId（SYS_DEPT.id）
  • 唯一约束：(userId, deptId)

章节来源

• SysUserRole.java
• SysRoleMenu.java
• SysUserDept.java

身份认证（AuthIdentity）

• 字段与类型
  • 主键：id（bigint）
  • 身份类型：identityType（int，参考 IdentityTypeEnum）
  • 身份值：identityValue（varchar，唯一或组合唯一）
  • 用户：userId（AUTH_USER.id）
  • 提供方：provider（varchar，如钉钉、企业微信等）
  • 开放ID：openId、unionId（varchar）
  • 状态：status（int，参考 StatusEnum）
  • 审计字段：createBy、updateBy、createTime、updateTime
• 约束与索引
  • 主键：id
  • 唯一索引：identityValue（或按 provider+openId 组合唯一）
  • 建议索引：userId、provider
• 业务含义
  • 统一第三方登录与账号绑定，支持多身份聚合到同一用户

章节来源

• AuthIdentity.java
• IdentityTypeEnum.java

文件元数据（FileInfo）

• 字段与类型
  • 主键：id（bigint）
  • 存储桶：bucket（varchar）
  • 对象键：objectKey（varchar，唯一）
  • 文件名：fileName（varchar）
  • 大小：fileSize（bigint）
  • MIME类型：mimeType（varchar）
  • 哈希：md5（varchar）
  • 状态：status（int，参考 StatusEnum）
  • 审计字段：createBy、updateBy、createTime、updateTime
• 约束与索引
  • 主键：id
  • 唯一索引：objectKey
  • 建议索引：md5（去重校验）、status（过滤查询）
• 业务含义
  • 记录文件在对象存储中的元数据，支撑上传、下载、预览与生命周期管理

章节来源

• FileInfo.java

类图（实体与基类关系）

classDiagram
class BaseEntity {
+long createBy
+long updateBy
+datetime createTime
+datetime updateTime
}
class OwnedEntity {
+long ownerDeptId
+long ownerUserId
}
class AuthUser {
+long id
+string username
+string nickname
+string email
+string phone
+int status
}
class SysRole {
+long id
+string roleName
+string roleCode
+int dataScope
+int sort
+boolean builtin
+int status
}
class SysMenu {
+long id
+string menuCode
+string menuName
+int type
+string path
+string component
+int sort
+int status
+long parentId
}
class SysDept {
+long id
+string deptCode
+string deptName
+int sort
+int status
+long parentId
}
class AuthIdentity {
+long id
+string identityType
+string identityValue
+long userId
+string provider
+string openId
+string unionId
+int status
}
class FileInfo {
+long id
+string bucket
+string objectKey
+string fileName
+long fileSize
+string mimeType
+string md5
+int status
}
class SysUserRole {
+long id
+long userId
+long roleId
}
class SysRoleMenu {
+long id
+long roleId
+long menuId
}
class SysUserDept {
+long id
+long userId
+long deptId
}
BaseEntity <|-- OwnedEntity
OwnedEntity <|-- AuthUser
OwnedEntity <|-- SysRole
OwnedEntity <|-- SysMenu
OwnedEntity <|-- SysDept
OwnedEntity <|-- AuthIdentity
OwnedEntity <|-- FileInfo

图表来源

• BaseEntity.java
• OwnedEntity.java
• AuthUser.java
• SysRole.java
• SysMenu.java
• SysDept.java
• AuthIdentity.java
• FileInfo.java
• SysUserRole.java
• SysRoleMenu.java
• SysUserDept.java

依赖关系分析

• 主键策略
  • 所有实体主键使用雪花ID，避免集中式ID冲突，提升写入性能
  • CustomIdGenerator 集成 MyBatis-Plus，自动注入雪花ID
• 外键与关联
  • 通过中间表实现多对多（用户-角色、角色-菜单、用户-部门）
  • 自引用树形结构（菜单、部门）通过 parentId 维护层级
• 索引设计
  • 唯一索引保证业务唯一性（用户名、角色编码、菜单编码、部门编码、对象键）
  • 建议为高频查询字段建立普通索引（如 status、parentId、userId、md5）
• 数据完整性
  • 逻辑删除由 CrmSqlInjector 启用，避免物理删除导致关联断裂
  • 审计字段由 MetaObjectFillHandler 统一填充，确保一致性
• 角色管理验证依赖
  • VALID_DATA_SCOPE_VALUES集合用于数据范围验证
  • 内置角色保护机制确保系统稳定性
  • 角色编码唯一性校验防止数据冲突

graph LR
AuthUser -- "1:N" --> AuthIdentity
AuthUser -- "N:M" --> SysRole
SysRole -- "N:M" --> SysMenu
AuthUser -- "N:M" --> SysDept
SysMenu -- "自引用" --> SysMenu
SysDept -- "自引用" --> SysDept
FileInfo -- "独立" --> "*"
SysRoleServiceImpl -- "验证规则" --> DataScopeEnum
SysRoleServiceImpl -- "内置保护" --> SysRole

图表来源

• AuthUser.java
• SysRole.java
• SysMenu.java
• SysDept.java
• AuthIdentity.java
• FileInfo.java
• SysRoleServiceImpl.java
• DataScopeEnum.java

章节来源

• CustomIdGenerator.java
• SnowflakeIdWorker.java
• CrmSqlInjector.java
• MetaObjectFillHandler.java
• SysRoleServiceImpl.java

性能考虑

• 主键选择雪花ID，减少热点与锁竞争，适合高并发写入
• 树形结构（菜单、部门）建议缓存根节点与常用分支，降低递归查询开销
• 大文件元数据（FileInfo）建议按状态分区或归档，保持热数据表轻量
• 批量操作使用 InsertBatchOnDuplicateKeyUpdate 减少往返次数
• 合理索引：唯一索引优先，普通索引按需添加，避免过度索引影响写入
• 角色管理性能优化
  • 角色编码唯一性检查使用LambdaQueryWrapper优化查询性能
  • 祖先节点补全采用批量查询+内存映射，避免逐节点查库
  • 事务保护确保级联操作的原子性

[本节为通用指导，不直接分析具体文件]

故障排查指南

• ID重复或生成失败
  • 检查 SnowflakeIdWorker 时钟回拨与节点ID配置
  • 确认 CustomIdGenerator 已正确注册到 MyBatis-Plus
• 审计字段未填充
  • 检查 MetaObjectFillHandler 是否生效，字段命名是否符合约定
  • 确认 BaseEntity/OwenedEntity 的字段映射正确
• 逻辑删除失效
  • 检查 CrmSqlInjector 是否启用，@TableLogic 注解是否正确
• 唯一约束冲突
  • 核对业务唯一字段（username、roleCode、menuCode、deptCode、objectKey）的输入校验
• 角色管理相关故障
  • 数据范围验证失败：检查dataScope是否在1-4范围内
  • 内置角色保护错误：确认角色builtin标志位设置
  • 角色编码重复：检查是否存在相同roleCode的其他角色
  • 级联删除失败：确认事务配置和关联表完整性

章节来源

• SnowflakeIdWorker.java
• CustomIdGenerator.java
• MetaObjectFillHandler.java
• CrmSqlInjector.java
• SysRoleServiceImpl.java

结论

本数据模型以雪花ID为主键，结合 MyBatis-Plus 的自动填充与SQL增强，实现了统一的审计、逻辑删除与批量操作能力。用户、角色、菜单、部门、身份与文件等核心实体通过明确的关联表与索引设计，满足权限控制、组织架构与文件管理的业务需求。

更新 角色管理系统的增强功能显著提升了数据完整性和系统安全性，包括严格的数据范围验证、内置角色保护机制和角色编码唯一性强制校验。这些改进确保了系统在面对恶意操作和误操作时的鲁棒性，为后续的业务发展奠定了坚实的基础。建议在后续演进中持续完善索引与缓存策略，保障性能与可维护性。

[本节为总结性内容，不直接分析具体文件]

附录

数据字典（核心实体）

• 用户（AuthUser）
  • id：主键，雪花ID
  • username：用户名，唯一
  • nickname：昵称
  • email：邮箱，可选唯一
  • phone：手机，可选唯一
  • status：状态（参考 StatusEnum）
  • 审计字段：create_by、update_by、create_time、update_time
• 角色（SysRole）- 已更新
  • id：主键，雪花ID
  • roleName：角色名称，非空
  • roleCode：角色编码，唯一，非空
  • dataScope：数据范围，1-4（本人、本部门、本部门及子部门、全部），默认1
  • sort：排序，默认0
  • remark：备注
  • builtin：内置标记，默认false，true表示系统内置不可删除
  • status：状态（参考 StatusEnum）
  • 审计字段：create_by、update_by、create_time、update_time
• 菜单（SysMenu）
  • id：主键，雪花ID
  • menuCode：菜单编码，唯一
  • menuName：菜单名称
  • type：类型（参考 MenuTypeEnum）
  • path：路由路径
  • component：前端组件
  • sort：排序
  • status：状态（参考 StatusEnum）
  • parentId：父级ID
  • 审计字段：同上
• 部门（SysDept）
  • id：主键，雪花ID
  • deptCode：部门编码，唯一
  • deptName：部门名称
  • sort：排序
  • status：状态（参考 StatusEnum）
  • parentId：父级ID
  • 审计字段：同上
• 身份（AuthIdentity）
  • id：主键，雪花ID
  • identityType：身份类型（参考 IdentityTypeEnum）
  • identityValue：身份值，唯一或组合唯一
  • userId：用户ID
  • provider：提供方
  • openId、unionId：第三方标识
  • status：状态（参考 StatusEnum）
  • 审计字段：同上
• 文件（FileInfo）
  • id：主键，雪花ID
  • bucket：存储桶
  • objectKey：对象键，唯一
  • fileName：文件名
  • fileSize：文件大小
  • mimeType：MIME类型
  • md5：文件哈希
  • status：状态（参考 StatusEnum）
  • 审计字段：同上

更新 角色实体新增了builtin字段和数据范围验证规则。

章节来源

• AuthUser.java
• SysRole.java
• SysMenu.java
• SysDept.java
• AuthIdentity.java
• FileInfo.java

枚举值定义

• StatusEnum：通用状态（如启用/禁用）
• HasValueEnum：通用布尔值（是/否）
• MenuTypeEnum：菜单类型（如目录、菜单、按钮）
• IdentityTypeEnum：身份类型（如手机号、邮箱、第三方账号）
• DataScopeEnum：数据范围枚举
  • SELF(1)：仅本人
  • DEPT(2)：本部门
  • DEPT_AND_CHILD(3)：本部门及子部门
  • ALL(4)：全部数据
  • CUSTOM(5)：自定义（API操作禁止使用）

更新 数据范围枚举新增了CUSTOM选项，但在API操作中通过VALID_DATA_SCOPE_VALUES集合排除。

章节来源

• StatusEnum.java
• HasValueEnum.java
• MenuTypeEnum.java
• IdentityTypeEnum.java
• DataScopeEnum.java

默认值与填充策略

• 主键：雪花ID（CustomIdGenerator + SnowflakeIdWorker）
• 审计字段：create_by、update_by、create_time、update_time（MetaObjectFillHandler）
• 逻辑删除：enabled（CrmSqlInjector）
• 批量插入去重：InsertBatchOnDuplicateKeyUpdate
• 角色默认值
  • dataScope：默认1（仅本人）
  • sort：默认0
  • builtin：默认false

更新 角色实体新增了builtin字段的默认值策略。

章节来源

• CustomIdGenerator.java
• SnowflakeIdWorker.java
• MetaObjectFillHandler.java
• CrmSqlInjector.java
• InsertBatchOnDuplicateKeyUpdate.java
• SysRole.java

角色管理验证规则 - 新增章节

• 数据范围验证
  • 允许的dataScope值：1-4（SELF、DEPT、DEPT_AND_CHILD、ALL）
  • 禁止的值：5（CUSTOM）
  • 验证方式：VALID_DATA_SCOPE_VALUES集合检查
• 内置角色保护
  • 禁止通过接口创建builtin=true的角色
  • 禁止删除builtin=true的角色
  • 禁止修改builtin=true角色的roleCode
• 角色编码唯一性
  • 全局唯一性检查（跨ID）
  • 保存时查询数据库验证
• 参数校验
  • roleName和roleCode非空校验
  • dataScope范围校验
  • 内置角色标志位校验

章节来源

• SysRoleServiceImpl.java
• AuthConstants.java

数据迁移策略与版本兼容性

• 使用数据库迁移工具（如 Flyway/Liquibase）管理DDL变更，确保环境一致性
• 新增字段时提供默认值与向后兼容的查询逻辑
• 修改唯一约束前评估历史数据，必要时先清洗再变更
• 灰度发布：先在测试环境验证，再逐步上线生产
• 角色管理迁移注意事项
  • 新增builtin字段需设置默认值false
  • 现有角色数据无需特殊处理
  • API端点迁移从SystemController到RoleController

[本节为通用指导，不直接分析具体文件]

备份恢复方案

• 定期全量备份（每日）与增量备份（每小时）
• 关键表（用户、角色、菜单、部门、文件元数据）提高备份频率
• 恢复演练：定期执行恢复演练，验证备份有效性
• 灾难恢复：制定RTO/RPO目标，明确恢复流程与责任人
• 角色管理数据保护
  • 重点关注sys_role表的builtin字段数据
  • 角色权限分配数据（sys_role_menu）的完整性保护
  • 用户角色关联数据（sys_user_role）的一致性维护

[本节为通用指导，不直接分析具体文件]