# 工单与待办

[项目](projects.md)是一等容器，承载人、Agent 和仓库，其 `kind` 为 product、ops、platform 或 internal。工单记录问题及其复现步骤、预期行为和实际行为。待办跟踪计划中的工作，包含负责人、可选的 Agent 委派、优先级和截止日期。两者都支持评论、附件、关联和个人视图。Work 管理员可以查看全实例范围的视图和工作负载分析。

![合成示例工作区中的工单](/images/tickets.png "跨项目的工单列表。")

## 推进工作

1. 打开或创建项目；绑定仓库和成员（人和 Agent）。
2. 创建工单或待办，填写清晰的标题和项目 id。
3. 指派一位人类负责人；可以为 Agent 设置 `delegate_login`，并填写验收标准。Agent 在编码前应调用 `project_context`。
4. 关联相关工作和执行证据。待办可以创建关联工单。
5. 记录进展并更新状态。推迟待办需要填写原因。
6. 验证已修复的工单，并在合适时归档。

## 工单

工单依次经过待办、进行中，修复就绪后进入**待验证**。由其创建者（报告人）或 Work 管理员验证：通过则关闭，不通过则以 `status_reason` 驳回，开发者再把被驳回的工单改回进行中。其他人不能关闭或驳回工单。每次验证都是一条 `verification` 事件，带有结果和原因；`rejections` 统计不通过的次数。工单进入待验证时会通知其创建者；驳回时还会通知其指派人。视图 `verifying` 和 `rejected` 分别列出这两类工单，`ticket_nav` 统计其数量。`ticket_list` 可以接受多个项目（`project=a,b`），也可以用 `unassigned_project=true` 查询没有项目的工单。

在等待验证的工单上，报告人会看到「验证通过」和「验证不通过」；选择不通过时需要填写原因，每次结果都会显示在工单的时间线中。工单列表在状态旁显示 「未通过 N 次」，侧栏有「待验证」和「未通过」，「项目」列标题可以选择任意多个项目以及 「未归属项目」；所选条件保存在页面地址中。

## 截止日、预估与延期

`due_at` 和 `start_at` 是 Asia/Shanghai 时区的日期；传入 `YYYY-MM-DD` 或当天的任意时间均可。截止日在 23:59:59 结束，待办只有在截止日结束后才算逾期，列表（`overdue=true`）、计数（`planning_progress` 的 `overdue`）和仪表盘都使用同一规则。把截止日往后推需要填写 `due_change_reason`，并使 `deferrals` 加一；`deferred=true` 列出这些待办，`sort=deferrals` 按延期次数排序。`estimate_minutes` 是计划工作量（480 为一天），[迭代](iterations.md)中的容量和燃尽图会用到它。

在 Web 应用中，待办的预估以天为单位，提供快捷选项（0.5、1、2、3、5）；表格有可排序的「预估工时」列，并标出超出预估的已记录工时。「已延期 N 次」显示在列表、卡片和待办页的截止日旁，悬停可看到每次调整及其原因。加入已开始迭代的待办会带有「计划外」标记。

工作记录在实例内共享。个人筛选可以帮你聚焦自己的队列，但不会让这些记录变为私有。

## 追踪流程

[追踪](track.md)按类型模板的各个阶段，从上报到发布，跟踪工单、待办、迭代、交付或失败的 Argos 用例。在 PR、分支或提交信息中提及待办或工单（`todo#123`、`ticket#45`、`todo-123`、`T-123`），Acahti 会自动建立关联；也可以把 PR、流水线或 Argos 运行的 URL 粘贴到待办的 「关联工作」 中手动关联。

## 通知与自动化

铃铛显示未读通知，并链接回相关记录。状态变更会通知记录的创建者进行复核。产品迭代的编辑会通知其负责人和参与者。浏览器会收到实时刷新事件。外部 Agent 使用 `notification_nav`、`notification_list`、`notification_mark_read` 和 `notification_mark_all_read` 处理同一个收件箱。通知只是提醒你去查看证据，并不代表自动批准。

## 工时与仪表盘

用 `time_entry_save` 在待办上记录完成工时。每日总量不设上限；单条记录最多十六小时。`time_entry_suggest` 根据你的实际工作提议当天的工时记录：当天进行中或有改动的待办，以及提及 `todo#N` 的提交、PR 和评审，并按活动量分配八小时工作日中尚未记录的部分。在你确认前不会保存任何内容；Aidy 会把这些建议转换成 `time_entry_save` 调用，等待你批准。工作日 18:00 起，有进行中的待办但当天未记录工时的人会收到一次提醒。在 Web 应用中完成待办（通过修改状态、在看板上拖动或在待办页操作）会打开其工时填报，并预填当天的建议；关闭即可跳过。提醒会打开「填写当天工时」：列出每个建议的待办及其证据和小时数，可逐条一键记录，或选择「让 Aidy 帮我填」。Work 管理员可以看到风险、按项目和指派人的拆分、新增和完成趋势。看板还会显示仓库活动、失败或受阻的流水线，以及可合并的 PR。

```bash
acahti mcp call ticket_list '{"view":"mine"}'
acahti mcp call todo_list '{"view":"mine"}'
acahti mcp call notification_list '{"page":1,"page_size":20}'
```

## 规划与执行

待办的 `requirement` 状态即需求池。管理员的 `progress` 视图选出所有作者中状态恰为 `in_progress` 的待办；普通成员只看到自己的范围。`closed_at` 与状态相互独立，因此关闭已完成的工作会保留完成状态。所有待办更新都需要提供当前的 `revision`；遇到 409 冲突时请刷新。

选择同一项目的多个工单，可以创建一个待办，需要指定迭代和截止日期。文档选择基于按权限过滤的目录树；选择文件夹会纳入其当前所有可读的下级内容。详情页支持逐个关联和取消关联工单、文档、PR、流水线和 Argos 运行。

工时报告列出所有日期和作者，提供完整合计和分页。每位成员可以添加自己的报告并删除自己的记录。待办在看板上打开；拖动卡片即可更改状态。看板、表格和时间线使用相同的筛选条件；时间线使用实际的开始和截止日期，只有截止日期的条目显示为里程碑。移动端还提供任务列表。

通过 MCP 或其文档中的 REST 路由使用 `planning_todo_time`、`planning_todo_links`、`planning_progress` 和 `planning_move_todos`。批量移动需要提供修订号和稳定的幂等键。Agent 的运行步骤驱动 Trace 和 DAG 视图。共享的交付流程见[迭代](iterations.md)。