whale-town-end/docs/ai-reading/step4-architecture-layer.md

步骤4：架构分层检查

⚠️ 执行前必读规范

🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 README.md 文件！

该README文件包含：

• 🎯 执行前准备和用户信息收集要求
• 🔄 强制执行原则和分步执行流程
• 🔥 修改后立即重新执行当前步骤的强制规则
• 📝 文件修改记录规范和版本号递增规则
• 🧪 测试文件调试规范和测试指令使用规范
• 🚨 全局约束和游戏服务器特殊要求

不阅读README直接执行步骤将导致执行不规范，违反项目要求！

---

🎯 检查目标

检查架构分层的合规性，确保Core层和Business层职责清晰、依赖关系正确。

🏗️ 架构层级识别

项目分层结构

src/
├── gateway/        # Gateway层：网关层（HTTP协议处理）
│   ├── auth/       # 认证网关
│   ├── users/      # 用户网关
│   └── admin/      # 管理网关
├── business/       # Business层：业务逻辑层
│   ├── auth/       # 认证业务
│   ├── users/      # 用户业务
│   └── admin/      # 管理业务
├── core/           # Core层：技术实现层
│   ├── db/         # 数据访问
│   ├── redis/      # 缓存服务
│   └── utils/      # 工具服务
└── common/         # 公共层：通用组件

4层架构说明

Gateway Layer（网关层）

• 位置：src/gateway/
• 职责：HTTP协议处理、数据验证、路由管理、认证守卫、错误转换
• 依赖：Business层

Business Layer（业务层）

• 位置：src/business/
• 职责：业务逻辑实现、业务流程控制、服务协调、业务规则验证
• 依赖：Core层

Core Layer（核心层）

• 位置：src/core/
• 职责：数据访问、基础设施、外部系统集成、技术实现细节
• 依赖：无（或第三方库）

检查范围

• 限制范围：仅检查当前执行检查的文件夹
• 不跨模块：不考虑其他同层功能模块
• 专注职责：确保当前模块职责清晰
• 按层检查：根据文件夹所在层级应用对应的检查规则

🌐 Gateway层规范检查

职责定义

Gateway层专注HTTP协议处理，不包含业务逻辑

Gateway层协议处理示例

// ✅ 正确：Gateway层只做协议转换
@Controller('auth')
export class LoginController {
  constructor(private readonly loginService: LoginService) {}

  @Post('login')
  async login(@Body() loginDto: LoginDto, @Res() res: Response): Promise<void> {
    // 1. 接收HTTP请求，使用DTO验证
    // 2. 调用Business层服务
    const result = await this.loginService.login({
      identifier: loginDto.identifier,
      password: loginDto.password
    });
    
    // 3. 将业务响应转换为HTTP响应
    this.handleResponse(result, res);
  }
  
  private handleResponse(result: any, res: Response): void {
    if (result.success) {
      res.status(HttpStatus.OK).json(result);
    } else {
      const statusCode = this.getErrorStatusCode(result);
      res.status(statusCode).json(result);
    }
  }
}

// ❌ 错误：Gateway层包含业务逻辑
@Controller('auth')
export class LoginController {
  @Post('login')
  async login(@Body() loginDto: LoginDto): Promise<any> {
    // 错误：在Controller中实现业务逻辑
    const user = await this.userRepository.findOne({ 
      where: { username: loginDto.identifier } 
    });
    
    if (!user) {
      throw new NotFoundException('用户不存在');
    }
    
    const isValid = await bcrypt.compare(loginDto.password, user.password);
    if (!isValid) {
      throw new UnauthorizedException('密码错误');
    }
    
    // ... 更多业务逻辑
  }
}

Gateway层依赖关系检查

// ✅ 允许的导入
import { Controller, Post, Body, Res } from '@nestjs/common';  # NestJS框架
import { Response } from 'express';                            # Express类型
import { LoginService } from '../../business/auth/login.service'; # Business层服务
import { LoginDto } from './dto/login.dto';                    # 同层DTO
import { JwtAuthGuard } from './jwt_auth.guard';              # 同层Guard

