spark-store-project/spark-store
15
0
Fork 0
mirror of https://gitee.com/spark-store-project/spark-store synced 2026-04-26 01:10:16 +08:00
Code Issues 1 Packages Projects Releases Wiki Activity

chore: add comprehensive documentation and testing infrastructure

Browse Source 
## 文档（全部中文）
- 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:
momen
2026-03-10 00:42:56 +08:00
parent 0035b3000d
commit cef68a95d9
31 changed files with 5403 additions and 424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.agents/workflows/1.md
View File

@@ -1,6 +0,0 @@
---
description: 审查
---
审查是否符合代码规范
是否有代码缺陷

139
.agents/workflows/bug-fix.md Normal file
View File

@@ -0,0 +1,139 @@
---
description: Bug 修复流程
---
## 工作流说明
此工作流指导如何修复 Bug。
## 步骤
### 1. 复现 Bug
- 根据 Issue 描述复现问题
- 记录详细的复现步骤
- 收集相关日志和错误信息
- 确认环境信息
### 2. 分析问题
- 查看相关代码
- 使用调试器定位问题
- 检查日志输出
- 识别根本原因
### 3. 创建修复分支
```bash
git checkout -b fix/your-bug-fix
```
### 4. 编写回归测试
先编写测试来复现 Bug：
```typescript
// src/__tests__/unit/bugFix.test.ts
import { describe, it, expect } from "vitest";
import { buggyFunction } from "@/modules/example";
describe("buggyFunction", () => {
it("should not crash with null input", () => {
expect(() => buggyFunction(null)).not.toThrow();
});
});
```
### 5. 修复代码
- 最小化修改
- 保持代码可读性
- 添加必要的注释
- 更新相关类型定义
### 6. 运行测试
```bash
# 确保新测试通过
npm run test
# 运行所有测试
npm run test:all
# 代码检查
npm run lint
npm run format
```
### 7. 本地验证
- 验证 Bug 已修复
- 测试相关功能
- 检查是否引入新问题
- 测试边界情况
### 8. 更新文档
- 更新 CHANGELOG.md（如果需要）
- 更新相关文档（如需要）
### 9. 提交代码
```bash
git add .
git commit -m "fix(scope): describe the bug fix" -s
git push origin fix/your-bug-fix
```
### 10. 创建 Pull Request
- 引用相关 Issue（`Fixes #123`）
- 描述修复方法
- 说明复现步骤
- 添加测试说明
### 11. 代码审查
- 响应审查意见
- 进行必要的修改
- 确保所有 CI 检查通过
### 12. 合并
- 等待审查批准
- Squash 合并到 main 分支
- 删除修复分支
## 注意事项
- ⚠️ 修复前先理解问题根源
- ⚠️ 最小化修改范围
- ⚠️ 添加回归测试防止复发
- ⚠️ 考虑向后兼容性
- ⚠️ 测试所有受影响的功能
## 常见 Bug 类型
### IPC 通信问题
- 检查事件名称是否匹配
- 检查数据格式是否正确
- 检查异步处理
### 状态管理问题
- 检查响应式依赖
- 检查状态更新时机
- 检查内存泄漏
### 类型错误
- 检查类型定义
- 检查类型断言
- 检查可选值处理
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [TESTING.md](../../TESTING.md) - 测试文档
- [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) - 问题排查

245
.agents/workflows/code-review.md Normal file
View File

