后端 API 概览¶

Inklet 后端提供 RESTful JSON API，用于认证、设备管理和计费。后端使用 Go 和 Chi 路由器构建。

基础 URL¶

Inklet 后端有两个生产域名，按路径前缀区分：

路径前缀	生产域名
`/auth/*`	`https://auth.iminklet.com`
`/api/*`、`/health`	`https://dev.iminklet.com`

本地开发时，两个前缀统一使用 http://localhost:4000。

响应格式¶

所有响应返回 JSON 并附带相应的 HTTP 状态码。成功响应使用 200 或 201；错误响应返回包含 error 字段的 JSON 内容：

{
  "error": "description of the error"
}

认证¶

受保护的接口需要在 Authorization 请求头中提供有效的 JWT 访问令牌：

Authorization: Bearer {accessToken}

访问令牌有较长的有效期，并带有滑动续签机制。使用刷新接口可以在无需重新认证的情况下获取新令牌。

令牌生命周期

访问令牌默认 72 小时过期（可通过 ACCESS_TOKEN_EXPIRY 环境变量调整）。刷新令牌有效期较长，但每次使用后会进行轮换 --- 当签发新的令牌对时，旧的刷新令牌将被废止。

滑动续签（X-Renewed-Token）

当访问令牌的剩余有效期不足 24 小时时，后端会在每个受保护接口的响应头中自动附带一个新的访问令牌：

X-Renewed-Token: eyJhbGciOiJIUzI1NiIs...

客户端应检查此响应头，若存在则用它替换本地存储的访问令牌，这样就无需等到过期再调用刷新接口。该响应头已在 CORS 的 ExposedHeaders 中声明，浏览器可直接读取。

API 分组¶

API 分为四组：

认证（`/auth/*`）— `https://auth.iminklet.com`¶

用户注册、登录、OAuth（Google 和 Apple）、会话管理、个人资料更新以及订阅计费。

参见：认证 | 计费

设备（`/api/devices/*`）— `https://dev.iminklet.com`¶

设备列表、绑定（NFC 和配对码）、解绑、命令下发和状态查询。

参见：设备

内容（`/api/*`）— `https://dev.iminklet.com`¶

原始内容上传（文本 + 附件包）、文件下载及手动触发分析任务。

参见：内容上传 | Worker 管线

POST /api/raw-items/upload — 请求上传预签名 URL
POST /api/raw-items/{id}/confirm — 确认文件已上传
GET /api/raw-items — 列出当前用户的 items
GET /api/raw-items/{id} — 获取单个 item
GET /api/raw-items/stats — 最近 7 天处理统计
GET /api/files/{fileId}/download — 获取文件下载重定向
POST /api/analyze/trigger — 手动触发分析 Worker（需认证）

健康检查（`/health`）— `https://dev.iminklet.com`¶

一个简单的健康检查接口，供负载均衡器和监控系统使用。

curl https://dev.iminklet.com/health

{
  "status": "ok"
}

常见 HTTP 状态码¶

状态码	含义
`200`	成功
`201`	资源已创建
`400`	请求无效 --- 字段缺失或格式错误
`401`	未授权 --- 令牌缺失或已过期
`403`	禁止访问 --- 你不是该资源的所有者
`404`	资源未找到
`409`	冲突 --- 邮箱、用户名重复或设备已被绑定
`410`	已失效 --- 资源已被删除或过期
`500`	服务器内部错误

频率限制¶

生产环境中的 API 请求可能受到频率限制。如果超出限制，你将收到 429 Too Many Requests 响应。请等待 Retry-After 响应头指定的时间后重试。

CORS¶

生产环境后端允许来自 https://portal.iminklet.com 的跨域请求。本地开发允许 http://localhost:5173。