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,74 @@
+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';
+import { EventsModule } from './modules/events/events.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,
+    EventsModule,
+  ],
+  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/events/dto/ongoing-event.dto.ts

@@ -0,0 +1,43 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+// 진행중 이벤트 응답 DTO (sa.nexon.com 이벤트 목록 크롤링 결과)
+export class OngoingEventDto {
+  @ApiProperty({ description: '이벤트 제목', example: '다이너마트 오픈!' })
+  title!: string;
+
+  @ApiProperty({
+    description: '이벤트 요약 설명',
+    example: '정채연, 웬디 캐릭터 영구제와 프라임 치어리더II 획득의 기회!',
+  })
+  sub!: string;
+
+  @ApiProperty({
+    description: '이벤트 배너 이미지 URL',
+    example: 'https://img-sa-file.nexon.com/event/20260611072536.jpg',
+  })
+  image!: string;
+
+  @ApiProperty({
+    description: '이벤트 기간',
+    example: '2026.06.11 ~ 2026.06.25',
+  })
+  period!: string;
+
+  @ApiProperty({
+    description: '원문 상세 페이지 링크',
+    example: 'https://sa.nexon.com/news/events/view.aspx?n4ArticleSN=2095',
+  })
+  link!: string;
+
+  @ApiProperty({
+    description: '종료까지 남은 일수 (예: D-14, D-DAY)',
+    example: 'D-14',
+  })
+  dday!: string;
+
+  @ApiProperty({
+    description: '분류 태그 (이벤트 / 업데이트)',
+    example: '이벤트',
+  })
+  tag!: string;
+}

backend/src/modules/events/entities/sa-event.entity.ts

@@ -0,0 +1,39 @@
+import {
+  Column,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+// 진행중 이벤트 저장 테이블 (주 1회 크롤링 결과를 영속화)
+// ※ D-day 는 기간(period)에 따라 조회 시점마다 달라지므로 저장하지 않고 읽을 때 계산한다.
+@Entity('sa_events')
+export class SaEventEntity {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ type: 'varchar', length: 300 })
+  title!: string;
+
+  @Column({ type: 'varchar', length: 500, default: '' })
+  sub!: string;
+
+  @Column({ type: 'varchar', length: 1000, default: '' })
+  image!: string;
+
+  @Column({ type: 'varchar', length: 100, default: '' })
+  period!: string;
+
+  @Column({ type: 'varchar', length: 1000, default: '' })
+  link!: string;
+
+  @Column({ type: 'varchar', length: 20, default: '이벤트' })
+  tag!: string;
+
+  // 크롤링 순서(사이트 노출 순서) 유지용
+  @Column({ type: 'int', default: 0 })
+  sortOrder!: number;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}

backend/src/modules/events/events.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+
+import { EventsService } from './events.service';
+import { OngoingEventDto } from './dto/ongoing-event.dto';
+
+@ApiTags('Events')
+@Controller('events')
+export class EventsController {
+  constructor(private readonly eventsService: EventsService) {}
+
+  @Get('ongoing')
+  @ApiOperation({
+    summary: '진행중 이벤트 목록 조회',
+    description:
+      'DB에 저장된 진행중 이벤트를 반환합니다. 원본 데이터는 매주 목요일 10:01(KST) 1회 크롤링으로 갱신됩니다. (방문마다 크롤링하지 않음)',
+  })
+  @ApiResponse({
+    status: 200,
+    description: '진행중 이벤트 목록 (없으면 빈 배열)',
+    type: [OngoingEventDto],
+  })
+  getOngoing(): Promise<OngoingEventDto[]> {
+    return this.eventsService.getOngoing();
+  }
+}

backend/src/modules/events/events.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { EventsController } from './events.controller';
+import { EventsService } from './events.service';
+import { SaEventEntity } from './entities/sa-event.entity';
+
+// 진행중 이벤트 모듈 — 주 1회 크롤링(스케줄) + DB 영속
+@Module({
+  imports: [TypeOrmModule.forFeature([SaEventEntity])],
+  controllers: [EventsController],
+  providers: [EventsService],
+  exports: [EventsService],
+})
+export class EventsModule {}

backend/src/modules/events/events.service.ts

