质量保证快速开始

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 质量保障体系快速上手指南

本指南将帮助你在 10 分钟内快速搭建代码质量保障体系，从根源上减少 BUG 出现的概率。

---

## &#128640; 一键安装（推荐）

```bash
# 运行安装脚本
chmod +x scripts/install-quality-tools.sh
bash scripts/install-quality-tools.sh
```

安装完成后，系统会自动配置：
- ✅ Pre-commit Hooks
- ✅ E111111111SLint 规则
- ✅ Prettier 格式化
- ✅ TypeScript 类型检查
- ✅ Jest 测试框架
- ✅ Playwright E2E 测试

---

## &#128203; 手动安装步骤

如果一键安装失败，可以按照以下步骤手动安装：

### 步骤 1: 安装依赖

```bash
# 安装 Husky（Git hooks 管理）
pnpm add -D husky

# 安装 lint-staged（暂存文件检查）
pnpm add -D lint-staged

# 安装 Prettier（代码格式化）
pnpm add -D prettier

# 安装 Jest（测试框架）
pnpm add -D jest jest-environment-jsdom @types/jest ts-jest

# 安装 React Testing Library（组件测试）
pnpm add -D @testing-library/react @testing-library/jest-dom @testing-library/user-event

# 安装 Playwright（E2E 测试）
pnpm add -D @playwright/test
```

### 步骤 2: 初始化 Husky

```bash
pnpm exec husky init
```

### 步骤 3: 复制配置文件

配置文件已经创建在项目根目录：
- `.husky/pre-commit` - Pre-commit hook
- `lint-staged.config.js` - Lint-staged 配置
- `eslint.config.mjs` - ESLint 配置
- `.prettierrc` - Prettier 配置
- `jest.config.js` - Jest 配置
- `playwright.config.ts` - Playwright 配置

### 步骤 4: 安装 Playwright 浏览器

```bash
pnpm exec playwright install --with-deps
```

### 步骤 5: 设置 Pre-commit Hook

```bash
chmod +x .husky/pre-commit
```

---

## &#127919; 快速验证

### 1. 测试代码检查

```bash
# 运行 ESLint
pnpm lint

# 自动修复
pnpm lint:fix

# 运行类型检查
pnpm type-check
```

### 2. 测试代码格式化

```bash
# 格式化所有文件
pnpm format

# 检查格式
pnpm format:check
```

### 3. 测试 Pre-commit Hook

```bash
# 修改一个文件
echo "test" > test.txt

# 尝试提交
git add test.txt
git commit -m "test: add test file"

# 应该会看到 Pre-commit 检查
```

### 4. 测试代码检查

```bash
# 运行所有测试
pnpm test

# 运行单元测试
pnpm test:unit

# 运行测试并生成覆盖率报告
pnpm test:coverage
```

---

## &#128221; 每日工作流

### 开发新功能

```bash
# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 编写代码
# ... 编写代码 ...

# 3. 运行代码检查
pnpm lint:fix
pnpm type-check

# 4. 运行测试
pnpm test:unit

# 5. 提交代码（会自动运行 Pre-commit 检查）
git add .
git commit -m "feat: add new feature"

# 6. 推送到远程
git push origin feature/new-feature
```

### 修复 BUG

```bash
# 1. 创建修复分支
git checkout -b bugfix/fix-bug

# 2. 修复 BUG
# ... 修复代码 ...

# 3. 编写测试（非常重要！）
# ... 编写测试 ...

# 4. 运行测试确保通过
pnpm test

# 5. 提交代码
git add .
git commit -m "fix: fix bug"

# 6. 推送到远程
git push origin bugfix/fix-bug
```

---

## &#128295; 常用命令

### 代码质量检查

```bash
# ESLint 检查
pnpm lint              # 检查代码
pnpm lint:fix          # 自动修复

# Prettier 格式化
pnpm format            # 格式化代码
pnpm format:check      # 检查格式

# TypeScript 类型检查
pnpm type-check        # 检查类型
pnpm type-check:watch  # 监听模式

# 综合检查
pnpm quality:check     # 运行所有检查
```

### 测试

```bash
# 运行测试
pnpm test              # 所有测试
pnpm test:unit         # 单元测试
pnpm test:integration  # 集成测试
pnpm test:e2e          # E2E 测试

# 测试监听模式
pnpm test:watch        # 监听模式

# 测试覆盖率
pnpm test:coverage     # 生成覆盖率报告
pnpm test:coverage:check  # 检查覆盖率是否达标
```

### 构建

```bash
# 开发构建
pnpm dev               # 开发服务器

# 生产构建
pnpm build             # 构建生产版本
pnpm build:clean       # 清理并构建
pnpm build:verify      # 验证构建产物
```

---

## &#128202; 质量检查清单

### 提交代码前

- [ ] 代码已通过 ESLint 检查
- [ ] 代码已通过 TypeScript 类型检查
- [ ] 代码已通过 Prettier 格式化
- [ ] 单元测试已添加/更新
- [ ] 所有测试通过
- [ ] 无 console.log 调试代码
- [ ] 提交消息符合规范

