414 lines
25 KiB
Markdown
414 lines
25 KiB
Markdown
# 系统管理API
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/dept/DeptDO.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/dept/DeptDO.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/enums/common/SexEnum.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/enums/common/SexEnum.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件为“系统管理API”提供全面的RESTful接口文档，覆盖用户管理、权限管理、角色管理、部门管理、日志管理等核心能力。内容包括：
|
||
- 接口的HTTP方法、URL路径、请求参数与响应格式
|
||
- 请求示例与响应示例
|
||
- 参数校验规则与错误处理机制
|
||
- 访问权限控制与安全注意事项
|
||
|
||
## 项目结构
|
||
系统管理模块采用“API接口层 + 控制器层 + 服务层 + 数据访问层”的分层架构，遵循微服务间通过Feign进行RPC调用的约定。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "系统管理API层"
|
||
A1["AdminUserApi<br/>用户RPC接口"]
|
||
A2["PermissionApi<br/>权限RPC接口"]
|
||
A3["RoleApi<br/>角色RPC接口"]
|
||
A4["DeptApi<br/>部门RPC接口"]
|
||
A5["LoginLogApi<br/>登录日志RPC接口"]
|
||
A6["OperateLogApi<br/>操作日志RPC接口"]
|
||
end
|
||
subgraph "系统管理服务层"
|
||
S1["UserController<br/>用户REST控制器"]
|
||
S2["PermissionController<br/>权限REST控制器"]
|
||
S3["DeptController<br/>部门REST控制器"]
|
||
SV1["AdminUserService<br/>用户服务"]
|
||
SV2["PermissionService<br/>权限服务"]
|
||
SV3["DeptService<br/>部门服务"]
|
||
end
|
||
A1 --> S1
|
||
A2 --> S2
|
||
A3 --> S2
|
||
A4 --> S3
|
||
A5 --> S1
|
||
A6 --> S1
|
||
S1 --> SV1
|
||
S2 --> SV2
|
||
S3 --> SV3
|
||
```
|
||
|
||
图表来源
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L25-L96)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L16-L27)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java#L14-L25)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java#L19-L57)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java#L14-L25)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java#L15-L26)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L38-L182)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L28-L83)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L25-L94)
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L38-L182)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L28-L83)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L25-L94)
|
||
|
||
## 核心组件
|
||
- 用户管理：提供用户增删改查、状态变更、密码重置、分页查询、导出导入、下属查询、按部门/岗位查询等能力。
|
||
- 权限管理：提供角色菜单授权、角色数据范围授权、用户角色授权、角色有效性校验等能力。
|
||
- 角色管理：提供角色有效性校验RPC接口。
|
||
- 部门管理：提供部门增删改查、列表查询、树形子部门查询、部门有效性校验等能力。
|
||
- 日志管理：提供登录日志创建RPC接口与操作日志分页查询RPC接口。
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L49-L182)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L38-L83)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L34-L94)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java#L20-L23)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java#L21-L24)
|
||
|
||
## 架构总览
|
||
系统管理API采用“控制器 + 服务 + RPC接口”的分层设计。控制器负责对外暴露REST接口并进行权限校验；服务层封装业务逻辑；RPC接口用于跨模块调用。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant UC as "UserController"
|
||
participant US as "AdminUserService"
|
||
participant UA as "AdminUserApi(RPC)"
|
||
participant DB as "数据库"
|
||
C->>UC : "POST /system/user/create"
|
||
UC->>US : "createUser(reqVO)"
|
||
US->>DB : "插入用户记录"
|
||
DB-->>US : "返回主键"
|
||
US-->>UC : "用户ID"
|
||
UC-->>C : "200 成功 + 用户ID"
|
||
C->>UA : "GET /system/user/get?id=1"
|
||
UA->>US : "getUser(id)"
|
||
US->>DB : "查询用户"
|
||
DB-->>US : "用户对象"
|
||
US-->>UA : "用户对象"
|
||
UA-->>C : "200 成功 + 用户信息"
|
||
```
|
||
|
||
图表来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L49-L55)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L32-L35)
|
||
|
||
## 详细组件分析
|
||
|
||
### 用户管理API
|
||
- 接口概览
|
||
- 新增用户：POST /system/user/create
|
||
- 修改用户：PUT /system/user/update
|
||
- 删除用户：DELETE /system/user/delete
|
||
- 批量删除用户：DELETE /system/user/delete-list
|
||
- 重置用户密码：PUT /system/user/update-password
|
||
- 修改用户状态：PUT /system/user/update-status
|
||
- 分页查询用户：GET /system/user/page
|
||
- 获取精简用户列表：GET /system/user/list-all-simple 或 /system/user/simple-list
|
||
- 获取用户详情：GET /system/user/get
|
||
- 导出用户Excel：GET /system/user/export-excel
|
||
- 下载用户导入模板：GET /system/user/get-import-template
|
||
- 导入用户：POST /system/user/import
|
||
|
||
- 请求与响应要点
|
||
- 权限注解：@PreAuthorize 指定具体权限标识，如 system:user:create、system:user:query 等
|
||
- 参数校验：使用 @Valid、@Validated 对请求体或分页参数进行校验
|
||
- 响应统一：返回 CommonResult<T>，成功时携带数据，失败时携带错误码与消息
|
||
- 数据拼装：在控制器中结合部门服务获取部门信息，统一转换为视图对象返回
|
||
|
||
- 关键流程示意
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Ctrl as "UserController"
|
||
participant Svc as "AdminUserService"
|
||
participant DeptSvc as "DeptService"
|
||
participant DO as "AdminUserDO"
|
||
Client->>Ctrl : "GET /system/user/page?pageNo=1&pageSize=10"
|
||
Ctrl->>Svc : "getUserPage(pageReqVO)"
|
||
Svc-->>Ctrl : "PageResult<AdminUserDO>"
|
||
Ctrl->>DeptSvc : "根据用户所属部门ID获取部门映射"
|
||
DeptSvc-->>Ctrl : "Map<Long, DeptDO>"
|
||
Ctrl-->>Client : "PageResult<UserRespVO>"
|
||
```
|
||
|
||
图表来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L99-L113)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java)
|
||
|
||
- 参数与权限对照
|
||
- 新增/修改/删除/重置密码/修改状态/删除列表：均需对应权限 system:user:create、system:user:update、system:user:delete、system:user:update-password
|
||
- 分页/详情/导出/导入/精简列表：需 system:user:query、system:user:export、system:user:import
|
||
- 示例：创建用户
|
||
- 方法：POST
|
||
- 路径：/system/user/create
|
||
- 权限：@PreAuthorize("@ss.hasPermission('system:user:create')")
|
||
- 请求体：UserSaveReqVO（字段由VO定义）
|
||
- 响应：CommonResult<Long>（返回新用户ID）
|
||
|
||
- 错误处理
|
||
- 参数校验失败：返回400，提示校验错误
|
||
- 权限不足：返回403
|
||
- 业务异常：返回500，携带错误码与消息
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L49-L182)
|
||
|
||
### 权限管理API
|
||
- 接口概览
|
||
- 获得角色菜单列表：GET /system/permission/list-role-menus
|
||
- 赋予角色菜单：POST /system/permission/assign-role-menu
|
||
- 赋予角色数据范围：POST /system/permission/assign-role-data-scope
|
||
- 获得用户角色列表：GET /system/permission/list-user-roles
|
||
- 赋予用户角色：POST /system/permission/assign-user-role
|
||
|
||
- 关键流程示意
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Ctrl as "PermissionController"
|
||
participant Svc as "PermissionService"
|
||
participant Tenant as "TenantService"
|
||
Client->>Ctrl : "POST /system/permission/assign-role-menu"
|
||
Ctrl->>Tenant : "handleTenantMenu(filter未开通菜单)"
|
||
Tenant-->>Ctrl : "过滤后的菜单ID集合"
|
||
Ctrl->>Svc : "assignRoleMenu(roleId, menuIds)"
|
||
Svc-->>Ctrl : "授权完成"
|
||
Ctrl-->>Client : "200 成功"
|
||
```
|
||
|
||
图表来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L46-L56)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java)
|
||
|
||
- 参数与权限对照
|
||
- 赋予角色菜单：权限 system:permission:assign-role-menu
|
||
- 赋予角色数据范围：权限 system:permission:assign-role-data-scope
|
||
- 赋予用户角色：权限 system:permission:assign-user-role
|
||
- 示例：赋予角色菜单
|
||
- 方法：POST
|
||
- 路径：/system/permission/assign-role-menu
|
||
- 权限：@PreAuthorize("@ss.hasPermission('system:permission:assign-role-menu')")
|
||
- 请求体：PermissionAssignRoleMenuReqVO（包含 roleId、menuIds）
|
||
- 响应：CommonResult<Boolean>
|
||
|
||
- 错误处理
|
||
- 参数校验失败：返回400
|
||
- 权限不足：返回403
|
||
- 租户过滤后无可用菜单：授权结果可能为空集
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L38-L83)
|
||
|
||
### 角色管理API
|
||
- 接口概览
|
||
- 校验角色是否合法：GET /system/role/valid
|
||
- RPC接口：RoleApi.validRoleList(ids)
|
||
|
||
- 参数与权限对照
|
||
- 校验角色是否合法：GET /system/role/valid
|
||
- 方法：GET
|
||
- 路径：/system/role/valid
|
||
- 参数：ids（角色编号数组）
|
||
- 响应：CommonResult<Boolean>
|
||
|
||
- 错误处理
|
||
- 参数校验失败：返回400
|
||
- 业务异常：返回500
|
||
|
||
章节来源
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java#L20-L24)
|
||
|
||
### 部门管理API
|
||
- 接口概览
|
||
- 创建部门：POST /system/dept/create
|
||
- 更新部门：PUT /system/dept/update
|
||
- 删除部门：DELETE /system/dept/delete
|
||
- 批量删除部门：DELETE /system/dept/delete-list
|
||
- 获取部门列表：GET /system/dept/list
|
||
- 获取精简部门列表：GET /system/dept/list-all-simple 或 /system/dept/simple-list
|
||
- 获取部门详情：GET /system/dept/get
|
||
|
||
- 参数与权限对照
|
||
- 创建/更新/删除/查询：分别需要 system:dept:create、system:dept:update、system:dept:delete、system:dept:query
|
||
- 示例：创建部门
|
||
- 方法：POST
|
||
- 路径：/system/dept/create
|
||
- 权限：@PreAuthorize("@ss.hasPermission('system:dept:create')")
|
||
- 请求体：DeptSaveReqVO（字段由VO定义）
|
||
- 响应：CommonResult<Long>
|
||
|
||
- 错误处理
|
||
- 参数校验失败：返回400
|
||
- 权限不足：返回403
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L34-L94)
|
||
|
||
### 日志管理API
|
||
- 登录日志API
|
||
- 创建登录日志：POST /system/login-log/create
|
||
- 参数：LoginLogCreateReqDTO（由DTO定义）
|
||
- 响应：CommonResult<Boolean>
|
||
|
||
- 操作日志API
|
||
- 获取操作日志分页：GET /system/operate-log/page
|
||
- 参数：OperateLogPageReqDTO（由DTO定义）
|
||
- 响应：CommonResult<PageResult<OperateLogRespDTO>>
|
||
|
||
- 错误处理
|
||
- 参数校验失败：返回400
|
||
- 业务异常：返回500
|
||
|
||
章节来源
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java#L20-L23)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java#L21-L24)
|
||
|
||
### RPC接口（跨模块调用）
|
||
- 用户RPC接口：AdminUserApi
|
||
- 查询单个用户：GET /infra/user/get
|
||
- 查询用户列表：GET /infra/user/list
|
||
- 校验用户是否有效：GET /infra/user/valid
|
||
- 下属用户查询：GET /infra/user/list-by-subordinate
|
||
- 按部门/岗位查询用户：GET /infra/user/list-by-dept-id、GET /infra/user/list-by-post-id
|
||
|
||
- 权限RPC接口：PermissionApi
|
||
- 获得拥有多个角色的用户编号集合：GET /infra/permission/user-role-id-list-by-role-id
|
||
|
||
- 角色RPC接口：RoleApi
|
||
- 校验角色是否合法：GET /infra/role/valid
|
||
|
||
- 部门RPC接口：DeptApi
|
||
- 获得部门信息：GET /infra/dept/get
|
||
- 获得部门信息数组：GET /infra/dept/list
|
||
- 校验部门是否合法：GET /infra/dept/valid
|
||
- 获得指定部门的所有子部门：GET /infra/dept/list-child
|
||
|
||
章节来源
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L32-L96)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L22-L26)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java#L20-L24)
|
||
- [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java#L25-L56)
|
||
|
||
## 依赖关系分析
|
||
- 控制器到服务：控制器通过资源注入调用服务层，服务层封装业务逻辑并访问数据访问层
|
||
- 服务到RPC：服务层可调用系统管理API中的RPC接口以跨模块查询用户、部门、角色等信息
|
||
- 安全配置：系统安全配置类提供统一的安全策略与权限校验入口
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class UserController {
|
||
+createUser(reqVO)
|
||
+updateUser(reqVO)
|
||
+deleteUser(id)
|
||
+getUserPage(pageReqVO)
|
||
+getUser(id)
|
||
}
|
||
class PermissionController {
|
||
+getRoleMenuList(roleId)
|
||
+assignRoleMenu(reqVO)
|
||
+assignRoleDataScope(reqVO)
|
||
+listAdminRoles(userId)
|
||
+assignUserRole(reqVO)
|
||
}
|
||
class DeptController {
|
||
+createDept(saveReqVO)
|
||
+updateDept(saveReqVO)
|
||
+deleteDept(id)
|
||
+getDeptList(reqVO)
|
||
+getDept(id)
|
||
}
|
||
class AdminUserService
|
||
class PermissionService
|
||
class DeptService
|
||
UserController --> AdminUserService : "依赖"
|
||
PermissionController --> PermissionService : "依赖"
|
||
DeptController --> DeptService : "依赖"
|
||
```
|
||
|
||
图表来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L42-L47)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L34-L36)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L31-L33)
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java)
|
||
|
||
## 性能考量
|
||
- 分页查询：建议使用分页参数避免一次性加载大量数据
|
||
- 批量操作：优先使用批量接口减少网络往返
|
||
- 缓存与转换：在控制器层对关联数据（如部门信息）进行Map化缓存，降低重复查询成本
|
||
- 导出与导入：导出时设置无分页参数，导入时注意文件大小限制与幂等处理
|
||
|
||
## 故障排查指南
|
||
- 权限不足
|
||
- 现象：返回403
|
||
- 排查：确认当前用户是否具备所需权限标识（如 system:user:create）
|
||
- 参数校验失败
|
||
- 现象：返回400，提示字段缺失或格式错误
|
||
- 排查：检查请求体字段类型、必填项与取值范围
|
||
- 业务异常
|
||
- 现象：返回500，携带错误码与消息
|
||
- 排查：查看服务层日志，定位具体异常原因
|
||
- RPC调用失败
|
||
- 现象：跨模块查询用户/部门/角色报错
|
||
- 排查：确认RPC接口是否正确暴露、服务名与前缀是否一致
|
||
|
||
章节来源
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java#L51-L52)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java#L48-L49)
|
||
- [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java#L36-L37)
|
||
|
||
## 结论
|
||
系统管理API提供了完善的用户、权限、角色、部门与日志管理能力，采用清晰的分层架构与统一的权限控制策略，满足企业级系统的管理需求。建议在生产环境中结合安全配置与监控体系，持续优化性能与稳定性。
|
||
|
||
## 附录
|
||
- 统一响应结构
|
||
- 成功：{ "code": 0, "msg": "成功", "data": T }
|
||
- 失败：{ "code": 非0, "msg": "错误描述", "data": null }
|
||
- 常用枚举
|
||
- 性别枚举：参考 SexEnum
|
||
- 数据模型
|
||
- 用户DO：参考 AdminUserDO
|
||
- 部门DO：参考 DeptDO |