# 系统管理API
**本文引用的文件**
- [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)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为“系统管理API”提供全面的RESTful接口文档，覆盖用户管理、权限管理、角色管理、部门管理、日志管理等核心能力。内容包括：
- 接口的HTTP方法、URL路径、请求参数与响应格式
- 请求示例与响应示例
- 参数校验规则与错误处理机制
- 访问权限控制与安全注意事项
## 项目结构
系统管理模块采用“API接口层 + 控制器层 + 服务层 + 数据访问层”的分层架构，遵循微服务间通过Feign进行RPC调用的约定。
```mermaid
graph TB
subgraph "系统管理API层"
A1["AdminUserApi
用户RPC接口"]
A2["PermissionApi
权限RPC接口"]
A3["RoleApi
角色RPC接口"]
A4["DeptApi
部门RPC接口"]
A5["LoginLogApi
登录日志RPC接口"]
A6["OperateLogApi
操作日志RPC接口"]
end
subgraph "系统管理服务层"
S1["UserController
用户REST控制器"]
S2["PermissionController
权限REST控制器"]
S3["DeptController
部门REST控制器"]
SV1["AdminUserService
用户服务"]
SV2["PermissionService
权限服务"]
SV3["DeptService
部门服务"]
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，成功时携带数据，失败时携带错误码与消息
- 数据拼装：在控制器中结合部门服务获取部门信息，统一转换为视图对象返回
- 关键流程示意
```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"
Ctrl->>DeptSvc : "根据用户所属部门ID获取部门映射"
DeptSvc-->>Ctrl : "Map"
Ctrl-->>Client : "PageResult"
```
图表来源
- [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（返回新用户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
- 错误处理
- 参数校验失败：返回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
- 错误处理
- 参数校验失败：返回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
- 错误处理
- 参数校验失败：返回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
- 操作日志API
- 获取操作日志分页：GET /system/operate-log/page
- 参数：OperateLogPageReqDTO（由DTO定义）
- 响应：CommonResult>
- 错误处理
- 参数校验失败：返回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