fix: 템플릿 점검 결과 반영 — Node 24·이미지 위생·운영 노출 최소화

템플릿 점검에서 나온 항목을 한 번에 반영한다. 항목별 이유:

- Node 20 → 24 LTS (Dockerfile·CI): Node 20 은 2026-04-30 에 지원이 끝나 보안 패치가 없다
- backend·frontend .dockerignore 추가: `COPY . .` 가 호스트 node_modules(Windows 바이너리)·dist·
  .env*(시크릿)를 이미지에 넣고 있었다
- 업로드 디렉터리 쓰기 검사(fail-fast): Linux 에서 Docker 가 root 소유로 만든 바인드 마운트에
  비-root 앱이 쓰지 못해 첫 업로드에서야 SYS_001 로 터졌다. 기동 시 해결 명령을 안내한다
- DB 커넥션 풀 100 → 10 (DB_POOL_MAX): PostgreSQL 기본 max_connections(100)를 앱 하나가 다 잡았다
- Swagger 운영 기본 비활성 (SWAGGER_ENABLED): API 구조 전체가 공개 도메인에 노출됐다
- 헬스체크 운영 응답에서 오류 상세 제거: 드라이버 오류 문구에 내부 주소·DB 계정명이 담긴다.
  원인은 error 로그로 남긴다
- nginx: location 의 add_header 때문에 정적 자원에서 보안 헤더가 빠지던 문제와,
  index.html 이 캐시돼 배포 직후 빈 화면이 날 수 있던 문제를 고친다
- vite allowedHosts: true 제거 (DEV_ALLOWED_HOSTS): DNS rebinding 보호가 꺼져 있었다
- 전역 설정을 configureApp() 으로 분리해 main.ts 와 e2e 가 공유: e2e 가 설정을 복사해 재현해
  실제 설정과 어긋나도 통과할 수 있었다. PORT 도 빈 값을 방어하는 파서를 거친다
- 쓰이지 않던 WEBSOCKET_PORT 제거: 별도 포트는 같은 도메인 라우팅과 맞지 않는다
- 예제 useUser 가 메시지 대신 에러 코드를 보관하도록 수정, testing.md 표 깨짐 수정,
  settings.json 허용 목록에서 npm install 제거 (Windows lock 파일 규칙과 충돌)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

backend/src/main.ts

@@ -1,92 +1,52 @@
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
-import { Logger, RequestMethod, ValidationPipe } from '@nestjs/common';
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { Logger } from '@nestjs/common';
 import { WinstonModule } from 'nest-winston';
-import helmet from 'helmet';
-import type {
-  Express,
-  Request as ExpressRequest,
-  Response as ExpressResponse,
-} from 'express';
 
-import { Reflector } from '@nestjs/core';
-
-import { HttpExceptionFilter } from '@/common/filters/http-exception.filter';
-import { TransformInterceptor } from '@/common/interceptors/transform.interceptor';
-import { buildCorsOptions } from '@/shared/config/cors.config';
+import { configureApp, GLOBAL_PREFIX } from '@/app.setup';
+import {
+  isSwaggerEnabled,
+  setupSwagger,
+  SWAGGER_PATH,
+} from '@/shared/config/swagger.config';
 import { winstonConfig } from '@/shared/logger/winston.config';
+import { parsePositiveInt } from '@/shared/utils/env';
+
+/** 루트 .env 에 BACKEND_PORT 가 없을 때만 쓰는 기본 포트 */
+const DEFAULT_PORT = 3000;
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule, {
     logger: WinstonModule.createLogger(winstonConfig),
   });
 
-  // 리버스 프록시 뒤에서 실제 클라이언트 IP 를 식별한다 (rate limit 이 IP 기준이다).
-  // 운영은 Nginx Proxy Manager → backend 로 한 번 거친다 (Custom location 이 X-Forwarded-For 에 클라이언트 IP 를 싣는다).
-  const expressApp = app.getHttpAdapter().getInstance() as Express;
-  expressApp.set('trust proxy', 1);
+  // 보안 헤더·CORS·prefix·검증 파이프·응답 래퍼 등 전역 설정 — e2e 테스트와 같은 함수를 쓴다 (app.setup.ts)
+  configureApp(app);
 