// ❌ 禁止的导入
import { LoginCoreService } from '../../core/login_core/login_core.service'; # 跳过Business层直接调用Core层
import { UsersRepository } from '../../core/db/users/users.repository';      # 直接访问数据层
import { RedisService } from '../../core/redis/redis.service';               # 直接访问技术服务

Gateway层文件类型检查

// ✅ Gateway层应该包含的文件类型
- *.controller.ts          # HTTP控制器
- *.dto.ts                 # 数据传输对象
- *.guard.ts               # 认证/授权守卫
- *.decorator.ts           # 参数装饰器
- *.interceptor.ts         # 拦截器
- *.filter.ts              # 异常过滤器
- *.gateway.module.ts      # 网关模块

// ❌ Gateway层不应该包含的文件类型
- *.service.ts             # 业务服务（应在Business层）
- *.repository.ts          # 数据仓库（应在Core层）
- *.entity.ts              # 数据实体（应在Core层）

Gateway层职责检查清单

• Controller方法是否只做协议转换？
• 是否使用DTO进行数据验证？
• 是否调用Business层服务而非Core层？
• 是否有统一的错误处理机制？
• 是否包含Swagger API文档？
• 是否使用限流和超时保护？

🔧 Core层规范检查

职责定义

Core层专注技术实现，不包含业务逻辑

命名规范检查

业务支撑模块（使用_core后缀）

专门为特定业务功能提供技术支撑：

✅ 正确示例：
src/core/location_broadcast_core/     # 为位置广播业务提供技术支撑
src/core/admin_core/                  # 为管理员业务提供技术支撑
src/core/user_auth_core/              # 为用户认证业务提供技术支撑
src/core/zulip_core/                  # 为Zulip集成提供技术支撑

❌ 错误示例：
src/core/location_broadcast/          # 应该是location_broadcast_core
src/core/admin/                       # 应该是admin_core

通用工具模块（不使用后缀）

提供可复用的数据访问或技术服务：

✅ 正确示例：
src/core/db/user_profiles/            # 通用的用户档案数据访问
src/core/redis/                       # 通用的Redis技术封装
src/core/utils/logger/                # 通用的日志工具服务
src/core/db/zulip_accounts/           # 通用的Zulip账户数据访问

❌ 错误示例：
src/core/db/user_profiles_core/       # 应该是user_profiles（通用工具）
src/core/redis_core/                  # 应该是redis（通用工具）

命名判断流程

1. 模块是否专门为某个特定业务功能服务？
   ├─ 是 → 检查模块名称是否体现业务领域
   │   ├─ 是 → 使用 _core 后缀
   │   └─ 否 → 重新设计模块职责
   └─ 否 → 模块是否提供通用的技术服务？
       ├─ 是 → 不使用 _core 后缀
       └─ 否 → 重新评估模块定位

2. 实际案例判断：
   - user_profiles: 通用的用户档案数据访问 → 不使用后缀 ✓
   - location_broadcast_core: 专门为位置广播业务服务 → 使用_core后缀 ✓
   - redis: 通用的缓存技术服务 → 不使用后缀 ✓
   - zulip_core: 专门为Zulip集成业务服务 → 使用_core后缀 ✓

Core层技术实现示例

// ✅ 正确：Core层专注技术实现
@Injectable()
export class LocationBroadcastCoreService {
  /**
   * 广播位置更新到指定房间
   * 
   * 技术实现：
   * 1. 验证WebSocket连接状态
   * 2. 序列化位置数据
   * 3. 通过Socket.IO广播消息
   * 4. 记录广播性能指标
   * 5. 处理广播异常和重试
   */
  async broadcastToRoom(roomId: string, data: PositionData): Promise<void> {
    const room = this.server.sockets.adapter.rooms.get(roomId);
    if (!room) {
      throw new NotFoundException(`Room ${roomId} not found`);
    }
    
    this.server.to(roomId).emit('position-update', data);
    this.metricsService.recordBroadcast(roomId, data.userId);
  }
}

