# WWJCloud 架构设计

## 架构概述

WWJCloud 基于 NestJS 框架设计，采用分层架构模式，参考 NiuCloud Java 和 PHP 版本的真实代码结构。

## 分层架构

### 1. Config 层 - 框架配置中心
**职责**: 提供框架级配置管理
- 环境变量管理
- 配置验证
- 配置热更新
- 框架级配置项

**位置**: `src/config/`
**特点**: 纯配置管理，不包含业务逻辑

### 2. Common 层 - 基础设施层
**职责**: 提供纯基础设施能力
- 安全认证和授权
- 链路追踪
- 缓存服务
- 队列服务
- 事件服务
- 定时任务调度
- 初始化管理
- 上下文管理
- API文档管理

**位置**: `src/common/`
**特点**: 纯基础设施，不包含业务逻辑

### 3. Core 层 - 核心业务逻辑层
**职责**: 提供核心业务能力
- 认证授权业务
- 系统管理业务
- 会员管理业务
- 支付业务
- 上传业务
- 通知业务
- 数据字典业务
- 多语言业务

**位置**: `src/core/`
**特点**: 核心业务逻辑，可被多个应用复用

### 4. Vendor 层 - 第三方集成层
**职责**: 提供第三方服务集成能力
- 支付服务集成
- 短信服务集成
- 通知服务集成
- 上传服务集成
- 存储服务集成

**位置**: `src/vendor/`
**特点**: 第三方服务适配器，支持动态切换

### 5. App 层 - 具体业务应用层
**职责**: 具体业务应用实现
- 特定业务逻辑
- 业务特定的控制器
- 业务特定的服务

**位置**: `src/app/`
**特点**: 具体业务实现，依赖其他层

## 依赖关系

```
App Layer
    ↓
Core Layer ← Vendor Layer
    ↓
Common Layer
    ↓
Config Layer
```

## 与 NiuCloud 的对应关系

### Java 版本对应
- `niucloud-core/common/config/` → `src/config/` (框架配置)
- `niucloud-core/common/component/` → `src/common/` (基础设施)
- `niucloud-core/service/core/` → `src/core/` (核心业务)
- `niucloud-core/common/component/pay|sms|upload/` → `src/vendor/` (第三方集成)

### PHP 版本对应
- `core/dict/Config.php` → `src/config/` (框架配置)
- `core/base/` → `src/common/` (基础设施)
- `core/dict/` → `src/core/` (核心业务)
- `core/pay|sms|upload/` → `src/vendor/` (第三方集成)

## 设计原则

1. **单一职责**: 每层只负责自己的职责
2. **依赖倒置**: 上层依赖下层，下层不依赖上层
3. **开闭原则**: 对扩展开放，对修改关闭
4. **接口隔离**: 使用接口定义契约
5. **配置驱动**: 通过配置驱动行为

## 微服务演进

未来可拆分为：
- **Config 微服务**: 配置中心
- **Common+Vendor 微服务**: 基础设施服务
- **Core 微服务**: 核心业务服务
- **App 微服务**: 具体业务服务

## 开发规范

1. **命名规范**: 遵循 NestJS 和业务对齐原则
2. **目录结构**: 按功能模块组织
3. **依赖管理**: 明确层间依赖关系
4. **配置管理**: 统一使用 Config 层
5. **错误处理**: 统一异常处理机制