76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# API
|
||
|
||
Base path: `/api/v1`。除初始化、登录和健康检查外，接口均要求 `dodo_session` Cookie；同源写请求使用双提交 CSRF 校验。登录后可访问 `/api/docs` 和 `/api/openapi.json`。
|
||
|
||
## 账户与会话
|
||
|
||
- `GET /setup/status`、`POST /setup/initialize`
|
||
- `POST /auth/login`、`POST /auth/logout`、`POST /auth/change-password`
|
||
- `GET/PATCH /me`
|
||
- `GET /sessions`、`DELETE /sessions/{session_id}`、`DELETE /sessions/others`
|
||
- `GET /audit-logs`
|
||
|
||
## 文件夹、清单与任务
|
||
|
||
- 文件夹：`GET/POST /folders`，`PATCH/DELETE /folders/{id}`，以及排序接口
|
||
- 清单：`GET/POST /lists`，`PATCH/DELETE /lists/{id}`，归档恢复、永久删除、移动与排序接口
|
||
- 归档清单只标记 `deleted_at`，不会把任务移到收集箱；清单归档期间，其任务在普通列表和详情中不可见，恢复清单后重新出现
|
||
- 任务：`GET/POST /tasks`、`GET/PATCH/DELETE /tasks/{id}`、`POST /tasks/{id}/restore`、`DELETE /trash/{id}`
|
||
- `GET /tasks` 和 `GET /trash` 使用不透明游标；`limit` 为 1–100
|
||
- `POST /tasks/batch` 支持批量完成、移动、截止时间与软删除；任务写入使用 `version` 乐观锁
|
||
- 一层子任务必须与父任务同清单；任务可带日期型或具体时间型截止时间
|
||
|
||
## 重复任务
|
||
|
||
- `GET /tasks/{task_id}/recurrence`
|
||
- `POST /recurrences`、`PATCH/DELETE /recurrences/{id}`
|
||
- `POST /recurrences/{id}/complete`
|
||
- 支持 RRULE 计划重复与按用户本地完成日期计算的“完成后重复”
|
||
|
||
## 习惯、倒数日与备忘录
|
||
|
||
- 习惯：创建、列表/周网格、部分更新、排序、归档/恢复/永久删除、日志、暂停和统计
|
||
- 倒数日：创建、列表、编辑、置顶、归档/恢复/永久删除；支持公历/农历及周/月/年重复
|
||
- 备忘录：游标列表、创建、读取、乐观锁更新、软删除、恢复和归档后永久删除
|
||
|
||
## 附件
|
||
|
||
- `GET/POST /tasks/{task_id}/attachments`
|
||
- `GET/DELETE /attachments/{attachment_id}`
|
||
- 文件保存在服务端附件目录；上传受大小与类型限制，访问始终校验当前用户归属
|
||
|
||
## 完整备份 ZIP v2
|
||
|
||
### `GET /backup/export.zip`
|
||
|
||
导出 `dodo-backup` version 2 ZIP。归档包含 `manifest.json`、每类实体的 `data/*.json`、附件元数据和附件原始字节。manifest 声明实体数量及每个条目的 SHA-256。
|
||
|
||
实体范围：`folders`、`lists`、`tasks`、`recurrences`、`recurrence_exceptions`、`habits`、`habit_logs`、`habit_pauses`、`countdowns`、`memos`、`attachments`。会话、密码散列、审计日志及备份内部账本不导出。
|
||
|
||
### `POST /backup/preflight?mode=merge|replace`
|
||
|
||
以 multipart 字段 `file` 上传 ZIP。服务端流式暂存，并在返回令牌前验证：ZIP 路径与条目、压缩比/容量、manifest 版本与计数、全部校验和、字段与业务约束、关系拓扑、一层任务树、用户隔离以及附件元数据/字节一致性。
|
||
|
||
成功返回 `valid`、短期 `preflight_token`、`backup_id`、归档摘要和各实体数量。预检有每用户待处理数量/容量配额和过期时间；令牌绑定用户、文件摘要和恢复模式。
|
||
|
||
### `POST /backup/restore`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{"preflight_token":"...","mode":"merge"}
|
||
```
|
||
|
||
`merge` 使用持久化 source→target ID/内容摘要账本实现可重试合并；跨用户或同 ID 不同内容冲突会拒绝。`replace` 在事务内替换当前用户业务实体，并通过同文件系统隔离区协调附件删除和失败补偿。令牌单次消费；若数据库已提交但隔离区清理失败，同一令牌仅重试清理，不重复导入。
|
||
|
||
## 旧格式兼容
|
||
|
||
- `GET /export`、`GET /export.csv`：旧版 JSON/UTF-8-BOM CSV v1 轻量导出，不是完整备份
|
||
- `POST /restore?mode=merge|replace`、`POST /restore.csv?mode=merge|replace`：兼容旧 JSON/CSV v1
|
||
- 旧格式只覆盖文件夹、清单、任务、重复模板、习惯、倒数日和备忘录；不包含日志、暂停、重复例外和附件字节
|
||
|
||
## 健康检查
|
||
|
||
- `GET /health/live`
|
||
- `GET /health/ready`
|