first commit

backend/src/app.controller.spec.ts

@@ -0,0 +1,22 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+describe('AppController', () => {
+  let appController: AppController;
+
+  beforeEach(async () => {
+    const app: TestingModule = await Test.createTestingModule({
+      controllers: [AppController],
+      providers: [AppService],
+    }).compile();
+
+    appController = app.get<AppController>(AppController);
+  });
+
+  describe('root', () => {
+    it('should return "Hello World!"', () => {
+      expect(appController.getHello()).toBe('Hello World!');
+    });
+  });
+});

backend/src/app.controller.ts

@@ -0,0 +1,16 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { AppService } from './app.service';
+
+// 루트 컨트롤러 — 헬스체크/디버그 용 단순 엔드포인트
+@ApiTags('App')
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get('hello')
+  @ApiOperation({ summary: '동작 확인용 Hello World' })
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}

backend/src/app.module.ts

@@ -0,0 +1,72 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ConfigModule } from '@nestjs/config';
+import { ScheduleModule } from '@nestjs/schedule';
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import { CacheModule } from '@nestjs/cache-manager';
+import { APP_GUARD } from '@nestjs/core';
+
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { HealthModule } from './modules/health/health.module';
+import { UserModule } from './modules/user/user.module';
+
+@Module({
+  imports: [
+    ScheduleModule.forRoot(),
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: `.env.${process.env.NODE_ENV || 'development'}`,
+    }),
+    // 전역 캐시 매니저 — Redis 도입 시 store 옵션을 redisStore 로 변경
+    CacheModule.register({
+      isGlobal: true,
+      ttl: 60_000, // 60초 기본 TTL
+    }),
+    // 전역 Rate Limiter — main.ts 의 express-rate-limit 와 별개로 라우트 단위 제어 가능
+    ThrottlerModule.forRoot([
+      {
+        ttl: 60_000,
+        limit: 100,
+      },
+    ]),
+    TypeOrmModule.forRootAsync({
+      useFactory: () => {
+        const isProduction = process.env.NODE_ENV === 'production';
+        return {
+          type: 'postgres',
+          host: process.env.DB_HOST || 'db',
+          port: parseInt(process.env.DB_PORT || '5432', 10),
+          username:
+            process.env.DB_USER || process.env.DB_USERNAME || 'postgres',
+          password: process.env.DB_PASSWORD || 'password',
+          database:
+            process.env.DB_NAME || process.env.DB_DATABASE || 'project_db',
+          autoLoadEntities: true,
+          // 운영 환경에서는 절대 synchronize 사용 금지 (스키마 자동 변경 → 데이터 손실 위험)
+          synchronize: !isProduction,
+          migrationsRun: isProduction,
+          logging: !isProduction,
+          extra: {
+            max: 100,
+            connectionTimeoutMillis: 5000,
+            idleTimeoutMillis: 30000,
+          },
+          entities: [__dirname + '/**/*.entity{.ts,.js}'],
+          migrations: [__dirname + '/migrations/*{.ts,.js}'],
+        };
+      },
+    }),
+    HealthModule,
+    UserModule,
+  ],
+  controllers: [AppController],
+  providers: [
+    AppService,
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+  ],
+})
+export class AppModule {}

backend/src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}

backend/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,72 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Response } from 'express';
+
+// 전역 Exception Filter — CLAUDE.md 에러 코드 맵에 따라 표준 응답으로 변환
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(HttpExceptionFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    let status: number = HttpStatus.INTERNAL_SERVER_ERROR;
+    let code = 'SYS_001';
+    let message = '일시적인 시스템 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.';
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+
+      if (status === HttpStatus.UNAUTHORIZED) {
+        code = 'AUTH_001';
+        message = '로그인이 필요한 서비스입니다. 로그인 후 이용해 주세요.';
+      } else if (status === HttpStatus.FORBIDDEN) {
+        code = 'AUTH_003';
+        message = '해당 메뉴나 기능에 접근할 수 있는 권한이 없습니다.';
+      } else if (status === HttpStatus.NOT_FOUND) {
+        code = 'RES_001';
+        message = '요청하신 정보나 페이지를 찾을 수 없습니다.';
+      } else if (
+        status === HttpStatus.BAD_REQUEST ||
+        status === HttpStatus.UNPROCESSABLE_ENTITY
+      ) {
+        code = 'VAL_001';
+        message = '입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)';
+      } else {
+        code = 'BIZ_001';
+        message = '요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요.';
+
+        // 비즈니스 예외에서는 사용자에게 보일 메시지를 재정의 가능
+        if (
+          typeof exceptionResponse === 'object' &&
+          exceptionResponse !== null &&
+          'message' in exceptionResponse
+        ) {
+          const responseMessage = (exceptionResponse as { message: unknown }).message;
+          if (typeof responseMessage === 'string') {
+            message = responseMessage;
+          }
+        }
+      }
+    } else {
+      // 정의되지 않은 예외 → 운영팀이 추적 가능하도록 로그 + SYS_001 응답 유지
+      this.logger.error('Unhandled Exception', exception as Error);
+    }
+
+    response.status(status).json({
+      success: false,
+      error: {
+        code,
+        message,
+      },
+    });
+  }
+}

