仓库模式

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

---

# 仓储模式（Repository Pattern）架构说明

## 概述

本系统采用仓储模式进行数据库访问层的重构，将数据访问逻辑与业务逻辑分离，提供统一的数据访问接口，便于测试和维护。

## 架构设计

### 目录结构

```
src/
├── domains/                      # 领域层
│   ├── shared/
│   │   └── repositories/
│   │       └── IRepository.ts   # 基础仓储接口
│   ├── tenant/
│   │   └── repositories/
│   │       ├── ITenantRepository.ts      # 租户仓储接口
│   │       └── ICompanyRepository.ts     # 企业仓储接口
│   ├── employee/
│   │   └── repositories/
│   │       └── IUserRepository.ts        # 用户仓储接口
│   └── salary/
│       └── repositories/
│           ├── ISalarySlipRepository.ts      # 工资条仓储接口
│           └── ISalarySlipSendRepository.ts  # 工资条发送仓储接口
├── infrastructure/              # 基础设施层
│   └── database/
│       └── repositories/
│           ├── BaseRepository.ts               # 基础仓储实现
│           ├── TenantRepository.ts             # 租户仓储实现
│           ├── CompanyRepository.ts            # 企业仓储实现
│           ├── UserRepository.ts               # 用户仓储实现
│           ├── SalarySlipRepository.ts         # 工资条仓储实现
│           ├── SalarySlipSendRepository.ts     # 工资条发送仓储实现
│           ├── RepositoryFactory.ts            # 仓储工厂
│           └── index.ts                       # 统一导出
└── application/                 # 应用层
    └── services/
        ├── companyManagerV2.ts          # 企业管理器（仓储模式）
        └── salarySlipManagerV2.ts       # 工资条管理器（仓储模式）
```

## 核心组件

### 1. 基础仓储接口 (IRepository)

定义了所有仓储必须实现的标准方法：

```typescript
interface IRepository<T, K = any> {
  // 基础CRUD
  create(data: K): Promise<T>;
  createMany(data: K[]): Promise<T[]>;
  findById(id: string): Promise<T | null>;
  findAll(options?: FindAllOptions): Promise<T[]>;
  update(id: string, data: Partial<K>): Promise<T | null>;
  updateMany(conditions: Partial<T>, data: Partial<K>): Promise<number>;
  delete(id: string): Promise<boolean>;
  deleteMany(conditions: Partial<T>): Promise<number>;
  exists(conditions: Partial<T>): Promise<boolean>;
  count(conditions?: Partial<T>): Promise<number>;

// 事务支持
  transaction<R>(callback: (tx: any) => Promise<R>): Promise<R>;

// 获取数据库表引用
  getTable(): any;
}
```

### 2. 领域仓储接口

基于基础仓储接口扩展，添加特定领域的业务方法：

```typescript
// 示例：企业仓储接口
interface ICompanyRepository extends IRepository<SaasCompany, InsertSaasCompany> {
  findByCompanyNo(companyNo: string): Promise<SaasCompany | null>;
  findByTenantId(tenantId: string): Promise<SaasCompany[]>;
  countByTenantId(tenantId: string): Promise<number>;
  updateLastLogin(id: string): Promise<boolean>;
}
```

### 3. 基础仓储实现

提供通用的查询构建、软删除处理、分页排序等核心逻辑：

```typescript
abstract class BaseRepository<T, K> implements IRepository<T, K> {
  protected db: PGDatabase;
  protected table: any;
  protected timestampFields: string[];

// 实现所有基础方法
  // 提供查询构建、过滤、排序、分页等通用逻辑
}
```

### 4. 领域仓储实现

继承基础仓储实现，添加特定领域的查询方法：

```typescript
class CompanyRepository extends BaseRepository<SaasCompany, InsertSaasCompany>
  implements ICompanyRepository {

// 实现特定业务方法
  async findByCompanyNo(companyNo: string): Promise<SaasCompany | null> {
    // ...
  }
}
```

### 5. 仓储工厂

统一管理所有仓储实例的创建和获取：

```typescript
class RepositoryFactory {
  private static instance: RepositoryFactory;
  private repositories: Map<string, IRepository<any, any>>;

static getInstance(): RepositoryFactory;
  getTenantRepository(): ITenantRepository;
  getCompanyRepository(): ICompanyRepository;
  getUserRepository(): IUserRepository;
  getSalarySlipRepository(): ISalarySlipRepository;
  getSalarySlipSendRepository(): ISalarySlipSendRepository;
}

// 便捷导出函数
export const repositoryFactory = RepositoryFactory.getInstance();
export const getTenantRepository = () => repositoryFactory.getTenantRepository();
export const getCompanyRepository = () => repositoryFactory.getCompanyRepository();
// ...
```

## 使用方法

### 1. 在Manager中使用仓储

