feat: complete task management workflow

docs/api.md

@@ -1,27 +1,56 @@
 # API
 
-Base path: `/api/v1`
+Base path: `/api/v1`. 除初始化、登录和健康检查外均需 `dodo_session` Cookie。
 
 ## Setup / Auth
+
 - `GET /setup/status`
 - `POST /setup/initialize`
 - `POST /auth/login`
+- `POST /auth/logout`
 - `GET /me`
 
 ## Folders
-- `GET /folders`
-- `POST /folders`
+
+- `GET /folders` — 仅返回未删除文件夹
+- `POST /folders` — 创建文件夹
+- `PATCH /folders/{folder_id}` — 重命名
+- `DELETE /folders/{folder_id}` — 软删除；其清单移到根层级
 
 ## Lists
-- `GET /lists`
-- `POST /lists`
+
+- `GET /lists` — 仅返回未删除清单，系统收集箱排首位
+- `POST /lists` — 创建清单，可指定 `folder_id`
+- `PATCH /lists/{list_id}` — 重命名；系统收集箱返回 409
+- `DELETE /lists/{list_id}` — 软删除并将任务移入系统收集箱；系统收集箱返回 409
+
+## Tags
+
+标签属于当前用户，可跨清单复用。
+
+- `GET /tags`
+- `POST /tags` — `{name, color}`；同一用户名称唯一
 
 ## Tasks
-- `GET /tasks`
-- `POST /tasks`
-- `PATCH /tasks/{task_id}` — 必须携带当前 `version`，冲突返回 409
-- `DELETE /tasks/{task_id}` — 软删除
+
+- `GET /tasks?q=&limit=&cursor=` — 顶层未删除任务的游标分页；`q` 匹配标题、描述、标签名和清单名
+- `POST /tasks` — 创建任务；`parent_id` 只允许指向同清单顶层任务；`tag_ids` 必须属于当前用户
+- `GET /tasks/{task_id}` — 返回任务、标签和一层子任务
+- `PATCH /tasks/{task_id}` — 必须携带当前 `version`，原子比较更新；版本冲突返回 409
+- `DELETE /tasks/{task_id}` — 软删除任务及其直接子任务
+- `POST /tasks/{task_id}/restore` — 恢复任务及其直接子任务
+- `POST /tasks/batch` — 原子批量完成、移动、设置截止时间、替换标签或软删除
+
+批量请求字段：`task_ids`、`completed`、`list_id`、`due_at`、`tag_ids`、`soft_delete`。所有任务、目标清单和标签在写入前完成归属校验；任一不存在则整批不修改。
+
+## Recycle bin
+
+- `GET /trash?limit=&cursor=` — 已删除顶层任务的游标分页
+- `DELETE /trash/{task_id}` — 永久删除任务及其子任务
+
+游标是不透明字符串。无效游标返回 422；`limit` 范围为 1–100。
 
 ## Health
+
 - `GET /health/live`
 - `GET /health/ready`