backend/src/common/interceptors/transform.interceptor.ts

@@ -0,0 +1,31 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface StandardResponse<T> {
+  success: boolean;
+  data: T;
+}
+
+@Injectable()
+export class TransformInterceptor<T>
+  implements NestInterceptor<T, StandardResponse<T>>
+{
+  intercept(
+    _context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<StandardResponse<T>> {
+    // 이미 Http 응답객체인 경우 등 예외처리가 필요할 수 있으나 기본적으로 data 래핑
+    return next.handle().pipe(
+      map((data) => ({
+        success: true,
+        data: data !== undefined ? data : null,
+      })),
+    );
+  }
+}

backend/src/main.ts

@@ -0,0 +1,103 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { Logger, RequestMethod, ValidationPipe } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { WinstonModule } from 'nest-winston';
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
+import type { Request as ExpressRequest, Response as ExpressResponse } from 'express';
+
+import { HttpExceptionFilter } from './common/filters/http-exception.filter';
+import { TransformInterceptor } from './common/interceptors/transform.interceptor';
+import { winstonConfig } from './shared/logger/winston.config';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, {
+    logger: WinstonModule.createLogger(winstonConfig),
+  });
+
+  // 리버스 프록시(Nginx, Docker 배포 환경 등) 뒤에서 올바른 클라이언트 IP 식별 지원을 위해 설정합니다.
+  const expressApp = app.getHttpAdapter().getInstance();
+  expressApp.set('trust proxy', 1);
+
+  // 글로벌 prefix — 모든 라우트가 /api/* 로 정규화됨 (Flutter, Web 양쪽 baseURL과 일치)
+  app.setGlobalPrefix('api', {
+    // 헬스체크 / 루트 상태 엔드포인트는 prefix 미적용
+    exclude: [{ path: '/', method: RequestMethod.GET }],
+  });
+
+  // 기본 주소('/') 접속 시 상태 확인용 텍스트 응답 추가
+  expressApp.get('/', (_req: ExpressRequest, res: ExpressResponse) => {
+    res.send('Backend API Server is running 정상 구동 중입니다.');
+  });
+
+  // 1. 보안 헤더 (Helmet) - XSS 방지 및 기본 웹 보안
+  app.use(helmet());
+
+  // 2. 화이트리스트 기반 CORS 정책
+  const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:5173';
+  const corsOriginEnv = process.env.CORS_ORIGIN;
+
+  app.enableCors({
+    origin: (
+      origin: string | undefined,
+      callback: (err: Error | null, allow?: boolean) => void,
+    ) => {
+      // 서버간의 통신(origin이 undefined)이거나 명시된 리스트일 때만 허용
+      const whitelist = [frontendUrl, 'http://localhost:3000'];
+      if (corsOriginEnv) whitelist.push(corsOriginEnv);
+
+      if (!origin || whitelist.indexOf(origin) !== -1) {
+        callback(null, true);
+      } else {
+        // 클라이언트에는 403 금지 에러로 리턴됨
+        callback(new Error('CORS 정책에 의해 차단된 도메인입니다.'));
+      }
+    },
+    credentials: true, // 쿠키 교환 허용
+  });
+
+  // 3. 글로벌 Rate Limiting 적용 (DDoS, 브루트포스 예방)
+  app.use(
+    rateLimit({
+      windowMs: 15 * 60 * 1000, // 15분
+      max: 150, // 15분 IP당 최대 150개 요청
+      message: {
+        success: false,
+        error: {
+          code: 'SYS_001',
+          message: '일시적인 시스템 오류가 발생했습니다. (요청 한도 초과) 잠시 후 다시 시도해 주세요.', // 글로벌 통합 에러 포맷
+        }
+      },
+    }),
+  );
+
+  // 4. 전역 DTO 유효성 파이프 (강력한 검증 단계)
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true, // DTO에 불필요한 값이 오면 삭제
+      forbidNonWhitelisted: true, // DTO에 없는 필드가 주입되면 400 에러 발생
+      transform: true, // 네트워크 데이터를 DTO나 기본 타입으로 자동 변환
+    }),
+  );
+
+  // 5. 프론트엔드 연동을 위한 규격화된 에러 & 성공 페이로드 인터셉터 적용
+  app.useGlobalFilters(new HttpExceptionFilter());
+  app.useGlobalInterceptors(new TransformInterceptor());
+
+  // 6. Swagger API 문서 설정
+  const config = new DocumentBuilder()
+    .setTitle('Backend API Documentation')
+    .setDescription('The API documentation conforming to the global guidelines')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api-docs', app, document);
+
+  const port = Number(process.env.PORT ?? 3000);
+  await app.listen(port, '0.0.0.0');
+  Logger.log(`🚀 Backend running on http://localhost:${port}/api`, 'Bootstrap');
+  Logger.log(`📘 Swagger docs at  http://localhost:${port}/api-docs`, 'Bootstrap');
+}
+bootstrap();

backend/src/modules/health/health.controller.ts

