happy-life-star/docs/superpowers/plans/2026-05-23-all-controller-chinese-annotations.md

# 全量 Controller 接口中文注解实施计划

> **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:** 为 backend-single 下全部 39 个 Controller 及其关联 Request DTO 补全 OpenAPI 中文注解（@Tag/@Operation/@Parameter/@Schema），使接口文档页面可通过清晰的中文描述理解每个接口的作用和参数含义。

**Architecture:** 在不改变现有代码结构和业务逻辑的前提下，为每个 Controller 类添加 `@Tag` 注解、为每个 public 方法添加 `@Operation` 注解、为 `@RequestParam`/`@PathVariable` 参数添加 `@Parameter` 注解、为被 Controller 直接引用的 Request DTO 字段添加 `@Schema` 注解。分 3 批实施，每批完成后编译验证。

**Tech Stack:** Spring Boot 2.7, Knife4j 4.3.0 (OpenAPI 3), Java 17, Maven

**重要规范：**
- `import io.swagger.v3.oas.annotations.tags.Tag;`
- `import io.swagger.v3.oas.annotations.Operation;`
- `import io.swagger.v3.oas.annotations.Parameter;`
- `import io.swagger.v3.oas.annotations.media.Schema;`
- `@Tag` 注解加在 `@RequestMapping` 下方
- `@Operation` 注解加在 HTTP 方法注解（@GetMapping 等）上方
- `@Parameter` 注解加在 `@RequestParam`/`@PathVariable` 之前
- 所有描述使用中文

---

## Task 1: Batch 1 — AI + 社区（7 个 Controller + 关联 DTO）

### Task 1.1: AiChatController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AiChatController.java`
- Modify: `backend-single/src/main/java/com/com/emotion/dto/request/AiChatRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/AiSummaryRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/GuestChatRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/ConversationCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/ChatStatsRequest.java`

- [ ] **Step 1: 为 AiChatController 添加 @Tag 和 @Operation 注解**

```java
// 在类级别添加 import
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;

// 在 @RequestMapping 下方添加 @Tag
@RestController
@RequestMapping("/aiChat")
@Tag(name = "AI 聊天", description = "AI 智能对话聊天接口，支持普通聊天、总结、状态查询、访客模式等")
public class AiChatController {
```

为每个方法添加 @Operation 注解（加在 @GetMapping/@PostMapping 等上方）：

```java
    @Operation(summary = "发送 AI 聊天消息", description = "向 AI 发送聊天消息，返回 AI 回复。支持指定会话 ID 和用户 ID。")
    @PostMapping(value = "/chat")
    public Result<AiChatResponse> chat(@Valid @RequestBody AiChatRequest request) {
```

```java
    @Operation(summary = "获取 AI 聊天总结", description = "获取指定会话的 AI 聊天总结，概括对话要点。")
    @PostMapping(value = "/summary")
    public Result<AiSummaryResponse> summary(@Valid @RequestBody AiSummaryRequest request) {
```

```java
    @Operation(summary = "获取 AI 状态", description = "获取当前 AI 服务的运行状态信息。")
    @GetMapping(value = "/status")
    public Result<AiStatusResponse> getStatus() {
```

```java
    @Operation(summary = "获取聊天统计数据", description = "获取指定时间范围内的聊天统计数据，包括消息数、Token 消耗等。")
    @PostMapping(value = "/stats")
    public Result<ChatStatsResponse> getStats(@Valid @RequestBody ChatStatsRequest request) {
```

```java
    @Operation(summary = "访客模式聊天", description = "未登录用户通过访客模式与 AI 进行对话，无需 token 认证。")
    @PostMapping(value = "/guestChat")
    public Result<GuestChatResponse> guestChat(@Valid @RequestBody GuestChatRequest request) {
```

```java
    @Operation(summary = "获取访客用户信息", description = "根据访客 ID 获取对应的用户信息。")
    @GetMapping(value = "/guestUserInfo")
    public Result<GuestUserInfoResponse> getGuestUserInfo(@Parameter(description = "访客 ID") @RequestParam String guestId) {
```

```java
    @Operation(summary = "创建对话会话", description = "为当前用户创建一个新的 AI 对话会话。")
    @PostMapping(value = "/createConversation")
    public Result<ConversationResponse> createConversation(@Valid @RequestBody ConversationCreateRequest request) {
```

- [ ] **Step 2: 为 AiChatRequest 添加 @Schema 注解**

```java
import io.swagger.v3.oas.annotations.media.Schema;

@Data
@EqualsAndHashCode(callSuper = true)
@Schema(description = "AI 聊天请求")
public class AiChatRequest extends BaseRequest {

    @Schema(description = "会话 ID")
    private String conversationId;

    @Schema(description = "消息内容")
    @NotBlank(message = "消息内容不能为空")
    private String message;

    @Schema(description = "用户 ID")
    private String userId;
}
```

- [ ] **Step 3: 为其他 Request DTO 添加 @Schema 注解**

AiSummaryRequest:
```java
@Schema(description = "AI 聊天总结请求")
public class AiSummaryRequest extends BaseRequest {
    @Schema(description = "会话 ID")
    private String conversationId;
}
```

GuestChatRequest:
```java
@Schema(description = "访客聊天请求")
public class GuestChatRequest {
    @Schema(description = "消息内容")
    private String message;
    @Schema(description = "访客 ID")
    private String guestId;
}
```

ConversationCreateRequest:
```java
@Schema(description = "创建对话会话请求")
public class ConversationCreateRequest {
    @Schema(description = "会话标题")
    private String title;
    @Schema(description = "初始消息内容")
    private String initialMessage;
}
```

ChatStatsRequest:
```java
@Schema(description = "聊天统计查询请求")
public class ChatStatsRequest extends BaseRequest {
    @Schema(description = "开始日期")
    private String startDate;
    @Schema(description = "结束日期")
    private String endDate;
    @Schema(description = "统计维度: daily-按天, weekly-按周, monthly-按月")
    private String granularity;
}
```

### Task 1.2: AiRoutingController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AiRoutingController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/ai/AiRuntimeRequest.java`

- [ ] **Step 1: 为 AiRoutingController 添加注解**

```java
@RestController
@RequestMapping("/aiRouting")
@Tag(name = "AI 路由管理", description = "AI 服务提供商路由管理接口，包括 Provider/Endpoint/Scene 的 CRUD、调用日志、运行时测试和流式测试")
public class AiRoutingController {
```

关键方法注解示例（其余方法类似处理）：

```java
    @Operation(summary = "创建 AI Provider", description = "创建一个新的 AI 服务提供商配置。")
    @PostMapping(value = "/providers/create")
    public Result<Void> createProvider(...) {
```

