cc-devflow 1.0.1

package/.claude/docs/design/prd-version-management-design.md

@@ -0,0 +1,437 @@
+# PRD 版本管理系统设计
+
+> **设计目标**: 建立追踪 PRD 变更历史和影响分析的完整系统
+> **创建时间**: 2025-01-20
+> **版本**: v1.0
+
+## 📋 概述
+
+基于 spec-kit 的规格驱动理念，为 cc-devflow 建立完整的 PRD 版本管理体系，支持：
+- PRD 文档版本化 (v1.0, v1.1, v2.0...)
+- 变更影响分析报告
+- 规格变更触发的重新评估机制
+- 向后兼容性检查
+
+## 🎯 核心目标
+
+### 主要功能
+1. **自动版本化**: PRD 变更时自动创建新版本
+2. **变更追踪**: 详细记录每次变更的内容和原因
+3. **影响分析**: 分析变更对现有实现的影响
+4. **回滚支持**: 支持回滚到历史版本
+5. **兼容性检查**: 检查新版本与现有实现的兼容性
+
+### 设计原则
+- **增量式管理**: 支持语义化版本控制 (SemVer)
+- **变更透明**: 每次变更都有清晰的记录和说明
+- **影响预测**: 在变更前预测可能的影响范围
+- **自动化优先**: 减少手动维护工作
+
+## 🏗 架构设计
+
+### 文件结构
+```text
+devflow/requirements/${reqId}/
+├── PRD.md                           # 当前版本 PRD
+├── versions/                        # 版本历史
+│   ├── v1.0/
+│   │   ├── PRD.md                  # v1.0 版本快照
+│   │   ├── CHANGELOG.md            # v1.0 变更日志
+│   │   └── IMPACT_ANALYSIS.md      # 影响分析报告
+│   ├── v1.1/
+│   │   ├── PRD.md
+│   │   ├── CHANGELOG.md
+│   │   └── IMPACT_ANALYSIS.md
+│   └── v2.0/
+│       ├── PRD.md
+│       ├── CHANGELOG.md
+│       └── IMPACT_ANALYSIS.md
+├── VERSION_HISTORY.md               # 完整版本历史
+├── COMPATIBILITY_MATRIX.md          # 兼容性矩阵
+└── upgrade/                         # 升级工具和脚本
+    ├── migration_guide.md           # 迁移指南
+    └── compatibility_check.json     # 兼容性检查结果
+```
+
+### 版本控制策略
+
+#### 语义化版本控制
+```yaml
+版本格式: MAJOR.MINOR.PATCH
+
+MAJOR (主版本):
+  - 破坏性变更
+  - 核心用户故事删除或重大修改
+  - API 接口不兼容变更
+
+MINOR (次版本):
+  - 新增功能
+  - 新增用户故事
+  - 向后兼容的功能增强
+
+PATCH (修订版):
+  - Bug 修复
+  - 文档更新
+  - 澄清性修改
+```
+
+#### 自动版本检测算法
+```yaml
+变更分析:
+  user_story_changes:
+    - added_stories: count
+    - removed_stories: count
+    - modified_stories: count
+
+  acceptance_criteria_changes:
+    - breaking_changes: count
+    - new_requirements: count
+    - clarifications: count
+
+  non_functional_changes:
+    - performance_requirements: modified
+    - security_requirements: modified
+    - integration_requirements: modified
+
+版本判定:
+  if removed_stories > 0 OR breaking_changes > 0:
+    version_type: MAJOR
+  elif added_stories > 0 OR new_requirements > 0:
+    version_type: MINOR
+  else:
+    version_type: PATCH
+```
+
+## 🔧 实现方案
+
+### 1. 版本管理核心组件
+
+#### 版本检测器 (Version Detector)
+```yaml
+职责:
+  - 比较新旧 PRD 内容
+  - 识别变更类型和级别
+  - 自动确定版本号
+
+输入:
+  - 当前 PRD 内容
+  - 新的 PRD 内容
+  - 历史版本信息
+
+输出:
+  - 建议版本号
+  - 变更摘要
+  - 影响评估
+```
+
+#### 影响分析器 (Impact Analyzer)
+```yaml
+职责:
+  - 分析变更对现有实现的影响
+  - 识别需要更新的代码模块
+  - 评估测试覆盖影响
+
+分析维度:
+  - API 接口变更
+  - 数据模型变更
+  - 业务流程变更
+  - 非功能需求变更
+  - 依赖关系变更
+```
+
+#### 兼容性检查器 (Compatibility Checker)
+```yaml
+职责:
+  - 检查新版本与现有实现的兼容性
+  - 生成兼容性报告
+  - 提供迁移建议
+
+检查类型:
+  - 向后兼容性
+  - 向前兼容性
+  - 数据兼容性
+  - API 兼容性
+```
+
+### 2. 升级工作流
+
+#### /flow-upgrade 命令
+```bash
+# 分析当前 PRD 并建议版本升级
+/flow-upgrade "REQ-123" --analyze
+
+# 执行版本升级
+/flow-upgrade "REQ-123" --version="2.0" --reason="添加移动端支持"
+
+# 回滚到指定版本
+/flow-upgrade "REQ-123" --rollback="v1.2"
+```
+
+#### 升级流程
+```yaml
+Phase 1 - 变更分析:
+  1. 读取当前 PRD 和历史版本
+  2. 执行差异分析
+  3. 生成变更摘要
+  4. 建议版本号
+
+Phase 2 - 影响评估:
+  1. 分析代码库中相关实现
+  2. 识别需要更新的文件
+  3. 评估测试影响
+  4. 生成影响分析报告
+
+Phase 3 - 版本创建:
+  1. 创建新版本目录
+  2. 保存 PRD 快照
+  3. 生成变更日志
+  4. 更新版本历史
+
+Phase 4 - 后续处理:
+  1. 触发相关代码更新流程
+  2. 更新测试用例
+  3. 生成迁移指南
+  4. 通知相关团队
+```
+
+### 3. 变更追踪机制
+
+#### 变更日志格式
+```markdown
+# PRD 变更日志 - v2.1
+
+> **版本**: v2.1.0
+> **发布日期**: 2025-01-20T14:30:00Z
+> **变更类型**: MINOR
+
+## 🆕 新增功能
+- **US-007**: 移动端用户登录支持
+  - 添加触摸 ID 认证选项
+  - 支持设备记住登录状态
+
+## 🔄 功能变更
+- **US-003**: 用户注册流程优化
+  - 简化注册步骤从 5 步减至 3 步
+  - 移除中间确认页面
+
+## 🔧 技术需求变更
+- **性能要求**: 登录响应时间从 <2s 调整为 <1s
+- **安全要求**: 新增设备指纹验证
+
+## 📊 影响分析
+- **前端代码**: 需要更新登录组件 (3 个文件)
+- **后端 API**: 需要新增移动端认证接口
+- **测试用例**: 需要增加 12 个新测试用例
+- **预估工作量**: 8-12 工作小时
+
+## 🔗 相关链接
+- [完整影响分析报告](./IMPACT_ANALYSIS.md)
+- [兼容性检查结果](../upgrade/compatibility_check.json)
+- [迁移指南](../upgrade/migration_guide.md)
+```
+
+#### 自动变更检测
+```yaml
+监控机制:
+  - PRD 文件修改检测
+  - Git commit 钩子集成
+  - 定期一致性检查
+
+触发条件:
+  - PRD.md 文件内容变更
+  - 用户手动触发升级
+  - 依赖需求变更
+
+处理策略:
+  - 自动创建变更提案
+  - 等待用户确认
+  - 执行版本升级流程
+```
+
+## 🔍 影响分析框架
+
+### 分析维度
+
+#### 1. 功能影响分析
+```yaml
+用户故事变更:
+  - 新增: 需要新的代码实现
+  - 修改: 需要更新现有代码
+  - 删除: 需要清理相关代码
+
+验收标准变更:
+  - 性能指标变化
+  - 安全要求调整
+  - 集成接口修改
+```
+
+#### 2. 技术影响分析
+```yaml
+代码影响:
+  - 前端组件 (React/Vue 组件)
+  - 后端服务 (API 接口)
+  - 数据库模式 (表结构/索引)
+  - 配置文件 (环境配置)
+
+测试影响:
+  - 单元测试更新
+  - 集成测试调整
+  - E2E 测试修改
+  - 性能测试更新
+```
+
+#### 3. 运维影响分析
+```yaml
+部署影响:
+  - 数据库迁移脚本
+  - 配置更新需求
+  - 服务重启要求
+  - 监控指标调整
+
+运行时影响:
+  - 性能指标变化
+  - 资源使用调整
+  - 监控告警更新
+  - 备份策略修改
+```
+
+### 影响评估算法
+```yaml
+影响权重计算:
+  breaking_changes_weight: 0.4
+  new_features_weight: 0.3
+  performance_changes_weight: 0.2
+  documentation_changes_weight: 0.1
+
+影响级别:
+  HIGH (>0.7): 需要项目经理审批
+  MEDIUM (0.3-0.7): 需要技术负责人审批
+  LOW (<0.3): 可以直接执行
+
+工作量估算:
+  基于历史数据和变更复杂度
+  考虑团队技能和项目熟悉度
+  包含测试和文档更新时间
+```
+
+## 📊 兼容性检查
+
+### 检查类型
+
+#### 1. API 兼容性
+```yaml
+向后兼容性:
+  - 接口签名未变更
+  - 响应格式保持一致
+  - 错误码保持稳定
+
+数据兼容性:
+  - 数据库模式兼容
+  - 数据迁移路径清晰
+  - 历史数据可访问
+```
+
+#### 2. 功能兼容性
+```yaml
+用户体验:
+  - 核心用户流程保持
+  - 界面交互一致性
+  - 性能不显著下降
+
+集成兼容性:
+  - 第三方集成稳定
+  - 内部服务接口兼容
+  - 消息格式保持
+```
+
+### 兼容性矩阵
+```yaml
+兼容性级别:
+  FULLY_COMPATIBLE: 完全兼容，无需任何变更
+  BACKWARD_COMPATIBLE: 向后兼容，旧版本客户端可正常工作
+  MIGRATION_REQUIRED: 需要迁移，提供自动迁移工具
+  BREAKING_CHANGE: 破坏性变更，需要手动处理
+
+检查结果格式:
+  version_from: v1.2
+  version_to: v2.0
+  compatibility_level: MIGRATION_REQUIRED
+  affected_components: [frontend, api, database]
+  migration_tools: [schema_migration, api_adapter]
+  estimated_effort: 16_hours
+```
+
+## 🔄 自动化集成
+
+### Git 钩子集成
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+# 检查 PRD 变更并自动创建版本
+
+if [[ $(git diff --cached --name-only) == *"PRD.md"* ]]; then
+    echo "检测到 PRD 变更，执行版本分析..."
+    /flow-upgrade $(extract_req_id) --analyze --auto
+fi
+```
+
+### CI/CD 集成
+```yaml
+# .github/workflows/prd-version-check.yml
+name: PRD Version Management
+on:
+  pull_request:
+    paths: ['devflow/requirements/**/PRD.md']
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Analyze PRD Changes
+        run: |
+          /flow-upgrade ${{ env.REQ_ID }} --analyze --format=json > impact.json
+
+      - name: Comment PR with Impact Analysis
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const impact = require('./impact.json');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: generateImpactComment(impact)
+            });
+```
+
+## 🎯 验收标准
+
+### 功能验收
+- [x] PRD 变更能够自动版本化
+- [x] 变更影响分析准确度 > 85%
+- [x] 支持回滚到历史版本
+- [x] 兼容性检查覆盖主要风险点
+- [x] 版本升级流程文档完整
+
+### 技术验收
+- [x] 版本管理不影响现有工作流性能
+- [x] 支持并发安全的版本操作
+- [x] 历史版本存储优化，避免空间浪费
+- [x] 与现有 git 工作流良好集成
+
+### 用户体验验收
+- [x] 版本升级过程对用户透明
+- [x] 提供清晰的变更摘要和影响说明
+- [x] 支持一键回滚操作
+- [x] 错误提示信息清晰易懂
+
+## 📚 相关文档
+
+- [/flow-upgrade 命令文档](./../commands/flow-upgrade.md)
+- [版本管理最佳实践](./../docs/best-practices/version-management.md)
+- [影响分析算法详解](./../docs/algorithms/impact-analysis.md)
+- [兼容性检查指南](./../docs/guides/compatibility-checking.md)
+
+---
+
+**核心价值**: PRD 版本管理系统为 cc-devflow 提供了规格演进的完整支持，确保需求变更的可追踪性和影响可控性，这是实现真正的 Specification-Driven Development 的关键基础设施。

package/.claude/docs/guides/INIT_TROUBLESHOOTING.md

@@ -0,0 +1,117 @@
+# Flow-Init Troubleshooting Guide
+
+> Quick reference for `/flow-init` errors and recovery
+
+---
+
+## Core Errors
+
+### E1: Invalid REQ_ID Format
+```bash
+❌ ERROR: REQ_ID format invalid
+```
+**Fix**: 使用格式 `REQ-123` 或 `BUG-456`（`^(REQ|BUG)-[0-9]+$`）
+
+---
+
+### E2: REQ_ID Already Exists
+```bash
+❌ ERROR: devflow/requirements/REQ-123/ already exists
+```
+**Fix**: 使用不同 ID 或 `/flow-init "REQ-123|..." --force` 强制覆盖
+
+---
+
+### E3: Git Status Not Clean
+```bash
+❌ ERROR: Git working directory has uncommitted changes
+```
+**Fix**: `git status` → `git commit` 或 `git stash`
+
+---
+
+### E4: Research Validation Failed
+```bash
+❌ ERROR: research.md validation failed (incomplete)
+```
+**Diagnose**: `grep -c "Decision:" devflow/requirements/REQ-123/research/research.md`
+**Fix**: 手动补充 research.md Decision blocks 或重新运行 research 步骤
+
+---
+
+### E5: MCP Fetch Failed
+```bash
+⚠️ WARNING: MCP fetch timed out (Context7)
+```
+**Fix**: 继续执行但标记 `research/mcp/` 下的待补项，稍后手动补充
+
+---
+
+## Recovery Procedures
+
+### Complete Restart
+```bash
+rm -rf devflow/requirements/REQ-123/
+git branch -D feature/REQ-123-*
+/flow-init "REQ-123|Title|URLs"
+```
+
+### Recover from Interruption
+```bash
+# 检查当前状态
+cat devflow/requirements/REQ-123/orchestration_status.json | jq '.phase0_complete'
+
+# 如果 false，补充研究材料
+# 手动编辑 research/research.md → 添加 Decision blocks
+
+# 更新状态
+jq '.phase0_complete = true' devflow/requirements/REQ-123/orchestration_status.json > tmp.json
+mv tmp.json devflow/requirements/REQ-123/orchestration_status.json
+
+# 继续下一阶段
+/flow-prd "REQ-123"
+```
+
+### Rebuild Research.md from Tasks.json
+```bash
+REQ_DIR="devflow/requirements/REQ-123"
+
+# 从 tasks.json 生成 research.md
+bash .claude/scripts/consolidate-research.sh "$REQ_DIR"
+
+# 验证
+bash .claude/scripts/validate-research.sh "$REQ_DIR"
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `SKIP_MCP_RESEARCH` | `false` | 跳过外部 MCP 材料抓取 |
+| `REQUIRE_CLEAN_GIT` | `true` | 要求 Git 状态干净 |
+
+### Command-Line Flags
+```bash
+/flow-init "REQ-123|..." --force        # 强制覆盖现有需求
+/flow-init --interactive                # 交互式输入模式
+```
+
+---
+
+## FAQ
+
+**Q: 如何跳过 MCP 研究阶段？**
+A: `SKIP_MCP_RESEARCH=1 /flow-init "REQ-123|..."`
+
+**Q: Context Loading 阶段找不到 ROADMAP.md 怎么办？**
+A: 可选步骤，不影响执行。如需路线图，先运行 `/core-roadmap`
+
+**Q: Research.md 格式要求？**
+A: 至少包含 1 个 `### Decision:` block，每个 block 有 Rationale/Alternatives/Source
+
+---
+
+**Last Updated**: 2025-12-19

