FootPrint/docs/api.md

HTTP API 参考

Base URL：部署域名（如 https://footpr.example.com）。除 /health 与 /auth/register|login 外， 所有接口都需要 Authorization: Bearer <token>。

统一响应格式：

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "错误原因" }

健康检查

方法	路径	说明
GET	/health	存活探针，无需鉴权

认证

方法	路径	说明
POST	/auth/register	注册（REGISTER_ENABLED/INVITE_CODE/MAX_USERS 门控；首位用户自动成为管理员）
POST	/auth/login	登录，返回 Bearer Token（365 天）
GET	/auth/me	当前用户信息（user_id / username / is_admin / device_id）

curl -s https://footpr.example.com/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"demo","password":"demo1234","device_name":"cli"}'
# => {"ok":true,"data":{"token":"...","user_id":"...","device_id":"...","expires_at":"..."}}

管理（仅 is_admin 会话）

方法	路径	说明
GET	/admin/users	用户列表（设备数/记录数/附件用量）
GET	/admin/invites	邀请码列表（含 remark、创建者、使用者）
POST	/admin/invites/generate	批量生成随机码 {"count": 5}（1-50）
POST	/admin/invites/create	新建自定义码 {"code":"XIONG-2025","remark":"备注"}（4-32 位字母数字-_）
POST	/admin/invites/update	改备注 / 启停 {"id":1,"remark":"...","valid":false}（已使用的码不可再启用）
POST	/admin/invites/delete	删除 {"id":1}
POST	/admin/invites/revoke	作废（等价 update valid=false，兼容保留）
POST	/admin/demo-seed	给 demo 账号播种演示数据（幂等；档案库非空时返回 seeded:false）

同步

方法	路径	说明
GET	/sync/status	当前用户同步账本统计
POST	/sync/push	推送 wire 变更（LWW 上/删除，立即生效）
GET	/sync/pull?cursor=...&limit=...	按 seq 游标增量拉取
POST	/sync/attachment	上传附件 {"sha256","size","mime","file_name","data_b64"}（内容寻址去重）
GET	/sync/attachment/<sha256>	下载附件

业务命令层 POST /api/<command>

与桌面端共用同一命令层（app/server/db.mjs），按用户隔离。37 个命令：

分组	命令
应用	app_info · sync_status
记录类型	type_list · type_upsert · type_delete
字典/维度	taxonomy_list · taxonomy_upsert · taxonomy_delete · dimension_list · dimension_upsert · dimension_delete
足迹	footprint_list · footprint_get · footprint_upsert · footprint_delete · timeline
统计	stats_overview · metric_list · metric_upsert · metric_delete
成绩	grades_overview · semester_upsert · semester_delete · course_upsert · course_delete · band_upsert · band_delete
附件	attachment_add · attachment_list · attachment_delete · attachment_read
保存视图	view_list · view_upsert · view_delete
播种/同步内核	demo_seed · sync_apply_wire · sync_pull_wire

示例（检索记录）：

curl -s https://footpr.example.com/api/footprint_list \
  -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" \
  -d '{"query":{"page":1,"page_size":20,"year":2025}}'

footprint_list 的 query 支持：year、type_id、level、status、q（全文检索）、 dimension_id、sort（date_desc/date_asc/updated_desc/weight_desc）、分页 page/page_size。