DOC-003: 整理 Calendar 验收清单

- 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作
- 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限
- CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展
- 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart
- 跨模块集成验收项

plans/CALENDAR_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,169 @@
+# 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

plans/TASKLIST.md

@@ -10,7 +10,7 @@
 
 ## A. Root / Docs(根目录与规划文档)
 
-- [x] DOC-001：整理本波开发范围说明（root docs only）
+- [x] DOC-001:整理本波开发范围说明(root docs only)
   - [x] 明确 Calendar 属于独立功能线
   - [x] 明确 Proposal / Essential 属于项目结构调整线
   - [x] 明确两条线的交叉点仅限 `event_data` / Agent 调度引用层
@@ -22,11 +22,11 @@
   - [x] 说明 `story/*` 改为 restricted 的影响面
   - [x] 说明旧数据和旧接口的兼容策略
 
-- [ ] DOC-003:整理 Calendar 验收清单(root docs only)
-  - [ ] 列出后端验收项
-  - [ ] 列出前端验收项
-  - [ ] 列出 CLI 验收项
-  - [ ] 列出插件联动验收项
+- [x] DOC-003：整理 Calendar 验收清单(root docs only)
+  - [x] 列出后端验收项
+  - [x] 列出前端验收项
+  - [x] 列出 CLI 验收项
+  - [x] 列出插件联动验收项
 
 ## B. HarborForge.Backend - Proposal / Essential / Story restricted