crm-backend-matt/.qoder/repowiki/zh/content/API参考文档/系统管理API.md

# 系统管理API

<cite>
**本文档引用的文件**   
- [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)
</cite>

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

## 简介
本文件为系统管理模块的API文档，覆盖部门管理、角色管理、菜单管理、用户管理等接口。内容包含：
- HTTP方法与URL路径
- 请求参数与响应格式
- RBAC权限模型使用方式与权限校验机制
- 数据范围控制与数据隔离策略
- 级联操作处理
- 完整CRUD示例、批量操作接口、树形结构数据处理
- 复杂查询条件、分页排序、导出功能实现说明

## 项目结构
系统管理相关能力集中在认证与安全模块中，控制器位于controller包，服务层在service与service.impl包，实体与枚举在domain包，基础能力（结果封装、工具类、数据范围等）在base模块。

```mermaid
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](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [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)
- [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)

章节来源
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)

## 核心组件
- 控制器层
  - 系统管理控制器：提供部门、角色、菜单、用户等管理接口
  - 认证控制器：提供登录、鉴权、用户信息获取等接口
- 服务层
  - 部门服务：树形结构构建、级联删除、数据范围过滤
  - 菜单服务：菜单树构建、类型区分、权限点映射
  - 角色服务：角色CRUD、角色-菜单关联、角色-用户关联
  - 用户服务：用户CRUD、用户-角色关联、数据可见性上下文
- 基础能力
  - 数据范围注解与辅助：@DataScope、DataScopeHelper、DataVisibilityContext
  - 安全工具：SecurityUtils（当前登录用户、权限判断）
  - 通用结果与分页：Result、PageResult
  - 工具类：ExcelUtil（导出）、TreeUtils（树构建）

章节来源
- [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)
- [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)

## 架构总览
系统采用分层架构：控制器接收HTTP请求，调用服务层完成业务逻辑，服务层通过MyBatis访问数据库；RBAC权限模型通过注解与拦截器结合实现；数据范围控制通过@DataScope注解与上下文注入SQL片段；树形结构与导出通过工具类统一处理。

```mermaid
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](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/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<DeptTreeNode>，含children递归结构
- 数据范围控制
  - 通过@DataScope注解在服务方法上启用，自动注入SQL片段限制可见范围
- 级联操作
  - 删除部门时检查是否存在子部门或关联用户，存在则拒绝或删除前提示
- 导出
  - 使用ExcelUtil生成Excel流，文件名按约定命名

```mermaid
flowchart TD
Start(["进入删除部门"]) --> CheckChildren["检查是否存在子部门"]
CheckChildren --> HasChildren{"有子部门?"}
HasChildren --> |是| Reject["拒绝删除并返回错误"]
HasChildren --> |否| CheckUsers["检查是否有关联用户"]
CheckUsers --> HasUsers{"有关联用户?"}
HasUsers --> |是| Reject
HasUsers --> |否| Delete["执行删除"]
Delete --> Success["返回成功"]
Reject --> End(["结束"])
Success --> End
```

图表来源
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.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)
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)

章节来源
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/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
- 数据范围控制
  - 角色本身无数据范围，但角色关联的用户受数据范围影响
- 级联操作
  - 删除角色前检查是否已分配给用户或菜单，存在则拒绝或删除前提示

```mermaid
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](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)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)

章节来源
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/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<MenuTreeNode>
- 数据范围控制
  - 菜单为系统配置，通常不应用数据范围
- 级联操作
  - 删除菜单时检查是否存在子菜单或关联角色，存在则拒绝或删除前提示

```mermaid
flowchart TD
Start(["进入删除菜单"]) --> CheckChildren["检查是否存在子菜单"]
CheckChildren --> HasChildren{"有子菜单?"}
HasChildren --> |是| Reject["拒绝删除并返回错误"]
HasChildren --> |否| CheckRoles["检查是否被角色引用"]
CheckRoles --> HasRoles{"被角色引用?"}
HasRoles --> |是| Reject
HasRoles --> |否| Delete["执行删除"]
Delete --> Success["返回成功"]
Reject --> End(["结束"])
Success --> End
```

图表来源
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)

章节来源
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/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
- 数据范围控制
  - 用户查询受数据范围控制，仅返回可见范围内的用户
- 级联操作
  - 删除用户前检查是否有关联角色，存在则拒绝或删除前提示

```mermaid
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](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java)

