test: 集成 Vitest 测试框架和开发规范

- 安装 vitest, @vue/test-utils, jsdom 等测试依赖 - 配置 vitest.config.js 测试环境 - 添加 schema.test.ts (7个数据结构验证测试) - 添加 useStore.test.ts (7个状态管理测试) - 创建测试指南文档 (docs/testing.md) - 创建测试规范文档 (docs/testing-rules.md) - 创建开发规范文档 (docs/development-rules.md) - 创建开发工作流程文档 (docs/1management/workflow.md) - 添加测试相关 npm scripts (test, test:watch, test:ui, test:coverage) - 所有测试通过 (14/14)
2026-03-05 06:55:26 +00:00 · 2026-02-12 23:25:13 +08:00
parent c4d701b443
commit 92aa4094f5
13 changed files with 4245 additions and 17 deletions
--- a/docs/1management/workflow.md
+++ b/docs/1management/workflow.md
@@ -0,0 +1,363 @@
+# 开发工作流程
+
+本文档描述在 yys-editor 项目中开发新功能的标准流程。
+
+## 开发流程概览
+
+```
+确定任务 → 需求分析 → 设计方案 → 编写测试 → 实现功能 → 测试验证 → 更新文档 → 提交代码
+```
+
+## 详细步骤
+
+### 0. 确定任务（第一步）
+
+**在开始任何开发工作前，先确定要做什么：**
+
+#### 0.1 查看任务列表
+
+1. **优先查看** `docs/1management/next.md`
+   - 这里记录了下一步要做的任务
+   - 按优先级排序
+   - 包含任务的简要描述
+
+2. **参考** `docs/1management/plan.md`
+   - 查看项目整体规划
+   - 了解任务的背景和目标
+   - 确认任务的优先级和依赖关系
+
+#### 0.2 确定任务来源
+
+任务可能来自：
+- `next.md` 中的待办事项
+- 用户直接提出的需求
+- Bug 修复需求
+- 技术债务优化
+
+#### 0.3 任务确认
+
+- 明确任务的具体目标
+- 确认任务的优先级
+- 评估任务的工作量
+- 检查是否有依赖的前置任务
+
+### 1. 需求分析
+
+- 明确功能需求和预期效果
+- 确定影响范围（数据层、UI 层、业务逻辑）
+- 评估是否需要修改现有数据结构
+- 在 `plan.md` 中记录设计思路（如果是重要功能）
+
+### 2. 设计方案
+
+- 确定实现方案和技术选型
+- 如果涉及数据模型变更，更新 `schema.ts`
+- 如果涉及状态管理，规划 Store 的修改
+- 考虑向后兼容性和数据迁移
+
+### 3. 编写测试（重要！）
+
+**在实现功能之前，先编写测试用例**
+
+#### 3.1 确定测试范围
+
+根据改动类型选择测试文件：
+
+| 改动类型 | 测试文件 | 示例 |
+|---------|---------|------|
+| 数据模型 | `schema.test.ts` | 添加新的节点类型 |
+| Store 操作 | `useStore.test.ts` | 文件导入导出逻辑 |
+| 工具函数 | `<功能名>.test.ts` | 数据转换、验证函数 |
+| 组件逻辑 | `<组件名>.test.ts` | 复杂的组件交互 |
+
+#### 3.2 编写测试用例
+
+在 `src/__tests__/` 目录创建或更新测试文件：
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest'
+
+describe('新功能名称', () => {
+  beforeEach(() => {
+    // 测试前的准备工作
+  })
+
+  it('应该正确处理正常情况', () => {
+    // 准备测试数据
+    const input = { /* ... */ }
+
+    // 执行功能
+    const result = newFeature(input)
+
+    // 验证结果
+    expect(result).toBe(expectedValue)
+  })
+
+  it('应该处理边界情况', () => {
+    // 测试空值、极端值等
+  })
+
+  it('应该处理错误情况', () => {
+    // 测试异常处理
+  })
+})
+```
+
+#### 3.3 运行测试（此时应该失败）
+
+```bash
+npm test
+```
+
+测试失败是正常的，因为功能还没实现。
+
+### 4. 实现功能
+
+根据测试用例的描述，实现具体功能：
+
+- 保持代码简洁清晰
+- 添加必要的注释
+- 遵循项目代码风格
+- 考虑性能和安全性
+
+### 5. 测试验证
+
+#### 5.1 运行单元测试
+
+```bash
+# 监听模式，实时查看测试结果
+npm run test:watch
+
+# 或单次运行
+npm test
+```
+
+确保所有测试通过（包括新增和已有的测试）。
+
+#### 5.2 手动测试
+
+- 启动开发服务器：`npm run dev`
+- 在浏览器中测试新功能
+- 验证 UI 交互和用户体验
+- 测试边界情况和异常场景
+
+#### 5.3 测试覆盖率（可选）
+
+```bash
+npm run test:coverage
+```
+
+查看测试覆盖率报告，确保关键代码被测试覆盖。
+
+### 6. 代码质量检查
+
+#### 6.1 代码格式化
+
+```bash
+npm run format
+```
+
+#### 6.2 代码检查
+
+```bash
+npm run lint
+```
+
+修复所有 ESLint 警告和错误。
+
+#### 6.3 一键检查（推荐）
+
+```bash
+npm test && npm run lint && npm run format
+```
+
+### 7. 更新文档
+
+**完成功能后，必须更新项目管理文档：**
+
+#### 7.1 更新 next.md
+
+- 将已完成的任务标记为完成或删除
+- 如果发现新的待办事项，添加到列表中
+- 调整任务优先级（如有必要）
+
+#### 7.2 更新 plan.md
+
+- 记录已完成的功能
+- 更新项目进度
+- 如果有重要的设计决策，记录下来
+- 更新已知问题列表
+
+#### 7.3 更新其他文档（如有必要）
+
+- 如果添加了新的 API 或功能，更新相关文档
+- 如果修改了数据结构，更新 schema 说明
+- 如果有用户可见的变化，更新 README 或更新日志
+
+### 8. 提交代码
+
+#### 8.1 提交前检查清单
+
+- [ ] 所有测试通过
+- [ ] 新功能有对应的测试用例
+- [ ] 代码已格式化
+- [ ] 没有 ESLint 错误
+- [ ] 手动测试通过
+- [ ] **已更新 next.md 和 plan.md**
+- [ ] 更新了相关文档（如有必要）
+
+#### 8.2 编写 Commit 消息
+
+遵循规范格式：
+
+```
+<type>: <subject>
+
+<body>
+```
+
+**Type 类型：**
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `test`: 添加或修改测试
+- `refactor`: 重构代码
+- `style`: 样式调整
+- `docs`: 文档更新
+- `chore`: 构建或工具变动
+
+**示例：**
+```
+feat: 添加式神筛选功能
+
+- 实现按稀有度筛选
+- 添加搜索框支持名称搜索
+- 补充单元测试覆盖筛选逻辑
+```
+
+#### 8.3 提交代码
+
+```bash
+git add .
+git commit -m "feat: 添加式神筛选功能"
+git push
+```
+
+#### 8.4 任务完成后的最终确认
+
+- [ ] 代码已提交
+- [ ] `next.md` 已更新（任务已完成或移除）
+- [ ] `plan.md` 已更新（记录进度）
+- [ ] 相关文档已同步更新
+
+## 文档更新示例
+
+### 示例 1: 完成 next.md 中的任务
+
+**任务前 (next.md):**
+```markdown
+## 下一步任务
+
+1. [ ] 添加式神筛选功能
+2. [ ] 优化文件导出性能
+```
+
+**任务后 (next.md):**
+```markdown
+## 下一步任务
+
+1. [x] ~~添加式神筛选功能~~ (已完成 2024-01-15)
+2. [ ] 优化文件导出性能
+```
+
+或直接删除已完成的任务：
+```markdown
+## 下一步任务
+
+1. [ ] 优化文件导出性能
+```
+
+### 示例 2: 更新 plan.md
+
+**在 plan.md 的相应章节添加：**
+```markdown
+## 已完成功能
+
+### 式神筛选功能 (2024-01-15)
+- 实现按稀有度筛选
+- 添加搜索框支持名称搜索
+- 测试覆盖率: 95%
+```
+
+## 特殊场景处理
+
+### 场景 1: 紧急 Bug 修复
+
+1. 创建 `fix/` 分支
+2. 先写测试复现 bug
+3. 修复代码直到测试通过
+4. 快速提交和部署
+
+### 场景 2: 重构现有代码
+
+1. 确保现有测试覆盖要重构的代码
+2. 如果没有测试，先补充测试
+3. 重构代码，保持测试通过
+4. 提交时使用 `refactor:` 类型
+
+### 场景 3: 仅 UI 调整
+
+- 可以不写单元测试
+- 但必须手动测试验证
+- 确保没有破坏现有功能
+
+### 场景 4: 数据模型变更
+
+1. 更新 `schema.ts` 类型定义
+2. 在 `schema.test.ts` 添加测试
+3. 实现数据迁移逻辑（如需要）
+4. 测试新旧数据的兼容性
+
+## 开发工具推荐
+
+### 测试相关
+
+```bash
+# 可视化测试界面
+npm run test:ui
+
+# 监听模式（开发时推荐）
+npm run test:watch
+```
+
+### 调试技巧
+
+- 在测试中使用 `console.log` 查看中间状态
+- 使用 `it.only()` 只运行特定测试
+- 使用 `it.skip()` 跳过某些测试（临时）
+
+## 常见问题
+
+### Q: 测试失败了怎么办？
+
+1. 仔细阅读错误信息
+2. 检查是代码问题还是测试用例问题
+3. 使用 `console.log` 调试
+4. 不要跳过或删除失败的测试
+
+### Q: 改动很小，必须写测试吗？
+
+- 如果涉及数据层或业务逻辑：**必须**
+- 如果只是 UI 样式调整：可以不写
+- 如果不确定：**建议写测试**
+
+### Q: 测试写起来很慢怎么办？
+
+- 参考现有测试用例的写法
+- 使用测试模板快速开始
+- 测试投入的时间会在后续维护中节省回来
+
+## 相关文档
+
+- [测试指南](../testing.md) - 如何运行和编写测试
+- [测试规范](../testing-rules.md) - 测试相关的强制要求
+- [开发规范](../development-rules.md) - 代码提交规范