开发规范

## 开发流程规范

### 🚀 快速参考

本项目的完整开发流程规范请参考：**[开发流程使用指南](/docs/development-guide)**

以下是核心内容的快速参考：

#### 三种开发模式

| 模式 | 适用场景 | 耗时 |
|------|---------|------|
| **快速迭代模式** | Bug修复、小调整 | 约7分钟 |
| **完整开发模式** | 新增功能、重构 | 约20分钟 |
| **重大发布模式** | 系统升级、重大功能 | 2-3天 |

#### 标准开发流程（简化版）

```bash
# 1. 开发前检查（可选）
pnpm run pre-dev-check

# 2. 进行开发
# ... 编写代码 ...

# 3. 开发自检（可选）
pnpm run post-dev-check /your-page-path

# 4. 提交代码
git add .
git commit -m "feat: 添加新功能"
git push

# 5. [仅重大发布] 更新系统版本
# 编辑 src/config/version.ts
# 更新 SYSTEM_VERSION 和 VERSION_HISTORY
git add src/config/version.ts
git commit -m "feat: 发布 v2.x.x"
git push
```

#### 版本管理规则（简化）

| 开发类型 | 系统版本 | 知识库 | 耗时 |
|---------|---------|--------|------|
| Bug修复 | ❌ 不更新 | ❌ 不导入 | 30秒 |
| 小功能优化 | ❌ 不更新 | ❌ 不导入 | 30秒 |
| 重大功能发布 | ✅ 更新 | ❌ 不导入 | 2分钟 |
| 系统重大升级 | ✅ 更新 | ✅ 导入（可选） | 5分钟 |

### 📚 详细文档

完整的开发流程规范包含以下内容：

1. **关键术语定义** - 知识库、文集、项目版本、系统版本等
2. **开发流程总览** - 可视化流程图和核心原则
3. **三种开发模式** - 快速迭代、完整开发、重大发布
4. **详细开发步骤** - 开发前、开发中、开发后、提交
5. **版本管理规范** - 项目版本和系统版本管理
6. **开发检查清单** - 完整的检查项清单
7. **错误处理指南** - TypeScript、构建、运行时错误
8. **开发效率技巧** - 快捷键、代码片段、调试技巧
9. **团队协作规范** - 分支管理、Commit规范、Code Review
10. **常见问题FAQ** - 10个常见问题及解答

**查看完整文档**：[开发流程使用指南 v2.0.0](/docs/development-guide)
    

## 版本号规范

### 🎯 快速参考

本项目采用**双版本管理策略**：

| 版本类型 | 格式示例 | 位置 | 更新时机 |
|---------|---------|------|---------|
| **项目版本** | `0.1.0` | `package.json` | 每次开发完成 |
| **系统版本** | `v2.0.0` | `src/config/version.ts` | 仅重大功能发布 |

### 📊 版本管理规则

> ⚡ **简化后的流程（2026-02-03起）**
> 只需更新 `src/config/version.ts` 即可，其他全部自动同步！

#### 系统版本（src/config/version.ts）- 唯一真相来源

- **格式**：`v2.0.0`（有 v 前缀）
- **用途**：标识系统产品发布，面向用户和客户
- **更新时机**：
  - **重大功能发布**：新模块、重要功能 → 更新系统版本
  - **系统升级**：架构变更、性能优化 → 更新系统版本
  - **日常开发**：Bug修复、小功能 → 不更新系统版本（仅git commit即可）
- **更新方式**：
  ```typescript
  // 编辑 src/config/version.ts
  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: ["优化系统性能"]
    }
  ];
  ```
- **显示位置**：
  - 首页 `/` - 版本号 Badge
  - 更新日志 `/changelogs` - 完整版本历史
  - 管理后台 - 自动同步

#### 项目版本（package.json）- 可选
- **格式**：`0.1.0`（无 v 前缀）
- **更新时机**：**按需更新**（可选）
- **更新命令**：`pnpm version patch/minor/major`
- **说明**：如需NPM发布才需要，否则可忽略

### 🎨 语义化版本号格式

系统采用语义化版本控制（Semantic Versioning），格式为：`v主版本号.次版本号.修订版本号`

