happy-life-star/docs/superpowers/plans/2026-05-23-endpoint-chinese-docs-and-test-panel.md

# 接口管理中文描述与测试面板改造 实现计划

> **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<AnalyticsOverviewResponse> 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
<el-table-column label="操作" width="150" align="center">
  <template #default="{ row }">
    <el-button type="primary" link size="small" @click="showDetail(row)">详情</el-button>
    <el-button type="success" link size="small" @click="showTest(row)">测试</el-button>
  </template>
</el-table-column>
```

- [ ] **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
<EndpointDetailDialog v-model="detailVisible" :detail="selectedDetail" :default-tab="defaultTab" />
```

- [ ] **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
<el-card style="margin-bottom: 16px">
  <template #header>参数配置</template>
  <el-form :model="testForm" label-width="100px">
    <el-form-item label="请求路径">
      <el-input v-model="testForm.path" disabled />
    </el-form-item>
    <el-form-item label="请求方法">
      <el-input v-model="testForm.method" disabled />
    </el-form-item>

    <!-- 查询参数/路径参数 -->
    <template v-if="queryParams.length > 0">
      <el-divider content-position="left">查询参数</el-divider>
      <el-form-item
        v-for="param in queryParams"
        :key="param.name"
        :label="param.description || param.name"
        :required="param.required === 1"
      >
        <el-select
          v-if="getParamInputType(param) === 'select'"
          v-model="testForm.params[param.name]"
          :placeholder="param.example || '请选择'"
          clearable
        >
          <el-option
            v-for="opt in getEnumOptions(param)"
            :key="opt.value"
            :label="opt.label"
            :value="opt.value"
          />
        </el-select>
        <el-switch
          v-else-if="getParamInputType(param) === 'switch'"
          v-model="testForm.params[param.name]"
          :active-value="'true'"
          :inactive-value="'false'"
        />
        <el-input-number
          v-else-if="getParamInputType(param) === 'number'"
          v-model="testForm.params[param.name]"
          :placeholder="param.example || ''"
          controls-position="right"
        />
        <el-input
          v-else
          v-model="testForm.params[param.name]"
          :placeholder="param.example || ''"
        />
      </el-form-item>
    </template>

    <!-- 请求体（POST/PUT/PATCH） -->
    <el-form-item v-if="['POST', 'PUT', 'PATCH'].includes(testForm.method)" label="请求体">
      <el-input
        v-model="testForm.body"
        type="textarea"
        :rows="8"
        placeholder="JSON 格式"
      />
      <div v-if="testForm.body" class="body-hint">
        <el-icon><InfoFilled /></el-icon>
        参数结构已预填充，修改值后点击"发送请求"
      </div>
    </el-form-item>
  </el-form>
</el-card>
```

- [ ] **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
<!-- 请求头 -->
<el-card class="headers-card" style="margin-bottom: 16px">
  <template #header>请求头</template>
  <div class="headers-list">
    <div class="header-item">
      <span class="header-key">Authorization:</span>
      <span class="header-value">{{ currentToken ? `Bearer ${currentToken.slice(0, 20)}...` : '未设置' }}</span>
    </div>
    <div v-if="['POST', 'PUT', 'PATCH'].includes(testForm.method) && testForm.body" class="header-item">
      <span class="header-key">Content-Type:</span>
      <span class="header-value">application/json</span>
    </div>
  </div>
</el-card>
```

- [ ] **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 逻辑) |