diff --git a/plans/TASKLIST.md b/plans/TASKLIST.md index 0dbca8e..f08debf 100644 --- a/plans/TASKLIST.md +++ b/plans/TASKLIST.md @@ -1,121 +1,379 @@ # TASKLIST.md > 说明：如果某个进行中的 Task 没有完全完成，或者在执行过程中遇到 block，需要在该 Task 下继续拆分若干子 TODO item：本次开发中已经完成的部分标记为已完成，block / pending / 尚未完成的部分标记为未完成。 +> +> 拆分原则：尽量保证 Task 之间相互独立；每个 Task 最好只改动一个子模块（如 `HarborForge.Backend` / `HarborForge.Frontend` / `HarborForge.Cli` / `HarborForge.OpenclawPlugin` / 根目录文档），避免一次任务同时横跨多个子模块。只有在确实无法避免时，才建立跨模块 Task。 --- # TODOLIST -- [ ] Task 1：整理并确认 Calendar / Proposal / Essential 的整体边界 - - [ ] 明确 Calendar 系统与 Proposal / Essential 结构调整的耦合边界 - - [ ] 确认哪些内容属于“本波开发必须实现” - - [ ] 确认哪些内容仅保留为设计备注或后续规划 +## A. Root / Docs（根目录与规划文档） -- [ ] Task 2：设计 Calendar 数据模型 - - [ ] 设计 `TimeSlot` 表结构 - - [ ] 设计 `SchedulePlan` 表结构 - - [ ] 设计 `MinimumWorkload` 存储方案 - - [ ] 设计 `slot_id` / plan 虚拟 slot 的标识策略 - - [ ] 定义 `event_type` 与 `event_data` 的结构约束 +- [ ] DOC-001：整理本波开发范围说明（root docs only） + - [ ] 明确 Calendar 属于独立功能线 + - [ ] 明确 Proposal / Essential 属于项目结构调整线 + - [ ] 明确两条线的交叉点仅限 `event_data` / Agent 调度引用层 + - [ ] 将“必须本波完成”和“仅设计保留”区分写清楚 -- [ ] Task 3：设计 Agent 日程唤醒与状态流转 - - [ ] 定义插件心跳请求 / 响应格式 - - [ ] 定义待执行 slot 的筛选规则 - - [ ] 定义 Agent Idle / Busy / OnCall / Exhausted / Offline 的状态流转 - - [ ] 定义多 slot 冲突时的优先级与 deferred 规则 - - [ ] 定义 Exhausted 状态的进入条件与恢复策略 +- [ ] DOC-002：整理 Proposal / Essential / Story restricted 的迁移说明（root docs only） + - [ ] 说明 `Propose -> Proposal` 的命名调整 + - [ ] 说明 `Proposal Accept` 语义变化 + - [ ] 说明 `story/*` 改为 restricted 的影响面 + - [ ] 说明旧数据和旧接口的兼容策略 -- [ ] Task 4：实现 Calendar 后端模型与数据库迁移 - - [ ] 新增 Calendar 相关模型 - - [ ] 新增数据库迁移或启动自修复逻辑 - - [ ] 处理 plan 物化与真实 slot 持久化逻辑 - - [ ] 处理不可编辑过去 slot 的限制 +- [ ] DOC-003：整理 Calendar 验收清单（root docs only） + - [ ] 列出后端验收项 + - [ ] 列出前端验收项 + - [ ] 列出 CLI 验收项 + - [ ] 列出插件联动验收项 -- [ ] Task 5：实现 Calendar 后端 API - - [ ] 实现单次日程创建接口 - - [ ] 实现日程查看接口 - - [ ] 实现日程编辑接口 - - [ ] 实现日程取消接口 - - [ ] 实现周期计划创建 / 编辑 / 取消 / 列表接口 - - [ ] 实现 overlap 检测 - - [ ] 实现 MinimumWorkload warning 机制 +## B. HarborForge.Backend — Proposal / Essential / Story restricted -- [ ] Task 6：实现 Calendar CLI - - [ ] 实现 `hf calendar schedule` - - [ ] 实现 `hf calendar show` - - [ ] 实现 `hf calendar cancel` - - [ ] 实现 `hf calendar edit` - - [ ] 实现 `hf calendar date-list` - - [ ] 实现 `hf calendar plan-schedule` - - [ ] 实现 `hf calendar plan-list` - - [ ] 实现 `hf calendar plan-cancel` - - [ ] 实现 `hf calendar plan-edit` +- [ ] BE-PR-001：后端统一重命名 `Propose` 概念为 `Proposal`（backend only） + - [ ] 盘点 `models / schemas / routers / services / tests` 中 `propose` 命名 + - [ ] 明确保留兼容别名还是直接切换 + - [ ] 输出重命名影响清单 -- [ ] Task 7：实现 Proposal 重命名为 Proposal 的后端改造 - - [ ] 将 `Propose` 概念统一重命名为 `Proposal` - - [ ] 调整后端模型 / schema / router 命名 - - [ ] 调整前端页面与 API 调用命名 - - [ ] 调整 CLI / 文档 / 测试中的命名 - - [ ] 处理兼容迁移策略（如旧接口别名或数据兼容） +- [ ] BE-PR-002：新增 Proposal 数据模型调整（backend only） + - [ ] 调整 Proposal 模型命名与字段注释 + - [ ] 确认 Proposal 与 `project_id / created_by_id / feat_task_id` 的后续关系 + - [ ] 标记 `feat_task_id` 是否废弃或替换 -- [ ] Task 8：设计并实现 Essential 数据模型 - - [ ] 新增 `Essential` 实体 - - [ ] 定义 `Essential` 与 `Proposal` 的关系 - - [ ] 定义 `Essential.type` 枚举：`feature` / `improvement` / `refactor` - - [ ] 设计 `EssentialCode` 编码规则 - - [ ] 实现 `EssentialCode` 自动生成逻辑 +- [ ] BE-PR-003：新增 Essential 模型（backend only） + - [ ] 新增 `Essential` SQLAlchemy model + - [ ] 增加 `proposal_id` 外键 + - [ ] 增加 `essential_code` + - [ ] 增加 `type / title / description / created_by_id / created_at / updated_at` -- [ ] Task 9：实现 Proposal / Essential 后端 API - - [ ] 实现 Proposal 下 Essential 的创建接口 - - [ ] 实现 Proposal 下 Essential 的编辑接口 - - [ ] 实现 Proposal 下 Essential 的删除接口 - - [ ] 实现 Proposal 详情中 Essential 列表返回 - - [ ] 实现 Proposal Accept 时选择目标 Milestone 的能力 +- [ ] BE-PR-004：实现 EssentialCode 编码规则（backend only） + - [ ] 参考现有 `ProjectCode / MilestoneCode / TaskCode / ProposeCode` 生成方式 + - [ ] 设计 Essential code 前缀 + - [ ] 实现唯一编号生成逻辑 + - [ ] 明确是否需要独立 counter 表 -- [ ] Task 10：重构 Proposal Accept 工作流 - - [ ] 移除“Accept 后生成单个 `story/feature` task”的旧逻辑 - - [ ] 改为遍历 Proposal 下所有 Essential - - [ ] 按 Essential 类型生成对应 `story/*` task - - [ ] 将生成的 task 统一挂到选定 Milestone - - [ ] 记录 Proposal 与生成 task 的追踪关系 - - [ ] 处理 Accept 时的事务一致性与失败回滚 +- [ ] BE-PR-005：新增 Essential 的 schema 定义（backend only） + - [ ] 新增 create schema + - [ ] 新增 update schema + - [ ] 新增 response schema + - [ ] 新增 Proposal detail 中嵌套 Essential 的返回结构 -- [ ] Task 11：收紧 Story 创建规则 - - [ ] 将 `story` 整个大类设为 restricted - - [ ] 禁止通过通用 task create endpoint 直接创建任意 `story/*` - - [ ] 仅允许通过 `Proposal Accept` 创建 `story/*` - - [ ] 调整前端 Task 创建页面，隐藏或禁用 story 创建入口 - - [ ] 调整 CLI 创建逻辑与错误提示 +- [ ] BE-PR-006：新增 Proposal 下 Essential CRUD API（backend only） + - [ ] 实现创建 Essential + - [ ] 实现编辑 Essential + - [ ] 实现删除 Essential + - [ ] 实现 Proposal 详情返回 Essential 列表 -- [ ] Task 12：实现 Calendar 前端页面 - - [ ] 设计日历页展示结构 - - [ ] 实现某日 slot 列表展示 - - [ ] 实现计划列表展示 - - [ ] 实现新增 / 编辑 / 取消日程交互 - - [ ] 实现 overlap / warning / deferred 状态提示 +- [ ] BE-PR-007：重构 Proposal Accept 逻辑（backend only） + - [ ] 移除“accept 后生成单个 `story/feature` task”的旧逻辑 + - [ ] Accept 时要求显式选择目标 Milestone + - [ ] 遍历 Proposal 下全部 Essential + - [ ] 按 Essential.type 生成对应 `story/*` task + - [ ] 保证批量创建在一个事务中完成 -- [ ] Task 13：实现 Proposal / Essential 前端页面 - - [ ] 调整 Proposal 列表与详情页命名 - - [ ] 在 Proposal 详情页增加 Essential 列表区域 - - [ ] 支持新增 / 编辑 / 删除 Essential - - [ ] 在 Accept 流程中增加目标 Milestone 选择 - - [ ] 展示 Accept 后生成的 story task 结果 +- [ ] BE-PR-008：补充 Proposal Accept 追踪字段/关系（backend only） + - [ ] 明确 Proposal 与生成 tasks 的映射方式 + - [ ] 设计是用反查字段、关联表还是事件记录 + - [ ] 实现最小可用追踪能力 -- [ ] Task 14：实现 acc-mgr 禁止修改密码的修复 - - [ ] 后端禁止修改 acc-mgr 密码 - - [ ] 前端隐藏 acc-mgr 修改密码入口 - - [ ] 补充测试覆盖该限制 +- [ ] BE-PR-009：收紧 Task 类型规则，限制全部 `story/*`（backend only） + - [ ] 更新 `TASK_SUBTYPE_MAP` 相关约束 + - [ ] 将所有 `story/*` 组合标记为 restricted + - [ ] 禁止通用 create endpoint 直接创建任何 story + - [ ] 保留内部受控入口用于 Proposal Accept -- [ ] Task 15：补齐测试 - - [ ] 补充 Calendar 模型 / API / CLI 测试 - - [ ] 补充 Proposal / Essential 工作流测试 - - [ ] 补充 Story restricted 相关测试 - - [ ] 补充 Proposal Accept 批量生成 story task 测试 - - [ ] 补充 acc-mgr 密码限制测试 +- [ ] BE-PR-010：清理旧的 `feat_task_id` 语义（backend only） + - [ ] 判断字段是否保留但废弃 + - [ ] 如果废弃，给出兼容读取策略 + - [ ] 如果替换，落地新的字段或关联方式 -- [ ] Task 16：补齐文档与迁移说明 - - [ ] 更新后端开发文档 - - [ ] 更新前端交互说明 - - [ ] 更新 CLI 使用文档 - - [ ] 补充 Proposal / Essential / Story restricted 的迁移说明 - - [ ] 补充本波开发完成后的验收清单 +- [ ] BE-PR-011：补 Proposal / Essential / Story restricted 的后端测试（backend only） + - [ ] Essential CRUD 测试 + - [ ] Proposal Accept 批量生成 story task 测试 + - [ ] 非受控入口创建 `story/*` 的失败测试 + - [ ] 兼容旧 proposal 数据的测试 + +## C. HarborForge.Backend — Calendar 基础模型与规则 + +- [ ] BE-CAL-001：新增 Calendar 基础模型 `TimeSlot`（backend only） + - [ ] 新增表结构 + - [ ] 定义 slot status / slot type / event type 枚举 + - [ ] 定义时间字段与时长字段 + - [ ] 定义 `plan_id` 关联 + +- [ ] BE-CAL-002：新增 Calendar 基础模型 `SchedulePlan`（backend only） + - [ ] 新增表结构 + - [ ] 定义 `at_time / on_day / on_week / on_month` + - [ ] 加入层级参数校验约束 + - [ ] 处理 user 归属关系 + +- [ ] BE-CAL-003：新增 Agent 扩展字段（backend only） + - [ ] 为 Agent 增加 `status / last_heartbeat` + - [ ] 增加 `exhausted_at / recovery_at / exhaust_reason` + - [ ] 明确与现有 user / monitor 标识的关系 + +- [ ] BE-CAL-004：实现 MinimumWorkload 存储方案（backend only） + - [ ] 确定 JSON 字段还是独立表 + - [ ] 实现用户级配置读写 + - [ ] 提供后续校验调用入口 + +- [ ] BE-CAL-005：实现 Plan 虚拟 slot 标识与物化策略（backend only） + - [ ] 实现 `plan-{plan_id}-{date}` 标识规则 + - [ ] 实现虚拟 slot 转真实 slot 的物化逻辑 + - [ ] 实现 edit / cancel 后断开 plan 关联 + +- [ ] BE-CAL-006：实现 Calendar overlap 校验（backend only） + - [ ] 校验同日时间冲突 + - [ ] 返回明确的冲突错误信息 + - [ ] 区分 create 与 edit 两种场景 + +- [ ] BE-CAL-007：实现 MinimumWorkload warning 规则（backend only） + - [ ] 计算 daily / weekly / monthly / yearly 工作量 + - [ ] 不阻止提交，仅返回 warning + - [ ] 统一 warning 数据结构 + +- [ ] BE-CAL-008：实现不可修改过去 slot 的规则（backend only） + - [ ] 禁止 edit 过去 slot + - [ ] 禁止 cancel 过去 slot + - [ ] 保证 plan-edit / plan-cancel 不追溯过去已物化 slot + +## D. HarborForge.Backend — Calendar API + +- [ ] BE-CAL-API-001：实现单次日程创建 API（backend only） + - [ ] 创建 slot + - [ ] 支持 job/system/event_data + - [ ] 接入 overlap 与 workload warning + +- [ ] BE-CAL-API-002：实现某日 Calendar 查询 API（backend only） + - [ ] 返回真实 slot + - [ ] 合成当日 plan 虚拟 slot + - [ ] 输出统一排序结构 + +- [ ] BE-CAL-API-003：实现 Calendar 编辑 API（backend only） + - [ ] 支持真实 slot 编辑 + - [ ] 支持虚拟 slot 编辑并触发物化 + - [ ] 返回编辑后的真实结果 + +- [ ] BE-CAL-API-004：实现 Calendar 取消 API（backend only） + - [ ] 支持真实 slot cancel + - [ ] 支持虚拟 slot cancel 并触发物化 + - [ ] 处理状态字段更新 + +- [ ] BE-CAL-API-005：实现 plan-schedule / plan-list API（backend only） + - [ ] 创建计划 + - [ ] 列出计划 + - [ ] 返回计划规则字段 + +- [ ] BE-CAL-API-006：实现 plan-edit / plan-cancel API（backend only） + - [ ] 编辑计划 + - [ ] 取消计划 + - [ ] 不追溯已物化过去数据 + +- [ ] BE-CAL-API-007：实现 date-list API（backend only） + - [ ] 仅列出有已物化未来 slot 的日期 + - [ ] 排除纯 plan 未物化日期 + +## E. HarborForge.Backend — Agent / Plugin Calendar 协作 + +- [ ] BE-AGT-001：定义心跳查询待执行 slot 的服务层（backend only） + - [ ] 筛选当天 `NotStarted / Deferred` + - [ ] 仅返回 `scheduled_at` 已过的 slot + - [ ] 按优先级排序 + +- [ ] BE-AGT-002：实现 Agent 状态流转服务（backend only） + - [ ] Idle -> Busy / OnCall + - [ ] Busy / OnCall -> Idle + - [ ] 超时无心跳 -> Offline + - [ ] API 配额错误 -> Exhausted + +- [ ] BE-AGT-003：实现多 slot 竞争处理（backend only） + - [ ] 选最高 priority 执行 + - [ ] 其余 slot 标记 Deferred + - [ ] Deferred slot 自动 priority += 1 + +- [ ] BE-AGT-004：实现 Exhausted 恢复时间解析（backend only） + - [ ] 解析 retry-after / reset in / resets at + - [ ] 解析失败时默认 5 小时 + - [ ] 到期恢复 Idle + +## F. HarborForge.Frontend — Proposal / Essential / Story restricted + +- [ ] FE-PR-001：前端统一重命名 Propose -> Proposal（frontend only） + - [ ] 调整页面标题与菜单文案 + - [ ] 调整类型名与 API 调用命名 + - [ ] 清理旧 propose 文案 + +- [ ] FE-PR-002：Proposal 详情页增加 Essential 列表区（frontend only） + - [ ] 展示 Essential 列表 + - [ ] 展示 Essential type / code / title + - [ ] 处理空状态 + +- [ ] FE-PR-003：新增 Essential 创建/编辑表单（frontend only） + - [ ] 创建表单 + - [ ] 编辑表单 + - [ ] type 选择器 + - [ ] 提交后局部刷新 + +- [ ] FE-PR-004：Proposal Accept 增加目标 Milestone 选择（frontend only） + - [ ] Accept 前展示 milestone 选择控件 + - [ ] 校验必须选择 milestone + - [ ] 展示 Accept 成功后的生成结果 + +- [ ] FE-PR-005：限制前端直接创建 `story/*`（frontend only） + - [ ] 从 Task 创建入口移除 story + - [ ] 或将 story 整体设为不可选 + - [ ] 调整相关提示文案 + +## G. HarborForge.Frontend — Calendar + +- [ ] FE-CAL-001：新增 Calendar 页面基础骨架（frontend only） + - [ ] 增加路由入口 + - [ ] 增加侧边栏入口 + - [ ] 增加基础页面布局 + +- [ ] FE-CAL-002：实现某日 slot 列表展示（frontend only） + - [ ] 展示时间轴或列表 + - [ ] 区分真实 slot 与 plan 虚拟 slot + - [ ] 展示状态 / 类型 / 时长 / 优先级 + +- [ ] FE-CAL-003：实现计划列表展示（frontend only） + - [ ] 展示计划规则 + - [ ] 展示周期参数 + - [ ] 支持跳转编辑 + +- [ ] FE-CAL-004：实现创建 / 编辑 / 取消日程交互（frontend only） + - [ ] 新建 slot 表单 + - [ ] 编辑 slot 表单 + - [ ] cancel 操作确认 + - [ ] 展示后端 warning + +- [ ] FE-CAL-005：实现 Deferred / Exhausted / overlap 等状态提示（frontend only） + - [ ] Deferred 提示 + - [ ] overlap 报错展示 + - [ ] workload warning 展示 + - [ ] Exhausted 状态展示 + +## H. HarborForge.Cli — Proposal / Essential / Story restricted + +- [ ] CLI-PR-001：统一 CLI 文案 `propose -> proposal`（cli only） + - [ ] 调整命令 help 文案 + - [ ] 调整输出文本 + - [ ] 评估命令名是否兼容保留 `hf propose` + +- [ ] CLI-PR-002：新增 Essential 相关命令（cli only） + - [ ] `hf proposal essential list` + - [ ] `hf proposal essential create` + - [ ] `hf proposal essential update` + - [ ] `hf proposal essential delete` + +- [ ] CLI-PR-003：更新 Proposal Accept CLI（cli only） + - [ ] Accept 时支持传入 milestone + - [ ] 展示批量生成的 task 结果 + - [ ] 更新帮助文案 + +- [ ] CLI-PR-004：限制 CLI 直接创建 `story/*`（cli only） + - [ ] 阻止 story 类型直建 + - [ ] 返回明确错误提示 + - [ ] 提示改走 Proposal Accept + +## I. HarborForge.Cli — Calendar + +- [ ] CLI-CAL-001：新增 `hf calendar` 命令组骨架（cli only） + - [ ] 注册命令组 + - [ ] 增加 help surface + - [ ] 增加 brief help + +- [ ] CLI-CAL-002：实现 `hf calendar schedule`（cli only） + - [ ] 参数解析 + - [ ] 请求构造 + - [ ] 结果输出 + +- [ ] CLI-CAL-003：实现 `hf calendar show`（cli only） + - [ ] 日期参数 + - [ ] 列表输出 + - [ ] JSON 输出 + +- [ ] CLI-CAL-004：实现 `hf calendar edit`（cli only） + - [ ] 支持 slot-id 与 date + - [ ] PATCH/POST 适配 + - [ ] 输出 warning / error + +- [ ] CLI-CAL-005：实现 `hf calendar cancel`（cli only） + - [ ] 支持 slot-id 与 date + - [ ] 输出结果 + +- [ ] CLI-CAL-006：实现 `hf calendar date-list`（cli only） + - [ ] 列出未来已物化日期 + - [ ] 适配 JSON 输出 + +- [ ] CLI-CAL-007：实现 `hf calendar plan-schedule`（cli only） + - [ ] 参数解析 `--at --on-day --on-week --on-month` + - [ ] 请求构造 + - [ ] 输出结果 + +- [ ] CLI-CAL-008：实现 `hf calendar plan-list`（cli only） + - [ ] 列表输出 + - [ ] JSON 输出 + +- [ ] CLI-CAL-009：实现 `hf calendar plan-edit`（cli only） + - [ ] 参数解析 + - [ ] 请求发送 + - [ ] 输出结果 + +- [ ] CLI-CAL-010：实现 `hf calendar plan-cancel`（cli only） + - [ ] 参数解析 + - [ ] 请求发送 + - [ ] 输出结果 + +## J. HarborForge.OpenclawPlugin / Monitor 联动 + +- [ ] PLG-CAL-001：插件侧定义 Calendar 心跳请求格式（plugin only） + - [ ] 明确 claw_identifier 传递方式 + - [ ] 明确 agent_id 传递方式 + - [ ] 明确返回 slot 列表结构 + +- [ ] PLG-CAL-002：插件侧处理待执行 slot 唤醒（plugin only） + - [ ] Idle 时唤醒 agent + - [ ] 透传任务上下文 + - [ ] 执行前更新 attended / started_at / status + +- [ ] PLG-CAL-003：插件侧处理非 Idle / Deferred 分支（plugin only） + - [ ] Agent 非 Idle 时上报 Deferred + - [ ] 处理多 slot 重排后的重新规划 + +- [ ] PLG-CAL-004：插件侧处理 ScheduledGatewayRestart（plugin only） + - [ ] 收到事件后持久化状态 + - [ ] 发送最终心跳 + - [ ] 暂停定时任务 + +## K. Tests / Integration（按子模块分别补，不混做） + +- [ ] TEST-BE-CAL-001：补 Calendar backend 测试（backend tests only） + - [ ] 模型测试 + - [ ] API 测试 + - [ ] overlap / warning / materialize 测试 + +- [ ] TEST-BE-PR-001：补 Proposal / Essential backend 测试（backend tests only） + - [ ] Essential CRUD + - [ ] Accept 生成 story tasks + - [ ] story restricted + +- [ ] TEST-FE-CAL-001：补 Calendar 前端测试（frontend tests only） + - [ ] 页面渲染 + - [ ] 表单交互 + - [ ] warning / error 展示 + +- [ ] TEST-FE-PR-001：补 Proposal / Essential 前端测试（frontend tests only） + - [ ] Essential 列表与表单 + - [ ] Accept milestone 选择 + - [ ] story 创建入口限制 + +- [ ] TEST-CLI-CAL-001：补 Calendar CLI 测试（cli tests only） + - [ ] 命令解析 + - [ ] JSON 输出 + - [ ] 错误输出 + +- [ ] TEST-CLI-PR-001：补 Proposal / Essential CLI 测试（cli tests only） + - [ ] Essential 子命令 + - [ ] accept milestone 参数 + - [ ] story 限制提示