Files

T

peanut f0f66427cd docs: 添加接口管理改造实现计划

- 8 个 Task 覆盖后端注解补全 + 前端测试面板改造
- 每个 Task 包含具体文件路径、代码示例、验证方式
- 附带 Controller 注解完整对照表和验收标准对应关系

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-23 21:20:16 +08:00

26 KiB

Raw Blame History

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

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（在方法上方的空白行插入）：

// 在 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: 提交

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

cat backend-single/src/main/java/com/emotion/controller/AdminController.java

检查每个方法的 @Operation 是否有 @Parameter，为路径参数和查询参数补全 @Parameter 注解。

Step 2: 读取 TokenController

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。

在类定义上方添加：

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;

@Tag(name = "数据分析管理", description = "管理后台的数据分析看板接口")

为每个方法添加 @Operation，例如：

@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: 提交

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 字段，添加：

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 文件确保有：

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

Step 3: 提交

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 行的操作列改为：

<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 中添加：

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

const defaultTab = ref<'detail' | 'test'>('detail')

Step 4: 修改 showDetail 方法确保重置 defaultTab

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

将详情弹窗调用改为：

<EndpointDetailDialog v-model="detailVisible" :detail="selectedDetail" :default-tab="defaultTab" />

Step 6: 提交

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 定义：

const props = defineProps<{
  modelValue: boolean
  detail: ApiEndpointDetail | null
  defaultTab?: 'detail' | 'test'
}>()

Step 2: 修改 watch 逻辑

将原有的 watch 改为：

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 方法

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: 提交

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 中添加：

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 编辑器。

模板改造：

<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

const queryParams = computed(() => {
  return (props.detail?.params || []).filter(p => p.paramType === 'query' || p.paramType === 'path')
})

Step 4: 添加 InfoFilled 图标导入

import { InfoFilled } from '@element-plus/icons-vue'

Step 5: 添加提示样式

.body-hint {
  margin-top: 4px;
  font-size: 12px;
  color: var(--el-text-color-secondary);
  display: flex;
  align-items: center;
  gap: 4px;
}

Step 6: 提交

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: 添加请求头展示区域

在参数配置卡片下方、发送按钮上方添加：

<!-- 请求头 -->
<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

const currentToken = computed(() => {
  if (tokenSource.value === 'admin') {
    return localStorage.getItem('adminToken') || ''
  }
  return manualToken.value
})

Step 3: 添加请求头样式

.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: 提交

git add web-admin/src/views/endpoint/EndpointDetailDialog.vue
git commit -m "feat: 测试面板增加请求头展示区域"

Task 8: 本地构建验证 + 手动同步验证

Files: 无新增，构建验证

Step 1: 本地构建后端

cd backend-single
mvn clean install -DskipTests

预期：BUILD SUCCESS

Step 2: 本地启动后端

mvn spring-boot:run

等待启动完成，访问 http://localhost:19089/api/doc.html 验证注解生效。

Step 3: 启动管理后台

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 逻辑)

26 KiB Raw Blame History Unescape Escape

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

文件结构

后端改动文件（按批次）

前端改动文件

Task 1: 后端 Batch 1 - AdminAuth + Auth Controller 注解补全

Task 2: 后端 Batch 1 - Admin + Token Controller 注解补全

Task 3: 后端 Batch 1 - 请求 DTO @Schema 注解补全

Task 4: 前端 - EndpointList.vue 操作列加"测试"按钮

Task 5: 前端 - EndpointDetailDialog.vue 新增 defaultTab prop 和 watch 改造

Task 6: 前端 - 测试面板查询参数表单化

Task 7: 前端 - 测试面板请求头展示

Task 8: 本地构建验证 + 手动同步验证

附录：Controller 注解完整对照表

已有 @Tag + @Operation 的 Controller（无需补 Tag）

需要新增 @Tag + @Operation 的 Controller

验收标准对应关系

26 KiB

Raw Blame History

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