✨ feat: 创建proj docs

.aide/project-docs/blocks/aide-program-flow.md

@@ -0,0 +1,101 @@
+# aide-program-flow
+
+> 路径：aide-program/aide/flow/
+> 最后更新：2025-12-15
+
+## 概述
+
+进度追踪模块，提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。
+
+## 文件清单
+
+| 文件 | 说明 |
+|------|------|
+| `__init__.py` | 模块初始化 |
+| `tracker.py` | FlowTracker 主逻辑（~200 行） |
+| `storage.py` | 状态文件读写（~147 行） |
+| `types.py` | 数据结构定义（~103 行） |
+| `validator.py` | 环节校验器（~50 行） |
+| `git.py` | Git 集成（~75 行） |
+| `hooks.py` | pre/post commit 钩子（~125 行） |
+| `errors.py` | 自定义异常 |
+| `utils.py` | 工具函数 |
+
+## 核心组件
+
+### FlowTracker
+
+- **职责**：编排一次 flow 动作（校验 → hooks → git → 落盘 → 输出）
+- **位置**：`tracker.py:20`
+- **关键方法**：
+  - `start(phase, summary)` - 开始新任务
+  - `next_step(summary)` - 记录步骤前进
+  - `back_step(reason)` - 记录步骤回退
+  - `next_part(phase, summary)` - 进入下一环节
+  - `back_part(phase, reason)` - 回退到之前环节
+  - `issue(description)` - 记录一般问题
+  - `error(description)` - 记录严重错误
+
+### FlowStorage
+
+- **职责**：状态文件的读写、锁定和归档
+- **位置**：`storage.py:16`
+- **关键方法**：
+  - `lock()` - 上下文管理器，获取文件锁
+  - `load_status()` - 加载当前任务状态
+  - `save_status(status)` - 保存状态（原子写入）
+  - `archive_existing_status()` - 归档旧状态到 logs/
+  - `list_all_tasks()` - 列出所有任务
+  - `load_task_by_id(task_id)` - 按 ID 加载任务
+
+### FlowValidator
+
+- **职责**：校验环节跳转合法性
+- **位置**：`validator.py`
+- **校验规则**：
+  - `next_part`: 只能跳转到相邻的下一环节
+  - `back_part`: 可以回退到任意之前的环节
+  - `start`: 必须从有效环节开始
+
+### 数据结构
+
+- `FlowStatus` - 任务状态（task_id, current_phase, current_step, history）
+- `HistoryEntry` - 历史条目（timestamp, action, phase, step, summary, git_commit）
+
+## 接口说明
+
+```python
+# CLI 入口
+aide flow start <phase> "<summary>"    # 开始任务
+aide flow next-step "<summary>"        # 步骤前进
+aide flow back-step "<reason>"         # 步骤回退
+aide flow next-part <phase> "<summary>" # 进入下一环节
+aide flow back-part <phase> "<reason>"  # 回退环节
+aide flow issue "<description>"         # 记录问题
+aide flow error "<description>"         # 记录错误
+aide flow status                        # 查看当前状态
+aide flow list                          # 列出所有任务
+aide flow show <task_id>                # 查看任务详情
+```
+
+## Git 集成
+
+每次 flow 操作自动执行：
+1. `git add .`
+2. `git commit -m "[aide] <phase>: <summary>"`
+
+提交信息格式：
+- 正常操作：`[aide] impl: 完成数据库模型设计`
+- 问题记录：`[aide] impl issue: 测试覆盖率低`
+- 错误记录：`[aide] impl error: 数据库连接失败`
+
+## 依赖关系
+
+- 依赖：core（output, config）
+- 被依赖：main.py
+
+## 注意事项
+
+- 状态文件使用文件锁防止并发写入
+- 归档文件保存在 `.aide/logs/` 目录
+- Hooks 支持 PlantUML 自动校验和构建