// ❌ 错误：Core层包含业务逻辑
@Injectable()
export class LocationBroadcastCoreService {
  async broadcastUserPosition(userId: string, position: Position): Promise<void> {
    // 错误：包含了用户权限检查的业务概念
    const user = await this.userService.findById(userId);
    if (user.status !== UserStatus.ACTIVE) {
      throw new ForbiddenException('用户状态不允许位置广播');
    }
  }
}

Core层依赖关系检查

// ✅ 允许的导入
import { Injectable } from '@nestjs/common';           # NestJS框架
import { Server } from 'socket.io';                   # 第三方技术库
import { RedisService } from '../redis/redis.service'; # 其他Core层模块
import * as crypto from 'crypto';                     # Node.js内置模块

// ❌ 禁止的导入
import { UserBusinessService } from '../../business/users/user.service'; # Business层模块
import { AdminController } from '../../business/admin/admin.controller'; # Business层模块

💼 Business层规范检查

职责定义

Business层专注业务逻辑实现，不关心底层技术细节

业务逻辑完备性检查

// ✅ 正确：完整的业务逻辑
@Injectable()
export class UserBusinessService {
  /**
   * 用户注册业务流程
   * 
   * 业务逻辑：
   * 1. 验证用户信息完整性
   * 2. 检查用户名/邮箱是否已存在
   * 3. 验证邮箱格式和域名白名单
   * 4. 生成用户唯一标识
   * 5. 设置默认用户权限
   * 6. 发送欢迎邮件
   * 7. 记录注册日志
   * 8. 返回注册结果
   */
  async registerUser(registerData: RegisterUserDto): Promise<UserResult> {
    await this.validateUserBusinessRules(registerData);
    const user = await this.userCoreService.create(registerData);
    await this.emailService.sendWelcomeEmail(user.email);
    await this.logService.recordUserRegistration(user.id);
    return this.buildUserResult(user);
  }
}

// ❌ 错误：业务逻辑不完整
@Injectable()
export class UserBusinessService {
  async registerUser(registerData: RegisterUserDto): Promise<User> {
    // 只是简单调用数据库保存，缺少业务验证和流程
    return this.userRepository.save(registerData);
  }
}

Business层依赖关系检查

// ✅ 允许的导入
import { UserCoreService } from '../../core/user_auth_core/user_core.service';     # 对应Core层业务支撑
import { CacheService } from '../../core/redis/cache.service';                     # Core层通用工具
import { EmailService } from '../../core/utils/email.service';                     # Core层通用工具
import { OtherBusinessService } from '../other/other.service';                     # 其他Business层（谨慎）

// ❌ 禁止的导入
import { createConnection } from 'typeorm';                                        # 直接技术实现
import * as Redis from 'ioredis';                                                 # 直接技术实现
import { DatabaseConnection } from '../../core/db/connection';                     # 底层技术细节

🚨 常见架构违规

Gateway层违规示例

// ❌ 错误：Gateway层包含业务逻辑
@Controller('users')
export class UserController {
  @Post('register')
  async register(@Body() registerDto: RegisterDto): Promise<User> {
    // 违规：在Controller中实现业务验证
    if (registerDto.age < 18) {
      throw new BadRequestException('用户年龄必须大于18岁');
    }
    
    // 违规：在Controller中协调多个服务
    const user = await this.userCoreService.create(registerDto);
    await this.emailService.sendWelcomeEmail(user.email);
    await this.zulipService.createAccount(user);
    
    return user;
  }
}

// ❌ 错误：Gateway层直接调用Core层
@Controller('auth')
export class LoginController {
  constructor(
    private readonly loginCoreService: LoginCoreService,  // 违规：跳过Business层
  ) {}
  
  @Post('login')
  async login(@Body() loginDto: LoginDto): Promise<any> {
    // 违规：直接调用Core层服务
    return this.loginCoreService.login(loginDto);
  }
}

