开发流程

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

> **搜索标签**: 开发流程, 工作流, 开发规范, 开发步骤
---

# 开发流程规范

本文档定义了开发流程的标准操作步骤，确保开发质量和效率。

## &#128640; 快速参考：版本管理规则

> **开发完成后必须更新项目版本，重大功能发布时更新系统版本**

| 开发类型 | 项目版本<br/>（package.json） | 系统版本<br/>（version.ts） | 项目更新日志<br/>（开发文档） | 系统更新日志<br/>（首页） |
|---------|--------------------------|-------------------------|------------------------|---------------------|
| Bug修复 | ✅ 0.3.0 → 0.3.1 | ❌ | ✅ 更新 | ❌ |
| 新增功能 | ✅ 0.3.0 → 0.4.0 | ❌ | ✅ 更新 | ❌ |
| 代码优化 | ✅ 0.3.0 → 0.3.1 | ❌ | ✅ 更新 | ❌ |
| 重大发布 | ✅ 0.4.0 → 0.5.0 | ✅ v2.0 → v2.1 | ✅ 更新 | ✅ 更新 |

**关键点**：
- **项目版本**：记录开发迭代，每次开发都更新
- **系统版本**：记录产品发布，仅重大功能发布时更新
- **版本同步**：系统版本号自动同步到首页和管理后台

详细说明见"版本管理说明"章节。

## 开发流程总览

```
需求分析 → 开发前检查 → 开发实现 → 开发自检 → 自动化验证 → 更新文档 → 完成
```

## 版本管理说明

系统中存在两种版本，需要区分管理：

### 1. 项目版本（NPM包版本）
- **定义**：标识项目开发迭代
- **位置**：`package.json` 中的 `version` 字段
- **格式**：`0.1.0`、`0.2.0`、`0.3.0`（不使用 v 前缀）
- **用途**：依赖管理、发布 NPM 包
- **更新时机**：**每次**功能开发、Bug修复、代码优化
- **记录位置**：
  - `docs/PROJECT_CHANGELOG.md`（文档）
  - `/docs/project-changelog`（页面）
- **示例**：`0.3.0` → `0.3.1`（修复Bug）

### 2. 系统版本（产品版本）
- **定义**：标识系统产品发布
- **位置**：`src/config/version.ts` 中的 `SYSTEM_VERSION`
- **格式**：`v2.0.0`、`v2.1.0`、`v2.0.1`（使用 v 前缀）
- **用途**：面向用户和客户的版本号
- **更新时机**：**仅**重大功能发布、系统升级、重要改进
- **显示位置**：
  - 首页知识库（"更新日志"卡片）
  - 管理后台（自动同步，从 `src/config/version.ts` 导入）
- **示例**：`v2.0.0` → `v2.1.0`（新增重要功能模块）

### 3. 版本更新决策树

```
开发完成
  │
  ├─ 是否是重大功能发布或系统升级？
  │    ├─ 是 → 更新系统版本（src/config/version.ts）
  │    │        - 修改 SYSTEM_VERSION
  │    │        - 添加 VERSION_HISTORY 记录
  │    │        - 版本号自动同步到首页和管理后台
  │    │
  │    └─ 否 → 不更新系统版本
  │
  └─ 是否有代码变更？
       ├─ 是 → 更新项目版本（package.json）
       │        - 运行 pnpm version patch/minor/major
       │        - 更新 docs/PROJECT_CHANGELOG.md
       │        - 更新 /docs/project-changelog 页面
       │
       └─ 否 → 不更新版本
```

### 4. 实际案例

**案例1：修复一个小Bug**
- ✅ 更新项目版本：`0.3.0` → `0.3.1`
- ✅ 更新项目更新日志：记录Bug修复详情
- ❌ 不更新系统版本

**案例2：开发一个新的功能模块**
- ✅ 更新项目版本：`0.3.1` → `0.4.0`
- ✅ 更新项目更新日志：记录新功能开发
- ❌ 不更新系统版本

**案例3：发布包含多个新功能的正式版本**
- ✅ 更新项目版本：`0.4.0` → `0.5.0`
- ✅ 更新项目更新日志：记录详细开发历史
- ✅ 更新系统版本：`v2.0.0` → `v2.1.0`
- ✅ 更新系统更新日志：记录版本发布信息

### 5. 版本号自动同步机制

**系统版本号同步**（已实现）：
```typescript
// src/config/version.ts
export const SYSTEM_VERSION = "v2.0.7";

// 首页导入并显示
import { SYSTEM_VERSION } from "@/config/version";

// 管理后台导入并显示（待实现）
import { SYSTEM_VERSION } from "@/config/version";
```

