项目目录结构

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

---

# 项目目录结构（DDD架构）

## 目录说明

本项目采用领域驱动设计（DDD）架构，将代码划分为清晰的层次。

```
src/
├── app/                          # Next.js页面（App Router）
│   ├── (routes)/                 # 页面路由
│   ├── api/                      # API路由（接口层）
│   └── layout.tsx                # 根布局
│
├── domains/                      # 领域层（核心业务逻辑）
│   ├── shared/                   # 共享领域
│   │   └── auth/                 # 认证和授权
│   │       ├── types.ts          # 角色和权限类型
│   │       ├── permission.ts     # 权限验证
│   │       └── token.ts          # Token解析
│   │
│   ├── platform/                 # 平台管理领域
│   │   ├── entities/             # 领域实体
│   │   ├── value-objects/        # 值对象
│   │   ├── repositories/         # 仓储接口
│   │   └── domain-services/      # 领域服务
│   │
│   ├── tenant/                   # 企业管理领域
│   │   ├── entities/
│   │   ├── value-objects/
│   │   ├── repositories/
│   │   └── domain-services/
│   │
│   ├── salary/                   # 工资管理领域
│   │   ├── entities/
│   │   ├── value-objects/
│   │   ├── repositories/
│   │   └── domain-services/
│   │
│   └── crm/                     # CRM领域
│       ├── entities/
│       ├── value-objects/
│       ├── repositories/
│       └── domain-services/
│
├── infrastructure/               # 基础设施层
│   ├── database/                 # 数据库
│   │   ├── shared/               # 共享Schema
│   │   │   ├── schema.ts         # 主Schema
│   │   │   ├── schema-legacy.ts  # 旧Schema迁移
│   │   │   └── relations.ts      # 表关系
│   │   ├── migrations/           # 数据库迁移
│   │   └── seeders/              # 数据填充
│   │
│   ├── email/                    # 邮件服务
│   │   ├── index.ts
│   │   └── templates/            # 邮件模板
│   │
│   ├── sms/                      # 短信服务
│   │   ├── index.ts
│   │   └── providers/            # 短信提供商
│   │
│   ├── storage/                  # 对象存储
│   │   ├── s3.ts                 # S3存储实现
│   │   └── types.ts              # 存储类型定义
│   │
│   └── cache/                    # 缓存服务
│       └── cache.ts              # 缓存实现
│
├── application/                  # 应用层（用例编排）
│   ├── services/                 # 应用服务
│   │   ├── salarySlipManager.ts  # 工资条服务
│   │   ├── employeeManager.ts    # 员工服务
│   │   ├── saasCompanyManager.ts # 企业服务
│   │   ├── saasUserManager.ts    # 用户服务
│   │   ├── saasOrderManager.ts   # 订单服务
│   │   └── ...
│   │
│   ├── commands/                 # 命令（写操作）
│   │   └── ...
│   │
│   └── queries/                  # 查询（读操作）
│       └── ...
│
├── interfaces/                   # 接口层
│   ├── middleware/               # 中间件
│   │   └── api-middleware.ts     # API中间件
│   │
│   └── api/                      # API相关
│       ├── dto/                  # 数据传输对象
│       └── validators/           # 请求验证器
│
├── shared/                       # 共享层
│   ├── constants/                # 常量
│   │   ├── app.ts
│   │   └── database.ts
│   │
│   ├── types/                    # 类型定义
│   │   ├── api-response.ts       # API响应类型
│   │   └── common.ts             # 通用类型
│   │
│   ├── utils/                    # 工具函数
│   │   ├── utils.ts              # 通用工具
│   │   ├── error-handler.ts      # 错误处理
│   │   ├── logger.ts             # 日志
│   │   ├── seo.ts                # SEO
│   │   ├── wechat.ts             # 微信
│   │   └── export/               # 数据导出
│   │       └── DataExporter.ts   # 数据导出器
│   │
│   └── validation/               # 验证
│       ├── validation.ts         # 验证器
│       └── validators.ts         # 验证规则
│
├── components/                   # UI组件
│   ├── ui/                       # 基础UI组件（shadcn/ui）
│   ├── layouts/                  # 布局组件
│   ├── brand/                    # 品牌组件
│   ├── charts/                   # 图表组件
│   └── employee/                 # 员工组件
│
├── config/                       # 配置
│   └── ...
│
├── contexts/                     # React上下文
│   └── ...
│
├── hooks/                        # React Hooks
│   └── ...
│
├── docs/                         # 文档
│   └── ...
│
└── services/                     # 其他服务
    └── ...
```