@@ -0,0 +1,24 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+  HealthCheck,
+  HealthCheckService,
+  TypeOrmHealthIndicator,
+} from '@nestjs/terminus';
+
+// 헬스체크 엔드포인트 — Docker healthcheck, 모니터링 시스템에서 사용
+@ApiTags('Health')
+@Controller('health')
+export class HealthController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly db: TypeOrmHealthIndicator,
+  ) {}
+
+  @Get()
+  @HealthCheck()
+  @ApiOperation({ summary: '애플리케이션 상태 확인' })
+  check() {
+    return this.health.check([() => this.db.pingCheck('database')]);
+  }
+}

backend/src/modules/health/health.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { HealthController } from './health.controller';
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+})
+export class HealthModule {}

backend/src/modules/user/dto/create-user.dto.ts

@@ -0,0 +1,20 @@
+import { IsEmail, IsNotEmpty, IsString, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+// 사용자 생성 DTO 샘플 — 모든 검증 메시지는 한국어, Swagger 메타 필수
+export class CreateUserDto {
+  @ApiProperty({ description: '사용자 이메일', example: 'user@example.com' })
+  @IsEmail({}, { message: '올바른 이메일 형식을 입력해 주세요.' })
+  @IsNotEmpty({ message: '이메일은 필수 입력 항목입니다.' })
+  email!: string;
+
+  @ApiProperty({ description: '비밀번호 (최소 8자)', example: 'password123' })
+  @IsString()
+  @MinLength(8, { message: '비밀번호는 최소 8자 이상이어야 합니다.' })
+  password!: string;
+
+  @ApiProperty({ description: '사용자 이름', example: '홍길동' })
+  @IsString()
+  @IsNotEmpty({ message: '이름은 필수 입력 항목입니다.' })
+  name!: string;
+}

backend/src/modules/user/user.controller.ts

@@ -0,0 +1,28 @@
+import { Body, Controller, Get, Param, ParseIntPipe, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { UserService } from './user.service';
+import { CreateUserDto } from './dto/create-user.dto';
+
+// 사용자 도메인 컨트롤러 샘플 — 라우팅과 입출력만 담당, 비즈니스 로직은 모두 service 위임
+@ApiTags('User')
+@ApiBearerAuth()
+@Controller('users')
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get(':id')
+  @ApiOperation({ summary: '사용자 단건 조회' })
+  @ApiResponse({ status: 200, description: '사용자 조회 성공' })
+  @ApiResponse({ status: 404, description: '사용자를 찾을 수 없음 (RES_001)' })
+  findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.userService.findOne(id);
+  }
+
+  @Post()
+  @ApiOperation({ summary: '사용자 생성' })
+  @ApiResponse({ status: 201, description: '사용자 생성 성공' })
+  @ApiResponse({ status: 400, description: '입력값 검증 실패 (VAL_001)' })
+  create(@Body() dto: CreateUserDto) {
+    return this.userService.create(dto);
+  }
+}

backend/src/modules/user/user.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { UserController } from './user.controller';
+import { UserService } from './user.service';
+
+@Module({
+  controllers: [UserController],
+  providers: [UserService],
+  exports: [UserService],
+})
+export class UserModule {}

backend/src/modules/user/user.service.ts

@@ -0,0 +1,25 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { CreateUserDto } from './dto/create-user.dto';
+
+// 비즈니스 로직 계층 샘플 — 실제 구현 시 Repository 주입하여 데이터 접근
+@Injectable()
+export class UserService {
+  // 임시 인메모리 저장소 — Repository 도입 시 교체
+  private readonly users = new Map<number, { id: number; email: string; name: string }>();
+
+  findOne(id: number) {
+    const user = this.users.get(id);
+    if (!user) {
+      // 404 → 전역 필터에서 RES_001 로 변환됨
+      throw new NotFoundException();
+    }
+    return user;
+  }
+
+  create(dto: CreateUserDto) {
+    const id = this.users.size + 1;
+    const user = { id, email: dto.email, name: dto.name };
+    this.users.set(id, user);
+    return user;
+  }
+}

backend/src/shared/logger/winston.config.ts

@@ -0,0 +1,20 @@
+import { utilities as nestWinstonUtilities } from 'nest-winston';
+import * as winston from 'winston';
+
+// 표준 로거 설정 — console.log 대체용
+// 운영 환경에서는 파일 로테이션 또는 외부 로그 수집기(예: Loki, ELK) 추가 권장
+export const winstonConfig: winston.LoggerOptions = {
+  level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.ms(),
+        nestWinstonUtilities.format.nestLike('App', {
+          colors: process.env.NODE_ENV !== 'production',
+          prettyPrint: true,
+        }),
+      ),
+    }),
+  ],
+};

backend/src/shared/utils/format.ts

@@ -0,0 +1,13 @@
+// 공통 포맷터 — 부수효과 없는 순수 함수만 작성
+
+/**
+ * Date 또는 ISO 문자열을 'YYYY-MM-DD' 형식으로 변환
+ */
+export function formatDate(input: Date | string): string {
+  const date = typeof input === 'string' ? new Date(input) : input;
+  if (Number.isNaN(date.getTime())) return '';
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, '0');
+  const dd = String(date.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}