当修改 `src/config/version.ts` 中的 `SYSTEM_VERSION` 后：
- ✅ 首页知识库自动显示最新版本号
- ✅ 系统更新日志自动显示最新版本历史
- ⏳ 管理后台需要在页面中导入并显示（待实现）

## 一、开发前检查清单

在开始任何开发工作之前，必须执行以下检查：

### 1.1 需求理解
- [ ] 完整阅读需求描述
- [ ] 识别关键词和核心要求
- [ ] 不明确的地方已向用户确认
- [ ] 复述需求并获得确认

### 1.2 上下文分析
- [ ] 查看相关代码文件
- [ ] 理解现有架构和模式
- [ ] 确认修改位置和影响范围
- [ ] 参考类似功能的实现

### 1.3 环境检查
- [ ] 确认项目版本号（package.json）
- [ ] 确认系统版本号（src/config/version.ts）
- [ ] 检查数据库连接状态
- [ ] 检查依赖是否完整

### 1.4 数据库状态检查（如涉及数据库）
```bash
# 检查数据库连接
curl -I http://localhost:5000/api/health

# 查看数据库表结构（如需要）
pnpm drizzle-kit generate
```

- [ ] 数据库连接正常
- [ ] 相关表结构已确认
- [ ] 数据迁移脚本已准备（如需要）

### 1.5 依赖检查
```bash
# 检查依赖安装
pnpm install

# 检查类型定义
pnpm ts-check
```

- [ ] 所有依赖已安装
- [ ] 无类型错误
- [ ] 无缺失依赖

## 二、开发实现阶段

### 2.1 代码编写规范
- [ ] 遵循项目代码风格
- [ ] 使用 TypeScript 类型定义
- [ ] 添加必要的注释
- [ ] 遵循单一职责原则

### 2.2 组件规范
- [ ] 客户端组件标记 `"use client"`
- [ ] 服务端组件不使用 Node.js 模块（fs, path等）
- [ ] Props 类型定义完整
- [ ] 错误边界处理

### 2.3 API 规范（如涉及）
- [ ] 遵循 RESTful 设计
- [ ] 请求参数验证
- [ ] 错误处理完整
- [ ] 返回格式统一

### 2.4 数据库规范（如涉及）
- [ ] 使用 Manager 模式
- [ ] SQL 查询优化
- [ ] 添加必要的索引
- [ ] 事务处理正确

## 三、开发后自检清单

开发完成后，必须执行以下自检：

### 3.1 语法检查
```bash
# TypeScript 类型检查
npx tsc --noEmit

# 如果有错误，必须修复
```

- [ ] 无 TypeScript 类型错误
- [ ] 无语法错误
- [ ] 无未使用的变量

### 3.2 导入检查
- [ ] 所有导入的组件已使用
- [ ] 所有导入的模块正确
- [ ] 无循环依赖

### 3.3 路径检查
- [ ] 所有文件路径正确
- [ ] 相对路径合理
- [ ] 绝对路径使用正确

### 3.4 功能验证
- [ ] 页面能正常访问
- [ ] 功能按需求实现
- [ ] 交互逻辑正确
- [ ] 错误处理有效

### 3.5 日志检查
```bash
# 查看最新日志
tail -n 20 /app/work/logs/bypass/app.log
```

- [ ] 无错误日志
- [ ] 无警告日志（或警告已说明）
- [ ] 性能日志正常

### 3.6 构建检查
```bash
# 运行构建
pnpm build

# 构建必须成功
```

- [ ] 构建成功
- [ ] 无构建错误
- [ ] 无构建警告

## 四、自动化验证

### 4.1 页面访问测试
```bash
# 检查页面响应
curl -I http://localhost:5000/your-page-path
```

- [ ] HTTP 状态码 200
- [ ] 无 500 错误
- [ ] 页面加载正常

### 4.2 API 测试（如涉及）
```bash
# 测试 API 端点
curl -X GET http://localhost:5000/api/your-endpoint
```

- [ ] API 响应正常
- [ ] 返回数据格式正确
- [ ] 错误处理有效

## 五、文档更新

### 5.1 版本管理规范

系统中有两种版本需要区分管理：

#### 5.1.1 项目版本（NPM包版本）
- **位置**：`package.json` 中的 `version` 字段
- **用途**：标识项目开发迭代，用于依赖管理和发布
- **更新时机**：每次功能开发、Bug修复、代码优化
- **版本格式**：`0.1.0`（不使用 v 前缀）
- **记录位置**：`docs/PROJECT_CHANGELOG.md` 和 `/docs/project-changelog` 页面

