反馈接口参考
反馈附件
为已存在的反馈记录上传截图和日志文件。
- 附件路由
- /api/feedbacks/:feedbackId/attachments
- 最大上传大小
- 5 MiB
- 支持类型
- screenshot, log_file
必须先创建反馈记录
附件上传路由仅在反馈记录已存在时可用。请先创建反馈，拿到返回的
feedbackId， 再针对该 id 上传文件。publicUrl 仅是元数据
上传响应中的文件元数据会返回
publicUrl，但当前文档并未定义可读取附件的 GET 路由。请把它视为未来或内部用途的元数据，而不是当前可直接访问的下载契约。总览
支持的附件类型
附件上传路由仅接收截图和日志文件。
POST /api/feedbacks/:feedbackId/attachments 会先把文件写入反馈上传目录，再插入附件数据库记录。
路由会在写入文件前按 kind 校验对应的 MIME 约束。
- screenshot 文件必须是 image/*。
- log_file 允许 text、json、xml、csv 和 octet-stream 类型。
- 大于 5 MiB 的文件会被拒绝。
- 即使 token 校验通过，服务端仍会按 IP、设备、feedbackId 和附件上传频率限流。
上传成功后会同时返回附件记录以及 storagePath、publicUrl 等文件元信息。
publicUrl 当前仅作为元数据返回，文档并未定义可直接读取的下载路由。
如果 feedbackId 不存在，路由会在插入附件元数据前直接返回 404。
POST
上传反馈附件
为已存在的反馈记录追加一张截图或一个日志文件。
POST/api/feedbacks/:feedbackId/attachments
鉴权方式
需要携带 x-feedback-app-token 上报通道标识；服务端会匹配 MDVIEWER_FEEDBACK_TOKEN、TT_PIGGY_FEEDBACK_TOKEN 或 TT_MATH_FEEDBACK_TOKEN，且 token 必须与目标反馈的 appName 对应。MDViewer 旧版客户端仍可使用 x-mdviewer-token。TT Piggy 小程序应通过自身后端代理转发；TT Math 小程序也应通过自身后端代理转发。服务端还会按 IP、设备、feedbackId 和客户端通道做附件上传频率限流。
请求结构
请求体为 multipart/form-data，包含 kind 和 file 两个字段。
- kind 必须是 screenshot 或 log_file。
- file 必填，且大小不能超过 5 MiB。
响应结构
返回持久化后的附件记录以及落盘文件的元信息。
- attachment 表示数据库中的附件记录，包含 id、mimeType、storagePath 等信息。
- file 表示落盘后的文件元数据，包含 publicUrl、mimeType、fileSize、storagePath；其中 publicUrl 当前仅供未来或内部用途使用。
补充说明
- 文件会存储在 FEEDBACK_UPLOADS_ROOT 指定目录，未配置时使用默认 .data 路径。
- publicUrl 当前仅作为元数据返回，本文档未定义可直接读取的 GET 下载接口。
- 附件数量或累计大小超过服务端限制时返回 400，不属于 429 附件上传频率限流。
- 429 响应会携带 Retry-After，客户端应等待指定时间后再重试。
- 若附件元数据入库失败，路由会尽力删除已写入的文件。