开发指南

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

> **搜索标签**: 开发, 开发流程, 开发规范, 代码规范, 最佳实践
---

# 开发流程使用指南

本文档定义了企业管理数字化中台的开发流程规范，所有开发人员必须严格遵循。

---

**> **文档版本**: v1.0.0  
**创建日期**：2026-01-29  
**最后更新**：2026-01-30  
**维护者**：开发团队

---

## 目录

1. [关键术语定义](#关键术语定义)
2. [开发流程总览](#开发流程总览)
3. [三种开发模式](#三种开发模式)
4. [详细开发步骤](#详细开发步骤)
5. [版本管理规范](#版本管理规范)
6. [开发检查清单](#开发检查清单)
7. [错误处理指南](#错误处理指南)
8. [开发效率技巧](#开发效率技巧)
9. [团队协作规范](#团队协作规范)
10. [常见问题 FAQ](#常见问题-faq)

---

## 关键术语定义

**重要**：以下术语在项目中有明确定义，请确保理解一致：

| 术语 | 定义 | 位置 |
|------|------|------|
| **知识库** | 项目首页的知识库系统，包含开发文档、功能介绍、部署文档等文集 | `/` (首页) |
| **文集** | 知识库中的文档分类，如开发文档文集、功能介绍文集、部署文档文集 | 首页知识库卡片 |
| **项目版本** | 项目开发迭代的版本号，标识每次开发的进度 | `package.json` |
| **系统版本** | 系统产品发布的版本号，标识重大功能发布 | `src/config/version.ts` |
| **项目更新日志** | 记录项目版本（0.1.0）的更新历史 | `/docs/project-changelog` (开发文档文集中) |
| **系统更新日志** | 记录系统版本（v2.0.0）的更新历史 | `/changelogs` (首页更新日志) |

**术语使用说明**：
- 当用户说"发布到知识库"时，指更新项目首页的知识库相关内容
- 当用户说"版本更新"时，需要同时更新项目版本和系统版本
- **项目更新日志**显示在开发文档文集中，记录项目版本历史
- **系统更新日志**显示在首页更新日志页面，记录系统版本历史

---

## 开发流程总览

### 标准开发流程图

```
┌─────────────────┐
│   开始开发任务   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ❌ 有错误      ┌──────────────┐
│  开发前检查     │ ──────────────→   │  修复错误    │
│ pre-dev-check  │                     │  重新检查   │
└────────┬────────┘                     └──────┬───────┘
         │ ✅ 通过                            │
         ▼                                    │
┌─────────────────┐                          │
│  编写代码       │ ─────────────────────────┘
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ❌ 有错误      ┌──────────────┐
│  开发自检       │ ──────────────→   │  修复错误    │
│ post-dev-check │                     │  重新检查   │
└────────┬────────┘                     └──────┬───────┘
         │ ✅ 通过                            │
         ▼                                    │
┌─────────────────┐                          │
│  手动测试       │ ─────────────────────────┘
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  更新文档和版本 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  提交代码       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   开发完成      │
└─────────────────┘
```

### 核心原则

- **开发前**：检查环境，确保一切正常
- **开发中**：遵循规范，编写高质量代码
- **开发后**：自检验证，确保功能正常
- **完成后**：更新文档，提交代码

---

## 三种开发模式

根据任务规模选择合适的开发模式：

### 模式选择决策树

```
你的开发任务是什么？
    │
    ├─ 修复 Bug、小调整
    │   └─→ 快速迭代模式（约 7 分钟）
    │
    ├─ 新增功能、重构
    │   └─→ 完整开发模式（约 20 分钟）
    │
    └─ 系统升级、重大功能
        └─→ 重大发布模式（2-3 天）
```

### 1. 快速迭代模式（⏱️ 约 7 分钟 + 开发时间）

**适用场景**：Bug 修复、样式调整、小功能优化

```bash
# 1. 一键检查（2分钟）
pnpm run pre-dev-check

# 2. 快速开发（根据需求时长）
# - 修改代码
# - 保存查看效果

# 3. 快速验证（3分钟）
pnpm run post-dev-check /your-page-path

# 4. 快速提交（2分钟）
pnpm version patch
git add .
git commit -m "fix: 修复页面bug"
git push
```

**特点**：
- ✅ 快速高效
- ✅ 适用于小改动
- ✅ 仅更新项目版本

---

### 2. 完整开发模式（⏱️ 约 20 分钟 + 开发时间）

**适用场景**：新增功能、代码重构、中等规模开发

```bash
# 1. 开发前检查（2分钟）
pnpm run pre-dev-check

# 2. 详细开发（根据需求时长）
# - 查看相关代码
# - 编写新功能
# - 添加类型定义
# - 处理边界情况

# 3. 完整验证（5分钟）
pnpm run post-dev-check /your-page-path

# 4. 手动测试（5分钟）
# - 测试所有功能点
# - 测试边界情况
# - 测试错误处理
# - 检查浏览器控制台

# 5. 文档更新（5分钟）
# - 更新 doc../08-版本管理/CHANGELOG.md
# - 更新 /docs/project-changelog 页面
# - 更新相关功能文档

# 6. 版本提交（3分钟）
pnpm version minor
git add .
git commit -m "feat: 添加用户注册功能"
git push
```

**特点**：
- ✅ 完整流程
- ✅ 适用于新功能
- ✅ 包含文档更新

---

### 3. 重大发布模式（⏱️ 2-3 天）

**适用场景**：系统升级、重大功能发布、架构变更

```bash
# 1. 前期准备（30分钟）
# - 需求分析
# - 技术方案设计
# - 风险评估
# - 制定测试计划

# 2. 开发实现（根据需求时长）
# - 分阶段开发
# - 每个阶段验证
# - Code Review

# 3. 集成测试（1小时）
# - 功能测试
# - 性能测试
# - 兼容性测试
# - 安全性测试

# 4. 文档完善（30分钟）
# - 更新项目更新日志
# - 更新系统更新日志
# - 更新用户文档
# - 更新 API 文档

# 5. 版本发布（10分钟）
# - 更新项目版本
# - 更新系统版本
# - 打 Tag
# - 推送发布
```

**特点**：
- ✅ 完整流程
- ✅ 适用于重大变更
- ✅ 同时更新项目版本和系统版本
- ✅ 完整的测试和文档

---

## 详细开发步骤

### 第一步：开发前检查（必做）

在开始任何开发工作之前，必须运行开发前检查脚本：

```bash
pnpm run pre-dev-check
```

**检查内容**：
1. ✅ 依赖安装状态（node_modules 完整性）
2. ✅ TypeScript 类型定义（无类型错误）
3. ✅ 数据库连接状态（连接正常）
4. ✅ 端口监听状态（5000 端口可用）
5. ✅ 版本号确认（版本号格式正确）

**如果有错误**：
- 根据错误信息修复问题
- 重新运行检查
- 直到全部通过

**手动检查项**：
```bash
[ ] 依赖已安装（node_modules 完整）
[ ] 数据库连接正常
[ ] 端口 5000 可用
[ ] 当前分支正确
[ ] 远程分支最新（git pull）
[ ] 理解需求内容
[ ] 确认修改位置
```

---

### 第二步：进行开发

按照需求和规范进行开发：

#### 1. 理解需求
- 仔细阅读需求文档
- 不明确的地方及时沟通
- 复述需求确认理解

#### 2. 查看代码
- 查看相关文件和目录结构
- 理解现有代码逻辑
- 参考类似功能的实现

#### 3. 编写代码
- **代码风格**：遵循 Airbnb 规范
- **类型定义**：添加完整的 TypeScript 类型
- **错误处理**：处理所有可能的错误情况
- **注释说明**：添加必要的注释
- **命名规范**：使用清晰的变量和函数命名

#### 4. 开发规范提醒
```typescript
// ✅ 正确：客户端组件
"use client";
import { useState } from "react";

// ✅ 正确：服务端组件
// 不使用 "use client"
// 不使用 Node.js 特定模块

// ✅ 正确：完整类型定义
interface User {
  id: string;
  name: string;
  email: string;
}

// ❌ 错误：未定义类型
const user: any = data;

// ❌ 错误：硬编码
const apiUrl = "http://localhost:5000/api";
// ✅ 正确：使用环境变量
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
```

---

### 第三步：开发自检（必做）

开发完成后，运行开发自检脚本：

```bash
pnpm run post-dev-check /your-page-path
```

**检查内容**：
1. ✅ TypeScript 类型检查（无类型错误）
2. ✅ 构建检查（构建成功）
3. ✅ 日志检查（无错误日志）
4. ✅ 页面响应检查（页面可访问）
5. ✅ 导入错误检查（无未定义引用）
6. ✅ 语法错误检查（无语法错误）

**如果有错误**：
- 查看错误详情
- 修复问题
- 重新运行检查
- 直到全部通过

**手动测试检查**：
```bash
[ ] 类型检查通过
[ ] 构建检查通过
[ ] 日志无错误
[ ] 页面正常访问
[ ] 功能正常工作
[ ] 浏览器控制台无错误
[ ] 移动端显示正常
```

---

### 第四步：更新文档和版本号

开发自检通过后，更新文档和版本号。

#### 1. 更新项目版本（每次开发必须）

```bash
# 修订版本（Bug修复、小优化）
pnpm version patch

# 次版本（新增功能）
pnpm version minor

# 主版本（重大架构变更）
pnpm version major
```

#### 2. 更新项目更新日志（每次开发必须）

**步骤 1**：更新 `doc../08-版本管理/CHANGELOG.md`

```markdown
## [0.3.1] - 2026-01-30

### 新增功能
- 添加用户注册功能
- 实现邮箱验证

### Bug修复
- 修复登录页面样式问题
- 修复 API 返回错误处理

### 改进优化
- 优化数据库查询性能
- 改进用户界面交互
```

**步骤 2**：更新 `/docs/project-changelog` 页面

```typescript
// 编辑 src/app/docs/project-changelog/page.tsx
const changelogs = [
  {
    id: 0,
    version: "0.3.1",
    date: "2026-01-30",
    type: "patch",
    title: "修复登录问题",
    features: ["添加用户注册功能"],
    fixes: ["修复登录页面样式问题"],
    improvements: ["优化数据库查询性能"]
  },
  // ... 其他版本
];
```

#### 3. 更新系统版本（仅重大功能发布时）

**仅当重大功能发布或系统升级时才更新**：

编辑 `src/config/version.ts`：

```typescript
// 更新系统版本号
export const SYSTEM_VERSION = "v2.1.0";

// 添加版本历史
export const VERSION_HISTORY = [
  {
    id: 0,
    version: "v2.1.0",
    date: "2026-01-30",
    type: "minor",
    title: "发布合作伙伴管理功能",
    features: ["新增合作伙伴管理系统", "支持多租户管理"],
    fixes: ["修复工资条发放问题"],
    improvements: ["优化系统性能"]
  },
  // ... 其他版本
];
```

**系统更新日志会自动同步到**：
- ✅ 首页独立更新日志页面（`/changelogs`）
- ✅ 首页知识库（"更新日志"卡片，点击跳转到 `/changelogs`）

#### 4. 同步其他文档（如需要）

- API 变更 → 更新 API 文档
- 数据库变更 → 更新数据库文档
- 功能变更 → 更新功能文档

---

### 第五步：提交代码（必做）

```bash
# 添加所有修改
git add .

# 提交（使用规范的 commit message）
git commit -m "feat: 添加用户注册功能"

# 推送到远程
git push
```

**Commit Message 规范**：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型**：
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 重构
- `docs`: 文档更新
- `style`: 代码格式（不影响功能）
- `test`: 测试相关
- `chore`: 构建/工具

**示例**：
```
feat(user): 添加用户注册功能

- 实现邮箱验证
- 添加密码强度检查
- 集成短信验证码

Closes #123
```

**提交前检查**：
```bash
[ ] 所有检查通过
[ ] 无遗留 TODO
[ ] 无 console.log 调试代码
[ ] 无注释代码
[ ] Commit message 规范
```

---

## 版本管理规范

### 两种版本对比

| 版本类型 | 用途 | 位置 | 格式 | 更新时机 | 记录位置 |
|---------|------|------|------|---------|---------|
| **项目版本** | 项目开发迭代 | `package.json` | `0.1.0` | **每次**开发完成 | `doc../08-版本管理/CHANGELOG.md` + `/docs/project-changelog` |
| **系统版本** | 系统产品发布 | `src/config/version.ts` | `v2.0.0` | **仅**重大功能发布 | `/changelogs` (首页更新日志) |

### 版本更新决策表

| 开发类型 | 项目版本 | 系统版本 | 项目更新日志 | 系统更新日志 | 说明 |
|---------|---------|---------|------------|------------|------|
| Bug修复 | ✅ 更新 | ❌ 不更新 | ✅ 更新 | ❌ 不更新 | 项目日志：记录修复内容 |
| 新增功能 | ✅ 更新 | ❌ 不更新 | ✅ 更新 | ❌ 不更新 | 项目日志：记录新增功能 |
| 代码优化 | ✅ 更新 | ❌ 不更新 | ✅ 更新 | ❌ 不更新 | 项目日志：记录优化内容 |
| 重大功能发布 | ✅ 更新 | ✅ 更新 | ✅ 更新 | ✅ 更新 | 两个日志都要更新 |
| 系统升级 | ✅ 更新 | ✅ 更新 | ✅ 更新 | ✅ 更新 | 两个日志都要更新 |

### 快速判断示例

```bash
# 场景 1：修复一个 Bug
# → 更新项目版本（patch）
# → 更新项目更新日志
pnpm version patch

# 场景 2：新增一个功能
# → 更新项目版本（minor）
# → 更新项目更新日志
pnpm version minor

# 场景 3：发布重大功能（如合作伙伴管理）
# → 更新项目版本（minor）
# → 更新系统版本（minor）
# → 更新项目更新日志
# → 更新系统更新日志
pnpm version minor
# 编辑 src/config/version.ts
```

**重要提示**：
- **项目更新日志**位于 `/docs/project-changelog`，属于开发文档文集
- **系统更新日志**位于 `/changelogs`，首页独立页面
- 首页知识库的"更新日志"卡片会跳转到系统更新日志页面

---

## 开发检查清单

### &#128640; 开发前检查（必做）

```bash
# 1. 自动检查
pnpm run pre-dev-check

# 2. 手动检查
[ ] 依赖已安装（node_modules 完整）
[ ] 数据库连接正常
[ ] 端口 5000 可用
[ ] 当前分支正确
[ ] 远程分支最新（git pull）
[ ] 理解需求内容
[ ] 确认修改位置
```

### &#128221; 开发中检查

**代码质量检查**：
```bash
[ ] 代码风格统一（Airbnb 规范）
[ ] TypeScript 类型完整
[ ] 错误处理完善
[ ] 关键代码有注释
[ ] 组件命名清晰
[ ] 避免硬编码
[ ] 无 console.log 调试代码
```

**功能实现检查**：
```bash
[ ] 需求完整实现
[ ] 边界情况处理
[ ] 空状态处理
[ ] 加载状态处理
[ ] 错误提示友好
[ ] 响应式适配
```

### ✅ 开发自检（必做）

```bash
# 1. 自动检查
pnpm run post-dev-check /your-page-path

# 2. 手动检查
[ ] 类型检查通过
[ ] 构建检查通过
[ ] 日志无错误
[ ] 页面正常访问
[ ] 功能正常工作
[ ] 浏览器控制台无错误
[ ] 移动端显示正常
```

### &#128218; 文档更新（必做）

```bash
# 1. 项目更新日志
[ ] 更新 doc../08-版本管理/CHANGELOG.md
[ ] 更新 /docs/project-changelog 页面

# 2. 系统更新日志（仅重大功能）
[ ] 更新系统版本号（src/config/version.ts）
[ ] 添加版本历史

# 3. 其他文档（如需要）
[ ] 更新功能文档
[ ] 更新 API 文档
[ ] 更新数据库文档
```

### &#128674; 提交检查（必做）

```bash
# 1. 版本更新
[ ] 已运行 pnpm version

# 2. Git 提交
[ ] 添加所有修改（git add .）
[ ] Commit message 规范
[ ] 推送到远程（git push）

# 3. 最终确认
[ ] 所有检查通过
[ ] 无遗留 TODO
[ ] 无 console.log 调试代码
[ ] 无注释代码
```

---

## 错误处理指南

### TypeScript 错误

| 错误类型 | 典型错误 | 解决方案 |
|---------|---------|---------|
| 类型不存在 | `Property 'xxx' does not exist on type 'yyy'` | 添加类型定义或接口 |
| 类型不匹配 | `Argument of type 'xxx' is not assignable to parameter of type 'yyy'` | 检查参数类型，使用类型断言 |
| 未定义引用 | `ReferenceError: xxx is not defined` | 导入缺失的组件或函数 |
| 严格模式错误 | `Object is possibly 'null'` | 添加可选链（`?.`）或空值检查 |

**查看类型错误**：
```bash
npx tsc --noEmit
```

**常见修复示例**：
```typescript
// ❌ 错误：类型不存在
const user = data;
console.log(user.name); // Property 'name' does not exist

// ✅ 正确：定义类型
interface User {
  name: string;
  email: string;
}
const user = data as User;
console.log(user.name);

// ❌ 错误：可能为 null
const result = getResult();
console.log(result.length); // Object is possibly 'null'

// ✅ 正确：可选链
const result = getResult();
console.log(result?.length);

// ✅ 正确：空值检查
const result = getResult();
if (result) {
  console.log(result.length);
}
```

---

### 构建错误

| 错误类型 | 典型错误 | 解决方案 |
|---------|---------|---------|
| 模块未找到 | `Module not found: Can't resolve '@/components/xxx'` | 检查导入路径，确保模块存在 |
| 依赖冲突 | `Cannot resolve module 'xxx'` | 安装缺失依赖 `pnpm add xxx` |
| 语法错误 | `Unexpected token` | 检查语法，修复错误 |
| 类型错误 | `Type 'xxx' is not assignable to type 'yyy'` | 修复类型定义 |

**查看构建错误**：
```bash
pnpm build
```

**常见修复示例**：
```bash
# ❌ 错误：模块未找到
# import { Button } from '@/components/ui/btn'

# ✅ 正确：检查路径
# import { Button } from '@/components/ui/button'

# ❌ 错误：依赖未安装
# Cannot resolve module 'axios'

# ✅ 正确：安装依赖
pnpm add axios
```

---

### 运行时错误

| 错误类型 | 典型错误 | 解决方案 |
|---------|---------|---------|
| 500 错误 | Internal Server Error | 查看日志 `/app/work/logs/bypass/app.log`，检查 API 逻辑 |
| 404 错误 | Not Found | 检查路由配置，确保路径正确 |
| 403 错误 | Forbidden | 检查权限配置，确保用户有权限 |
| 超时错误 | Request timeout | 检查数据库连接，优化查询性能 |

**查看日志**：
```bash
# 查看应用日志
tail -n 50 /app/work/logs/bypass/app.log

# 查看开发日志
tail -n 50 /app/work/logs/bypass/dev.log

# 搜索错误
grep -nE "Error|Exception|Traceback" /app/work/logs/bypass/app.log | tail -n 20
```

---

### 导入错误

**常见错误**：
```
ReferenceError: ComponentName is not defined
```

**解决方案**：
```typescript
// ❌ 错误：未导入
function App() {
  return <Button>Click</Button>;
}

// ✅ 正确：导入组件
import { Button } from "@/components/ui/button";

function App() {
  return <Button>Click</Button>;
}
```

---

## 开发效率技巧

### 1. VS Code 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+P` | 快速打开文件 |
| `Ctrl+Shift+P` | 命令面板 |
| `Alt+↑/↓` | 移动行 |
| `Ctrl+D` | 选择相同的下一个词 |
| `Ctrl+/` | 注释/取消注释 |
| `Ctrl+Shift+F` | 全局搜索 |
| `F12` | 跳转到定义 |
| `Shift+F12` | 查看所有引用 |

---

### 2. 代码片段（Snippets）

**React 组件**：
```typescript
rafce → React Arrow Function Component
```

**常用 Hooks**：
```typescript
useState → useState Hook
useEffect → useEffect Hook
useCallback → useCallback Hook
useMemo → useMemo Hook
```

**自定义片段**：
```json
// .vscode/code-snippets.json
{
  "React Component with Types": {
    "prefix": "rct",
    "body": [
      "interface ${1:Props} {",
      "  ${2:prop}: ${3:string};",
      "}",
      "",
      "export function ${4:ComponentName}({ $2 }: $1) {",
      "  return <div>$0</div>;",
      "}"
    ],
    "description": "React component with TypeScript"
  }
}
```

---

### 3. Git 别名

```bash
# 添加别名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual 'log --graph --oneline --decorate --all'

# 使用别名
git st          # git status
git co main     # git checkout main
git ci -m "xxx" # git commit -m "xxx"
```

---

### 4. pnpm 命令别名

```json
// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "pre-dev-check": "node scripts/pre-dev-check.js",
    "post-dev-check": "node scripts/post-dev-check.js"
  }
}

# 使用别名
pnpm dev              # 开发
pnpm build            # 构建
pnpm type-check       # 类型检查
pnpm pre-dev-check    # 开发前检查
pnpm post-dev-check   # 开发自检
```

---

### 5. 预提交钩子（Pre-commit Hooks）

```bash
# 安装 husky
pnpm add -D husky

# 初始化
pnpm husky install

# 添加钩子
pnpm husky add .husky/pre-commit "pnpm type-check && pnpm lint"
```

---

### 6. 调试技巧

**浏览器控制台**：
```javascript
// 查看组件状态
console.log('Component state:', state);

// 查看网络请求
// 打开 Network 标签，查看请求详情

// 查看性能
// 打开 Performance 标签，录制性能分析

// 查看存储
// 打开 Application 标签，查看 LocalStorage、SessionStorage、Cookies
```

**Node.js 调试**：
```bash
# 启用调试
node --inspect app.js

# VS Code 调试配置
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug App",
      "program": "${workspaceFolder}/app.js"
    }
  ]
}
```

---

## 团队协作规范

### 分支管理策略

```
主分支
├─ main          # 生产环境，稳定版本
└─ develop       # 开发环境，最新功能

功能分支
├─ feature/*     # 功能分支（feature/user-login）
├─ fix/*         # 修复分支（fix/login-bug）
├─ release/*     # 发布分支（release/v2.1.0）
└─ hotfix/*      # 紧急修复分支（hotfix/security-patch）
```

**分支命名规范**：
```bash
# 功能分支
feature/功能描述
feature/add-user-login

# 修复分支
fix/问题描述
fix/login-page-bug

# 发布分支
release/版本号
release/v2.1.0

# 紧急修复分支
hotfix/问题描述
hotfix/security-patch
```

**分支工作流**：
```bash
# 1. 创建功能分支
git checkout -b feature/add-user-login

# 2. 开发功能
# ... 编写代码 ...

# 3. 提交代码
git add .
git commit -m "feat: 添加用户登录功能"

# 4. 推送到远程
git push origin feature/add-user-login

# 5. 创建 Pull Request
# 在 GitLab/GitHub 上创建 PR

# 6. Code Review
# 团队成员审查代码

# 7. 合并到 develop
git checkout develop
git merge feature/add-user-login

# 8. 删除功能分支
git branch -d feature/add-user-login
git push origin --delete feature/add-user-login
```

---

### Commit Message 规范

**格式**：
```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型**：
| Type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(user): 添加用户注册功能` |
| `fix` | Bug 修复 | `fix(auth): 修复登录失败问题` |
| `refactor` | 重构 | `refactor(api): 重构用户 API` |
| `docs` | 文档更新 | `docs(readme): 更新使用说明` |
| `style` | 代码格式 | `style(button): 调整按钮样式` |
| `test` | 测试相关 | `test(user): 添加用户测试` |
| `chore` | 构建/工具 | `chore(deps): 更新依赖版本` |

**完整示例**：
```
feat(user): 添加用户注册功能

- 实现邮箱验证功能
- 添加密码强度检查
- 集成短信验证码
- 优化注册流程

Closes #123
```

**禁止的示例**：
```
# ❌ 错误：缺少类型
添加用户注册功能

# ❌ 错误：缺少描述
feat: update

# ❌ 错误：使用不规范的类型
update: 修改代码
```

---

### Code Review 检查点

**代码质量检查**：
```markdown
## 代码质量
- [ ] 代码风格统一（遵循 Airbnb 规范）
- [ ] 命名清晰规范
- [ ] 注释充分
- [ ] 无重复代码
- [ ] 无死代码
- [ ] 无硬编码
- [ ] 无 console.log 调试代码
```

**功能实现检查**：
```markdown
## 功能实现
- [ ] 需求完整实现
- [ ] 边界情况处理
- [ ] 错误处理完善
- [ ] 性能优化
- [ ] 安全性考虑
- [ ] 可维护性良好
```

**测试覆盖检查**：
```markdown
## 测试覆盖
- [ ] 单元测试
- [ ] 集成测试
- [ ] 端到端测试
- [ ] 边界测试
- [ ] 错误场景测试
```

**文档更新检查**：
```markdown
## 文档更新
- [ ] 代码注释充分
- [ ] API 文档更新
- [ ] 用户文档更新
- [ ] 更新日志更新
```

---

### Pull Request 规范

**PR 标题**：
```
<type>: 简短描述

示例：
feat: 添加用户注册功能
fix: 修复登录失败问题
```

**PR 描述模板**：
```markdown
## 变更说明
简要描述本次变更的内容

## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 代码重构
- [ ] 文档更新
- [ ] 其他

## 测试
描述如何测试本次变更

## 截图（如适用）
添加截图或录屏

## 相关 Issue
Closes #123

## 检查清单
- [ ] 代码风格符合规范
- [ ] 已添加单元测试
- [ ] 已更新文档
- [ ] 已通过自检
```

---

## 常见问题 FAQ

### Q1: 开发前检查失败怎么办？

**A**: 按照错误提示修复：

```bash
# 1. 查看错误详情
pnpm run pre-dev-check

# 2. 根据错误类型修复
# - 依赖问题：运行 pnpm install
# - 类型错误：修复类型定义
# - 数据库问题：检查数据库连接
# - 端口问题：关闭占用端口的进程

# 3. 重新检查
pnpm run pre-dev-check
```

---

### Q2: 开发自检时提示页面路径错误？

**A**: 确保传入正确的页面路径：

```bash
# ❌ 错误：缺少路径
pnpm run post-dev-check

# ❌ 错误：路径错误
pnpm run post-dev-check /wrong-path

# ✅ 正确：传入页面路径
pnpm run post-dev-check /user/profile

# ✅ 正确：API 路由不需要路径
pnpm run post-dev-check
```

---

### Q3: 什么时候更新系统版本？

**A**: 仅在以下情况更新系统版本：

- ✅ 重大功能发布（如新增合作伙伴管理系统）
- ✅ 系统架构升级
- ✅ 安全漏洞修复
- ❌ 日常 Bug 修复（只更新项目版本）
- ❌ 小功能优化（只更新项目版本）

**示例**：
```bash
# 日常开发
pnpm version patch  # 只更新项目版本

# 重大发布
pnpm version minor  # 更新项目版本
# 编辑 src/config/version.ts  # 更新系统版本
```

---

### Q4: 如何处理类型错误？

**A**: 按以下步骤处理：

```bash
# 1. 查看类型错误
npx tsc --noEmit

# 2. 根据错误类型修复

# 类型不存在
# ❌ Property 'xxx' does not exist
# ✅ 添加类型定义

# 类型不匹配
# ❌ is not assignable to
# ✅ 使用类型断言 or 修改类型定义

# 可能为 null
# ❌ Object is possibly 'null'
# ✅ 添加可选链 (?.) or 空值检查

# 3. 重新检查
npx tsc --noEmit
```

---

### Q5: 开发流程中可以跳过检查吗？

**A**: **绝对不可以！**

**原因**：
- 检查确保代码质量
- 检查避免引入 Bug
- 检查保持代码一致性
- 跳过检查可能导致严重问题

**正确做法**：
```bash
# ✅ 正确：完整流程
pnpm run pre-dev-check
# ... 开发 ...
pnpm run post-dev-check /path
# ... 更新文档 ...
pnpm version patch
git commit -m "feat: xxx"
git push

# ❌ 错误：跳过检查
# 直接提交代码
git add .
git commit -m "feat: xxx"  # 禁止！
git push
```

---

### Q6: 如何选择开发模式？

**A**: 根据任务规模选择：

```
小任务（Bug 修复、样式调整）
→ 快速迭代模式（约 7 分钟）

中任务（新增功能、重构）
→ 完整开发模式（约 20 分钟）

大任务（系统升级、重大功能）
→ 重大发布模式（2-3 天）
```

---

### Q7: 如何快速定位错误？

**A**: 按以下优先级查看日志：

```bash
# 1. 浏览器控制台（前端问题）
# 打开开发者工具 → Console 标签

# 2. 应用日志（后端问题）
tail -n 50 /app/work/logs/bypass/app.log

# 3. 开发日志（调试信息）
tail -n 50 /app/work/logs/bypass/dev.log

# 4. 搜索错误关键词
grep -nE "Error|Exception|Traceback" /app/work/logs/bypass/app.log | tail -n 20
```

---

### Q8: 如何处理数据库迁移？

**A**: 按以下步骤操作：

```bash
# 1. 修改 schema
# 编辑 src/db/schema.ts

# 2. 生成迁移
pnpm drizzle-kit generate

# 3. 查看生成的迁移文件
# 检查 drizzle 目录下的迁移文件

# 4. 运行迁移
pnpm drizzle-kit push

# 5. 验证迁移
# 检查数据库结构是否正确
```

---

### Q9: 如何优化开发效率？

**A**: 遵循以下建议：

```bash
# 1. 频繁保存，分步验证
# 不要等所有代码写完才测试

# 2. 使用快捷键和代码片段
# 提升编码速度

# 3. 遵循开发流程
# 避免反复修复

# 4. 保持代码整洁
# 便于维护和调试

# 5. 使用 Git 分支
# 并行开发多个功能
```

---

### Q10: 如何处理紧急 Bug 修复？

**A**: 使用 hotfix 分支：

```bash
# 1. 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/security-patch

# 2. 修复 Bug
# ... 修复代码 ...

# 3. 测试
pnpm run post-dev-check

# 4. 合并到 main 和 develop
git checkout main
git merge hotfix/security-patch
git checkout develop
git merge hotfix/security-patch

# 5. 删除分支
git branch -d hotfix/security-patch
```

---

## 附录

### A. 快捷命令参考

```bash
# 开发检查
pnpm run pre-dev-check        # 开发前检查
pnpm run post-dev-check      # 开发自检

# 类型检查
npx tsc --noEmit             # TypeScript 类型检查
pnpm type-check              # 类型检查别名

# 构建和运行
pnpm build                   # 构建生产版本
pnpm dev                     # 启动开发服务器
pnpm start                   # 启动生产服务器

# 测试
pnpm test                    # 运行测试
pnpm lint                    # 代码检查

# 版本管理
pnpm version patch           # 修订版本（Bug 修复）
pnpm version minor           # 次版本（新功能）
pnpm version major           # 主版本（重大变更）

# Git 常用
git status                   # 查看状态
git add .                    # 添加所有修改
git commit -m "xxx"          # 提交
git push                     # 推送
git pull                     # 拉取
git checkout -b branch-name  # 创建并切换分支
```

---

### B. 推荐插件和工具

**VS Code 插件**：
- ESLint - 代码检查
- Prettier - 代码格式化
- TypeScript - TypeScript 支持
- Tailwind CSS IntelliSense - Tailwind 提示
- GitLens - Git 增强
- Auto Rename Tag - 自动重命名标签
- Path Intellisense - 路径提示

**开发工具**：
- Drizzle Kit - 数据库 ORM 工具
- TypeScript - 类型系统
- ESLint - 代码检查
- Prettier - 代码格式化
- Husky - Git 钩子

---

### C. 相关文档

- [项目需求文档](../10-平台规划/README.md)
- [项目更新日志](../08-版本管理/CHANGELOG.md)
- [版本管理规范](../08-版本管理/README.md)
- [API 文档](../../src/app/docs/dev/api/page.tsx)
- [数据库文档](../../src/app/docs/dev/database/page.tsx)

---

## 总结

遵循开发流程规范可以：

✅ **提高代码质量**  
✅ **减少错误率**  
✅ **提升开发效率**  
✅ **保持代码一致性**  
✅ **便于团队协作**

**核心原则**：
- 开发前：检查环境
- 开发中：遵循规范
- 开发后：自检验证
- 完成后：更新文档

---

**> **文档版本**: v1.0.0  
**创建日期**：2026-01-29  
**最后更新**：2026-01-30  
**维护者**：开发团队