@su-record/vibe 2.7.18 → 2.7.20

package/languages/typescript-nestjs.md

@@ -1,524 +1,524 @@
-# 🐱 TypeScript + NestJS Quality Rules
-
-## Core Principles (inherited from core)
-
-```markdown
-✅ Single Responsibility (SRP)
-✅ Don't Repeat Yourself (DRY)
-✅ Reusability
-✅ Low Complexity
-✅ Functions ≤ 30 lines
-✅ Nesting ≤ 3 levels
-✅ Cyclomatic complexity ≤ 10
-```
-
-## NestJS Architecture
-
-```
-┌─────────────────────────────────────────────┐
-│  Controller (HTTP Request Handling)         │
-│  - Routing, request validation, response    │
-├─────────────────────────────────────────────┤
-│  Service (Business Logic)                   │
-│  - Domain logic, data processing            │
-├─────────────────────────────────────────────┤
-│  Repository (Data Access)                   │
-│  - DB queries, ORM operations               │
-└─────────────────────────────────────────────┘
-```
-
-## TypeScript/NestJS Patterns
-
-### 1. Module Structure
-
-```typescript
-// ✅ Feature Module
-@Module({
-  imports: [
-    TypeOrmModule.forFeature([User]),
-    CommonModule,
-  ],
-  controllers: [UserController],
-  providers: [UserService, UserRepository],
-  exports: [UserService],
-})
-export class UserModule {}
-
-// ✅ Module folder structure
-// src/
-// ├── user/
-// │   ├── user.module.ts
-// │   ├── user.controller.ts
-// │   ├── user.service.ts
-// │   ├── user.repository.ts
-// │   ├── dto/
-// │   │   ├── create-user.dto.ts
-// │   │   └── update-user.dto.ts
-// │   └── entities/
-// │       └── user.entity.ts
-```
-
-### 2. Controller Pattern
-
-```typescript
-// ✅ Controller
-@Controller('users')
-@ApiTags('users')
-export class UserController {
-  constructor(private readonly userService: UserService) {}
-
-  @Get()
-  @ApiOperation({ summary: 'Get all users' })
-  @ApiResponse({ status: 200, type: [UserResponseDto] })
-  async findAll(@Query() query: FindUsersQueryDto): Promise<UserResponseDto[]> {
-    return this.userService.findAll(query);
-  }
-
-  @Get(':id')
-  @ApiOperation({ summary: 'Get user by ID' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  @ApiResponse({ status: 404, description: 'User not found' })
-  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
-    return this.userService.findOne(id);
-  }
-
-  @Post()
-  @ApiOperation({ summary: 'Create user' })
-  @ApiResponse({ status: 201, type: UserResponseDto })
-  async create(@Body() createUserDto: CreateUserDto): Promise<UserResponseDto> {
-    return this.userService.create(createUserDto);
-  }
-
-  @Patch(':id')
-  async update(
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() updateUserDto: UpdateUserDto,
-  ): Promise<UserResponseDto> {
-    return this.userService.update(id, updateUserDto);
-  }
-
-  @Delete(':id')
-  @HttpCode(HttpStatus.NO_CONTENT)
-  async remove(@Param('id', ParseUUIDPipe) id: string): Promise<void> {
-    await this.userService.remove(id);
-  }
-}
-```
-
-### 3. Service Pattern
-
-```typescript
-// ✅ Service
-@Injectable()
-export class UserService {
-  constructor(
-    private readonly userRepository: UserRepository,
-    private readonly eventEmitter: EventEmitter2,
-  ) {}
-
-  async findAll(query: FindUsersQueryDto): Promise<User[]> {
-    return this.userRepository.findWithPagination(query);
-  }
-
-  async findOne(id: string): Promise<User> {
-    const user = await this.userRepository.findById(id);
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-    return user;
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const existingUser = await this.userRepository.findByEmail(dto.email);
-    if (existingUser) {
-      throw new ConflictException('Email already exists');
-    }
-
-    const user = await this.userRepository.create(dto);
-    this.eventEmitter.emit('user.created', new UserCreatedEvent(user));
-    return user;
-  }
-
-  async update(id: string, dto: UpdateUserDto): Promise<User> {
-    const user = await this.findOne(id);
-    return this.userRepository.update(user.id, dto);
-  }
-
-  async remove(id: string): Promise<void> {
-    const user = await this.findOne(id);
-    await this.userRepository.softDelete(user.id);
-    this.eventEmitter.emit('user.deleted', new UserDeletedEvent(user));
-  }
-}
-```
-
-### 4. DTO + Validation
-
-```typescript
-// ✅ Request DTO
-export class CreateUserDto {
-  @ApiProperty({ example: 'john@example.com' })
-  @IsEmail()
-  @IsNotEmpty()
-  email: string;
-
-  @ApiProperty({ example: 'John Doe' })
-  @IsString()
-  @MinLength(2)
-  @MaxLength(100)
-  name: string;
-
-  @ApiProperty({ example: 'password123' })
-  @IsString()
-  @MinLength(8)
-  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
-    message: 'Password must contain uppercase, lowercase, and number',
-  })
-  password: string;
-}
-
-// ✅ Response DTO (only Expose fields are visible)
-@Exclude()
-export class UserResponseDto {
-  @Expose()
-  @ApiProperty()
-  id: string;
-
-  @Expose()
-  @ApiProperty()
-  email: string;
-
-  @Expose()
-  @ApiProperty()
-  name: string;
-
-  @Expose()
-  @ApiProperty()
-  createdAt: Date;
-
-  // password is excluded
-}
-
-// ✅ Query DTO
-export class FindUsersQueryDto {
-  @ApiPropertyOptional()
-  @IsOptional()
-  @IsString()
-  search?: string;
-
-  @ApiPropertyOptional({ default: 1 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  page?: number = 1;
-
-  @ApiPropertyOptional({ default: 10 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit?: number = 10;
-}
-```
-
-### 5. Exception Handling
-
-```typescript
-// ✅ Custom Exception Filter
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  constructor(private readonly logger: Logger) {}
-
-  catch(exception: unknown, host: ArgumentsHost): void {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
-
-    const { status, message } = this.getErrorDetails(exception);
-
-    const errorResponse = {
-      statusCode: status,
-      timestamp: new Date().toISOString(),
-      path: request.url,
-      message,
-    };
-
-    this.logger.error(
-      `${request.method} ${request.url} - ${status}`,
-      exception instanceof Error ? exception.stack : undefined,
-    );
-
-    response.status(status).json(errorResponse);
-  }
-
-  private getErrorDetails(exception: unknown): { status: number; message: string } {
-    if (exception instanceof HttpException) {
-      return {
-        status: exception.getStatus(),
-        message: exception.message,
-      };
-    }
-
-    return {
-      status: HttpStatus.INTERNAL_SERVER_ERROR,
-      message: 'Internal server error',
-    };
-  }
-}
-
-// ✅ Business Exception
-export class UserNotFoundException extends NotFoundException {
-  constructor(userId: string) {
-    super(`User with ID ${userId} not found`);
-  }
-}
-```
-
-### 6. Guard & Interceptor
-
-```typescript
-// ✅ Auth Guard
-@Injectable()
-export class JwtAuthGuard extends AuthGuard('jwt') {
-  canActivate(context: ExecutionContext) {
-    return super.canActivate(context);
-  }
-
-  handleRequest<T>(err: Error, user: T): T {
-    if (err || !user) {
-      throw err || new UnauthorizedException();
-    }
-    return user;
-  }
-}
-
-// ✅ Role Guard
-@Injectable()
-export class RolesGuard implements CanActivate {
-  constructor(private reflector: Reflector) {}
-
-  canActivate(context: ExecutionContext): boolean {
-    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(
-      ROLES_KEY,
-      [context.getHandler(), context.getClass()],
-    );
-    if (!requiredRoles) {
-      return true;
-    }
-    const { user } = context.switchToHttp().getRequest();
-    return requiredRoles.some((role) => user.roles?.includes(role));
-  }
-}
-
-// ✅ Transform Interceptor
-@Injectable()
-export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
-    return next.handle().pipe(
-      map((data) => ({
-        success: true,
-        data,
-        timestamp: new Date().toISOString(),
-      })),
-    );
-  }
-}
-```
-
-### 7. Repository Pattern (TypeORM)
-
-```typescript
-// ✅ Custom Repository
-@Injectable()
-export class UserRepository {
-  constructor(
-    @InjectRepository(User)
-    private readonly repo: Repository<User>,
-  ) {}
-
-  async findById(id: string): Promise<User | null> {
-    return this.repo.findOne({ where: { id } });
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.repo.findOne({ where: { email } });
-  }
-
-  async findWithPagination(query: FindUsersQueryDto): Promise<User[]> {
-    const { search, page, limit } = query;
-    const qb = this.repo.createQueryBuilder('user');
-
-    if (search) {
-      qb.where('user.name ILIKE :search OR user.email ILIKE :search', {
-        search: `%${search}%`,
-      });
-    }
-
-    return qb
-      .skip((page - 1) * limit)
-      .take(limit)
-      .orderBy('user.createdAt', 'DESC')
-      .getMany();
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const user = this.repo.create(dto);
-    return this.repo.save(user);
-  }
-
-  async update(id: string, dto: UpdateUserDto): Promise<User> {
-    await this.repo.update(id, dto);
-    return this.findById(id);
-  }
-
-  async softDelete(id: string): Promise<void> {
-    await this.repo.softDelete(id);
-  }
-}
-```
-
-### 8. Configuration
-
-```typescript
-// ✅ Config Module
-@Module({
-  imports: [
-    ConfigModule.forRoot({
-      isGlobal: true,
-      validationSchema: Joi.object({
-        NODE_ENV: Joi.string().valid('development', 'production', 'test').required(),
-        PORT: Joi.number().default(3000),
-        DATABASE_URL: Joi.string().required(),
-        JWT_SECRET: Joi.string().required(),
-        JWT_EXPIRES_IN: Joi.string().default('1d'),
-      }),
-    }),
-  ],
-})
-export class AppConfigModule {}
-
-// ✅ Typed Config Service
-@Injectable()
-export class AppConfigService {
-  constructor(private configService: ConfigService) {}
-
-  get port(): number {
-    return this.configService.get<number>('PORT', 3000);
-  }
-
-  get databaseUrl(): string {
-    return this.configService.getOrThrow<string>('DATABASE_URL');
-  }
-
-  get jwtSecret(): string {
-    return this.configService.getOrThrow<string>('JWT_SECRET');
-  }
-
-  get isProduction(): boolean {
-    return this.configService.get('NODE_ENV') === 'production';
-  }
-}
-```
-
-## Recommended Folder Structure
-
-```
-src/
-├── main.ts
-├── app.module.ts
-├── common/                 # Shared module
-│   ├── decorators/
-│   ├── filters/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── pipes/
-│   └── common.module.ts
-├── config/                 # Configuration
-│   ├── app.config.ts
-│   └── database.config.ts
-├── user/                   # Feature module
-│   ├── dto/
-│   ├── entities/
-│   ├── user.controller.ts
-│   ├── user.service.ts
-│   ├── user.repository.ts
-│   └── user.module.ts
-└── auth/
-    ├── strategies/
-    ├── guards/
-    └── auth.module.ts
-```
-
-## Testing
-
-```typescript
-// ✅ Unit Test
-describe('UserService', () => {
-  let service: UserService;
-  let repository: MockType<UserRepository>;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        UserService,
-        {
-          provide: UserRepository,
-          useFactory: () => ({
-            findById: jest.fn(),
-            create: jest.fn(),
-          }),
-        },
-      ],
-    }).compile();
-
-    service = module.get(UserService);
-    repository = module.get(UserRepository);
-  });
-
-  it('should create a user', async () => {
-    const dto = { email: 'test@test.com', name: 'Test' };
-    repository.create.mockResolvedValue({ id: '1', ...dto });
-
-    const result = await service.create(dto);
-    expect(result.email).toBe(dto.email);
-  });
-});
-
-// ✅ E2E Test
-describe('UserController (e2e)', () => {
-  let app: INestApplication;
-
-  beforeAll(async () => {
-    const module = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = module.createNestApplication();
-    await app.init();
-  });
-
-  it('/users (GET)', () => {
-    return request(app.getHttpServer())
-      .get('/users')
-      .expect(200)
-      .expect((res) => {
-        expect(Array.isArray(res.body)).toBe(true);
-      });
-  });
-});
-```
-
-## Checklist
-
-- [ ] Separate request/response types with DTOs
-- [ ] Validate with class-validator
-- [ ] Serialize with class-transformer
-- [ ] Use custom Exceptions
-- [ ] Apply Repository pattern
-- [ ] Handle auth/authorization with Guards
-- [ ] Transform responses with Interceptors
-- [ ] Validate environment variables with ConfigModule
-- [ ] Document API with Swagger
-- [ ] Write Unit + E2E tests
+# 🐱 TypeScript + NestJS Quality Rules
+
+## Core Principles (inherited from core)
+
+```markdown
+✅ Single Responsibility (SRP)
+✅ Don't Repeat Yourself (DRY)
+✅ Reusability
+✅ Low Complexity
+✅ Functions ≤ 30 lines
+✅ Nesting ≤ 3 levels
+✅ Cyclomatic complexity ≤ 10
+```
+
+## NestJS Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  Controller (HTTP Request Handling)         │
+│  - Routing, request validation, response    │
+├─────────────────────────────────────────────┤
+│  Service (Business Logic)                   │
+│  - Domain logic, data processing            │
+├─────────────────────────────────────────────┤
+│  Repository (Data Access)                   │
+│  - DB queries, ORM operations               │
+└─────────────────────────────────────────────┘
+```
+
+## TypeScript/NestJS Patterns
+
+### 1. Module Structure
+
+```typescript
+// ✅ Feature Module
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([User]),
+    CommonModule,
+  ],
+  controllers: [UserController],
+  providers: [UserService, UserRepository],
+  exports: [UserService],
+})
+export class UserModule {}
+
+// ✅ Module folder structure
+// src/
+// ├── user/
+// │   ├── user.module.ts
+// │   ├── user.controller.ts
+// │   ├── user.service.ts
+// │   ├── user.repository.ts
+// │   ├── dto/
+// │   │   ├── create-user.dto.ts
+// │   │   └── update-user.dto.ts
+// │   └── entities/
+// │       └── user.entity.ts
+```
+
+### 2. Controller Pattern
+
+```typescript
+// ✅ Controller
+@Controller('users')
+@ApiTags('users')
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get()
+  @ApiOperation({ summary: 'Get all users' })
+  @ApiResponse({ status: 200, type: [UserResponseDto] })
+  async findAll(@Query() query: FindUsersQueryDto): Promise<UserResponseDto[]> {
+    return this.userService.findAll(query);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
+    return this.userService.findOne(id);
+  }
+
+  @Post()
+  @ApiOperation({ summary: 'Create user' })
+  @ApiResponse({ status: 201, type: UserResponseDto })
+  async create(@Body() createUserDto: CreateUserDto): Promise<UserResponseDto> {
+    return this.userService.create(createUserDto);
+  }
+
+  @Patch(':id')
+  async update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() updateUserDto: UpdateUserDto,
+  ): Promise<UserResponseDto> {
+    return this.userService.update(id, updateUserDto);
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async remove(@Param('id', ParseUUIDPipe) id: string): Promise<void> {
+    await this.userService.remove(id);
+  }
+}
+```
+
+### 3. Service Pattern
+
+```typescript
+// ✅ Service
+@Injectable()
+export class UserService {
+  constructor(
+    private readonly userRepository: UserRepository,
+    private readonly eventEmitter: EventEmitter2,
+  ) {}
+
+  async findAll(query: FindUsersQueryDto): Promise<User[]> {
+    return this.userRepository.findWithPagination(query);
+  }
+
+  async findOne(id: string): Promise<User> {
+    const user = await this.userRepository.findById(id);
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+    return user;
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const existingUser = await this.userRepository.findByEmail(dto.email);
+    if (existingUser) {
+      throw new ConflictException('Email already exists');
+    }
+
+    const user = await this.userRepository.create(dto);
+    this.eventEmitter.emit('user.created', new UserCreatedEvent(user));
+    return user;
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<User> {
+    const user = await this.findOne(id);
+    return this.userRepository.update(user.id, dto);
+  }
+
+  async remove(id: string): Promise<void> {
+    const user = await this.findOne(id);
+    await this.userRepository.softDelete(user.id);
+    this.eventEmitter.emit('user.deleted', new UserDeletedEvent(user));
+  }
+}
+```
+
+### 4. DTO + Validation
+
+```typescript
+// ✅ Request DTO
+export class CreateUserDto {
+  @ApiProperty({ example: 'john@example.com' })
+  @IsEmail()
+  @IsNotEmpty()
+  email: string;
+
+  @ApiProperty({ example: 'John Doe' })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(100)
+  name: string;
+
+  @ApiProperty({ example: 'password123' })
+  @IsString()
+  @MinLength(8)
+  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
+    message: 'Password must contain uppercase, lowercase, and number',
+  })
+  password: string;
+}
+
+// ✅ Response DTO (only Expose fields are visible)
+@Exclude()
+export class UserResponseDto {
+  @Expose()
+  @ApiProperty()
+  id: string;
+
+  @Expose()
+  @ApiProperty()
+  email: string;
+
+  @Expose()
+  @ApiProperty()
+  name: string;
+
+  @Expose()
+  @ApiProperty()
+  createdAt: Date;
+
+  // password is excluded
+}
+
+// ✅ Query DTO
+export class FindUsersQueryDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({ default: 10 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 10;
+}
+```
+
+### 5. Exception Handling
+
+```typescript
+// ✅ Custom Exception Filter
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  constructor(private readonly logger: Logger) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const { status, message } = this.getErrorDetails(exception);
+
+    const errorResponse = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      message,
+    };
+
+    this.logger.error(
+      `${request.method} ${request.url} - ${status}`,
+      exception instanceof Error ? exception.stack : undefined,
+    );
+
+    response.status(status).json(errorResponse);
+  }
+
+  private getErrorDetails(exception: unknown): { status: number; message: string } {
+    if (exception instanceof HttpException) {
+      return {
+        status: exception.getStatus(),
+        message: exception.message,
+      };
+    }
+
+    return {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message: 'Internal server error',
+    };
+  }
+}
+
+// ✅ Business Exception
+export class UserNotFoundException extends NotFoundException {
+  constructor(userId: string) {
+    super(`User with ID ${userId} not found`);
+  }
+}
+```
+
+### 6. Guard & Interceptor
+
+```typescript
+// ✅ Auth Guard
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  canActivate(context: ExecutionContext) {
+    return super.canActivate(context);
+  }
+
+  handleRequest<T>(err: Error, user: T): T {
+    if (err || !user) {
+      throw err || new UnauthorizedException();
+    }
+    return user;
+  }
+}
+
+// ✅ Role Guard
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+    if (!requiredRoles) {
+      return true;
+    }
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+}
+
+// ✅ Transform Interceptor
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
+    return next.handle().pipe(
+      map((data) => ({
+        success: true,
+        data,
+        timestamp: new Date().toISOString(),
+      })),
+    );
+  }
+}
+```
+
+### 7. Repository Pattern (TypeORM)
+
+```typescript
+// ✅ Custom Repository
+@Injectable()
+export class UserRepository {
+  constructor(
+    @InjectRepository(User)
+    private readonly repo: Repository<User>,
+  ) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.repo.findOne({ where: { id } });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.repo.findOne({ where: { email } });
+  }
+
+  async findWithPagination(query: FindUsersQueryDto): Promise<User[]> {
+    const { search, page, limit } = query;
+    const qb = this.repo.createQueryBuilder('user');
+
+    if (search) {
+      qb.where('user.name ILIKE :search OR user.email ILIKE :search', {
+        search: `%${search}%`,
+      });
+    }
+
+    return qb
+      .skip((page - 1) * limit)
+      .take(limit)
+      .orderBy('user.createdAt', 'DESC')
+      .getMany();
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const user = this.repo.create(dto);
+    return this.repo.save(user);
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<User> {
+    await this.repo.update(id, dto);
+    return this.findById(id);
+  }
+
+  async softDelete(id: string): Promise<void> {
+    await this.repo.softDelete(id);
+  }
+}
+```
+
+### 8. Configuration
+
+```typescript
+// ✅ Config Module
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      validationSchema: Joi.object({
+        NODE_ENV: Joi.string().valid('development', 'production', 'test').required(),
+        PORT: Joi.number().default(3000),
+        DATABASE_URL: Joi.string().required(),
+        JWT_SECRET: Joi.string().required(),
+        JWT_EXPIRES_IN: Joi.string().default('1d'),
+      }),
+    }),
+  ],
+})
+export class AppConfigModule {}
+
+// ✅ Typed Config Service
+@Injectable()
+export class AppConfigService {
+  constructor(private configService: ConfigService) {}
+
+  get port(): number {
+    return this.configService.get<number>('PORT', 3000);
+  }
+
+  get databaseUrl(): string {
+    return this.configService.getOrThrow<string>('DATABASE_URL');
+  }
+
+  get jwtSecret(): string {
+    return this.configService.getOrThrow<string>('JWT_SECRET');
+  }
+
+  get isProduction(): boolean {
+    return this.configService.get('NODE_ENV') === 'production';
+  }
+}
+```
+
+## Recommended Folder Structure
+
+```
+src/
+├── main.ts
+├── app.module.ts
+├── common/                 # Shared module
+│   ├── decorators/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   ├── pipes/
+│   └── common.module.ts
+├── config/                 # Configuration
+│   ├── app.config.ts
+│   └── database.config.ts
+├── user/                   # Feature module
+│   ├── dto/
+│   ├── entities/
+│   ├── user.controller.ts
+│   ├── user.service.ts
+│   ├── user.repository.ts
+│   └── user.module.ts
+└── auth/
+    ├── strategies/
+    ├── guards/
+    └── auth.module.ts
+```
+
+## Testing
+
+```typescript
+// ✅ Unit Test
+describe('UserService', () => {
+  let service: UserService;
+  let repository: MockType<UserRepository>;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        UserService,
+        {
+          provide: UserRepository,
+          useFactory: () => ({
+            findById: jest.fn(),
+            create: jest.fn(),
+          }),
+        },
+      ],
+    }).compile();
+
+    service = module.get(UserService);
+    repository = module.get(UserRepository);
+  });
+
+  it('should create a user', async () => {
+    const dto = { email: 'test@test.com', name: 'Test' };
+    repository.create.mockResolvedValue({ id: '1', ...dto });
+
+    const result = await service.create(dto);
+    expect(result.email).toBe(dto.email);
+  });
+});
+
+// ✅ E2E Test
+describe('UserController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    await app.init();
+  });
+
+  it('/users (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/users')
+      .expect(200)
+      .expect((res) => {
+        expect(Array.isArray(res.body)).toBe(true);
+      });
+  });
+});
+```
+
+## Checklist
+
+- [ ] Separate request/response types with DTOs
+- [ ] Validate with class-validator
+- [ ] Serialize with class-transformer
+- [ ] Use custom Exceptions
+- [ ] Apply Repository pattern
+- [ ] Handle auth/authorization with Guards
+- [ ] Transform responses with Interceptors
+- [ ] Validate environment variables with ConfigModule
+- [ ] Document API with Swagger
+- [ ] Write Unit + E2E tests