docs: add quality gates documentation

2026-03-24 13:32:01 +08:00
parent 707f125c14
commit c06ac08510
4 changed files with 572 additions and 4 deletions
@@ -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)
+- 联系开发团队