Business层违规示例

// ❌ 错误：Business层包含技术实现细节
@Injectable()
export class UserBusinessService {
  async createUser(userData: CreateUserDto): Promise<User> {
    // 违规：直接操作Redis连接
    const redis = new Redis({ host: 'localhost', port: 6379 });
    await redis.set(`user:${userData.id}`, JSON.stringify(userData));
    
    // 违规：直接写SQL语句
    const sql = 'INSERT INTO users (name, email) VALUES (?, ?)';
    await this.database.query(sql, [userData.name, userData.email]);
  }
}

Core层违规示例

// ❌ 错误：Core层包含业务逻辑
@Injectable()
export class DatabaseService {
  async saveUser(userData: CreateUserDto): Promise<User> {
    // 违规：包含用户注册的业务验证
    if (userData.age < 18) {
      throw new BadRequestException('用户年龄必须大于18岁');
    }
    
    // 违规：包含业务规则
    if (userData.email.endsWith('@competitor.com')) {
      throw new ForbiddenException('不允许竞争对手注册');
    }
  }
}

🎮 游戏服务器架构特殊检查

WebSocket Gateway分层

// ✅ 正确：Gateway在Business层，调用Core层服务
@WebSocketGateway()
export class LocationBroadcastGateway {
  constructor(
    private readonly locationBroadcastCore: LocationBroadcastCoreService,
    private readonly userProfiles: UserProfilesService,
  ) {}
  
  @SubscribeMessage('position_update')
  async handlePositionUpdate(client: Socket, data: PositionData): Promise<void> {
    // 业务逻辑：验证、权限检查
    await this.validateUserPermission(client.userId);
    
    // 调用Core层技术实现
    await this.locationBroadcastCore.broadcastToRoom(client.roomId, data);
  }
}

双模式服务分层

// ✅ 正确：Business层统一接口，Core层不同实现
@Injectable()
export class UsersBusinessService {
  constructor(
    @Inject('USERS_SERVICE') 
    private readonly usersCore: UsersMemoryService | UsersDatabaseService,
  ) {}
  
  async createUser(userData: CreateUserDto): Promise<User> {
    // 业务逻辑：验证、权限、流程
    await this.validateUserBusinessRules(userData);
    
    // 调用Core层（内存或数据库模式）
    const user = await this.usersCore.create(userData);
    
    // 业务逻辑：后续处理
    await this.sendWelcomeNotification(user);
    return user;
  }
}

🔧 NestJS依赖注入检查（重要）

依赖注入完整性检查

在NestJS中，如果一个类（如Guard、Service、Controller）需要注入其他服务，必须确保该服务在模块的imports中可访问。

常见依赖注入问题

// ❌ 错误：JwtAuthGuard需要LoginCoreService，但模块未导入LoginCoreModule
@Module({
  imports: [
    AuthModule,  // AuthModule虽然导入了LoginCoreModule，但没有重新导出
  ],
  providers: [
    JwtAuthGuard,  // 错误：无法注入LoginCoreService
  ],
})
export class AuthGatewayModule {}

@Injectable()
export class JwtAuthGuard {
  constructor(
    private readonly loginCoreService: LoginCoreService,  // 注入失败！
  ) {}
}

// ✅ 正确方案1：直接导入需要的Core模块
@Module({
  imports: [
    AuthModule,
    LoginCoreModule,  // 直接导入，使LoginCoreService可用
  ],
  providers: [
    JwtAuthGuard,  // 现在可以成功注入LoginCoreService
  ],
})
export class AuthGatewayModule {}

// ✅ 正确方案2：在中间模块重新导出
@Module({
  imports: [LoginCoreModule],
  exports: [LoginCoreModule],  // 重新导出，让导入AuthModule的模块也能访问
})
export class AuthModule {}

依赖注入检查规则

1. 检查Provider的构造函数依赖