@@ -0,0 +1,245 @@
---
description: 代码审查流程
---
## 工作流说明
此工作流指导如何进行代码审查。
## 审查清单
### 代码质量
- [ ] 代码遵循项目规范
- [ ] TypeScript 类型正确
- [ ] 没有 `any` 类型（除非必要）
- [ ] ESLint 和 Prettier 通过
- [ ] 代码可读性良好
### 功能实现
- [ ] 实现符合需求
- [ ] 边界情况处理
- [ ] 错误处理完善
- [ ] 没有引入新 Bug
### 测试
- [ ] 包含足够的测试
- [ ] 测试覆盖率合理
- [ ] 所有测试通过
- [ ] E2E 测试（如需要）
### 文档
- [ ] 更新了相关文档
- [ ] 代码注释充分
- [ ] API 文档（如需要）
- [ ] CHANGELOG.md（如需要）
### 安全性
- [ ] 没有安全漏洞
- [ ] 输入验证完善
- [ ] 权限检查正确
- [ ] 敏感信息保护
### 性能
- [ ] 没有明显的性能问题
- [ ] 内存使用合理
- [ ] 没有不必要的渲染
- [ ] 资源加载优化
## 审查流程
### 1. 理解变更
- 阅读 PR 描述
- 查看 Issue 链接
- 理解变更目的
- 检查变更范围
### 2. 代码审查
**主进程代码:**
```bash
# 检查类型安全
npx tsc --noEmit
# 检查代码质量
npm run lint
```
**渲染进程代码:**
- 组件结构
- 状态管理
- 事件处理
- 样式实现
### 3. 测试验证
```bash
# 运行单元测试
npm run test
# 运行 E2E 测试
npm run test:e2e
# 检查覆盖率
npm run test:coverage
```
### 4. 提供反馈
**正面反馈:**
- 好的实现
- 优秀的代码
- 有价值的贡献
**建设性反馈:**
- 指出问题
- 提出建议
- 解释原因
**反馈格式:**
````markdown
### 问题
**位置:** `src/components/AppCard.vue:45`
**描述:** 这里缺少错误处理，可能导致应用崩溃。
**建议:**
```typescript
try {
await installPackage();
} catch (error) {
console.error("Install failed:", error);
showError(error.message);
}
```
````
````
### 5. 批准或要求修改
**批准条件:**
- 所有审查项目通过
- 所有测试通过
- CI 检查通过
- 没有阻塞问题
**要求修改:**
- 指出必须修复的问题
- 给出明确的修改建议
- 等待作者响应
## 审查原则
### 及时性
- 尽快响应 PR
- 设定响应时间预期
- 优先处理紧急 PR
### 建设性
- 提供具体的反馈
- 给出改进建议
- 解释审查理由
### 尊重
- 尊重作者的贡献
- 使用礼貌的语言
- 认可好的实现
### 一致性
- 遵循项目规范
- 保持审查标准一致
- 参考之前类似 PR
## 常见问题
### 类型安全问题
**问题:** 使用了 `any` 类型
**建议:**
```typescript
// ❌ 避免
const data: any = response;
// ✅ 推荐
interface ResponseData {
id: string;
name: string;
}
const data: ResponseData = response;
````
### 代码重复
**问题:** 代码重复
**建议:**
```typescript
// 提取公共函数
function formatSize(size: number): string {
return size > 1024 ? `${size / 1024} MB` : `${size} KB`;
}
```
### 错误处理
**问题:** 缺少错误处理
**建议:**
```typescript
async function loadApps() {
try {
const response = await axios.get("/api/apps");
return response.data;
} catch (error) {
logger.error({ err: error }, "Failed to load apps");
throw error;
}
}
```
## 审查后操作
### 批准
- 点击 "Approve review"
- 添加评论（可选）
- 等待合并
### 要求修改
- 选择 "Request changes"
- 提供详细反馈
- 等待作者更新
### 评论
- 选择 "Comment"
- 提供建议或问题
- 不阻止合并
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [AGENTS.md](../../AGENTS.md) - AI 编码指南

264
.agents/workflows/documentation.md Normal file
View File

@@ -0,0 +1,264 @@
---
description: 文档更新流程
---
## 工作流说明
此工作流指导如何更新项目文档。
## 步骤
### 1. 确定需要更新的文档
根据变更内容确定需要更新的文档：
- README.md - 主要说明
- DEVELOPMENT.md - 开发指南
- CONTRIBUTING.md - 贡献指南
- TESTING.md - 测试文档
- DEPLOYMENT.md - 部署文档
- TROUBLESHOOTING.md - 问题排查
- FAQ.md - 常见问题
- AGENTS.md - AI 编码指南
- CHANGELOG.md - 变更日志
### 2. 创建文档分支
```bash
git checkout -b docs/update-documentation
```
### 3. 更新文档
#### README.md
添加新功能说明：
```markdown
## 新功能
### 应用更新
现在支持一键更新所有可更新的应用。
### 下载管理
改进了下载队列管理，支持暂停和继续。
```
#### DEVELOPMENT.md
添加开发指南：
```markdown
## 新功能开发
### 添加新功能步骤
1. 理解需求
2. 设计方案
3. 实现功能
4. 编写测试
5. 提交 PR
```
#### CONTRIBUTING.md
更新贡献指南：
```markdown
### 新功能贡献
- 遵循现有代码风格
- 编写充分的测试
- 更新相关文档
```
#### TESTING.md
添加测试示例：
```typescript
describe("New Feature", () => {
it("should work correctly", () => {
// 测试代码
});
});
```
#### CHANGELOG.md
添加变更记录：
```markdown
## [4.10.0](https://github.com/elysia-best/apm-app-store/compare/v4.9.9...v4.10.0) (2026-03-10)
### Features
- feat(download): add pause and resume for downloads
- feat(update): add batch update for apps
### Bug Fixes
- fix(ui): correct dark mode toggle persistence
```
### 4. 检查文档质量
- [ ] 语法正确
- [ ] 格式统一
- [ ] 链接有效
- [ ] 内容准确
- [ ] 示例可运行
### 5. 运行文档测试
```bash
# 如果有文档测试
npm run test:docs
# 检查链接
npm run check-links
```
### 6. 本地预览
使用 Markdown 预览工具查看效果。
### 7. 提交文档
```bash
git add .
git commit -m "docs: update documentation for new features" -s
git push origin docs/update-documentation
```
### 8. 创建 Pull Request
- 说明更新的内容
- 提供预览截图（如需要）
- 引用相关 Issue
### 9. 代码审查
- 响应审查意见
- 确保文档质量
- 合并到 main 分支
## 文档编写规范
### 格式规范
- 使用 Markdown
- 保持一致的标题层级
- 使用代码块展示示例
- 使用表格对比选项
### 语言规范
- 使用简洁清晰的语言
- 避免技术术语（或解释）
- 保持中英文术语一致
- 使用被动语态
### 示例规范
```typescript
// 好的示例
import { ref } from "vue";
const count = ref(0);
function increment() {
count.value++;
}
```
### 链接规范
```markdown
- 内部链接: [文档名](./document.md)
- 外部链接: [Vue 文档](https://vuejs.org/)
- 锚点链接: [章节](#section-name)
```
## 文档模板
### 新功能文档
````markdown
## 功能名称
### 描述
简要描述功能
### 使用方法
```typescript
// 示例代码
```
````
### 配置选项
| 选项 | 类型 | 默认值 | 说明 |
| ------ | ------ | --------- | -------- |
| option | string | 'default' | 选项说明 |
### 注意事项
- 注意事项 1
- 注意事项 2
````
### API 文档
```markdown
## API 函数名
### 签名
```typescript
function functionName(param1: Type1, param2: Type2): ReturnType
````
### 参数
| 参数 | 类型 | 必填 | 说明 |
| ------ | ----- | ---- | -------- |
| param1 | Type1 | 是 | 参数说明 |
| param2 | Type2 | 否 | 参数说明 |
### 返回值
| 类型 | 说明 |
| ---------- | ---------- |
| ReturnType | 返回值说明 |
### 示例
```typescript
const result = functionName(arg1, arg2);
```
### 错误
抛出 `Error` 异常的情况说明。
```
## 注意事项
- ⚠️ 保持文档与代码同步
- ⚠️ 更新示例代码
- ⚠️ 检查链接有效性
- ⚠️ 使用统一的格式
- ⚠️ 提供清晰的说明
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [AGENTS.md](../../AGENTS.md) - AI 编码指南
```

135
.agents/workflows/feature-development.md Normal file
View File

@@ -0,0 +1,135 @@
---
description: 新功能开发流程
---
## 工作流说明
此工作流指导如何开发新功能。
## 步骤
### 1. 理解需求
- 阅读 Issue 描述
- 确认功能范围
- 识别依赖关系
- 设计 API 和数据结构
### 2. 设计方案
- 设计 UI/UX（如需要）
- 设计数据流
- 确定 IPC 通信（如需要）
- 编写技术方案文档（可选）
### 3. 创建功能分支
```bash
git checkout -b feature/your-feature-name
```
### 4. 更新类型定义
在 `src/global/typedefinition.ts` 中添加新的类型定义：
```typescript
export interface NewFeatureData {
id: string;
name: string;
// ...其他字段
}
```
### 5. 编写测试
先编写测试，遵循 TDD 原则：
```typescript
// src/__tests__/unit/newFeature.test.ts
import { describe, it, expect } from "vitest";
import { newFunction } from "@/modules/newFeature";
describe("newFunction", () => {
it("should work correctly", () => {
const result = newFunction(input);
expect(result).toBe(expected);
});
});
```
### 6. 实现功能
按照以下顺序实现：
- 后端逻辑（Electron 主进程）
- 前端逻辑（Vue 组件）
- IPC 通信（如需要）
- 样式和布局
### 7. 运行测试
```bash
# 单元测试
npm run test
# E2E 测试
npm run test:e2e
# 代码检查
npm run lint
npm run format
```
### 8. 本地测试
- 测试所有功能场景
- 测试边界情况
- 测试错误处理
- 检查性能影响
### 9. 更新文档
- 更新 API 文档（如需要）
- 更新用户文档（如需要）
- 更新 CHANGELOG.md
### 10. 提交代码
```bash
git add .
git commit -m "feat(scope): add new feature" -s
git push origin feature/your-feature-name
```
### 11. 创建 Pull Request
- 使用 PR 模板
- 引用相关 Issue
- 添加测试说明
- 添加截图/录屏（UI 变更）
### 12. 代码审查
- 响应审查意见
- 进行必要的修改
- 确保所有 CI 检查通过
### 13. 合并
- 等待审查批准
- Squash 合并到 main 分支
- 删除功能分支
## 注意事项
- ⚠️ 保持 PR 小而聚焦（建议 < 500 行）
- ⚠️ 确保 TypeScript 严格模式通过
- ⚠️ 不引入 `any` 类型（必要时使用 `eslint-disable`）
- ⚠️ 所有新功能必须有测试
- ⚠️ 遵循代码规范
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [TESTING.md](../../TESTING.md) - 测试文档

333
.agents/workflows/performance-optimization.md Normal file
View File

@@ -0,0 +1,333 @@
---
description: 性能优化流程
---
## 工作流说明
此工作流指导如何优化应用性能。
## 步骤
### 1. 识别性能问题
使用工具分析性能：
- Chrome DevTools Performance
- Vue DevTools
- Vite Build Analysis
- 内存分析工具
### 2. 分析瓶颈
确定性能瓶颈：
- 渲染性能
- 网络请求
- 内存使用
- CPU 使用
- 磁盘 I/O
### 3. 创建优化分支
```bash
git checkout -b perf/optimize-performance
```
### 4. 添加性能测试
```typescript
// src/__tests__/perf/performance.test.ts
import { describe, it, expect } from "vitest";
import { heavyFunction } from "@/modules/example";
describe("heavyFunction", () => {
it("should complete within 100ms", () => {
const start = performance.now();
heavyFunction();
const duration = performance.now() - start;
expect(duration).toBeLessThan(100);
});
});
```
### 5. 实施优化
#### 渲染性能优化
```typescript
// 使用 computed 缓存计算结果
const filteredApps = computed(() => {
return apps.value.filter(app => app.category === selectedCategory);
});
// 使用 v-memo 优化列表渲染
<template>
<div v-for="app in apps" :key="app.pkgname" v-memo="[app.id]">
{{ app.name }}
</div>
</template>
// 防抖和节流
import { debounce } from 'lodash-es';
const debouncedSearch = debounce((query: string) => {
searchApps(query);
}, 300);
```
#### 网络请求优化
```typescript
// 使用缓存
const appCache = new Map<string, App[]>();
async function fetchApps(category: string): Promise<App[]> {
if (appCache.has(category)) {
return appCache.get(category)!;
}
const apps = await axios.get(`/api/apps/${category}`);
appCache.set(category, apps.data);
return apps.data;
}
// 并发请求
const [apps1, apps2] = await Promise.all([
fetchApps("category1"),
fetchApps("category2"),
]);
```
#### 内存优化
```typescript
// 及时清理事件监听
onMounted(() => {
window.addEventListener("resize", handleResize);
});
onUnmounted(() => {
window.removeEventListener("resize", handleResize);
});
// 避免内存泄漏
let timer: number;
function startTimer() {
clearInterval(timer);
timer = setInterval(() => {
// 定时任务
}, 1000);
}
onUnmounted(() => {
clearInterval(timer);
});
```
#### 代码分割
```typescript
// 动态导入组件
const AppDetailModal = defineAsyncComponent(
() => import("@/components/AppDetailModal.vue"),
);
// 路由懒加载
const routes = [
{
path: "/app/:id",
component: () => import("@/views/AppDetail.vue"),
},
];
```
### 6. 测试性能
```bash
# 运行性能测试
npm run test:perf
# 使用 DevTools 分析
# 1. 打开 DevTools
# 2. 切换到 Performance 标签
# 3. 点击 Record
# 4. 执行操作
# 5. 停止录制并分析
```
### 7. 对比优化效果
记录优化前后的数据：
- 渲染时间
- 内存使用
- 网络请求数
- 应用启动时间
### 8. 验证功能
```bash
# 确保功能正常
npm run test
# 手动测试主要流程
```
### 9. 代码审查
检查优化是否：
- 提升了性能
- 没有破坏功能
- 代码可读
- 易于维护
### 10. 更新文档
- 记录优化内容
- 更新性能指标
- 添加优化说明
### 11. 提交代码
```bash
git add .
git commit -m "perf(scope): optimize performance" -s
git push origin perf/optimize-performance
```
### 12. 创建 Pull Request
- 说明优化内容
- 提供性能对比
- 展示优化效果
## 性能优化清单
### 渲染性能
- [ ] 使用 computed 缓存
- [ ] 使用 v-memo 优化
- [ ] 避免不必要的重新渲染
- [ ] 使用虚拟滚动（大数据集）
- [ ] 图片懒加载
### 网络性能
- [ ] 减少请求数量
- [ ] 使用缓存
- [ ] 压缩资源
- [ ] 使用 CDN
- [ ] 并发请求
### 内存性能
- [ ] 清理事件监听
- [ ] 避免内存泄漏
- [ ] 释放不再使用的资源
- [ ] 使用对象池（如需要）
- [ ] 优化数据结构
### 构建性能
- [ ] 代码分割
- [ ] Tree shaking
- [ ] 压缩代码
- [ ] 优化依赖
- [ ] 使用缓存
## 性能监控
### 关键指标
- **FCP (First Contentful Paint):** < 1.5s
- **LCP (Largest Contentful Paint):** < 2.5s
- **TTI (Time to Interactive):** < 3.5s
- **CLS (Cumulative Layout Shift):** < 0.1
- **FID (First Input Delay):** < 100ms
### 监控工具
```typescript
// 使用 Performance API
const perfData = performance.getEntriesByType("navigation")[0];
console.log("Page Load Time:", perfData.loadEventEnd - perfData.fetchStart);
// 使用 Vue DevTools
// 监控组件渲染时间
```
## 常见性能问题
### 1. 大列表渲染
**问题:** 渲染大量数据导致卡顿
**解决方案:**
```vue
<template>
<RecycleScroller :items="largeList" :item-size="50" key-field="id">
<template #default="{ item }">
<div>{{ item.name }}</div>
</template>
</RecycleScroller>
</template>
```
### 2. 频繁的 DOM 更新
**问题:** 频繁更新 DOM 导致性能下降
**解决方案:**
```typescript
// 使用 requestAnimationFrame
function animate() {
updatePosition();
requestAnimationFrame(animate);
}
```
### 3. 内存泄漏
**问题:** 内存持续增长
**解决方案:**
```typescript
// 及时清理
onUnmounted(() => {
clearInterval(timer);
removeEventListener("resize", handleResize);
clearTimeout(timeout);
});
```
### 4. 不必要的计算
**问题:** 重复计算相同结果
**解决方案:**
```typescript
// 使用 computed
const expensiveValue = computed(() => {
return heavyCalculation(data.value);
});
```
## 注意事项
- ⚠️ 不要过早优化
- ⚠️ 先测量再优化
- ⚠️ 保持代码可读
- ⚠️ 避免过度优化
- ⚠️ 持续监控性能
## 相关文档
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [TESTING.md](../../TESTING.md) - 测试文档
- [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) - 问题排查

284
.agents/workflows/refactoring.md Normal file
View File

@@ -0,0 +1,284 @@
---
description: 代码重构流程
---
## 工作流说明
此工作流指导如何安全地重构代码。
## 步骤
### 1. 识别重构需求
分析代码中的问题：
- 代码重复
- 复杂度过高
- 性能问题
- 可读性差
- 难以维护
### 2. 制定重构计划
- 确定重构范围
- 列出具体改进点
- 评估影响范围
- 制定测试策略
### 3. 创建重构分支
```bash
git checkout -b refactor/your-refactor
```
### 4. 编写测试
如果代码缺少测试，先添加测试：
```typescript
// src/__tests__/unit/refactorTarget.test.ts
import { describe, it, expect } from "vitest";
import { functionToRefactor } from "@/modules/example";
describe("functionToRefactor", () => {
it("should maintain existing behavior", () => {
const result = functionToRefactor(input);
expect(result).toBe(expected);
});
});
```
### 5. 逐步重构
**原则:**
- 小步迭代
- 保持测试通过
- 不改变外部行为
**示例:**
```typescript
// 重构前
function processApp(app: any) {
if (app) {
return {
name: app.name,
pkgname: app.pkgname,
version: app.version,
};
}
return null;
}
// 重构后 - 添加类型
interface App {
name: string;
pkgname: string;
version: string;
}
function processApp(app: App | null): App | null {
if (!app) return null;
return {
name: app.name,
pkgname: app.pkgname,
version: app.version,
};
}
```
### 6. 运行测试
```bash
# 每次重构后运行测试
npm run test
# 确保所有测试通过
npm run test:all
```
### 7. 性能验证
如果重构涉及性能：
```bash
# 运行性能测试
npm run test:perf
# 对比重构前后性能
```
### 8. 代码审查
自我检查：
- 代码更清晰
- 性能未下降
- 测试全部通过
- 没有引入新问题
### 9. 更新文档
- 更新相关文档
- 添加注释说明
- 更新 CHANGELOG.md
### 10. 提交代码
```bash
git add .
git commit -m "refactor(scope): describe the refactoring" -s
git push origin refactor/your-refactor
```
### 11. 创建 Pull Request
- 说明重构原因
- 展示改进效果
- 提供性能对比（如需要）
### 12. 代码审查
- 响应审查意见
- 确保所有测试通过
- 合并到 main 分支
## 重构原则
### 不改变外部行为
- 保持 API 兼容
- 保持输出一致
- 保持错误处理
### 小步迭代
- 每次只改一处
- 频繁运行测试
- 及时提交代码
### 测试驱动
- 先写测试
- 重构代码
- 确保通过
### 保持简单
- 减少复杂度
- 提高可读性
- 增强可维护性
## 常见重构模式
### 提取函数
```typescript
// 重构前
function processApps(apps: App[]) {
for (const app of apps) {
if (app.installed) {
console.log(app.name + " is installed");
}
}
}
// 重构后
function logInstalledApp(app: App) {
if (app.installed) {
console.log(`${app.name} is installed`);
}
}
function processApps(apps: App[]) {
apps.forEach(logInstalledApp);
}
```
### 提取类型
```typescript
// 重构前
function createDownload(data: any) {
return {
id: data.id,
name: data.name,
pkgname: data.pkgname,
};
}
// 重构后
interface DownloadData {
id: number;
name: string;
pkgname: string;
}
function createDownload(data: DownloadData): DownloadItem {
return {
id: data.id,
name: data.name,
pkgname: data.pkgname,
status: "queued",
progress: 0,
downloadedSize: 0,
totalSize: 0,
speed: 0,
timeRemaining: 0,
startTime: Date.now(),
logs: [],
source: "APM Store",
retry: false,
};
}
```
### 简化条件
```typescript
// 重构前
function getStatus(status: string): string {
if (status === "queued") {
return "Queued";
} else if (status === "downloading") {
return "Downloading";
} else if (status === "installing") {
return "Installing";
} else if (status === "completed") {
return "Completed";
} else if (status === "failed") {
return "Failed";
} else {
return "Unknown";
}
}
// 重构后
const statusMap: Record<string, string> = {
queued: "Queued",
downloading: "Downloading",
installing: "Installing",
completed: "Completed",
failed: "Failed",
};
function getStatus(status: string): string {
return statusMap[status] || "Unknown";
}
```
## 注意事项
- ⚠️ 不要在重构中引入新功能
- ⚠️ 不要同时重构多处
- ⚠️ 确保测试覆盖充分
- ⚠️ 保持提交历史清晰
- ⚠️ 及时回退有问题的重构
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [TESTING.md](../../TESTING.md) - 测试文档

211
.agents/workflows/release.md Normal file
View File

@@ -0,0 +1,211 @@
---
description: 发布流程
---
## 工作流说明
此工作流指导如何发布新版本。
## 步骤
### 1. 更新版本号
```bash
# 更新版本
npm version patch # 1.0.0 → 1.0.1
npm version minor # 1.0.0 → 1.1.0
npm version major # 1.0.0 → 2.0.0
# 或手动编辑 package.json
```
### 2. 更新 CHANGELOG.md
```bash
# 生成变更日志
npm run changelog
```
或手动更新：
```markdown
## [1.0.1](https://github.com/elysia-best/apm-app-store/compare/v1.0.0...v1.0.1) (2026-03-10)
### Bug Fixes
- fix(ui): correct dark mode toggle persistence (#123)
### Features
- feat(install): add retry mechanism for failed installations (#124)
```
### 3. 运行完整测试
```bash
# 运行所有测试
npm run test:all
# 运行代码检查
npm run lint
npm run format
# 构建项目
npm run build:vite
```
### 4. 提交变更
```bash
git add .
git commit -m "chore(release): bump version to x.x.x" -s
git push origin main
```
### 5. 创建 Git 标签
```bash
# 创建标签
git tag v{version}
# 推送标签
git push origin v{version}
```
### 6. 触发 CI 构建
推送标签后会自动触发 GitHub Actions 构建。
### 7. 验证构建
在 GitHub Actions 页面查看：
- 所有测试通过
- 构建成功
- 构建产物生成
### 8. 检查 Release
GitHub Actions 会自动创建 Release：
- 访问 Releases 页面
- 检查版本信息
- 确认构建产物
### 9. 发布说明
如果需要，更新 Release 说明：
- 添加主要变更
- 添加已知问题
- 添加升级说明
### 10. 通知用户
- 更新 README
- 发布公告
- 通知用户
## 发布检查清单
### 代码质量
- [ ] 所有测试通过
- [ ] 代码检查通过
- [ ] 没有已知严重 Bug
- [ ] 性能测试通过
### 文档
- [ ] CHANGELOG.md 更新
- [ ] README.md 更新（如需要）
- [ ] API 文档更新（如需要）
### 构建
- [ ] 本地构建成功
- [ ] CI 构建成功
- [ ] 构建产物正确
### 发布
- [ ] 版本号正确
- [ ] 标签已推送
- [ ] Release 已创建
- [ ] 构建产物已上传
## 版本号规范
遵循 [Semantic Versioning](https://semver.org/)：
- **MAJOR:** 不兼容的 API 变更
- **MINOR:** 向后兼容的功能新增
- **PATCH:** 向后兼容的 Bug 修复
### 示例
```
4.9.9 → 4.9.10 (PATCH: Bug 修复)
4.9.9 → 4.10.0 (MINOR: 新功能)
4.9.9 → 5.0.0 (MAJOR: 重大变更)
```
## 发布后
### 更新开发分支
```bash
git checkout develop
git merge main
git push origin develop
```
### 监控反馈
- 收集用户反馈
- 监控 Bug 报告
- 记录性能数据
### 准备下一个版本
- 创建新的 Issue
- 规划新功能
- 评估技术债务
## 回滚流程
如果发现严重问题：
### 1. 立即停止推广
- 通知用户暂停升级
- 更新下载页面
### 2. 修复问题
```bash
git checkout main
git checkout -b fix/critical-issue
# 修复问题
git push origin fix/critical-issue
```
### 3. 紧急发布
```bash
npm version patch
git tag -a v{x.x.x} -m "Hotfix: description"
git push origin v{x.x.x}
```
### 4. 通知用户
- 发布新版本
- 说明问题和修复
- 提供升级说明
## 相关文档
- [DEPLOYMENT.md](../../DEPLOYMENT.md) - 部署文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [CHANGELOG.md](../../CHANGELOG.md) - 变更日志

435
.agents/workflows/security-audit.md Normal file
View File

@@ -0,0 +1,435 @@
---
description: 安全审计流程
---
## 工作流说明
此工作流指导如何进行安全审计。
## 步骤
### 1. 确定审计范围
确定需要审计的方面：
- 代码安全
- 依赖安全
- 数据安全
- 网络安全
- 权限管理
### 2. 创建审计分支
```bash
git checkout -b security/security-audit
```
### 3. 代码安全审计
#### 检查 SQL 注入
```typescript
// ❌ 不安全
const query = `SELECT * FROM apps WHERE name = '${appName}'`;
// ✅ 安全
const query = "SELECT * FROM apps WHERE name = ?";
db.query(query, [appName]);
```
#### 检查 XSS 攻击
```typescript
// ❌ 不安全
element.innerHTML = userInput;
// ✅ 安全
element.textContent = userInput;
// 或使用 DOMPurify
import DOMPurify from "dompurify";
element.innerHTML = DOMPurify.sanitize(userInput);
```
#### 检查命令注入
```typescript
// ❌ 不安全
const cmd = `apm install ${packageName}`;
exec(cmd);
// ✅ 安全
const args = ["apm", "install", packageName];
spawn("apm", args);
```
#### 检查路径遍历
```typescript
// ❌ 不安全
const filePath = path.join(basePath, userInput);
// ✅ 安全
const safePath = path.normalize(userInput).replace(/^(\.\.(\/|\\|$))+/, "");
const filePath = path.join(basePath, safePath);
```
### 4. 依赖安全审计
```bash
# 检查依赖漏洞
npm audit
# 自动修复
npm audit fix
# 手动修复
npm audit fix --force
```
#### 检查 package.json
```json
{
"dependencies": {
"axios": "^1.13.2",
"pino": "^10.3.0"
},
"devDependencies": {
"@playwright/test": "^1.40.0"
}
}
```
### 5. 数据安全审计
#### 检查敏感信息
```typescript
// ❌ 不安全 - 硬编码密钥
const apiKey = "sk-1234567890";
// ✅ 安全 - 使用环境变量
const apiKey = process.env.API_KEY;
// ❌ 不安全 - 记录敏感信息
logger.info({ password: user.password }, "User logged in");
// ✅ 安全 - 不记录敏感信息
logger.info({ userId: user.id }, "User logged in");
```
#### 检查数据加密
```typescript
// 加密敏感数据
import crypto from "crypto";
function encrypt(text: string, key: string): string {
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
let encrypted = cipher.update(text, "utf8", "hex");
encrypted += cipher.final("hex");
return iv.toString("hex") + ":" + encrypted;
}
```
### 6. 网络安全审计
#### 检查 HTTPS
```typescript
// ❌ 不安全 - HTTP
const baseURL = "http://api.example.com";
// ✅ 安全 - HTTPS
const baseURL = "https://api.example.com";
```
#### 检查证书验证
```typescript
// 配置 Axios 验证证书
const axiosInstance = axios.create({
httpsAgent: new https.Agent({
rejectUnauthorized: true,
}),
});
```
#### 检查 CORS
```typescript
// 配置 CORS
app.use(
cors({
origin: "https://yourdomain.com",
credentials: true,
}),
);
```
### 7. 权限管理审计
#### 检查权限提升
```typescript
// 检查 pkexec 可用性
const checkSuperUserCommand = async (): Promise<string> => {
if (process.getuid && process.getuid() !== 0) {
const { stdout } = await execAsync("which /usr/bin/pkexec");
return stdout.trim().length > 0 ? "/usr/bin/pkexec" : "";
}
return "";
};
```
#### 检查上下文隔离
```typescript
// electron/preload/index.ts
// ✅ 安全 - 启用上下文隔离
contextBridge.exposeInMainWorld("ipcRenderer", {
send: (...args) => ipcRenderer.send(...args),
on: (...args) => ipcRenderer.on(...args),
invoke: (...args) => ipcRenderer.invoke(...args),
});
// ❌ 不安全 - 禁用上下文隔离
contextIsolation: false;
```
### 8. 运行安全工具
```bash
# 使用 Snyk 扫描
npx snyk test
# 使用 npm audit
npm audit
# 使用 ESLint 安全规则
npm run lint
```
### 9. 修复安全问题
根据审计结果修复发现的问题：
```typescript
// 修复示例
function validateInput(input: string): boolean {
// 验证输入
const regex = /^[a-zA-Z0-9-_]+$/;
return regex.test(input);
}
function sanitizeInput(input: string): string {
// 清理输入
return input.trim().replace(/[<>]/g, "");
}
```
### 10. 安全测试
```typescript
// src/__tests__/security/security.test.ts
import { describe, it, expect } from "vitest";
import { validateInput, sanitizeInput } from "@/modules/security";
describe("Security", () => {
describe("validateInput", () => {
it("should reject malicious input", () => {
expect(validateInput('<script>alert("xss")</script>')).toBe(false);
});
it("should accept valid input", () => {
expect(validateInput("valid-app-name")).toBe(true);
});
});
describe("sanitizeInput", () => {
it("should remove dangerous characters", () => {
expect(sanitizeInput("<script>app</script>")).toBe("scriptapp/script");
});
});
});
```
### 11. 更新文档
- 记录安全问题
- 说明修复方法
- 更新安全指南
### 12. 提交代码
```bash
git add .
git commit -m "security: fix security vulnerabilities" -s
git push origin security/security-audit
```
### 13. 创建 Pull Request
- 说明安全问题
- 展示修复方法
- 提供安全测试结果
## 安全检查清单
### 代码安全
- [ ] 输入验证
- [ ] 输出编码
- [ ] 参数化查询
- [ ] 错误处理
- [ ] 日志安全
### 依赖安全
- [ ] 定期更新依赖
- [ ] 使用 `npm audit`
- [ ] 检查已知漏洞
- [ ] 使用可信源
### 数据安全
- [ ] 敏感数据加密
- [ ] 不记录敏感信息
- [ ] 使用环境变量
- [ ] 安全存储
### 网络安全
- [ ] 使用 HTTPS
- [ ] 验证证书
- [ ] 配置 CORS
- [ ] 防止 CSRF
### 权限管理
- [ ] 最小权限原则
- [ ] 上下文隔离
- [ ] 权限检查
- [ ] 审计日志
## 常见安全问题
### 1. XSS 攻击
**问题:** 用户输入包含恶意脚本
**解决方案:**
```typescript
import DOMPurify from "dompurify";
function sanitizeHTML(html: string): string {
return DOMPurify.sanitize(html);
}
```
### 2. SQL 注入
**问题:** 恶意 SQL 代码注入
**解决方案:**
```typescript
// 使用参数化查询
db.query("SELECT * FROM apps WHERE name = ?", [appName]);
```
### 3. 命令注入
**问题:** 恶意命令注入
**解决方案:**
```typescript
// 使用 spawn 而非 exec
const args = ["apm", "install", packageName];
spawn("apm", args);
```
### 4. 路径遍历
**问题:** 访问未授权文件
**解决方案:**
```typescript
// 验证路径
const safePath = path.normalize(userPath).replace(/^(\.\.(\/|\\|$))+/, "");
```
### 5. 敏感信息泄露
**问题:** 日志中包含敏感信息
**解决方案:**
```typescript
// 不记录敏感信息
logger.info({ userId: user.id }, "User logged in");
```
## 安全最佳实践
### 1. 最小权限原则
只授予必要的权限，避免过度授权。
### 2. 深度防御
多层安全防护，不依赖单一安全措施。
### 3. 输入验证
验证所有输入，包括用户输入和 API 响应。
### 4. 输出编码
对输出进行编码，防止 XSS 攻击。
### 5. 定期审计
定期进行安全审计，及时发现和修复问题。
### 6. 安全更新
及时更新依赖和系统，修复已知漏洞。
## 安全工具
### 静态分析
- ESLint
- TypeScript
- SonarQube
### 动态分析
- OWASP ZAP
- Burp Suite
- Snyk
### 依赖扫描
- npm audit
- Snyk
- Dependabot
## 注意事项
- ⚠️ 不要忽视安全问题
- ⚠️ 及时修复漏洞
- ⚠️ 定期更新依赖
- ⚠️ 保持安全意识
- ⚠️ 遵循安全最佳实践
## 相关文档
- [CONTRIBUTING.md](../../CONTRIBUTING.md) - 贡献指南
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档
- [SECURITY.md](../../SECURITY.md) - 安全政策

108
.agents/workflows/testing.md Normal file
View File

@@ -0,0 +1,108 @@
---
description: 测试编写流程
---
## 工作流说明
此工作流指导如何为新功能或 Bug 修复编写测试。
## 步骤
### 1. 确定测试范围
分析需要测试的功能点：
- 单元测试：测试独立函数/组件
- 集成测试：测试模块间交互
- E2E 测试：测试完整用户流程
### 2. 编写单元测试（Vitest）
在 `src/__tests__/unit/` 目录下创建测试文件：
```typescript
import { describe, it, expect } from "vitest";
import { someFunction } from "@/modules/example";
describe("someFunction", () => {
it("should return expected result", () => {
const result = someFunction(input);
expect(result).toBe(expected);
});
});
```
### 3. 编写组件测试
```typescript
import { describe, it, expect } from "vitest";
import { mount } from "@vue/test-utils";
import AppCard from "@/components/AppCard.vue";
describe("AppCard", () => {
it("should render app name", () => {
const wrapper = mount(AppCard, {
props: {
app: {
name: "Test App",
pkgname: "test-app",
},
},
});
expect(wrapper.text()).toContain("Test App");
});
});
```
### 4. 编写 E2E 测试（Playwright）
在 `e2e/` 目录下创建测试文件：
```typescript
import { test, expect } from "@playwright/test";
test("install app from store", async ({ page }) => {
await page.goto("http://localhost:3344");
await page.click("text=Test App");
await page.click('button:has-text("安装")');
await expect(page.locator(".install-progress")).toBeVisible();
});
```
### 5. 运行测试
```bash
# 运行单元测试
npm run test
# 运行测试并监听
npm run test:watch
# 运行 E2E 测试
npm run test:e2e
# 生成覆盖率报告
npm run test:coverage
```
### 6. 确保测试通过
- 所有单元测试必须通过
- E2E 测试覆盖主要用户流程
- 测试覆盖率不低于 70%
### 7. 提交代码
测试通过后，提交代码并创建 PR。
## 注意事项
- ⚠️ 不要测试第三方库的功能
- ⚠️ 保持测试独立性和可重复性
- ⚠️ 使用有意义的测试名称
- ⚠️ Mock 外部依赖（APM 命令、API 调用）
## 相关文档
- [TESTING.md](../../TESTING.md) - 测试框架和规范
- [DEVELOPMENT.md](../../DEVELOPMENT.md) - 开发文档

6
.agents/workflows/代码审查.md
View File

@@ -1,6 +0,0 @@
---
description: 审查
---
审查是否符合代码规范
是否有代码缺陷

55
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -1,11 +1,52 @@
--- ---
name: Bug 报告
name: 🐞 Bug report about: 创建一个 Bug 报告以帮助我们改进
about: Create a report to help us improve title: "[Bug] "
title: "[Bug] the title of bug report"
labels: bug labels: bug
assignees: '' assignees: ""
--- ---
#### Describe the bug ## 描述
清晰简洁地描述这个 Bug 是什么。
## 复现步骤
1. 打开 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误
## 期望行为
清晰简洁地描述你期望发生什么。
## 实际行为
清晰简洁地描述实际发生了什么。
## 截图
如果适用，添加截图以帮助解释你的问题。
## 环境信息
**操作系统:** [例如: Ubuntu 22.04]
**APM 版本:** [例如: 1.0.0]
**应用商店版本:** [例如: 4.9.9]
**桌面环境:** [例如: GNOME, KDE]
## 日志
如果相关，粘贴日志到以下区域（使用代码块）：
```
粘贴日志内容
```
## 额外上下文
添加任何其他关于问题的上下文信息。

27
.github/ISSUE_TEMPLATE/help_wanted.md vendored
View File

@@ -1,10 +1,23 @@
--- ---
name: 🥺 Help wanted name: 功能请求 / 帮助请求
about: Confuse about the use of electron-vue-vite about: 为这个项目建议一个新想法
title: "[Help] the title of help wanted report" title: "[Feature] "
labels: help wanted labels: enhancement
assignees: '' assignees: ""
--- ---
#### Describe the problem you confuse ## 你的功能请求是否与问题有关？
清晰简洁地描述问题。例如：我在 [...] 时总是感到沮丧
## 你想要的解决方案是什么？
清晰简洁地描述你想要发生什么。
## 你考虑过哪些替代方案？
清晰简洁地描述你考虑过的任何替代解决方案或功能。
## 额外上下文
添加任何其他关于功能请求的上下文或截图。

27
.github/workflows/build.yml vendored
View File

@@ -15,6 +15,7 @@ on:
- ".gitignore" - ".gitignore"
- ".github/**" - ".github/**"
- "!.github/workflows/build.yml" - "!.github/workflows/build.yml"
- "!.github/workflows/test.yml"
pull_request: pull_request:
branches: [main] branches: [main]
paths-ignore: paths-ignore:
@@ -32,7 +33,28 @@ permissions:
contents: write contents: write
jobs: jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm run test
- name: Run lint
run: npm run lint
build: build:
needs: test
runs-on: ${{ matrix.os }} runs-on: ${{ matrix.os }}
container: ${{ matrix.docker_image }} container: ${{ matrix.docker_image }}
@@ -46,7 +68,6 @@ jobs:
docker_image: "debian:12" docker_image: "debian:12"
- package: rpm - package: rpm
docker_image: "almalinux:8" docker_image: "almalinux:8"
steps: steps:
- name: Install Build Dependencies - name: Install Build Dependencies
@@ -71,7 +92,7 @@ jobs:
node-version: 20 node-version: 20
- name: Install Dependencies - name: Install Dependencies
run: | run: |
npm install npm install
- name: Download host-spawn - name: Download host-spawn
@@ -119,4 +140,4 @@ jobs:
files: | files: |
artifacts/**/*.deb artifacts/**/*.deb
artifacts/**/*.rpm artifacts/**/*.rpm
generate_release_notes: true generate_release_notes: true

83
.github/workflows/test.yml vendored Normal file
View File

@@ -0,0 +1,83 @@
name: Test
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
jobs:
unit-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Run unit tests
run: npm run test -- --coverage
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v4
with:
files: ./coverage/lcov.info
flags: unittests
name: codecov-umbrella
e2e-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Install Playwright Browsers
run: npx playwright install --with-deps chromium
- name: Run E2E tests
run: npm run test:e2e
- name: Upload test results
if: always()
uses: actions/upload-artifact@v6
with:
name: playwright-report
path: playwright-report/
retention-days: 30
lint:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Run ESLint
run: npm run lint
- name: Check formatting
run: npm run format -- --check

9
.gitignore vendored
View File

@@ -14,6 +14,15 @@ dist-electron
release release
*.local *.local
# Test coverage
coverage
.nyc_output
# Playwright
test-results
playwright-report
playwright/.cache
# Editor directories and files # Editor directories and files
.vscode/.debug.env .vscode/.debug.env
.idea .idea

856
AGENTS.md
View File

File diff suppressed because it is too large Load Diff

247
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,247 @@
# 贡献指南
感谢您对 APM 应用商店项目的关注！我们欢迎任何形式的贡献。
## 📋 目录
- [行为准则](#行为准则)
- [如何贡献](#如何贡献)
- [开发流程](#开发流程)
- [代码规范](#代码规范)
- [提交信息规范](#提交信息规范)
- [Pull Request 流程](#pull-request-流程)
- [问题报告](#问题报告)
## 行为准则
- 尊重所有贡献者
- 接受建设性批评
- 专注于对项目最有利的事情
- 对社区表现出同理心
## 如何贡献
### 报告 Bug
1. 使用 [Bug 报告模板](.github/ISSUE_TEMPLATE/bug_report.md)
2. 搜索现有 Issue，避免重复
3. 提供清晰的重现步骤
4. 包含相关日志和截图
### 建议新功能
1. 使用 [功能请求模板](.github/ISSUE_TEMPLATE/help_wanted.md)
2. 解释使用场景和需求
3. 考虑是否值得投入开发资源
4. 愿意帮助实现吗？
### 提交代码
1. Fork 项目并创建分支
2. 编写代码和测试
3. 确保所有测试通过
4. 提交 Pull Request
### 改进文档
- 修正错误或不清晰之处
- 添加示例和教程
- 翻译文档
- 提出文档改进建议
## 开发流程
### 环境搭建
```bash
# 克隆仓库
git clone https://github.com/elysia-best/apm-app-store.git
cd apm-app-store
# 安装依赖
npm install
# 启动开发服务器
npm run dev
```
### 创建分支
```bash
# 功能分支
git checkout -b feature/your-feature-name
# Bug 修复分支
git checkout -b fix/your-bug-fix
```
### 本地开发
1. 遵循 [代码规范](#代码规范)
2. 编写 [单元测试](TESTING.md)
3. 运行 `npm run lint` 和 `npm run format`
4. 运行 `npm run test` 确保测试通过
### 代码审查
- 保持 PR 小而聚焦
- 添加清晰的描述
- 引用相关的 Issue
- 回应审查意见
## 代码规范
### TypeScript
- 使用严格模式 (`strict: true`)
- 避免使用 `any` 类型（必要时使用 `eslint-disable` 注释）
- 使用显式类型注解
- 优先使用 `interface` 而非 `type`
### Vue 3
- 使用 Composition API 和 `<script setup>`
- 使用 `ref` 和 `computed` 管理状态
- 遵循 Props 和 Events 模式
- 组件名使用 PascalCase
### 样式（Tailwind CSS）
- 优先使用 Tailwind 工具类
- 支持暗色模式（`dark:` 前缀）
- 响应式设计（`md:`, `lg:` 前缀）
### 命名约定
- **组件:** PascalCase (`AppCard.vue`)
- **函数:** camelCase (`handleInstall`)
- **常量:** UPPER_SNAKE_CASE (`SHELL_CALLER_PATH`)
- **文件:** kebab-case (`install-manager.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
feat(install): add retry mechanism for failed installations
fix(ui): correct dark mode toggle persistence
refactor(ipc): simplify install manager event handling
docs(readme): update build instructions
test(download): add unit tests for download queue
```
### 签名（可选）
添加签名以遵守 DCO（Developer Certificate of Origin）：
```bash
git commit -m "feat(example): add new feature" -s
```
或在 `~/.gitconfig` 中配置：
```ini
[commit]
gpgsign = true
```
## Pull Request 流程
### PR 前检查
- [ ] 代码通过 `npm run lint`
- [ ] 代码通过 `npm run format`
- [ ] 所有测试通过 (`npm run test`)
- [ ] 新功能包含测试
- [ ] 文档已更新（如需要）
### PR 描述
使用 [PR 模板](.github/PULL_REQUEST_TEMPLATE.md)，包括：
1. **变更类型:** feat / fix / refactor 等
2. **变更描述:** 清晰说明做了什么
3. **相关 Issue:** 引用 `#123`
4. **测试说明:** 如何测试这些变更
5. **截图/录屏:** UI 变更需要
6. **检查清单:** 完成上述 PR 前检查
### 审查流程
1. 至少一位维护者审查通过
2. 解决所有审查意见
3. 确保所有 CI 检查通过
4. Squash 并合并到 main 分支
### 合并要求
- CI 检查全部通过
- 至少一次审查批准
- 无冲突
- 分支最新
## 问题报告
### Bug 报告
使用 [Bug 报告模板](.github/ISSUE_TEMPLATE/bug_report.md)，包含：
- 描述
- 复现步骤
- 期望行为
- 实际行为
- 环境信息
- 截图/日志
### 功能请求
使用 [功能请求模板](.github/ISSUE_TEMPLATE/help_wanted.md)，包含：
- 问题描述
- 期望的解决方案
- 替代方案
- 额外上下文
---
**© 2026 APM 应用商店项目**

156
DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,156 @@
# 部署文档
## 📋 目录
- [构建配置](#构建配置)
- [打包流程](#打包流程)
- [发布流程](#发布流程)
- [CI/CD 工作流](#cicd-工作流)
- [版本管理](#版本管理)
## 构建配置
### electron-builder.yml
主要配置项：
- **appId:** `store.spark-app.apm`
- **productName:** `spark-store`
- **打包格式:** deb, rpm, AppImage
- **输出目录:** `release/${version}`
### 环境变量
| 变量 | 说明 |
| --------------------- | ------------------------ |
| `GITHUB_TOKEN` | GitHub Token（用于发布） |
| `VITE_DEV_SERVER_URL` | 开发服务器地址 |
## 打包流程
### 本地构建
```bash
# 构建所有格式
npm run build
# 仅构建 deb
npm run build:deb
# 仅构建 rpm
npm run build:rpm
# 仅构建前端（不打包）
npm run build:vite
```
### 构建产物
构建完成后，产物位于：
```
release/
└── {version}/
├── spark-store_{version}_linux_amd64.deb
├── spark-store_{version}_linux_amd64.rpm
├── spark-store_{version}_linux_arm64.deb
└── spark-store_{version}_linux_arm64.rpm
```
## 发布流程
### 1. 更新版本号
```bash
# 更新 package.json 中的版本
npm version patch # 1.0.0 → 1.0.1
npm version minor # 1.0.0 → 1.1.0
npm version major # 1.0.0 → 2.0.0
```
### 2. 更新 CHANGELOG.md
```bash
# 生成变更日志
npm run changelog
```
### 3. 提交并推送
```bash
git add .
git commit -m "chore(release): bump version to x.x.x" -s
git push origin main
```
### 4. 创建 Git 标签
```bash
git tag v{version}
git push origin v{version}
```
### 5. 触发 CI 构建
推送标签后会自动触发 GitHub Actions 构建。
### 6. 检查构建结果
在 GitHub Actions 页面查看构建状态。
### 7. 发布到 GitHub Release
构建成功后，GitHub Actions 会自动创建 Release 并上传构建产物。
## CI/CD 工作流
### test.yml
每次推送或 PR 时运行：
- 单元测试
- E2E 测试
- Lint 检查
### build.yml
推送到 main 分支或标签时运行：
- 运行测试（前置依赖）
- 构建 deb 和 rpm 包
- 支持 x64 和 arm64 架构
- 标签推送时自动创建 Release
## 版本管理
### 语义化版本
遵循 [Semantic Versioning](https://semver.org/)：
- **MAJOR:** 不兼容的 API 变更
- **MINOR:** 向后兼容的功能新增
- **PATCH:** 向后兼容的 Bug 修复
### 版本号示例
```
4.9.9
│ └─ PATCH (Bug 修复)
│ └─ MINOR (新功能)
└───── MAJOR (重大变更)
```
### 发布流程检查清单
- [ ] 版本号已更新
- [ ] CHANGELOG.md 已更新
- [ ] 所有测试通过
- [ ] 代码已审查
- [ ] Lint 检查通过
- [ ] 构建成功
- [ ] Release 已创建
- [ ] 构建产物已上传
---
**© 2026 APM 应用商店项目**

380
DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,380 @@
# 开发文档
## 📋 目录
- [环境搭建](#环境搭建)
- [项目结构详解](#项目结构详解)
- [开发工作流](#开发工作流)
- [调试技巧](#调试技巧)
- [本地开发最佳实践](#本地开发最佳实践)
## 环境搭建
### 系统要求
- **Node.js:** >= 20.x
- **npm:** >= 9.x 或 pnpm >= 8.x
- **操作系统:** Linux（推荐 Ubuntu 22.04+）
- **可选:** APM 包管理器（用于测试）
### 安装依赖
```bash
# 克隆仓库
git clone https://github.com/elysia-best/apm-app-store.git
cd apm-app-store
# 安装依赖
npm install
# 或使用 pnpm
pnpm install
```
### 开发服务器启动
```bash
# 启动开发模式
npm run dev
# 应用将在以下地址启动
# Vite 开发服务器: http://127.0.0.1:3344/
# Electron 窗口将自动打开
```
### 构建项目
```bash
# 构建生产版本（deb + rpm）
npm run build
# 仅构建前端
npm run build:vite
# 仅构建 deb 包
npm run build:deb
# 仅构建 rpm 包
npm run build:rpm
```
## 项目结构详解
### Electron 主进程
**目录:** `electron/main/`
**核心文件:**
- **`index.ts`** - 主进程入口
- 创建应用窗口
- 管理 IPC 通信
- 处理生命周期事件
- **`backend/install-manager.ts`** - 安装管理器
- 管理安装任务队列
- 执行 APM 命令
- 流式输出日志
- 解析安装结果
- **`deeplink.ts`** - Deep Link 处理
- 解析 `spk://` 协议
- 路由到对应操作
### Vue 渲染进程
**目录:** `src/`
**核心模块:**
- **`App.vue`** - 根组件
- 应用状态管理
- 分类和应用加载
- 模态框协调
- Deep Link 监听
- **`components/`** - UI 组件
- `AppCard.vue` - 应用卡片
- `AppDetailModal.vue` - 应用详情
- `DownloadQueue.vue` - 下载队列
- 其他 11 个组件
- **`global/`** - 全局状态
- `downloadStatus.ts` - 下载队列
- `storeConfig.ts` - API 配置
- `typedefinition.ts` - 类型定义
- **`modules/`** - 业务逻辑
- `processInstall.ts` - 安装/卸载
### 共享模块
**目录:** `electron/global.ts`
- 进程间共享的常量和配置
- 系统架构检测
### 配置文件
- **`vite.config.ts`** - Vite 构建配置
- **`electron-builder.yml`** - 打包配置
- **`tsconfig.json`** - TypeScript 配置
- **`eslint.config.ts`** - ESLint 配置
## 开发工作流
### 功能开发流程
1. **需求分析**
- 理解功能需求
- 设计 API 和数据结构
- 确定影响范围
2. **创建分支**
```bash
git checkout -b feature/your-feature
```
3. **实现功能**
- 更新类型定义 (`src/global/typedefinition.ts`)
- 实现 Vue 组件
- 添加 IPC 处理（如需要）
- 编写测试
4. **测试**
```bash
npm run test
npm run test:e2e
```
5. **代码检查**
```bash
npm run lint
npm run format
```
6. **提交 PR**
- 使用 `feat(scope): description` 格式
- 引用相关 Issue
- 添加详细描述
### Bug 修复流程
1. **复现 Bug**
- 确认 Bug 存在
- 添加复现步骤到 Issue
2. **定位问题**
- 查看日志
- 使用调试器
- 检查相关代码
3. **创建分支**
```bash
git checkout -b fix/your-bug-fix
```
4. **修复代码**
- 最小化修改
- 添加回归测试
- 更新文档（如需要）
5. **验证修复**
- 本地测试
- 确保测试通过
6. **提交 PR**
- 使用 `fix(scope): description` 格式
- 说明修复方法
### 重构流程
1. **识别需要重构的代码**
- 代码重复
- 复杂度过高
- 性能问题
2. **制定重构计划**
- 不改变外部行为
- 逐步进行
- 保持测试通过
3. **执行重构**
```bash
git checkout -b refactor/your-refactor
```
4. **验证**
- 所有测试通过
- 性能未下降
- 代码可读性提升
## 调试技巧
### 主进程调试
**VS Code 配置:**
创建 `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Electron: Main",
"type": "node",
"request": "launch",
"cwd": "${workspaceFolder}",
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
"windows": {
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
},
"args": ["."],
"outputCapture": "std"
}
]
}
```
**日志调试:**
```typescript
import pino from "pino";
const logger = pino({ name: "module-name" });
logger.info("Application started");
logger.error({ err }, "Failed to load apps");
logger.debug("Debug information");
```
### 渲染进程调试
**使用 Vue DevTools:**
1. 安装 Vue DevTools 浏览器扩展
2. Electron 会自动检测
3. 检查组件树和状态
**控制台日志:**
```typescript
console.log("Debug:", data);
console.error("Error:", error);
console.table(apps);
```
### IPC 通信调试
**主进程:**
```typescript
ipcMain.on("test-channel", (event, data) => {
console.log("Received:", data);
event.sender.send("test-response", { result: "ok" });
});
```
**渲染进程:**
```typescript
window.ipcRenderer.send("test-channel", { test: "data" });
window.ipcRenderer.on("test-response", (_event, data) => {
console.log("Response:", data);
});
```
### 性能分析
**Chrome DevTools:**
1. 打开 DevTools (Ctrl+Shift+I)
2. Performance 面板
3. 录制并分析
**Vite 分析:**
```bash
npm run build:vite -- --mode profile
```
## 本地开发最佳实践
### 代码组织
1. **组件拆分**
- 单一职责原则
- 组件不超过 300 行
- 提取可复用逻辑
2. **状态管理**
- 使用 Vue 响应式系统
- 全局状态放在 `src/global/`
- 组件状态使用 `ref` 和 `computed`
3. **类型定义**
- 所有数据结构都有类型
- 避免 `any` 类型
- 使用 TypeScript 工具类型
### 组件复用
1. **Props 设计**
- 明确的类型定义
- 合理的默认值
- 必填项标注
2. **Events 设计**
- 使用 TypeScript 定义
- 清晰的事件命名
3. **插槽使用**
- 提供灵活的内容布局
- 具名插槽增强可用性
### 错误处理
1. **Try-Catch**
```typescript
try {
await someAsyncOperation();
} catch (error) {
logger.error({ err: error }, "Operation failed");
showErrorToUser(error.message);
}
```
2. **Promise 错误**
```typescript
somePromise()
.then((result) => {
// handle success
})
.catch((error) => {
// handle error
});
```
3. **Vue 错误捕获**
```typescript
onMounted(() => {
window.addEventListener("error", handleError);
});
```
### 性能优化
1. **列表虚拟化**（大数据集）
2. **图片懒加载**
3. **防抖和节流**
4. **计算结果缓存**
---
**© 2026 APM 应用商店项目**

154
FAQ.md Normal file
View File

@@ -0,0 +1,154 @@
# 常见问题 (FAQ)
## 基本问题
### Q: APM 应用商店是什么？
**A:** APM 应用商店是基于 Electron + Vue 3 构建的桌面应用商店客户端，用于 APM (AmberPM) 包管理器的图形化界面。
### Q: 支持哪些操作系统？
**A:** 目前支持 Linux 系统，包括但不限于：
- Ubuntu 20.04+
- Debian 11+
- Fedora 35+
- Arch Linux
- 银河麒麟
- 统信 UOS
### Q: 如何安装 APM 应用商店？
**A:**
1. 从 GitHub Releases 下载 deb 或 rpm 包
2. 使用包管理器安装：
```bash
# Debian/Ubuntu
sudo dpkg -i spark-store_*.deb
# Fedora/RHEL
sudo dnf install spark-store_*.rpm
```
### Q: 需要 APM 包管理器吗？
**A:** 是的，APM 应用商店需要 APM 包管理器才能工作。请先安装 APM。
## 使用问题
### Q: 如何安装应用？
**A:**
1. 打开 APM 应用商店
2. 浏览或搜索应用
3. 点击应用卡片查看详情
4. 点击"安装"按钮
5. 等待安装完成
### Q: 如何卸载应用？
**A:**
1. 点击右上角"已安装"按钮
2. 在列表中找到要卸载的应用
3. 点击"卸载"按钮
4. 确认卸载
### Q: 如何更新应用？
**A:**
1. 点击右上角"更新"按钮
2. 选择要更新的应用
3. 点击"更新"按钮
4. 等待更新完成
### Q: 下载的应用在哪里？
**A:**
应用下载后存储在 APM 管理的目录中，通常位于：
```
/opt/spark-store/apps/{pkgname}/
```
## 技术问题
### Q: 应用无法启动怎么办？
**A:** 请参考 [问题排查指南](TROUBLESHOOTING.md)。
### Q: 如何查看日志？
**A:**
日志位置：
- 主进程日志：`~/.config/spark-store/logs/`
- 系统日志：`journalctl -u spark-store`
### Q: 如何切换主题？
**A:**
点击右上角主题切换按钮，或按 `Ctrl+Shift+T`。
### Q: 支持深色模式吗？
**A:** 是的，支持亮色、暗色和跟随系统主题。
## 开发问题
### Q: 如何参与开发？
**A:** 请参考 [贡献指南](CONTRIBUTING.md)。
### Q: 如何运行开发版本？
**A:**
```bash
git clone https://github.com/elysia-best/apm-app-store.git
cd apm-app-store
npm install
npm run dev
```
### Q: 技术栈是什么？
**A:**
- Electron 40.0.0
- Vue 3
- Vite 6.4.1
- TypeScript
- Tailwind CSS 4.1.18
### Q: 如何报告 Bug？
**A:**
请在 [GitHub Issues](https://github.com/elysia-best/apm-app-store/issues) 提交 Bug 报告。
## 其他问题
### Q: 可以在 Windows/Mac 上使用吗？
**A:** 目前不支持，但计划在未来添加跨平台支持。
### Q: 如何获取帮助？
**A:**
- 查看 [文档](README.md)
- 提交 [Issue](https://github.com/elysia-best/apm-app-store/issues)
- 加入 [社区论坛](https://bbs.spark-app.store/)
### Q: 许可证是什么？
**A:**
本项目采用 [GPL-3.0](LICENSE.md) 协议开源。
---
**© 2026 APM 应用商店项目**

229
PROJECT_ORGANIZATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,229 @@
# 项目整理完成总结
## ✅ 完成的工作
### 1. 核心文档（3个文件）
| 文件 | 状态 | 说明 |
| --------------- | ----------------- | --------------------------- |
| AGENTS.md | ✅ 已替换为中文版 | 完整的 AI 编码指南（894行） |
| CONTRIBUTING.md | ✅ 新建 | 贡献指南（中文） |
| DEVELOPMENT.md | ✅ 新建 | 开发文档（中文） |
### 2. 工作流文档（9个文件）
| 文件 | 说明 |
| --------------------------------------------- | -------------- |
| .agents/workflows/feature-development.md | 新功能开发流程 |
| .agents/workflows/bug-fix.md | Bug 修复流程 |
| .agents/workflows/code-review.md | 代码审查流程 |
| .agents/workflows/testing.md | 测试编写流程 |
| .agents/workflows/release.md | 发布流程 |
| .agents/workflows/refactoring.md | 代码重构流程 |
| .agents/workflows/documentation.md | 文档更新流程 |
| .agents/workflows/performance-optimization.md | 性能优化流程 |
| .agents/workflows/security-audit.md | 安全审计流程 |
**删除的文件:**
- .agents/workflows/1.md
- .agents/workflows/代码审查.md
### 3. 测试基础设施（5个文件）
| 文件 | 说明 |
| ----------------------------------------- | ----------------------- |
| vitest.config.ts | Vitest 单元测试配置 |
| playwright.config.ts | Playwright E2E 测试配置 |
| src/**tests**/setup.ts | 测试环境设置 |
| src/**tests**/unit/downloadStatus.test.ts | 示例单元测试 |
| e2e/basic.spec.ts | 示例 E2E 测试 |
### 4. 测试文档（1个文件）
| 文件 | 说明 |
| ---------- | ---------------------- |
| TESTING.md | 完整的测试文档（中文） |
### 5. CI/CD 集成（2个文件）
| 文件 | 操作 |
| --------------------------- | -------------------- |
| .github/workflows/test.yml | 新建（测试 CI） |
| .github/workflows/build.yml | 更新（添加测试步骤） |
### 6. 完善文档（3个文件）
| 文件 | 说明 |
| ------------------ | -------------------- |
| DEPLOYMENT.md | 部署文档（中文） |
| TROUBLESHOOTING.md | 问题排查指南（中文） |
| FAQ.md | 常见问题（中文） |
### 7. Issue 模板更新（2个文件）
| 文件 | 操作 |
| ------------------------------------- | -------------- |
| .github/ISSUE_TEMPLATE/bug_report.md | 更新为标准模板 |
| .github/ISSUE_TEMPLATE/help_wanted.md | 更新为标准模板 |
### 8. 配置更新
| 文件 | 操作 |
| ------------ | ------------------ |
| package.json | 添加测试依赖和脚本 |
| .gitignore | 添加测试相关忽略项 |
## 📊 统计数据
- **创建的文件:** 23个
- **更新的文件:** 3个
- **删除的文件:** 2个
- **总计:** 28个文件操作
## 📝 新增的 npm 脚本
```json
{
"test": "vitest",
"test:watch": "vitest --watch",
"test:coverage": "vitest --coverage",
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:debug": "playwright test --debug",
"test:all": "npm run test && npm run test:e2e"
}
```
## 📦 新增的依赖
### Dev Dependencies
- `@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
## 🔍 已知问题
### LSP 类型错误
由于 Vitest 和 Vite 的版本兼容性问题，LSP 会报告一些类型错误，但这些不会影响实际运行：
- `vitest.config.ts` 中的插件类型不匹配（Vite vs Vitest 版本差异）
- 这些错误在运行时不会出现
### ESLint 错误
项目中有一些现有的 ESLint 错误需要修复：
- `src/App.vue`: 3个 `any` 类型错误
- `src/components/HomeView.vue`: 5个错误（未使用变量、any 类型）
- `src/components/TopActions.vue`: 1个未使用变量
这些是原有代码的问题，不是本次整理引入的。
## 🚀 下一步建议
1. **修复 ESLint 错误**
```bash
npm run lint:fix
```
2. **运行测试验证**
```bash
npm run test
```
3. **安装 Playwright 浏览器**
```bash
npx playwright install --with-deps chromium
```
4. **运行 E2E 测试**
```bash
npm run test:e2e
```
5. **提交代码**
```bash
git add .
git commit -m "chore: add comprehensive documentation and testing infrastructure" -s
git push origin main
```
## 📚 文档结构总览
```
apm-app-store/
├── AGENTS.md # AI 编码指南（中文）
├── CONTRIBUTING.md # 贡献指南（中文）
├── DEVELOPMENT.md # 开发文档（中文）
├── DEPLOYMENT.md # 部署文档（中文）
├── TROUBLESHOOTING.md # 问题排查（中文）
├── FAQ.md # 常见问题（中文）
├── TESTING.md # 测试文档（中文）
├── README.md # 项目说明（已存在）
├── CHANGELOG.md # 变更日志（已存在）
├── SECURITY.md # 安全政策（已存在）
├── LICENSE.md # 许可证（已存在）
├── CREDITS.md # 致谢（已存在）
├── vitest.config.ts # Vitest 配置
├── playwright.config.ts # Playwright 配置
├── .agents/
│ └── workflows/
│ ├── feature-development.md # 新功能开发
│ ├── bug-fix.md # Bug 修复
│ ├── code-review.md # 代码审查
│ ├── testing.md # 测试编写
│ ├── release.md # 发布流程
│ ├── refactoring.md # 代码重构
│ ├── documentation.md # 文档更新
│ ├── performance-optimization.md # 性能优化
│ └── security-audit.md # 安全审计
├── .github/
│ ├── workflows/
│ │ ├── test.yml # 测试 CI（新建）
│ │ └── build.yml # 构建 CI（更新）
│ └── ISSUE_TEMPLATE/
│ ├── bug_report.md # Bug 报告模板（更新）
│ └── help_wanted.md # 功能请求模板（更新）
├── src/
│ └── __tests__/
│ ├── setup.ts # 测试设置
│ └── unit/
│ └── downloadStatus.test.ts # 示例测试
└── e2e/
└── basic.spec.ts # E2E 测试示例
```
## 🎯 项目成熟度提升
整理前：
- ❌ 缺少完整的开发文档
- ❌ 缺少测试基础设施
- ❌ 工作流文档简单
- ❌ 没有自动化测试 CI
整理后：
- ✅ 完整的中文开发文档
- ✅ 完整的测试基础设施（Vitest + Playwright）
- ✅ 9个详细的 AI 工作流
- ✅ 自动化测试 CI/CD
- ✅ 标准化的 Issue 模板
- ✅ 完善的部署和问题排查文档
---
**整理完成时间:** 2026-03-10
**整理执行者:** OpenCode AI Assistant
**文档版本:** 1.0

436
TESTING.md Normal file
View File

@@ -0,0 +1,436 @@
# 测试文档
## 📋 目录
- [测试框架](#测试框架)
- [测试规范](#测试规范)
- [编写测试](#编写测试)
- [运行测试](#运行测试)
- [测试覆盖率](#测试覆盖率)
- [Mock 数据](#mock-数据)
- [E2E 测试](#e2e-测试)
## 测试框架
### Vitest（单元测试）
Vitest 是 Vite 原生的测试框架，提供快速的开发体验。
**特点:**
- 与 Vite 配置共享
- 极快的测试执行速度
- 内置 TypeScript 支持
- Jest 兼容的 API
**配置文件:** `vitest.config.ts`
### Playwright（E2E 测试）
Playwright 用于端到端测试，模拟真实用户操作。
**特点:**
- 支持多浏览器（Chromium, Firefox, WebKit）
- 自动等待
- 网络拦截和 mock
- 可视化测试运行
**配置文件:** `playwright.config.ts`
## 测试规范
### 命名规范
**测试文件:** `*.test.ts` 或 `*.spec.ts`
**测试目录结构:**
```
src/
├── __tests__/
│ ├── unit/ # 单元测试
│ │ ├── downloadStatus.test.ts
│ │ └── storeConfig.test.ts
│ ├── integration/ # 集成测试
│ │ └── installFlow.test.ts
│ └── setup.ts # 测试设置
└── components/
└── AppCard.test.ts # 组件测试
e2e/
├── install.spec.ts # E2E 测试
└── download.spec.ts
```
### 测试分组
使用 `describe` 分组相关测试：
```typescript
describe("ComponentName", () => {
describe("method", () => {
it("should do something", () => {
// ...
});
});
});
```
### 测试命名
使用清晰的描述性名称：
```typescript
✅ 好的:
it('should return true when app is installed')
it('should throw error when package not found')
❌ 不好的:
it('test1')
it('works')
```
## 编写测试
### 单元测试
**测试纯函数:**
```typescript
import { describe, it, expect } from "vitest";
import { parseInstalledList } from "@/modules/parse";
describe("parseInstalledList", () => {
it("should parse installed list correctly", () => {
const output = "code/stable,1.108.2 amd64 [installed]";
const result = parseInstalledList(output);
expect(result).toHaveLength(1);
expect(result[0].pkgname).toBe("code");
expect(result[0].version).toBe("1.108.2");
});
});
```
**测试 Vue 组件:**
```typescript
import { describe, it, expect } from "vitest";
import { mount } from "@vue/test-utils";
import AppCard from "@/components/AppCard.vue";
import type { App } from "@/global/typedefinition";
describe("AppCard", () => {
const mockApp: App = {
name: "Test App",
pkgname: "test-app",
version: "1.0.0",
filename: "test.deb",
torrent_address: "",
author: "Test",
contributor: "Test",
website: "https://example.com",
update: "2024-01-01",
size: "100M",
more: "Test app",
tags: "",
img_urls: [],
icons: "",
category: "test",
currentStatus: "not-installed",
};
it("should render app name", () => {
const wrapper = mount(AppCard, {
props: {
app: mockApp,
},
});
expect(wrapper.text()).toContain("Test App");
});
it("should emit install event", async () => {
const wrapper = mount(AppCard, {
props: {
app: mockApp,
},
});
await wrapper.find(".install-button").trigger("click");
expect(wrapper.emitted("install")).toBeTruthy();
});
});
```
### 集成测试
测试模块间的交互：
```typescript
import { describe, it, expect, vi, beforeEach } from "vitest";
import { installPackage } from "@/modules/processInstall";
import { downloads, addDownload } from "@/global/downloadStatus";
describe("installPackage integration", () => {
beforeEach(() => {
downloads.value = [];
vi.clearAllMocks();
});
it("should add download and send IPC message", () => {
const pkgname = "test-app";
installPackage(pkgname);
expect(downloads.value).toHaveLength(1);
expect(downloads.value[0].pkgname).toBe(pkgname);
expect(window.ipcRenderer.send).toHaveBeenCalledWith(
"queue-install",
expect.any(String),
);
});
});
```
## 运行测试
### 单元测试
```bash
# 运行所有测试
npm run test
# 监听模式（开发时）
npm run test:watch
# 运行特定文件
npm run test src/__tests__/unit/downloadStatus.test.ts
# 运行匹配模式的测试
npm run test -- downloadStatus
```
### 覆盖率
```bash
# 生成覆盖率报告
npm run test:coverage
# 报告位置:
# - 控制台: 文本报告
# - coverage/ 目录: HTML 报告
```
### E2E 测试
```bash
# 运行所有 E2E 测试
npm run test:e2e
# UI 模式（推荐用于开发）
npm run test:e2e:ui
# 调试模式
npm run test:e2e:debug
# 运行特定测试
npm run test:e2e -- install.spec.ts
```
## 测试覆盖率
### 覆盖率目标
- **语句覆盖率:** ≥ 70%
- **分支覆盖率:** ≥ 70%
- **函数覆盖率:** ≥ 70%
- **行覆盖率:** ≥ 70%
### 查看报告
```bash
npm run test:coverage
# 在浏览器中打开
open coverage/index.html
```
### CI 中强制检查
在 `.github/workflows/test.yml` 中配置覆盖率阈值。
## Mock 数据
### Mock IPC
在 `src/__tests__/setup.ts` 中全局 mock：
```typescript
global.window = Object.create(window);
Object.defineProperty(window, "ipcRenderer", {
value: {
send: vi.fn(),
on: vi.fn(),
off: vi.fn(),
invoke: vi.fn(),
removeListener: vi.fn(),
},
});
```
### Mock API 响应
```typescript
import { vi } from "vitest";
import axios from "axios";
vi.mock("axios");
describe("fetchApps", () => {
it("should fetch apps from API", async () => {
const mockApps = [{ name: "Test", pkgname: "test" }];
axios.get.mockResolvedValue({ data: mockApps });
const result = await fetchApps();
expect(result).toEqual(mockApps);
});
});
```
### Mock 文件系统
```typescript
import { vi } from "vitest";
import fs from "node:fs";
vi.mock("node:fs");
describe("readConfig", () => {
it("should read config file", () => {
const mockConfig = { theme: "dark" };
fs.readFileSync.mockReturnValue(JSON.stringify(mockConfig));
const config = readConfig();
expect(config).toEqual(mockConfig);
});
});
```
## E2E 测试
### 编写 E2E 测试
```typescript
import { test, expect } from "@playwright/test";
test.describe("App Installation", () => {
test.beforeEach(async ({ page }) => {
await page.goto("http://127.0.0.1:3344");
});
test("should install an app", async ({ page }) => {
// 搜索应用
await page.fill('input[placeholder="搜索应用"]', "Test App");
await page.press('input[placeholder="搜索应用"]', "Enter");
// 等待结果
await expect(page.locator(".app-card")).toBeVisible();
// 点击安装
await page.click('.app-card:has-text("Test App") .install-button');
// 验证下载队列
await expect(page.locator(".download-queue")).toBeVisible();
await expect(page.locator(".download-item")).toHaveText("Test App");
});
test("should show installation progress", async ({ page }) => {
// ... 测试进度显示
});
test("should handle installation failure", async ({ page }) => {
// ... 测试失败处理
});
});
```
### E2E 测试最佳实践
1. **使用选择器**
```typescript
// 推荐：语义化选择器
await page.click('[data-testid="install-button"]');
// 避免：脆弱的选择器
await page.click("button.btn-primary");
```
2. **等待元素**
```typescript
// 自动等待
await expect(page.locator(".modal")).toBeVisible();
// 手动等待（必要时）
await page.waitForSelector(".modal", { state: "visible" });
```
3. **截图和视频**
- 失败时自动截图
- 失败时自动录制视频
4. **网络拦截**
```typescript
await page.route("**/api/**", (route) => {
route.fulfill({
status: 200,
body: JSON.stringify(mockData),
});
});
```
## 常见问题
### 测试超时
```typescript
test(
"slow test",
async () => {
// 增加超时时间
},
{ timeout: 10000 },
);
```
### 异步测试
```typescript
it("should handle async operation", async () => {
await someAsyncOperation();
expect(result).toBe(expected);
});
```
### 清理副作用
```typescript
import { afterEach } from "vitest";
afterEach(() => {
// 清理 mock
vi.restoreAllMocks();
// 清理状态
downloads.value = [];
});
```
---
**© 2026 APM 应用商店项目**

160
TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,160 @@
# 问题排查指南
## 📋 目录
- [常见问题](#常见问题)
- [调试方法](#调试方法)
- [日志分析](#日志分析)
- [性能问题](#性能问题)
## 常见问题
### 应用无法启动
**症状:** 双击应用图标后无反应
**可能原因:**
1. 依赖包未安装
2. 配置文件损坏
3. 权限问题
**解决方法:**
```bash
# 检查日志
journalctl -u spark-store
# 重新安装
sudo dpkg -i spark-store_*.deb
# 检查依赖
sudo apt-get install -f
```
### 安装失败
**症状:** 点击安装按钮后无响应或报错
**可能原因:**
1. APM 未安装
2. 权限不足
3. 网络问题
**解决方法:**
```bash
# 检查 APM 是否安装
which apm
# 检查权限
pkexec --version
# 查看 APM 日志
sudo journalctl -u amber-pm
```
### 下载速度慢
**症状:** 下载进度缓慢
**解决方法:**
1. 检查网络连接
2. 更换下载源
3. 使用代理
### 主题切换无效
**症状:** 切换暗色/亮色主题后无变化
**解决方法:**
```bash
# 清除本地存储
rm -rf ~/.config/spark-store/
```
## 调试方法
### 主进程调试
```bash
# 使用命令行启动并查看日志
spark-store --enable-logging
```
### 渲染进程调试
1. 打开应用
2. 按 `Ctrl+Shift+I` 打开 DevTools
3. 查看 Console 和 Network 标签
### IPC 通信调试
在 `electron/main/index.ts` 中添加日志：
```typescript
ipcMain.on("test-channel", (event, data) => {
logger.info("IPC received:", data);
});
```
## 日志分析
### 日志位置
- **主进程日志:** `~/.config/spark-store/logs/`
- **系统日志:** `journalctl -u spark-store`
### 日志级别
- `trace`: 最详细
- `debug`: 调试信息
- `info`: 一般信息
- `warn`: 警告
- `error`: 错误
- `fatal`: 致命错误
### 查看日志
```bash
# 查看最新日志
tail -f ~/.config/spark-store/logs/main.log
# 搜索错误
grep ERROR ~/.config/spark-store/logs/*.log
```
## 性能问题
### 内存占用高
**检查方法:**
1. 打开 DevTools → Performance 标签
2. 录制并分析内存使用
**优化建议:**
- 清理不必要的组件
- 使用虚拟滚动
- 避免内存泄漏
### 启动慢
**检查方法:**
1. 查看 DevTools → Network 标签
2. 检查加载时间
**优化建议:**
- 延迟加载非关键资源
- 优化 API 请求
- 减少 HTTP 请求数量
---
**© 2026 APM 应用商店项目**

632
WORKFLOW.md Normal file
View 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 应用商店项目**

27
e2e/basic.spec.ts Normal file
View File

@@ -0,0 +1,27 @@
import { test, expect } from "@playwright/test";
test.describe("应用基本功能", () => {
test.beforeEach(async ({ page }) => {
await page.goto("http://127.0.0.1:3344");
});
test("页面应该正常加载", async ({ page }) => {
await expect(page).toHaveTitle(/APM 应用商店|Spark Store/);
});
test("应该显示应用列表", async ({ page }) => {
await page.waitForSelector(".app-card", { timeout: 10000 });
const appCards = page.locator(".app-card");
await expect(appCards.first()).toBeVisible();
});
test("搜索功能应该工作", async ({ page }) => {
const searchInput = page.locator('input[placeholder*="搜索"]').first();
await expect(searchInput).toBeVisible();
await searchInput.fill("test");
await searchInput.press("Enter");
await page.waitForTimeout(1000);
});
});

16
package.json
View File

@@ -30,14 +30,26 @@
"lint": "eslint --ext .ts,.vue src electron", "lint": "eslint --ext .ts,.vue src electron",
"lint:fix": "eslint --ext .ts,.vue src electron --fix", "lint:fix": "eslint --ext .ts,.vue src electron --fix",
"format": "prettier --write \"src/**/*.{ts,vue}\" \"electron/**/*.{ts,vue}\"", "format": "prettier --write \"src/**/*.{ts,vue}\" \"electron/**/*.{ts,vue}\"",
"changelog": "conventional-changelog -p angular -r 0" "changelog": "conventional-changelog -p angular -r 0",
"test": "vitest",
"test:watch": "vitest --watch",
"test:coverage": "vitest --coverage",
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:debug": "playwright test --debug",
"test:all": "npm run test && npm run test:e2e"
}, },
"devDependencies": { "devDependencies": {
"@dotenvx/dotenvx": "^1.51.4", "@dotenvx/dotenvx": "^1.51.4",
"@eslint/create-config": "^1.11.0", "@eslint/create-config": "^1.11.0",
"@eslint/js": "^9.39.2", "@eslint/js": "^9.39.2",
"@loongdotjs/electron-builder": "^26.0.12-1", "@loongdotjs/electron-builder": "^26.0.12-1",
"@playwright/test": "^1.40.0",
"@testing-library/jest-dom": "^6.1.5",
"@testing-library/vue": "^8.0.1",
"@vitejs/plugin-vue": "^6.0.3", "@vitejs/plugin-vue": "^6.0.3",
"@vitest/coverage-v8": "^1.0.0",
"@vue/test-utils": "^2.4.3",
"conventional-changelog": "^7.1.1", "conventional-changelog": "^7.1.1",
"conventional-changelog-angular": "^8.1.0", "conventional-changelog-angular": "^8.1.0",
"electron": "^40.0.0", "electron": "^40.0.0",
@@ -47,6 +59,7 @@
"eslint-plugin-vue": "^10.7.0", "eslint-plugin-vue": "^10.7.0",
"globals": "^17.3.0", "globals": "^17.3.0",
"jiti": "^2.6.1", "jiti": "^2.6.1",
"jsdom": "^23.0.1",
"pino-pretty": "^13.1.3", "pino-pretty": "^13.1.3",
"prettier": "3.8.1", "prettier": "3.8.1",
"typescript": "^5.4.2", "typescript": "^5.4.2",
@@ -54,6 +67,7 @@
"vite": "^6.4.1", "vite": "^6.4.1",
"vite-plugin-electron": "^0.29.0", "vite-plugin-electron": "^0.29.0",
"vite-plugin-electron-renderer": "^0.14.5", "vite-plugin-electron-renderer": "^0.14.5",
"vitest": "^1.0.0",
"vue": "^3.4.21", "vue": "^3.4.21",
"vue-tsc": "^3.2.4" "vue-tsc": "^3.2.4"
}, },

33
playwright.config.ts Normal file
View File

@@ -0,0 +1,33 @@
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./e2e",
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: [
["html", { outputFolder: "playwright-report" }],
["json", { outputFile: "test-results.json" }],
],
use: {
baseURL: "http://127.0.0.1:3344",
trace: "on-first-retry",
screenshot: "only-on-failure",
video: "retain-on-failure",
},
projects: [
{
name: "chromium",
use: { ...devices["Desktop Chrome"] },
},
],
webServer: {
command: "npm run dev",
url: "http://127.0.0.1:3344",
reuseExistingServer: !process.env.CI,
timeout: 120 * 1000,
stdout: "pipe",
stderr: "pipe",
},
});

30
src/__tests__/setup.ts Normal file
View File

@@ -0,0 +1,30 @@
import { expect, afterEach, vi } from "vitest";
import { cleanup } from "@testing-library/vue";
import * as matchers from "@testing-library/jest-dom/matchers";
// 扩展 Vitest 的 expect
expect.extend(matchers);
// 每个测试后清理
afterEach(() => {
cleanup();
});
// Mock window.ipcRenderer
global.window = Object.create(window);
Object.defineProperty(window, "ipcRenderer", {
value: {
send: vi.fn(),
on: vi.fn(),
off: vi.fn(),
invoke: vi.fn(),
removeListener: vi.fn(),
},
});
// Mock window.apm_store
Object.defineProperty(window, "apm_store", {
value: {
arch: "amd64-store",
},
});

67
src/__tests__/unit/downloadStatus.test.ts Normal file
View File

@@ -0,0 +1,67 @@
import { describe, it, expect, beforeEach } from "vitest";
import {
downloads,
addDownload,
removeDownloadItem,
} from "@/global/downloadStatus";
import type { DownloadItem } from "@/global/typedefinition";
describe("downloadStatus", () => {
beforeEach(() => {
downloads.value = [];
});
describe("addDownload", () => {
it("should add a new download item", () => {
const mockDownload: DownloadItem = {
id: 1,
name: "Test App",
pkgname: "test-app",
version: "1.0.0",
icon: "",
status: "queued",
progress: 0,
downloadedSize: 0,
totalSize: 1000000,
speed: 0,
timeRemaining: 0,
startTime: Date.now(),
logs: [],
source: "Test",
retry: false,
};
addDownload(mockDownload);
expect(downloads.value).toHaveLength(1);
expect(downloads.value[0].pkgname).toBe("test-app");
});
});
describe("removeDownloadItem", () => {
it("should remove download by pkgname", () => {
const mockDownload: DownloadItem = {
id: 1,
name: "Test App",
pkgname: "test-app",
version: "1.0.0",
icon: "",
status: "queued",
progress: 0,
downloadedSize: 0,
totalSize: 1000000,
speed: 0,
timeRemaining: 0,
startTime: Date.now(),
logs: [],
source: "Test",
retry: false,
};
downloads.value.push(mockDownload);
removeDownloadItem("test-app");
expect(downloads.value).toHaveLength(0);
});
});
});

37
vitest.config.ts Normal file
View File

@@ -0,0 +1,37 @@
import { defineConfig } from "vitest/config";
import vue from "@vitejs/plugin-vue";
import { resolve } from "node:path";
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
"@": resolve(__dirname, "./src"),
},
},
test: {
globals: true,
environment: "jsdom",
setupFiles: ["./src/__tests__/setup.ts"],
coverage: {
provider: "v8",
reporter: ["text", "json", "html", "lcov"],
exclude: [
"node_modules/",
"dist/",
"dist-electron/",
"**/*.d.ts",
"**/*.config.*",
"**/mockData",
"src/__tests__/",
"**/*.spec.ts",
"**/*.test.ts",
"electron/",
],
statements: 70,
branches: 70,
functions: 70,
lines: 70,
},
},
});