待办
列表、发布、勾选/取消、定位与审核
路径未版本化
最后更新：2026-10-25
待办
GET /api/todos
认证：是。班级：必需。用途：按当前用户可见范围返回待办，分为待完成和已完成。
| 参数 | 位置 | 说明 |
|---|---|---|
class | query | 可选，指定班级 id 或 slug；不传用自己加入的班 |
{
"ok": true,
"data": {
"pending": [ { "id": 55, "title": "交实验报告", "scope": "class", "done": false, "pending_review": false, "overdue": false, "time_label": "截止 10-30 23:59", "visible_label": "全班", "geo": null } ],
"finished": [ { "id": 54, "title": "青年大学习", "scope": "class", "done": true, "done_at": "2026-10-24 20:11:03" } ]
},
"meta": { "classId": 3, "isManager": false, "canPublish": false, "pendingCount": 1, "finishedCount": 1 }
}待办对象包含待办行的原始字段（如 start_at、due_at、status、source_key、created_at 等）以及以下派生字段：
| 字段 | 说明 |
|---|---|
scope | class 班级待办；personal 个人待办 |
creator_name / creator_username / system_generated | 发布人；今日课程自动生成的待办显示为「系统自动」 |
time_label / has_time / only_in_window | 时间文案、是否有时间、是否仅时间内可完成 |
visible_label / group_list | 可见范围文案、分组徽章数组 |
geo | {name, radius} 或 null。注意：当前实现会随待办行一并返回 geo_lat/geo_lng/geo_radius 等原始字段（完整清单以源码 TODO_FIELDS 为准）；geo 只是给界面展示的派生字段，客户端不应把坐标展示给其他同学 |
done / pending_review / done_at / overdue | 是否已完成、是否待审核、完成时间、是否过期 |
done_count | 已完成人数 |
meta.isManager 表示当前用户是否可管理本班待办；meta.canPublish 表示是否可以发布班级待办。
POST /api/todos
认证：是。班级：必需。用途：发布班级待办或个人待办。班级待办需要班委及以上权限；个人待办任何已登入同学都可发布，且只有自己可见。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
title | string | 是 | 标题，最长 128 字符 |
content | string | 否 | 正文 |
scope | string | 否 | class 或 personal；不传时按权限推断（班委默认 class，同学默认 personal） |
visibleGroups | number[] | 否 | 班级待办的可见分组 id 数组；空数组表示全班；分组必须属于本班（个人待办忽略该字段） |
startAt | string | 否 | 开始时间；与 dueAt 至少填一个 |
dueAt | string | 否 | 结束/截止时间；与 startAt 至少填一个 |
onlyInWindow | boolean | 否 | 仅允许在开始–结束之间完成；开启时必须同时提供两个时间 |
needReview | boolean | 否 | 完成后需班委/班级管理员确认 |
geoLat / geoLng | number | 否 | 定位打卡坐标；坐标不合法时按“未开启定位”处理 |
geoRadius | number | 否 | 允许半径（米），服务端会归一化 |
geoName | string | 否 | 地点名称，最长 64 字符 |
status | string | 否 | 只有 closed 会写成关闭状态，其他值都按 published |
成功返回新待办的摘要：{id, title, scope, notified}。notified 是实际写入的通知条数；个人待办恒为 0。发布班级待办后会自动通知应完成的人，通知失败不会让发布失败。
curl -s -X POST "$BASE/api/todos" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "交实验报告",
"content": "周四前交到学习委员处",
"scope": "class",
"visibleGroups": [1, 2],
"startAt": "2026-10-26 08:00:00",
"dueAt": "2026-10-30 23:59:59",
"onlyInWindow": false,
"needReview": true
}'没有班委权限却指定 scope=class 会返回 403；visibleGroups 里出现不属于本班的分组返回 400；时间格式不接受时返回 400。
POST /api/todos/:id/toggle
认证：是。班级：必需。用途：勾选或取消「已完成」。再次调用会取消完成。
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
id | path | number | 待办 id，必须是正整数 |
lat / lng | body | number | 当前定位坐标；待办要求定位时必须提供且在允许半径内 |
accuracy | body | number | 定位精度（米），可选 |
成功返回 {done, pending, title}：普通待办变成完成时 done=true；需要审核的待办提交后 done=false, pending=true；取消完成时两者都为 false。
curl -s -X POST "$BASE/api/todos/55/toggle" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"lat":30.123456,"lng":114.123456,"accuracy":20}'- 待办不存在、已删除或属于其他班：404；待办对当前用户不可见：403。
- 时间窗口不满足或定位超出范围：400，错误信息会说明原因。
- 取消完成不校验定位和时间窗口。