feat(ops): update cleaner status and assignment logic

This commit is contained in:
lzh
2026-01-19 14:56:31 +08:00
parent 73bc3b299f
commit b71558ae07
169 changed files with 57972 additions and 162 deletions

View File

@@ -0,0 +1,333 @@
# 基础设施API
<cite>
**本文引用的文件**
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java)
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java)
- [ConfigTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/config/ConfigTypeEnum.java)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java)
- [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java)
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java)
- [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java)
- [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java)
- [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向基础设施模块的API接口文档覆盖以下能力
- 系统配置管理提供配置的增删改查、分页、导出Excel、按键取值等接口明确配置分类与可见性控制。
- 文件上传下载:提供后端直传、前端直传(预签名)、文件创建、下载、删除与分页接口;说明文件类型、大小与存储策略。
- WebSocket消息推送提供基于会话或用户维度的消息推送接口支持消息类型与内容格式。
- 代码生成器API支持根据数据库表结构生成前后端代码包含模板类型枚举。
文档同时给出接口调用示例与错误处理说明,帮助开发者快速集成与排障。
## 项目结构
基础设施模块由“API接口层”和“服务端实现层”组成API层通过OpenFeign声明远程调用接口服务端实现层提供RESTful控制器与业务逻辑。
```mermaid
graph TB
subgraph "API 层"
A1["ConfigApi.java"]
A2["FileApi.java"]
A3["WebSocketSenderApi.java"]
A4["ApiConstants.java"]
A5["FileCreateReqDTO.java"]
A6["WebSocketSendReqDTO.java"]
A7["ConfigTypeEnum.java"]
A8["CodegenTemplateTypeEnum.java"]
end
subgraph "服务端实现层"
S1["ConfigController.java"]
S2["FileController.java"]
S3["WebSocketSenderApiImpl.java"]
end
A1 --> S1
A2 --> S2
A3 --> S3
```
图表来源
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
章节来源
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
## 核心组件
- 配置管理API通过Feign接口暴露配置的键值查询能力服务端提供完整的增删改查、分页与导出能力。
- 文件存储API提供文件上传后端直传/前端直传、创建、下载、删除与分页接口支持预签名URL用于前端直传。
- WebSocket消息推送API提供REST风格的发送接口支持按会话、按用户类型+用户ID、按用户类型三种推送方式。
- 代码生成器模板类型定义单表、树表、主子表等模板类型支撑代码生成器API。
章节来源
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L1-L22)
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L1-L118)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L1-L74)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L1-L138)
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
- [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java#L1-L54)
## 架构总览
基础设施模块采用“API声明 + 控制器实现”的分层架构。API层通过OpenFeign声明远程调用接口服务端实现层提供RESTful控制器统一在统一前缀下暴露HTTP接口。
```mermaid
graph TB
C1["ConfigController<br/>GET/POST/PUT/DELETE /infra/config/*"] --> SvcC["ConfigService"]
F1["FileController<br/>POST/GET /infra/file/*"] --> SvcF["FileService"]
W1["WebSocketSenderApiImpl<br/>POST /infra/websocket/send"] --> WS["WebSocketMessageSender"]
subgraph "API 声明"
A1["ConfigApi"]
A2["FileApi"]
A3["WebSocketSenderApi"]
end
A1 --> C1
A2 --> F1
A3 --> W1
```
图表来源
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L32-L118)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L36-L138)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L14-L36)
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L11-L21)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L16-L73)
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L15-L33)
## 详细组件分析
### 配置管理API
- 接口范围
- 创建配置POST /infra/config/create
- 修改配置PUT /infra/config/update
- 删除配置DELETE /infra/config/delete?id=...
- 批量删除DELETE /infra/config/delete-list?ids=...
- 查询配置GET /infra/config/get?id=...
- 键值查询GET /infra/config/get-value-by-key?key=...
- 分页查询GET /infra/config/page
- 导出ExcelGET /infra/config/export-excel
- 关键行为
- 键值查询对不可见配置进行保护,若不可见则抛出错误。
- 分页与导出支持复杂筛选条件。
- 配置分类
- 系统配置与自定义配置两类,便于区分权限与作用域。
- 生效机制
- 本节未发现显式的“立即生效”接口;键值查询接口返回当前值,建议结合缓存或配置中心实现热更新。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "ConfigController"
participant Svc as "ConfigService"
Client->>Ctrl : GET /infra/config/get-value-by-key?key=...
Ctrl->>Svc : getConfigByKey(key)
Svc-->>Ctrl : ConfigDO
alt 不可见配置
Ctrl-->>Client : 错误响应
else 可见配置
Ctrl-->>Client : 返回value
end
```
图表来源
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L82-L94)
章节来源
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L32-L118)
- [ConfigApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/config/ConfigApi.java#L11-L21)
- [ConfigTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/config/ConfigTypeEnum.java#L1-L22)
### 文件上传下载API
- 接口范围
- 后端直传POST /infra/file/uploadmultipart
- 前端直传预签名URLGET /infra/file/presigned-url?name=...&directory=...
- 创建文件记录POST /infra/file/create配合前端直传
- 下载文件GET /infra/file/{configId}/get/**(透传路径)
- 删除文件DELETE /infra/file/delete?id=...
- 批量删除DELETE /infra/file/delete-list?ids=...
- 查询文件GET /infra/file/get?id=...
- 分页查询GET /infra/file/page
- 文件类型与大小
- 服务端直传从上传文件中读取原始名称与MIME类型未见显式大小限制。
- 前端直传通过预签名URL生成上传凭证具体大小限制取决于对象存储策略。
- 存储策略
- 支持“后端直传”和“前端直传”两种模式前端直传需配合预签名URL接口使用。
- 文件创建接口可记录已上传文件信息,便于后续管理与下载。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "FileController"
participant Svc as "FileService"
Client->>Ctrl : POST /infra/file/upload
Ctrl->>Svc : createFile(content, name, directory, type)
Svc-->>Ctrl : 返回访问路径
Ctrl-->>Client : 成功响应
Client->>Ctrl : GET /infra/file/presigned-url
Ctrl->>Svc : presignPutUrl(name, directory)
Svc-->>Ctrl : 返回预签名URL
Ctrl-->>Client : 预签名URL
Client->>Ctrl : POST /infra/file/create
Ctrl->>Svc : createFile(createReqDTO)
Svc-->>Ctrl : 返回文件ID
Ctrl-->>Client : 成功响应
```
图表来源
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L46-L73)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L57-L73)
- [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java#L1-L26)
章节来源
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L36-L138)
- [FileApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/FileApi.java#L16-L73)
- [FileCreateReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/file/dto/FileCreateReqDTO.java#L1-L26)
### WebSocket消息推送API
- 接口范围
- 发送消息POST /infra/websocket/send
- 推送范围
- 按会话ID推送指定sessionId
- 按用户类型+用户ID推送指定userType与userId
- 按用户类型推送指定userType广播到该类型所有在线会话
- 消息格式
- 消息类型与内容均为字符串建议使用JSON格式承载业务数据。
- 消息持久化
- 本节未发现消息持久化接口;如需持久化,可在业务侧自行实现。
```mermaid
sequenceDiagram
participant Caller as "调用方"
participant API as "WebSocketSenderApi"
participant Impl as "WebSocketSenderApiImpl"
participant Sender as "WebSocketMessageSender"
Caller->>API : POST /infra/websocket/send
API->>Impl : send(message)
alt 指定sessionId
Impl->>Sender : send(sessionId, messageType, messageContent)
else 指定userType与userId
Impl->>Sender : send(userType, userId, messageType, messageContent)
else 仅指定userType
Impl->>Sender : send(userType, messageType, messageContent)
end
Impl-->>Caller : 成功响应
```
图表来源
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L15-L33)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L14-L36)
- [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java#L1-L26)
章节来源
- [WebSocketSenderApi.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApi.java#L1-L33)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L1-L36)
- [WebSocketSendReqDTO.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/api/websocket/dto/WebSocketSendReqDTO.java#L1-L26)
### 代码生成器API
- 模板类型
- 单表(增删改查)
- 树表(增删改查)
- 主子表:主表普通/ERP/内嵌模式,子表
- 使用场景
- 根据数据库表结构生成前后端代码,提升开发效率。
- 适用范围
- 本节提供模板类型枚举,具体生成流程在上层模块或工具链中实现。
章节来源
- [CodegenTemplateTypeEnum.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/codegen/CodegenTemplateTypeEnum.java#L1-L54)
## 依赖关系分析
- 统一前缀与版本
- 所有接口均以统一前缀与版本号组合,便于网关路由与版本管理。
- 接口命名与路径
- 配置:/infra/config/*
- 文件:/infra/file/*
- WebSocket/infra/websocket/*
- 权限控制
- 管理后台接口普遍使用权限注解进行授权校验。
```mermaid
graph LR
AC["ApiConstants.PREFIX"] --> P1["/infra/config/*"]
AC --> P2["/infra/file/*"]
AC --> P3["/infra/websocket/*"]
AC --> V["VERSION 1.0.0"]
```
图表来源
- [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java#L10-L23)
章节来源
- [ApiConstants.java](file://viewsh-module-infra/viewsh-module-infra-api/src/main/java/com/viewsh/module/infra/enums/ApiConstants.java#L1-L24)
## 性能考量
- 文件上传
- 建议对大文件采用分片上传与断点续传,减少网络波动影响。
- 前端直传模式可利用对象存储的并发上传能力,提升吞吐。
- 配置查询
- 键值查询建议结合本地缓存,降低数据库压力。
- WebSocket
- 广播推送应避免过大的消息体,建议拆分为多个小消息或压缩传输。
## 故障排查指南
- 配置键值查询失败
- 若返回空值,确认键是否存在;若抛出错误,确认配置是否可见。
- 文件下载404
- 确认路径编码与解码正确,检查文件是否存在于存储系统。
- WebSocket推送无响应
- 确认目标会话或用户是否在线;检查消息类型与内容格式是否符合预期。
章节来源
- [ConfigController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/config/ConfigController.java#L82-L94)
- [FileController.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/controller/admin/file/FileController.java#L101-L127)
- [WebSocketSenderApiImpl.java](file://viewsh-module-infra/viewsh-module-infra-server/src/main/java/com/viewsh/module/infra/api/websocket/WebSocketSenderApiImpl.java#L21-L34)
## 结论
基础设施模块提供了完善的配置管理、文件存储与WebSocket消息推送能力接口清晰、职责明确。建议在生产环境中结合缓存与对象存储优化性能并完善消息持久化与错误监控体系。
## 附录
- 接口调用示例(路径与方法)
- 配置管理
- 创建POST /infra/config/create
- 更新PUT /infra/config/update
- 删除DELETE /infra/config/delete?id=1
- 批量删除DELETE /infra/config/delete-list?ids=1,2
- 查询GET /infra/config/get?id=1
- 键值查询GET /infra/config/get-value-by-key?key=...
- 分页GET /infra/config/page
- 导出GET /infra/config/export-excel
- 文件存储
- 后端直传POST /infra/file/uploadmultipart
- 预签名URLGET /infra/file/presigned-url?name=...&directory=...
- 创建文件POST /infra/file/create
- 下载GET /infra/file/{configId}/get/**(透传路径)
- 删除DELETE /infra/file/delete?id=1
- 批量删除DELETE /infra/file/delete-list?ids=1,2
- 查询GET /infra/file/get?id=1
- 分页GET /infra/file/page
- WebSocket推送
- 发送POST /infra/websocket/send