// 对于每个Provider（Service、Guard、Interceptor等）
@Injectable()
export class SomeGuard {
  constructor(
    private readonly serviceA: ServiceA,  // 依赖1
    private readonly serviceB: ServiceB,  // 依赖2
  ) {}
}

// 检查清单：
// ✓ ServiceA是否在当前模块的imports中？
// ✓ ServiceB是否在当前模块的imports中？
// ✓ 如果不在，是否需要添加对应的Module到imports？

2. 检查Module的导出完整性

// ❌ 错误：导入了模块但没有导出，导致上层模块无法访问
@Module({
  imports: [LoginCoreModule],
  providers: [LoginService],
  exports: [LoginService],  // 只导出了LoginService，没有导出LoginCoreModule
})
export class AuthModule {}

// 如果上层模块需要直接使用LoginCoreService：
@Module({
  imports: [AuthModule],  // 无法访问LoginCoreService
  providers: [JwtAuthGuard],  // JwtAuthGuard需要LoginCoreService，会失败
})
export class AuthGatewayModule {}

// ✅ 正确：根据需要导出Module
@Module({
  imports: [LoginCoreModule],
  providers: [LoginService],
  exports: [
    LoginService,
    LoginCoreModule,  // 导出Module，让上层也能访问
  ],
})
export class AuthModule {}

3. 检查跨层依赖的模块导入

// Gateway层的Guard直接依赖Core层Service的情况
@Injectable()
export class JwtAuthGuard {
  constructor(
    private readonly loginCoreService: LoginCoreService,  // 直接依赖Core层
  ) {}
}

// 检查清单：
// ✓ AuthGatewayModule是否导入了LoginCoreModule？
// ✓ 如果通过AuthModule间接导入，AuthModule是否导出了LoginCoreModule？
// ✓ 是否符合架构分层原则（Gateway可以直接依赖Core用于技术实现）？

依赖注入检查步骤

1. 扫描所有Injectable类

   • 找出所有使用@Injectable()装饰器的类
   • 包括Service、Guard、Interceptor、Pipe等

2. 分析构造函数依赖

   • 检查每个类的constructor参数
   • 列出所有需要注入的服务

3. 检查Module的imports

   • 确认每个依赖的服务是否在Module的imports中
   • 检查imports的Module是否导出了需要的服务

4. 验证依赖链完整性

   • 如果A模块导入B模块，B模块导入C模块
   • 确认A模块是否能访问C模块的服务（取决于B是否导出C）

5. 检查常见错误模式

   • Guard/Interceptor依赖Service但模块未导入
   • 中间模块导入但未导出，导致上层无法访问
   • 循环依赖问题

依赖注入错误识别

典型错误信息

Nest can't resolve dependencies of the JwtAuthGuard (?). 
Please make sure that the argument LoginCoreService at index [0] 
is available in the AuthGatewayModule context.

错误分析流程

1. 识别问题类：JwtAuthGuard
2. 识别缺失依赖：LoginCoreService（索引0）
3. 识别所在模块：AuthGatewayModule
4. 检查解决方案：
   ├─ LoginCoreService在哪个Module中提供？
   │  └─ 答：LoginCoreModule
   ├─ AuthGatewayModule是否导入了LoginCoreModule？
   │  └─ 否 → 需要添加到imports
   └─ 如果通过其他Module间接导入，该Module是否导出了LoginCoreModule？
      └─ 否 → 需要在中间Module的exports中添加

依赖注入最佳实践

// ✅ 推荐：明确的依赖关系
@Module({
  imports: [
    // 业务层模块
    AuthModule,
    // 直接需要的核心层模块（用于Guard等技术组件）
    LoginCoreModule,
  ],
  controllers: [LoginController],
  providers: [JwtAuthGuard],
  exports: [JwtAuthGuard],
})
export class AuthGatewayModule {}

// ✅ 推荐：完整的导出链
@Module({
  imports: [LoginCoreModule, UsersModule],
  providers: [LoginService],
  exports: [
    LoginService,      // 导出自己的服务
    LoginCoreModule,   // 导出依赖的模块（如果上层需要）
  ],
})
export class AuthModule {}