```java
    @Operation(summary = "获取 Provider 列表", description = "分页查询所有 AI 服务提供商配置。")
    @GetMapping(value = "/providers/list")
    public Result<PageResult<...>> listProviders(...) {
```

```java
    @Operation(summary = "运行时测试", description = "对指定的 AI 配置进行运行时连通性测试，支持同步和流式模式。")
    @PostMapping(value = "/runtime/test")
    public Result<AiRuntimeTestResponse> runtimeTest(@Valid @RequestBody AiRuntimeRequest request) {
```

```java
    @Operation(summary = "流式运行时测试", description = "对指定的 AI 配置进行流式运行时连通性测试，以 SSE 事件流返回结果。")
    @PostMapping(value = "/runtime/stream-test")
    public SseEmitter streamRuntimeTest(@Valid @RequestBody AiRuntimeRequest request) {
```

- [ ] **Step 2: 为 AiRuntimeRequest 添加 @Schema 注解**

```java
@Schema(description = "AI 运行时测试请求")
public class AiRuntimeRequest {
    @Schema(description = "AI 配置 ID")
    private String configId;
    @Schema(description = "测试消息内容")
    private String message;
}
```

### Task 1.3: CozeApiCallController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/CozeApiCallController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/coze/CozeApiCallPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/coze/CozeApiCallCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/coze/CozeApiCallUpdateRequest.java`

- [ ] **Step 1: 为 CozeApiCallController 添加 @Tag 注解**

```java
@RestController
@RequestMapping("/cozeApiCall")
@Tag(name = "Coze API 调用记录", description = "Coze API 调用记录的查询、创建、更新和删除接口")
public class CozeApiCallController {
```

- [ ] **Step 2: 为每个方法添加 @Operation**

```java
    @Operation(summary = "分页查询调用记录", description = "根据条件分页查询 Coze API 调用记录。")
    @PostMapping(value = "/page")
    public Result<PageResult<CozeApiCallResponse>> page(...) {
```

```java
    @Operation(summary = "获取调用记录详情", description = "根据 ID 获取单条调用记录的详细信息。")
    @GetMapping(value = "/detail")
    public Result<CozeApiCallResponse> detail(@Parameter(description = "调用记录 ID") @RequestParam String id) {
```

```java
    @Operation(summary = "创建调用记录", description = "新增一条 Coze API 调用记录。")
    @PostMapping(value = "/create")
    public Result<Void> create(...) {
```

```java
    @Operation(summary = "更新调用记录", description = "更新已有的 Coze API 调用记录。")
    @PostMapping(value = "/update")
    public Result<Void> update(...) {
```

```java
    @Operation(summary = "删除调用记录", description = "删除指定的 Coze API 调用记录。")
    @DeleteMapping(value = "/delete")
    public Result<Void> delete(@Parameter(description = "调用记录 ID") @RequestParam String id) {
```

```java
    @Operation(summary = "按用户统计调用量", description = "统计指定用户在时间范围内的 Coze API 调用次数。")
    @GetMapping(value = "/countByUser")
    public Result<Long> countByUser(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "按 Bot 统计调用量", description = "统计指定 Bot 的 Coze API 调用次数。")
    @GetMapping(value = "/countByBot")
    public Result<Long> countByBot(@Parameter(description = "Bot ID") @RequestParam String botId) {
```

```java
    @Operation(summary = "按状态统计调用量", description = "按调用状态统计 Coze API 调用次数。")
    @GetMapping(value = "/countByStatus")
    public Result<Map<String, Long>> countByStatus() {
```

```java
    @Operation(summary = "按用户统计 Token 消耗", description = "统计指定用户的 Token 总消耗量。")
    @GetMapping(value = "/tokensByUser")
    public Result<Long> tokensByUser(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "按用户统计费用", description = "统计指定用户的 API 调用总费用。")
    @GetMapping(value = "/costByUser")
    public Result<BigDecimal> costByUser(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

- [ ] **Step 3: 为 Request DTO 添加 @Schema**

CozeApiCallPageRequest:
```java
@Schema(description = "Coze API 调用记录分页查询请求")
public class CozeApiCallPageRequest extends PageRequest {
    @Schema(description = "用户 ID")
    private String userId;
    @Schema(description = "Bot ID")
    private String botId;
    @Schema(description = "调用状态")
    private String status;
}
```

CozeApiCallCreateRequest:
```java
@Schema(description = "创建 Coze API 调用记录请求")
public class CozeApiCallCreateRequest {
    @Schema(description = "用户 ID")
    private String userId;
    @Schema(description = "Bot ID")
    private String botId;
    @Schema(description = "请求参数 JSON")
    private String requestParams;
    @Schema(description = "响应结果 JSON")
    private String responseBody;
    @Schema(description = "Token 消耗量")
    private Long tokenCount;
}
```

CozeApiCallUpdateRequest:
```java
@Schema(description = "更新 Coze API 调用记录请求")
public class CozeApiCallUpdateRequest {
    @Schema(description = "调用记录 ID")
    private String id;
    @Schema(description = "调用状态")
    private String status;
    @Schema(description = "错误信息")
    private String errorMessage;
}
```

### Task 1.4: CommunityPostController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/CommunityPostController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/community/CommunityPostCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/community/CommunityPostUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/community/CommunityPostPageRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/communityPost")
@Tag(name = "社区帖子管理", description = "社区帖子的查询、创建、更新和删除接口")
public class CommunityPostController {
```

```java
    @Operation(summary = "分页查询社区帖子", description = "根据条件分页查询社区帖子列表。")
    @PostMapping(value = "/page")
```

```java
    @Operation(summary = "获取帖子详情", description = "根据 ID 获取社区帖子的详细信息。")
    @GetMapping(value = "/detail")
```

```java
    @Operation(summary = "创建社区帖子", description = "发布一篇新的社区帖子。")
    @PostMapping(value = "/create")
```

```java
    @Operation(summary = "更新社区帖子", description = "修改已有的社区帖子内容。")
    @PostMapping(value = "/update")
```

```java
    @Operation(summary = "删除社区帖子", description = "删除指定的社区帖子。")
    @DeleteMapping(value = "/delete")
```

- [ ] **Step 2: DTO @Schema**

CommunityPostCreateRequest 各字段加 @Schema(description = "帖子标题")、@Schema(description = "帖子内容") 等。
CommunityPostUpdateRequest 各字段加 @Schema(description = "帖子 ID")、@Schema(description = "更新后的标题") 等。
CommunityPostPageRequest 各字段加 @Schema(description = "页码")、@Schema(description = "每页数量") 等。

