# 架构约束规则

## 🏗️ 分层架构

```
┌─────────────────┐
│      App        │  ← 业务开发层（用户自定义业务模块）
│   (用户业务)     │    电商、CRM、ERP等具体业务逻辑
└─────────────────┘
         ↓
┌─────────────────┐
│     Common      │  ← 框架通用服务层（企业级通用功能）
│ (框架通用服务)   │    用户管理、权限管理、菜单管理
└─────────────────┘    文件上传、通知服务、系统设置
         ↓              数据字典、缓存服务、队列服务
┌─────────────────┐
│      Core       │  ← 核心基础设施层（底层基础设施）
│   (基础设施)     │    认证核心、数据库核心、验证核心
└─────────────────┘    HTTP核心、缓存核心、队列核心
         ↓
┌─────────────────┐
│     Vendor      │  ← 第三方服务适配层
│   (外部集成)     │    存储、支付、通信、云服务适配
└─────────────────┘

┌─────────────────┐
│     Addons      │  ← 插件扩展层（可插拔功能模块）
│   (插件扩展)     │    扩展框架功能，不影响核心稳定性
└─────────────────┘

┌─────────────────┐
│      Test       │  ← 测试代码层（独立测试模块）
│   (测试代码)     │    单元测试、集成测试、E2E测试
└─────────────────┘
```

## 📋 依赖约束规则

### 1. **Core 层（最底层）**
- ✅ **允许依赖**：无（最底层基础设施）
- ❌ **禁止依赖**：Common、App、Vendor 层
- 📁 **位置**：`src/core/`
- 🎯 **职责**：提供最基础的抽象和接口

### 2. **Vendor 层（第三方适配）**
- ✅ **允许依赖**：Core 层
- ❌ **禁止依赖**：Common、App 层
- 📁 **位置**：`src/vendor/`
- 🎯 **职责**：第三方服务适配，实现 Core 层抽象

### 3. **Common 层（通用服务）**
- ✅ **允许依赖**：Core 层
- ❌ **禁止依赖**：App、Vendor 层
- 📁 **位置**：`src/common/`
- 🎯 **职责**：企业级通用功能，基于 Core 层构建

### 4. **App 层（业务应用）**
- ✅ **允许依赖**：Common、Core 层
- ❌ **禁止依赖**：Vendor 层（通过 Common 层抽象）
- 📁 **位置**：`src/app/`
- 🎯 **职责**：具体业务逻辑实现

### 5. **Test 层（测试代码）**
- ✅ **允许依赖**：所有层（测试需要）
- 📁 **位置**：`test/`（项目根目录）
- ❌ **禁止位置**：`src/` 目录下
- 🎯 **职责**：测试所有层的功能

## 🚫 禁止的依赖关系

```typescript
// ❌ 错误：Common 层依赖 App 层
// src/common/auth/auth.service.ts
import { AppService } from '../../app/app.service'; // 禁止！

// ❌ 错误：Core 层依赖 Common 层  
// src/core/database/database.service.ts
import { UserService } from '../../common/user/user.service'; // 禁止！

// ❌ 错误：App 层直接依赖 Vendor 层
// src/app/payment/payment.service.ts
import { AlipayProvider } from '../../vendor/payment/alipay.provider'; // 禁止！

// ❌ 错误：在 src 目录下创建测试代码
// src/test/test.service.ts - 禁止！
```

## ✅ 正确的依赖关系

```typescript
// ✅ 正确：Common 层依赖 Core 层
// src/common/auth/auth.service.ts
import { JwtService } from '../../core/auth/jwt.service';

// ✅ 正确：App 层依赖 Common 层
// src/app/user/user.controller.ts
import { AuthService } from '../../common/auth/auth.service';

// ✅ 正确：Vendor 层依赖 Core 层
// src/vendor/payment/alipay.provider.ts
import { PaymentProvider } from '../../core/payment/payment.provider';

// ✅ 正确：测试代码依赖所有层
// test/auth.test.ts
import { AuthService } from '../src/common/auth/auth.service';
```

## 🔧 ESLint 规则

项目已配置严格的 ESLint 规则来强制执行这些约束：

1. **分层依赖检查**：自动检测违反依赖方向的导入
2. **测试代码位置检查**：禁止在 src 目录下创建测试代码
3. **路径别名检查**：强制使用相对路径，避免路径别名
4. **内部实现检查**：禁止依赖其他模块的内部实现

## 📝 开发建议

1. **设计时先确定层级**：新功能应该放在哪一层？
2. **依赖时检查方向**：确保依赖关系符合架构约束
3. **测试代码统一管理**：所有测试代码放在 `test/` 目录
4. **定期运行 ESLint**：`npm run lint` 检查架构约束
5. **代码审查时关注架构**：确保新代码符合分层原则

## 🚨 常见错误

1. **在 Core 层导入业务逻辑**
2. **Common 层直接调用第三方服务**
3. **App 层绕过 Common 层直接使用 Vendor**
4. **测试代码放在 src 目录下**
5. **使用绝对路径或路径别名导入**

遵循这些约束规则，可以确保 WWJCloud 的架构清晰、依赖关系正确，为未来的微服务拆分奠定坚实基础。