bobo-ai-cli 3.0.4 → 3.0.5

package/knowledge/rules/engineering-workflows.md

@@ -1,225 +1,225 @@
----
-id: "engineering-workflows"
-title: "工程化工作流规则"
-category: "domain"
-tags: ["工程化工作流规则", "第一阶段：日常工作流（每次任务必须遵循）", "第二阶段：高级工程化模式（复杂任务时启用）", "触发规则"]
-source: "C:/Users/Administrator/.claude/rules/domain/engineering-workflows.md"
----
-
-# 工程化工作流规则
-
-> **来源**: Claude Code Insights 报告分析（2025-12-26 至 2026-03-02）
-> **原则**: 验证闭环 → 结构化思维 → 数据一致性
-> **相关**: `testing.md`(TDD快速参考), `coding.md`(代码风格), `security.md`(安全检查)
-> **记忆**: Detailed patterns → `memory/engineering-patterns.md`
-
----
-
-## 第一阶段：日常工作流（每次任务必须遵循）
-
-### 1. UI 修改验证闭环
-
-**触发条件**: 任何 UI 修改、3D 可视化变更、前端组件调整
-
-**执行步骤**:
-
-1. 完成代码修改
-2. 用 `npm run dev` 启动应用
-3. 导航到受影响的组件
-4. 验证视觉元素正确渲染
-5. 检查浏览器控制台无错误
-6. **确认无误后才能标记任务完成**
-
-**禁止**: 修改 UI 代码后不验证就标记完成
-
----
-
-### 2. 功能实现结构化规划
-
-**触发条件**: 新功能开发、复杂 bug 修复、多文件变更
-
-**执行步骤**:
-
-1. 使用顺序思维分析需求
-2. 将功能分解为清晰的步骤
-3. 标注步骤间的依赖关系
-4. 按依赖顺序逐步实现
-5. 每步完成后验证再进入下一步
-
-**模板**:
-
-```
-步骤 1: [描述] — 依赖: 无
-步骤 2: [描述] — 依赖: 步骤 1
-步骤 3: [描述] — 依赖: 步骤 1, 2
-```
-
----
-
-### 3. 数据库变更事务化
-
-**触发条件**: 数据库 schema 变更、数据迁移、多表操作
-
-**执行步骤**:
-
-1. 分析涉及的所有表和依赖
-2. 编写迁移脚本，在单个事务中处理所有变更
-3. 包含回滚逻辑
-4. 通过 Bytebase MCP 执行
-5. 验证数据一致性
-
-**模板**:
-
-```sql
-BEGIN;
--- 变更操作
--- ...
--- 验证查询
-SELECT ... -- 确认数据一致
-COMMIT;
--- 如果失败: ROLLBACK;
-```
-
----
-
-## 第二阶段：高级工程化模式（复杂任务时启用）
-
-### 1. 测试驱动开发（TDD）全流程
-
-**触发条件**: 新功能开发、关键业务逻辑、高风险修改
-
-**执行步骤**:
-
-1. **规划**: 使用顺序思维规划架构
-2. **RED**: 编写覆盖所有边界情况的单元测试
-3. **GREEN**: 实现通过每个测试的最小代码
-4. **迭代**: 每次实现后运行测试，分析失败，迭代代码
-5. **属性测试**: 为关键函数生成基于属性的测试
-6. **变异测试**: 验证测试质量，补充遗漏的测试用例
-7. **记录**: 每一步的推理过程
-
-**验收标准**:
-
-- 测试覆盖率 ≥ 80%
-- 所有边界情况覆盖
-- 关键路径有属性测试
-
----
-
-### 2. 数据库迁移编排
-
-**触发条件**: 跨环境数据库迁移、schema 大改、数据模型重构
-
-**执行步骤**:
-
-1. **依赖分析**: 分析所有依赖和外键关系
-2. **脚本生成**: 生成正向迁移和回滚脚本
-3. **完整性验证**: 创建迁移前验证套件检查数据完整性
-4. **兼容层**: 构建向后兼容的视图
-5. **测试执行**: 先在测试环境执行迁移
-6. **验证查询**: 运行全面的验证查询
-7. **生产计划**: 生成带检查点的生产部署计划
-8. **逐步验证**: 使用 SQL 执行工具验证每个步骤
-9. **风险记录**: 记录潜在风险和回滚方案
-
-**模板**:
-
-```
-迁移计划: [当前模式] → [目标模式]
-├── 1. 依赖图谱
-├── 2. 正向迁移脚本
-├── 3. 回滚脚本
-├── 4. 验证套件
-├── 5. 兼容视图
-├── 6. 测试环境执行结果
-├── 7. 生产部署检查点
-└── 8. 风险评估
-```
-
----
-
-### 3. 自愈合组件系统
-
-**触发条件**: 核心 UI 组件开发、组件库建设、设计系统实现
-
-**执行步骤**:
-
-1. **扫描**: 扫描代码库了解当前实现及使用模式
-2. **回归测试**: 生成视觉回归测试和无障碍检查
-3. **响应式变体**: 构建针对不同断点优化的多个变体
-4. **性能基准**: 创建性能基准并优化瓶颈
-5. **类型接口**: 生成带完整 JSDoc 的 TypeScript 接口
-6. **Storybook**: 构建包含所有变体和状态的交互式故事
-7. **单元测试**: 创建验证功能和无障碍标准的测试
-8. **自动修复**: 发现现有组件问题时自动生成修复
-
-**验收标准**:
-
-- 所有断点有响应式变体
-- WCAG 2.1 AA 级无障碍
-- 性能基准通过
-- TypeScript 接口完整
-- 测试覆盖率 ≥ 80%
-
----
-
-### 4. 3D 可视化布局修改
-
-**触发条件**: Three.js / R3F 场景修改、节点布局算法变更、AttentionFlow 连线调整
-
-**执行步骤**:
-
-1. 理解当前数据规模（节点数量、分类分布）
-2. 布局算法修改时，按节点数量加权分配扇区角度（而非固定等分）
-3. 考虑溢出策略：节点数 > 扇区容量时，启用多环螺旋分布
-4. 连线连接点必须偏移到几何体表面，非中心点
-5. 不同几何体形状使用不同偏移系数（球=1.0, 方=1.2, 环=1.4）
-6. `npm run dev` 启动后用截图验证全局布局 + 局部连线
-
-**关键教训（2026-02-09）**:
-
-- 固定角度等分在节点数差异大时（如 50 Skills vs 3 Hooks）会导致重叠
-- 3D 连线 `AttentionFlow` 连到中心点会穿透几何体，必须做表面偏移
-
----
-
-### 5. 大规模数据处理 + 前端展示
-
-**触发条件**: 批量数据查询、大数据集前端渲染、用户搜索功能
-
-**执行步骤**:
-
-1. 数据获取：分批查询（batch），每批控制在合理大小
-2. 数据处理：去重（dedup）+ 分类（classify）+ 聚合
-3. 前端展示：懒加载图片、视频首帧 `#t=0.1`、`object-fit: cover`
-4. 搜索功能：支持多字段（用户名 + 数字 ID）
-5. 跑马灯/列表数据：必须 deduplicate display names
-
-**关键教训（2026-02-09）**:
-
-- Marquee 展示重复显示名 → 需要前端 Set 去重
-- 图片比例不一 → 1:1 裁剪必须在 CSS 层面固定
-- 348K 用户数据 → 必须按需加载，不能全量传输
-
----
-
-## 触发规则
-
-| 任务类型       | 最低要求         | 推荐流程                 |
-| -------------- | ---------------- | ------------------------ |
-| 简单 UI 修改   | 第一阶段 #1      | 验证闭环                 |
-| 新功能开发     | 第一阶段 #1 + #2 | + 第二阶段 #1 (TDD)      |
-| 数据库变更     | 第一阶段 #3      | + 第二阶段 #2 (迁移编排) |
-| 核心组件       | 第一阶段 #1 + #2 | + 第二阶段 #3 (自愈合)   |
-| 多文件重构     | 第一阶段 #2      | + 第二阶段 #1 (TDD)      |
-| 3D 可视化修改  | 第一阶段 #1 + #4 | 截图验证闭环             |
-| 大规模数据展示 | 第一阶段 #2 + #5 | 分批 + 去重 + 懒加载     |
-
----
-
-**版本**: v1.2
-**来源**: Claude Code Insights 报告
-**更新**: 2026-03-02 (添加交叉引用, 收束工程化内容)
-**上次内容更新**: 2026-02-09 (新增 3D 可视化、大规模数据处理工作流)
-**状态**: Active
-**记忆同步**: `memory/engineering-patterns.md`
+---
+id: "engineering-workflows"
+title: "工程化工作流规则"
+category: "domain"
+tags: ["工程化工作流规则", "第一阶段：日常工作流（每次任务必须遵循）", "第二阶段：高级工程化模式（复杂任务时启用）", "触发规则"]
+source: "C:/Users/Administrator/.claude/rules/domain/engineering-workflows.md"
+---
+
+# 工程化工作流规则
+
+> **来源**: Claude Code Insights 报告分析（2025-12-26 至 2026-03-02）
+> **原则**: 验证闭环 → 结构化思维 → 数据一致性
+> **相关**: `testing.md`(TDD快速参考), `coding.md`(代码风格), `security.md`(安全检查)
+> **记忆**: Detailed patterns → `memory/engineering-patterns.md`
+
+---
+
+## 第一阶段：日常工作流（每次任务必须遵循）
+
+### 1. UI 修改验证闭环
+
+**触发条件**: 任何 UI 修改、3D 可视化变更、前端组件调整
+
+**执行步骤**:
+
+1. 完成代码修改
+2. 用 `npm run dev` 启动应用
+3. 导航到受影响的组件
+4. 验证视觉元素正确渲染
+5. 检查浏览器控制台无错误
+6. **确认无误后才能标记任务完成**
+
+**禁止**: 修改 UI 代码后不验证就标记完成
+
+---
+
+### 2. 功能实现结构化规划
+
+**触发条件**: 新功能开发、复杂 bug 修复、多文件变更
+
+**执行步骤**:
+
+1. 使用顺序思维分析需求
+2. 将功能分解为清晰的步骤
+3. 标注步骤间的依赖关系
+4. 按依赖顺序逐步实现
+5. 每步完成后验证再进入下一步
+
+**模板**:
+
+```
+步骤 1: [描述] — 依赖: 无
+步骤 2: [描述] — 依赖: 步骤 1
+步骤 3: [描述] — 依赖: 步骤 1, 2
+```
+
+---
+
+### 3. 数据库变更事务化
+
+**触发条件**: 数据库 schema 变更、数据迁移、多表操作
+
+**执行步骤**:
+
+1. 分析涉及的所有表和依赖
+2. 编写迁移脚本，在单个事务中处理所有变更
+3. 包含回滚逻辑
+4. 通过 Bytebase MCP 执行
+5. 验证数据一致性
+
+**模板**:
+
+```sql
+BEGIN;
+-- 变更操作
+-- ...
+-- 验证查询
+SELECT ... -- 确认数据一致
+COMMIT;
+-- 如果失败: ROLLBACK;
+```
+
+---
+
+## 第二阶段：高级工程化模式（复杂任务时启用）
+
+### 1. 测试驱动开发（TDD）全流程
+
+**触发条件**: 新功能开发、关键业务逻辑、高风险修改
+
+**执行步骤**:
+
+1. **规划**: 使用顺序思维规划架构
+2. **RED**: 编写覆盖所有边界情况的单元测试
+3. **GREEN**: 实现通过每个测试的最小代码
+4. **迭代**: 每次实现后运行测试，分析失败，迭代代码
+5. **属性测试**: 为关键函数生成基于属性的测试
+6. **变异测试**: 验证测试质量，补充遗漏的测试用例
+7. **记录**: 每一步的推理过程
+
+**验收标准**:
+
+- 测试覆盖率 ≥ 80%
+- 所有边界情况覆盖
+- 关键路径有属性测试
+
+---
+
+### 2. 数据库迁移编排
+
+**触发条件**: 跨环境数据库迁移、schema 大改、数据模型重构
+
+**执行步骤**:
+
+1. **依赖分析**: 分析所有依赖和外键关系
+2. **脚本生成**: 生成正向迁移和回滚脚本
+3. **完整性验证**: 创建迁移前验证套件检查数据完整性
+4. **兼容层**: 构建向后兼容的视图
+5. **测试执行**: 先在测试环境执行迁移
+6. **验证查询**: 运行全面的验证查询
+7. **生产计划**: 生成带检查点的生产部署计划
+8. **逐步验证**: 使用 SQL 执行工具验证每个步骤
+9. **风险记录**: 记录潜在风险和回滚方案
+
+**模板**:
+
+```
+迁移计划: [当前模式] → [目标模式]
+├── 1. 依赖图谱
+├── 2. 正向迁移脚本
+├── 3. 回滚脚本
+├── 4. 验证套件
+├── 5. 兼容视图
+├── 6. 测试环境执行结果
+├── 7. 生产部署检查点
+└── 8. 风险评估
+```
+
+---
+
+### 3. 自愈合组件系统
+
+**触发条件**: 核心 UI 组件开发、组件库建设、设计系统实现
+
+**执行步骤**:
+
+1. **扫描**: 扫描代码库了解当前实现及使用模式
+2. **回归测试**: 生成视觉回归测试和无障碍检查
+3. **响应式变体**: 构建针对不同断点优化的多个变体
+4. **性能基准**: 创建性能基准并优化瓶颈
+5. **类型接口**: 生成带完整 JSDoc 的 TypeScript 接口
+6. **Storybook**: 构建包含所有变体和状态的交互式故事
+7. **单元测试**: 创建验证功能和无障碍标准的测试
+8. **自动修复**: 发现现有组件问题时自动生成修复
+
+**验收标准**:
+
+- 所有断点有响应式变体
+- WCAG 2.1 AA 级无障碍
+- 性能基准通过
+- TypeScript 接口完整
+- 测试覆盖率 ≥ 80%
+
+---
+
+### 4. 3D 可视化布局修改
+
+**触发条件**: Three.js / R3F 场景修改、节点布局算法变更、AttentionFlow 连线调整
+
+**执行步骤**:
+
+1. 理解当前数据规模（节点数量、分类分布）
+2. 布局算法修改时，按节点数量加权分配扇区角度（而非固定等分）
+3. 考虑溢出策略：节点数 > 扇区容量时，启用多环螺旋分布
+4. 连线连接点必须偏移到几何体表面，非中心点
+5. 不同几何体形状使用不同偏移系数（球=1.0, 方=1.2, 环=1.4）
+6. `npm run dev` 启动后用截图验证全局布局 + 局部连线
+
+**关键教训（2026-02-09）**:
+
+- 固定角度等分在节点数差异大时（如 50 Skills vs 3 Hooks）会导致重叠
+- 3D 连线 `AttentionFlow` 连到中心点会穿透几何体，必须做表面偏移
+
+---
+
+### 5. 大规模数据处理 + 前端展示
+
+**触发条件**: 批量数据查询、大数据集前端渲染、用户搜索功能
+
+**执行步骤**:
+
+1. 数据获取：分批查询（batch），每批控制在合理大小
+2. 数据处理：去重（dedup）+ 分类（classify）+ 聚合
+3. 前端展示：懒加载图片、视频首帧 `#t=0.1`、`object-fit: cover`
+4. 搜索功能：支持多字段（用户名 + 数字 ID）
+5. 跑马灯/列表数据：必须 deduplicate display names
+
+**关键教训（2026-02-09）**:
+
+- Marquee 展示重复显示名 → 需要前端 Set 去重
+- 图片比例不一 → 1:1 裁剪必须在 CSS 层面固定
+- 348K 用户数据 → 必须按需加载，不能全量传输
+
+---
+
+## 触发规则
+
+| 任务类型       | 最低要求         | 推荐流程                 |
+| -------------- | ---------------- | ------------------------ |
+| 简单 UI 修改   | 第一阶段 #1      | 验证闭环                 |
+| 新功能开发     | 第一阶段 #1 + #2 | + 第二阶段 #1 (TDD)      |
+| 数据库变更     | 第一阶段 #3      | + 第二阶段 #2 (迁移编排) |
+| 核心组件       | 第一阶段 #1 + #2 | + 第二阶段 #3 (自愈合)   |
+| 多文件重构     | 第一阶段 #2      | + 第二阶段 #1 (TDD)      |
+| 3D 可视化修改  | 第一阶段 #1 + #4 | 截图验证闭环             |
+| 大规模数据展示 | 第一阶段 #2 + #5 | 分批 + 去重 + 懒加载     |
+
+---
+
+**版本**: v1.2
+**来源**: Claude Code Insights 报告
+**更新**: 2026-03-02 (添加交叉引用, 收束工程化内容)
+**上次内容更新**: 2026-02-09 (新增 3D 可视化、大规模数据处理工作流)
+**状态**: Active
+**记忆同步**: `memory/engineering-patterns.md`