You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
26 KiB
26 KiB
系统管理API
**本文档引用的文件** - [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java) - [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java) - [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java) - [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java) - [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java) - [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java) - [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java) - [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java) - [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java) - [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java) - [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java) - [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java) - [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java) - [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java) - [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java) - [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java) - [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java) - [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java) - [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java) - [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java) - [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java) - [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java) - [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java) - [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)目录
简介
本文件为系统管理模块的API文档，覆盖部门管理、角色管理、菜单管理、用户管理等接口。内容包含：
- HTTP方法与URL路径
- 请求参数与响应格式
- RBAC权限模型使用方式与权限校验机制
- 数据范围控制与数据隔离策略
- 级联操作处理
- 完整CRUD示例、批量操作接口、树形结构数据处理
- 复杂查询条件、分页排序、导出功能实现说明
项目结构
系统管理相关能力集中在认证与安全模块中，控制器位于controller包，服务层在service与service.impl包，实体与枚举在domain包，基础能力（结果封装、工具类、数据范围等）在base模块。
graph TB
subgraph "认证与安全(crm-auth)"
C1["控制器<br/>AuthController / SystemController"]
S1["服务接口<br/>ISysDeptService / ISysMenuService / ISysRoleService / IAuthUserService"]
S2["服务实现<br/>SysDeptServiceImpl / SysMenuServiceImpl / SysRoleServiceImpl / AuthUserServiceImpl"]
E1["实体<br/>SysDept / SysMenu / SysRole / AuthUser"]
EN["枚举<br/>DataScopeEnum / MenuTypeEnum"]
end
subgraph "基础能力(crm-base)"
B1["注解与拦截<br/>@DataScope / DataScopeHelper / DataVisibilityContext"]
B2["安全工具<br/>SecurityUtils"]
B3["通用结果与分页<br/>Result / PageResult"]
B4["工具类<br/>ExcelUtil / TreeUtils"]
end
C1 --> S1
S1 --> S2
S2 --> E1
S2 --> EN
S2 --> B1
S2 --> B2
C1 --> B3
S2 --> B4
图表来源
- SystemController.java
- AuthController.java
- ISysDeptService.java
- ISysMenuService.java
- ISysRoleService.java
- IAuthUserService.java
- SysDeptServiceImpl.java
- SysMenuServiceImpl.java
- SysRoleServiceImpl.java
- AuthUserServiceImpl.java
- DataScope.java
- DataScopeHelper.java
- DataVisibilityContext.java
- SecurityUtils.java
- Result.java
- PageResult.java
- ExcelUtil.java
- TreeUtils.java
章节来源
- SystemController.java
- AuthController.java
核心组件
- 控制器层
- 系统管理控制器：提供部门、角色、菜单、用户等管理接口
- 认证控制器：提供登录、鉴权、用户信息获取等接口
- 服务层
- 部门服务：树形结构构建、级联删除、数据范围过滤
- 菜单服务：菜单树构建、类型区分、权限点映射
- 角色服务：角色CRUD、角色-菜单关联、角色-用户关联
- 用户服务：用户CRUD、用户-角色关联、数据可见性上下文
- 基础能力
- 数据范围注解与辅助：@DataScope、DataScopeHelper、DataVisibilityContext
- 安全工具：SecurityUtils（当前登录用户、权限判断）
- 通用结果与分页：Result、PageResult
- 工具类：ExcelUtil（导出）、TreeUtils（树构建）
章节来源
- SysDeptServiceImpl.java
- SysMenuServiceImpl.java
- SysRoleServiceImpl.java
- AuthUserServiceImpl.java
- DataScope.java
- DataScopeHelper.java
- DataVisibilityContext.java
- SecurityUtils.java
- Result.java
- PageResult.java
- ExcelUtil.java
- TreeUtils.java
架构总览
系统采用分层架构：控制器接收HTTP请求，调用服务层完成业务逻辑，服务层通过MyBatis访问数据库；RBAC权限模型通过注解与拦截器结合实现；数据范围控制通过@DataScope注解与上下文注入SQL片段；树形结构与导出通过工具类统一处理。
sequenceDiagram
participant Client as "客户端"
participant Controller as "SystemController"
participant Service as "ISysDeptService"
participant Impl as "SysDeptServiceImpl"
participant DB as "数据库"
participant Scope as "DataScopeHelper"
participant Utils as "SecurityUtils"
Client->>Controller : "GET /api/sys/dept/list?parentId=0"
Controller->>Utils : "获取当前用户与权限"
Controller->>Service : "listByParentId(parentId)"
Service->>Impl : "实现查询"
Impl->>Scope : "应用数据范围过滤"
Scope-->>Impl : "附加SQL片段"
Impl->>DB : "执行查询"
DB-->>Impl : "返回部门列表"
Impl-->>Service : "返回结果"
Service-->>Controller : "返回结果"
Controller-->>Client : "JSON响应"
图表来源
- SystemController.java
- ISysDeptService.java
- SysDeptServiceImpl.java
- DataScopeHelper.java
- SecurityUtils.java
详细组件分析
部门管理API
- 接口概览
- 新增部门：POST /api/sys/dept
- 更新部门：PUT /api/sys/dept
- 删除部门：DELETE /api/sys/dept/{id}
- 查询部门详情：GET /api/sys/dept/{id}
- 分页查询部门：GET /api/sys/dept/page
- 树形查询部门：GET /api/sys/dept/tree
- 导出部门：GET /api/sys/dept/export
- 权限要求
- 需要“部门管理”菜单权限，具体权限标识由菜单配置决定
- 支持数据范围控制：全部数据、本部门、本部门及子部门、仅本人
- 请求参数
- 新增/更新：部门名称、父部门ID、排序号、状态、备注等
- 分页：页码、每页条数、排序字段、排序方向、查询条件（如名称模糊）
- 树形：根节点ID或默认根
- 响应格式
- 统一Result包装，成功时data为对象或集合，失败时code与message提示
- 分页返回PageResult，包含records、total、pageNo、pageSize
- 树形返回List，含children递归结构
- 数据范围控制
- 通过@DataScope注解在服务方法上启用，自动注入SQL片段限制可见范围
- 级联操作
- 删除部门时检查是否存在子部门或关联用户，存在则拒绝或删除前提示
- 导出
- 使用ExcelUtil生成Excel流，文件名按约定命名
flowchart TD
Start(["进入删除部门"]) --> CheckChildren["检查是否存在子部门"]
CheckChildren --> HasChildren{"有子部门?"}
HasChildren --> |是| Reject["拒绝删除并返回错误"]
HasChildren --> |否| CheckUsers["检查是否有关联用户"]
CheckUsers --> HasUsers{"有关联用户?"}
HasUsers --> |是| Reject
HasUsers --> |否| Delete["执行删除"]
Delete --> Success["返回成功"]
Reject --> End(["结束"])
Success --> End
图表来源
- SysDeptServiceImpl.java
- DataScope.java
- DataScopeHelper.java
- ExcelUtil.java
章节来源
- SysDeptServiceImpl.java
- ISysDeptService.java
- SysDept.java
- DataScopeEnum.java
角色管理API
- 接口概览
- 新增角色：POST /api/sys/role
- 更新角色：PUT /api/sys/role
- 删除角色：DELETE /api/sys/role/{id}
- 查询角色详情：GET /api/sys/role/{id}
- 分页查询角色：GET /api/sys/role/page
- 分配菜单：PUT /api/sys/role/menu
- 分配用户：PUT /api/sys/role/user
- 权限要求
- 需要“角色管理”菜单权限
- 请求参数
- 新增/更新：角色编码、角色名称、排序号、状态、备注
- 分配菜单：角色ID、菜单ID数组
- 分配用户：角色ID、用户ID数组
- 响应格式
- Result包装，分页返回PageResult
- 数据范围控制
- 角色本身无数据范围，但角色关联的用户受数据范围影响
- 级联操作
- 删除角色前检查是否已分配给用户或菜单，存在则拒绝或删除前提示
classDiagram
class SysRole {
+long id
+string roleCode
+string roleName
+int sortOrder
+boolean status
+string remark
}
class SysMenu {
+long id
+string menuName
+string menuType
+string path
+string perms
+int sortOrder
+long parentId
}
class SysUserRole {
+long userId
+long roleId
}
class SysRoleMenu {
+long roleId
+long menuId
}
SysRole --> SysRoleMenu : "一对多"
SysMenu --> SysRoleMenu : "一对多"
SysRole --> SysUserRole : "一对多"
图表来源
- SysRole.java
- SysMenu.java
- SysRoleServiceImpl.java
- ISysRoleService.java
章节来源
- SysRoleServiceImpl.java
- ISysRoleService.java
- SysRole.java
菜单管理API
- 接口概览
- 新增菜单：POST /api/sys/menu
- 更新菜单：PUT /api/sys/menu
- 删除菜单：DELETE /api/sys/menu/{id}
- 查询菜单详情：GET /api/sys/menu/{id}
- 分页查询菜单：GET /api/sys/menu/page
- 树形查询菜单：GET /api/sys/menu/tree
- 导出菜单：GET /api/sys/menu/export
- 权限要求
- 需要“菜单管理”菜单权限
- 请求参数
- 新增/更新：菜单名称、菜单类型（目录/菜单/按钮）、路由路径、权限标识、父菜单ID、排序号、状态
- 树形：根节点ID或默认根
- 响应格式
- Result包装，树形返回List
- 数据范围控制
- 菜单为系统配置，通常不应用数据范围
- 级联操作
- 删除菜单时检查是否存在子菜单或关联角色，存在则拒绝或删除前提示
flowchart TD
Start(["进入删除菜单"]) --> CheckChildren["检查是否存在子菜单"]
CheckChildren --> HasChildren{"有子菜单?"}
HasChildren --> |是| Reject["拒绝删除并返回错误"]
HasChildren --> |否| CheckRoles["检查是否被角色引用"]
CheckRoles --> HasRoles{"被角色引用?"}
HasRoles --> |是| Reject
HasRoles --> |否| Delete["执行删除"]
Delete --> Success["返回成功"]
Reject --> End(["结束"])
Success --> End
图表来源
- SysMenuServiceImpl.java
- MenuTypeEnum.java
- ExcelUtil.java
章节来源
- SysMenuServiceImpl.java
- ISysMenuService.java
- SysMenu.java
- MenuTypeEnum.java
用户管理API
- 接口概览
- 新增用户：POST /api/sys/user
- 更新用户：PUT /api/sys/user
- 删除用户：DELETE /api/sys/user/{id}
- 查询用户详情：GET /api/sys/user/{id}
- 分页查询用户：GET /api/sys/user/page
- 分配角色：PUT /api/sys/user/role
- 重置密码：PUT /api/sys/user/password
- 导出用户：GET /api/sys/user/export
- 权限要求
- 需要“用户管理”菜单权限
- 请求参数
- 新增/更新：用户名、手机号、邮箱、部门ID、状态、备注
- 分配角色：用户ID、角色ID数组
- 重置密码：用户ID、新密码
- 响应格式
- Result包装，分页返回PageResult
- 数据范围控制
- 用户查询受数据范围控制，仅返回可见范围内的用户
- 级联操作
- 删除用户前检查是否有关联角色，存在则拒绝或删除前提示
sequenceDiagram
participant Client as "客户端"
participant Controller as "SystemController"
participant Service as "IAuthUserService"
participant Impl as "AuthUserServiceImpl"
participant Scope as "DataScopeHelper"
participant Utils as "SecurityUtils"
Client->>Controller : "GET /api/sys/user/page?pageNo=1&pageSize=10"
Controller->>Utils : "获取当前用户与权限"
Controller->>Service : "page(param)"
Service->>Impl : "实现分页查询"
Impl->>Scope : "应用数据范围过滤"
Scope-->>Impl : "附加SQL片段"
Impl->>Impl : "组装分页结果"
Impl-->>Service : "返回PageResult"
Service-->>Controller : "返回PageResult"
Controller-->>Client : "JSON响应"
图表来源
- AuthUserServiceImpl.java
- IAuthUserService.java
- DataScopeHelper.java
- SecurityUtils.java
章节来源
- AuthUserServiceImpl.java
- IAuthUserService.java
- AuthUser.java
RBAC权限模型与权限校验
- 模型要点
- 用户-角色-菜单三级关联，菜单包含目录、菜单、按钮三种类型
- 权限标识perms用于接口级权限控制
- 权限校验机制
- 通过SecurityUtils获取当前登录用户及其角色、菜单权限
- 控制器或服务方法可通过注解或代码进行权限判断
- 数据范围控制
- 通过@DataScope注解在服务方法上启用，DataScopeHelper根据用户的数据范围级别动态注入SQL片段
- 数据隔离策略
- 基于用户所属部门与数据范围级别，限制查询与修改的数据集
classDiagram
class SecurityUtils {
+getCurrentUser()
+hasPermission(perms)
+getRoleCodes()
}
class DataScopeHelper {
+applyScope(sql, scopeLevel)
+buildScopeClause(user)
}
class DataVisibilityContext {
+setScope(level)
+getScope()
}
SecurityUtils --> DataVisibilityContext : "设置上下文"
DataScopeHelper --> DataVisibilityContext : "读取上下文"
图表来源
- SecurityUtils.java
- DataScopeHelper.java
- DataVisibilityContext.java
- DataScope.java
章节来源
- SecurityUtils.java
- DataScopeHelper.java
- DataVisibilityContext.java
- DataScope.java
树形结构数据处理
- 部门树与菜单树
- 通过TreeUtils将扁平列表转换为树形结构
- 支持指定根节点或默认根
- 数据结构
- 节点包含id、name、parentId、children等字段
- 使用场景
- 前端渲染树形控件，后端返回标准树形结构
flowchart TD
Start(["开始构建树"]) --> LoadFlat["加载扁平列表"]
LoadFlat --> BuildMap["构建ID到节点的映射"]
BuildMap --> AttachChildren["根据parentId挂载子节点"]
AttachChildren --> FindRoot["查找根节点"]
FindRoot --> ReturnTree["返回树形结构"]
图表来源
- TreeUtils.java
- SysDeptServiceImpl.java
- SysMenuServiceImpl.java
章节来源
- TreeUtils.java
分页与复杂查询
- 分页
- 使用PageResult封装分页结果，包含records、total、pageNo、pageSize
- 支持排序字段与排序方向
- 复杂查询
- 支持模糊匹配、范围查询、多条件组合
- 通过BaseParam定义查询参数，服务层组装查询条件
flowchart TD
Start(["进入分页查询"]) --> ParseParams["解析查询参数"]
ParseParams --> BuildQuery["组装查询条件"]
BuildQuery --> ApplyScope["应用数据范围"]
ApplyScope --> Execute["执行查询"]
Execute --> WrapResult["封装分页结果"]
WrapResult --> Return["返回PageResult"]
图表来源
- PageResult.java
- DataScopeHelper.java
章节来源
- PageResult.java
导出功能
- 导出接口
- 部门、菜单、用户均提供导出接口
- 实现方式
- 使用ExcelUtil生成Excel流，文件名按约定命名
- 注意事项
- 大数据量导出建议异步处理或分批导出
flowchart TD
Start(["进入导出"]) --> QueryData["查询导出数据"]
QueryData --> GenerateExcel["使用ExcelUtil生成Excel"]
GenerateExcel --> SetHeaders["设置响应头与文件名"]
SetHeaders --> StreamOut["输出流"]
StreamOut --> End(["结束"])
图表来源
- ExcelUtil.java
章节来源
- ExcelUtil.java
依赖关系分析
- 控制器依赖服务接口，服务实现依赖实体与枚举
- 数据范围控制依赖注解与辅助类
- 工具类提供通用能力（分页、树、导出）
graph LR
Controller["SystemController"] --> Service["ISysDeptService / ISysMenuService / ISysRoleService / IAuthUserService"]
Service --> Impl["SysDeptServiceImpl / SysMenuServiceImpl / SysRoleServiceImpl / AuthUserServiceImpl"]
Impl --> Entity["SysDept / SysMenu / SysRole / AuthUser"]
Impl --> Enum["DataScopeEnum / MenuTypeEnum"]
Impl --> Base["DataScopeHelper / SecurityUtils / ExcelUtil / TreeUtils"]
图表来源
- SystemController.java
- ISysDeptService.java
- ISysMenuService.java
- ISysRoleService.java
- IAuthUserService.java
- SysDeptServiceImpl.java
- SysMenuServiceImpl.java
- SysRoleServiceImpl.java
- AuthUserServiceImpl.java
- DataScopeHelper.java
- SecurityUtils.java
- ExcelUtil.java
- TreeUtils.java
章节来源
- SystemController.java
- SysDeptServiceImpl.java
- SysMenuServiceImpl.java
- SysRoleServiceImpl.java
- AuthUserServiceImpl.java
性能考虑
- 分页查询避免全表扫描，合理使用索引
- 树形构建尽量使用内存映射减少多次查询
- 导出大文件建议使用异步任务与流式写入
- 数据范围SQL片段应简洁高效，避免复杂子查询
故障排查指南
- 权限问题
- 检查用户是否拥有对应菜单权限与权限标识
- 确认SecurityUtils是否正确获取当前用户
- 数据范围问题
- 检查@DataScope注解是否正确使用
- 确认DataVisibilityContext上下文是否正确设置
- 级联删除失败
- 检查是否存在子节点或关联记录
- 导出失败
- 检查ExcelUtil的使用方式与响应头设置
章节来源
- SecurityUtils.java
- DataScopeHelper.java
- ExcelUtil.java
结论
系统管理模块通过清晰的层次划分与统一的工具类实现了部门、角色、菜单、用户的完整管理能力。RBAC权限模型与数据范围控制提供了灵活的权限与数据隔离机制。树形结构与导出功能提升了用户体验与运维效率。建议在后续迭代中进一步优化性能与错误处理。
附录
- 统一响应格式
- code：状态码
- message：提示信息
- data：业务数据
- 分页格式
- records：数据列表
- total：总数
- pageNo：当前页码
- pageSize：每页条数