feat(ops): update cleaner status and assignment logic
This commit is contained in:
414
.qoder/repowiki/zh/content/API接口文档/系统管理API.md
Normal file
414
.qoder/repowiki/zh/content/API接口文档/系统管理API.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# 系统管理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
|
||||
Reference in New Issue
Block a user