🔍 检查执行步骤

1. 识别当前模块的层级

   • 确定是Gateway层、Business层还是Core层
   • 检查文件夹路径和命名
   • 根据层级应用对应的检查规则

2. Gateway层检查（如果是Gateway层）

   • 检查是否只包含协议处理代码
   • 检查是否使用DTO进行数据验证
   • 检查是否只调用Business层服务
   • 检查是否有统一的错误处理
   • 检查文件类型是否符合Gateway层规范

3. Business层检查（如果是Business层）

   • 检查是否只包含业务逻辑
   • 检查是否协调多个Core层服务
   • 检查是否返回统一的业务响应
   • 检查是否不包含HTTP协议处理

4. Core层检查（如果是Core层）

   • 检查Core层命名规范
   • 业务支撑模块是否使用_core后缀
   • 通用工具模块是否不使用后缀
   • 根据模块职责判断命名正确性
   • 检查是否只包含技术实现

5. 检查职责分离

   • Gateway层是否只做协议转换
   • Business层是否只包含业务逻辑
   • Core层是否只包含技术实现
   • 是否有跨层职责混乱

6. 🔥 检查依赖注入完整性（关键步骤）

   • 扫描所有Injectable类的构造函数依赖
   • 检查Module的imports是否包含所有依赖的Module
   • 验证中间Module是否正确导出了需要的服务
   • 确认依赖链的完整性和可访问性
   • 识别并修复常见的依赖注入错误

7. 检查依赖关系

   • Gateway层是否只依赖Business层
   • Business层是否只依赖Core层
   • Core层是否不依赖业务层
   • 依赖注入是否正确使用

8. 检查架构违规

   • 识别常见的分层违规模式
   • 检查技术实现和业务逻辑的边界
   • 检查协议处理和业务逻辑的边界
   • 确保架构清晰度

9. 游戏服务器特殊检查

   • WebSocket Gateway的分层正确性
   • 双模式服务的架构设计
   • 实时通信组件的职责分离

10. 🚀 应用启动验证（强制步骤）

    • 执行 pnpm dev 或 npm run dev 启动应用
    • 验证应用能够成功启动，无模块依赖错误
    • 检查控制台是否有依赖注入失败的错误信息
    • 如有启动错误，必须修复后重新验证

🚀 应用启动验证（强制要求）

为什么需要启动验证？

静态代码检查无法发现所有的模块依赖问题！ 以下问题只有在应用启动时才会暴露：

1. Module exports 配置错误：导出了不属于当前模块的服务
2. 依赖注入链断裂：中间模块未正确导出依赖
3. 循环依赖问题：模块间存在循环引用
4. Provider 注册遗漏：服务未在正确的模块中注册
5. CacheModule/ConfigModule 等全局模块缺失

常见启动错误示例

错误1：导出不属于当前模块的服务

UnknownExportException [Error]: Nest cannot export a provider/module that 
is not a part of the currently processed module (ZulipModule). 
Please verify whether the exported DynamicConfigManagerService is available 
in this particular context.

原因：ZulipModule 尝试导出 DynamicConfigManagerService，但该服务来自 ZulipCoreModule，不是 ZulipModule 自己的 provider。

修复方案：

// ❌ 错误：直接导出其他模块的服务
@Module({
  imports: [ZulipCoreModule],
  exports: [DynamicConfigManagerService],  // 错误！
})
export class ZulipModule {}

// ✅ 正确：导出整个模块
@Module({
  imports: [ZulipCoreModule],
  exports: [ZulipCoreModule],  // 正确：导出模块而非服务
})
export class ZulipModule {}

错误2：依赖注入失败

Nest can't resolve dependencies of the JwtAuthGuard (?). 
Please make sure that the argument LoginCoreService at index [0] 
is available in the ZulipGatewayModule context.