| 版本号 | 触发条件 | 示例 |
|-------|---------|------|
| **主版本号（Major）** | 重大架构变更或不兼容更新 | v1.0.0 → v2.0.0 |
| **次版本号（Minor）** | 新增功能模块或重要功能更新 | v2.0.0 → v2.1.0 |
| **修订版本号（Patch）** | Bug修复、小功能优化 | v2.0.0 → v2.0.1 |

### 📝 版本更新示例

#### 场景1：修复一个小Bug（日常开发）
```bash
# 不更新版本号
# 直接提交代码
git add .
git commit -m "fix: 修复登录失败问题"
git push
```

#### 场景2：发布新功能（重大发布）
```bash
# 1. 编辑 src/config/version.ts
export const SYSTEM_VERSION = "v2.1.0";

export const VERSION_HISTORY = [
  {
    id: 0,
    version: "v2.1.0",
    date: "2026-02-03",
    type: "minor",
    title: "发布新功能",
    features: ["功能1", "功能2"],
    fixes: [],
    improvements: []
  },
  // ... 历史版本 ID 依次递增
];

# 2. 提交代码
git add src/config/version.ts
git commit -m "feat: 发布 v2.1.0 - 发布新功能"
git push

# 完成！首页自动显示最新版本
```

### 📚 详细文档

