任务 - TaskNeo

任务只属于一个班级。只有 OWNER 和 ADMIN 可以创建、更新或删除任务。所有班级成员都可以阅读已发布任务。

所有任务接口都需要有效的 Authorization: Bearer <token> 头。

GET /classes/:classId/tasks

返回班级中的所有活跃任务。每个任务都包含当前用户的个人状态（userState），用于记录查看时间、标签和排序顺序。 Path parameters

classId

string

required

班级 UUID。

Response — 200 OK 任务摘要对象数组。

string

required

任务 UUID。

classId

string

required

该任务所属班级 UUID。

className

string

required

班级名称。

title

string

required

任务标题。

startAt

string

任务对成员可见的时间，或 null。

dueAt

string

提交截止时间，或 null。

allowLateSubmission

boolean

required

是否在 dueAt 后仍接受提交。

blockedBy

string[]

required

在解锁此任务前必须完成的任务 UUID 数组。

createdBy

string

创建该任务的用户 UUID，或 null。

createdAt

string

required

ISO 8601 UTC 时间戳。

updatedAt

string

required

ISO 8601 UTC 时间戳。

submittedCount

integer

required

已提交成员数。

memberCount

integer

required

班级成员总数。

userState

object

当前用户在该任务上的个人状态；如果尚未有任何交互，则为 null。

Show properties

viewedAt

string

用户首次查看任务的时间，或 null。

状态	何时发生
`403 Forbidden`	你不是这个班级的成员。

POST /classes/:classId/tasks

在班级中创建新任务。需要 OWNER 或 ADMIN 角色。 Path parameters

classId

string

required

班级 UUID。

Request body

title

string

required

任务标题。

description

string

Markdown 正文内容。传入 null 可保持为空。

startAt

string

任务对成员可见时的 ISO 8601 UTC 日期时间。传入 null 表示立即可见。

dueAt

string

ISO 8601 UTC 提交截止时间。传入 null 表示没有截止时间。

allowLateSubmission

boolean

default:"true"

是否接受 dueAt 之后的提交。

blockedBy

string[]

default:"[]"

在此任务解锁前必须完成的任务 UUID 数组。

Response — 201 Created 返回完整的任务详情对象（除了摘要字段外，还包含 description 和 attachments）。 Error codes

状态	何时发生
`403 Forbidden`	权限不足（必须是 OWNER 或 ADMIN）。

curl -X POST https://api.yourdomain.com/classes/c1a2b3c4-.../tasks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Assignment 1: Hello World",
    "description": "Write a program that prints Hello World.",
    "dueAt": "2025-09-15T23:59:00.000Z",
    "allowLateSubmission": true
  }'

GET /classes/:classId/tasks/drafts/mine

返回指定班级中当前用户最近的未发布草稿任务。只有 OWNER 和 ADMIN 可以调用此接口。 Path parameters

classId

string

required

班级 UUID。

Response — 200 OK

draft

object

包含 attachments 数组的草稿任务对象；若不存在草稿则为 null。

curl https://api.yourdomain.com/classes/c1a2b3c4-.../tasks/drafts/mine \
  -H "Authorization: Bearer <token>"

GET /tasks/:taskId

获取任务完整详情，包括 Markdown 正文和附件。OWNER 和 ADMIN 还会收到一个包含查看和提交数量的 stats 对象。

此接口不会记录任务被查看。请单独调用 POST /tasks/:taskId/view 将其标记为已读。

Path parameters

taskId

string

required

任务 UUID。

Response — 200 OK

string

required

任务 UUID。

title

string

required

任务标题。

description

string

Markdown 正文，或 null。

attachments

object[]

required

已附加文件列表。

Show attachment properties

string

required

附件 UUID。

fileKey

string

required

用于获取文件的存储键。

originalName

string

required

原始文件名。

mimeType

string

MIME 类型，或 null。

sizeBytes

integer

文件大小（字节），或 null。

url

string

required

指向 GET /files/:fileKey 的 URL。

createdAt

string

required

ISO 8601 UTC 时间戳。

stats

object

仅 OWNER 和 ADMIN 可见。

Show stats properties

memberCount

integer

班级成员总数。

viewedCount

integer

已查看该任务的成员。

submittedCount

integer

已提交的成员。

Error codes

状态	何时发生
`403 Forbidden`	你无权访问此任务。
`404 Not Found`	任务不存在或已被删除。

curl https://api.yourdomain.com/tasks/t1a2b3c4-... \
  -H "Authorization: Bearer <token>"

PATCH /tasks/:taskId

更新任务字段。需要 OWNER 或 ADMIN 角色。 Path parameters

taskId

string

required

任务 UUID。

Request body

title

string

新标题。

description

string

新的 Markdown 正文。传入 null 可清空。

startAt

string

新的 ISO 8601 UTC 开始时间。传入 null 可清空。

dueAt

string

新的 ISO 8601 UTC 截止时间。传入 null 可清空。

allowLateSubmission

boolean

是否允许迟交。

blockedBy

string[]

更新后的阻塞任务 UUID 列表。

Response — 200 OK 返回完整的更新后任务详情对象。 Error codes

状态	何时发生
`403 Forbidden`	权限不足。

curl -X PATCH https://api.yourdomain.com/tasks/t1a2b3c4-... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dueAt": "2025-09-20T23:59:00.000Z"}'

