docs: 全量Controller接口中文注解补全设计文档

- 明确31个Controller需要实施（4个部分注解+27个无注解） - 按业务模块分3批：AI+社区(7)、情绪+日记+互动(11)、其他(13) - 补充每个Controller关联的完整DTO文件列表 - 定义验收标准和DTO作用范围 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 22:03:01 +08:00
parent c80c7b6bbe
commit 88bec9b5df
1 changed files with 105 additions and 0 deletions
@@ -0,0 +1,105 @@
+---
+author: 花生
+created_at: 2026-05-23
+purpose: 为所有 Controller 及关联 DTO 补全 OpenAPI 中文注解
+---
+
+# 全量 Controller 接口中文注解补全设计
+
+## 1. 目标
+
+为 `backend-single/src/main/java/com/emotion/controller/` 下所有 39 个 Controller 及其关联的 Request/Response DTO 补全 OpenAPI 注解，使接口文档页面可通过清晰的中文描述理解每个接口的作用和参数含义。
+
+## 2. 注解规范
+
+| 位置 | 注解 | 作用 |
+|------|------|------|
+| Controller 类级别 | `@Tag(name = "中文模块名", description = "中文模块描述")` | 分组展示模块功能 |
+| Controller 方法级别 | `@Operation(summary = "中文简述", description = "中文详细描述")` | 展示接口用途 |
+| 路径/查询参数 | `@Parameter(description = "中文描述", required = true)` | 说明参数含义 |
+| DTO 字段级别 | `@Schema(description = "中文描述")` | 说明请求/响应字段含义 |
+
+## 3. 当前状态
+
+### 3.1 注解状态分类
+
+| 状态 | 数量 | Controller 列表 |
+|------|------|----------------|
+| 完全注解（@Tag + 全部方法 @Operation 已补全） | 8 | AuthController、AdminAuthController、AdminController、TokenController、AdminAnalyticsController、UserController、ApiEndpointController、ApiTestProxyController |
+| 部分注解（有 @Tag，但方法级 @Operation 不全） | 4 | AiConfigController、EmotionSummaryController、AchievementController、UserProfileController |
+| 无注解 | 27 | 其余所有 |
+
+### 3.2 需要实施的 Controller（共 31 个）
+
+- **部分注解 4 个**：AiConfigController、EmotionSummaryController、AchievementController、UserProfileController — 仅补充缺失的方法级 @Operation
+- **无注解 27 个**：其余所有 — 补充 @Tag + 全部 @Operation + @Parameter + DTO @Schema
+
+## 4. 分批策略
+
+按业务模块分 3 批实施，每批独立编译验证：
+
+### Batch 1 — AI + 社区（7 个 Controller，~40 接口）
+
+| Controller | 注解状态 | 关联 DTO（Request） | 关联 DTO（Response） |
+|-----------|---------|-------------------|---------------------|
+| AiChatController | 无 | AiChatRequest, AiSummaryRequest, GuestChatRequest, ConversationCreateRequest, ChatStatsRequest | AiChatResponse, AiSummaryResponse, AiStatusResponse, ChatStatsResponse, GuestChatResponse, GuestUserInfoResponse, ConversationResponse |
+| AiRoutingController | 无 | AiRuntimeRequest | AiTestTemplateResponse, AiRuntimeTestResponse, AiStreamEvent |
+| CozeApiCallController | 无 | CozeApiCallPageRequest, CozeApiCallCreateRequest, CozeApiCallUpdateRequest | CozeApiCallResponse |
+| CommunityPostController | 无 | CommunityPostCreateRequest, CommunityPostUpdateRequest, CommunityPostPageRequest | CommunityPostResponse |
+| CommentController | 无 | CommentCreateRequest, CommentUpdateRequest, CommentPageRequest | CommentResponse |
+| SocialContentController | 无 | SocialContentApprovalRequest, SocialContentLinkImportRequest, SocialContentManualImportRequest | SocialContentItemResponse |
+| SocialInsightController | 无 | SocialInsightGenerateRequest, SocialInsightUpdateRequest | SocialProfileInsightResponse |
+
+### Batch 2 — 情绪 + 日记 + 互动（11 个 Controller，~55 接口）
+
+| Controller | 注解状态 | 关联 DTO（Request） | 关联 DTO（Response） |
+|-----------|---------|-------------------|---------------------|
+| EmotionAnalysisController | 无 | EmotionAnalysisCreateRequest, EmotionAnalysisPageRequest, EmotionAnalysisUpdateRequest | EmotionAnalysisResponse |
+| EmotionRecordController | 无 | EmotionRecordCreateRequest, EmotionRecordPageRequest, EmotionRecordUpdateRequest | EmotionRecordResponse |
+| EmotionSummaryController | 部分 | EmotionSummaryGenerateRequest, EmotionSummaryStatusRequest | EmotionSummaryGenerateResponse, EmotionSummaryStatusResponse |
+| DiaryPostController | 无 | DiaryPostCreateRequest, DiaryPostPageRequest, DiaryPostUpdateRequest | DiaryPostResponse |
+| DiaryCommentController | 无 | DiaryCommentCreateRequest, DiaryCommentPageRequest | DiaryCommentResponse |
+| GrowthTopicController | 无 | GrowthTopicCreateRequest, GrowthTopicPageRequest, GrowthTopicUpdateRequest | GrowthTopicResponse |
+| TopicInteractionController | 无 | TopicInteractionCreateRequest, TopicInteractionPageRequest, TopicInteractionUpdateRequest | TopicInteractionResponse |
+| ConversationController | 无 | ConversationCreateRequest, ConversationPageRequest | ConversationResponse |
+| MessageController | 无 | MessageCreateRequest, MessagePageRequest, MessageSearchRequest, MessageRecentRequest | MessageResponse |
+| UserProfileController | 部分 | UserProfileCreateRequest, UserProfilePageRequest, UserProfileUpdateRequest | UserProfileResponse |
+| AchievementController | 部分 | Achievement 包下所有 Request | AchievementResponse |
+
+### Batch 3 — 其他（13 个 Controller，~55 接口）
+
+| Controller | 注解状态 | 关联 DTO（Request） | 关联 DTO（Response） |
+|-----------|---------|-------------------|---------------------|
+| LifePathController | 无 | LifePathCreateRequest, LifePathPageRequest, LifePathUpdateRequest | LifePathResponse |
+| RewardController | 无 | RewardCreateRequest, RewardPageRequest, RewardUpdateRequest | RewardResponse |
+| UserStatsController | 无 | UserStatsCreateRequest, UserStatsIncrementRequest, UserStatsPageRequest, UserStatsUpdateValueRequest | UserStatsResponse |
+| EpicScriptController | 无 | EpicScriptCreateRequest, EpicScriptInspirationRequest, EpicScriptPageRequest, EpicScriptUpdateRequest | EpicScriptInspirationResponse, EpicScriptResponse, InspirationSuggestionResponse |
+| DictionaryController | 无 | DictionaryCreateRequest, DictionaryPageRequest, DictionaryUpdateRequest | DictionaryResponse |
+| GuestUserController | 无 | GuestUserCreateRequest, GuestUserPageRequest, GuestUserUpdateRequest | GuestUserResponse |
+| TtsController | 无 | TtsTaskCreateRequest | TtsTaskResponse |
+| AsrController | 无 | 无 Request（仅响应） | AsrTranscribeResponse |
+| HealthController | 无 | 无 Request/Response（简单接口） | 无 |
+| LifeEventController | 无 | LifeEventCreateRequest, LifeEventPageRequest, LifeEventUpdateRequest | LifeEventResponse |
+| ChatWebSocketController | 无 | WebSocketRequest | 无 |
+| AnalyticsController | 无 | AnalyticsEventBatchRequest | AnalyticsBatchResponse |
+| AiConfigController | 部分 | AiConfig 包下所有 Request | AiConfigResponse |
+
+## 5. 实施原则
+
+- 每个接口的 `summary` 用 5-15 字中文简述接口功能
+- `description` 用 1-2 句话补充说明，包括参数、返回值、业务规则
+- `@Parameter` 描述参数用途、是否必填、默认值
+- `@Schema` 描述字段含义，对枚举值说明可选范围
+- 已有注解的 Controller 不重复修改，仅补充缺失部分
+- 每批完成后编译验证无语法错误
+- 保持现有代码结构不变，不重构逻辑
+
+## 6. 验收标准
+
+- 所有 39 个 Controller 均有 `@Tag` 注解
+- 所有 Controller 的 public 方法均有 `@Operation` 注解
+- 所有 `@RequestParam` / `@PathVariable` 参数均有 `@Parameter` 注解
+- 所有被 Controller 直接引用的 Request DTO 类字段均有 `@Schema` 注解（不含公共响应包装类如 `Result<T>`、分页基类等）
+- 所有注解内容为中文描述
+- 编译通过，无语法错误
+- 接口管理页面同步后，所有接口显示中文描述