# 开发工作流程 本文档描述在 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 类型：** - `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) - 代码提交规范