# 基础概念

::: info 理解 wwjcloud 框架

为了更好地理解和使用 wwjcloud 框架，我们需要了解一些基础概念。

:::

## 核心概念

### 🏗️ 基础架构

wwjcloud 框架基于 NestJS 构建，采用了分层架构设计：

```mermaid
graph TB
    A[Controller 控制器层] --> B[Service 服务层]
    B --> C[Repository 数据访问层]
    C --> D[Database 数据库]
    
    E[BaseEntity] --> F[BaseService]
    F --> G[BaseController]
```

### 📦 模块化设计

框架采用模块化设计，每个业务功能都是一个独立的模块：

```
src/
├── core/                    # 核心模块
│   ├── base/               # 基础类
│   ├── lang/               # 多语言系统
│   └── utils/              # 工具函数
├── common/                 # 业务模块
│   ├── member/             # 会员模块
│   ├── notice/             # 通知模块
│   ├── schedule/           # 定时任务
│   ├── rbac/               # 权限管理
│   └── admin/              # 管理模块
└── config/                 # 配置文件
```

## 基础类

### 🔧 BaseEntity

所有实体的基类，提供通用字段和功能：

```typescript
export abstract class BaseEntity {
  @Column({ name: 'site_id', type: 'int', default: 0 })
  site_id: number;

  @Column({ name: 'create_time', type: 'int', default: 0 })
  create_time: number;

  @Column({ name: 'update_time', type: 'int', default: 0 })
  update_time: number;

  @Column({ name: 'is_del', type: 'tinyint', default: 0 })
  is_del: number;

  @Column({ name: 'delete_time', type: 'int', default: 0 })
  delete_time: number;
}
```

**特点：**
- **通用字段**：包含所有实体都需要的字段
- **软删除**：统一的软删除机制
- **时间戳**：自动管理创建和更新时间
- **站点隔离**：支持多站点部署

### 🛠️ BaseService

提供通用的 CRUD 操作和业务逻辑：

```typescript
export abstract class BaseService<T> {
  constructor(protected readonly repository: Repository<T>) {}

  async findAll(): Promise<T[]> {
    return this.repository.find({
      where: { is_del: 0 } as any
    });
  }

  async findById(id: number): Promise<T | null> {
    return this.repository.findOne({
      where: { id, is_del: 0 } as any
    });
  }

  async create(data: Partial<T>): Promise<T> {
    const entity = this.repository.create(data);
    return this.repository.save(entity);
  }
}
```

**特点：**
- **通用 CRUD**：提供标准的增删改查操作
- **软删除**：自动处理软删除逻辑
- **查询过滤**：自动过滤已删除的数据
- **错误处理**：统一的错误处理机制

### 🎮 BaseController

提供标准的 API 端点：

```typescript
export abstract class BaseController<T> {
  constructor(protected readonly service: BaseService<T>) {}

  @Get()
  async getList() {
    const data = await this.service.findAll();
    return {
      code: 200,
      message: '获取成功',
      data
    };
  }

  @Post()
  async create(@Body() data: Partial<T>) {
    const result = await this.service.create(data);
    return {
      code: 200,
      message: '创建成功',
      data: result
    };
  }
}
```

**特点：**
- **标准端点**：提供 RESTful API 标准端点
- **统一响应**：统一的响应格式
- **参数验证**：自动参数验证
- **错误处理**：统一的错误处理

## 软删除机制

### 🗑️ 双字段策略

wwjcloud 采用双字段软删除策略：

```typescript
// 软删除字段
@Column({ name: 'is_del', type: 'tinyint', default: 0 })
is_del: number;  // 0: 正常, 1: 已删除

@Column({ name: 'delete_time', type: 'int', default: 0 })
delete_time: number;  // 删除时间戳
```

**优势：**
- **查询效率**：`is_del` 字段便于快速查询
- **时间记录**：`delete_time` 记录删除时间
- **恢复功能**：支持数据恢复
- **兼容性**：与 PHP 框架保持一致

## 多语言系统

### 🌐 动态加载

支持运行时动态加载语言包：

```typescript
// 语言包目录结构
src/
├── common/lang/           # 通用语言包
│   ├── zh-cn/
│   │   ├── common.json
│   │   └── member.json
│   └── en/
│       ├── common.json
│       └── member.json
├── app/lang/             # 应用语言包
└── addons/*/lang/        # 插件语言包
```

## 统一响应格式

### 📊 标准格式

所有 API 响应都遵循统一格式：

```typescript
interface ApiResponse<T = any> {
  code: number;        // 状态码
  message: string;     // 消息
  data: T;            // 数据
  timestamp: number;   // 时间戳
}
```

## 下一步

::: tip 深入学习

1. **查看架构文档**：了解整体架构设计
2. **阅读 API 规范**：了解接口设计规范
3. **参考开发规范**：遵循开发规范
4. **查看最佳实践**：学习最佳实践

:::

::: warning 注意事项

- 所有实体都应该继承 BaseEntity
- 所有服务都应该继承 BaseService
- 遵循统一的命名规范
- 使用统一的响应格式

::: 