-  // 글로벌 prefix — 모든 라우트가 /api/* 로 정규화됨 (Flutter, Web 양쪽 baseURL과 일치)
-  // 리버스 프록시(운영 NPM · 개발 vite)는 /api 로 시작하는 요청을 경로 그대로 넘기므로 이 prefix 와 맞물려 있다.
-  app.setGlobalPrefix('api', {
-    // 헬스체크 / 루트 상태 엔드포인트는 prefix 미적용
-    exclude: [{ path: '/', method: RequestMethod.GET }],
-  });
+  // Swagger API 문서 — 운영에서는 기본으로 끈다 (shared/config/swagger.config.ts)
+  const swaggerEnabled = isSwaggerEnabled();
+  if (swaggerEnabled) setupSwagger(app);
 
-  // 기본 주소('/') 접속 시 상태 확인용 텍스트 응답 추가
-  expressApp.get('/', (_req: ExpressRequest, res: ExpressResponse) => {
-    res.send('Backend API Server is running 정상 구동 중입니다.');
-  });
-
-  // 1. 보안 헤더 (Helmet) - XSS 방지 및 기본 웹 보안
-  app.use(helmet());
-
-  // 2. CORS — 기본 구성은 프론트와 API 가 같은 도메인이라(브라우저는 /api 상대경로로 호출) 필요 없다.
-  //    다른 오리진에서 호출해야 할 때만 루트 .env 의 CORS_ORIGIN 에 콤마로 나열한다 (shared/config/cors.config.ts)
-  app.enableCors(buildCorsOptions());
-
-  // 3. Rate Limiting 은 AppModule 의 ThrottlerGuard(APP_GUARD)로 일원화되어 있다.
-  //    라우트 단위 제어(@Throttle / @SkipThrottle)가 가능하고, 한도 초과는 REQ_001(429)로 응답된다.
-  //    (전역 예외 필터가 429 → REQ_001 로 매핑한다 — .claude/rules/error-codes.md)
-
-  // 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(app.get(Reflector)));
-
-  // 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);
-
-  // 7. Graceful shutdown — SIGTERM 수신 시 새 요청을 받지 않고
-  //    처리 중인 요청을 마친 뒤 DB/Redis 커넥션을 정리하고 종료한다.
-  //    (이 설정이 없으면 배포·재시작 때 처리 중이던 요청이 그대로 끊긴다)
+  // Graceful shutdown — SIGTERM 수신 시 새 요청을 받지 않고
+  // 처리 중인 요청을 마친 뒤 DB/Redis 커넥션을 정리하고 종료한다.
+  // (이 설정이 없으면 배포·재시작 때 처리 중이던 요청이 그대로 끊긴다)
   app.enableShutdownHooks();
 
-  //    종료 로그는 ShutdownLogger(OnApplicationShutdown)가 남긴다.
+  // 종료 로그는 ShutdownLogger(OnApplicationShutdown)가 남긴다.
 
-  const port = Number(process.env.PORT ?? 3000);
+  // compose 가 미정의 변수를 빈 문자열로 주입하므로 parsePositiveInt 로 방어한다 (Number('') 는 0 → 임의 포트)
+  const port = parsePositiveInt(process.env.PORT, DEFAULT_PORT);
   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`,
+    `🚀 Backend running on http://localhost:${port}/${GLOBAL_PREFIX}`,
     'Bootstrap',
   );
+  if (swaggerEnabled) {
+    Logger.log(
+      `📘 Swagger docs at  http://localhost:${port}/${SWAGGER_PATH}`,
+      'Bootstrap',
+    );
+  }
 }
 
 void bootstrap();