# 系统管理API
**本文档引用的文件**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml)
- [AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java)
- [PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java)
- [RoleApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java)
- [DeptApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java)
- [PostApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/PostApi.java)
- [DictDataApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dict/DictDataApi.java)
- [LoginLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java)
- [OperateLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java)
- [MailSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/mail/MailSendApi.java)
- [NotifyMessageSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/notify/NotifyMessageSendApi.java)
- [SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java)
- [SmsSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsSendApi.java)
- [ApiConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为系统管理模块的全面API接口文档，覆盖用户管理、部门管理、权限管理、字典管理、日志管理等核心功能。文档基于实际代码实现，提供RESTful风格的接口定义、请求参数、响应格式以及典型调用流程，帮助开发者快速集成和使用系统管理能力。
## 项目结构
系统管理模块采用标准的微服务分层架构，API层位于viewsh-module-system/viewsh-module-system-api中，通过OpenFeign对外暴露RPC服务，统一前缀为/system，版本号为1.0.0。模块间通过FeignClient进行声明式调用，接口文档由springdoc-openapi提供支持。
```mermaid
graph TB
subgraph "系统管理API模块"
A[AdminUserApi
管理员用户RPC接口]
B[PermissionApi
权限RPC接口]
C[RoleApi
角色RPC接口]
D[DeptApi
部门RPC接口]
E[PostApi
岗位RPC接口]
F[DictDataApi
字典数据RPC接口]
G[LoginLogApi
登录日志RPC接口]
H[OperateLogApi
操作日志RPC接口]
I[MailSendApi
邮件发送RPC接口]
J[NotifyMessageSendApi
站内信发送RPC接口]
K[SmsCodeApi
短信验证码RPC接口]
L[SmsSendApi
短信发送RPC接口]
end
subgraph "系统常量"
M[ApiConstants
服务名与前缀定义]
end
A --> M
B --> M
C --> M
D --> M
E --> M
F --> M
G --> M
H --> M
I --> M
J --> M
K --> M
L --> M
```
**图表来源**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml#L1-L49)
- [ApiConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java#L1-L24)
**章节来源**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml#L1-L49)
- [ApiConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java#L1-L24)
## 核心组件
系统管理API模块包含以下核心组件：
### 服务常量定义
- 服务名称：system-server
- API前缀：/infra/api/system
- 版本号：1.0.0
- 服务端口：默认8080
### 统一返回格式
所有接口均采用CommonResult包装响应，包含状态码、消息和数据体，确保前后端交互的一致性。
### 参数校验支持
- 使用Jakarta Validation进行参数校验
- 支持嵌套对象和集合参数的校验
- 自动参数绑定和错误处理
**章节来源**
- [ApiConstants.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java#L1-L24)
## 架构概览
系统管理API采用微服务架构，通过FeignClient实现模块间的RPC调用。所有接口遵循RESTful设计原则，使用HTTP方法表达操作语义，路径采用名词复数形式。
```mermaid
sequenceDiagram
participant Client as 客户端应用
participant API as 系统管理API
participant Service as 系统服务
participant DB as 数据库
Client->>API : HTTP请求
API->>API : 参数校验
API->>Service : Feign RPC调用
Service->>DB : 数据库操作
DB-->>Service : 查询结果
Service-->>API : 业务结果
API-->>Client : CommonResult包装响应
```
**图表来源**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml#L25-L44)
## 详细组件分析
### 用户管理接口
用户管理提供管理员用户的查询、校验和关联查询功能。
#### 接口定义
- 获取单个用户：GET /infra/api/system/user/get?id={userId}
- 批量获取用户：GET /infra/api/system/user/list?ids={userIds}
- 获取用户下属：GET /infra/api/system/user/list-by-subordinate?id={userId}
- 按部门获取用户：GET /infra/api/system/user/list-by-dept-id?deptIds={deptIds}
- 按岗位获取用户：GET /infra/api/system/user/list-by-post-id?postIds={postIds}
- 校验用户有效性：GET /infra/api/system/user/valid?ids={userIds}
#### 关键特性
- 支持批量查询优化，减少网络往返
- 提供用户Map转换工具方法
- 内置用户有效性校验逻辑
- 支持层级查询（下属用户）
```mermaid
classDiagram
class AdminUserApi {
+getUser(id) CommonResult~AdminUserRespDTO~
+getUserList(ids) CommonResult~AdminUserRespDTO[]~
+getUserListBySubordinate(id) CommonResult~AdminUserRespDTO[]~
+getUserListByDeptIds(deptIds) CommonResult~AdminUserRespDTO[]~
+getUserListByPostIds(postIds) CommonResult~AdminUserRespDTO[]~
+validateUserList(ids) CommonResult~Boolean~
+getUserMap(ids) Map~Long,AdminUserRespDTO~
}
class AdminUserRespDTO {
+Long id
+String nickname
+String status
+Date createTime
}
AdminUserApi --> AdminUserRespDTO : 返回
```
**图表来源**
- [AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L28-L96)
**章节来源**
- [AdminUserApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java#L1-L97)
### 部门管理接口
部门管理提供部门信息的查询、校验和层级查询功能。
#### 接口定义
- 获取单个部门：GET /infra/api/system/dept/get?id={deptId}
- 批量获取部门：GET /infra/api/system/dept/list?ids={deptIds}
- 校验部门有效性：GET /infra/api/system/dept/valid?ids={deptIds}
- 获取子部门：GET /infra/api/system/dept/list-child?id={deptId}
#### 关键特性
- 支持部门层级关系查询
- 提供部门Map转换工具方法
- 内置部门有效性校验
- 支持递归子部门查询
```mermaid
classDiagram
class DeptApi {
+getDept(id) CommonResult~DeptRespDTO~
+getDeptList(ids) CommonResult~DeptRespDTO[]~
+validateDeptList(ids) CommonResult~Boolean~
+getChildDeptList(id) CommonResult~DeptRespDTO[]~
+getDeptMap(ids) Map~Long,DeptRespDTO~
}
class DeptRespDTO {
+Long id
+String name
+Integer sort
+Long parentId
+String status
}
DeptApi --> DeptRespDTO : 返回
```
**图表来源**
- [DeptApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java#L21-L56)
**章节来源**
- [DeptApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java#L1-L57)
### 岗位管理接口
岗位管理提供岗位信息的查询和校验功能。
#### 接口定义
- 校验岗位有效性：GET /infra/api/system/post/valid?ids={postIds}
- 获取岗位列表：GET /infra/api/system/post/list?ids={postIds}
#### 关键特性
- 支持批量岗位校验
- 提供岗位Map转换工具方法
- 空集合安全处理
```mermaid
classDiagram
class PostApi {
+validPostList(ids) CommonResult~Boolean~
+getPostList(ids) CommonResult~PostRespDTO[]~
+getPostMap(ids) Map~Long,PostRespDTO~
}
class PostRespDTO {
+Long id
+String name
+String code
+Integer sort
+String status
}
PostApi --> PostRespDTO : 返回
```
**图表来源**
- [PostApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/PostApi.java#L22-L45)
**章节来源**
- [PostApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/PostApi.java#L1-L46)
### 权限管理接口
权限管理提供角色权限查询和用户角色关联查询功能。
#### 接口定义
- 获取角色用户ID列表：GET /infra/api/system/permission/user-role-id-list-by-role-id?roleIds={roleIds}
- 校验角色有效性：GET /infra/api/system/role/valid?ids={roleIds}
```mermaid
classDiagram
class PermissionApi {
+getUserRoleIdListByRoleIds(roleIds) CommonResult~Set~Long~~
}
class RoleApi {
+validRoleList(ids) CommonResult~Boolean~
}
PermissionApi --> RoleApi : 依赖
```
**图表来源**
- [PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L18-L27)
- [RoleApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java#L16-L25)
**章节来源**
- [PermissionApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java#L1-L27)
- [RoleApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java#L1-L25)
### 字典管理接口
字典管理提供字典数据的校验功能。
#### 接口定义
- 校验字典数据有效性：GET /infra/api/system/dict-data/valid?dictType={dictType}&values={values}
#### 关键特性
- 支持按字典类型和值集合的批量校验
- 返回布尔结果表示校验通过性
**章节来源**
- [DictDataApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dict/DictDataApi.java#L1-L32)
### 日志管理接口
日志管理提供登录日志创建和操作日志分页查询功能。
#### 登录日志接口
- 创建登录日志：POST /infra/api/system/login-log/create
- 请求体：LoginLogCreateReqDTO
- 响应：CommonResult
#### 操作日志接口
- 获取操作日志分页：GET /infra/api/system/operate-log/page
- 查询参数：OperateLogPageReqDTO
- 响应：CommonResult>
```mermaid
sequenceDiagram
participant Client as 客户端
participant LoginLog as 登录日志API
participant OperateLog as 操作日志API
participant Service as 日志服务
Client->>LoginLog : POST /login-log/create
LoginLog->>Service : 创建登录日志
Service-->>LoginLog : 返回结果
LoginLog-->>Client : CommonResult
Client->>OperateLog : GET /operate-log/page
OperateLog->>Service : 分页查询操作日志
Service-->>OperateLog : 返回分页结果
OperateLog-->>Client : CommonResult
```
**图表来源**
- [LoginLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java#L20-L24)
- [OperateLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java#L21-L25)
**章节来源**
- [LoginLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java#L1-L25)
- [OperateLogApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java#L1-L26)
### 通知公告接口
通知公告提供站内信的发送功能。
#### 接口定义
- 发送站内信给管理员：POST /infra/api/system/notify/send/send-single-admin
- 发送站内信给会员：POST /infra/api/system/notify/send/send-single-member
```mermaid
flowchart TD
Start([开始发送站内信]) --> ChooseUser{"选择用户类型"}
ChooseUser --> |管理员| SendAdmin["发送给管理员"]
ChooseUser --> |会员| SendMember["发送给会员"]
SendAdmin --> Validate["参数校验"]
SendMember --> Validate
Validate --> CallAPI["调用通知发送API"]
CallAPI --> Return["返回消息ID"]
Return --> End([结束])
```
**图表来源**
- [NotifyMessageSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/notify/NotifyMessageSendApi.java#L20-L28)
**章节来源**
- [NotifyMessageSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/notify/NotifyMessageSendApi.java#L1-L29)
### 邮件短信发送接口
邮件短信发送提供邮件和短信的发送功能。
#### 邮件发送接口
- 发送邮件给管理员：POST /infra/api/system/mail/send/send-single-admin
- 发送邮件给会员：POST /infra/api/system/mail/send/send-single-member
#### 短信发送接口
- 发送短信给管理员：POST /infra/api/system/sms/send/send-single-admin
- 发送短信给会员：POST /infra/api/system/sms/send/send-single-member
#### 短信验证码接口
- 发送验证码：POST /infra/api/system/oauth2/sms/code/send
- 使用验证码：PUT /infra/api/system/oauth2/sms/code/use
- 校验验证码：GET /infra/api/system/oauth2/sms/code/validate
```mermaid
classDiagram
class MailSendApi {
+sendSingleMailToAdmin(reqDTO) CommonResult~Long~
+sendSingleMailToMember(reqDTO) CommonResult~Long~
}
class SmsSendApi {
+sendSingleSmsToAdmin(reqDTO) CommonResult~Long~
+sendSingleSmsToMember(reqDTO) CommonResult~Long~
}
class SmsCodeApi {
+sendSmsCode(reqDTO) CommonResult~Boolean~
+useSmsCode(reqDTO) CommonResult~Boolean~
+validateSmsCode(reqDTO) CommonResult~Boolean~
}
MailSendApi --> SmsSendApi : 服务同类
SmsSendApi --> SmsCodeApi : 功能互补
```
**图表来源**
- [MailSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/mail/MailSendApi.java#L18-L28)
- [SmsSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsSendApi.java#L16-L28)
- [SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java#L22-L36)
**章节来源**
- [MailSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/mail/MailSendApi.java#L1-L29)
- [SmsSendApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsSendApi.java#L1-L29)
- [SmsCodeApi.java](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/sms/SmsCodeApi.java#L1-L37)
## 依赖关系分析
系统管理API模块依赖于多个基础设施组件，形成完整的微服务生态。
```mermaid
graph TB
subgraph "外部依赖"
A[SpringDoc OpenAPI
接口文档生成]
B[Jakarta Validation
参数校验]
C[OpenFeign
声明式HTTP客户端]
D[Hutool
Java工具类库]
end
subgraph "内部模块"
E[CommonResult
统一响应封装]
F[AutoTrans
自动翻译]
G[RpcConstants
RPC常量]
end
subgraph "系统管理API"
H[用户管理]
I[部门管理]
J[权限管理]
K[日志管理]
L[通知服务]
end
A --> H
B --> H
C --> H
D --> H
E --> H
F --> H
G --> H
```
**图表来源**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml#L25-L44)
**章节来源**
- [viewsh-module-system-api/pom.xml](file://viewsh-module-system/viewsh-module-system-api/pom.xml#L1-L49)
## 性能考虑
- 批量查询优化：用户、部门、岗位接口支持批量查询，减少网络开销
- 缓存策略：建议在上层服务实现适当的缓存机制
- 参数校验：前置参数校验减少无效请求
- 连接池管理：合理配置数据库连接池大小
## 故障排除指南
- 服务不可用：检查system-server服务状态和网络连通性
- 参数校验失败：确认请求参数格式和必填字段
- 权限不足：验证调用方权限和角色配置
- 数据不一致：检查缓存同步和事务一致性
## 结论
系统管理API模块提供了完整的系统管理能力，包括用户、部门、权限、字典、日志等核心功能。通过标准化的接口设计和统一的响应格式，为上层应用提供了稳定可靠的服务支撑。
## 附录
### API调用示例
以下为典型接口调用的示例格式：
#### 用户查询示例
```
GET /infra/api/system/user/list?ids=1,2,3
Response: CommonResult>
```
#### 部门校验示例
```
GET /infra/api/system/dept/valid?ids=101,102
Response: CommonResult
```
#### 日志查询示例
```
GET /infra/api/system/operate-log/page?page=1&size=10&businessType=1
Response: CommonResult>
```
### 错误码规范
- 200：请求成功
- 400：参数校验失败
- 401：未授权
- 403：权限不足
- 500：服务器内部错误