DOC-001: 整理本波开发范围说明

- 明确 Calendar 为独立功能线,Proposal/Essential 为项目结构调整线
- 明确两条线交叉点仅限 event_data / Agent 调度引用层
- 区分必须本波完成 vs 仅设计保留内容
- 新增 docs/wave-2026-03-scope.md
This commit is contained in:
zhi
2026-03-29 14:01:10 +00:00
parent d7029a1cc7
commit d6ed523731
2 changed files with 193 additions and 87 deletions

View File

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