aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/业务模块API/系统管理API.md

系统管理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提供支持。

graph TB
subgraph "系统管理API模块"
A[AdminUserApi<br/>管理员用户RPC接口]
B[PermissionApi<br/>权限RPC接口]
C[RoleApi<br/>角色RPC接口]
D[DeptApi<br/>部门RPC接口]
E[PostApi<br/>岗位RPC接口]
F[DictDataApi<br/>字典数据RPC接口]
G[LoginLogApi<br/>登录日志RPC接口]
H[OperateLogApi<br/>操作日志RPC接口]
I[MailSendApi<br/>邮件发送RPC接口]
J[NotifyMessageSendApi<br/>站内信发送RPC接口]
K[SmsCodeApi<br/>短信验证码RPC接口]
L[SmsSendApi<br/>短信发送RPC接口]
end
subgraph "系统常量"
M[ApiConstants<br/>服务名与前缀定义]
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
• ApiConstants.java

章节来源

• viewsh-module-system-api/pom.xml
• ApiConstants.java

核心组件

系统管理API模块包含以下核心组件：

服务常量定义

• 服务名称：system-server
• API前缀：/infra/api/system
• 版本号：1.0.0
• 服务端口：默认8080

统一返回格式

所有接口均采用CommonResult包装响应，包含状态码、消息和数据体，确保前后端交互的一致性。

参数校验支持

• 使用Jakarta Validation进行参数校验
• 支持嵌套对象和集合参数的校验
• 自动参数绑定和错误处理

章节来源

• ApiConstants.java

架构概览

系统管理API采用微服务架构，通过FeignClient实现模块间的RPC调用。所有接口遵循RESTful设计原则，使用HTTP方法表达操作语义，路径采用名词复数形式。

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

详细组件分析

用户管理接口

用户管理提供管理员用户的查询、校验和关联查询功能。

接口定义

• 获取单个用户：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转换工具方法
• 内置用户有效性校验逻辑
• 支持层级查询（下属用户）

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

章节来源

• AdminUserApi.java

部门管理接口

部门管理提供部门信息的查询、校验和层级查询功能。

接口定义

• 获取单个部门：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转换工具方法
• 内置部门有效性校验
• 支持递归子部门查询

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

章节来源

• DeptApi.java

岗位管理接口

岗位管理提供岗位信息的查询和校验功能。

接口定义

• 校验岗位有效性：GET /infra/api/system/post/valid?ids={postIds}
• 获取岗位列表：GET /infra/api/system/post/list?ids={postIds}

关键特性

• 支持批量岗位校验
• 提供岗位Map转换工具方法
• 空集合安全处理

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

章节来源

• PostApi.java

权限管理接口

权限管理提供角色权限查询和用户角色关联查询功能。

接口定义

• 获取角色用户ID列表：GET /infra/api/system/permission/user-role-id-list-by-role-id?roleIds={roleIds}
• 校验角色有效性：GET /infra/api/system/role/valid?ids={roleIds}

classDiagram
class PermissionApi {
+getUserRoleIdListByRoleIds(roleIds) CommonResult~Set~Long~~
}
class RoleApi {
+validRoleList(ids) CommonResult~Boolean~
}
PermissionApi --> RoleApi : 依赖

图表来源

• PermissionApi.java
• RoleApi.java

章节来源

• PermissionApi.java
• RoleApi.java

字典管理接口

字典管理提供字典数据的校验功能。

接口定义

• 校验字典数据有效性：GET /infra/api/system/dict-data/valid?dictType={dictType}&values={values}

关键特性

• 支持按字典类型和值集合的批量校验
• 返回布尔结果表示校验通过性

章节来源

• DictDataApi.java

日志管理接口

日志管理提供登录日志创建和操作日志分页查询功能。

登录日志接口

• 创建登录日志：POST /infra/api/system/login-log/create
  • 请求体：LoginLogCreateReqDTO
  • 响应：CommonResult

操作日志接口

• 获取操作日志分页：GET /infra/api/system/operate-log/page
  • 查询参数：OperateLogPageReqDTO
  • 响应：CommonResult<PageResult>

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<Boolean>
Client->>OperateLog : GET /operate-log/page
OperateLog->>Service : 分页查询操作日志
Service-->>OperateLog : 返回分页结果
OperateLog-->>Client : CommonResult<PageResult>

图表来源

• LoginLogApi.java
• OperateLogApi.java

章节来源

• LoginLogApi.java
• OperateLogApi.java

通知公告接口

通知公告提供站内信的发送功能。

接口定义

• 发送站内信给管理员：POST /infra/api/system/notify/send/send-single-admin
• 发送站内信给会员：POST /infra/api/system/notify/send/send-single-member

flowchart TD
Start([开始发送站内信]) --> ChooseUser{"选择用户类型"}
ChooseUser --> |管理员| SendAdmin["发送给管理员"]
ChooseUser --> |会员| SendMember["发送给会员"]
SendAdmin --> Validate["参数校验"]
SendMember --> Validate
Validate --> CallAPI["调用通知发送API"]
CallAPI --> Return["返回消息ID"]
Return --> End([结束])

图表来源

• NotifyMessageSendApi.java

章节来源

• NotifyMessageSendApi.java

邮件短信发送接口

邮件短信发送提供邮件和短信的发送功能。

邮件发送接口

• 发送邮件给管理员：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

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
• SmsSendApi.java
• SmsCodeApi.java

章节来源

• MailSendApi.java
• SmsSendApi.java
• SmsCodeApi.java

依赖关系分析

系统管理API模块依赖于多个基础设施组件，形成完整的微服务生态。

graph TB
subgraph "外部依赖"
A[SpringDoc OpenAPI<br/>接口文档生成]
B[Jakarta Validation<br/>参数校验]
C[OpenFeign<br/>声明式HTTP客户端]
D[Hutool<br/>Java工具类库]
end
subgraph "内部模块"
E[CommonResult<br/>统一响应封装]
F[AutoTrans<br/>自动翻译]
G[RpcConstants<br/>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

章节来源

• viewsh-module-system-api/pom.xml

性能考虑

• 批量查询优化：用户、部门、岗位接口支持批量查询，减少网络开销
• 缓存策略：建议在上层服务实现适当的缓存机制
• 参数校验：前置参数校验减少无效请求
• 连接池管理：合理配置数据库连接池大小

故障排除指南

• 服务不可用：检查system-server服务状态和网络连通性
• 参数校验失败：确认请求参数格式和必填字段
• 权限不足：验证调用方权限和角色配置
• 数据不一致：检查缓存同步和事务一致性

结论

系统管理API模块提供了完整的系统管理能力，包括用户、部门、权限、字典、日志等核心功能。通过标准化的接口设计和统一的响应格式，为上层应用提供了稳定可靠的服务支撑。

附录

API调用示例

以下为典型接口调用的示例格式：

用户查询示例

GET /infra/api/system/user/list?ids=1,2,3
Response: CommonResult<List<User>>

部门校验示例

GET /infra/api/system/dept/valid?ids=101,102
Response: CommonResult<Boolean>

日志查询示例

GET /infra/api/system/operate-log/page?page=1&size=10&businessType=1
Response: CommonResult<PageResult<OperateLogRespDTO>>

错误码规范

• 200：请求成功
• 400：参数校验失败
• 401：未授权
• 403：权限不足
• 500：服务器内部错误