docs: README + LICENSE + CONTRIBUTING + CHANGELOG + API reference + issue/PR templates + editorconfig

docs/api.md

@@ -0,0 +1,82 @@
+# HTTP API 参考
+
+Base URL：部署域名（如 `https://footpr.example.com`）。除 `/health` 与 `/auth/register|login` 外，
+所有接口都需要 `Authorization: Bearer <token>`。
+
+统一响应格式：
+
+```json
+{ "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`） |
+
+```bash
+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` |
+
+示例（检索记录）：
+
+```bash
+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`。