仓库实现总结

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

---

# 仓储模式（Repository Pattern）实施总结

## 已完成的工作

### 1. 核心架构建立

✅ **基础仓储接口** (`IRepository`)
- 定义了所有仓储必须实现的标准CRUD方法
- 包含事务支持、分页、过滤、排序等功能
- 位置：`src/domains/shared/repositories/IRepository.ts`

✅ **领域仓储接口**
定义了各领域的专用仓储接口：
- `ITenantRepository` - 租户仓储接口
- `ICompanyRepository` - 企业仓储接口
- `IUserRepository` - 用户仓储接口
- `ISalarySlipRepository` - 工资条仓储接口
- `ISalarySlipSendRepository` - 工资条发送仓储接口

### 2. 基础设施实现

✅ **BaseRepository 抽象类**
- 实现了通用的查询构建逻辑
- 提供了软删除支持
- 处理时间戳字段的自动转换
- 支持灵活的过滤、排序和分页
- 位置：`src/infrastructure/database/repositories/BaseRepository.ts`

✅ **领域仓储实现**
实现了各领域的具体仓储类：
- `TenantRepository` - 租户仓储实现
- `CompanyRepository` - 企业仓储实现
- `UserRepository` - 用户仓储实现
- `SalarySlipRepository` - 工资条仓储实现
- `SalarySlipSendRepository` - 工资条发送仓储实现

### 3. 依赖管理

✅ **RepositoryFactory 工厂**
- 单例模式管理所有仓储实例
- 统一导出便捷的获取函数
- 位置：`src/infrastructure/database/repositories/RepositoryFactory.ts`

## 使用方法

### 导入仓储

```typescript
// 方式1：使用工厂方法
import { getCompanyRepository, getUserRepository } from '@/infrastructure/database/repositories';

const companyRepo = getCompanyRepository();
const userRepo = getUserRepository();

// 方式2：使用工厂实例
import { repositoryFactory } from '@/infrastructure/database/repositories';

const companyRepo = repositoryFactory.getCompanyRepository();
```

### 在Manager中使用

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

export class CompanyManager {
  private companyRepository: ICompanyRepository;

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

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

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

### 基础CRUD操作

```typescript
// 创建
const company = await companyRepo.create({
  companyName: 'Test Company',
  tenantId: 'tenant-123',
  // ... other fields
});

// 查询
const companies = await companyRepo.findAll({
  filters: { status: 'active' },
  pagination: { skip: 0, limit: 10 },
  sort: { field: 'createdAt', direction: 'desc' }
});

const company = await companyRepo.findById('company-id');

// 更新
const updated = await companyRepo.update('company-id', {
  status: 'inactive'
});

// 删除（软删除）
const deleted = await companyRepo.delete('company-id');

// 事务
await companyRepo.transaction(async (tx) => {
  // 在事务中执行多个操作
});
```

## 优势

1. **关注点分离**：业务逻辑与数据访问逻辑分离
2. **易于测试**：可以轻松mock仓储接口
3. **可维护性**：统一的接口定义，代码结构清晰
4. **可扩展性**：易于添加新的仓储实现
5. **事务支持**：提供统一的事务处理机制
6. **软删除支持**：自动处理软删除逻辑

## 下一步工作

1. **更新现有Manager**：将现有的Manager类逐步迁移到使用仓储模式
2. **类型完善**：根据实际Schema调整仓储接口的类型定义
3. **测试覆盖**：为仓储模式编写单元测试
4. **性能优化**：对高频查询进行性能优化
5. **文档完善**：补充更多使用示例和最佳实践

## 注意事项

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

## 技术栈

- **框架**：Next.js 16 (App Router)
- **ORM**：Drizzle ORM
- **数据库**：PostgreSQL
- **语言**：TypeScript 5
- **设计模式**：Repository Pattern, Factory 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
└── storage/database/shared/
    └── schema.ts               # 数据库Schema定义
```

## 参考资料

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