# Calendar 验收清单

> 基于 `NEXT_WAVE_DEV_DIRECTION.md` 设计文档整理
> Date: 2026-03-29

---

## 一、后端验收项 (Backend)

### 1.1 数据模型

- [ ] `TimeSlot` 模型已创建，字段完整（slot_id, user_id, date, slot_type, estimated_duration, scheduled_at, started_at, attended, actual_duration, event_type, event_data, priority, status, plan_id, created_at, updated_at）
- [ ] `SchedulePlan` 模型已创建，字段完整（id, user_id, slot_type, estimated_duration, event_type, event_data, at_time, on_day, on_week, on_month, created_at, updated_at）
- [ ] Agent 表已扩展字段：status, last_heartbeat, exhausted_at, recovery_at, exhaust_reason
- [ ] 枚举类型已定义：SlotType (Work, OnCall, Entertainment, System)、SlotStatus (NotStarted, Ongoing, Deferred, Skipped, Paused, Finished, Aborted)、EventType (Job, Entertainment, SystemEvent)、AgentStatus (Idle, OnCall, Busy, Exhausted, Offline)、ExhaustReason (RateLimit, Billing)
- [ ] SchedulePlan 周期参数层级约束已实现（on_month 需 on_week，on_week 需 on_day，at 始终必填）
- [ ] MinimumWorkload 存储方案已实现（用户级配置读写）

### 1.2 Slot ID 策略与物化

- [ ] 已物化 slot 使用数据库自增 ID
- [ ] Plan 虚拟 slot 使用 `plan-{plan_id}-{date}` 标识
- [ ] 虚拟 slot 被 edit/cancel 时物化到数据库，断开 plan 关联
- [ ] Plan 不预展开，只存规则

### 1.3 验证规则

- [ ] Overlap 检测：同日时间重叠 → 拒绝并报错
- [ ] Overlap 检测区分 create 与 edit 场景
- [ ] MinimumWorkload warning：不满足时返回 warning 但允许提交
- [ ] Warning 数据结构统一定义
- [ ] 计算 daily / weekly / monthly / yearly 工作量

### 1.4 不可变性规则

- [ ] 禁止 edit 过去的 slot
- [ ] 禁止 cancel 过去的 slot
- [ ] plan-edit / plan-cancel 不追溯过去已物化 slot

### 1.5 Calendar API

- [ ] `POST` 单次日程创建：支持 slot_type, scheduled_at, estimated_duration, job/system/event_data，接入 overlap 与 workload warning
- [ ] `GET` 某日 Calendar 查询：返回真实 slot + 合成当日 plan 虚拟 slot，统一排序
- [ ] `PATCH/PUT` Calendar 编辑：支持真实 slot 编辑 + 虚拟 slot 编辑并触发物化
- [ ] `DELETE/POST` Calendar 取消：支持真实 slot cancel + 虚拟 slot cancel 并触发物化，状态字段更新
- [ ] `POST` plan-schedule：创建周期性计划
- [ ] `GET` plan-list：列出所有计划
- [ ] `PATCH/PUT` plan-edit：编辑计划，不追溯过去已物化数据
- [ ] `POST/DELETE` plan-cancel：取消计划，不追溯过去已物化数据
- [ ] `GET` date-list：仅列出有已物化未来 slot 的日期，排除纯 plan 未物化日期

### 1.6 Agent / 心跳协作

- [ ] 心跳查询服务：筛选当天 NotStarted / Deferred 且 scheduled_at 已过的 slot，按优先级排序
- [ ] Agent 状态流转：Idle ↔ Busy/OnCall、超时→Offline、API错误→Exhausted
- [ ] 多 slot 竞争：选最高 priority 执行，其余 Deferred，Deferred slot priority += 1
- [ ] Exhausted 恢复时间解析：解析 retry-after / reset in / resets at，失败默认 5 小时，到期恢复 Idle

---

## 二、前端验收项 (Frontend)

### 2.1 页面骨架

- [ ] Calendar 路由入口已添加
- [ ] 侧边栏 Calendar 入口已添加
- [ ] Calendar 基础页面布局完成

### 2.2 日程展示