### Task 1.5: CommentController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/CommentController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/comment/CommentCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/comment/CommentUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/comment/CommentPageRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/comment")
@Tag(name = "评论管理", description = "评论的查询、创建、更新和删除接口")
public class CommentController {
```

```java
    @Operation(summary = "分页查询评论", description = "根据条件分页查询评论列表。")
    @PostMapping(value = "/page")
```

```java
    @Operation(summary = "创建评论", description = "对指定目标发表一条新评论。")
    @PostMapping(value = "/create")
```

```java
    @Operation(summary = "更新评论", description = "修改已有评论的内容。")
    @PostMapping(value = "/update")
```

```java
    @Operation(summary = "删除评论", description = "删除指定的评论。")
    @DeleteMapping(value = "/delete")
```

```java
    @Operation(summary = "获取评论详情", description = "根据 ID 获取评论的详细信息。")
    @GetMapping(value = "/detail")
```

### Task 1.6: SocialContentController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/SocialContentController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/social/SocialContentManualImportRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/social/SocialContentLinkImportRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/social/SocialContentApprovalRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/socialContent")
@Tag(name = "社交内容管理", description = "社交媒体内容的导入、截图、审核等接口")
public class SocialContentController {
```

```java
    @Operation(summary = "手动导入社交内容", description = "通过上传文本内容手动导入社交媒体数据。")
    @PostMapping(value = "/manual")
```

```java
    @Operation(summary = "链接导入社交内容", description = "通过社交媒体链接 URL 导入内容。")
    @PostMapping(value = "/link")
```

```java
    @Operation(summary = "截图导入社交内容", description = "通过上传截图图片来导入社交媒体内容。")
    @PostMapping(value = "/screenshot")
```

```java
    @Operation(summary = "获取社交内容列表", description = "查询所有已导入的社交媒体内容列表。")
    @GetMapping(value = "/list")
```

```java
    @Operation(summary = "更新内容审核状态", description = "修改指定社交内容的审核状态（通过/拒绝）。")
    @PutMapping(value = "/updateApproval")
```

```java
    @Operation(summary = "删除社交内容", description = "删除指定的社交媒体内容记录。")
    @DeleteMapping(value = "/delete")
```

### Task 1.7: SocialInsightController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/SocialInsightController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/social/SocialInsightGenerateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/social/SocialInsightUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/socialInsight")
@Tag(name = "社交洞察管理", description = "社交媒体洞察生成、查询和更新接口")
public class SocialInsightController {
```

```java
    @Operation(summary = "生成社交洞察", description = "基于用户社交数据生成 AI 分析洞察报告。")
    @PostMapping(value = "/generate")
```

```java
    @Operation(summary = "获取洞察列表", description = "查询当前用户的所有社交洞察记录。")
    @GetMapping(value = "/list")
```

```java
    @Operation(summary = "更新洞察记录", description = "更新已有洞察的状态或备注信息。")
    @PutMapping(value = "/update")
```

```java
    @Operation(summary = "删除洞察记录", description = "删除指定的社交洞察记录。")
    @DeleteMapping(value = "/delete/{id}")
```

### Task 1.8: Batch 1 编译验证

- [ ] **Step 1: 编译验证**

```bash
cd backend-single
mvn clean install -pl :backend-single -am -DskipTests
```

Expected: BUILD SUCCESS，无编译错误。

- [ ] **Step 2: 提交 Batch 1 改动**

```bash
git add backend-single/src/main/java/com/emotion/controller/AiChatController.java
git add backend-single/src/main/java/com/emotion/controller/AiRoutingController.java
# ... 添加 Batch 1 所有修改的文件
git commit -m "feat: Batch 1 — AI + 社区 Controller 中文注解补全"
```

---

## Task 2: Batch 2 — 情绪 + 日记 + 互动（11 个 Controller + 关联 DTO）

### Task 2.1: EmotionAnalysisController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/EmotionAnalysisController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionAnalysisCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionAnalysisPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionAnalysisUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/emotionAnalysis")
@Tag(name = "情绪分析管理", description = "情绪分析记录的查询、创建、更新和删除接口")
public class EmotionAnalysisController {
```

```java
    @Operation(summary = "分页查询情绪分析", description = "根据条件分页查询情绪分析记录列表。")
    @PostMapping(value = "/page")
```

```java
    @Operation(summary = "创建情绪分析", description = "基于情绪记录数据创建一条新的 AI 情绪分析报告。")
    @PostMapping(value = "/create")
```

```java
    @Operation(summary = "获取分析详情", description = "根据 ID 获取情绪分析报告的详细信息。")
    @GetMapping(value = "/detail")
```

```java
    @Operation(summary = "更新情绪分析", description = "修改已有情绪分析报告的内容。")
    @PutMapping(value = "/update")
```

```java
    @Operation(summary = "删除情绪分析", description = "删除指定的情绪分析记录。")
    @DeleteMapping(value = "/delete")
```

### Task 2.2: EmotionRecordController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/EmotionRecordController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionRecordCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionRecordPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionRecordUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/emotionRecord")
@Tag(name = "情绪记录管理", description = "用户情绪记录的查询、创建、更新、删除和统计接口")
public class EmotionRecordController {
```

```java
    @Operation(summary = "创建情绪记录", description = "记录用户当天的情绪数据，包括类型、强度、触发因素等。")
    @PostMapping(value = "/create")
```

```java
    @Operation(summary = "分页查询情绪记录", description = "根据日期范围、情绪类型等条件分页查询情绪记录。")
    @PostMapping(value = "/page")
```

```java
    @Operation(summary = "获取记录详情", description = "根据 ID 获取情绪记录的详细信息。")
    @GetMapping(value = "/detail")
```

```java
    @Operation(summary = "更新情绪记录", description = "修改已有情绪记录的内容。")
    @PutMapping(value = "/update")
```

```java
    @Operation(summary = "删除情绪记录", description = "删除指定的情绪记录。")
    @DeleteMapping(value = "/delete")
```

```java
    @Operation(summary = "获取情绪统计", description = "统计指定时间范围内的情绪数据分布。")
    @GetMapping(value = "/stats")
```

### Task 2.3: EmotionSummaryController 补充注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/EmotionSummaryController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionSummaryGenerateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EmotionSummaryStatusRequest.java`

- [ ] **Step 1: 补充缺失的 @Operation 注解**

该 Controller 已有 `@Tag("情绪总结管理")` 和部分 @Operation。检查缺失的方法级注解并补充。

```java
    @Operation(summary = "生成情绪总结", description = "基于指定时间范围的情绪记录数据，生成 AI 情绪总结报告。")
    @PostMapping(value = "/generate")
```

```java
    @Operation(summary = "查询总结状态", description = "查询指定时间段内是否已生成情绪总结及其状态。")
    @PostMapping(value = "/status")
```

### Task 2.4: DiaryPostController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/DiaryPostController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/DiaryPostCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/DiaryPostPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/DiaryPostUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/diaryPost")
@Tag(name = "日记管理", description = "用户日记帖子的查询、创建、发布、更新、删除、点赞、分享等接口")
public class DiaryPostController {
```

13 个方法的 @Operation 注解（逐一添加）：

```java
    @Operation(summary = "分页查询日记", description = "根据条件分页查询当前用户的日记帖子列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取日记详情", description = "根据 ID 获取日记帖子的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建日记", description = "创建一篇新的日记帖子。")
    @PostMapping(value = "/create")

