Public API

目标读者：需要验证 SDK 配置读取和反馈接收流程的 SDK 开发者与后端开发者。

public API 使用 contracts version 0.4.0-alpha.1，本地地址是 http://localhost:4000。它提供 SDK config 读取、反馈写入，以及受同意状态限制的附件上传。认证方式是 X-Project-Key。

路由

方法	路径	用途
`GET`	`/healthz`	只检查进程存活。
`GET`	`/readyz`	检查 PostgreSQL 和对象存储就绪状态。
`GET`	`/v1/sdk/config?locale=zh-CN\|en\|ja`	本地化 SDK 配置、隐私文本、分类、附件限制和默认未勾选的同意项。
`POST`	`/v1/feedback/reports`	创建玩家主动提交的反馈报告和同意快照。
`POST`	`/v1/feedback/reports/{feedback_id}/attachments`	上传受同意状态限制的附件，例如截图或最近日志。

存活、就绪与浏览器访问

GET /healthz 不检查外部依赖。无需认证的 GET /readyz 把 PostgreSQL 和对象存储都视为硬依赖：只有两个组件均为 ready 时才返回 200 ready，任一依赖失败都会返回 503 unavailable。响应使用 Cache-Control: no-store，且不会暴露原始依赖错误、端点、bucket 名称或凭证。

Alpha 的 Public API 刻意没有浏览器 CORS 策略。它支持原生 Godot 游戏和非浏览器工具；不要把它当成浏览器 API，也不要根据 Admin API 的状态推断 Public API 状态。

最小示例

curl -X POST "http://localhost:4000/v1/feedback/reports" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: zh-CN" \
  -H "X-Project-Key: enb_pk_xxx" \
  -H "Idempotency-Key: godot-demo-uuid-002" \
  -d '{
  "client_report_id": "godot-demo-uuid-002",
  "trigger_source": "button",
  "category": "suggestion",
  "description": "地图标记如果对比度更高会更容易看清。",
  "content_language": "zh-CN",
  "player": {
    "id_hash": "sha256:337180dda29405211bf7a37ea531367110370dc54db2298fcf4450f1749badb3"
  },
  "app": {
    "environment": "test",
    "release": "0.1.0",
    "build_id": "dev-build-001",
    "engine": "godot",
    "engine_version": "4.x"
  },
  "game_context": {
    "scene": "res://scenes/hub.tscn",
    "level": "hub",
    "extra": {}
  },
  "breadcrumbs": [],
  "consents": {
    "privacy_notice_version": "v1",
    "locale": "zh-CN",
    "player_confirmed_submit": true,
    "screenshot_upload": false,
    "recent_logs_upload": false,
    "contact_upload": false,
    "submitted_at": "2026-06-10T01:05:02Z"
  },
  "locale": "zh-CN",
  "device": {
    "platform": "macos",
    "locale": "zh-CN"
  }
}'

成功时返回 202 Accepted，并包含 feedback_id 和 multipart 附件上传地址。

服务端默认值

client_report_id、trigger_source、category、description 和 consents 是必填字段。运行环境、版本、构建和引擎放在 app，平台与设备事实放在 device，可选玩家标识和联系方式放在 player。省略运行上下文时存储 unknown，引擎默认 godot。UI 语言按 locale、Accept-Language、项目默认语言、en 解析，content_language 与 consent 语言独立。重复的顶层运行字段、联系方式字段和 ui_locale 均拒绝。请使用当前 SDK 包，不迁移旧 Alpha 数据或请求格式。

常见错误

创建反馈时不要省略 Idempotency-Key。
附件重试必须使用稳定且附件级的 Idempotency-Key（1–120 字符）；同一键改传不同附件内容会返回 409。
consents.recent_logs_upload 为 false 时应避免发送 recent_logs；如果仍发送，服务端会丢弃内嵌日志并记录 recent_logs_dropped: true。
已保存同意状态不允许截图时，不要上传 screenshot 附件。
不要复用示例 player_id_hash；发送前应先对自己的玩家标识做 hash 或假名化。
不要把 Project Key 用在 /admin/v1/* Admin API 端点。

下一步

用 Admin API 查看已接收的反馈。

资源限制与启动配置策略见排障说明。