DOC-003: 整理 Calendar 验收清单
- 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作 - 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限 - CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展 - 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart - 跨模块集成验收项
This commit is contained in:
169
plans/CALENDAR_ACCEPTANCE_CHECKLIST.md
Normal file
169
plans/CALENDAR_ACCEPTANCE_CHECKLIST.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user