## 层次说明

### 1. 领域层（domains/）
**核心业务逻辑**，最纯粹的业务规则。

- **职责**：封装业务逻辑，领域模型，业务规则
- **特点**：不依赖外部框架，可独立测试
- **包含**：
  - 实体（Entities）：具有唯一标识的对象
  - 值对象（Value Objects）：不可变的对象
  - 聚合（Aggregates）：一组相关对象的集合
  - 领域服务（Domain Services）：业务服务
  - 仓储接口（Repository Interfaces）：数据访问接口

### 2. 基础设施层（infrastructure/）
**技术实现**，提供技术支持。

- **职责**：提供技术能力，实现领域层的接口
- **特点**：可替换，不包含业务逻辑
- **包含**：
  - 数据库实现（Drizzle ORM）
  - 邮件服务
  - 短信服务
  - 对象存储
  - 缓存
  - 外部API集成

### 3. 应用层（application/）
**用例编排**，协调领域对象完成业务用例。

- **职责**：协调领域对象，编排业务流程
- **特点**：薄应用层，胖领域层
- **包含**：
  - 应用服务（Application Services）
  - 命令（Commands）：写操作
  - 查询（Queries）：读操作

### 4. 接口层（interfaces/）
**对外接口**，处理外部请求。

- **职责**：处理HTTP请求，参数验证，响应格式化
- **特点**：薄接口层，只负责协议转换
- **包含**：
  - API路由
  - 中间件
  - DTO（数据传输对象）
  - 验证器

### 5. 共享层（shared/）
**通用工具**，被各层共享。

- **职责**：提供通用工具和类型
- **特点**：无状态，可复用
- **包含**：
  - 工具函数
  - 类型定义
  - 常量
  - 验证器

### 6. 展示层（app/, components/）
**用户界面**，Next.js页面和组件。

- **职责**：展示数据，处理用户交互
- **特点**：依赖应用层服务
- **包含**：
  - 页面路由
  - UI组件
  - 布局组件

## 依赖规则

**单向依赖原则**：
- 展示层 → 应用层 → 领域层
- 应用层 → 领域层
- 基础设施层 ← 领域层（实现领域接口）

**禁止依赖**：
- ❌ 领域层依赖应用层
- ❌ 领域层依赖基础设施层
- ❌ 应用层依赖展示层

## 导入路径规范

```typescript
// 领域层
import { User } from '@/domains/platform/entities/User';
import { UserRepository } from '@/domains/platform/repositories/UserRepository';

// 基础设施层
import { getDb } from '@/infrastructure/database';

// 应用层
import { UserService } from '@/application/services/UserService';

// 接口层
import { withAuthAndPermission } from '@/interfaces/middleware/api-middleware';

// 共享层
import { ApiResponse } from '@/shared/types/api-response';
import { formatDate } from '@/shared/utils/utils';
import { UserRole } from '@/domains/shared/auth/types';
```

## 迁移进度

### ✅ 已完成
- 创建DDD目录结构
- 迁移shared/通用代码
- 迁移infrastructure/基础设施
- 迁移application/应用服务
- 迁移interfaces/中间件

### &#128260; 进行中
- 更新导入路径
- 验证构建

### &#128203; 待完成
- 创建领域实体和值对象
- 实现仓储模式
- 优化服务分层
- 添加单元测试

## 最佳实践

1. **领域优先**：核心业务逻辑放在领域层
2. **依赖倒置**：依赖抽象而非具体实现
3. **单一职责**：每层只负责自己的职责
4. **接口隔离**：使用接口隔离外部依赖
5. **可测试性**：每层都可以独立测试