mirror of
https://gitee.com/spark-store-project/spark-store
synced 2026-04-26 01:10:16 +08:00
chore: add comprehensive documentation and testing infrastructure
## 文档（全部中文） - AGENTS.md - 完整的 AI 编码指南（中文版） - CONTRIBUTING.md - 贡献指南 - DEVELOPMENT.md - 开发文档 - DEPLOYMENT.md - 部署文档 - TESTING.md - 测试文档 - TROUBLESHOOTING.md - 问题排查指南 - FAQ.md - 常见问题 - WORKFLOW.md - 标准开发流程文档 ## AI 工作流（9个详细工作流） - feature-development.md - 新功能开发流程 - bug-fix.md - Bug 修复流程 - code-review.md - 代码审查流程 - testing.md - 测试编写流程 - release.md - 发布流程 - refactoring.md - 代码重构流程 - documentation.md - 文档更新流程 - performance-optimization.md - 性能优化流程 - security-audit.md - 安全审计流程 ## 测试基础设施 - vitest.config.ts - Vitest 单元测试配置 - playwright.config.ts - Playwright E2E 测试配置 - src/__tests__/setup.ts - 测试环境设置 - src/__tests__/unit/downloadStatus.test.ts - 示例单元测试 - e2e/basic.spec.ts - 示例 E2E 测试 ## CI/CD - .github/workflows/test.yml - 新建测试 CI 工作流 - .github/workflows/build.yml - 更新构建工作流，添加测试步骤 ## Issue 模板 - 更新 bug_report.md 为标准 Bug 报告模板 - 更新 help_wanted.md 为标准功能请求模板 ## 配置更新 - package.json - 添加测试依赖和 7 个新的 npm 脚本 - .gitignore - 添加测试相关忽略项 ## 新增 npm 脚本 - test - 运行单元测试 - test:watch - 监听模式 - test:coverage - 生成覆盖率报告 - test:e2e - 运行 E2E 测试 - test:e2e:ui - E2E UI 模式 - test:e2e:debug - E2E 调试模式 - test:all - 运行所有测试 ## 新增测试依赖 - @playwright/test ^1.40.0 - @testing-library/jest-dom ^6.1.5 - @testing-library/vue ^8.0.1 - @vitest/coverage-v8 ^1.0.0 - @vue/test-utils ^2.4.3 - jsdom ^23.0.1 - vitest ^1.0.0
This commit is contained in:
632
WORKFLOW.md
Normal file
632
WORKFLOW.md
Normal file
@@ -0,0 +1,632 @@
|
||||
# 标准开发流程
|
||||
|
||||
本文档描述在 APM 应用商店项目中完成代码开发后的标准提交流程。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [开发前准备](#开发前准备)
|
||||
- [代码完成后](#代码完成后)
|
||||
- [提交流程](#提交流程)
|
||||
- [典型场景](#典型场景)
|
||||
- [提交流程检查清单](#提交流程检查清单)
|
||||
- [常见问题](#常见问题)
|
||||
|
||||
---
|
||||
|
||||
## 开发前准备
|
||||
|
||||
在开始开发之前，确保你的开发环境已正确配置：
|
||||
|
||||
```bash
|
||||
# 1. 切换到项目目录
|
||||
cd apm-app-store
|
||||
|
||||
# 2. 拉取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 3. 创建功能分支
|
||||
git checkout -b feature/your-feature-name
|
||||
# 或修复分支
|
||||
git checkout -b fix/your-bug-fix
|
||||
|
||||
# 4. 确保依赖已安装
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 代码完成后
|
||||
|
||||
### 1️⃣ 运行代码检查
|
||||
|
||||
首先确保代码符合项目规范：
|
||||
|
||||
```bash
|
||||
# 运行 ESLint 检查
|
||||
npm run lint
|
||||
|
||||
# 如果有错误，尝试自动修复
|
||||
npm run lint:fix
|
||||
|
||||
# 手动修复无法自动处理的问题
|
||||
```
|
||||
|
||||
**ESLint 错误类型：**
|
||||
|
||||
- `@typescript-eslint/no-explicit-any`: 避免使用 `any` 类型
|
||||
- `@typescript-eslint/no-unused-vars`: 未使用的变量
|
||||
- 其他代码风格问题
|
||||
|
||||
### 2️⃣ 格式化代码
|
||||
|
||||
使用 Prettier 格式化代码：
|
||||
|
||||
```bash
|
||||
npm run format
|
||||
```
|
||||
|
||||
### 3️⃣ 运行测试
|
||||
|
||||
确保所有测试通过：
|
||||
|
||||
```bash
|
||||
# 运行单元测试
|
||||
npm run test
|
||||
|
||||
# 生成测试覆盖率报告
|
||||
npm run test:coverage
|
||||
|
||||
# 运行 E2E 测试（如果需要）
|
||||
npm run test:e2e
|
||||
|
||||
# 运行所有测试
|
||||
npm run test:all
|
||||
```
|
||||
|
||||
**测试覆盖率要求：**
|
||||
|
||||
- 语句覆盖率: ≥ 70%
|
||||
- 分支覆盖率: ≥ 70%
|
||||
- 函数覆盖率: ≥ 70%
|
||||
- 行覆盖率: ≥ 70%
|
||||
|
||||
### 4️⃣ 构建验证
|
||||
|
||||
验证代码可以成功构建：
|
||||
|
||||
```bash
|
||||
# 仅构建前端代码（快速）
|
||||
npm run build:vite
|
||||
```
|
||||
|
||||
如果构建失败，检查 TypeScript 错误并修复。
|
||||
|
||||
---
|
||||
|
||||
## 提交流程
|
||||
|
||||
### 5️⃣ 提交代码
|
||||
|
||||
#### 查看变更
|
||||
|
||||
```bash
|
||||
# 查看所有变更文件
|
||||
git status
|
||||
|
||||
# 查看具体变更
|
||||
git diff
|
||||
```
|
||||
|
||||
#### 添加文件
|
||||
|
||||
```bash
|
||||
# 添加所有变更文件
|
||||
git add .
|
||||
|
||||
# 或添加特定文件
|
||||
git add path/to/file.ts
|
||||
```
|
||||
|
||||
#### 提交信息
|
||||
|
||||
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
[可选的正文]
|
||||
|
||||
[可选的脚注]
|
||||
```
|
||||
|
||||
**Type 类型：**
|
||||
|
||||
- `feat`: 新功能
|
||||
- `fix`: Bug 修复
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码格式（不影响功能）
|
||||
- `refactor`: 重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具相关
|
||||
|
||||
**Scope 范围：**
|
||||
|
||||
- `app`: 应用核心
|
||||
- `install`: 安装/卸载
|
||||
- `ui`: UI 组件
|
||||
- `ipc`: IPC 通信
|
||||
- `api`: API 集成
|
||||
- `theme`: 主题
|
||||
- `build`: 构建
|
||||
- `docs`: 文档
|
||||
|
||||
**Subject 主题：**
|
||||
|
||||
- 使用现在时态（"add" 而非 "added"）
|
||||
- 首字母小写
|
||||
- 不以句号结尾
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 新功能
|
||||
git commit -m "feat(install): add retry mechanism for failed installations" -s
|
||||
|
||||
# Bug 修复
|
||||
git commit -m "fix(ui): correct dark mode toggle persistence" -s
|
||||
|
||||
# 文档更新
|
||||
git commit -m "docs(readme): update build instructions" -s
|
||||
|
||||
# 重构
|
||||
git commit -m "refactor(ipc): simplify install manager event handling" -s
|
||||
|
||||
# 测试
|
||||
git commit -m "test(download): add unit tests for download queue" -s
|
||||
```
|
||||
|
||||
**添加签名：**
|
||||
|
||||
```bash
|
||||
# 使用 -s 添加签名
|
||||
git commit -m "feat(example): add new feature" -s
|
||||
|
||||
# 或在 ~/.gitconfig 中配置
|
||||
# [commit]
|
||||
# gpgsign = true
|
||||
```
|
||||
|
||||
#### 执行提交
|
||||
|
||||
```bash
|
||||
git commit -m "type(scope): description" -s
|
||||
```
|
||||
|
||||
### 6️⃣ 推送到远程仓库
|
||||
|
||||
```bash
|
||||
# 推送当前分支
|
||||
git push origin feature/your-feature-name
|
||||
|
||||
# 或使用简写
|
||||
git push -u origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### 7️⃣ 创建 Pull Request
|
||||
|
||||
#### 访问 GitHub
|
||||
|
||||
1. 访问仓库页面
|
||||
2. 点击 "New Pull Request"
|
||||
3. 选择你的分支 → main 分支
|
||||
|
||||
#### 填写 PR 模板
|
||||
|
||||
使用 PR 模板填写信息：
|
||||
|
||||
**变更类型：**
|
||||
|
||||
- [ ] `feat` - 新功能
|
||||
- [ ] `fix` - Bug 修复
|
||||
- [ ] `refactor` - 重构
|
||||
- [ ] `docs` - 文档更新
|
||||
- [ ] `test` - 测试相关
|
||||
- [ ] `chore` - 构建/工具相关
|
||||
|
||||
**变更描述：**
|
||||
清晰简洁地说明你做了什么，为什么这么做。
|
||||
|
||||
**相关 Issue：**
|
||||
引用相关的 Issue 编号，例如 `Fixes #123` 或 `Closes #123`。
|
||||
|
||||
**测试说明：**
|
||||
如何测试这些变更？包括：
|
||||
|
||||
- 测试步骤
|
||||
- 预期结果
|
||||
- 测试环境
|
||||
|
||||
**截图/录屏：**
|
||||
如果涉及 UI 变更，添加截图或录屏。
|
||||
|
||||
**检查清单：**
|
||||
|
||||
- [ ] 代码通过 `npm run lint`
|
||||
- [ ] 代码通过 `npm run format`
|
||||
- [ ] 所有测试通过 (`npm run test`)
|
||||
- [ ] 新功能包含测试
|
||||
- [ ] 文档已更新（如需要）
|
||||
|
||||
#### 提交 PR
|
||||
|
||||
点击 "Create Pull Request"。
|
||||
|
||||
### 8️⃣ 代码审查
|
||||
|
||||
#### 等待审查
|
||||
|
||||
- 至少一位维护者会审查你的 PR
|
||||
- CI 会自动运行测试和检查
|
||||
- 确保所有 CI 检查通过（绿色 ✅）
|
||||
|
||||
#### 响应审查意见
|
||||
|
||||
- 阅审审查者提出的意见
|
||||
- 进行必要的修改
|
||||
- 提交更改到你的分支
|
||||
- 在 PR 中评论说明修改内容
|
||||
|
||||
#### 更新 PR
|
||||
|
||||
```bash
|
||||
# 修改代码后
|
||||
git add .
|
||||
git commit -m "address review feedback" -s
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### 9️⃣ 合并 PR
|
||||
|
||||
#### 合并条件
|
||||
|
||||
- 至少一次审查批准
|
||||
- 所有 CI 检查通过
|
||||
- 无冲突
|
||||
- 分支最新
|
||||
|
||||
#### 合并方式
|
||||
|
||||
- 使用 "Squash and merge" 将提交压缩为一个
|
||||
- 或使用 "Merge commit" 保留提交历史
|
||||
|
||||
#### 删除分支
|
||||
|
||||
合并后删除你的功能分支：
|
||||
|
||||
```bash
|
||||
# 删除本地分支
|
||||
git branch -d feature/your-feature-name
|
||||
|
||||
# 删除远程分支
|
||||
git push origin --delete feature/your-feature-name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型场景
|
||||
|
||||
### 场景 1: 开发新功能
|
||||
|
||||
```bash
|
||||
# 1. 创建功能分支
|
||||
git checkout -b feature/add-search-filters
|
||||
|
||||
# 2. 开发代码...
|
||||
# （编写代码）
|
||||
|
||||
# 3. 运行检查
|
||||
npm run lint
|
||||
npm run lint:fix
|
||||
npm run format
|
||||
npm run test
|
||||
|
||||
# 4. 构建验证
|
||||
npm run build:vite
|
||||
|
||||
# 5. 提交代码
|
||||
git add .
|
||||
git commit -m "feat(search): add advanced search filters with category filtering" -s
|
||||
|
||||
# 6. 推送
|
||||
git push -u origin feature/add-search-filters
|
||||
|
||||
# 7. 创建 PR
|
||||
# （在 GitHub 上创建 PR）
|
||||
```
|
||||
|
||||
### 场景 2: 修复 Bug
|
||||
|
||||
```bash
|
||||
# 1. 创建修复分支
|
||||
git checkout -b fix/fix-download-timeout
|
||||
|
||||
# 2. 修复代码...
|
||||
|
||||
# 3. 运行检查
|
||||
npm run lint
|
||||
npm run format
|
||||
npm run test
|
||||
|
||||
# 4. 提交代码
|
||||
git add .
|
||||
git commit -m "fix(download): resolve timeout issue with retry logic" -m "Fixes #123" -s
|
||||
|
||||
# 5. 推送
|
||||
git push -u origin fix/fix-download-timeout
|
||||
|
||||
# 6. 创建 PR
|
||||
```
|
||||
|
||||
### 场景 3: 更新文档
|
||||
|
||||
```bash
|
||||
# 1. 创建文档分支
|
||||
git checkout -b docs/update-api-docs
|
||||
|
||||
# 2. 更新文档...
|
||||
|
||||
# 3. 提交代码
|
||||
git add .
|
||||
git commit -m "docs(api): update installation API documentation" -s
|
||||
|
||||
# 4. 推送
|
||||
git push -u origin docs/update-api-docs
|
||||
|
||||
# 5. 创建 PR
|
||||
```
|
||||
|
||||
### 场景 4: 重构代码
|
||||
|
||||
```bash
|
||||
# 1. 创建重构分支
|
||||
git checkout -b refactor/simplify-download-manager
|
||||
|
||||
# 2. 重构代码...
|
||||
|
||||
# 3. 运行检查
|
||||
npm run lint
|
||||
npm run format
|
||||
npm run test
|
||||
|
||||
# 4. 提交代码
|
||||
git add .
|
||||
git commit -m "refactor(download): simplify download manager event handling" -s
|
||||
|
||||
# 5. 推送
|
||||
git push -u origin refactor/simplify-download-manager
|
||||
|
||||
# 6. 创建 PR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提交流程检查清单
|
||||
|
||||
在创建 PR 前，确保完成以下检查：
|
||||
|
||||
### 代码质量
|
||||
|
||||
- [ ] ESLint 检查通过 (`npm run lint`)
|
||||
- [ ] 代码已格式化 (`npm run format`)
|
||||
- [ ] 没有 `any` 类型（除非必要并添加注释）
|
||||
- [ ] 遵循代码规范（见 [AGENTS.md](./AGENTS.md)）
|
||||
- [ ] TypeScript 严格模式通过
|
||||
|
||||
### 测试
|
||||
|
||||
- [ ] 单元测试通过 (`npm run test`)
|
||||
- [ ] 新功能包含测试
|
||||
- [ ] 测试覆盖率 ≥ 70%
|
||||
- [ ] E2E 测试通过（如需要，`npm run test:e2e`）
|
||||
- [ ] 没有测试回归
|
||||
|
||||
### 文档
|
||||
|
||||
- [ ] 更新了相关文档（如需要）
|
||||
- [ ] 更新了 CHANGELOG.md（如需要）
|
||||
- [ ] API 文档更新（如需要）
|
||||
- [ ] README.md 更新（如需要）
|
||||
|
||||
### 功能验证
|
||||
|
||||
- [ ] 本地测试通过
|
||||
- [ ] 没有引入新 Bug
|
||||
- [ ] 边界情况已处理
|
||||
- [ ] 错误处理完善
|
||||
- [ ] 性能未下降
|
||||
|
||||
### 提交信息
|
||||
|
||||
- [ ] 遵循 Conventional Commits 规范
|
||||
- [ ] 添加了签名（`-s`）
|
||||
- [ ] 引用相关 Issue（如适用）
|
||||
- [ ] 提交信息清晰明确
|
||||
|
||||
---
|
||||
|
||||
## 快速提交命令
|
||||
|
||||
如果你想快速提交所有检查，可以使用以下命令：
|
||||
|
||||
```bash
|
||||
# 完整流程（一行命令）
|
||||
npm run lint && npm run format && npm run test && git add . && git commit -m "type(scope): description" -s && git push -u origin $(git branch --show-current)
|
||||
```
|
||||
|
||||
### 创建便捷脚本
|
||||
|
||||
在 `scripts/` 目录下创建 `commit.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 检查参数
|
||||
if [ -z "$1" ]; then
|
||||
echo "❌ 错误: 请提供提交信息"
|
||||
echo "使用方法: ./scripts/commit.sh \"type(scope): description\""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "🔍 Running lint..."
|
||||
npm run lint
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ ESLint 检查失败，请修复错误后重试"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "🎨 Formatting code..."
|
||||
npm run format
|
||||
|
||||
echo "🧪 Running tests..."
|
||||
npm run test
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ 测试失败，请修复测试后重试"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📝 Committing changes..."
|
||||
git add .
|
||||
git commit -m "$1" -s
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ 提交失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "🚀 Pushing to remote..."
|
||||
BRANCH_NAME=$(git branch --show-current)
|
||||
git push -u origin $BRANCH_NAME
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ 推送失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✅ 提交成功！"
|
||||
echo "📌 分支: $BRANCH_NAME"
|
||||
echo "📝 提交信息: $1"
|
||||
echo "🔗 请创建 Pull Request: https://github.com/elysia-best/apm-app-store/compare/main...$BRANCH_NAME"
|
||||
```
|
||||
|
||||
使用方法：
|
||||
|
||||
```bash
|
||||
# 给脚本添加执行权限
|
||||
chmod +x scripts/commit.sh
|
||||
|
||||
# 使用脚本提交
|
||||
./scripts/commit.sh "feat(search): add advanced search filters"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: ESLint 检查失败怎么办？
|
||||
|
||||
**A:**
|
||||
|
||||
1. 运行 `npm run lint:fix` 自动修复
|
||||
2. 手动修复无法自动处理的问题
|
||||
3. 如果确实需要使用 `any`，添加 `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
|
||||
|
||||
### Q: 测试失败怎么办？
|
||||
|
||||
**A:**
|
||||
|
||||
1. 查看测试失败信息
|
||||
2. 修复代码或测试
|
||||
3. 确保测试覆盖所有情况
|
||||
4. 运行 `npm run test` 重新验证
|
||||
|
||||
### Q: 构建失败怎么办？
|
||||
|
||||
**A:**
|
||||
|
||||
1. 查看 TypeScript 错误
|
||||
2. 修复类型错误
|
||||
3. 确保类型定义正确
|
||||
4. 运行 `npm run build:vite` 重新验证
|
||||
|
||||
### Q: 如何修复合并冲突？
|
||||
|
||||
**A:**
|
||||
|
||||
```bash
|
||||
# 1. 拉取最新代码
|
||||
git fetch origin
|
||||
|
||||
# 2. 合并 main 分支到你的分支
|
||||
git merge origin/main
|
||||
|
||||
# 3. 解决冲突
|
||||
# （编辑冲突文件，选择正确的代码）
|
||||
|
||||
# 4. 标记冲突已解决
|
||||
git add .
|
||||
|
||||
# 5. 提交合并
|
||||
git commit -m "merge: resolve conflicts with main" -s
|
||||
|
||||
# 6. 推送
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### Q: 如何修改已提交的代码？
|
||||
|
||||
**A:**
|
||||
|
||||
```bash
|
||||
# 1. 修改代码...
|
||||
|
||||
# 2. 添加到暂存区
|
||||
git add .
|
||||
|
||||
# 3. 提交到分支
|
||||
git commit -m "address review feedback" -s
|
||||
|
||||
# 4. 推送
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### Q: 如何撤回错误的提交？
|
||||
|
||||
**A:**
|
||||
|
||||
```bash
|
||||
# 如果还未推送
|
||||
git reset --soft HEAD~1
|
||||
# 重新提交
|
||||
git commit -m "correct message" -s
|
||||
|
||||
# 如果已推送（需要强制推送，谨慎使用）
|
||||
git reset --soft HEAD~1
|
||||
git commit -m "correct message" -s
|
||||
git push origin feature/your-feature-name --force
|
||||
```
|
||||
|
||||
**注意:** 避免在已公开的分支上使用强制推送。
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- **开发指南:** [DEVELOPMENT.md](./DEVELOPMENT.md)
|
||||
- **贡献指南:** [CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||
- **测试文档:** [TESTING.md](./TESTING.md)
|
||||
- **AI 编码指南:** [AGENTS.md](./AGENTS.md)
|
||||
- **部署文档:** [DEPLOYMENT.md](./DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
**© 2026 APM 应用商店项目**
|
||||
Reference in New Issue
Block a user