反馈接口参考
反馈记录
用于创建、查询、查看和更新客户端用户反馈记录。
- 集合路由
- /api/feedbacks
- 详情路由
- /api/feedbacks/:feedbackId
- 状态路由
- /api/feedbacks/:feedbackId/status
/api/feedbacks /api/feedbacks 同时承载创建和列表查询两类操作。创建反馈走应用令牌鉴权，返回 FeedbackDetail，且 attachments: []；查询列表走管理员会话鉴权。总览
反馈路由地图
反馈集合同时承担 App 上报入口和后台列表查询入口。
POST /api/feedbacks 用于接收已配置客户端新提交的反馈记录。
GET /api/feedbacks 用于返回带筛选、分页和统计汇总的后台反馈列表。
GET /api/feedbacks/:feedbackId 返回单条反馈记录及其附件信息。
PATCH /api/feedbacks/:feedbackId/status 用于在 unprocessed、processing 和 processed 之间切换，并记录处理备注。
POST
创建反馈
由已配置客户端创建一条新的用户反馈记录。
请求
请求体为 JSON，包含必填反馈字段，以及可选的联系方式、设备信息、页面上下文、日志和扩展元数据。
- 必填：type、title、content、appName、appVersion、platform。
- 可选：userId、contactEmail、contactWechat、buildNumber、deviceModel、osVersion、deviceId、pagePath、occurredAt、logText、extra；TT Math 仅允许匿名诊断字段（buildNumber、deviceModel、osVersion、pagePath、occurredAt、extra.envVersion、extra.locale）。
响应
返回新创建的 FeedbackDetail 记录，初始状态为 unprocessed，attachments 为空数组。
- id 和 feedbackNo 用于标识该反馈记录。
- status 初始值固定为 unprocessed。
- 创建成功时响应内包含 attachments，且在未上传附件前为空数组。
- 不支持的反馈类型会返回 400。
- 429 响应会携带 Retry-After，客户端应等待指定时间后再重试。
- TT Math 第一版不使用附件上传；数据会写入 DATABASE_URL 指定的 PostgreSQL 数据库，附件文件仍使用默认 .data 路径。
| Name | Type | Required | Description | Notes |
|---|---|---|---|---|
| HTTP 201 | 已创建 | Optional | 反馈载荷校验通过并成功写入数据库。 | - |
| HTTP 400 | 请求错误 | Optional | JSON 载荷缺少必填字段或包含非法取值。 | - |
| HTTP 401 | 未授权 | Optional | 客户端 token 缺失或校验失败。 | - |
| HTTP 409 | 重复反馈 | Optional | 24 小时内提交了相同内容指纹的反馈。 | - |
| HTTP 413 | 请求体过大 | Optional | JSON 请求体超过服务端大小限制。 | - |
| HTTP 429 | 请求过于频繁 | Optional | 命中 IP、设备、版本或客户端通道频率限流。 | - |
| HTTP 500 | 服务器内部错误 | Optional | 数据库打开或写入失败。 | - |
GET
查询反馈列表
返回后台反馈列表视图。
请求
查询参数支持 status、type、appName、platform、appVersion、keyword、from、to、page 和 pageSize。
- status 允许 all、unprocessed、processing、processed。
- page 和 pageSize 必须是正整数。
响应
返回 items、pagination，以及 all、unprocessed、processing、processed 四类统计信息。
- 每条列表项都包含 attachmentCount。
- stats 对象基于整张反馈表聚合计算。
GET
获取反馈详情
供管理员加载单条反馈及其附件详情。
请求
通过路径参数 feedbackId 指定目标记录。
响应
返回完整的反馈详情记录，附件按创建时间顺序排列。
- attachments 中包含 screenshot 和 log_file 两类附件元数据。
- 当记录已处理时，会返回 adminNote、processedAt 和 processedBy。
PATCH
更新反馈状态
将反馈标记为 processing、processed，或重新恢复为 unprocessed。
请求
请求体为 JSON，包含 status 和可选 adminNote。
- status 必须是 unprocessed、processing 或 processed。
- adminNote 为可选字段，会与反馈记录一同存储。
响应
返回更新后的反馈详情记录。
- processedBy 来源于已校验管理员会话中的用户名。
- processedAt 仅在 status=processed 时写入；status=processing 会保留处理人和备注但不写完成时间。
- 路由在 requireAdminSession 之后会再次校验 review session，以便持久化 processedBy。