zhi/HarborForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eece0773cba5b1f003f1d0c55c1e87696a6febc0
HarborForge/plans/CALENDAR_ACCEPTANCE_CHECKLIST.md
zhi 339f9aa126 DOC-003: 整理 Calendar 验收清单 
- 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作
- 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限
- CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展
- 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart
- 跨模块集成验收项
2026-03-29 15:01:35 +00:00

6.7 KiB
Raw Blame History

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 View Git Blame Copy Permalink