#### 5.1.2 系统版本（产品版本）
- **位置**：`src/config/version.ts` 中的 `SYSTEM_VERSION` 和 `VERSION_HISTORY`
- **用途**：标识系统产品发布，面向用户和客户
- **更新时机**：重大功能发布、系统升级、重要改进
- **版本格式**：`v2.0.0`（使用 v 前缀）
- **显示位置**：首页知识库 + 管理后台（自动同步）

### 5.2 完成前自动更新流程

#### 5.2.1 更新项目版本和日志
```bash
# 1. 更新项目版本号（package.json）
pnpm version patch  # 或 minor/major

# 2. 更新项目更新日志文档
# 编辑 docs/PROJECT_CHANGELOG.md，在开头添加新的版本记录

# 3. 更新项目更新日志页面（/docs/project-changelog）
# 编辑 src/app/docs/project-changelog/page.tsx，更新 changelogs 数据
```

#### 5.2.2 更新系统版本和日志（如需要）
```bash
# 1. 更新系统版本号（src/config/version.ts）
# 编辑 SYSTEM_VERSION = "v2.0.x"

# 2. 更新系统版本历史
# 在 VERSION_HISTORY 数组开头添加新的版本记录
```

**注意**：
- 项目版本和系统版本是独立的，需要根据实际变更分别更新
- 不是每次开发都需要更新系统版本，只有重大功能发布时才更新
- 项目版本每次开发都应该更新，记录开发迭代历史

### 5.3 文档同步
- [ ] 更新相关文档
- [ ] 更新 API 文档（如涉及）
- [ ] 更新数据库文档（如涉及）
- [ ] 确认版本号已正确同步到首页和管理后台

## 六、完成标准

开发任务完成的条件：

- [ ] ✅ 所有检查项已完成
- [ ] ✅ 所有测试通过
- [ ] ✅ 无已知错误
- [ ] ✅ 文档已更新
- [ ] ✅ 版本号已更新

## 七、常见错误避免

### 7.1 客户端/服务端混用
❌ 错误：在客户端组件中使用 `fs` 模块
```tsx
"use client"
import { readFileSync } from "fs" // 错误！
```

✅ 正确：使用服务端组件
```tsx
// 没有 "use client"
import { readFileSync } from "fs" // 正确
```

### 7.2 缺少导入
❌ 错误：使用了未导入的组件
```tsx
<Card className="..."> {/* Card 未导入 */}
```

✅ 正确：导入所有需要的组件
```tsx
import { Card } from "@/components/ui/card"
<Card className="...">
```

### 7.3 类型错误
❌ 错误：未定义类型
```tsx
function processData(data: any) { ... }
```

✅ 正确：定义类型
```tsx
interface UserData {
  id: string;
  name: string;
}
function processData(data: UserData) { ... }
```

## 八、自动化脚本

### 开发前检查脚本
```bash
#!/bin/bash
# scripts/pre-dev-check.sh

echo "&#128269; 开发前检查..."

# 检查依赖
echo "&#128230; 检查依赖..."
pnpm install

# 检查类型
echo "&#128295; 检查类型定义..."
pnpm ts-check

# 检查数据库
echo "&#128452;️  检查数据库连接..."
curl -I http://localhost:5000/api/health

echo "✅ 开发前检查完成"
```

### 开发自检脚本
```bash
#!/bin/bash
# scripts/post-dev-check.sh

echo "&#128269; 开发自检..."

# 类型检查
echo "&#128295; TypeScript 类型检查..."
npx tsc --noEmit

# 构建检查
echo "&#127959;️  构建检查..."
pnpm build

# 日志检查
echo "&#128203; 查看最新日志..."
tail -n 20 /app/work/logs/bypass/app.log

echo "✅ 开发自检完成"
```

## 九、快速参考

### 开发前检查（5分钟）
1. 理解需求
2. 查看代码
3. 检查环境
4. 确认数据库
5. 检查依赖

### 开发实现（根据复杂度）
1. 编写代码
2. 遵循规范
3. 添加类型
4. 处理错误

### 开发自检（5分钟）
1. 类型检查
2. 导入检查
3. 功能测试
4. 日志检查
5. 构建检查

### 文档更新（3分钟）
1. 更新日志
2. 更新版本号
3. 同步文档

---

**文档版本**：v1.0.0
**创建日期**：2026-01-29
**维护者**：开发团队