spark-store/WORKFLOW.md

标准开发流程

本文档描述在 APM 应用商店项目中完成代码开发后的标准提交流程。

📋 目录

• 开发前准备
• 代码完成后
• 提交流程
• 典型场景
• 提交流程检查清单
• 常见问题

---

开发前准备

在开始开发之前，确保你的开发环境已正确配置：

# 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️⃣ 运行代码检查

首先确保代码符合项目规范：

# 运行 ESLint 检查
npm run lint

# 如果有错误，尝试自动修复
npm run lint:fix

# 手动修复无法自动处理的问题

ESLint 错误类型：

• @typescript-eslint/no-explicit-any: 避免使用 any 类型
• @typescript-eslint/no-unused-vars: 未使用的变量
• 其他代码风格问题

2️⃣ 格式化代码

使用 Prettier 格式化代码：

npm run format

3️⃣ 运行测试

确保所有测试通过：

# 运行单元测试
npm run test

# 生成测试覆盖率报告
npm run test:coverage

# 运行 E2E 测试（如果需要）
npm run test:e2e

# 运行所有测试
npm run test:all

测试覆盖率要求：

• 语句覆盖率: ≥ 70%
• 分支覆盖率: ≥ 70%
• 函数覆盖率: ≥ 70%
• 行覆盖率: ≥ 70%

4️⃣ 构建验证

验证代码可以成功构建：

# 仅构建前端代码（快速）
npm run build:vite

如果构建失败，检查 TypeScript 错误并修复。

---

提交流程

5️⃣ 提交代码

查看变更

# 查看所有变更文件
git status

# 查看具体变更
git diff

添加文件

# 添加所有变更文件
git add .

# 或添加特定文件
git add path/to/file.ts

提交信息

遵循 Conventional Commits 规范：

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"）
• 首字母小写
• 不以句号结尾

示例：

# 新功能
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

添加签名：

# 使用 -s 添加签名
git commit -m "feat(example): add new feature" -s

# 或在 ~/.gitconfig 中配置
# [commit]
#     gpgsign = true

执行提交

git commit -m "type(scope): description" -s

6️⃣ 推送到远程仓库

# 推送当前分支
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

# 修改代码后
git add .
git commit -m "address review feedback" -s
git push origin feature/your-feature-name

9️⃣ 合并 PR

合并条件

• 至少一次审查批准
• 所有 CI 检查通过
• 无冲突
• 分支最新

合并方式

• 使用 "Squash and merge" 将提交压缩为一个
• 或使用 "Merge commit" 保留提交历史

删除分支

合并后删除你的功能分支：

# 删除本地分支
git branch -d feature/your-feature-name

# 删除远程分支
git push origin --delete feature/your-feature-name

---

典型场景

场景 1: 开发新功能

# 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

# 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: 更新文档

# 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: 重构代码

# 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）
• TypeScript 严格模式通过

测试

• 单元测试通过 (npm run test)
• 新功能包含测试
• 测试覆盖率 ≥ 70%
• E2E 测试通过（如需要，npm run test:e2e）
• 没有测试回归

文档

• 更新了相关文档（如需要）
• 更新了 CHANGELOG.md（如需要）
• API 文档更新（如需要）
• README.md 更新（如需要）

功能验证

• 本地测试通过
• 没有引入新 Bug
• 边界情况已处理
• 错误处理完善
• 性能未下降

提交信息

• 遵循 Conventional Commits 规范
• 添加了签名（-s）
• 引用相关 Issue（如适用）
• 提交信息清晰明确

---

快速提交命令

如果你想快速提交所有检查，可以使用以下命令：

# 完整流程（一行命令）
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:

#!/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"

使用方法：

# 给脚本添加执行权限
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:

# 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:

# 1. 修改代码...

# 2. 添加到暂存区
git add .

# 3. 提交到分支
git commit -m "address review feedback" -s

# 4. 推送
git push origin feature/your-feature-name

Q: 如何撤回错误的提交？

A:

# 如果还未推送
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
• 贡献指南: CONTRIBUTING.md
• 测试文档: TESTING.md
• AI 编码指南: AGENTS.md
• 部署文档: DEPLOYMENT.md

---

© 2026 APM 应用商店项目