- [ ] 某日 slot 列表展示（时间轴或列表视图）
- [ ] 区分真实 slot 与 plan 虚拟 slot（视觉区分）
- [ ] 展示 status / type / duration / priority 等核心字段

### 2.3 计划展示

- [ ] 计划列表展示：规则、周期参数
- [ ] 支持从计划列表跳转编辑

### 2.4 日程操作交互

- [ ] 新建 slot 表单（含 slot_type, scheduled_at, estimated_duration, event_data 等）
- [ ] 编辑 slot 表单
- [ ] Cancel 操作确认弹窗
- [ ] 展示后端返回的 warning（workload 不足等）

### 2.5 状态提示

- [ ] Deferred 状态提示
- [ ] Overlap 报错展示
- [ ] Workload warning 展示
- [ ] Exhausted 状态展示（含预计恢复时间）

### 2.6 权限

- [ ] 普通用户仅查看/调整自己的日程表
- [ ] Admin 可查看/调整所有用户的日程表

---

## 三、CLI 验收项 (CLI)

### 3.1 命令组

- [ ] `hf calendar` 命令组已注册，help 正常输出

### 3.2 日程操作命令

- [ ] `hf calendar schedule <slot-type> <scheduled-at> <estimated-duration> [--job <code>] [--date <yyyy-mm-dd>]` 正常工作
- [ ] `hf calendar show [--date <yyyy-mm-dd>]` 正常展示当日日程（真实 + 虚拟 slot 合并）
- [ ] `hf calendar edit [--date] <slot-id> [--slot-type] [--estimated-duration] [--job] [--scheduled-at]` 正常工作
- [ ] `hf calendar cancel [--date] <slot-id>` 正常工作
- [ ] `hf calendar date-list` 列出有已物化日程的未来日期

### 3.3 计划操作命令

- [ ] `hf calendar plan-schedule <slot-type> <estimated-duration> --at <HH:mm> [--on-day] [--on-week] [--on-month]` 正常工作
- [ ] `hf calendar plan-list` 列出所有计划
- [ ] `hf calendar plan-edit <plan-id> [options]` 正常工作
- [ ] `hf calendar plan-cancel <plan-id>` 正常工作

### 3.4 输出格式

- [ ] 所有命令支持 JSON 输出（`--json` 或类似选项）
- [ ] 错误信息（overlap 等）清晰明确
- [ ] Warning 信息（workload 不足等）正常展示

### 3.5 用户创建扩展

- [ ] `hf user create` 支持 `--agent-id` + `--claw-identifier` 参数
- [ ] 两参数必须同时出现或同时不出现
- [ ] pcexec 模式下自动从环境变量 / openclaw config 获取

---

## 四、插件联动验收项 (OpenclawPlugin)

### 4.1 心跳请求

- [ ] 插件每分钟向 HarborForge 发送心跳
- [ ] 心跳请求正确传递 claw_identifier 和 agent_id
- [ ] 正确接收返回的 slot 列表

### 4.2 唤醒逻辑

- [ ] Agent Idle 时：唤醒 agent，透传任务上下文，更新 attended/started_at/status
- [ ] Agent 非 Idle 时：上报 Deferred
- [ ] 多 slot 竞争时正确选择最高 priority

### 4.3 状态管理

- [ ] 超过 2 分钟无心跳 → Agent 标记 Offline
- [ ] API rate-limit / billing 错误 → Agent 标记 Exhausted
- [ ] Exhausted 恢复计时器到期 → Agent 恢复 Idle

### 4.4 ScheduledGatewayRestart 处理

- [ ] 收到 ScheduledGatewayRestart 事件后持久化状态
- [ ] 发送最终心跳
- [ ] 暂停定时任务

---

## 五、跨模块集成验收

- [ ] 完整流程：创建 plan → 心跳触发物化 → Agent 被唤醒执行 → slot 状态更新为 Finished
- [ ] 完整流程：schedule 单次日程 → CLI 查看 → 前端查看 → Agent 执行
- [ ] Overlap / Warning 全链路：后端检测 → CLI 展示 → 前端展示
- [ ] Exhausted 全链路：Agent 报错 → 后端标记 Exhausted → 前端展示 → 恢复后自动 Idle