docs: add quality gates documentation
This commit is contained in:
张翔
@@ -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