316 lines
10 KiB
Markdown
316 lines
10 KiB
Markdown
# 问题反馈 API 接口定义
|
||
|
||
## 1. 文档状态
|
||
|
||
本文档定义 CozSweet 问题反馈提交接口，供后端实现和前后端联调使用。
|
||
|
||
前端已经按本文协议完成以下功能：
|
||
|
||
- 反馈分类和文字提交；
|
||
- 最多 3 张截图；
|
||
- 图片压缩和格式限制；
|
||
- Login Token 与 Guest Token 认证；
|
||
- 提交成功后展示 `feedbackId`。
|
||
|
||
后端需要实现：
|
||
|
||
```http
|
||
POST /api/feedback
|
||
```
|
||
|
||
环境地址：
|
||
|
||
| 环境 | API Base URL |
|
||
| --- | --- |
|
||
| test 测试环境 | `https://testapi.banlv-ai.com` |
|
||
| pro 预发环境 | `https://proapi.banlv-ai.com` |
|
||
| production 生产环境 | `https://api.banlv-ai.com` |
|
||
|
||
## 2. 身份认证
|
||
|
||
接口需要 Bearer Token，支持以下两种身份：
|
||
|
||
1. 正式用户 Login Token；
|
||
2. 游客 Guest Token。
|
||
|
||
```http
|
||
Authorization: Bearer <TOKEN>
|
||
```
|
||
|
||
后端必须从 Token 中解析用户或游客身份，不接受前端传递 `userId`、`guestId` 或其他身份字段。
|
||
|
||
Token 缺失、无效或过期时返回 HTTP `401`。
|
||
|
||
## 3. 请求定义
|
||
|
||
### 3.1 请求地址
|
||
|
||
```http
|
||
POST <API_BASE_URL>/api/feedback
|
||
```
|
||
|
||
### 3.2 Content-Type
|
||
|
||
请求使用：
|
||
|
||
```http
|
||
Content-Type: multipart/form-data; boundary=<AUTO_GENERATED_BOUNDARY>
|
||
```
|
||
|
||
调用方不能手工固定 `boundary`。浏览器会根据 FormData 自动生成完整 Content-Type。
|
||
|
||
### 3.3 Multipart 字段
|
||
|
||
| 字段 | 类型 | 是否必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `category` | string | 是 | 反馈分类，只允许标准枚举值。 |
|
||
| `content` | string | 是 | 用户反馈正文，去除首尾空白后长度为 10–2000。 |
|
||
| `context` | string | 是 | JSON 字符串，结构见下文。 |
|
||
| `images` | file[] | 否 | 重复字段，最多 3 张图片。没有图片时不发送该字段。 |
|
||
|
||
标准 `category`：
|
||
|
||
| 值 | 含义 |
|
||
| --- | --- |
|
||
| `problem` | 功能异常或使用问题 |
|
||
| `suggestion` | 产品建议 |
|
||
| `payment` | 充值、订阅或支付问题 |
|
||
| `other` | 其他反馈 |
|
||
|
||
不支持分类别名。非法分类返回 HTTP `400`。
|
||
|
||
### 3.4 Context JSON
|
||
|
||
`context` 在 multipart 中是一个 JSON 字符串：
|
||
|
||
```json
|
||
{
|
||
"appVersion": "0.1.0",
|
||
"platform": "android Android 15",
|
||
"browser": "facebook IAB / Chrome 135.0",
|
||
"viewport": "392x760@2.75"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 最大长度 | 说明 |
|
||
| --- | --- | ---: | --- |
|
||
| `appVersion` | string | 64 | 前端应用版本。 |
|
||
| `platform` | string | 128 | 平台、系统名称和版本。 |
|
||
| `browser` | string | 256 | 浏览器或应用内浏览器信息。 |
|
||
| `viewport` | string | 64 | CSS viewport 宽高和设备像素比。 |
|
||
|
||
后端只需要保存上述 4 个字段。不要要求前端增加 User-Agent、设备型号、IP、聊天内容、联系方式或 Token。
|
||
|
||
### 3.5 图片规则
|
||
|
||
| 规则 | 要求 |
|
||
| --- | --- |
|
||
| 数量 | 0–3 张 |
|
||
| 单文件大小 | 不超过 2 MiB，即 `2 * 1024 * 1024` bytes |
|
||
| 接受格式 | JPEG、PNG、WebP |
|
||
| 接受 MIME | `image/jpeg`、`image/png`、`image/webp` |
|
||
| 推荐请求总大小上限 | 8 MiB |
|
||
|
||
前端允许用户选择不超过 5 MiB 的源文件，但提交前会压缩到最长边不超过 1600px、目标大小不超过 2 MiB。后端仍需独立执行数量、大小、扩展名、MIME 和文件魔数校验，不能信任浏览器提供的文件名或 Content-Type。
|
||
|
||
建议后端移除 EXIF 等元数据，并将图片保存到私有存储桶。反馈截图不得使用永久公开 URL。
|
||
|
||
## 4. 请求示例
|
||
|
||
### 4.1 仅文字反馈
|
||
|
||
```bash
|
||
curl -X POST 'https://api.banlv-ai.com/api/feedback' \
|
||
-H 'Authorization: Bearer <TOKEN>' \
|
||
-F 'category=problem' \
|
||
-F 'content=The send button did not respond after I entered a message.' \
|
||
-F 'context={"appVersion":"0.1.0","platform":"android Android 15","browser":"Chrome 135.0","viewport":"392x760@2.75"}'
|
||
```
|
||
|
||
### 4.2 带多张截图
|
||
|
||
```bash
|
||
curl -X POST 'https://api.banlv-ai.com/api/feedback' \
|
||
-H 'Authorization: Bearer <TOKEN>' \
|
||
-F 'category=payment' \
|
||
-F 'content=The payment completed but my balance did not update.' \
|
||
-F 'context={"appVersion":"0.1.0","platform":"android Android 15","browser":"facebook IAB / Chrome 135.0","viewport":"392x760@2.75"}' \
|
||
-F 'images=@payment-screen-1.webp;type=image/webp' \
|
||
-F 'images=@payment-screen-2.jpg;type=image/jpeg'
|
||
```
|
||
|
||
## 5. 成功响应
|
||
|
||
成功时返回 HTTP `200`：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Feedback submitted",
|
||
"data": {
|
||
"feedbackId": "c5db8e32-60f0-4f47-81bb-c22254c0562f"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端公开响应字段只有：
|
||
|
||
| 字段 | 类型 | 是否必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `data.feedbackId` | string | 是 | 非空反馈编号，推荐使用 UUID。 |
|
||
|
||
前端不需要后端返回用户信息、反馈正文、图片地址、状态、创建时间或诊断上下文。
|
||
|
||
## 6. 失败响应
|
||
|
||
失败响应使用统一 envelope：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Feedback content must contain at least 10 characters",
|
||
"error": "INVALID_FEEDBACK_CONTENT"
|
||
}
|
||
```
|
||
|
||
建议状态码：
|
||
|
||
| HTTP 状态 | error | 场景 |
|
||
| ---: | --- | --- |
|
||
| `400` | `INVALID_FEEDBACK_CATEGORY` | 分类不在标准枚举中。 |
|
||
| `400` | `INVALID_FEEDBACK_CONTENT` | 正文为空或长度不在 10–2000。 |
|
||
| `400` | `INVALID_FEEDBACK_CONTEXT` | Context 不是合法 JSON 或字段不合法。 |
|
||
| `400` | `TOO_MANY_FEEDBACK_IMAGES` | 图片超过 3 张。 |
|
||
| `401` | `UNAUTHORIZED` | Token 缺失、无效或过期。 |
|
||
| `413` | `FEEDBACK_PAYLOAD_TOO_LARGE` | 单文件或请求总大小超过限制。 |
|
||
| `415` | `UNSUPPORTED_FEEDBACK_IMAGE` | 图片格式、MIME 或文件魔数不支持。 |
|
||
| `429` | `FEEDBACK_RATE_LIMITED` | 用户或游客提交过于频繁。 |
|
||
| `500` | `FEEDBACK_SUBMIT_FAILED` | 持久化或文件存储失败。 |
|
||
|
||
`message` 应当是可展示给用户的简短英文文本。不得在响应中返回堆栈、存储路径、数据库错误或内部实现信息。
|
||
|
||
## 7. 后端处理流程
|
||
|
||
推荐处理顺序：
|
||
|
||
1. 验证 Bearer Token，解析正式用户或游客身份。
|
||
2. 读取 multipart 字段并验证分类、正文和 Context。
|
||
3. 在读取完整文件前检查图片数量和请求大小。
|
||
4. 校验每张图片的真实格式、文件魔数、尺寸和大小。
|
||
5. 使用服务端生成的随机对象名写入私有存储。
|
||
6. 创建反馈记录并关联图片对象。
|
||
7. 返回非空 `feedbackId`。
|
||
8. 任一步失败时清理本次已经上传但未关联的图片。
|
||
|
||
每个成功请求创建一条反馈记录。当前前端没有发送 Idempotency-Key，因此后端不能依赖客户端幂等键去重。
|
||
|
||
## 8. 推荐数据模型
|
||
|
||
反馈主记录最少需要：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `id` | UUID，作为 `feedbackId` 返回。 |
|
||
| `user_id` | 正式用户 ID，可为空。 |
|
||
| `guest_id` | Guest 身份 ID，可为空。 |
|
||
| `category` | 标准反馈分类。 |
|
||
| `content` | 反馈正文。 |
|
||
| `context` | JSON/JSONB，只保存定义的 4 个字段。 |
|
||
| `status` | 内部处理状态，例如 `open`、`resolved`。不返回前端。 |
|
||
| `created_at` | 服务端创建时间。 |
|
||
|
||
图片记录最少需要反馈 ID、私有对象 key、MIME、字节大小、宽高和创建时间。不要把用户原始文件名作为存储对象名。
|
||
|
||
正式用户必须只写入 `user_id`，Guest 必须只写入 `guest_id`。身份信息由 Token 派生。
|
||
|
||
## 9. 安全与日志
|
||
|
||
- 建议按用户或 Guest 身份限流，例如每小时不超过 10 次。
|
||
- 普通应用日志不得记录反馈正文、Token、图片内容、原始文件名或完整 Context。
|
||
- 可以记录 `feedbackId`、分类、图片数量、处理时长和错误码。
|
||
- 图片下载和后台查看必须经过授权，不允许匿名公开访问。
|
||
- 数据保留、删除和后台访问需要遵循现有隐私政策。
|
||
|
||
## 10. OpenAPI 参考
|
||
|
||
```yaml
|
||
paths:
|
||
/api/feedback:
|
||
post:
|
||
summary: Submit user feedback
|
||
security:
|
||
- bearerAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- category
|
||
- content
|
||
- context
|
||
properties:
|
||
category:
|
||
type: string
|
||
enum: [problem, suggestion, payment, other]
|
||
content:
|
||
type: string
|
||
minLength: 10
|
||
maxLength: 2000
|
||
context:
|
||
type: string
|
||
description: JSON-encoded FeedbackContext
|
||
images:
|
||
type: array
|
||
maxItems: 3
|
||
items:
|
||
type: string
|
||
format: binary
|
||
responses:
|
||
"200":
|
||
description: Feedback submitted
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [success, data]
|
||
properties:
|
||
success:
|
||
type: boolean
|
||
const: true
|
||
message:
|
||
type: string
|
||
data:
|
||
type: object
|
||
required: [feedbackId]
|
||
properties:
|
||
feedbackId:
|
||
type: string
|
||
minLength: 1
|
||
"400":
|
||
description: Invalid feedback payload
|
||
"401":
|
||
description: Missing or invalid token
|
||
"413":
|
||
description: Payload too large
|
||
"415":
|
||
description: Unsupported image
|
||
"429":
|
||
description: Too many requests
|
||
"500":
|
||
description: Feedback persistence failed
|
||
```
|
||
|
||
## 11. 联调验收
|
||
|
||
后端完成后至少验证：
|
||
|
||
1. Login Token 和 Guest Token 都能成功提交。
|
||
2. 无图片、1 张图片和 3 张图片均能创建反馈。
|
||
3. 第 4 张图片、超大图片、伪造 MIME 和非法 Context 被拒绝。
|
||
4. 成功响应始终包含非空 `data.feedbackId`。
|
||
5. 存储失败时不留下孤立图片对象或半成品反馈记录。
|
||
6. 日志中不出现反馈正文、Token、图片内容和原始文件名。
|
||
7. 同一身份超过限流阈值后返回 HTTP `429`。
|