# 本波开发范围说明

> 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 用户密码；前端隐藏修改密码入口