docs: add quality gates documentation
This commit is contained in:
张翔
@@ -108,7 +108,7 @@ npm start
|
||||
|
||||
```
|
||||
novalon-website/
|
||||
├── src/
|
||||
├── src/ # 源代码
|
||||
│ ├── app/ # Next.js App Router
|
||||
│ │ ├── (marketing)/ # 营销页面路由组
|
||||
│ │ │ ├── page.tsx # 首页
|
||||
@@ -147,6 +147,7 @@ novalon-website/
|
||||
│ │ ├── analytics/ # 分析组件
|
||||
│ │ └── admin/ # 管理后台组件
|
||||
│ ├── lib/ # 工具函数
|
||||
│ │ ├── api/ # API 服务
|
||||
│ │ ├── auth/ # 认证相关
|
||||
│ │ ├── db.ts # 数据库连接
|
||||
│ │ ├── audit.ts # 审计日志
|
||||
@@ -157,7 +158,7 @@ novalon-website/
|
||||
│ │ └── migrations/ # 迁移文件
|
||||
│ ├── hooks/ # 自定义 Hooks
|
||||
│ └── contexts/ # React Context
|
||||
├── e2e/ # E2E 测试
|
||||
├── e2e/ # E2E 测试（统一测试框架）
|
||||
│ ├── src/
|
||||
│ │ ├── tests/ # 测试用例
|
||||
│ │ │ ├── smoke/ # 冒烟测试
|
||||
@@ -170,14 +171,49 @@ novalon-website/
|
||||
│ │ ├── pages/ # Page Object
|
||||
│ │ ├── fixtures/ # 测试 Fixtures
|
||||
│ │ └── config/ # 测试配置
|
||||
│ └── playwright.config.ts
|
||||
│ ├── playwright.config.ts
|
||||
│ └── MIGRATION.md # 测试框架迁移说明
|
||||
├── docs/ # 项目文档
|
||||
│ ├── architecture/ # 架构文档
|
||||
│ ├── development/ # 开发文档
|
||||
│ ├── deployment/ # 部署文档
|
||||
│ ├── testing/ # 测试文档
|
||||
│ ├── api/ # API 文档
|
||||
│ ├── guides/ # 使用指南
|
||||
│ ├── STRUCTURE_PLAN.md # 目录结构规划
|
||||
│ └── OPTIMIZATION_REPORT.md # 优化报告
|
||||
├── scripts/ # 脚本文件
|
||||
│ ├── deployment/ # 部署脚本
|
||||
│ ├── monitoring/ # 监控脚本
|
||||
│ ├── testing/ # 测试脚本
|
||||
│ ├── maintenance/ # 维护脚本
|
||||
│ └── utils/ # 工具脚本
|
||||
├── config/ # 配置文件
|
||||
│ ├── ci/ # CI/CD 配置
|
||||
│ ├── lint/ # 代码检查配置
|
||||
│ └── test/ # 测试配置
|
||||
├── reports/ # 测试报告
|
||||
│ ├── e2e/ # E2E 测试报告
|
||||
│ ├── performance/ # 性能测试报告
|
||||
│ └── coverage/ # 代码覆盖率报告
|
||||
├── public/ # 静态资源
|
||||
├── uploads/ # 上传文件存储
|
||||
├── data/ # SQLite 数据库文件
|
||||
├── docs/ # 项目文档
|
||||
└── dist/ # 构建输出
|
||||
```
|
||||
|
||||
### 项目优化说明
|
||||
|
||||
本项目已于 2026-03-24 完成全面的工程化与规范化优化，包括：
|
||||
|
||||
1. **测试体系整合** - 统一为 Playwright TypeScript 测试框架
|
||||
2. **目录结构规范化** - 建立清晰的目录结构，符合 Next.js 最佳实践
|
||||
3. **配置文件优化** - 合并重复配置，统一配置管理
|
||||
4. **文档体系完善** - 建立完整的文档体系和导航
|
||||
5. **代码质量提升** - 修复所有类型错误，确保构建成功
|
||||
|
||||
详细信息请查看 [优化报告](docs/OPTIMIZATION_REPORT.md)
|
||||
|
||||
## 页面路由
|
||||
|
||||
| 路由 | 描述 |
|
||||
@@ -220,6 +256,38 @@ novalon-website/
|
||||
| `npm run db:seed` | 填充数据库种子数据 |
|
||||
| `npm run db:studio` | 启动 Drizzle Studio |
|
||||
|
||||
## 代码质量门禁
|
||||
|
||||
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查：
|
||||
|
||||
- **ESLint**: 代码风格检查
|
||||
- **commitlint**: 提交信息规范
|
||||
- **Jest**: 代码覆盖率检查
|
||||
|
||||
详细信息请查看 [质量门禁文档](docs/development/quality-gates.md)。
|
||||
|
||||
### 提交规范
|
||||
|
||||
使用Conventional Commits规范：
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
**提交类型**:
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码格式调整
|
||||
- `refactor`: 重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具相关
|
||||
|
||||
## 测试
|
||||
|
||||
项目使用 Playwright 进行 E2E 测试，测试框架位于 `e2e/` 目录。
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
# CI/CD中的质量门禁
|
||||
|
||||
## 概述
|
||||
|
||||
质量门禁不仅在本地的Git hooks中运行，也在CI/CD流水线中执行，确保所有合并到主分支的代码都符合质量标准。
|
||||
|
||||
## Woodpecker CI配置
|
||||
|
||||
### 质量检查步骤
|
||||
|
||||
在 `.woodpecker.yml` 中添加质量检查步骤：
|
||||
|
||||
```yaml
|
||||
pipeline:
|
||||
quality-check:
|
||||
image: node:18-alpine
|
||||
environment:
|
||||
NODE_ENV: test
|
||||
commands:
|
||||
- npm ci
|
||||
- npm run lint
|
||||
- npm run type-check
|
||||
- npm run test:coverage
|
||||
when:
|
||||
event:
|
||||
- push
|
||||
- pull_request
|
||||
|
||||
coverage-report:
|
||||
image: node:18-alpine
|
||||
environment:
|
||||
NODE_ENV: test
|
||||
commands:
|
||||
- npm ci
|
||||
- npm run test:coverage
|
||||
# 上传覆盖率报告到Codecov或其他服务
|
||||
secrets: [codecov_token]
|
||||
when:
|
||||
event:
|
||||
- pull_request
|
||||
```
|
||||
|
||||
### 质量门禁规则
|
||||
|
||||
CI/CD中的质量门禁规则：
|
||||
|
||||
1. **代码检查**: ESLint必须通过，无错误
|
||||
2. **类型检查**: TypeScript编译必须成功
|
||||
3. **测试通过**: 所有测试必须通过
|
||||
4. **覆盖率达标**: 代码覆盖率必须≥70%
|
||||
|
||||
### 失败处理
|
||||
|
||||
如果质量检查失败：
|
||||
|
||||
1. CI/CD流水线失败
|
||||
2. 阻止合并到主分支
|
||||
3. 发送通知给开发者
|
||||
4. 显示详细的错误信息
|
||||
|
||||
## 本地开发 vs CI/CD
|
||||
|
||||
### 本地开发
|
||||
|
||||
- **优点**: 快速反馈，立即发现问题
|
||||
- **缺点**: 可能被绕过（--no-verify）
|
||||
|
||||
### CI/CD
|
||||
|
||||
- **优点**: 强制执行，无法绕过
|
||||
- **缺点**: 反馈延迟，需要等待CI运行
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **本地优先**: 在本地运行质量检查，确保通过后再推送
|
||||
2. **CI兜底**: CI/CD作为最后一道防线，确保质量
|
||||
3. **快速反馈**: CI/CD配置为快速失败，尽早发现问题
|
||||
|
||||
## 持续改进
|
||||
|
||||
### 监控质量指标
|
||||
|
||||
定期监控以下指标：
|
||||
|
||||
- 代码覆盖率趋势
|
||||
- ESLint错误数量
|
||||
- TypeScript错误数量
|
||||
- 测试失败率
|
||||
- CI/CD通过率
|
||||
|
||||
### 优化质量门禁
|
||||
|
||||
根据监控数据优化质量门禁：
|
||||
|
||||
1. 调整覆盖率阈值
|
||||
2. 添加新的质量检查
|
||||
3. 优化检查性能
|
||||
4. 改进错误提示
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Woodpecker CI文档](https://woodpecker-ci.org/)
|
||||
- [Codecov文档](https://docs.codecov.com/)
|
||||
- [GitHub Actions文档](https://docs.github.com/en/actions)
|
||||
@@ -0,0 +1,220 @@
|
||||
# 快速开始
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Node.js 18+
|
||||
- npm / yarn / pnpm / bun
|
||||
- Git
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd novalon-website
|
||||
```
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
编辑`.env.local`文件，配置必要的环境变量：
|
||||
|
||||
```env
|
||||
# 数据库
|
||||
DATABASE_URL=file:./data/dev.db
|
||||
|
||||
# NextAuth
|
||||
NEXTAUTH_SECRET=your-secret-key-here
|
||||
NEXTAUTH_URL=http://localhost:3000
|
||||
|
||||
# 管理员
|
||||
ADMIN_EMAIL=admin@novalon.cn
|
||||
ADMIN_PASSWORD=your-secure-password
|
||||
|
||||
# 邮件服务（可选）
|
||||
RESEND_API_KEY=your_resend_api_key
|
||||
COMPANY_EMAIL=contact@novalon.cn
|
||||
|
||||
# 站点URL
|
||||
NEXT_PUBLIC_SITE_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
### 4. 初始化数据库
|
||||
|
||||
```bash
|
||||
npm run db:push
|
||||
npm run db:seed
|
||||
```
|
||||
|
||||
### 5. 启动开发服务器
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
访问 http://localhost:3000
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
novalon-website/
|
||||
├── src/ # 源代码
|
||||
│ ├── app/ # Next.js App Router
|
||||
│ ├── components/ # React组件
|
||||
│ ├── lib/ # 工具函数
|
||||
│ ├── db/ # 数据库
|
||||
│ ├── hooks/ # 自定义Hooks
|
||||
│ └── contexts/ # React Context
|
||||
├── e2e/ # E2E测试
|
||||
├── docs/ # 项目文档
|
||||
├── scripts/ # 脚本文件
|
||||
├── config/ # 配置文件
|
||||
├── public/ # 静态资源
|
||||
└── package.json # 项目配置
|
||||
```
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 代码规范
|
||||
|
||||
项目使用ESLint和TypeScript进行代码检查：
|
||||
|
||||
```bash
|
||||
npm run lint # 代码检查
|
||||
npm run type-check # 类型检查
|
||||
```
|
||||
|
||||
### 测试
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
npm run test # 运行E2E测试
|
||||
npm run test:smoke # 运行冒烟测试
|
||||
npm run test:unit # 运行单元测试
|
||||
```
|
||||
|
||||
### 代码质量门禁
|
||||
|
||||
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查。
|
||||
|
||||
#### 质量检查
|
||||
|
||||
- **代码风格检查**: ESLint
|
||||
- **提交信息规范**: commitlint
|
||||
- **代码覆盖率检查**: Jest
|
||||
|
||||
#### 提交规范
|
||||
|
||||
使用Conventional Commits规范：
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
**提交类型**:
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码格式调整
|
||||
- `refactor`: 重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具相关
|
||||
|
||||
详细信息请查看 [质量门禁文档](quality-gates.md)。
|
||||
|
||||
### 数据库操作
|
||||
|
||||
```bash
|
||||
npm run db:generate # 生成迁移文件
|
||||
npm run db:migrate # 执行迁移
|
||||
npm run db:push # 推送schema到数据库
|
||||
npm run db:studio # 打开数据库管理界面
|
||||
npm run db:seed # 填充种子数据
|
||||
```
|
||||
|
||||
### 构建和部署
|
||||
|
||||
```bash
|
||||
npm run build # 构建生产版本
|
||||
npm start # 启动生产服务器
|
||||
```
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `npm run dev` | 启动开发服务器 |
|
||||
| `npm run build` | 构建生产版本 |
|
||||
| `npm start` | 启动生产服务器 |
|
||||
| `npm run lint` | 运行代码检查 |
|
||||
| `npm run type-check` | 运行类型检查 |
|
||||
| `npm run test` | 运行E2E测试 |
|
||||
| `npm run test:smoke` | 运行冒烟测试 |
|
||||
| `npm run db:push` | 推送schema到数据库 |
|
||||
| `npm run db:seed` | 填充种子数据 |
|
||||
|
||||
## 开发工具
|
||||
|
||||
### VS Code推荐插件
|
||||
|
||||
- ESLint
|
||||
- Prettier
|
||||
- TypeScript Vue Plugin (Volar)
|
||||
- Tailwind CSS IntelliSense
|
||||
- GitLens
|
||||
|
||||
### 浏览器开发者工具
|
||||
|
||||
- React Developer Tools
|
||||
- Redux DevTools（如果使用）
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 端口被占用
|
||||
|
||||
如果3000端口被占用，可以修改端口：
|
||||
|
||||
```bash
|
||||
npm run dev -- -p 3001
|
||||
```
|
||||
|
||||
### 数据库连接错误
|
||||
|
||||
检查`.env.local`中的`DATABASE_URL`配置是否正确。
|
||||
|
||||
### 依赖安装失败
|
||||
|
||||
尝试清除缓存重新安装：
|
||||
|
||||
```bash
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 阅读[编码规范](coding-standards.md)
|
||||
- 查看[组件开发指南](component-guide.md)
|
||||
- 了解[测试策略](../testing/testing-strategy.md)
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- 查看[故障排查指南](../guides/troubleshooting.md)
|
||||
- 阅读项目[README](../../README.md)
|
||||
- 联系开发团队
|
||||
@@ -0,0 +1,176 @@
|
||||
# 代码质量门禁
|
||||
|
||||
## 概述
|
||||
|
||||
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查。
|
||||
|
||||
## 质量检查
|
||||
|
||||
### 1. 代码风格检查
|
||||
|
||||
**工具**: ESLint
|
||||
|
||||
**检查时机**: pre-commit hook
|
||||
|
||||
**检查内容**:
|
||||
- 代码语法错误
|
||||
- 代码风格规范
|
||||
- 代码格式化
|
||||
|
||||
**通过标准**: 无错误，无警告
|
||||
|
||||
### 2. 提交信息规范
|
||||
|
||||
**工具**: commitlint
|
||||
|
||||
**检查时机**: commit-msg hook
|
||||
|
||||
**检查内容**:
|
||||
- 提交信息格式
|
||||
- 提交类型合法性
|
||||
|
||||
**通过标准**: 符合Conventional Commits规范
|
||||
|
||||
**提交类型**:
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码格式调整
|
||||
- `refactor`: 重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试相关
|
||||
- `chore`: 构建/工具相关
|
||||
- `revert`: 回滚提交
|
||||
- `build`: 构建相关
|
||||
- `ci`: CI/CD相关
|
||||
|
||||
**提交信息格式**:
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
**示例**:
|
||||
```
|
||||
feat(auth): add JWT authentication
|
||||
|
||||
Implement JWT-based authentication with:
|
||||
- Token generation
|
||||
- Token validation
|
||||
- Refresh token mechanism
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
### 3. 代码覆盖率检查
|
||||
|
||||
**工具**: Jest
|
||||
|
||||
**检查时机**: 手动运行或CI/CD
|
||||
|
||||
**检查内容**:
|
||||
- 单元测试覆盖率
|
||||
- 分支覆盖率
|
||||
- 函数覆盖率
|
||||
- 行覆盖率
|
||||
- 语句覆盖率
|
||||
|
||||
**通过标准**:
|
||||
- 分支覆盖率: ≥ 70%
|
||||
- 函数覆盖率: ≥ 70%
|
||||
- 行覆盖率: ≥ 70%
|
||||
- 语句覆盖率: ≥ 70%
|
||||
|
||||
### 4. 类型检查
|
||||
|
||||
**工具**: TypeScript
|
||||
|
||||
**检查时机**: pre-commit hook（通过ESLint）
|
||||
|
||||
**检查内容**:
|
||||
- 类型错误
|
||||
- 类型推断
|
||||
|
||||
**通过标准**: 无类型错误
|
||||
|
||||
## 如何绕过质量门禁
|
||||
|
||||
⚠️ **警告**: 仅在紧急情况下绕过质量门禁
|
||||
|
||||
### 绕过pre-commit hook
|
||||
|
||||
```bash
|
||||
git commit --no-verify -m "message"
|
||||
```
|
||||
|
||||
### 绕过commit-msg hook
|
||||
|
||||
```bash
|
||||
git commit --no-verify -m "message"
|
||||
```
|
||||
|
||||
### 绕过所有hooks
|
||||
|
||||
```bash
|
||||
git commit --no-verify -m "message"
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### ESLint错误
|
||||
|
||||
**问题**: pre-commit hook因ESLint错误失败
|
||||
|
||||
**解决方案**:
|
||||
1. 查看错误详情
|
||||
2. 修复代码或配置
|
||||
3. 运行 `npm run lint` 检查
|
||||
4. 重新提交
|
||||
|
||||
### commitlint错误
|
||||
|
||||
**问题**: commit-msg hook因提交信息格式错误失败
|
||||
|
||||
**解决方案**:
|
||||
1. 检查提交信息格式
|
||||
2. 使用正确的提交类型
|
||||
3. 重新提交
|
||||
|
||||
### 覆盖率不达标
|
||||
|
||||
**问题**: 覆盖率检查失败
|
||||
|
||||
**解决方案**:
|
||||
1. 查看覆盖率报告
|
||||
2. 补充测试用例
|
||||
3. 重新提交
|
||||
|
||||
## 持续改进
|
||||
|
||||
### 提高覆盖率阈值
|
||||
|
||||
随着项目发展，逐步提高覆盖率阈值：
|
||||
- Phase 1: 70% (当前)
|
||||
- Phase 2: 75%
|
||||
- Phase 3: 80%
|
||||
- Phase 4: 85%
|
||||
- Phase 5: 90%
|
||||
|
||||
### 添加更多质量检查
|
||||
|
||||
未来可以添加：
|
||||
- 复杂度检查
|
||||
- 重复代码检查
|
||||
- 安全漏洞扫描
|
||||
- 依赖漏洞检查
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
- [ESLint文档](https://eslint.org/)
|
||||
- [Jest文档](https://jestjs.io/)
|
||||
- [Husky文档](https://typicode.github.io/husky/)
|
||||
- [lint-staged文档](https://github.com/okonet/lint-staged)
|
||||
Reference in New Issue
Block a user