    @Operation(summary = "发布日记", description = "将草稿状态的日记帖子发布为正式内容。")
    @PostMapping(value = "/publish")

    @Operation(summary = "更新日记", description = "修改已有日记帖子的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除日记", description = "永久删除指定的日记帖子。")
    @DeleteMapping(value = "/delete")

    @Operation(summary = "软删除日记", description = "将日记帖子标记为已删除状态（可恢复）。")
    @PutMapping(value = "/softDelete")

    @Operation(summary = "恢复日记", description = "将已软删除的日记帖子恢复为正常状态。")
    @PutMapping(value = "/restore")

    @Operation(summary = "点赞日记", description = "对指定日记帖子进行点赞操作。")
    @PostMapping(value = "/like")

    @Operation(summary = "取消点赞日记", description = "取消对指定日记帖子的点赞。")
    @PostMapping(value = "/unlike")

    @Operation(summary = "分享日记", description = "将指定日记帖子分享给其他用户。")
    @PostMapping(value = "/share")

    @Operation(summary = "设置精选日记", description = "将指定日记帖子标记为精选内容。")
    @PutMapping(value = "/setFeatured")

    @Operation(summary = "设置日记优先级", description = "修改指定日记帖子的优先级排序。")
    @PutMapping(value = "/setPriority")
```

### Task 2.5: DiaryCommentController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/DiaryCommentController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/DiaryCommentCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/DiaryCommentPageRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/diaryComment")
@Tag(name = "日记评论管理", description = "日记评论的查询、创建、更新、删除、点赞、置顶等接口")
public class DiaryCommentController {
```

11 个方法逐一添加 @Operation：

```java
    @Operation(summary = "分页查询评论", description = "分页查询指定日记的评论列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取评论树", description = "以树形结构获取日记的评论及其回复列表。")
    @GetMapping(value = "/commentTree")

    @Operation(summary = "获取评论详情", description = "根据 ID 获取评论详情。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建评论", description = "对指定日记发表一条新评论或回复。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新评论", description = "修改已有评论的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除评论", description = "永久删除指定评论。")
    @DeleteMapping(value = "/delete")

    @Operation(summary = "软删除评论", description = "将评论标记为已删除状态。")
    @PutMapping(value = "/softDelete")

    @Operation(summary = "恢复评论", description = "恢复已软删除的评论。")
    @PutMapping(value = "/restore")

    @Operation(summary = "点赞评论", description = "对指定评论进行点赞。")
    @PostMapping(value = "/like")

    @Operation(summary = "取消点赞评论", description = "取消对指定评论的点赞。")
    @PostMapping(value = "/unlike")

    @Operation(summary = "置顶评论", description = "将指定评论设为置顶显示。")
    @PutMapping(value = "/setTop")
```

### Task 2.6: GrowthTopicController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/GrowthTopicController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/growth/GrowthTopicCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/growth/GrowthTopicPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/growth/GrowthTopicUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/growthTopic")
@Tag(name = "成长话题管理", description = "成长话题的查询、创建、更新和删除接口")
public class GrowthTopicController {
```

```java
    @Operation(summary = "分页查询成长话题", description = "分页查询成长话题列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取话题详情", description = "根据 ID 获取成长话题的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建成长话题", description = "创建一个新的成长话题。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新成长话题", description = "修改已有成长话题的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除成长话题", description = "删除指定的成长话题。")
    @DeleteMapping(value = "/delete")
```

### Task 2.7: TopicInteractionController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/TopicInteractionController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/TopicInteractionCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/TopicInteractionPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/TopicInteractionUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/topicInteraction")
@Tag(name = "话题互动管理", description = "话题互动记录的查询、创建、更新和删除接口")
public class TopicInteractionController {
```

5 个方法添加 @Operation：

```java
    @Operation(summary = "分页查询互动记录", description = "分页查询话题互动记录列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取互动详情", description = "根据 ID 获取互动记录的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建互动记录", description = "创建一条新的话题互动记录。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新互动记录", description = "修改已有话题互动的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除互动记录", description = "删除指定的话题互动记录。")
    @DeleteMapping(value = "/delete")
```

### Task 2.8: ConversationController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/ConversationController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/ConversationPageRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/conversation")
@Tag(name = "会话管理", description = "AI 对话会话的查询、创建、更新、删除和状态管理接口")
public class ConversationController {
```

8 个方法添加 @Operation：

```java
    @Operation(summary = "分页查询会话", description = "分页查询当前用户的对话会话列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取会话详情", description = "根据 ID 获取会话的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建会话", description = "创建一个新的 AI 对话会话。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新会话", description = "修改已有会话的标题等属性。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除会话", description = "删除指定的对话会话。")
    @DeleteMapping(value = "/delete")

    @Operation(summary = "获取活跃会话", description = "获取当前用户最近的活跃会话列表。")
    @GetMapping(value = "/active")

    @Operation(summary = "获取归档会话", description = "获取当前用户已归档的会话列表。")
    @GetMapping(value = "/archived")

