From 339f9aa126f98e0fbe564094720756d8c4a0b12f Mon Sep 17 00:00:00 2001 From: zhi Date: Sun, 29 Mar 2026 15:01:35 +0000 Subject: [PATCH] =?UTF-8?q?DOC-003:=20=E6=95=B4=E7=90=86=20Calendar=20?= =?UTF-8?q?=E9=AA=8C=E6=94=B6=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作 - 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限 - CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展 - 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart - 跨模块集成验收项 --- plans/CALENDAR_ACCEPTANCE_CHECKLIST.md | 169 +++++++++++++++++++++++++ plans/TASKLIST.md | 12 +- 2 files changed, 175 insertions(+), 6 deletions(-) create mode 100644 plans/CALENDAR_ACCEPTANCE_CHECKLIST.md diff --git a/plans/CALENDAR_ACCEPTANCE_CHECKLIST.md b/plans/CALENDAR_ACCEPTANCE_CHECKLIST.md new file mode 100644 index 0000000..01866d0 --- /dev/null +++ b/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 [--job ] [--date ]` 正常工作 +- [ ] `hf calendar show [--date ]` 正常展示当日日程（真实 + 虚拟 slot 合并） +- [ ] `hf calendar edit [--date] [--slot-type] [--estimated-duration] [--job] [--scheduled-at]` 正常工作 +- [ ] `hf calendar cancel [--date] ` 正常工作 +- [ ] `hf calendar date-list` 列出有已物化日程的未来日期 + +### 3.3 计划操作命令 + +- [ ] `hf calendar plan-schedule --at [--on-day] [--on-week] [--on-month]` 正常工作 +- [ ] `hf calendar plan-list` 列出所有计划 +- [ ] `hf calendar plan-edit [options]` 正常工作 +- [ ] `hf calendar plan-cancel ` 正常工作 + +### 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 diff --git a/plans/TASKLIST.md b/plans/TASKLIST.md index aa5437b..666e135 100644 --- a/plans/TASKLIST.md +++ b/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