# 接口管理中文描述与测试面板改造 实现计划 > **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:** 为接口管理页面补全中文描述注解，并将测试面板改造为预填充参数表单 **Architecture:** 后端为 Controller 和 DTO 补全 OpenAPI 注解（@Tag/@Operation/@Parameter/@Schema），SpringDoc 自动生成中文 OpenAPI 规范；前端改造测试面板，从空白 JSON 输入框改为预填充参数的表单编辑器 **Tech Stack:** Spring Boot 2.7 + SpringDoc/Knife4j 4.x (OpenAPI3), Vue3 + Element Plus --- ## 文件结构 ### 后端改动文件（按批次） **Batch 1 (P0):** - `backend-single/src/main/java/com/emotion/controller/AdminAuthController.java` — 已有 @Operation，补全 @Parameter - `backend-single/src/main/java/com/emotion/controller/AuthController.java` — 补全缺少的 @Operation，补全 @Parameter - `backend-single/src/main/java/com/emotion/controller/AdminController.java` — 已有 @Tag/@Operation，补全 @Parameter - `backend-single/src/main/java/com/emotion/controller/TokenController.java` — 已有 @Operation，检查完整度 - `backend-single/src/main/java/com/emotion/controller/AdminAnalyticsController.java` — 新增 @Tag/@Operation - `backend-single/src/main/java/com/emotion/controller/UserController.java` — 新增 @Tag/@Operation - `backend-single/src/main/java/com/emotion/controller/UserProfileController.java` — 新增 @Tag/@Operation - `backend-single/src/main/java/com/emotion/dto/request/AdminLoginRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/AdminCreateRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/AdminUpdateRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/AdminPageRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/AdminChangePasswordRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/AdminResetPasswordRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/RefreshTokenRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/ResetPasswordRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/RegisterRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/LoginRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/UserCreateRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/UserUpdateRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/UserPageRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/UserProfileUpdateRequest.java` — 补全 @Schema - `backend-single/src/main/java/com/emotion/dto/request/analytics/AnalyticsQueryRequest.java` — 补全 @Schema ### 前端改动文件 - `web-admin/src/views/endpoint/EndpointList.vue` — 操作列加"测试"按钮 - `web-admin/src/views/endpoint/EndpointDetailDialog.vue` — 新增 defaultTab prop，测试面板改造 --- ## Task 1: 后端 Batch 1 - AdminAuth + Auth Controller 注解补全 **Files:** - Modify: `backend-single/src/main/java/com/emotion/controller/AdminAuthController.java` - Modify: `backend-single/src/main/java/com/emotion/controller/AuthController.java` - [ ] **Step 1: 查看 AdminAuthController 已有注解** AdminAuthController 已有 @Tag 和 @Operation。检查 @Parameter 是否缺失。 需要补全的 @Parameter： - `login(@RequestBody AdminLoginRequest request)` — 无路径/查询参数，body 参数用 DTO 的 @Schema 描述 - `getCurrentAdminInfo(HttpServletRequest request)` — 无显式参数 - `logout(HttpServletRequest request)` — 无显式参数 - `refreshToken(@RequestBody RefreshTokenRequest request)` — 无路径/查询参数 - `validateToken(HttpServletRequest request)` — 无显式参数 - `changePassword(HttpServletRequest request, @RequestBody AdminChangePasswordRequest req)` — 无路径/查询参数 AdminAuthController 无需额外 @Parameter，注解已完整。 - [ ] **Step 2: 查看 AuthController 缺少注解的方法** AuthController 已有 @Tag。需要补全以下方法的 @Operation： - `getCurrentUserInfo` — 缺少 @Operation - `logout` — 缺少 @Operation - `refreshToken` — 缺少 @Operation - `validateToken` — 缺少 @Operation - `getUsernameFromToken` — 缺少 @Operation - `checkAccount` — 缺少 @Operation - `checkEmail` — 缺少 @Operation - `checkPhone` — 缺少 @Operation 需要补全的 @Parameter： - `getSmsCode(@RequestParam String phone)` — 已有，检查描述准确性 - `checkAccount(@RequestParam String account)` — 新增 - `checkEmail(@RequestParam String email)` — 新增 - `checkPhone(@RequestParam String phone)` — 新增 - [ ] **Step 3: 为 AuthController 缺少的方法补全注解** 修改 `backend-single/src/main/java/com/emotion/controller/AuthController.java`： 为以下方法添加 @Operation（在方法上方的空白行插入）： ```java // 在 getCurrentUserInfo 方法上方添加： @Operation(summary = "获取当前用户信息", description = "根据当前登录用户的Token获取用户详细信息") // 在 logout 方法上方添加： @Operation(summary = "用户登出", description = "退出登录，清除服务端Token") // 在 refreshToken 方法上方添加： @Operation(summary = "刷新访问令牌", description = "使用刷新令牌获取新的访问令牌和刷新令牌") // 在 validateToken 方法上方添加： @Operation(summary = "验证访问令牌", description = "验证当前Token是否有效") // 在 getUsernameFromToken 方法上方添加： @Operation(summary = "获取用户名", description = "根据Token获取当前登录用户的用户名") // 在 checkAccount 方法上方添加： @Operation(summary = "检查账号是否存在", description = "检查指定账号是否已被注册") // 在 checkAccount 的 @RequestParam 上方添加： @Parameter(description = "账号（手机号/邮箱/用户名）", required = true) // 在 checkEmail 方法上方添加： @Operation(summary = "检查邮箱是否存在", description = "检查指定邮箱是否已被注册") // 在 checkEmail 的 @RequestParam 上方添加： @Parameter(description = "邮箱地址", required = true) // 在 checkPhone 方法上方添加： @Operation(summary = "检查手机号是否存在", description = "检查指定手机号是否已被注册") // 在 checkPhone 的 @RequestParam 上方添加： @Parameter(description = "手机号码", required = true) ``` 同时为 `getSmsCode` 的 `@RequestParam String phone` 确认已有 `@Parameter(description = "手机号", required = true)`。 - [ ] **Step 4: 为 AdminAuthController 确认注解完整** AdminAuthController 的 6 个方法全部有 @Operation，无需修改。 - [ ] **Step 5: 提交** ```bash git add backend-single/src/main/java/com/emotion/controller/AuthController.java git commit -m "feat: 补全 AuthController 缺失的 @Operation 和 @Parameter 注解" ``` --- ## Task 2: 后端 Batch 1 - Admin + Token Controller 注解补全 **Files:** - Modify: `backend-single/src/main/java/com/emotion/controller/AdminController.java` - Modify: `backend-single/src/main/java/com/emotion/controller/TokenController.java` - Modify: `backend-single/src/main/java/com/emotion/controller/AdminAnalyticsController.java` - Modify: `backend-single/src/main/java/com/emotion/controller/UserController.java` - Modify: `backend-single/src/main/java/com/emotion/controller/UserProfileController.java` - [ ] **Step 1: 读取 AdminController** ```bash cat backend-single/src/main/java/com/emotion/controller/AdminController.java ``` 检查每个方法的 @Operation 是否有 @Parameter，为路径参数和查询参数补全 @Parameter 注解。 - [ ] **Step 2: 读取 TokenController** ```bash cat backend-single/src/main/java/com/emotion/controller/TokenController.java ``` 已有 3 个 @Operation，检查是否缺少 @Parameter，补全。 - [ ] **Step 3: 为 AdminAnalyticsController 添加 @Tag 和 @Operation** 该 Controller 有 6 个 GET 接口（overview/trend/funnel/preferences/top-events/users），都需要 @Tag 和 @Operation。 在类定义上方添加： ```java import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.Operation; @Tag(name = "数据分析管理", description = "管理后台的数据分析看板接口") ``` 为每个方法添加 @Operation，例如： ```java @Operation(summary = "获取数据概览", description = "获取指定时间范围内的核心指标概览（用户数、事件数等）") @GetMapping("/overview") public Result overview(@Validated AnalyticsQueryRequest request) { ... } ``` - [ ] **Step 4: 为 UserController 添加 @Tag 和 @Operation** 读取 `UserController.java`，查看现有方法，逐个添加 @Tag 和 @Operation。 - [ ] **Step 5: 为 UserProfileController 添加 @Tag 和 @Operation** 读取 `UserProfileController.java`，逐个添加 @Tag 和 @Operation。 - [ ] **Step 6: 提交** ```bash git add backend-single/src/main/java/com/emotion/controller/AdminController.java git add backend-single/src/main/java/com/emotion/controller/TokenController.java git add backend-single/src/main/java/com/emotion/controller/AdminAnalyticsController.java git add backend-single/src/main/java/com/emotion/controller/UserController.java git add backend-single/src/main/java/com/emotion/controller/UserProfileController.java git commit -m "feat: 为 Admin/Token/AdminAnalytics/User/UserProfile Controller 补全 OpenAPI 注解" ``` --- ## Task 3: 后端 Batch 1 - 请求 DTO @Schema 注解补全 **Files:** 所有 Batch 1 涉及的 Request DTO - [ ] **Step 1: 为认证相关 DTO 补全 @Schema** 读取并修改以下 DTO，为每个字段添加 `@Schema(description = "中文描述")`： `LoginRequest.java` — 已有 phone 和 smsCode 字段，添加： ```java import io.swagger.v3.oas.annotations.media.Schema; @Schema(description = "手机号") private String phone; @Schema(description = "短信验证码") private String smsCode; ``` `RegisterRequest.java` — 读取内容，为 phone/password/smsCode 等字段添加 @Schema。 `ResetPasswordRequest.java` — 为 phone/smsCode/newPassword 等字段添加 @Schema。 `RefreshTokenRequest.java` — 为 refreshToken 字段添加 @Schema。 `AdminLoginRequest.java` — 为 username/password 等字段添加 @Schema。 `AdminCreateRequest.java` — 为 username/password/realName/phone/email/role 等字段添加 @Schema。 `AdminUpdateRequest.java` — 为各字段添加 @Schema。 `AdminPageRequest.java` — 为 page/size/keyword 等字段添加 @Schema。 `AdminChangePasswordRequest.java` — 为 oldPassword/newPassword 添加 @Schema。 `AdminResetPasswordRequest.java` — 为 adminId/newPassword 添加 @Schema。 `UserCreateRequest.java` / `UserUpdateRequest.java` / `UserPageRequest.java` — 读取后为各字段添加 @Schema。 `UserProfileUpdateRequest.java` — 为各字段添加 @Schema。 `AnalyticsQueryRequest.java` — 为 startDate/endDate/dimension 等字段添加 @Schema。 - [ ] **Step 2: 确认 import 语句** 每个 DTO 文件确保有： ```java import io.swagger.v3.oas.annotations.media.Schema; ``` - [ ] **Step 3: 提交** ```bash git add backend-single/src/main/java/com/emotion/dto/request/LoginRequest.java git add backend-single/src/main/java/com/emotion/dto/request/RegisterRequest.java git add backend-single/src/main/java/com/emotion/dto/request/ResetPasswordRequest.java git add backend-single/src/main/java/com/emotion/dto/request/RefreshTokenRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminLoginRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminCreateRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminUpdateRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminPageRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminChangePasswordRequest.java git add backend-single/src/main/java/com/emotion/dto/request/AdminResetPasswordRequest.java git add backend-single/src/main/java/com/emotion/dto/request/UserCreateRequest.java git add backend-single/src/main/java/com/emotion/dto/request/UserUpdateRequest.java git add backend-single/src/main/java/com/emotion/dto/request/UserPageRequest.java git add backend-single/src/main/java/com/emotion/dto/request/UserProfileUpdateRequest.java git add backend-single/src/main/java/com/emotion/dto/request/analytics/AnalyticsQueryRequest.java git commit -m "feat: 为 Batch 1 请求 DTO 补全 @Schema 中文描述注解" ``` --- ## Task 4: 前端 - EndpointList.vue 操作列加"测试"按钮 **Files:** - Modify: `web-admin/src/views/endpoint/EndpointList.vue` - [ ] **Step 1: 修改操作列模板** 将 EndpointList.vue 中第 56-60 行的操作列改为： ```vue ``` - [ ] **Step 2: 添加 showTest 方法** 在 script setup 中添加： ```typescript const showTest = async (row: ApiEndpointItem) => { selectedDetail.value = null detailVisible.value = true defaultTab.value = 'test' // 默认打开测试标签 try { const res: any = await getEndpointDetail(row.operationId) selectedDetail.value = res.data } catch { ElMessage.error('加载详情失败') } } ``` - [ ] **Step 3: 添加 defaultTab ref** ```typescript const defaultTab = ref<'detail' | 'test'>('detail') ``` - [ ] **Step 4: 修改 showDetail 方法确保重置 defaultTab** ```typescript const showDetail = async (row: ApiEndpointItem) => { selectedDetail.value = null defaultTab.value = 'detail' // 确保默认打开详情标签 detailVisible.value = true try { const res: any = await getEndpointDetail(row.operationId) selectedDetail.value = res.data } catch { ElMessage.error('加载详情失败') } } ``` - [ ] **Step 5: 修改子组件调用传 defaultTab** 将详情弹窗调用改为： ```vue ``` - [ ] **Step 6: 提交** ```bash git add web-admin/src/views/endpoint/EndpointList.vue git commit -m "feat: 接口管理操作列增加测试按钮" ``` --- ## Task 5: 前端 - EndpointDetailDialog.vue 新增 defaultTab prop 和 watch 改造 **Files:** - Modify: `web-admin/src/views/endpoint/EndpointDetailDialog.vue` - [ ] **Step 1: 添加 defaultTab prop** 修改 props 定义： ```typescript const props = defineProps<{ modelValue: boolean detail: ApiEndpointDetail | null defaultTab?: 'detail' | 'test' }>() ``` - [ ] **Step 2: 修改 watch 逻辑** 将原有的 watch 改为： ```typescript watch(() => props.detail, (ep) => { if (ep) { testForm.value.path = ep.path testForm.value.method = ep.method testForm.value.params = {} testForm.value.body = '' testResult.value = null generateRequestBody() // 预填充请求体 activeTab.value = props.defaultTab || 'detail' } }, { immediate: true }) ``` - [ ] **Step 3: 添加 generateRequestBody 方法** ```typescript const generateRequestBody = () => { if (!props.detail?.requestSchema || props.detail.requestSchema === '{}') { testForm.value.body = '' return } try { const schema = JSON.parse(props.detail.requestSchema) testForm.value.body = JSON.stringify(generateJsonTemplate(schema), null, 2) } catch { testForm.value.body = '' } } const generateJsonTemplate = (schema: any): any => { if (!schema || !schema.properties) return {} const result: any = {} for (const [key, prop] of Object.entries(schema.properties)) { const p = prop as any if (p.example && p.example !== '' && p.example !== 'null') { try { result[key] = JSON.parse(p.example) } catch { result[key] = p.example } } else if (p.type === 'string') { result[key] = '' } else if (p.type === 'integer') { result[key] = 0 } else if (p.type === 'number') { result[key] = 0 } else if (p.type === 'boolean') { result[key] = false } else if (p.type === 'array') { result[key] = [] } else if (p.type === 'object' && p.properties) { result[key] = generateJsonTemplate(p) } else { result[key] = null } } // 移除非必填且无有效默认值的字段 const required = schema.required || [] for (const key of Object.keys(result)) { if (!required.includes(key) && (result[key] === null || result[key] === '' || result[key] === 0 || result[key] === false || (Array.isArray(result[key]) && result[key].length === 0))) { delete result[key] } } return result } ``` - [ ] **Step 4: 提交** ```bash git add web-admin/src/views/endpoint/EndpointDetailDialog.vue git commit -m "feat: 测试面板新增 defaultTab prop 和请求体预填充逻辑" ``` --- ## Task 6: 前端 - 测试面板查询参数表单化 **Files:** - Modify: `web-admin/src/views/endpoint/EndpointDetailDialog.vue` - [ ] **Step 1: 添加参数类型渲染工具方法** 在 script setup 中添加： ```typescript const getParamInputType = (param: ApiParamItem): string => { if (param.enumValues) return 'select' const type = (param.paramTypeDef || '').toLowerCase() if (type === 'boolean') return 'switch' if (type === 'integer' || type === 'number') return 'number' return 'text' } const getEnumOptions = (param: ApiParamItem): { label: string; value: string }[] => { if (!param.enumValues) return [] return param.enumValues.split(',').map(v => ({ label: v.trim(), value: v.trim() })) } ``` - [ ] **Step 2: 改造测试面板的参数配置区域** 将原有参数表单区域改造为按参数类型分组渲染。查询参数（paramType=query/path）显示为表单输入，请求体参数显示为 JSON 编辑器。 模板改造： ```vue
参数结构已预填充，修改值后点击"发送请求"
``` - [ ] **Step 3: 添加 queryParams computed** ```typescript const queryParams = computed(() => { return (props.detail?.params || []).filter(p => p.paramType === 'query' || p.paramType === 'path') }) ``` - [ ] **Step 4: 添加 InfoFilled 图标导入** ```typescript import { InfoFilled } from '@element-plus/icons-vue' ``` - [ ] **Step 5: 添加提示样式** ```scss .body-hint { margin-top: 4px; font-size: 12px; color: var(--el-text-color-secondary); display: flex; align-items: center; gap: 4px; } ``` - [ ] **Step 6: 提交** ```bash git add web-admin/src/views/endpoint/EndpointDetailDialog.vue git commit -m "feat: 测试面板查询参数表单化，支持枚举下拉/开关/数字输入" ``` --- ## Task 7: 前端 - 测试面板请求头展示 **Files:** - Modify: `web-admin/src/views/endpoint/EndpointDetailDialog.vue` - [ ] **Step 1: 添加请求头展示区域** 在参数配置卡片下方、发送按钮上方添加： ```vue
Authorization: {{ currentToken ? `Bearer ${currentToken.slice(0, 20)}...` : '未设置' }}
Content-Type: application/json
``` - [ ] **Step 2: 添加 currentToken computed** ```typescript const currentToken = computed(() => { if (tokenSource.value === 'admin') { return localStorage.getItem('adminToken') || '' } return manualToken.value }) ``` - [ ] **Step 3: 添加请求头样式** ```scss .headers-card { :deep(.el-card__header) { padding: 8px 16px; } } .headers-list { .header-item { display: flex; gap: 8px; font-size: 13px; font-family: 'Menlo', 'Monaco', monospace; .header-key { color: var(--el-text-color-secondary); white-space: nowrap; } .header-value { color: var(--el-text-color-primary); word-break: break-all; } } } ``` - [ ] **Step 4: 提交** ```bash git add web-admin/src/views/endpoint/EndpointDetailDialog.vue git commit -m "feat: 测试面板增加请求头展示区域" ``` --- ## Task 8: 本地构建验证 + 手动同步验证 **Files:** 无新增，构建验证 - [ ] **Step 1: 本地构建后端** ```bash cd backend-single mvn clean install -DskipTests ``` 预期：BUILD SUCCESS - [ ] **Step 2: 本地启动后端** ```bash mvn spring-boot:run ``` 等待启动完成，访问 `http://localhost:19089/api/doc.html` 验证注解生效。 - [ ] **Step 3: 启动管理后台** ```bash cd web-admin npm run dev ``` 访问 `http://localhost:5174/emotion-museum-admin/endpoint/list` - [ ] **Step 4: 点击"手动同步"验证** 在接口管理页面点击"手动同步"按钮，等待 5 秒后刷新页面，检查： - 接口列表中"简述"列是否显示中文描述 - 点击"详情"按钮，查看参数描述是否有中文 - 点击"测试"按钮，查看测试面板是否正常打开 - [ ] **Step 5: 验证测试面板功能** 打开一个 POST 接口（如 /auth/login）的测试面板，确认： - 请求体 JSON 已预填充字段结构 - 查询参数以表单形式展示 - 点击"发送请求"能正常发出请求并返回结果 - [ ] **Step 6: 提交（如有构建产物变更）** 构建验证通过无需额外提交。 --- ## 附录：Controller 注解完整对照表 ### 已有 @Tag + @Operation 的 Controller（无需补 Tag） | Controller | 已有 @Operation 数 | 需要补全 | |-----------|------------------|---------| | AdminAuthController | 6 | 无 | | AuthController | 5 → 13 | 补 8 个方法 | | AdminController | 14 | 检查 @Parameter | | AiConfigController | 24 | 已有 | | TokenController | 3 | 检查 @Parameter | | AchievementController | 14 | 已有 | | ApiEndpointController | 3 | 已有 | | ApiTestProxyController | 1 | 已有 | | EmotionSummaryController | 2 | 已有 | ### 需要新增 @Tag + @Operation 的 Controller | Controller | 接口数 | 优先级 | |-----------|-------|-------| | AdminAnalyticsController | 6 | P0 | | UserController | ~10 | P0 | | UserProfileController | ~6 | P0 | | GuestUserController | ~6 | P1 | | AiChatController | ~8 | P1 | | AiRoutingController | ~4 | P1 | | CozeApiCallController | ~6 | P1 | | CommunityPostController | ~8 | P1 | | CommentController | ~6 | P1 | | SocialContentController | ~6 | P1 | | SocialInsightController | ~4 | P1 | | DiaryPostController | ~8 | P1 | | DiaryCommentController | ~6 | P1 | | GrowthTopicController | ~6 | P1 | | TopicInteractionController | ~6 | P1 | | EmotionAnalysisController | ~6 | P1 | | EmotionRecordController | ~8 | P1 | | LifeEventController | ~6 | P1 | | ConversationController | ~6 | P1 | | MessageController | ~8 | P1 | | ChatWebSocketController | ~2 | P2 | | DictionaryController | ~6 | P2 | | EpicScriptController | ~6 | P2 | | LifePathController | ~6 | P2 | | RewardController | ~6 | P2 | | UserStatsController | ~6 | P2 | | TtsController | ~4 | P2 | | AsrController | ~4 | P2 | | HealthController | 1 | P2 | | AnalyticsController | ~4 | P2 | --- ## 验收标准对应关系 | 验收标准 | 对应 Task | |---------|----------| | 接口列表"简述"列显示中文描述 | Task 1-3 (后端注解) | | 接口详情描述字段有中文说明 | Task 1-3 (后端注解) | | 参数列表"描述"列有中文说明 | Task 3 (DTO @Schema) | | 操作列有"测试"按钮 | Task 4 | | 点击测试打开弹窗并切换到测试标签 | Task 4-5 | | GET/DELETE 查询参数以表单形式展示 | Task 6 | | POST/PUT 请求体预填充 JSON 结构 | Task 5 | | 请求头区域展示 Authorization/Content-Type | Task 7 | | 测试接口正常发出请求并返回结果 | Task 6-7 (已有 handleTest 逻辑) |