mirror of
https://github.com/Powerful-517/yys-editor.git
synced 2026-03-05 15:05:27 +00:00
rookie4show
92aa4094f5
- 安装 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)
364 lines
7.6 KiB
Markdown
364 lines
7.6 KiB
Markdown
# 开发工作流程
|
||
|
||
本文档描述在 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) - 代码提交规范
|