product-issue/docs/api.md

公共反馈 API

Endpoint

POST /api/v1/feedback

该接口不使用用户账户。服务端按来源 IP 和 installationId 的 keyed digest 分别限流，并使用 (productKey, clientRequestId) 保证幂等。

生产环境必须使用 HTTPS。若请求包含 Origin，它必须与服务端 PUBLIC_ORIGIN 的 origin 完全一致。桌面应用的 Main 进程请求通常不发送 Origin。

JSON 提交

POST /api/v1/feedback HTTP/1.1
Content-Type: application/json

{
  "schemaVersion": 1,
  "productKey": "goodbuddy",
  "category": "bug",
  "title": "魔法笔记页签不可见",
  "description": "平台功能中的魔法笔记页签被布局压缩，无法看到或点击。",
  "contactEmail": "user@example.com",
  "environment": {
    "appVersion": "0.11.0",
    "platform": "windows",
    "architecture": "x64",
    "locale": "zh-CN"
  },
  "installationId": "00000000-0000-4000-8000-000000000101",
  "clientRequestId": "00000000-0000-4000-8000-000000000102"
}

Multipart 提交截图

使用 multipart/form-data 时：

• payload：上述 JSON 的字符串形式
• screenshot：可选，最多一个 PNG、JPEG 或 WebP 文件

curl \
  --fail-with-body \
  --form 'payload={
    "schemaVersion":1,
    "productKey":"goodbuddy",
    "category":"bug",
    "title":"魔法笔记页签不可见",
    "description":"平台功能中的魔法笔记页签被布局压缩，无法看到或点击。",
    "installationId":"00000000-0000-4000-8000-000000000101",
    "clientRequestId":"00000000-0000-4000-8000-000000000102"
  }' \
  --form 'screenshot=@capture.png;type=image/png' \
  https://feedback.example.com/api/v1/feedback

服务端会验证实际解码格式，只接受单帧 PNG、JPEG 或 WebP，随后应用方向 信息、重编码为 PNG 并去除原文件元数据。 输入和重编码后的文件都必须满足 MAX_SCREENSHOT_BYTES。最大边长为 8192 像素，最大像素数为 3200 万。

字段

字段	必填	约束
schemaVersion	是	当前固定为 1
productKey	是	2–64 位小写字母、数字或连字符，产品必须启用
category	是	bug、feature、experience、other
title	是	去除首尾空白后 1–120 字符
description	是	去除首尾空白后 10–5000 字符
contactEmail	否	有效邮箱，最多 254 字符
environment.appVersion	环境存在时	1–64 字符
environment.platform	环境存在时	windows、macos、linux、unknown
environment.architecture	环境存在时	x64、arm64、unknown
environment.locale	否	2–32 字符
installationId	是	应用安装级随机 UUID，不应使用硬件 ID
clientRequestId	是	每次新反馈生成的随机 UUID；重试时保持不变

请求对象采用严格 schema，未声明字段会导致请求失败。

成功响应

首次创建返回 HTTP 201：

{
  "reference": "GOODBUDDY-000001",
  "duplicate": false
}

同一产品和 clientRequestId 的重试返回 HTTP 200，并返回原编号：

{
  "reference": "GOODBUDDY-000001",
  "duplicate": true
}

错误

HTTP	含义
400	字段、JSON、multipart 或图片无效
403	请求 Origin 不允许
404	产品不存在或已停用
413	请求体超过限制
429	IP 或安装实例超过提交频率
500	服务端内部错误

客户端应：

1. 为一次用户提交生成 clientRequestId，网络重试时复用。
2. 设置明确的连接与总超时。
3. 限制响应体大小，只接受 JSON。
4. 将非 2xx 响应作为失败处理，并向用户保留输入内容。
5. 仅在用户明确选择后添加截图。