package/.claude/docs/guides/NEW_TROUBLESHOOTING.md

@@ -0,0 +1,151 @@
+# Flow-New Troubleshooting Guide
+
+> Quick reference for `/flow-new` errors and recovery
+
+---
+
+## Core Errors
+
+### E1: Stage Command Not Found
+```bash
+❌ ERROR: Command /flow-init not found
+```
+**Fix**: `ls .claude/commands/flow-*.md` → 检查缺失文件 → `git checkout HEAD -- .claude/commands/`
+
+---
+
+### E2: Status File Corrupted
+```bash
+❌ ERROR: Invalid orchestration_status.json
+```
+**Diagnose**: `jq . devflow/requirements/REQ-123/orchestration_status.json`
+**Fix**: 从模板重建或 `/flow-restart "REQ-123"`
+
+---
+
+### E3: Interrupted, Cannot Resume
+```bash
+❌ ERROR: Requirement REQ-123 already exists
+```
+**Diagnose**: `/flow-status REQ-123`
+**Fix**: `/flow-restart "REQ-123"` 或手动从特定阶段继续
+
+---
+
+### E4: UI Detection False Positive
+```bash
+✅ UI原型生成完成 (但项目是纯后端)
+```
+**Fix**: 在 PRD.md 开头添加 `## 项目类型声明\n**纯后端 API 项目**，无 UI 需求。`
+
+---
+
+### E5: Epic 未覆盖所有技术层
+```bash
+⚠️ WARNING: TASKS.md 未覆盖 TECH_DESIGN.md 所有层
+```
+**Diagnose**: `grep "## Section" devflow/requirements/REQ-123/TECH_DESIGN.md`
+**Fix**: 手动补充缺失任务或重新生成 `/flow-epic "REQ-123"`
+
+---
+
+### E6: QA Gate Failure
+```bash
+❌ 代码覆盖率: 65% (要求 ≥ 80%)
+❌ 安全问题: 2 个高危漏洞
+```
+**Fix**:
+- 补充测试: `npm test -- --coverage --verbose` → 识别未覆盖模块
+- 修复漏洞: 查看 `SECURITY_REPORT.md` → 修复代码 → 重新运行 `/flow-qa "REQ-123" --full`
+
+---
+
+### E7: Build Failure
+```bash
+❌ error TS2345: Argument of type 'string | undefined'...
+```
+**Fix**: `npm run typecheck` → 修复类型错误 → `npm run build`
+
+---
+
+### E8: PR Creation Failed
+```bash
+❌ gh pr create: HTTP 403: Resource not accessible
+```
+**Fix**: `gh auth login` → 重新认证 → `/flow-release "REQ-123"`
+
+---
+
+## Recovery Procedures
+
+### Complete Restart
+```bash
+rm -rf devflow/requirements/REQ-123/
+git branch -D feature/REQ-123-*
+/flow-new "REQ-123|Title|URLs"
+```
+
+### Partial Resume (从特定任务继续)
+```bash
+# 检查最后完成的任务
+ls devflow/requirements/REQ-123/tasks/*.completed | tail -1
+
+# 从下一任务继续
+/flow-dev "REQ-123" --resume --from=TASK_008
+```
+
+### State File Rebuild
+```bash
+REQ_DIR="devflow/requirements/REQ-123"
+HAS_PRD=$([ -f "$REQ_DIR/PRD.md" ] && echo true || echo false)
+HAS_TECH=$([ -f "$REQ_DIR/TECH_DESIGN.md" ] && echo true || echo false)
+
+# 重建状态文件
+cat > $REQ_DIR/orchestration_status.json <<EOF
+{
+  "reqId": "REQ-123",
+  "status": "$( [ "$HAS_TECH" = "true" ] && echo "tech_complete" || echo "prd_complete" )",
+  "prd_complete": $HAS_PRD,
+  "tech_design_complete": $HAS_TECH,
+  "epic_complete": false,
+  "dev_complete": false
+}
+EOF
+
+jq . $REQ_DIR/orchestration_status.json  # 验证
+/flow-restart "REQ-123"
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `SKIP_UI_DETECTION` | `false` | 强制跳过 UI 生成 |
+| `COVERAGE_THRESHOLD` | `80` | 代码覆盖率要求 |
+| `FLOW_DEBUG` | `false` | 启用调试日志 |
+
+### Command-Line Flags
+```bash
+/flow-new "REQ-123|..." --skip-ui         # 跳过 UI
+/flow-new "REQ-123|..." --resume          # 恢复执行
+```
+
+---
+
+## FAQ
+
+**Q: 可以在 flow-new 执行中暂停吗？**
+A: Ctrl+C 中断 → `/flow-status REQ-123` 查看状态 → `/flow-restart "REQ-123"` 恢复
+
+**Q: 如何从特定阶段重新开始？**
+A: 使用对应阶段命令重新执行，如 `/flow-prd "REQ-123"` 或 `/flow-epic "REQ-123"`
+
+**Q: flow-new 支持 BUG 修复吗？**
+A: 不支持，BUG 使用 `/flow-fix "BUG-456|描述"`
+
+---
+
+**Last Updated**: 2025-12-19