DELETE /tasks/:taskId

删除任务。需要 OWNER 或 ADMIN 角色。

若任务没有提交：执行硬删除 - 所有数据和附件都会被永久移除。
若任务已有提交：执行软删除 - 正文和附件会被清空，但任务记录会保留，以便提交仍可引用它。

Path parameters

taskId

string

required

任务 UUID。

Response — 204 No Content Error codes

状态	何时发生
`403 Forbidden`	权限不足。

curl -X DELETE https://api.yourdomain.com/tasks/t1a2b3c4-... \
  -H "Authorization: Bearer <token>"

POST /tasks/:taskId/view

记录当前用户已查看某个任务。成员打开任务详情页时调用此接口。只有第一次调用会设置 viewedAt - 后续调用不会产生变化。

这是一个一次性发送的调用。即使失败，也请继续向用户展示任务 - 该错误不会影响阅读体验。

Path parameters

taskId

string

required

任务 UUID。

Response — 204 No Content

curl -X POST https://api.yourdomain.com/tasks/t1a2b3c4-.../view \
  -H "Authorization: Bearer <token>"

POST /tasks/parse

使用 AI 将自然语言任务描述解析为结构化字段。该接口不会创建任务 - 只会返回解析建议。

如果 LLM 调用失败或返回了意外格式，该接口仍会返回 200，并将所有字段设为 null（优雅降级）。

Request body

text

string

required

自然语言任务描述，例如 "Submit the lab report by next Friday, no late submissions"。

Response — 200 OK

title

string

Suggested task title, or null.

timeOptions

object[]

1 到 3 种可能的开始/截止时间解释。输入含糊时会返回多个选项。

Show properties

startAt

string

建议的开始时间，ISO 8601 UTC 格式，或 null。

dueAt

string

建议的截止时间，ISO 8601 UTC 格式，或 null。

allowLateSubmission

boolean

解析出的迟交偏好；若未提及则为 null。

description

string

建议的 Markdown 正文，或 null。

curl -X POST https://api.yourdomain.com/tasks/parse \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Lab report due next Friday at midnight, no late submissions allowed"}'

POST /tasks/:taskId/parse

使用 AI 解析草稿任务，并整合已上传的附件。会自动更新草稿的 title、startAt、dueAt 和 description（使用第一个 timeOption）。还会生成并缓存可通过 GET /tasks/:taskId/draft-markdown 获取的 Markdown 草稿。只有 OWNER 和 ADMIN 可以调用此接口。 Path parameters

taskId

string

required

草稿任务 UUID。

Request body

text

string

自然语言描述。若省略，则使用该任务现有的 sourceText。

Response — 200 OK 与 POST /tasks/parse 相同的字段，外加：

markdownCached

boolean

是否已生成 Markdown 草稿并可供检索。

curl -X POST https://api.yourdomain.com/tasks/t9a8b7c6-.../parse \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Lab report due next Friday, no late submissions"}'

GET /tasks/:taskId/draft-markdown

从之前的 POST /tasks/:taskId/parse 调用中获取 AI 生成的 Markdown 草稿。该草稿在解析后可保留 3 天。只有 OWNER 和 ADMIN 可以调用此接口。 Path parameters

taskId

string

required

草稿任务 UUID。

Response — 200 OK

markdown

string

缓存的 Markdown 内容；如果不存在缓存或已过期则为 null。

curl https://api.yourdomain.com/tasks/t9a8b7c6-.../draft-markdown \
  -H "Authorization: Bearer <token>"

POST /tasks/:taskId/attachments

向任务正文上传文件附件。需要 OWNER 或 ADMIN 角色。接受 multipart/form-data。 Path parameters

taskId

string

required

任务 UUID。

Request body (multipart/form-data)

file

required

要上传的文件。

Response — 201 Created

string

required

附件 UUID。

fileKey

string

required

存储键。

originalName

string

required

原始文件名。

mimeType

string

MIME 类型。

sizeBytes

integer

文件大小（字节）。

url

string

required

指向 GET /files/:fileKey 的 URL。

createdAt

string

required

ISO 8601 UTC 时间戳。

Error codes

状态	何时发生
`403 Forbidden`	权限不足。

curl -X POST https://api.yourdomain.com/tasks/t1a2b3c4-.../attachments \
  -H "Authorization: Bearer <token>" \
  -F "file=@assignment-brief.pdf"

概览

接口

​GET /classes/:classId/tasks

​POST /classes/:classId/tasks

​GET /classes/:classId/tasks/drafts/mine

​GET /tasks/:taskId

​PATCH /tasks/:taskId

​DELETE /tasks/:taskId

​POST /tasks/:taskId/view

​POST /tasks/parse

​POST /tasks/:taskId/parse

​GET /tasks/:taskId/draft-markdown

​POST /tasks/:taskId/attachments

GET /classes/:classId/tasks

POST /classes/:classId/tasks

GET /classes/:classId/tasks/drafts/mine

GET /tasks/:taskId

PATCH /tasks/:taskId

DELETE /tasks/:taskId

POST /tasks/:taskId/view

POST /tasks/parse

POST /tasks/:taskId/parse

GET /tasks/:taskId/draft-markdown

POST /tasks/:taskId/attachments