    @Operation(summary = "获取会话状态", description = "获取指定会话的当前状态信息。")
    @GetMapping(value = "/status")
```

### Task 2.9: MessageController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/MessageController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/MessageCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/MessagePageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/MessageSearchRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/MessageRecentRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/message")
@Tag(name = "消息管理", description = "会话消息的查询、创建、搜索、更新和删除接口")
public class MessageController {
```

7 个方法添加 @Operation：

```java
    @Operation(summary = "创建消息", description = "在指定会话中创建一条新消息。")
    @PostMapping(value = "/create")

    @Operation(summary = "获取消息详情", description = "根据 ID 获取消息的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "分页查询消息", description = "分页查询指定会话的消息列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "搜索消息", description = "根据关键词在指定会话中搜索消息内容。")
    @PostMapping(value = "/search")

    @Operation(summary = "获取最近消息", description = "获取指定会话最近的消息列表。")
    @PostMapping(value = "/recent")

    @Operation(summary = "更新消息", description = "修改指定消息的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除消息", description = "删除指定的消息记录。")
    @DeleteMapping(value = "/delete")
```

### Task 2.10: UserProfileController 补充注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/UserProfileController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/userprofile/UserProfileCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/userprofile/UserProfileUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/userprofile/UserProfilePageRequest.java`

- [ ] **Step 1: 补充 @Operation 注解（该 Controller 已有 @Tag 但方法级注解缺失）**

```java
    @Operation(summary = "分页查询用户档案", description = "分页查询用户档案列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取档案详情", description = "根据 ID 获取用户档案详情。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建用户档案", description = "为当前用户创建个人档案，包含昵称、MBTI 人格类型、童年经历等。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新用户档案", description = "更新当前用户的个人档案信息。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除用户档案", description = "删除指定的用户档案。")
    @DeleteMapping(value = "/delete")

    @Operation(summary = "迁移生活事件", description = "将生活事件模块的数据迁移到用户档案中。")
    @PostMapping(value = "/migrateLifeEvents")

    @Operation(summary = "获取档案 AI 设置", description = "获取用户档案关联的 AI 配置信息。")
    @GetMapping(value = "/getAiSettings")

    @Operation(summary = "更新档案 AI 设置", description = "更新用户档案关联的 AI 配置。")
    @PostMapping(value = "/updateAiSettings")
```

### Task 2.11: AchievementController 补充注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AchievementController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/achievement/AchievementCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/achievement/AchievementPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/achievement/AchievementUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/achievement/AchievementProgressUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/achievement/AchievementUnlockRequest.java`

- [ ] **Step 1: 补充 @Parameter 注解（已有 @Tag 和 @Operation，但缺少 @RequestParam 的 @Parameter）**

为所有 `@RequestParam` 参数添加 `@Parameter(description = "...")` 注解：

```java
    @Operation(summary = "分页查询成就", description = "分页查询成就列表。")
    @PostMapping(value = "/page")
    public Result<PageResult<AchievementResponse>> page(@Validated AchievementPageRequest request) {
```

```java
    @Operation(summary = "获取成就详情", description = "根据 ID 获取成就详情。")
    @GetMapping(value = "/detail")
    public Result<AchievementResponse> getById(@Parameter(description = "成就 ID") @RequestParam String id) {
```

```java
    @Operation(summary = "创建成就", description = "创建一个新的成就。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新成就", description = "更新指定成就的信息。")
    @PostMapping(value = "/update")

    @Operation(summary = "删除成就", description = "删除指定的成就。")
    @DeleteMapping(value = "/delete")

    @Operation(summary = "获取用户成就列表", description = "获取指定用户的所有成就及其进度。")
    @GetMapping(value = "/userAchievements")
    public Result<List<AchievementResponse>> getUserAchievements(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "更新成就进度", description = "更新指定成就的完成进度。")
    @PostMapping(value = "/updateProgress")
    public Result<Void> updateProgress(@Valid @RequestBody AchievementProgressUpdateRequest request) {
```

```java
    @Operation(summary = "解锁成就", description = "解锁指定成就（标记为已完成）。")
    @PostMapping(value = "/unlock")
    public Result<Void> unlock(@Valid @RequestBody AchievementUnlockRequest request) {
```

```java
    @Operation(summary = "获取成就统计", description = "获取用户的成就统计数据。")
    @GetMapping(value = "/stats")
    public Result<AchievementStatsResponse> getStats(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "检查成就达成", description = "检查指定用户是否有新成就可以达成。")
    @PostMapping(value = "/checkAchievement")
    public Result<List<AchievementResponse>> checkAchievement(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "批量检查成就达成", description = "批量检查多个用户的成就达成情况。")
    @PostMapping(value = "/batchCheckAchievement")
    public Result<Map<String, List<AchievementResponse>>> batchCheckAchievement(@Parameter(description = "用户 ID 列表") @RequestBody List<String> userIds) {
```

```java
    @Operation(summary = "重置成就进度", description = "重置指定成就的完成进度。")
    @PostMapping(value = "/resetProgress")
    public Result<Void> resetProgress(@Parameter(description = "成就 ID") @RequestParam String achievementId, @Parameter(description = "用户 ID") @RequestParam String userId) {
```

```java
    @Operation(summary = "获取成就排行榜", description = "获取用户成就完成数量的排行榜。")
    @GetMapping(value = "/leaderboard")
    public Result<List<AchievementLeaderboardItem>> getLeaderboard(@Parameter(description = "排名数量限制") @RequestParam(defaultValue = "10") Integer limit) {
```

```java
    @Operation(summary = "获取用户排名", description = "获取指定用户在成就排行榜中的排名。")
    @GetMapping(value = "/userRank")
    public Result<AchievementRankResponse> getUserRank(@Parameter(description = "用户 ID") @RequestParam String userId) {
```

### Task 2.12: Batch 2 编译验证

- [ ] **Step 1: 编译验证**

```bash
cd backend-single
mvn clean install -pl :backend-single -am -DskipTests
```

Expected: BUILD SUCCESS

- [ ] **Step 2: 提交 Batch 2 改动**

```bash
git add backend-single/src/main/java/com/emotion/controller/EmotionAnalysisController.java
# ... 添加 Batch 2 所有修改的文件
git commit -m "feat: Batch 2 — 情绪 + 日记 + 互动 Controller 中文注解补全"
```

---

## Task 3: Batch 3 — 其他（13 个 Controller + 关联 DTO）

### Task 3.1: LifePathController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/LifePathController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifePathCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifePathPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifePathUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/lifePath")
@Tag(name = "实现路径管理", description = "人生剧本实现路径的查询、创建、更新和删除接口")
public class LifePathController {
```

7 个方法添加 @Operation：

```java
    @Operation(summary = "分页查询实现路径", description = "分页查询当前用户的实现路径列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取实现路径列表", description = "获取当前用户的所有实现路径列表。")
    @GetMapping(value = "/listAll")

    @Operation(summary = "根据剧本ID获取路径", description = "根据剧本 ID 获取对应的实现路径。")
    @GetMapping(value = "/byScript")

