# 框架介绍

::: info 你正在阅读的是 [wwjcloud](https://github.com/vbenjs/vue-vben-admin) 框架文档！

wwjcloud 是一个基于 NestJS 的现代化后端框架，专为 PHP 项目迁移而设计。我们致力于提供一个平滑的迁移路径，让您能够轻松地从 PHP 迁移到现代化的 Node.js 技术栈。

- 如果你只是想体验一下，你可以查看[快速开始](./quick-start.md)。
- 如发现文档有误，欢迎提交 [issue](https://github.com/vbenjs/vue-vben-admin/issues) 帮助我们改进。

:::

## 设计理念

### 🎯 核心目标

- **平滑迁移**：保持与 PHP 框架的数据库一致性和业务逻辑兼容性
- **现代化**：采用最新的 Node.js 技术栈，提供更好的性能和开发体验
- **企业级**：内置多语言、权限管理、软删除等企业级功能
- **开箱即用**：提供完整的开发规范和最佳实践

### 🔄 迁移友好

我们深知从 PHP 迁移到 Node.js 的挑战，因此 wwjcloud 框架在设计时特别考虑了：

- **数据库一致性**：保持与 PHP 框架相同的数据库结构
- **软删除机制**：统一的双字段软删除策略 (`is_del` + `delete_time`)
- **命名规范**：保持与 PHP 框架一致的字段命名和表结构
- **业务逻辑**：核心业务逻辑与 PHP 框架保持一致

## 技术架构

### 🏗️ 整体架构

```mermaid
graph TB
    A[前端应用] --> B[API Gateway]
    B --> C[wwjcloud 后端]
    C --> D[数据库层]
    C --> E[缓存层]
    C --> F[文件存储]
    
    subgraph "wwjcloud 核心"
        G[BaseEntity] --> H[BaseService]
        H --> I[BaseController]
        J[多语言系统] --> K[权限管理]
        L[软删除] --> M[统一响应]
    end
    
    C --> G
    C --> J
    C --> L
```

### 🧩 核心组件

::: grid
```md
### BaseEntity
- 统一的基础实体类
- 包含通用字段 (site_id, create_time, update_time)
- 软删除机制 (is_del, delete_time)
- 时间戳管理
```

```md
### BaseService
- 通用 CRUD 操作
- 软删除处理
- 查询条件构建
- 错误处理
```

```md
### BaseController
- 标准 API 端点
- 统一响应格式
- 参数验证
- 错误处理
```

```md
### 多语言系统
- 动态语言包加载
- 缓存机制
- 模块化语言包
- 支持 common/app/addons
```
:::

## 技术栈

### 🛠️ 核心技术

- **NestJS** - 现代化 Node.js 框架
- **TypeScript** - 强类型 JavaScript
- **TypeORM** - 数据库 ORM
- **MySQL** - 主数据库
- **Redis** - 缓存存储
- **JWT** - 身份认证

### 📦 开发工具

- **ESLint** - 代码规范检查
- **Prettier** - 代码格式化
- **Swagger** - API 文档生成
- **Jest** - 单元测试
- **Docker** - 容器化部署

## 目录结构

```
wwjcloud/
├── src/
│   ├── core/                    # 核心模块
│   │   ├── base/               # 基础类
│   │   ├── lang/               # 多语言系统
│   │   └── utils/              # 工具函数
│   ├── common/                 # 业务模块
│   │   ├── member/             # 会员模块
│   │   ├── notice/             # 通知模块
│   │   ├── schedule/           # 定时任务
│   │   ├── rbac/               # 权限管理
│   │   └── admin/              # 管理模块
│   ├── config/                 # 配置文件
│   ├── vendor/                 # 第三方服务
│   └── migrations/             # 数据库迁移
├── test/                       # 测试文件
├── docs/                       # 文档
└── docker/                     # Docker 配置
```

## 核心特性

### 🔐 权限管理

- **RBAC 模型**：基于角色的访问控制
- **动态权限**：支持动态权限配置
- **按钮级权限**：细粒度的权限控制
- **菜单权限**：动态菜单显示

### 🌐 多语言支持

- **动态加载**：支持运行时语言包加载
- **模块化**：按业务模块组织语言包
- **缓存机制**：提高语言包加载性能
- **扩展性**：支持插件语言包

### 🗑️ 软删除机制

- **双字段策略**：`is_del` + `delete_time`
- **统一处理**：BaseService 自动处理软删除
- **查询过滤**：自动过滤已删除数据
- **恢复功能**：支持数据恢复

### 📊 统一响应格式

```typescript
{
  code: 200,
  message: "操作成功",
  data: {},
  timestamp: 1640995200
}
```

## 开发规范

### 📝 命名规范

- **数据库字段**：使用下划线命名法 (`snake_case`)
- **TypeScript 属性**：使用下划线命名法 (`snake_case`)
- **方法名**：使用驼峰命名法 (`camelCase`)
- **文件名**：使用帕斯卡命名法 (`PascalCase`)

### 🏗️ 架构规范

- **模块化设计**：按业务功能划分模块
- **依赖注入**：使用 NestJS 的依赖注入
- **接口分离**：遵循接口隔离原则
- **单一职责**：每个类只负责一个功能

### 🔧 代码规范

- **TypeScript**：严格类型检查
- **ESLint**：代码质量检查
- **Prettier**：代码格式化
- **注释规范**：完整的代码注释

## 迁移优势

### 🚀 性能提升

- **异步处理**：Node.js 的异步非阻塞特性
- **内存优化**：更好的内存管理
- **并发处理**：更高的并发处理能力
- **缓存策略**：Redis 缓存提升性能

### 🛠️ 开发效率

- **TypeScript**：强类型支持，减少错误
- **热重载**：开发时自动重载
- **调试工具**：丰富的调试工具
- **生态丰富**：npm 生态丰富

### 🔒 安全性

- **JWT 认证**：无状态的认证机制
- **参数验证**：严格的参数验证
- **SQL 注入防护**：ORM 自动防护
- **XSS 防护**：内置安全防护

## 下一步

::: tip 开始使用

1. **阅读快速开始**：了解如何快速搭建项目
2. **查看基础概念**：理解框架的核心概念
3. **参考 API 文档**：了解可用的 API 接口
4. **查看迁移指南**：了解如何从 PHP 迁移

:::

::: warning 注意事项

- 确保 Node.js 版本 >= 16
- 数据库需要 MySQL 5.7+ 或 8.0+
- 建议使用 Docker 进行部署
- 请遵循开发规范进行开发

::: 