docs: 添加接口管理改造实现计划
- 8 个 Task 覆盖后端注解补全 + 前端测试面板改造 - 每个 Task 包含具体文件路径、代码示例、验证方式 - 附带 Controller 注解完整对照表和验收标准对应关系 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,774 @@
|
||||
# 接口管理中文描述与测试面板改造 实现计划
|
||||
|
||||
> **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 逻辑) |
|
||||
Reference in New Issue
Block a user