    @Operation(summary = "获取路径详情", description = "根据 ID 获取实现路径的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建实现路径", description = "创建一条新的实现路径。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新实现路径", description = "修改已有实现路径的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除实现路径", description = "删除指定的实现路径。")
    @DeleteMapping(value = "/delete")
```

为 @RequestParam 添加 @Parameter：

```java
    public Result<LifePathResponse> getByScriptId(@Parameter(description = "剧本 ID") @RequestParam String scriptId) {
    public Result<LifePathResponse> getById(@Parameter(description = "路径 ID") @RequestParam String id) {
    public Result<Void> delete(@Parameter(description = "路径 ID") @RequestParam String id) {
```

### Task 3.2: RewardController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/RewardController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/reward/RewardCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/reward/RewardPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/reward/RewardUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/reward")
@Tag(name = "奖励管理", description = "奖励的查询、创建、更新和删除接口")
public class RewardController {
```

5 个方法添加 @Operation：

```java
    @Operation(summary = "分页查询奖励", description = "分页查询奖励列表。")
    @GetMapping(value = "/page")

    @Operation(summary = "获取奖励详情", description = "根据 ID 获取奖励的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建奖励", description = "创建一个新的奖励。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新奖励", description = "修改已有奖励的信息。")
    @PutMapping(value = "/update")

    @Operation(summary = "删除奖励", description = "删除指定的奖励。")
    @DeleteMapping(value = "/delete")
```

### Task 3.3: UserStatsController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/UserStatsController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/UserStatsCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/UserStatsIncrementRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/UserStatsPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/UserStatsUpdateValueRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/userStats")
@Tag(name = "用户统计管理", description = "用户统计数据的查询、创建、更新、增量操作和重新计算接口")
public class UserStatsController {
```

8 个方法添加 @Operation + @Parameter：

```java
    @Operation(summary = "分页查询用户统计", description = "分页查询用户统计数据。")
    @GetMapping(value = "/page")

    @Operation(summary = "创建或更新用户统计", description = "创建新用户统计数据或更新已有数据。")
    @PostMapping(value = "/createOrUpdate")

    @Operation(summary = "更新用户统计值", description = "直接更新指定统计项的值。")
    @PutMapping(value = "/updateStatsValue")

    @Operation(summary = "增加用户统计值", description = "对指定统计项进行增量累加操作。")
    @PutMapping(value = "/incrementStatsValue")

    @Operation(summary = "重新计算用户统计", description = "基于原始数据重新计算用户的统计值。")
    @PutMapping(value = "/recalculateUserStats")
    public Result<Void> recalculateUserStats(@Parameter(description = "用户 ID") @RequestParam String userId) {

    @Operation(summary = "重新计算所有用户统计", description = "重新计算所有用户的统计值（管理员操作）。")
    @PutMapping(value = "/recalculateAll")

    @Operation(summary = "删除过期统计数据", description = "清理超过指定天数的过期统计数据。")
    @DeleteMapping(value = "/deleteExpired")
    public Result<Void> deleteExpiredStats(@Parameter(description = "过期天数阈值", required = false) @RequestParam(defaultValue = "30") Integer days) {
```

### Task 3.4: EpicScriptController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/EpicScriptController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EpicScriptCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EpicScriptUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EpicScriptPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/EpicScriptInspirationRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/epicScript")
@Tag(name = "爽文剧本管理", description = "爽文剧本的查询、创建、更新、删除和灵感推荐接口")
public class EpicScriptController {
```

11 个方法添加 @Operation：

```java
    @Operation(summary = "分页查询爽文剧本", description = "分页查询当前用户的爽文剧本列表。")
    @PostMapping(value = "/page")

    @Operation(summary = "获取爽文剧本列表", description = "获取当前用户的所有爽文剧本列表。")
    @GetMapping(value = "/listAll")

    @Operation(summary = "获取灵感推荐", description = "获取系统推荐的灵感建议列表。")
    @GetMapping(value = "/inspiration/recommendations")

    @Operation(summary = "获取随机灵感", description = "随机获取指定数量的灵感建议。")
    @GetMapping(value = "/inspiration/random")
    public Result<List<InspirationSuggestionResponse>> getRandomInspirations(@Parameter(description = "灵感数量", required = false) @RequestParam(required = false, defaultValue = "3") Integer size) {

    @Operation(summary = "从灵感生成剧本", description = "基于选定的灵感建议生成爽文剧本。")
    @PostMapping(value = "/inspiration/generate")

    @Operation(summary = "获取剧本详情", description = "根据 ID 获取爽文剧本的详细信息。")
    @GetMapping(value = "/detail")

    @Operation(summary = "创建爽文剧本", description = "创建一个新的爽文剧本。")
    @PostMapping(value = "/create")

    @Operation(summary = "更新爽文剧本", description = "修改已有爽文剧本的内容。")
    @PutMapping(value = "/update")

    @Operation(summary = "选中剧本", description = "选中指定剧本并取消其他剧本的选中状态。")
    @PutMapping(value = "/select")

    @Operation(summary = "删除爽文剧本", description = "删除指定的爽文剧本。")
    @DeleteMapping(value = "/delete")
```

### Task 3.5: DictionaryController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/DictionaryController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/dictionary/DictionaryCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/dictionary/DictionaryPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/dictionary/DictionaryUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/dictionary")
@Tag(name = "字典管理", description = "数据字典的查询、创建、更新和删除接口")
public class DictionaryController {
```

5 个方法添加 @Operation。

### Task 3.6: GuestUserController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/GuestUserController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/guest/GuestUserCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/guest/GuestUserPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/guest/GuestUserUpdateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/guestUser")
@Tag(name = "访客用户管理", description = "访客用户的查询、创建、更新和删除接口")
public class GuestUserController {
```

5 个方法添加 @Operation。

### Task 3.7: TtsController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/TtsController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/tts/TtsTaskCreateRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/tts")
@Tag(name = "语音合成(TTS)", description = "文字转语音任务创建和查询接口")
public class TtsController {
```

方法添加 @Operation。

### Task 3.8: AsrController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AsrController.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/asr")
@Tag(name = "语音识别(ASR)", description = "语音转文字识别接口")
public class AsrController {
```

方法添加 @Operation。

### Task 3.9: HealthController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/HealthController.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/health")
@Tag(name = "健康检查", description = "系统健康状态检查接口")
public class HealthController {
```

方法添加 @Operation(summary = "系统健康检查", description = "返回系统各组件的健康状态，包括数据库、Redis 等。")。

### Task 3.10: LifeEventController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/LifeEventController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifeEventCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifeEventUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/LifeEventPageRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/lifeEvent")
@Tag(name = "生命事件管理", description = "生命事件的查询、创建、更新和删除接口")
public class LifeEventController {
```

5 个方法添加 @Operation。

### Task 3.11: ChatWebSocketController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/ChatWebSocketController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/WebSocketRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/ws/chat")
@Tag(name = "WebSocket 聊天", description = "基于 WebSocket 的实时 AI 聊天通信接口")
public class ChatWebSocketController {
```

方法添加 @Operation。

### Task 3.12: AnalyticsController 注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AnalyticsController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/analytics/AnalyticsEventBatchRequest.java`

- [ ] **Step 1: Controller 注解**

```java
@RestController
@RequestMapping("/analytics")
@Tag(name = "事件分析", description = "前端行为事件上报和分析接口")
public class AnalyticsController {
```

方法添加 @Operation。

### Task 3.13: AiConfigController 补充注解

**Files:**
- Modify: `backend-single/src/main/java/com/emotion/controller/AiConfigController.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigCreateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigUpdateRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigPageRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigEnableRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigDefaultRequest.java`
- Modify: `backend-single/src/main/java/com/emotion/dto/request/aiconfig/AiConfigTestUpdateRequest.java`

- [ ] **Step 1: 补充缺失的 @Operation 注解（已有 @Tag 但方法级注解不全）**

为每个缺失的方法添加 @Operation。

### Task 3.14: Batch 3 编译验证

- [ ] **Step 1: 编译验证**

```bash
cd backend-single
mvn clean install -pl :backend-single -am -DskipTests
```

Expected: BUILD SUCCESS

- [ ] **Step 2: 提交 Batch 3 改动**

```bash
git add backend-single/src/main/java/com/emotion/controller/LifePathController.java
# ... 添加 Batch 3 所有修改的文件
git commit -m "feat: Batch 3 — 其他 Controller 中文注解补全"
```

---

## Task 4: 全量 DTO @Schema 注解补充

以下为各批次的 DTO 文件补充清单。所有 `@Schema` 注解格式统一：

```java
@Schema(description = "中文描述")
private String fieldName;
```

### Batch 1 DTO 列表（21 个文件）

| 文件路径 | 关键字段 |
|---------|---------|
| `dto/request/AiChatRequest.java` | conversationId-会话 ID, message-消息内容, userId-用户 ID |
| `dto/request/AiSummaryRequest.java` | conversationId-会话 ID |
| `dto/request/GuestChatRequest.java` | message-消息内容, guestId-访客 ID |
| `dto/request/ConversationCreateRequest.java` | title-会话标题, initialMessage-初始消息 |
| `dto/request/ChatStatsRequest.java` | startDate-开始日期, endDate-结束日期, granularity-统计维度 |
| `dto/request/ai/AiRuntimeRequest.java` | configId-配置 ID, message-测试消息 |
| `dto/request/coze/CozeApiCallPageRequest.java` | userId-用户 ID, botId-Bot ID, status-调用状态 |
| `dto/request/coze/CozeApiCallCreateRequest.java` | userId-用户 ID, botId-Bot ID, requestParams-请求参数, responseBody-响应结果, tokenCount-Token 消耗 |
| `dto/request/coze/CozeApiCallUpdateRequest.java` | id-记录 ID, status-调用状态, errorMessage-错误信息 |
| `dto/request/community/CommunityPostCreateRequest.java` | title-帖子标题, content-帖子内容, type-帖子类型 |
| `dto/request/community/CommunityPostUpdateRequest.java` | id-帖子 ID, title-标题, content-内容 |
| `dto/request/community/CommunityPostPageRequest.java` | keyword-关键词, type-帖子类型 |
| `dto/request/comment/CommentCreateRequest.java` | targetId-目标 ID, targetType-目标类型, content-评论内容, parentId-父评论 ID |
| `dto/request/comment/CommentUpdateRequest.java` | id-评论 ID, content-评论内容 |
| `dto/request/comment/CommentPageRequest.java` | targetId-目标 ID, targetType-目标类型 |
| `dto/request/social/SocialContentManualImportRequest.java` | content-内容文本, platform-平台名称 |
| `dto/request/social/SocialContentLinkImportRequest.java` | url-社交媒体链接 |
| `dto/request/social/SocialContentApprovalRequest.java` | contentId-内容 ID, approved-是否通过 |
| `dto/request/social/SocialInsightGenerateRequest.java` | userId-用户 ID, dateRange-日期范围 |
| `dto/request/social/SocialInsightUpdateRequest.java` | id-洞察 ID, status-状态 |

### Batch 2 DTO 列表（17 个文件）

| 文件路径 | 关键字段 |
|---------|---------|
| `dto/request/EmotionAnalysisCreateRequest.java` | userId-用户 ID, startDate-开始日期, endDate-结束日期 |
| `dto/request/EmotionAnalysisPageRequest.java` | userId-用户 ID, startDate-开始日期 |
| `dto/request/EmotionAnalysisUpdateRequest.java` | id-分析 ID, analysisContent-分析内容 |
| `dto/request/EmotionRecordCreateRequest.java` | userId-用户 ID, recordDate-记录日期, emotionType-情绪类型, intensity-情绪强度, triggers-触发因素, description-描述, tags-标签, weather-天气, location-地点, activity-活动, people-相关人物, notes-备注 |
| `dto/request/EmotionRecordPageRequest.java` | startDate-开始日期, endDate-结束日期, emotionType-情绪类型 |
| `dto/request/EmotionRecordUpdateRequest.java` | id-记录 ID, emotionType-情绪类型, intensity-情绪强度, description-描述 |
| `dto/request/EmotionSummaryGenerateRequest.java` | startDate-开始日期, endDate-结束日期 |
| `dto/request/EmotionSummaryStatusRequest.java` | startDate-开始日期, endDate-结束日期 |
| `dto/request/DiaryPostCreateRequest.java` | title-日记标题, content-日记内容, mood-心情, tags-标签 |
| `dto/request/DiaryPostPageRequest.java` | startDate-开始日期, endDate-结束日期, keyword-关键词 |
| `dto/request/DiaryPostUpdateRequest.java` | id-日记 ID, title-标题, content-内容 |
| `dto/request/DiaryCommentCreateRequest.java` | diaryId-日记 ID, content-评论内容, parentId-父评论 ID |
| `dto/request/DiaryCommentPageRequest.java` | diaryId-日记 ID |
| `dto/request/growth/GrowthTopicCreateRequest.java` | title-话题标题, content-话题内容, category-话题分类 |
| `dto/request/growth/GrowthTopicPageRequest.java` | keyword-关键词, category-分类 |
| `dto/request/growth/GrowthTopicUpdateRequest.java` | id-话题 ID, title-标题, content-内容 |
| `dto/request/TopicInteractionCreateRequest.java` | topicId-话题 ID, actionType-互动类型, content-互动内容 |
| `dto/request/TopicInteractionPageRequest.java` | topicId-话题 ID, userId-用户 ID |
| `dto/request/TopicInteractionUpdateRequest.java` | id-互动 ID, content-互动内容 |
| `dto/request/ConversationPageRequest.java` | keyword-关键词, status-会话状态 |
| `dto/request/MessageCreateRequest.java` | conversationId-会话 ID, content-消息内容, messageType-消息类型 |
| `dto/request/MessagePageRequest.java` | conversationId-会话 ID, startDate-开始日期, endDate-结束日期 |
| `dto/request/MessageSearchRequest.java` | conversationId-会话 ID, keyword-搜索关键词 |
| `dto/request/MessageRecentRequest.java` | conversationId-会话 ID, limit-数量限制 |
| `dto/request/userprofile/UserProfileCreateRequest.java` | nickname-昵称, gender-性别, zodiac-星座, profession-职业, mbti-MBTI 人格类型, hobbies-兴趣爱好, childhoodDate-童年经历日期, childhoodContent-童年经历描述, peakDate-高光时刻日期, peakContent-高光时刻描述, valleyDate-低谷时期日期, valleyContent-低谷时期描述, futureVision-未来期许, idealLife-理想生活状态 |
| `dto/request/userprofile/UserProfileUpdateRequest.java` | 同 Create，增加 id-档案 ID |
| `dto/request/userprofile/UserProfilePageRequest.java` | keyword-关键词 |
| `dto/request/achievement/AchievementCreateRequest.java` | name-成就名称, description-成就描述, icon-成就图标, requiredCount-所需次数 |
| `dto/request/achievement/AchievementPageRequest.java` | keyword-关键词, type-成就类型 |
| `dto/request/achievement/AchievementUpdateRequest.java` | id-成就 ID, name-成就名称, description-成就描述 |
| `dto/request/achievement/AchievementProgressUpdateRequest.java` | achievementId-成就 ID, progress-进度值 |
| `dto/request/achievement/AchievementUnlockRequest.java` | achievementId-成就 ID, userId-用户 ID |

### Batch 3 DTO 列表（21 个文件）

| 文件路径 | 关键字段 |
|---------|---------|
| `dto/request/LifePathCreateRequest.java` | scriptId-关联剧本 ID, title-路径标题, content-路径内容 |
| `dto/request/LifePathPageRequest.java` | scriptId-剧本 ID |
| `dto/request/LifePathUpdateRequest.java` | id-路径 ID, title-标题, content-内容 |
| `dto/request/reward/RewardCreateRequest.java` | name-奖励名称, description-奖励描述, type-奖励类型, cost-所需积分 |
| `dto/request/reward/RewardPageRequest.java` | keyword-关键词, type-奖励类型 |
| `dto/request/reward/RewardUpdateRequest.java` | id-奖励 ID, name-名称, description-描述 |
| `dto/request/UserStatsCreateRequest.java` | userId-用户 ID, statsKey-统计项键, statsValue-统计值 |
| `dto/request/UserStatsIncrementRequest.java` | userId-用户 ID, statsKey-统计项键, incrementValue-增量值 |
| `dto/request/UserStatsPageRequest.java` | userId-用户 ID, statsKey-统计项键 |
| `dto/request/UserStatsUpdateValueRequest.java` | userId-用户 ID, statsKey-统计项键, newValue-新值 |
| `dto/request/EpicScriptCreateRequest.java` | title-剧本标题, content-剧本内容, inspirationId-灵感 ID |
| `dto/request/EpicScriptUpdateRequest.java` | id-剧本 ID, title-标题, content-内容 |
| `dto/request/EpicScriptPageRequest.java` | keyword-关键词 |
| `dto/request/EpicScriptInspirationRequest.java` | inspirationId-灵感 ID, theme-主题 |
| `dto/request/dictionary/DictionaryCreateRequest.java` | dictType-字典类型, dictKey-字典键, dictValue-字典值 |
| `dto/request/dictionary/DictionaryPageRequest.java` | dictType-字典类型 |
| `dto/request/dictionary/DictionaryUpdateRequest.java` | id-字典 ID, dictValue-字典值 |
| `dto/request/guest/GuestUserCreateRequest.java` | guestId-访客 ID, nickname-昵称 |
| `dto/request/guest/GuestUserPageRequest.java` | keyword-关键词 |
| `dto/request/guest/GuestUserUpdateRequest.java` | id-用户 ID, nickname-昵称 |
| `dto/request/tts/TtsTaskCreateRequest.java` | sourceType-来源类型, sourceId-来源 ID, voice-语音类型 |
| `dto/request/LifeEventCreateRequest.java` | eventType-事件类型, eventDate-事件日期, timeMode-时间模式, title-事件标题, content-事件内容, aiReply-AI 疗愈回复, emotionType-情绪类型, emotionScore-情绪评分, tags-标签 |
| `dto/request/LifeEventUpdateRequest.java` | id-事件 ID, title-标题, content-内容 |
| `dto/request/LifeEventPageRequest.java` | eventType-事件类型, startDate-开始日期, endDate-结束日期 |
| `dto/request/WebSocketRequest.java` | type-消息类型, content-消息内容, conversationId-会话 ID |
| `dto/request/analytics/AnalyticsEventBatchRequest.java` | events-事件列表 |
| `dto/request/aiconfig/AiConfigCreateRequest.java` | configName-配置名称, configKey-配置键值, configType-配置类型, provider-服务提供商, apiBaseUrl-API 地址, apiToken-API 令牌, modelName-模型名称, usageScenario-使用场景 |
| `dto/request/aiconfig/AiConfigUpdateRequest.java` | id-配置 ID + 同 Create 字段 |
| `dto/request/aiconfig/AiConfigPageRequest.java` | keyword-关键词, configType-配置类型 |
| `dto/request/aiconfig/AiConfigEnableRequest.java` | id-配置 ID, enabled-是否启用 |
| `dto/request/aiconfig/AiConfigDefaultRequest.java` | id-配置 ID |
| `dto/request/aiconfig/AiConfigTestUpdateRequest.java` | id-配置 ID, testName-测试名称 |

### DTO @Schema 注解通用模板

对每个 DTO 文件，添加以下 import（如果尚未存在）：

```java
import io.swagger.v3.oas.annotations.media.Schema;
```

在类级别添加：

```java
@Schema(description = "XX 请求")
public class XxxRequest {
```

为每个字段添加：

```java
@Schema(description = "中文描述")
private String fieldName;
```

注意：@NotBlank/@NotNull/@Size 等校验注解保持原位置不变，@Schema 放在其上方或下方均可。

---

## Task 5: 全量验收与最终验证

- [ ] **Step 1: 全量编译**

```bash
cd backend-single
mvn clean install -pl :backend-single -am -DskipTests
```

- [ ] **Step 2: 启动服务验证 OpenAPI 同步**

启动后端服务，访问 Knife4j 文档页面，验证所有接口均以中文描述显示。

- [ ] **Step 3: 前端接口管理页面验证**

访问管理后台接口管理页面，点击"手动同步"按钮，确保所有新注解的接口都能正确同步到数据库。

- [ ] **Step 4: 提交所有改动**

```bash
git add .
git commit -m "feat: 全量 Controller 及 DTO 中文注解补全完成"
```