✨ feat: 完成aide flow设计

aide-program/docs/commands/flow/state-and-storage.md

@@ -0,0 +1,125 @@
+# 状态模型与存储设计
+
+## 一、状态文件（源规范）
+
+状态文件的数据结构以 `aide-program/docs/formats/data.md` 的“流程状态格式”为准：
+
+- 位置：`.aide/flow-status.json`
+- 顶层结构：`FlowStatus`
+- 历史条目：`HistoryEntry`
+
+本文档补充**字段语义**与**落盘/并发/容错**约定。
+
+## 二、字段语义（实现必须遵守）
+
+### 2.1 task_id
+
+- 生成时机：`aide flow start` 调用时生成
+- 语义：标识一次“任务”的全生命周期（覆盖 prep + exec）
+- 格式：与 `aide-program/docs/formats/data.md` 的时间戳约定一致
+
+### 2.2 current_phase
+
+- 语义：当前所处环节名称
+- 取值：必须在 `flow.phases` 中
+- 变更来源：`start`、`next-part`、`back-part`
+
+### 2.3 current_step
+
+为避免历史回溯混乱，建议将 `current_step` 定义为**单调递增的记录序号**：
+
+- `start` 产生第一条记录，`current_step = 1`
+- 每次成功记录一次动作（start/next-step/back-step/next-part/back-part/issue/error），`current_step += 1`
+- 不做递减（回退动作使用 action=back-step/back-part 表达）
+
+> 如果团队坚持“回退需要 step-1”，需先在全体文档中统一，并评估历史序号重复/倒序对调试的影响。
+
+### 2.4 history
+
+每次 flow 调用都会追加一个 HistoryEntry：
+
+- `timestamp`：本次记录时间（ISO 8601）
+- `action`：动作类型（与 data.md 枚举一致）
+- `phase`：本次动作完成后的 current_phase
+- `step`：本次动作完成后的 current_step
+- `summary`：摘要/原因/描述
+- `git_commit`：若本次产生了 commit，则为 commit hash，否则为空
+
+约束（建议实现中校验）：
+
+- `history[-1].phase == current_phase`
+- `history[-1].step == current_step`
+- `history` 按追加顺序即时间顺序
+
+## 三、存储生命周期
+
+### 3.1 start 行为（归档旧状态）
+
+当执行 `aide flow start` 时：
+
+- 若 `.aide/flow-status.json` 不存在：直接创建新状态
+- 若已存在：应先归档旧文件，避免无提示覆盖导致历史丢失
+
+推荐归档位置（本地数据，不纳入 git）：
+
+- `.aide/logs/flow-status.<old_task_id>.json`
+
+### 3.2 其它动作行为
+
+除 `start` 外的命令要求：
+
+- 状态文件必须存在，否则返回错误并建议先运行 `aide flow start ...` 或执行 `/aide:prep`
+
+## 四、并发与原子性（落盘必须可靠）
+
+### 4.1 互斥（锁）
+
+为避免并发调用导致状态文件损坏，`aide flow` 在读写前必须获得独占锁。
+
+推荐方案（跨平台、实现简单）：
+
+- 锁文件：`.aide/flow-status.lock`
+- 加锁：以“创建新文件（独占）”方式获取
+- 释放：删除锁文件
+
+约定：
+
+- 获取锁失败时：短暂重试（例如总计 2~3 秒），仍失败则返回错误 `✗ 状态文件被占用`
+- 异常退出时：应尽力清理锁（并允许人工删除）
+
+### 4.2 原子写入
+
+必须避免写一半导致 JSON 损坏：
+
+1. 写入临时文件：`.aide/flow-status.json.tmp`
+2. fsync（如实现选择支持）
+3. 原子替换为目标文件：`.aide/flow-status.json`
+
+### 4.3 编码与换行
+
+- UTF-8 编码
+- 换行统一 `\n`
+- JSON 建议使用稳定排序/缩进策略（便于人工阅读与 diff），但不要依赖其格式做解析
+
+## 五、容错与恢复策略
+
+### 5.1 JSON 解析失败
+
+当状态文件存在但无法解析：
+
+- 输出错误并提示用户手动处理（例如备份后删除该文件，再重新 start）
+- 不建议在未确认的情况下自动“修复”或丢弃字段
+
+### 5.2 目录缺失
+
+若 `.aide/` 不存在：
+
+- 返回错误并提示先执行 `aide init`
+
+## 六、与 Git 的关系（重要）
+
+`.aide/` 默认在仓库 `.gitignore` 内：
+
+- 状态文件用于本地追踪，不要求进入提交
+- Git 提交用于记录真实产出（代码/文档等）
+- 若团队希望将状态文件纳入版本库，应显式调整 `.gitignore`，并在 Git 策略上达成一致