```typescript
import { getCompanyRepository } from '@/infrastructure/database/repositories';
import type { ICompanyRepository } from '@/domains/tenant/repositories/ICompanyRepository';

export class CompanyManagerV2 {
  private companyRepository: ICompanyRepository;

constructor() {
    this.companyRepository = getCompanyRepository();
  }

async createCompany(data: InsertSaasCompany): Promise<SaasCompany> {
    return await this.companyRepository.create(data);
  }

async getCompanies(options: {
    skip?: number;
    limit?: number;
    filters?: Partial<SaasCompany>;
    sort?: { field: keyof SaasCompany; direction: 'asc' | 'desc' };
  } = {}): Promise<SaasCompany[]> {
    return await this.companyRepository.findAll(options);
  }

async getCompanyByNo(companyNo: string): Promise<SaasCompany | null> {
    return await this.companyRepository.findByCompanyNo(companyNo);
  }
}
```

### 2. 在API路由中使用

```typescript
import { companyManagerV2, salarySlipManagerV2 } from '@/application/services';

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();

// 创建企业
    const company = await companyManagerV2.createCompany({
      companyName: body.companyName,
      contactName: body.contactName,
      contactPhone: body.contactPhone,
      tenantId: body.tenantId,
      companyNo: `C${Date.now()}`,
      status: 'active'
    });

return NextResponse.json({ success: true, data: company });
  } catch (error) {
    return NextResponse.json({ success: false, error: '操作失败' }, { status: 500 });
  }
}
```

### 3. 使用事务

```typescript
async createWithTransaction(data: any) {
  return await this.companyRepository.transaction(async (tx) => {
    // 在事务中执行多个数据库操作
    const [company] = await tx
      .insert(this.companyRepository.getTable())
      .values(data)
      .returning();

// 其他操作...

return company;
  });
}
```

### 4. 复杂查询

```typescript
async getComplexData(companyId: string, month: string) {
  return await this.salarySlipRepository.findAll({
    filters: {
      companyId,
      month,
      status: 'issued'
    },
    sort: {
      field: 'salaryAmount' as any,
      direction: 'desc'
    },
    pagination: {
      skip: 0,
      limit: 10
    }
  });
}
```

## 优势

### 1. 关注点分离
- 业务逻辑与数据访问逻辑分离
- Manager专注于业务逻辑，Repository专注于数据访问

### 2. 易于测试
- 可以轻松mock仓储接口进行单元测试
- 业务逻辑不依赖具体的数据库实现

### 3. 可维护性
- 统一的接口定义，代码结构清晰
- 修改数据库访问逻辑不影响业务层

### 4. 可扩展性
- 易于添加新的仓储实现
- 支持缓存、日志等横切关注点

### 5. 事务支持
- 提供统一的事务处理机制
- 支持跨多个仓储的复杂事务

### 6. 软删除支持
- 自动处理软删除逻辑
- 避免数据误删

## 迁移指南

### 从旧的Manager迁移到仓储模式

**旧代码：**
```typescript
export class CompanyManager {
  async createCompany(data: InsertSaasCompany): Promise<SaasCompany> {
    const [company] = await db.insert(saasCompany).values(data).returning();
    return company;
  }

async getCompanies(filters: any): Promise<SaasCompany[]> {
    return await db.select().from(saasCompany).where(filters);
  }
}
```

**新代码：**
```typescript
export class CompanyManagerV2 {
  private companyRepository: ICompanyRepository;

constructor() {
    this.companyRepository = getCompanyRepository();
  }

async createCompany(data: InsertSaasCompany): Promise<SaasCompany> {
    return await this.companyRepository.create(data);
  }

async getCompanies(options: FindAllOptions = {}): Promise<SaasCompany[]> {
    return await this.companyRepository.findAll(options);
  }
}
```

### 迁移步骤

1. 在Manager构造函数中注入仓储
2. 替换直接的数据库调用为仓储方法调用
3. 调整参数格式以适配仓储接口
4. 测试所有功能是否正常

## 未来改进方向

1. **引入依赖注入**：使用DI容器管理仓储生命周期
2. **添加缓存层**：对频繁访问的数据添加缓存
3. **实现读写分离**：支持主从数据库配置
4. **添加审计日志**：记录所有数据变更
5. **实现数据版本控制**：支持数据历史版本追踪
6. **添加批量操作优化**：优化大批量数据操作性能

## 注意事项

1. 所有仓储实例应通过工厂方法获取，不要直接new
2. 仓储方法是事务无关的，需要事务时使用`transaction`方法
3. 软删除字段（`isDeleted`）会自动处理，无需手动过滤
4. 时间戳字段会自动转换为Date对象，无需手动处理
5. 复杂查询优先使用仓储提供的`findAll`方法，而不是直接使用Drizzle API

## 参考文档

- [Drizzle ORM文档](https://orm.drizzle.team/)
- [仓储模式设计模式](https://martinfowler.com/eaaCatalog/repository.html)
- [领域驱动设计](https://martinfowler.com/bliki/DomainDrivenDesign.html)