章节来源
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)

### RBAC权限模型与权限校验
- 模型要点
  - 用户-角色-菜单三级关联，菜单包含目录、菜单、按钮三种类型
  - 权限标识perms用于接口级权限控制
- 权限校验机制
  - 通过SecurityUtils获取当前登录用户及其角色、菜单权限
  - 控制器或服务方法可通过注解或代码进行权限判断
- 数据范围控制
  - 通过@DataScope注解在服务方法上启用，DataScopeHelper根据用户的数据范围级别动态注入SQL片段
- 数据隔离策略
  - 基于用户所属部门与数据范围级别，限制查询与修改的数据集

```mermaid
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](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.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)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)

章节来源
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.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)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)

### 树形结构数据处理
- 部门树与菜单树
  - 通过TreeUtils将扁平列表转换为树形结构
  - 支持指定根节点或默认根
- 数据结构
  - 节点包含id、name、parentId、children等字段
- 使用场景
  - 前端渲染树形控件，后端返回标准树形结构

```mermaid
flowchart TD
Start(["开始构建树"]) --> LoadFlat["加载扁平列表"]
LoadFlat --> BuildMap["构建ID到节点的映射"]
BuildMap --> AttachChildren["根据parentId挂载子节点"]
AttachChildren --> FindRoot["查找根节点"]
FindRoot --> ReturnTree["返回树形结构"]
```

图表来源
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.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)

章节来源
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

### 分页与复杂查询
- 分页
  - 使用PageResult封装分页结果，包含records、total、pageNo、pageSize
  - 支持排序字段与排序方向
- 复杂查询
  - 支持模糊匹配、范围查询、多条件组合
  - 通过BaseParam定义查询参数，服务层组装查询条件

```mermaid
flowchart TD
Start(["进入分页查询"]) --> ParseParams["解析查询参数"]
ParseParams --> BuildQuery["组装查询条件"]
BuildQuery --> ApplyScope["应用数据范围"]
ApplyScope --> Execute["执行查询"]
Execute --> WrapResult["封装分页结果"]
WrapResult --> Return["返回PageResult"]
```

图表来源
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)

章节来源
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)

### 导出功能
- 导出接口
  - 部门、菜单、用户均提供导出接口
- 实现方式
  - 使用ExcelUtil生成Excel流，文件名按约定命名
- 注意事项
  - 大数据量导出建议异步处理或分批导出

```mermaid
flowchart TD
Start(["进入导出"]) --> QueryData["查询导出数据"]
QueryData --> GenerateExcel["使用ExcelUtil生成Excel"]
GenerateExcel --> SetHeaders["设置响应头与文件名"]
SetHeaders --> StreamOut["输出流"]
StreamOut --> End(["结束"])
```

图表来源
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)

章节来源
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)

## 依赖关系分析
- 控制器依赖服务接口，服务实现依赖实体与枚举
- 数据范围控制依赖注解与辅助类
- 工具类提供通用能力（分页、树、导出）

```mermaid
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](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.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)
- [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)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.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)

章节来源
- [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)

## 性能考虑
- 分页查询避免全表扫描，合理使用索引
- 树形构建尽量使用内存映射减少多次查询
- 导出大文件建议使用异步任务与流式写入
- 数据范围SQL片段应简洁高效，避免复杂子查询

## 故障排查指南
- 权限问题
  - 检查用户是否拥有对应菜单权限与权限标识
  - 确认SecurityUtils是否正确获取当前用户
- 数据范围问题
  - 检查@DataScope注解是否正确使用
  - 确认DataVisibilityContext上下文是否正确设置
- 级联删除失败
  - 检查是否存在子节点或关联记录
- 导出失败
  - 检查ExcelUtil的使用方式与响应头设置

章节来源
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)

## 结论
系统管理模块通过清晰的层次划分与统一的工具类实现了部门、角色、菜单、用户的完整管理能力。RBAC权限模型与数据范围控制提供了灵活的权限与数据隔离机制。树形结构与导出功能提升了用户体验与运维效率。建议在后续迭代中进一步优化性能与错误处理。

## 附录
- 统一响应格式
  - code：状态码
  - message：提示信息
  - data：业务数据
- 分页格式
  - records：数据列表
  - total：总数
  - pageNo：当前页码
  - pageSize：每页条数