**查看完整文档**：[开发流程使用指南 v2.0.0 - 版本管理规范](/docs/development-guide#版本管理规范)
    

## 代码规范

### 🎯 快速参考

本项目遵循 **Airbnb 代码规范**，使用 **TypeScript 5** 进行开发。

### 📝 TypeScript 规范

#### 命名规范
- **变量名**：camelCase，如 `userName`, `isLoading`
- **常量**：UPPER_SNAKE_CASE，如 `SYSTEM_VERSION`, `API_BASE_URL`
- **类型/接口**：PascalCase，如 `User`, `ApiResponse`
- **枚举**：PascalCase，成员使用 UPPER_SNAKE_CASE
- **文件名**：kebab-case，如 `user-service.ts`, `api-client.ts`

#### 组件规范
- **函数组件**：使用 React Hooks，避免类组件
- **Props 类型**：定义明确的 TypeScript 接口
- **默认值**：使用默认参数

```typescript
interface UserCardProps {
  name: string;
  avatar?: string;
  onClick?: () => void;
}

export function UserCard({ name, avatar, onClick }: UserCardProps) {
  return <div>{name}</div>;
}
```

#### Hooks 规范
- **自定义 Hook**：以 `use` 开头，如 `useAuth`, `useApi`
- **依赖数组**：完整声明所有依赖

```typescript
// ✅ 正确
useEffect(() => {
  fetchData(userId, type);
}, [userId, type]);

// ❌ 错误 - 缺少依赖
useEffect(() => {
  fetchData(userId, type);
}, [userId]);
```

### 🔧 Next.js 规范

#### 客户端/服务端组件
- **客户端组件**：使用 `"use client"` 指令
- **服务端组件**：不使用 `"use client"`，默认为服务端
- **Node.js 模块**：仅在服务端组件中使用

```typescript
// ✅ 正确 - 客户端组件
"use client";
import { useState } from "react";

export function ClientComponent() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

// ✅ 正确 - 服务端组件
// 没有 "use client"
import { readFileSync } from "fs";

export function ServerComponent() {
  const data = readFileSync("data.txt", "utf-8");
  return <div>{data}</div>;
}
```

#### 路由规范
- **App Router**：使用 `app` 目录结构
- **动态路由**：使用 `[param]` 语法
- **路由组**：使用 `(group)` 语法

```
app/
├── (auth)/
│   ├── login/
│   │   └── page.tsx
│   └── register/
│       └── page.tsx
├── dashboard/
│   └── [id]/
│       └── page.tsx
└── layout.tsx
```

### 📦 React 规范

#### Hooks 使用
- **useState**：管理组件状态
- **useEffect**：处理副作用
- **useCallback**：优化函数引用
- **useMemo**：优化计算结果
- **useContext**：访问上下文

```typescript
import { useState, useEffect, useCallback } from "react";

export function ExampleComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);

  const fetchData = useCallback(async () => {
    setLoading(true);
    const response = await fetch("/api/data");
    const json = await response.json();
    setData(json);
    setLoading(false);
  }, []);

  useEffect(() => {
    fetchData();
  }, [fetchData]);

  return <div>{loading ? "Loading..." : JSON.stringify(data)}</div>;
}
```

### 🎨 样式规范

#### Tailwind CSS
- 使用 utility-first 的 CSS 类
- 优先使用 Tailwind 内置工具类
- 复杂样式使用 `style` 属性

```typescript
// ✅ 正确 - 使用 Tailwind
export function Card({ title, content }: { title: string; content: string }) {
  return (
    <div className="p-4 bg-white rounded-lg shadow-md">
      <h2 className="text-xl font-bold mb-2">{title}</h2>
      <p className="text-gray-600">{content}</p>
    </div>
  );
}

// ✅ 正确 - 复杂样式使用 style
export function CustomComponent() {
  return (
    <div style={{ backgroundColor: "rgba(0,0,0,0.5)" }}>
      Content
    </div>
  );
}
```

### 🗂️ 文件组织

#### 目录结构
```
src/
├── app/              # Next.js App Router
│   ├── (auth)/      # 路由组
│   ├── api/         # API 路由
│   ├── dashboard/   # 页面
│   └── layout.tsx   # 根布局
├── components/      # React 组件
│   ├── ui/         # UI 组件
│   └── features/   # 功能组件
├── hooks/          # 自定义 Hooks
├── lib/            # 工具函数
├── types/          # TypeScript 类型
└── utils/          # 辅助函数
```

### 📚 详细文档

**查看完整文档**：[开发流程使用指南 v2.0.0 - 错误处理指南](/docs/development-guide#错误处理指南)

**参考资源**：
- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)
- [Next.js 官方文档](https://nextjs.org/docs)
- [Tailwind CSS 官方文档](https://tailwindcss.com/docs)
- [Airbnb JavaScript 规范](https://github.com/airbnb/javascript)
    

## 提交规范

### 🎯 快速参考

本项目遵循 **Conventional Commits** 规范，使用规范的 Git 提交信息。

### 📝 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
```

```
fix(auth): 修复登录失败问题

修复了当用户输入错误密码时无法正确显示错误信息的问题

Fixes #456
```

```
docs(readme): 更新安装说明

- 添加 pnpm 安装步骤
- 更新环境变量配置说明
```

### ❌ 错误示例

```
# ❌ 错误：缺少类型
添加用户注册功能

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

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

# ❌ 错误：subject 过长
feat(user): 添加用户注册功能并实现邮箱验证和密码强度检查以及短信验证码集成
```

### 📐 Subject 规则

- 使用现在时态，如 `添加` 而不是 `添加了` 或 `已添加`
- 首字母小写
- 不以句号（`.`）结尾
- 限制在 50 个字符以内

### 📝 Body 规则

- 使用现在时态
- 应该说明 `是什么` 和 `为什么`，而不是 `怎么做`
- 每行限制在 72 个字符以内

### 🔗 Footer 规则

- 引用相关 Issue：`Closes #123` 或 `Fixes #456`
- 可以引用多个 Issue：`Closes #123, #456, #789`

### 🛠️ 实际使用

#### 新功能开发
```bash
# 1. 开发功能
# ... 编写代码 ...

# 2. 更新项目版本
pnpm version minor

# 3. 更新项目更新日志
# 编辑 docs/PROJECT_CHANGELOG.md

# 4. 提交代码
git add .
git commit -m "feat(user): 添加用户注册功能"
git push
```

#### Bug 修复
```bash
# 1. 修复 Bug
# ... 修复代码 ...

# 2. 更新项目版本
pnpm version patch

# 3. 更新项目更新日志
# 编辑 docs/PROJECT_CHANGELOG.md

# 4. 提交代码
git add .
git commit -m "fix(auth): 修复登录失败问题"
git push
```

### 📚 详细文档

**查看完整文档**：[开发流程使用指南 v2.0.0 - 团队协作规范](/docs/development-guide#团队协作规范)

**参考资源**：
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Commitlint](https://commitlint.js.org/)
    

## API 设计规范

### 🎯 快速参考

本项目 API 遵循 **RESTful 设计原则**，使用统一的接口规范。

### 📋 基本规范

#### URL 命名
- 使用小写字母
- 使用连字符（`-`）分隔单词
- 使用复数形式表示资源

```
# ✅ 正确
GET /api/users
GET /api/user-orders
POST /api/auth/login

# ❌ 错误
GET /api/getUsers
GET /api/userOrders
POST /api/Auth/Login
```

#### HTTP 方法

| 方法 | 说明 | 示例 |
|------|------|------|
| `GET` | 获取资源 | `GET /api/users` |
| `POST` | 创建资源 | `POST /api/users` |
| `PUT` | 更新资源（全量） | `PUT /api/users/123` |
| `PATCH` | 更新资源（部分） | `PATCH /api/users/123` |
| `DELETE` | 删除资源 | `DELETE /api/users/123` |

#### 状态码

| 状态码 | 说明 | 使用场景 |
|-------|------|---------|
| `200` | 成功 | GET、PUT、PATCH 成功 |
| `201` | 已创建 | POST 成功创建资源 |
| `204` | 无内容 | DELETE 成功删除资源 |
| `400` | 请求错误 | 请求参数错误 |
| `401` | 未授权 | 未登录或 Token 过期 |
| `403` | 禁止访问 | 无权限访问 |
| `404` | 未找到 | 资源不存在 |
| `500` | 服务器错误 | 服务器内部错误 |

### 📦 请求格式

#### 查询参数
```
# 分页
GET /api/users?page=1&limit=10

# 排序
GET /api/users?sort=name&order=asc

# 过滤
GET /api/users?status=active&role=admin
```

#### 请求体
```
// POST /api/users
{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "securepassword"
}

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}
```

### 📤 响应格式

#### 成功响应
```json
{
  "success": true,
  "data": {
    "id": "123",
    "username": "john_doe",
    "email": "john@example.com",
    "createdAt": "2026-01-30T12:00:00Z"
  }
}
```

#### 错误响应
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": {
      "email": "邮箱格式不正确"
    }
  }
}
```

#### 分页响应
```json
{
  "success": true,
  "data": [
    { "id": "1", "username": "user1" },
    { "id": "2", "username": "user2" }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}
```

### 🔐 认证和授权

#### Token 认证
```bash
# 在请求头中携带 Token
Authorization: Bearer <token>
```

#### 权限检查
```json
// 响应中包含用户权限信息
{
  "success": true,
  "data": {
    "id": "123",
    "username": "john_doe",
    "permissions": ["users:read", "users:write", "users:delete"]
  }
}
```

### 📚 详细文档

**查看完整 API 文档**：[API 接口文档](/docs/dev/api)
    

## 数据库规范

### 🎯 快速参考

本项目使用 **PostgreSQL** 数据库，通过 **Drizzle ORM** 进行数据操作。

### 📋 表命名规范

- 使用小写字母
- 使用下划线（`_`）分隔单词
- 使用复数形式

```
✅ 正确：users, user_roles, salary_slips
❌ 错误：Users, userRoles, SalarySlips
```

### 🗂️ 字段命名规范

- 使用小写字母
- 使用下划线（`_`）分隔单词
- 使用 snake_case

```
✅ 正确：user_name, created_at, is_active
❌ 错误：userName, createdAt, isActive
```

### 🔑 常见字段

| 字段名 | 类型 | 说明 |
|-------|------|------|
| `id` | `text` | 主键，使用 UUID |
| `created_at` | `timestamp` | 创建时间 |
| `updated_at` | `timestamp` | 更新时间 |
| `deleted_at` | `timestamp` | 软删除时间 |
| `is_active` | `boolean` | 是否激活 |

### 📝 使用 Manager 模式

本项目使用 Manager 模式进行数据库操作，所有数据库操作都通过 Manager 类进行。

```typescript
// ✅ 正确 - 使用 Manager
import { userManager } from "@/storage/database/userManager";

const user = await userManager.findById("123");
```

```typescript
// ❌ 错误 - 直接使用 db
import { db } from "@/storage/database";
import { users } from "@/storage/database/schema";

const user = await db.select().from(users).where(eq(users.id, "123"));
```

### 🔧 迁移管理

#### 生成迁移
```bash
pnpm drizzle-kit generate
```

#### 运行迁移
```bash
pnpm drizzle-kit push
```

#### 查看迁移
```
drizzle/
├── 0001_init.sql
├── 0002_add_user_roles.sql
└── ...
```

### 📚 详细文档

**查看完整数据库文档**：[数据库字典](/docs/dev/database)

**查看开发流程规范**：[开发流程使用指南 v2.0.0 - 数据库迁移](/docs/development-guide#常见问题-faq)