zhi
d6ed523731
- 明确 Calendar 为独立功能线，Proposal/Essential 为项目结构调整线 - 明确两条线交叉点仅限 event_data / Agent 调度引用层 - 区分必须本波完成 vs 仅设计保留内容 - 新增 docs/wave-2026-03-scope.md
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# 本波开发范围说明
|
||
|
||
> Date: 2026-03-29
|
||
> Wave: 2026-03 (Calendar & Proposal 重构)
|
||
|
||
---
|
||
|
||
## 一、两条功能线概述
|
||
|
||
本波开发包含两条独立的功能线：
|
||
|
||
### 功能线 1：Calendar 日程系统（独立功能线）
|
||
|
||
全新功能模块，为 HarborForge 增加日程调度能力。
|
||
|
||
**包含内容：**
|
||
- `TimeSlot` 日程槽模型与 CRUD API
|
||
- `SchedulePlan` 周期性计划模型与管理 API
|
||
- Agent 状态管理（Idle / Busy / OnCall / Exhausted / Offline）
|
||
- `MinimumWorkload` 最小工作量配置
|
||
- Plan 虚拟 slot 标识与物化策略
|
||
- Overlap 校验与 Workload warning 规则
|
||
- 不可变过去 slot 规则
|
||
- Agent 心跳唤醒机制与 Exhausted 恢复
|
||
- 前端 Calendar 页面
|
||
- CLI `hf calendar` 命令组
|
||
- OpenClaw 插件 Calendar 心跳联动
|
||
|
||
### 功能线 2：Proposal / Essential / Story restricted（项目结构调整线）
|
||
|
||
对已有的 Propose 流程进行重构和增强。
|
||
|
||
**包含内容：**
|
||
- `Propose` → `Proposal` 统一重命名
|
||
- 新增 `Essential` 概念及数据模型
|
||
- `EssentialCode` 编码规则
|
||
- Proposal Accept 语义变更：遍历 Essential 批量生成 story task
|
||
- `story/*` 整个大类设为 restricted，仅允许通过 Proposal Accept 创建
|
||
- 清理旧 `feat_task_id` 语义
|
||
- 前端 Proposal 详情页 Essential 管理
|
||
- CLI Proposal Essential 子命令
|
||
|
||
---
|
||
|
||
## 二、两条线的交叉点
|
||
|
||
两条功能线设计上相互独立，交叉点仅限于以下层面：
|
||
|
||
| 交叉点 | 说明 |
|
||
|--------|------|
|
||
| `event_data` | Calendar 的 TimeSlot 通过 `event_data` JSON 字段引用 Task/Essential code，但不直接依赖 Proposal/Essential 的数据模型 |
|
||
| Agent 调度引用层 | Calendar 心跳唤醒 Agent 执行任务时，任务可能是 story task（由 Proposal Accept 生成），但 Calendar 只关心 task code，不关心其来源 |
|
||
|
||
**关键原则：**
|
||
- Calendar 不直接 FK 到 Essential 或 Proposal 表
|
||
- Proposal/Essential 不直接 FK 到 TimeSlot 或 SchedulePlan 表
|
||
- 两者通过 code 引用（字符串）松耦合
|
||
- 可以独立开发、独立测试、独立部署
|
||
|
||
---
|
||
|
||
## 三、本波必须完成 vs 仅设计保留
|
||
|
||
### ✅ 必须本波完成
|
||
|
||
#### Calendar 线
|
||
|
||
| 范围 | 任务 ID 区间 | 说明 |
|
||
|------|-------------|------|
|
||
| 后端基础模型 | BE-CAL-001 ~ BE-CAL-008 | TimeSlot、SchedulePlan、Agent 扩展、MinimumWorkload、物化策略、overlap/warning/不可变规则 |
|
||
| 后端 API | BE-CAL-API-001 ~ BE-CAL-API-007 | 日程 CRUD、计划 CRUD、date-list |
|
||
| 后端 Agent 协作 | BE-AGT-001 ~ BE-AGT-004 | 心跳查询、状态流转、多 slot 竞争、Exhausted 恢复 |
|
||
| 前端 | FE-CAL-001 ~ FE-CAL-005 | 页面骨架、slot 列表、计划列表、CRUD 交互、状态提示 |
|
||
| CLI | CLI-CAL-001 ~ CLI-CAL-010 | `hf calendar` 全部子命令 |
|
||
| 插件 | PLG-CAL-001 ~ PLG-CAL-004 | 心跳格式、唤醒处理、Deferred 分支、ScheduledGatewayRestart |
|
||
|
||
#### Proposal 线
|
||
|
||
| 范围 | 任务 ID 区间 | 说明 |
|
||
|------|-------------|------|
|
||
| 后端 | BE-PR-001 ~ BE-PR-011 | 重命名、Essential 模型/schema/API、Accept 重构、story restricted、测试 |
|
||
| 前端 | FE-PR-001 ~ FE-PR-005 | 重命名、Essential 列表/表单、Accept milestone 选择、story 限制 |
|
||
| CLI | CLI-PR-001 ~ CLI-PR-004 | 重命名、Essential 命令、Accept 更新、story 限制 |
|
||
|
||
#### 文档与测试
|
||
|
||
| 范围 | 任务 ID 区间 | 说明 |
|
||
|------|-------------|------|
|
||
| 文档 | DOC-001 ~ DOC-003 | 范围说明、迁移说明、验收清单 |
|
||
| 测试 | TEST-* | 各子模块测试补充 |
|
||
|
||
### 📐 仅设计保留（不在本波实现）
|
||
|
||
| 内容 | 说明 |
|
||
|------|------|
|
||
| Entertainment 事件子类型 | `event_data` 中 Entertainment 的具体结构待设计 |
|
||
| 用户级时区支持 | 本波统一使用服务器时区 |
|
||
| 前端日程表详细 UI 设计 | 本波实现基础功能骨架，精细 UI 留后续迭代 |
|
||
| Agent 唤醒的提示词模板 | 本波实现唤醒机制，提示词模板留后续打磨 |
|
||
| Proposal/Essential 数据迁移工具 | 旧数据兼容读取即可，自动化迁移工具留后续 |
|
||
|
||
---
|
||
|
||
## 四、Bug Fix（附带修复）
|
||
|
||
- **acc-mgr 密码修改限制**：后端禁止修改 acc-mgr 用户密码；前端隐藏修改密码入口
|