cc-devflow 4.3.0 → 4.4.1

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

@@ -1,437 +0,0 @@
-# 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/examples/design-inspiration-pool.md

@@ -1,59 +0,0 @@
-# Design Inspiration Pool
-
-> 80+ 位艺术家/设计师/建筑师灵感来源池
-> 用于 UI_PROTOTYPE_TEMPLATE.md Phase 2: Design Inspiration Sampling
-
----
-
-## 使用方法
-
-从不同类别中随机采样 2 位大师，生成风格转译说明。
-
-**采样策略**:
-- 从不同类别中选择（避免风格过于相似）
-- 优先组合：现代主义 + 生成艺术，建筑 + 平面设计
-- 避免组合：同类别内的大师（如两位都是建筑师）
-
-**转译模板**:
-```
-**灵感来源X**: {艺术家姓名} ({类别})
-**核心特质**: {艺术家代表性特点,1-2句话}
-**网页转译**:
-  - 色彩: {具体色值} → {应用场景}
-  - 版式: {布局策略} → {CSS实现方式}
-  - 形态: {视觉元素} → {HTML/CSS实现}
-  - 动效: {动态特征} → {CSS/JS实现}
-**禁止模仿**: 不复刻{具体作品名称}的{具体元素}
-```
-
----
-
-## 灵感来源池 (8 类别, 80+ 位大师)
-
-### 类别1: 影视片头 / 动态叙事
-Saul Bass, Maurice Binder, Pablo Ferro, Dan Perri, Kyle Cooper
-
-### 类别2: 平面 / 字体 / 后现代图形
-Paula Scher, Neville Brody, April Greiman, David Carson, Jamie Reid, Push Pin Studios (Seymour Chwast)
-
-### 类别3: 现代主义信息设计 / 网格系统
-Massimo Vignelli, Josef Müller-Brockmann, Otl Aicher, Armin Hofmann, Karl Gerstner, Muriel Cooper
-
-### 类别4: 几何与抽象艺术 / 光学艺术
-Piet Mondrian, Sonia Delaunay, Josef Albers, Victor Vasarely, Bridget Riley, M. C. Escher, Paul Klee, Kazimir Malevich, Joan Miró, Henri Matisse, Mark Rothko, René Magritte, Salvador Dalí
-
-### 类别5: 亚洲与当代艺术
-Yayoi Kusama, Takashi Murakami, Katsushika Hokusai(葛饰北斋), Xu Bing(徐冰), Zao Wou-Ki(赵无极)
-
-### 类别6: 建筑 / 空间设计
-Zaha Hadid, Frank Gehry, Le Corbusier, Mies van der Rohe, Tadao Ando(安藤忠雄), Oscar Niemeyer, Santiago Calatrava, Norman Foster, Rem Koolhaas
-
-### 类别7: 生成艺术 / 算法设计 / 数据可视化
-Casey Reas, Ben Fry (Processing), Joshua Davis, Jared Tarbell, Robert Hodgin, Jer Thorp, Nadieh Bremer, Shirley Wu, Stefanie Posavec, Giorgia Lupi
-
-### 类别8: 工业设计 / 产品设计
-Dieter Rams, Charles & Ray Eames, Naoto Fukasawa(深泽直人), Jasper Morrison, Marc Newson, Philippe Starck, Karim Rashid, Jonathan Ive
-
----
-
-**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/examples/ui-prototype-constitution-checklist.md

@@ -1,75 +0,0 @@
-# UI Prototype Constitution Checklist
-
-> UI 原型宪法合规检查清单
-> 用于 UI_PROTOTYPE_TEMPLATE.md Phase 10: Constitution & Quality Check
-
----
-
-## Constitution 检查
-
-### Article I - Quality First (质量至上)
-- [ ] I.1 Complete Implementation: HTML 无占位符，所有页面完整
-- [ ] I.2 No Simplification: 交互逻辑完整，非简化版本
-- [ ] I.4 Quality Gates: 通过 HTML 验证，无 console 错误
-
-### Article III - Security First (安全优先)
-- [ ] III.1 No Hardcoded Secrets: 无 API 密钥硬编码
-- [ ] III.2 Input Validation: 表单有验证逻辑
-- [ ] III.4 Secure by Default: 使用 HTTPS CDN 资源
-
-### Article V - Maintainability (可维护性)
-- [ ] V.3 Documentation: HTML 注释包含设计文档
-- [ ] V.4 File Size Limits: 单文件 HTML ≤ 2000 行（可接受）
-
-### Article X - Requirement Boundary (需求边界)
-- [ ] X.1 No Speculation: 仅实现 PRD 明确的功能
-- [ ] X.2 No Speculative Features: 无"未来可能需要"的功能
-
----
-
-## 质量检查清单
-
-### HTML 质量
-- [ ] 使用 HTML5 语义化标签
-- [ ] 无未闭合标签
-- [ ] ARIA 标签完整
-- [ ] 无重复 ID
-
-### CSS 质量
-- [ ] 使用 CSS 变量（Design System）
-- [ ] 响应式媒体查询正常
-- [ ] 无 !important 滥用
-- [ ] 命名规范（BEM 或一致的命名）
-
-### JavaScript 质量
-- [ ] 无全局变量污染
-- [ ] 事件监听器正确绑定
-- [ ] 无内存泄漏（事件监听器移除）
-- [ ] Console 无错误
-
-### 可访问性
-- [ ] 色彩对比度 ≥ 4.5:1
-- [ ] 键盘导航可用
-- [ ] 屏幕阅读器友好
-- [ ] focus 状态可见
-
-### 性能
-- [ ] CDN 资源加载 <1s
-- [ ] 首屏渲染 <2s
-- [ ] 交互响应 <100ms
-- [ ] 无不必要的重绘/回流
-
----
-
-## Anti-Generic-Design 验证
-- [ ] 无占位图片（Picsum 图片正常加载）
-- [ ] 无常见 AI 紫/蓝配色
-- [ ] 无 Emoji 图标（使用 SVG/图标库）
-- [ ] 无 Lorem Ipsum 文本
-- [ ] 所有交互元素有完整状态（hover/active/disabled/error）
-
----
-
-**完整 Constitution 文档**: `.claude/rules/project-constitution.md`
-
-**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

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

@@ -1,117 +0,0 @@
-# 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:spec "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