Initial commit

2026-10-28 15:30:05 +09:00
commit 696e34f403
269 changed files with 33654 additions and 0 deletions
@@ -0,0 +1,57 @@
+# 로깅 규칙
+
+`console.log` 사용 금지. 백엔드는 winston(`shared/logger/winston.config.ts`), Nest 내부는 `Logger` 를 쓴다.
+
+## 레벨 기준
+
+| 레벨 | 쓰는 상황 | 예 |
+| --- | --- | --- |
+| `error` | 서버 책임 오류(5xx), 즉시 조치가 필요한 실패 | 미정의 예외, DB 커넥션 실패 |
+| `warn` | 사용자 책임 실패(4xx), 예상된 비정상 | 검증 실패, 권한 없음, Rate Limit 초과 |
+| `log`(info) | 상태 변화가 있는 주요 이벤트 | 서버 기동, 가입 완료, 결제 승인 |
+| `debug` | 개발 환경 진단 | 외부 API 요청/응답 요약 |
+
+- 4xx 를 `error` 로 남기지 않는다 — 알림 피로도가 올라가 진짜 장애를 놓친다.
+- 반복되는 정상 흐름(헬스체크, 폴링)은 로그를 남기지 않는다.
+
+## 필수 포함 정보
+
+모든 에러 로그에는 **에러 코드**와 **추적 ID**를 함께 남긴다.
+
+```
+[RES_001][3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d] GET /api/users/1 {"userId":1}
+```
+
+- 추적 ID는 `RequestIdMiddleware` 가 발급하는 `x-request-id` 이며, 실패 응답의 `error.traceId` 와 같은 값이다.
+- 사용자 문의가 들어오면 이 값으로 로그를 검색한다 ([[error-codes]]).
+- 개발자용 컨텍스트는 `BusinessException` 의 `context` 에 담는다 — 로그에만 남고 응답에는 포함되지 않는다.
+
+## 민감정보 마스킹 (필수)
+
+아래 값은 **어떤 레벨에서도 원문 그대로 남기지 않는다.**
+
+- 비밀번호, 토큰(JWT·리프레시·API 키), 쿠키, `Authorization` 헤더
+- 주민등록번호·카드번호·계좌번호 등 개인 식별/금융 정보
+- 요청 본문 전체 덤프 (`JSON.stringify(req.body)` 금지 — 필요한 필드만 선택해 남긴다)
+
+```typescript
+// ❌ 금지
+this.logger.log(`로그인 시도: ${JSON.stringify(dto)}`);
+
+// ✅ 필요한 식별자만
+this.logger.log(`로그인 시도: email=${maskEmail(dto.email)}`);
+```
+
+- 마스킹 유틸은 순수 함수로 `shared/utils/` 에 둔다 ([[coding-common]]).
+
+## 클라이언트 로깅
+
+- 프론트/앱에서 사용자 정보를 콘솔에 출력하지 않는다. 운영 빌드에는 디버그 로그를 남기지 않는다.
+- 사용자 노출 문구는 로그가 아니라 에러 사전에서 온다 ([[error-codes]]).
+
+## 운영 확장
+
+- 운영 환경은 JSON 포맷 + 외부 수집기(Loki/ELK/CloudWatch) 연동을 권장한다.
+- 파일로 남길 경우 로테이션(`winston-daily-rotate-file`)을 적용하고 보존 기간을 정한다.
+
+> 보안 규칙은 [[security]], 테스트 규칙은 [[testing]] 참조.