💬 反馈中心

反馈中心 API 接入说明（给开发者 / AI 看的）

把你软件的用户反馈汇集到这个中心：用户在软件里提交 → 管理员在本后台审核、回复 → 审核通过的反馈和回复会显示在各软件里。接入不需要任何密钥，照下面调接口即可。

基础地址

https://fbk.pages.dev

1）提交反馈（写入）

POST /feedback
Content-Type: application/json

{
  "app": "your-app-id",        // 必填：你的应用唯一标识（小写英文/数字/-）
  "appName": "你的应用名",       // 选填：展示名
  "userId": "0000001234",      // 必填：该用户的稳定 ID（自定规则，建议每用户不变）
  "category": "bug",           // 必填：bug | suggestion | praise | other
  "content": "反馈正文",         // 必填：≤1000 字，支持 Markdown 子集
  "contact": "",               // 选填：联系方式，仅管理员可见，永不公开
  "attachments": [],           // 选填：附件数组 [{url, name, type}]（url 先走上传接口拿到）
  "client": {                  // 选填但强烈建议：诊断环境，仅管理员可见
    "version": "web-1", "mode": "pwa 或 browser",
    "platform": "Android", "screen": "390x844",
    "lang": "zh-CN", "tz": "Asia/Shanghai", "online": true
  }
}
// 成功返回：{ "ok": true, "number": 12 }
// 注意：新反馈默认不公开，管理员在本后台点「审核通过」后才对外可见。

2）上传附件（可选，单个 ≤100MB）

POST /upload
请求头： X-Filename: 文件名.png
请求体： 文件的原始二进制
// 返回：{ "ok": true, "url": "https://fbk.pages.dev/file/uploads/..." }
// 然后把 url 放进 /feedback 的 attachments，或以 Markdown 写进正文：
// 图片 ![](url)    其它文件 [文件名](url)

3）读取反馈（公开列表）

GET /list?app=your-app-id
// 只返回「审核通过」的反馈（有约 60 秒缓存，加 &fresh=1 可绕过）
// 每条字段：number, app, category, userId, content（正文）,
//           reply（开发者最新回复，无则为 null）, state, createdAt

4）JavaScript 接入示例（复制改 app 即可）

const FB = "https://fbk.pages.dev";

// 提交
await fetch(FB + "/feedback", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    app: "your-app-id", appName: "你的应用名",
    userId: getMyUserId(), category: "bug",
    content: "用户输入的反馈内容",
    client: { version: "1.0", platform: navigator.platform,
              lang: navigator.language }
  })
});

// 读取并展示（只含审核通过的）
const d = await (await fetch(FB + "/list?app=your-app-id")).json();
for (const it of d.items) {
  console.log(it.userId, it.content, "开发者回复：", it.reply || "暂无");
}

规则与注意

- 正文支持 Markdown 子集：**粗体**、`代码`、# 标题、- 列表、> 引用、![图](url)、[链接](url)
- 反馈公开后所有人可见，请勿在正文里放敏感信息；联系方式只填 contact 字段
- 提交无需登录/令牌；请勿高频刷接口
- 管理员接口（仅本后台使用，不要写进普通软件）：
  POST /login {username,password} → {token}（7 天有效，之后请求带 Authorization: Bearer <token>）
  GET  /admin/list        全部反馈（含未公开、联系方式、诊断环境）
  POST /admin/reply       {number, content} 直接回复用户
  POST /admin/visibility  {number, visible} 审核公开 / 取消公开