### 发布前

- [ ] 所有测试通过
- [ ] 测试覆盖率达标 (≥ 70%)
- [ ] 已在测试环境验证
- [ ] 已在预发布环境验证
- [ ] CHANGELOG 已更新
- [ ] 文档已更新
- [ ] 回滚方案已准备
- [ ] 监控已配置

---

## &#128027; 常见问题

### Q1: Pre-commit Hook 不生效

**问题**: 提交代码时没有运行检查

**解决方案**:
```bash
# 重新初始化 Husky
pnpm exec husky init

# 确保 pre-commit 文件有执行权限
chmod +x .husky/pre-commit

# 检查 Git hooks 目录
ls -la .git/hooks/
```

### Q2: 类型检查失败

**问题**: `pnpm type-check` 报错

**解决方案**:
```bash
# 清理缓存
rm -rf .next node_modules/.cache

# 重新安装依赖
pnpm install

# 再次运行类型检查
pnpm type-check
```

### Q3: 测试覆盖率不达标

**问题**: 测试覆盖率 < 70%

**解决方案**:
1. 为核心业务逻辑添加测试
2. 为 API 路由添加测试
3. 为工具函数添加测试
4. 查看覆盖率报告，补充缺失的测试

```bash
# 查看详细覆盖率报告
pnpm test:coverage

# 打开覆盖率报告
open coverage/index.html  # macOS
xdg-open coverage/index.html  # Linux
```

### Q4: ESLint 报错

**问题**: ESLint 检查失败

**解决方案**:
```bash
# 自动修复
pnpm lint:fix

# 如果自动修复失败，手动修改
# 根据错误信息逐一修复
```

### Q5: Prettier 格式化后代码被 ESLint 报错

**问题**: Prettier 和 ESLint 冲突

**解决方案**:
确保使用 `prettier` 作为 ESLint 的最后一个插件：

```javascript
// eslint.config.mjs
const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  {
    rules: {
      // ... 其他规则
    },
  },
]);
```

---

## &#128218; 进阶使用

### 1. 编写你的第一个测试

创建文件 `src/lib/__tests__/utils.test.ts`:

```typescript
describe('测试示例', () => {
  it('应该通过', () => {
    expect(1 + 1).toBe(2);
  });

it('应该异步通过', async () => {
    const result = await Promise.resolve(42);
    expect(result).toBe(42);
  });
});
```

运行测试:
```bash
pnpm test
```

### 2. 编写你的第一个组件测试

创建文件 `src/components/__tests__/Button.test.tsx`:

```typescript
import { render, screen, fireEvent } from '@testing-library/react';
import '@testing-library/jest-dom';
import Button from '../Button';

describe('Button 组件', () => {
  it('应该渲染按钮', () => {
    render(<Button>点击我</Button>);
    expect(screen.getByText('点击我')).toBeInTheDocument();
  });

it('应该响应点击事件', () => {
    const onClick = jest.fn();
    render(<Button onClick={onClick}>点击我</Button>);

fireEvent.click(screen.getByText('点击我'));
    expect(onClick).toHaveBeenCalledTimes(1);
  });
});
```

### 3. 编写你的第一个 E2E 测试

创建文件 `tests/e2e/home.spec.ts`:

```typescript
import { test, expect } from '@playwright/test';

test('应该访问首页', async ({ page }) => {
  await page.goto('http://localhost:5000');

await expect(page).toHaveTitle(/企业管理数字化中台/);
});
```

运行 E2E 测试:
```bash
pnpm test:e2e
```

---

## &#127919; 效果预期

实施质量保障体系后，你可以期待：

### 短期效果（1-2 周）

- ✅ 代码风格统一
- ✅ 减少 50% 的低级错误
- ✅ 代码提交更规范

### 中期效果（1-2 个月）

- ✅ BUG 数量减少 70%
- ✅ 回归测试自动化
- ✅ 开发信心提升

### 长期效果（3-6 个月）

- ✅ 代码质量显著提升
- ✅ 维护成本大幅降低
- ✅ 团队效率提高

---

## &#128222; 获取帮助

如果遇到问题：

1. 查看文档
   - [质量保障体系](../07-测试质量/README.md)
   - [构建和发布流程](../08-版本管理/README.md)
   - [环境隔离和灰度发布](../02-部署指南/部署指南.md)

2. 查看配置文件
   - `package.json` - 查看脚本命令
   - `jest.config.js` - 查看测试配置
   - `eslint.config.mjs` - 查看 ESLint 配置

3. 在线资源
   - [Jest 官方文档](https://jestjs.io/)
   - [React Testing Library](https://testing-library.com/react)
   - [Playwright 官方文档](https://playwright.dev/)

---

## &#127881; 开始吧！

现在就开始使用质量保障体系吧！

```bash
# 1. 安装工具
bash scripts/install-quality-tools.sh

# 2. 运行第一次检查
pnpm quality:check

# 3. 编写你的第一个测试
# ... 创建测试文件 ...

# 4. 提交代码
git add .
git commit -m "feat: add quality assurance system"
```

祝你的项目质量节节高升！&#128640;