# 蓝图更新规则

本文件定义了 `.blueprint/` 目录的维护规范，供 Claude 在对话中遵循。

## 目录结构

```
.blueprint/
├── manifest.yaml        ← 模块列表、关系、布局坐标
├── CONVENTIONS.md       ← 本文件（Claude 行为规则）
└── modules/
    └── <module-id>.md   ← 每个模块的详情 + 任务卡
```

## 何时更新蓝图

| 事件 | 操作 |
|------|------|
| 用户确认了新需求 | 在 manifest.yaml 新增模块，创建 modules/<id>.md |
| 完成了功能实现 | 更新模块 status → done，标记任务卡 ✅ |
| 拆分了大需求为子任务 | 在 modules/<id>.md 中添加任务卡 |
| 调整了架构方向 | 更新 edges 关系，可能调整 area |
| 放弃了某个方向 | 删除对应模块和文件，或标记 status: abandoned |

## 模块状态定义

| 状态 | 含义 | 色标 |
|------|------|------|
| `done` | 已实现并验证 | 🟢 绿色 |
| `in_progress` | 正在开发 | 🔵 蓝色 |
| `planned` | 已规划，需求明确 | 🟡 黄色 |
| `concept` | 构思中，信息不完整 | ⚪ 灰色 |

## 任务卡格式

modules/<id>.md 中的每个二级标题（`###`）是一张任务卡：

```markdown
### 📋 任务标题
- status: todo
- complexity: M
- files: src/path/to/file.tsx, src-tauri/src/commands/xxx.rs
- depends: other-module-id
- acceptance: 简要描述完成标准

详细说明（可选）。
```

### 状态前缀

| 前缀 | status | 含义 |
|------|--------|------|
| ✅ | done | 已完成 |
| 🔵 | in_progress | 进行中 |
| 📋 | todo | 可派发（信息充足） |
| 💭 | concept | 构思中 |

### 可派发标准（📋）

任务卡同时满足以下条件时标记为 📋：
1. status 为 `todo`
2. 有明确的 `files`（涉及哪些文件）
3. 有明确的 `acceptance`（验收标准）
4. complexity 为 `S` 或 `M`

不满足条件的 todo 任务保持无前缀，说明还需补充信息。

## manifest.yaml 规范

### 模块字段

```yaml
- id: kebab-case-id        # 唯一标识，同时是 modules/ 下的文件名
  name: 显示名称
  area: frontend            # 所属领域 ID
  status: done              # done / in_progress / planned / concept
  progress: 100             # 0~100，done 自动视为 100
  position: [x, y]          # React Flow 画布坐标（可选）
```

### 边字段

```yaml
- from: module-a
  to: module-b
  type: dependency          # dependency（实线）/ related（虚线）
```

### 领域字段

```yaml
- id: frontend
  name: 前端
  color: "#3B82F6"          # 节点边框/分组背景色
```

## 进度计算

模块的 progress 由其任务卡的完成比例推算：
- 无任务卡的模块：手动设置 progress
- 有任务卡的模块：`完成数 / 总数 × 100`（取整）

## 决策记录格式

模块文件中可添加 `## 决策记录` 段落，记录架构决策的 WHY：

```markdown
## 决策记录

- 选择阿里云 OSS 而非 GitHub Releases 作为更新源，因为国内用户访问 GitHub 不稳定
- 使用 document-driven 蓝图而非数据库存储，因为 Claude 天然支持文件读写且可版本控制
```

桌面 App 会以琥珀色卡片展示在模块详情面板中。

## 飞轮工作流

Claude 在每次对话中应遵循以下流程：

### 阶段 1：进入对话 — 读取蓝图
```
读取 .blueprint/manifest.yaml → 了解项目全景和当前状态
```
- 识别哪些模块 in_progress，哪些有可派发任务
- 用简短话语告诉用户当前项目进展（如 "18/22 模块已完成，2 个进行中"）

### 阶段 2：讨论需求 — 同步更新蓝图
| 用户说的 | Claude 应做的 |
|----------|--------------|
| "我想加个 XX 功能" | 确认需求后：manifest 加模块 (status: concept)，创建 modules/<id>.md |
| "XX 功能需要 A、B、C 三步" | 在模块文件中拆分为 3 张任务卡 |
| "这个方案确定了" | 模块 status → planned，补充任务卡的 files/acceptance |
| "开始做 XX" | 模块 status → in_progress |
| "为什么选这个方案" | 记录到模块的 `## 决策记录` |

### 阶段 3：实现功能 — 标记完成
```
完成代码 → 更新任务卡前缀为 ✅ → status: done
所有任务卡完成 → 模块 status: done
更新 manifest.yaml 的 updated 日期
```

### 阶段 4：回顾 — 用户在桌面 App 查看
用户打开蓝图可视化：
- 看到全景进度
- 在「下一步」面板查看可派发任务
- 点击「复制派发」→ 粘贴给新 Claude 会话

### 飞轮的反馈信号
Claude 应关注这些信号来决定是否更新蓝图：
- 用户说"这个做完了" → 标记 done
- 用户说"这个不做了" → 标记 abandoned 或删除
- 用户说"这个要拆一下" → 拆分任务卡
- 用户说"记住这个决策" → 写入决策记录
- 用户没提蓝图但在讨论功能 → 主动提议更新蓝图

## 注意事项

- 不要删除已完成的任务卡，它们是项目历史的一部分
- 模块 id 一旦确定尽量不要修改（会影响 edges 引用）
- 每次更新后修改 manifest.yaml 顶部的 `updated` 日期
- progress 由桌面 App 自动从任务卡完成比例计算，不需要手动维护
- 当用户的操作隐含了蓝图变更但没有明说时，Claude 应主动提议更新（而非沉默）