@@ -0,0 +1,194 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { Cron } from '@nestjs/schedule';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { load } from 'cheerio';
+
+import { curlFetchHtml } from '../../shared/utils/curl-fetch';
+import { OngoingEventDto } from './dto/ongoing-event.dto';
+import { SaEventEntity } from './entities/sa-event.entity';
+
+// ────────────────────────────────────────────────────────────
+// 서든어택 진행중 이벤트 — 주 1회 크롤링 후 DB 영속, 유저에겐 DB에서 서빙.
+// 출처: https://sa.nexon.com/news/events/list.aspx (서버렌더 HTML)
+// 갱신 시점: 매주 목요일 10:01(KST) — 정기점검 종료 직후. (방문마다 크롤링 X)
+// ────────────────────────────────────────────────────────────
+@Injectable()
+export class EventsService implements OnModuleInit {
+  private readonly logger = new Logger(EventsService.name);
+
+  private static readonly SOURCE_URL =
+    'https://sa.nexon.com/news/events/list.aspx';
+  private static readonly REFERER = 'https://sa.nexon.com/';
+  private static readonly MAX_PAGES = 10; // 페이지네이션 안전 상한 (무한루프 방지)
+
+  constructor(
+    @InjectRepository(SaEventEntity)
+    private readonly repo: Repository<SaEventEntity>,
+  ) {}
+
+  // 최초 기동 시 데이터가 비어 있으면 1회 시드 크롤링 (부팅을 막지 않도록 백그라운드 실행)
+  onModuleInit(): void {
+    void this.seedIfEmpty();
+  }
+
+  private async seedIfEmpty(): Promise<void> {
+    try {
+      const count = await this.repo.count();
+      if (count > 0) return;
+      this.logger.log('이벤트 데이터가 없어 초기 크롤링을 수행합니다.');
+      await this.refresh();
+    } catch (error) {
+      this.logger.warn(`초기 이벤트 시드 실패: ${(error as Error).message}`);
+    }
+  }
+
+  // 매주 목요일 10:01 (KST) — 정기점검 종료 후 이벤트 갱신
+  @Cron('1 10 * * 4', { name: 'weekly-events-refresh', timeZone: 'Asia/Seoul' })
+  async handleWeeklyRefresh(): Promise<void> {
+    this.logger.log('주간 이벤트 갱신(목 10:01 KST) 시작');
+    await this.refresh();
+  }
+
+  /** 크롤링 → 성공·비어있지 않을 때만 DB 전체 교체. 실패/빈 결과 시 기존 데이터 유지. */
+  async refresh(): Promise<number> {
+    let events: OngoingEventDto[];
+    try {
+      events = await this.crawlAllPages();
+    } catch (error) {
+      this.logger.warn(
+        `이벤트 크롤링 실패(기존 데이터 유지): ${(error as Error).message}`,
+      );
+      return 0;
+    }
+    if (!events.length) {
+      this.logger.warn(
+        '크롤링 결과가 비어 있어 갱신을 건너뜁니다(기존 데이터 유지).',
+      );
+      return 0;
+    }
+
+    // 전체 교체 (트랜잭션) — 부분 갱신으로 인한 불일치 방지
+    await this.repo.manager.transaction(async (m) => {
+      await m.clear(SaEventEntity);
+      const rows = events.map((e, i) =>
+        m.create(SaEventEntity, {
+          title: e.title,
+          sub: e.sub,
+          image: e.image,
+          period: e.period,
+          link: e.link,
+          tag: e.tag,
+          sortOrder: i,
+        }),
+      );
+      await m.save(rows);
+    });
+    this.logger.log(`이벤트 ${events.length}건 갱신 완료`);
+    return events.length;
+  }
+
+  /** DB에서 진행중 이벤트 조회 (D-day는 조회 시점 기준 재계산). 크롤링하지 않음. */
+  async getOngoing(): Promise<OngoingEventDto[]> {
+    const rows = await this.repo.find({ order: { sortOrder: 'ASC' } });
+    return rows.map((r) => ({
+      title: r.title,
+      sub: r.sub,
+      image: r.image,
+      period: r.period,
+      link: r.link,
+      tag: r.tag,
+      dday: this.computeDday(r.period),
+    }));
+  }
+
+  /**
+   * 진행중 이벤트는 `?n4PageNo=N` 으로 페이지네이션된다.
+   * 빈 페이지(등록된 글 없음)거나 새 항목이 없을 때까지 순차 수집한다.
+   */
+  private async crawlAllPages(): Promise<OngoingEventDto[]> {
+    const all: OngoingEventDto[] = [];
+    const seen = new Set<string>();
+
+    for (let page = 1; page <= EventsService.MAX_PAGES; page++) {
+      const url = `${EventsService.SOURCE_URL}?n4PageNo=${page}`;
+      const html = await curlFetchHtml(url, { referer: EventsService.REFERER });
+      const pageEvents = this.parse(html);
+      if (!pageEvents.length) break; // 빈 페이지 → 마지막 도달
+
+      // 페이지 번호 클램핑(같은 페이지 반복) 대비: 신규 항목만 누적, 신규 없으면 종료
+      let added = 0;
+      for (const ev of pageEvents) {
+        const key = `${ev.title}|${ev.period}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        all.push(ev);
+        added++;
+      }
+      if (added === 0) break;
+    }
+
+    return all;
+  }
+
+  /** 이벤트 목록 페이지 HTML → DTO 배열 파싱 */
+  private parse(html: string): OngoingEventDto[] {
+    const $ = load(html);
+    const out: OngoingEventDto[] = [];
+
+    // 진행중 이벤트 영역: .boardEventList > ul > li
+    $('.boardEventList ul li').each((_, li) => {
+      const el = $(li);
+      const title = el.find('.data .subject').text().trim();
+      if (!title) return; // 광고/구분용 빈 항목 스킵
+
+      const sub = el.find('.data .txt').text().trim();
+      const image = el.find('.thumb img').attr('src')?.trim() ?? '';
+      const link = el.find('.data .subject a').attr('href')?.trim() ?? '';
+
+      // 기간: '<span>기간</span> 2026.06.11 ~ 2026.06.25' 형태에서 라벨 제거
+      let period = '';
+      el.find('.data .icon.info').each((__, info) => {
+        if ($(info).find('span').first().text().trim() === '기간') {
+          period = $(info).text().replace('기간', '').trim();
+        }
+      });
+
+      out.push({
+        title,
+        sub,
+        image,
+        period,
+        link: this.normalizeLink(link),
+        dday: this.computeDday(period),
+        tag: link.includes('/news/update/') ? '업데이트' : '이벤트',
+      });
+    });
+
+    return out;
+  }
+
+  /** http → https 정규화 (혼합 콘텐츠 방지) */
+  private normalizeLink(link: string): string {
+    return link.replace(/^http:\/\//i, 'https://');
+  }
+
+  /** 기간 문자열의 종료일로 D-day 계산 (예: 'D-14', 'D-DAY') */
+  private computeDday(period: string): string {
+    const end = period.split('~')[1]?.trim();
+    if (!end) return '';
+    const m = end.match(/(\d{4})[.-](\d{1,2})[.-](\d{1,2})/);
+    if (!m) return '';
+
+    const endDate = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const diffDays = Math.ceil(
+      (endDate.getTime() - today.getTime()) / 86_400_000,
+    );
+
+    if (diffDays < 0) return '종료';
+    if (diffDays === 0) return 'D-DAY';
+    return `D-${diffDays}`;
+  }
+}

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/curl-fetch.ts

@@ -0,0 +1,93 @@
+import { execFile } from 'node:child_process';
+
+// ────────────────────────────────────────────────────────────
+// curl 기반 HTML fetch 유틸
+// 넥슨 SA 사이트는 Node 의 TLS 지문(JA3)을 차단하므로(axios/native https → 403),
+// 시스템 curl 바이너리를 통해 요청한다. URL 은 호출부의 상수이며 사용자 입력이
+// 아니고, execFile(쉘 미경유)을 사용하므로 커맨드 인젝션 위험이 없다.
+// ※ 배포(Docker) 이미지에 curl 패키지가 설치되어 있어야 한다.
+// ────────────────────────────────────────────────────────────
+
+const DEFAULT_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+
+export interface CurlFetchOptions {
+  /** Referer 헤더 (안티봇 우회에 필요한 경우) */
+  referer?: string;
+  /** 타임아웃(초) — 기본 12초 */
+  timeoutSec?: number;
+  /** 최대 응답 버퍼(MB) — 기본 10MB */
+  maxBufferMb?: number;
+}
+
+/** curl 로 URL 을 GET 하여 본문(HTML/텍스트)을 문자열로 반환 */
+export function curlFetchHtml(
+  url: string,
+  opts: CurlFetchOptions = {},
+): Promise<string> {
+  const { referer, timeoutSec = 12, maxBufferMb = 10 } = opts;
+
+  // 넥슨 WAF 우회 핵심: 반드시 HTTP/2(--http2)로 요청하고, 브라우저(Chrome) 헤더를
+  // 함께 보낸다. 단 `--compressed`(Accept-Encoding: gzip,deflate,br,zstd)는 차단을
+  // 유발하므로 사용하지 않는다(서버는 압축 없이 평문 HTML 반환).
+  const args = [
+    '-sSL', // silent + 에러 표시 + 리다이렉트 추적
+    '--http2', // HTTP/2 강제 — 미적용 시 403
+    '--max-time',
+    String(timeoutSec),
+    '-A',
+    DEFAULT_UA,
+    '-H',
+    'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+    '-H',
+    'Accept-Language: ko-KR,ko;q=0.9',
+    '-H',
+    'sec-ch-ua: "Chromium";v="126", "Not.A/Brand";v="24"',
+    '-H',
+    'sec-ch-ua-mobile: ?0',
+    '-H',
+    'sec-ch-ua-platform: "Windows"',
+    '-H',
+    'Sec-Fetch-Dest: document',
+    '-H',
+    'Sec-Fetch-Mode: navigate',
+    '-H',
+    'Sec-Fetch-Site: none',
+    '-H',
+    'Sec-Fetch-User: ?1',
+    '-H',
+    'Upgrade-Insecure-Requests: 1',
+  ];
+  if (referer) {
+    args.push('-H', `Referer: ${referer}`);
+  }
+  args.push(url);
+
+  return new Promise<string>((resolve, reject) => {
+    execFile(
+      'curl',
+      args,
+      {
+        maxBuffer: maxBufferMb * 1024 * 1024,
+        windowsHide: true,
+        encoding: 'utf8',
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          reject(
+            new Error(
+              `curl 요청 실패: ${stderr?.toString().trim() || err.message}`,
+            ),
+          );
+          return;
+        }
+        const body = stdout?.toString() ?? '';
+        if (!body) {
+          reject(new Error('curl 응답 본문이 비어 있습니다.'));
+          return;
+        }
+        resolve(body);
+      },
+    );
+  });
+}

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}`;
+}