# label_backend Swagger DTO Annotation Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Make every public `label_backend` API parameter visible in Swagger with its name, type, requiredness, and meaning by replacing fixed `Map` request bodies with DTOs and adding OpenAPI annotations.
**Architecture:** Keep existing URLs, HTTP methods, JSON field names, service calls, and auth behavior unchanged. Add DTOs in the flat `com.label.dto` package, annotate Controller parameters and public schema models, and extend OpenAPI reflection tests so future endpoints cannot regress to undocumented parameters.
- [ ]**Step 1: Add DTO and parameter coverage expectations**
Add tests that fail before implementation because new DTO classes do not exist, some endpoint parameters lack `@Parameter`, and request body parameters still use `Map`.
@Schema(description = "训练样本 ID 列表", example = "[1,2,3]")
private List<Long> sampleIds;
}
```
```java
@Data
@Schema(description = "微调任务响应")
public class FinetuneJobResponse {
@Schema(description = "导出批次 ID", example = "10")
private Long batchId;
@Schema(description = "微调任务 ID", example = "glm-ft-abc123")
private String finetuneJobId;
@Schema(description = "微调任务状态，可选值：PENDING、RUNNING、SUCCESS、FAILED", example = "RUNNING")
private String status;
@Schema(description = "错误信息；任务失败时返回", example = "training file not found")
private String errorMessage;
}
```
- [ ]**Step 6: Add video and config DTOs**
Create:
```java
@Data
@Schema(description = "创建视频处理任务请求")
public class VideoProcessCreateRequest {
@Schema(description = "视频资料 ID", example = "1001")
private Long sourceId;
@Schema(description = "任务类型，可选值：EXTRACT_FRAMES、VIDEO_TO_TEXT", example = "EXTRACT_FRAMES")
private String jobType;
@Schema(description = "任务参数 JSON 字符串，例如抽帧模式、帧间隔或起止时间", example = "{\"mode\":\"interval\",\"frameInterval\":30}")
private String params;
}
```
```java
@Data
@Schema(description = "AI 服务视频处理回调请求")
public class VideoProcessCallbackRequest {
@Schema(description = "视频处理任务 ID", example = "123")
private Long jobId;
@Schema(description = "处理状态，可选值：SUCCESS、FAILED", example = "SUCCESS")
private String status;
@Schema(description = "输出文件路径；成功时返回", example = "frames/1001/0.jpg")
private String outputPath;
@Schema(description = "错误信息；失败时返回", example = "video decode failed")
private String errorMessage;
}
```
```java
@Data
@Schema(description = "系统配置更新请求")
public class SysConfigUpdateRequest {
@Schema(description = "配置值", example = "glm-4-flash")
private String value;
@Schema(description = "配置说明", example = "默认文本模型")
private String description;
}
```
```java
@Data
@Schema(description = "系统配置项响应")
public class SysConfigItemResponse {
@Schema(description = "配置键", example = "ai.defaultTextModel")
private String configKey;
@Schema(description = "配置值", example = "glm-4-flash")
private String configValue;
@Schema(description = "配置说明", example = "默认文本模型")
private String description;
@Schema(description = "配置作用域，可选值：GLOBAL、COMPANY", example = "COMPANY")
private String scope;
}
```
- [ ]**Step 7: Run test and verify partial GREEN**
Run:
```bash
mvn -Dtest=OpenApiAnnotationTest test
```
Expected: FAIL remains, but missing class errors are gone. Failures should now point to missing Controller parameter annotations and raw `Map` request bodies.
### Task 3: Annotate Common Models, Existing DTOs, and Exposed Entities
**Files:**
- Modify common result classes, existing DTOs, and exposed entity files listed above
- [ ]**Step 1: Add `@Schema` to `Result<T>` and `PageResult<T>`**
Update `Result<T>`:
```java
@Data
@Schema(description = "统一接口响应包装")
public class Result<T> {
@Schema(description = "业务状态码；成功为 SUCCESS，失败为具体错误码", example = "SUCCESS")
private String code;
@Schema(description = "接口返回主体；不同接口类型不同")
private T data;
@Schema(description = "响应消息；失败时说明错误原因", example = "参数不合法")
private String message;
}
```
Update `PageResult<T>` similarly for `items`, `total`, `page`, `pageSize`.
- [ ]**Step 2: Complete existing DTO field descriptions**
Ensure every field in `LoginRequest`, `LoginResponse`, `UserInfoResponse`, `TaskResponse`, and `SourceResponse` has `@Schema(description = ..., example = ...)`.
- [ ]**Step 3: Add class and field schemas to exposed entities**
For each exposed entity, add class-level `@Schema(description = "...")` and field-level `@Schema`.
Use these class descriptions:
-`SysCompany`: "租户公司"
-`SysUser`: "系统用户"
-`SysConfig`: "系统配置"
-`TrainingDataset`: "训练样本数据"
-`ExportBatch`: "训练数据导出批次"
-`VideoProcessJob`: "视频处理任务"
- [ ]**Step 4: Run schema coverage test**
Run:
```bash
mvn -Dtest=OpenApiAnnotationTest test
```
Expected: raw `Map` body and parameter annotation tests still fail, schema coverage should pass.
### Task 4: Refactor Controller Request Bodies to DTOs
**Files:**
- Modify Controller files listed in File Structure
- [ ]**Step 1: Replace company `Map` request bodies**
In `CompanyController`, replace:
```java
public Result<SysCompany> create(@RequestBody Map<String,String> body)
Call service with `body.getCompanyName()` and `body.getCompanyCode()`.
Apply the same pattern to `update` and `updateStatus`.
- [ ]**Step 2: Replace user `Map` request bodies**
In `UserController`, replace create/update/status/role request bodies with `UserCreateRequest`, `UserUpdateRequest`, `UserStatusUpdateRequest`, and `UserRoleUpdateRequest`.
Keep service calls unchanged except changing `body.get("field")` to DTO getters.
- [ ]**Step 3: Replace task request bodies**
In `TaskController`, use `CreateTaskRequest` and `TaskReassignRequest`.
In `SysConfigController#updateConfig`, use `SysConfigUpdateRequest`.
Service call uses `body.getValue()` and `body.getDescription()`.
- [ ]**Step 6: Replace video request bodies**
In `VideoController#createJob`, use `VideoProcessCreateRequest`.
In `VideoController#handleCallback`, use `VideoProcessCallbackRequest`.
Keep callback secret header logic unchanged.
- [ ]**Step 7: Replace reject request bodies**
In `ExtractionController#reject` and `QaController#reject`, use `RejectRequest`.
Set:
```java
String reason = body != null ? body.getReason() : null;
```
- [ ]**Step 8: Run raw Map body test**
Run:
```bash
mvn -Dtest=OpenApiAnnotationTest test
```
Expected: raw `Map` request-body test passes. Parameter description test may still fail until Task 5.
### Task 5: Add Controller Parameter and Request Body OpenAPI Descriptions
**Files:**
- Modify all Controller files
- [ ]**Step 1: Add imports**
Use:
```java
import io.swagger.v3.oas.annotations.Parameter;
```
Use fully qualified `io.swagger.v3.oas.annotations.parameters.RequestBody` for Swagger request body annotations to avoid conflict with Spring `@RequestBody`.