原因：JwtAuthGuard 需要 LoginCoreService，但 ZulipGatewayModule 没有导入 LoginCoreModule。

修复方案：

// ❌ 错误：缺少必要的模块导入
@Module({
  imports: [ZulipModule, AuthModule],
  providers: [JwtAuthGuard],
})
export class ZulipGatewayModule {}

// ✅ 正确：添加缺失的模块导入
@Module({
  imports: [
    ZulipModule, 
    AuthModule,
    LoginCoreModule,  // 添加：JwtAuthGuard 依赖 LoginCoreService
  ],
  providers: [JwtAuthGuard],
})
export class ZulipGatewayModule {}

错误3：CACHE_MANAGER 未注册

Nest can't resolve dependencies of the SomeService (?). 
Please make sure that the argument "CACHE_MANAGER" at index [2] 
is available in the SomeModule context.

原因：服务使用了 @Inject(CACHE_MANAGER)，但模块未导入 CacheModule。

修复方案：

// ❌ 错误：缺少 CacheModule
@Module({
  imports: [OtherModule],
  providers: [SomeService],
})
export class SomeModule {}

// ✅ 正确：添加 CacheModule
import { CacheModule } from '@nestjs/cache-manager';

@Module({
  imports: [
    CacheModule.register(),  // 添加缓存模块
    OtherModule,
  ],
  providers: [SomeService],
})
export class SomeModule {}

启动验证执行流程

# 1. 执行启动命令
pnpm dev
# 或
npm run dev

# 2. 观察控制台输出，检查是否有以下错误类型：
# - UnknownExportException
# - Nest can't resolve dependencies
# - Circular dependency detected
# - Module not found

# 3. 如果启动成功，应该看到类似输出：
# [Nest] LOG [NestFactory] Starting Nest application...
# [Nest] LOG [RoutesResolver] AppController {/}: +Xms
# [Nest] LOG [NestApplication] Nest application successfully started +Xms

# 4. 验证健康检查接口
curl http://localhost:3000/health
# 应返回：{"status":"ok",...}

启动验证检查清单

• 执行 pnpm dev 或 npm run dev
• 确认无 UnknownExportException 错误
• 确认无依赖注入失败错误
• 确认无循环依赖错误
• 确认应用成功启动并监听端口
• 验证健康检查接口返回正常
• 如有错误，修复后重新启动验证

🚨 启动验证失败处理

如果启动验证失败，必须：

1. 分析错误信息：识别具体的模块和依赖问题
2. 定位问题模块：找到报错的 Module 文件
3. 修复依赖配置：
   • 添加缺失的 imports
   • 修正错误的 exports
   • 注册缺失的 providers
4. 重新启动验证：修复后必须再次执行启动验证
5. 记录修改：更新文件头部的修改记录

🔥 重要：启动验证是步骤4的强制完成条件，不能跳过！

🔥 重要提醒

如果在本步骤中执行了任何修改操作（调整分层结构、修正依赖关系、重构代码等），必须立即重新执行步骤4的完整检查！

• ✅ 执行修改 → 🔥 立即重新执行步骤4 → 提供验证报告 → 等待用户确认
• ❌ 执行修改 → 直接进入步骤5（错误做法）

🚨 重要强调：纯检查步骤不更新修改记录 如果检查发现架构分层已经符合规范，无需任何修改，则：

• ❌ 禁止添加检查记录：不要添加"AI代码检查步骤4：架构分层检查和优化"
• ❌ 禁止更新时间戳：不要修改@lastModified字段
• ❌ 禁止递增版本号：不要修改@version字段
• ✅ 仅提供检查报告：说明检查结果，确认符合规范

🚀 步骤4完成的强制条件：

1. 架构分层检查通过：Gateway/Business/Core层职责清晰
2. 依赖注入检查通过：所有Module的imports/exports配置正确
3. 🔥 应用启动验证通过：执行 pnpm dev 应用能成功启动，无依赖错误

不能跳过应用启动验证环节！如果启动失败，必须修复后重新执行整个步骤4！