Initial commit

.claude/rules/api-design.md

@@ -0,0 +1,64 @@
+# API 설계 규약
+
+세 클라이언트가 공유하는 계약이므로, 아래 규약은 백엔드 단독으로 바꾸지 않는다.
+
+## 경로 · 메서드
+
+- 모든 라우트는 글로벌 prefix `/api` 아래에 놓인다 (`main.ts`). 클라이언트 baseURL 도 `/api` 를 포함한다.
+- 리소스는 **복수형 명사**, 소문자 kebab-case: `/users`, `/order-items`
+- 동사를 경로에 넣지 않는다. 상태 변경이 필요하면 하위 리소스로 표현한다.
+  - ❌ `POST /users/1/doDeactivate`
+  - ✅ `POST /users/1/deactivation`
+
+| 메서드 | 용도 | 성공 상태 |
+| --- | --- | --- |
+| GET | 조회 (부수효과 없음) | 200 |
+| POST | 생성 · 비멱등 작업 | 201 (생성) / 200 |
+| PATCH | 부분 수정 | 200 |
+| PUT | 전체 교체 | 200 |
+| DELETE | 삭제 | 204 (`@SkipTransform()`) 또는 200 |
+
+## 쿼리 파라미터
+
+| 용도 | 파라미터 | 비고 |
+| --- | --- | --- |
+| 커서 페이지네이션 | `cursor`, `limit` | 기본 20 / 최대 100 ([[response-format]]) |
+| 오프셋 페이지네이션 | `page`, `limit` | 전체 페이지 수가 UI 에 필요할 때만 |
+| 정렬 | `sort=createdAt:desc` | `필드:방향`, 콤마로 다중 지정 |
+| 검색 | `q` | 자유 텍스트 검색 |
+| 필터 | 필드명 그대로 (`status=active`) | 화이트리스트 DTO 로만 수용 |
+
+- 모든 쿼리는 DTO(`class-validator`)로 검증한다. `forbidNonWhitelisted` 때문에 미정의 파라미터는 400(VAL_001)이 된다.
+
+## 데이터 표현
+
+- **날짜/시각**: ISO 8601 UTC 문자열 (`2026-09-16T13:22:16.000Z`). 타임존 변환은 클라이언트 책임.
+- **ID**: 노출용 식별자는 문자열로 직렬화해도 되지만 타입을 도메인 내에서 일관되게 유지한다.
+- **금액**: 소수 오차를 피해 최소 단위 정수(원 단위)로 주고받는다.
+- **불리언 필드**: `is`/`has` 접두어 (`isActive`, `hasNext`).
+- **필드명**: JSON 은 camelCase. DB 컬럼명이 snake_case 여도 응답에서 변환한다.
+- `null` 과 필드 생략을 혼용하지 않는다 — "값 없음"은 `null` 로 통일한다.
+
+## 버전 관리
+
+- 호환성을 깨는 변경(필드 삭제, 타입 변경, 의미 변경)이 필요하면 경로 버전을 올린다: `/api/v2/users`
+- 필드 **추가**는 호환 변경이므로 버전을 올리지 않는다. 클라이언트는 모르는 필드를 무시해야 한다.
+- 제거 예정 필드는 먼저 문서에 `deprecated` 로 표시하고, 클라이언트 전환 후 삭제한다.
+
+## 문서화 (Swagger)
+
+- 모든 컨트롤러에 `@ApiTags()`, 모든 엔드포인트에 `@ApiOperation()`.
+- 성공 응답은 `@ApiStandardResponse()`, 실패 응답은 `@ApiErrorResponse('CODE')` 로 문서화한다
+  — 래퍼 구조와 에러 레지스트리가 자동 반영되어 문서와 구현이 어긋나지 않는다 ([[response-format]]).
+- 모든 DTO 필드에 `@ApiProperty()` + 한국어 `description`.
+
+## 신규 엔드포인트 체크
+
+- [ ] 경로가 복수형 리소스 + 동사 없음
+- [ ] 입력은 DTO 검증, 출력은 응답 DTO 정의
+- [ ] 목록이면 페이지네이션 적용
+- [ ] 실패 경로마다 에러 코드 지정 ([[error-codes]])
+- [ ] Swagger 데코레이터 작성
+- [ ] 세 클라이언트 중 사용하는 쪽의 타입/모델 갱신
+
+> 응답 구조는 [[response-format]], 에러는 [[error-codes]], 구현 규칙은 [[nestjs]] 참조.

.claude/rules/checklist.md

@@ -0,0 +1,86 @@
+# 작업 점검 & 신규 프로젝트 셋업
+
+> 이 저장소는 **재사용 템플릿**이다. 클론해 어떤 프로젝트든 시작할 수 있도록, 여기에는 **언제나 유효한 공용 규칙**만 둔다(특정 시점의 구현 상태는 두지 않는다).
+> 각 스택이 기본 제공하는 골격과 확장 규칙은 [[nestjs]] · [[vue3]] · [[flutter]] · [[docker]] 스킬 참조.
+
+---
+
+## 1. 신규 프로젝트 셋업 (클론 직후 1회)
+
+- [ ] 루트 `.env.{env}.example` → `.env.{env}` 복사 후 **placeholder 값 교체** (`change-me-*` 가 남아 있으면 안 된다, [[env-structure]])
+      운영은 `BACKEND_API_URL`·`CORS_ORIGIN` 을 **실제 도메인**으로 — `localhost`/`example.com` 이 남으면 기동 실패한다
+- [ ] `backend/.env.{env}.example` → `backend/.env.{env}` 복사 후 `JWT_SECRET` 등 고유 시크릿 작성 (compose `env_file` 로 로드 — 파일이 없으면 기동 실패)
+- [ ] `flutter/.env.example` → `flutter/.env` 복사 후 `API_URL` 확인 (Android 에뮬레이터: `10.0.2.2`)
+      — **이 파일이 없으면 `flutter analyze` 가 asset 경고를 낸다**
+- [ ] 프로젝트 식별 값 교체 (`PROJECT_NAME` 등 루트 env 키)
+- [ ] 의존성 설치: `cd backend && npm ci`, `cd frontend && npm ci`, `cd flutter && flutter pub get`
+- [ ] Docker 개발 환경 기동으로 동작 확인 — backend + db ([[docker]])
+      (Redis 와 프론트엔드 컨테이너는 기본 비활성이다 — 필요하면 루트 `.env` 에 `COMPOSE_PROFILES=redis,frontend`)
+- [ ] 프론트엔드 dev 서버는 **호스트에서** 기동 — `cd frontend && npm run dev` (→ <http://localhost:5173>)
+      컨테이너 vite 는 바인드 마운트 때문에 첫 서빙까지 수 분이 걸려 profile 뒤로 숨겨 두었다 ([[docker]])
+
+## 2. 커밋 전 공통 점검 (매 작업)
+
+> 아래 항목은 `.github/workflows/ci.yml` 이 PR 마다 자동 검사한다. 로컬에서 먼저 통과시키면 CI 도 통과한다.
+
+- [ ] 주석은 한국어, 매직 넘버·하드코딩 문자열 없음 ([[coding-common]])
+- [ ] 린트/분석 통과 — backend `npm run lint`, frontend `npm run lint && npm run type-check`, flutter `flutter analyze`
+      (lint 스크립트에 `--max-warnings 0` 이 걸려 있어 **Warning 하나만 있어도 실패**한다. 자동 수정은 `npm run lint:fix`)
+- [ ] 변경 영역 테스트 통과 — backend `npm run test`, frontend `npm run test:unit`, flutter `flutter test` ([[testing]])
+- [ ] 절대경로 alias 사용 (TS `@/`, Dart `package:`), 깊은 상대경로 없음
+- [ ] 민감정보(`.env`, 시크릿) 미커밋 — `*.example` 만 추적하며 그 값은 placeholder ([[security]])
+- [ ] 로그에 비밀번호·토큰·요청 본문 전체가 남지 않음 ([[logging]])
+- [ ] 커밋 메시지 `<type>(<scope>): <한국어 제목>` 형식, 한 커밋 한 변경 ([[git-convention]])
+- [ ] **의존성을 바꿨다면** lock 파일이 Linux 빌드와 호환되는지 확인 — Windows 에서 `npm install` 하면
+      Linux 전용 optional 의존성이 lock 에서 잘려 Docker 의 `npm ci` 가 실패한다. 컨테이너 안에서 설치할 것 ([[nestjs]])
+- [ ] **의존성을 바꿨다면** dev 컨테이너를 `--renew-anon-volumes` 로 재생성 — `--build` 만으로는
+      `node_modules` 익명 볼륨이 갱신되지 않아 새 패키지가 컨테이너에 반영되지 않는다 ([[docker]])
+
+## 3. 에러 코드 변경 시 (SSOT 절차)
+
+에러 코드/메시지는 **백엔드 레지스트리 한 파일**만 고친다. 세 파일을 손으로 맞추지 않는다.
+
+- [ ] `backend/src/common/errors/error-codes.ts` 수정 (코드는 `DOMAIN_NNN`, 번호 재사용 금지)
+- [ ] `cd backend && npm run sync:error-codes` 실행 → 클라이언트 사전 자동 생성
+      (`frontend/src/shared/constants/error-codes.generated.ts`, `flutter/lib/core/api/error_lexicon.g.dart` — **직접 수정 금지**)
+- [ ] 세 스택 테스트 통과 확인 (`error-codes.spec.ts` · `useApi.spec.ts` · `error_lexicon_test.dart`)
+      — 계약 테스트는 **클라이언트가 실제로 참조하는 코드의 존재**와 네이밍 규약만 검사한다.
+      도메인 코드를 추가했다고 테스트를 고칠 필요는 없다.
+      단, 클라이언트가 그 코드로 분기한다면 해당 목록에 추가한다.
+- [ ] 생성 파일까지 함께 커밋
+      (CI 의 `error-codes-sync` 잡이 `sync` 재실행 후 `git diff` 로 드리프트를 검사하므로, 빠뜨리면 PR 이 실패한다)
+
+> `AUTH_002`(세션 만료)는 **클라이언트 전용** 코드로 서버 응답에는 나타나지 않는다. 자세한 내용은 [[error-codes]].
+
+## 4. 엔티티(DB 스키마)를 바꿀 때
+
+- [ ] 마이그레이션 생성 — `dc exec backend npm run migration:generate -- src/migrations/<이름>` ([[nestjs]])
+- [ ] 생성된 SQL 검토 — 의도치 않은 `DROP` 이 없는지 **반드시 눈으로 확인**
+- [ ] 적용 확인 — `migration:run` 후 의도한 스키마가 되었는지
+- [ ] 엔티티와 마이그레이션 파일을 **함께 커밋** (하나만 올라가면 배포 시 깨진다)
+- [ ] `DB_SYNCHRONIZE=true` 로 실험했다면 **끄고** 마이그레이션을 생성했는지 확인
+
+## 5. 공유 계약을 바꿀 때 (응답 포맷 · 페이지네이션 · API 규약)
+
+- [ ] 백엔드 구현 수정 ([[response-format]] · [[api-design]])
+- [ ] 세 클라이언트의 인터셉터/타입 동기화 (`useApi.ts` · `dio_client.dart` · 공유 타입 파일)
+- [ ] Swagger 데코레이터(`ApiStandardResponse` / `ApiErrorResponse`) 갱신 — 문서와 실응답 불일치 방지
+- [ ] PR 본문에 영향 범위 명시 ([[git-convention]])
+
+---
+
+## 6. 기능 확장 시 따르는 순서
+
+새 기능은 만들기 전에, 해당 스킬의 **"템플릿 기본 제공 골격"** 에서 재사용할 패턴을 먼저 찾는다(같은 역할을 새로 만들지 말 것).
+
+1. 해당 디렉터리 스킬 규칙 확인 ([[nestjs]] / [[vue3]] / [[flutter]])
+2. 기본 제공 골격(인터셉터·필터·에러 레지스트리·dio client·예제 모듈)에서 패턴 재사용
+3. 표준 응답/에러 흐름 준수 ([[response-format]] · [[error-codes]] · [[api-design]])
+4. 실패 경로마다 에러 코드 지정 — `BusinessException('CODE')` 로 던진다
+5. env 신규 값은 루트 `.env` 부터 ([[env-structure]])
+6. 커밋 전 위 2·3·4절 점검 통과
+
+> 대표 확장 지점(각 스킬의 "확장 시 따르는 규칙" 참조):
+> - 인증/권한 → [[nestjs]](guards·JWT) · [[vue3]](auth store + 라우터 가드)
+> - 데이터 영속화 → [[nestjs]](TypeORM 엔티티/리포지토리 · 마이그레이션)
+> - 상태·화면 계층 → [[flutter]](Riverpod 프로바이더 · features 구조)

.claude/rules/coding-common.md

@@ -0,0 +1,35 @@
+---
+name: coding-common
+description: 세 클라이언트(backend/frontend/flutter) 공통 코딩 규칙 — 주석 언어, 타입 정책, 린트, 순수 유틸 분리, 절대경로 alias.
+---
+
+# 공통 코딩 규칙
+
+- 모든 코드 주석은 **한국어**로 작성
+- 웹(`frontend`)·서버(`backend`)는 100% TypeScript, 모바일(`flutter`)은 Dart Sound Null Safety 준수
+- 컴파일러/린터 **Warning 방치 금지** — 커밋 전 각 프로젝트 `lint` / `analyze` 통과
+  (lint 스크립트에 `--max-warnings 0` 이 걸려 있다. 자동 수정은 `npm run lint:fix`)
+- 아래 규칙은 **린트로 강제**되므로 위반 시 빌드가 실패한다:
+  `any`/`dynamic` 사용, `console`/`print` 출력, Vue 인라인 스타일·Options API,
+  Dart `const` 누락·await 누락, backend 에서 `HttpException` 직접 생성(→ `BusinessException` 사용)
+- 유틸 함수는 순수 함수로 분리 — TS는 `shared/utils/`, Dart는 `core/utils/`
+- 매직 넘버·하드코딩 문자열 지양 → 상수 또는 환경변수로 분리
+  (반복 사용되는 키 문자열도 상수로: 예 `kJwtTokenKey`, `REQUEST_ID_HEADER`)
+- 절대경로 alias 사용 (TS `@/`, Dart `package:`), 깊은 상대경로(`../../`) 지양
+  — backend/frontend 모두 `@/` → `src/` 로 설정되어 있다 (backend 는 `tsconfig.json` paths + jest `moduleNameMapper`)
+- **자동 생성 파일은 직접 수정하지 않는다** — `*.generated.ts`, `*.g.dart` 는 생성 스크립트를 통해서만 바꾼다 ([[error-codes]])
+
+## 네이밍 규약
+
+| 대상 | 규칙 | 예 |
+| --- | --- | --- |
+| TS 파일(일반) | kebab-case | `user.store.ts`, `use-api.ts` / 기존 composable 은 `useApi.ts` 형태 유지 |
+| Vue 컴포넌트 파일 | PascalCase | `BaseButton.vue`, `UserCard.vue` |
+| Dart 파일·디렉터리 | snake_case | `dio_client.dart`, `user_repository.dart` |
+| 클래스/타입 | PascalCase | `UserModel`, `TransformInterceptor` |
+| 변수/함수 | camelCase (Dart 포함) | `getUser`, `isLoggedIn` |
+| 상수 | TS `UPPER_SNAKE` 또는 모듈 상수, Dart `lowerCamel` | `MAX_RETRY`, `defaultTimeout` |
+| 에러 코드 | `DOMAIN_NNN` | `AUTH_001`, `VAL_001` ([[error-codes]]) |
+| 자동 생성 파일 | TS `*.generated.ts`, Dart `*.g.dart` | `error-codes.generated.ts`, `error_lexicon.g.dart` |
+
+> 도메인별 세부 규칙: [[nestjs]] · [[vue3]] · [[flutter]] · 테스트: [[testing]] · 로깅: [[logging]] · API 설계: [[api-design]]

.claude/rules/env-structure.md

@@ -0,0 +1,50 @@
+---
+name: env-structure
+description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{APP_ENV} 가 모든 설정의 SSOT, docker-compose 가 서비스에 주입. 새 설정값 추가/서비스 env 작성 규칙.
+---
+
+# 환경변수 구조 (단일 진실 공급원: 루트 `.env`)
+
+이 템플릿은 **루트 `.env.{APP_ENV}` 가 모든 설정의 단일 진실 공급원(SSOT)** 이다.
+값을 한 곳에서만 관리하기 위해, 서비스(backend/frontend)는 자체 env에 값을 중복 작성하지 않고 **루트 → docker-compose 가 주입한 값을 그대로 사용**한다.
+
+```
+루트 .env.{APP_ENV}
+   │  (docker compose --env-file 로 로드)
+   ├─▶ backend   : env_file + environment 로 DB/Redis/CORS/포트 주입
+   │               (backend/.env.{APP_ENV} 는 "존재"만 하면 됨, 내용 최소)
+   ├─▶ frontend  : BACKEND_API_URL → build arg(VITE_API_BASE_URL) 로 주입
+   │               (호스트에서 `npm run dev` 로 띄울 때는 compose 를 거치지 않으므로
+   │                vite.config.ts 가 이 파일을 `loadEnv` 로 직접 읽어 FRONTEND_PORT/BACKEND_PORT 사용)
+   ├─▶ db        : DB_USER/DB_PASSWORD/DB_NAME, DB_DATA_DIR 볼륨
+   └─▶ redis     : REDIS_PASSWORD, REDIS_DATA_DIR 볼륨
+```
+
+규칙:
+
+- **새 설정값은 루트 `.env.{APP_ENV}` 에 먼저 추가**하고, 필요한 서비스에 `docker-compose.yml` 의 `environment` / `args` 로 전달한다.
+- 서비스 자체 env 파일에는 **루트에서 내려주지 않는 고유 값만** 작성한다. (예: 백엔드 `JWT_SECRET`)
+- **compose 는 정의되지 않은 변수를 빈 문자열로 주입한다.** 코드에서 `??` 기본값만 쓰면 `Number('')===0` 같은 함정에 빠진다 —
+  숫자 설정값은 `shared/utils/env.ts` 의 `parsePositiveInt()` 처럼 빈 문자열까지 방어하는 파서를 거친다.
+  (기존 `.env` 를 쓰는 사람이 새 키를 추가하지 않아도 안전해야 한다)
+- `docker-compose.yml` 의 `env_file` 지시자 때문에 `backend/.env.{APP_ENV}` 파일은 비어 있어도 **존재해야 한다.**
+- **프론트엔드 dev 서버는 compose 를 거치지 않는다** — 호스트에서 직접 띄우므로([[docker]])
+  `vite.config.ts` 가 루트 `.env.{mode}` 를 `loadEnv` 로 읽어 포트·프록시 대상을 정한다.
+  포트를 `frontend/.env` 나 `vite.config.ts` 에 중복 작성하지 말 것 — 루트가 SSOT 다.
+  (읽은 값은 dev 서버 설정에만 쓰고 클라이언트 번들에는 넣지 않는다 — `VITE_` 없는 값의 번들 노출 금지, [[security]])
+- **Flutter 는 예외** — docker-compose 대상이 아니므로 `flutter/.env` 에서 `API_URL` 을 독립적으로 관리한다.
+- 모든 env 파일은 커밋 금지, `*.example` 만 커밋한다. (`.gitignore` 의 `!*.example` 재포함 규칙)
+- **설정이 잘못되면 서버가 뜨지 않아야 한다(fail-fast).** 조용히 기본값으로 굴러가다 운영에서 터지는 것이 더 위험하다.
+  검증은 `backend/src/shared/config/env.validation.ts` 가 담당하며 `ConfigModule.forRoot({ validate })` 에 연결되어 있다.
+  - 숫자 항목은 형식 검사 (모든 환경)
+  - 운영 환경: `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` 필수
+  - 운영 환경: `change-me`·`password` 같은 **예시 값이 그대로 배포되는 것을 차단**
+  - 운영 환경: `CORS_ORIGIN`·`BACKEND_API_URL` 에 **로컬 주소(`localhost`·`127.0.0.1` 등)나
+    예시 도메인(`example.com`)이 남아 있으면 차단** — 기동은 되는데 브라우저만 조용히 실패하는 조합을 막는다.
+    로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓸 때만 `ALLOW_LOCALHOST_URL=true` 로 건너뛴다
+    (`BACKEND_API_URL` 은 앱이 쓰지 않지만 이 검사를 위해 compose 가 backend 에 주입한다)
+  - 문제는 하나씩이 아니라 **한 번에 모아서** 보여준다 (재기동 반복 방지)
+  - 새 필수 설정을 추가하면 이 파일의 목록과 테스트도 함께 갱신한다
+
+> 루트 env의 대표 키: `PROJECT_NAME`, `APP_ENV`, `BUILD_MODE`, 각종 `*_PORT`, `BACKEND_API_URL`, `CORS_ORIGIN`, `DB_*`/`DB_DATA_DIR`, `REDIS_*`/`REDIS_DATA_DIR`, `THROTTLE_TTL_MS`/`THROTTLE_LIMIT`. 실제 목록은 `.env.development.example` 참조.
+> 실행/배포 명령은 [[docker]], 보안 규칙은 [[security]] 참조.

.claude/rules/error-codes.md

@@ -0,0 +1,115 @@
+# 에러 코드 규칙
+
+## 핵심 원칙
+
+> **사용자에게 노출되는 모든 실패는 반드시 에러 코드를 가진다.**
+> 코드 없이 문자열 메시지만 던지는 실패는 허용하지 않는다.
+
+- 사용자 노출 문구는 **에러 코드 사전에만 존재**한다. 컨트롤러·서비스·컴포넌트에 문구를 하드코딩하지 않는다.
+- 클라이언트는 `message` 가 아니라 **`code` 로 분기**한다. (문구는 언제든 바뀔 수 있다)
+- 서버 내부 정보(스택, 쿼리, 호스트명)는 절대 응답에 싣지 않는다 — 로그로만 남긴다 ([[logging]]).
+
+## SSOT — 레지스트리 한 곳
+
+에러 코드 ↔ 메시지 ↔ HTTP 상태는 **백엔드 레지스트리 한 파일**이 단일 진실 공급원이다.
+
+```
+backend/src/common/errors/error-codes.ts   ← 여기만 수정한다
+        │  npm run sync:error-codes
+        ├─▶ frontend/src/shared/constants/error-codes.generated.ts   (자동 생성)
+        └─▶ flutter/lib/core/api/error_lexicon.g.dart                (자동 생성)
+```
+
+- **생성 파일은 직접 수정 금지.** 레지스트리를 고치고 `cd backend && npm run sync:error-codes` 를 실행한다.
+- 코드 추가/변경 후에는 세 스택의 코드 목록 일치 테스트가 통과해야 한다
+  (backend `error-codes.spec.ts` · frontend `useApi.spec.ts` · flutter `error_lexicon_test.dart`).
+  목록을 바꿨다면 이 테스트의 기대 배열도 함께 갱신한다.
+
+## 공통 코드
+
+| 코드 | HTTP | 상황 | 메시지 |
+| --- | --- | --- | --- |
+| SYS_001 | 500 | 미정의 예외·네트워크 장애 (최종 폴백) | "일시적인 시스템 오류가 발생했습니다. 잠시 후 다시 시도해 주세요." |
+| REQ_001 | 429 | Rate Limit 초과 | "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요." |
+| AUTH_001 | 401 | 미인증 상태로 보호 자원 접근 | "로그인이 필요한 서비스입니다. 로그인 후 이용해 주세요." |
+| AUTH_002 | — | **클라이언트 전용** · 세션 만료 | "안전을 위해 로그아웃 되었습니다. 다시 로그인해 주세요." |
+| AUTH_003 | 403 | 권한 부족 | "해당 메뉴나 기능에 접근할 수 있는 권한이 없습니다." |
+| VAL_001 | 400 / 422 | 입력 검증 실패 | "입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)" |
+| RES_001 | 404 | 리소스 없음 | "요청하신 정보나 페이지를 찾을 수 없습니다." |
+| BIZ_001 | 400 | 그 외 비즈니스 규칙 위반 | "요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요." |
+
+### AUTH_002 (클라이언트 전용)
+
+서버는 이 코드를 **절대 내려주지 않는다.** 클라이언트가 다음 조건에서 스스로 생성한다.
+
+- **인증된 세션이 있는 상태**에서 401 응답을 받았을 때 → `AUTH_001` 을 `AUTH_002` 로 승격하고 세션을 정리한다.
+- 웹: `useApi.ts` 의 `toAuthCode()` (`authStore.clearAuth()` 호출)
+- 앱: `dio_client.dart` 의 `_toApiException()` (`jwt_token` 삭제)
+
+## 도메인 코드 추가
+
+1. `error-codes.ts` 의 `DOMAIN_ERROR_CODES` 에 `DOMAIN_NNN` 형식으로 등록한다.
+   ```typescript
+   USER_001: {
+     status: HttpStatus.CONFLICT,
+     message: '이미 가입된 이메일입니다. 다른 이메일을 사용해 주세요.',
+   },
+   ```
+2. `npm run sync:error-codes` 실행 → 클라이언트 사전 자동 갱신.
+3. 세 스택의 코드 목록 테스트에 새 코드를 추가한다.
+
+규칙:
+
+- 번호는 **001 부터 순차 부여**하고, 한번 배포된 코드의 **의미는 바꾸지 않는다** (폐기 시 주석으로 `deprecated` 표시, 번호 재사용 금지).
+- 도메인 접두어는 대문자 스네이크 (`USER`, `ORDER`, `PAYMENT`).
+- 같은 의미의 실패에 새 코드를 만들지 말고 기존 코드를 재사용한다.
+
+## 던지는 방법 (backend)
+
+```typescript
+import { BusinessException } from '@/common/errors/business.exception';
+
+// 레지스트리 메시지 그대로 사용
+throw new BusinessException('RES_001', { context: { userId: id } });
+
+// 동적 값이 필요할 때만 메시지 재정의 (코드·상태는 레지스트리 값 유지)
+throw new BusinessException('USER_001', {
+  message: `이미 가입된 이메일입니다. (${email})`,
+  context: { email },
+});
+```
+
+- `context` 는 **로그 전용**이다. 응답 본문에는 포함되지 않으므로 식별자를 자유롭게 넣어도 된다.
+- Nest 내장 예외(`NotFoundException` 등)를 던져도 필터가 상태 코드로 역매핑하지만, **새 코드에서는 `BusinessException` 을 쓴다** (코드가 명시되어 추적이 쉽다).
+- `HttpExceptionFilter` 에 문구를 하드코딩하지 않는다 — 레지스트리 조회만 한다.
+
+## 받는 방법 (client)
+
+```typescript
+// frontend — 인터셉터가 ApiError { code, message, traceId } 로 정규화해 reject
+try {
+  await api.post('/users', payload)
+} catch (e) {
+  const error = e as ApiError
+  if (error.code === 'USER_001') focusEmailField()   // 코드로 분기
+  // 알림은 인터셉터가 이미 처리했으므로 여기서 다시 띄우지 않는다
+}
+```
+
+```dart
+// flutter — 인터셉터가 DioException.error 에 ApiException 을 실어준다
+on DioException catch (e) {
+  final error = e.error as ApiException;
+  if (error.code == 'AUTH_002') redirectToLogin();
+}
+```
+
+- 개별 `try/catch` 에서 **메시지를 새로 만들지 않는다.** 문구는 사전에서만 온다.
+- 같은 코드의 알림이 연속으로 뜨지 않도록 인터셉터가 중복을 억제한다 — 호출부에서 다시 알림을 띄우지 말 것.
+
+## 추적 (traceId)
+
+- 모든 요청에 `x-request-id` 가 부여되고(`RequestIdMiddleware`), 실패 응답의 `error.traceId` 와 서버 로그에 같은 값이 남는다.
+- 사용자 문의 대응 시 이 값으로 로그를 검색한다. 상세 화면·에러 페이지에 작게 노출하는 것을 권장한다.
+
+> 응답 래퍼 구조는 [[response-format]], 로그 규칙은 [[logging]] 참조.

.claude/rules/git-convention.md

@@ -0,0 +1,38 @@
+# Git 컨벤션
+
+## 커밋 메시지
+
+`<type>(<scope>): <제목>` 형식 — scope 는 선택.
+
+- type: **feat / fix / refactor / docs / chore / perf / test / style**
+- scope: 변경이 한 스택에 한정되면 명시 — `backend` / `frontend` / `flutter` / `docker` / `rules`
+- 제목은 한국어, 명령형 현재 시제, 마침표 없음
+- 한 커밋은 하나의 논리적 변경만 포함
+
+```
+feat(backend): 사용자 목록 커서 페이지네이션 추가
+fix(frontend): 세션 만료 시 중복 알림 노출 수정
+docs(rules): 에러 코드 SSOT 동기화 절차 정리
+```
+
+본문이 필요하면 제목 다음 줄을 비우고 **왜** 바꿨는지 적는다(무엇을 바꿨는지는 diff 가 말해준다).
+
+## 브랜치
+
+`<type>/<간단한-설명>` — 기본 브랜치는 `main`.
+
+```
+feat/user-pagination
+fix/session-expired-alert
+```
+
+- 기본 브랜치에 직접 커밋하지 않는다. 작업은 브랜치에서 하고 PR 로 합친다.
+- 브랜치는 머지 후 삭제한다. 오래 유지되는 브랜치를 만들지 않는다.
+
+## PR
+
+- 제목은 커밋 규칙과 동일한 형식
+- 본문에 **무엇을 왜 바꿨는지**와 **확인 방법**을 적는다
+- `.github/pull_request_template.md` 의 체크리스트를 채운다
+- 머지 전 CI(`.github/workflows/ci.yml`)와 [[checklist]] 의 "커밋 전 공통 점검"을 통과해야 한다
+- 에러 코드·응답 포맷 등 **공유 계약을 바꾸는 PR** 은 세 스택 영향 범위를 본문에 명시한다 ([[error-codes]] · [[response-format]])

.claude/rules/logging.md

@@ -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]] 참조.

.claude/rules/response-format.md

@@ -0,0 +1,90 @@
+# 표준 응답 포맷 (Global Response Wrapper)
+
+모든 API 응답은 아래 구조로 통일한다.
+SSOT: backend `TransformInterceptor` + `HttpExceptionFilter` ([[nestjs]] 참조)
+
+```jsonc
+// 성공
+{ "success": true, "data": { /* ... */ } }
+
+// 실패
+{ "success": false, "error": { "code": "VAL_001", "message": "...", "traceId": "3f1c0a2e-..." } }
+```
+
+- 컨트롤러는 **raw 데이터만 반환**한다. `{success,data}` 래핑은 인터셉터가 담당 — 직접 래핑 금지.
+- 클라이언트 인터셉터는 `success: true` 면 `data` 만 언래핑해 반환한다.
+- 실패는 **항상 `error.code` 로 분기**한다. `message` 로 분기하지 않는다 ([[error-codes]]).
+- `traceId` 는 서버가 요청마다 발급하는 추적 ID(`x-request-id`)다. 응답 헤더로도 함께 내려간다.
+
+## 비즈니스 실패도 4xx 로 내린다
+
+- 백엔드는 `success: false` 를 **항상 4xx/5xx 와 함께** 내려보낸다. HTTP 200 + `success:false` 조합은 만들지 않는다.
+- 단, 클라이언트 인터셉터는 외부 게이트웨이 등이 200 으로 감싸는 경우를 대비해 **방어적으로 이 분기를 유지**한다.
+
+## 래핑 예외 (`@SkipTransform()`)
+
+본문 구조를 바꾸면 안 되는 응답은 백엔드에서 `@SkipTransform()` 을 붙여 래핑을 건너뛴다.
+
+```typescript
+@Get('export')
+@SkipTransform()   // 파일 스트림 — { success, data } 로 감싸면 깨진다
+exportCsv(@Res() res: Response) { /* ... */ }
+```
+
+적용 대상: 파일 다운로드·스트림, 리다이렉트, `204 No Content`, 외부 규격을 따라야 하는 웹훅 응답,
+그리고 **기계가 소비하는 엔드포인트**(헬스체크 등).
+
+### 헬스체크는 표준 포맷에서 제외한다
+
+`/api/health` 는 사람이 아니라 모니터링 도구가 읽는다. 래퍼로 감싸거나 실패를 `SYS_001` 로 덮어쓰면
+**어느 구성요소가 죽었는지가 사라진다.** 그래서 성공·실패 모두 terminus 원본 형식을 그대로 내보낸다.
+
+```jsonc
+// 200 — 정상
+{ "status": "ok", "info": { "database": { "status": "up" } }, "error": {}, "details": { ... } }
+
+// 503 — 실패 (원인이 보인다)
+{ "status": "error", "info": {}, "error": { "database": { "status": "down", "message": "..." } }, ... }
+```
+
+구현: `HealthController` 에 `@SkipTransform()` 을 붙이고, terminus 의 `ServiceUnavailableException` 은
+컨트롤러에서 직접 잡아 503 + 원본 본문을 반환한다(전역 필터까지 가지 않게 한다).
+같은 성격의 엔드포인트를 추가할 때 이 패턴을 재사용한다.
+
+## 목록 응답 (페이지네이션)
+
+목록 API 의 `data` 는 **항상 아래 구조**를 가진다. 배열을 그대로 반환하지 않는다.
+
+```jsonc
+{
+  "success": true,
+  "data": {
+    "items": [ /* ... */ ],
+    "pageInfo": {
+      "hasNext": true,
+      "nextCursor": "eyJpZCI6MTQzfQ==",  // 마지막 페이지면 null
+      "total": 143                        // 계산 비용이 크면 null 허용
+    }
+  }
+}
+```
+
+- 구현 SSOT: backend `common/dto/pagination.dto.ts`
+  (`CursorPaginationQueryDto` · `OffsetPaginationQueryDto` · `PageInfoDto` · `toPaginatedResult()`)
+- 클라이언트 타입: frontend `src/shared/types/pagination.ts`, flutter `UserRepository.getUsers()` 패턴
+- **커서 기반이 기본**이다. 전체 페이지 수가 UI 에 필요한 경우에만 오프셋을 쓴다.
+- `limit` 기본값 20, 최대 100 — 무제한 조회를 허용하지 않는다.
+
+## Swagger 문서 일치
+
+컨트롤러는 raw 를 반환하지만 실제 응답은 래핑되므로, `@ApiResponse({ type: Dto })` 를 그대로 쓰면 문서와 실응답이 어긋난다.
+
+```typescript
+@ApiStandardResponse(UserResponseDto, { description: '사용자 조회 성공' })
+@ApiErrorResponse('RES_001', '사용자를 찾을 수 없음')
+```
+
+- `ApiStandardResponse` / `ApiErrorResponse` 는 `common/decorators/api-standard-response.decorator.ts` 제공.
+- `ApiErrorResponse` 는 상태 코드·메시지를 에러 레지스트리에서 가져오므로 문서가 구현과 자동으로 일치한다.
+
+> 에러 코드 ↔ 메시지 매핑은 [[error-codes]], API 설계 규약은 [[api-design]] 참조.

.claude/rules/security.md

@@ -0,0 +1,114 @@
+# 보안
+
+## 비밀 정보
+
+- `.env*` 등 민감정보 Git 커밋 금지 (`.gitignore` 확인) — 예시는 `*.example`(예: `.env.development.example`, `.env.example`) 로만 공유
+- **`*.example` 파일의 값은 반드시 더미 placeholder 여야 한다.** 실제로 쓰는(또는 쓸 법한) 비밀번호·키를 예시 파일에 적지 않는다.
+  - ❌ `DB_PASSWORD=dev_960426`
+  - ✅ `DB_PASSWORD=change-me-in-local-env`
+- 시크릿이 한 번이라도 커밋되었다면 **값을 교체(rotate)** 한다. 커밋을 되돌리는 것만으로는 노출이 해소되지 않는다.
+- 로그·에러 응답에 시크릿을 남기지 않는다 ([[logging]]).
+
+## 인증 · 토큰
+
+- JWT는 HttpOnly·Secure 쿠키 사용 (웹 `localStorage` 금지) / 모바일은 `flutter_secure_storage` 사용 (키: `jwt_token`)
+- Access Token 만료는 짧게(15분~1시간), Refresh Token 은 HttpOnly 쿠키로만 전달
+- 비밀번호는 단방향 해시(`bcrypt`/`argon2`)로 저장한다. 평문·가역 암호화 금지
+- 인증 실패 응답에서 **원인을 구분해 알려주지 않는다** (아이디 없음/비밀번호 틀림 → 동일하게 AUTH_001)
+
+## 입력 · 출력
+
+- 입력값은 DTO(`class-validator`) 검증을 거친 뒤 서비스 계층에 전달한다. 전역 `ValidationPipe` 의 `whitelist`/`forbidNonWhitelisted` 를 끄지 않는다
+- TypeORM ORM 쿼리 사용으로 SQL Injection 차단 (Raw 쿼리 시 파라미터 바인딩 필수)
+- 에러 응답에 스택·쿼리·내부 호스트명을 싣지 않는다 — 미정의 예외는 항상 `SYS_001` 로 수렴시킨다 ([[error-codes]])
+### 파일 업로드
+
+템플릿은 `modules/upload` 에 로컬 디스크 기준 골격을 제공한다. 새 업로드 엔드포인트는 이 패턴을 복제한다.
+
+- **확장자와 MIME 을 둘 다** 검사한다 (`upload.config.ts`). 확장자만 보면 위장이 쉽고,
+  MIME 만 보면 클라이언트가 보낸 값이라 신뢰할 수 없다.
+- **허용 목록(allowlist) 방식**으로만 받는다. 차단 목록은 언제나 빠뜨린다.
+  `.html`·`.svg`·`.js` 등 **브라우저가 실행할 수 있는 형식은 넣지 않는다.**
+- **저장 파일명은 서버가 생성**한다(UUID + 검증된 확장자). 클라이언트가 보낸 이름을 경로에 쓰면
+  `../../etc/passwd` 같은 경로 탈출이 가능하다. 원본 이름은 표시용 메타데이터로만 보관한다.
+- 크기 한도를 설정한다 (`UPLOAD_MAX_SIZE_MB`, 기본 5MB). 초과 시 `FILE_002`(413).
+- 업로드 디렉터리를 **정적 파일로 그대로 서빙하지 않는다.** 내려줄 때는 컨트롤러를 거쳐
+  `Content-Type` 을 서버가 지정하고 `Content-Disposition: attachment` 를 붙인다.
+
+> ⚠️ **알려진 한계**: 확장자·MIME 검사는 **파일 내용을 보지 않는다.**
+> 이름이 `.png` 이고 MIME 이 `image/png` 이면 내용이 HTML 이어도 통과한다.
+> 그래서 위의 "정적 서빙 금지"가 중요하다 — 내용 기반 검증이 필요하면
+> 매직 바이트를 확인하는 라이브러리(`file-type` 등)를 파이프라인에 추가한다.
+
+## 네트워크 · 인프라
+
+- 보안 헤더(`helmet`) 적용
+- CORS 는 화이트리스트 방식. 차단 시 `callback(null, false)` 로 **헤더를 부여하지 않아** 브라우저가 막게 한다
+  (`callback(new Error(...))` 를 쓰면 500(SYS_001)이 되어 원인 파악이 어려워진다)
+- Rate Limiting: **`@nestjs/throttler` 하나로 일원화**되어 있다 (`app.module.ts` 의 `APP_GUARD`).
+  초과 시 429 → 전역 필터가 **`REQ_001`** 로 매핑한다.
+  - 기본 정책은 루트 `.env` 의 `THROTTLE_TTL_MS`/`THROTTLE_LIMIT` (미설정 시 60초/100회)
+  - 라우트 단위 조정: `@Throttle({ default: { ttl, limit } })` / 제외: `@SkipThrottle()`
+  - 로그인·비밀번호 재설정처럼 브루트포스 표적이 되는 엔드포인트는 **더 엄격한 한도**를 따로 건다
+  - ⚠️ rate limiter 를 이중으로 걸지 말 것 — 어느 쪽이 실제로 동작하는지 알 수 없게 되고 응답 헤더가 실제 한도와 어긋난다
+- **컨테이너 root 실행 금지 — 개발 환경 포함.** 운영뿐 아니라 dev 오버라이드가 사용하는 빌드 스테이지도 비-root 여야 한다.
+  - 프론트엔드 운영: `nginxinc/nginx-unprivileged` + `listen 8080` (비-root 는 1024 미만 포트 바인드 불가)
+  - Node 스테이지: `RUN chown node:node /app` → `USER node` → `COPY --chown=node:node`
+    (소유권을 먼저 넘겨야 익명 볼륨 `node_modules` 가 node 소유로 생성되어 캐시 쓰기가 가능하다)
+- DB·Redis 는 `expose` 만 사용해 내부 네트워크에만 노출한다.
+  개발 편의로 호스트에 열어야 한다면 **반드시 `127.0.0.1` 로 한정**한다 — `"${DB_PORT}:5432"` 는 `0.0.0.0` 바인딩이라
+  같은 공유기(사무실·카페)에 있는 누구나 개발 DB 에 접속할 수 있다.
+  ```yaml
+  ports:
+    - "127.0.0.1:${DB_PORT}:5432"   # ✅
+    # - "${DB_PORT}:5432"           # ❌ 외부 네트워크 노출
+  ```
+- **보안 헤더는 CSP 까지** 설정한다 (`frontend/nginx.conf`). 외부 CDN·폰트·분석 스크립트를 추가하면
+  해당 도메인을 CSP 에 명시한다. `script-src` 에 `'unsafe-inline'`/`'unsafe-eval'` 을 넣으면 CSP 의 의미가 사라진다.
+  API 도메인이 다르면 `connect-src` 에 추가해야 요청이 차단되지 않는다.
+
+## 의존성
+
+- 의존성 추가 시 유지보수 상태를 확인하고, 주기적으로 `npm audit` / `flutter pub outdated` 로 취약점을 점검한다
+- **`npm audit fix` 는 반드시 컨테이너 안에서 실행**한다. 호스트(Windows)에서 실행하면 lock 파일이 깨진다 ([[nestjs]])
+  ```bash
+  docker exec <프로젝트>-backend npm audit fix
+  ```
+- **`--force` 는 함부로 쓰지 않는다.** 메이저 버전을 올려 다른 패키지와의 호환이 깨질 수 있다.
+  실행 전 `npm audit fix --force --dry-run` 으로 어떤 패키지가 올라가는지 확인한다.
+
+### 남아 있는 취약점 판단 기준
+
+모든 취약점을 즉시 올릴 수 있는 것은 아니다. 다음을 근거로 판단하고 **결정을 기록**한다.
+
+1. **도달 가능한 코드 경로가 있는가** — 해당 기능을 쓰지 않으면 노출되지 않는다
+2. **수정이 다른 것을 깨뜨리는가** — 생태계 버전이 어긋나면 더 큰 위험
+3. 미룬다면 **언제 다시 볼지** 조건을 적어둔다
+
+> **현재 유예 중인 항목**: 없음 (`npm audit` 0건)
+
+### 전이 의존성 취약점은 overrides 로 끊는다
+
+직접 의존성이 취약한 하위 패키지를 **정확 버전으로 고정**해 두면 `npm audit fix` 로는 해결되지 않는다.
+상위 패키지의 메이저 업그레이드를 기다리지 말고 `package.json` 의 `overrides` 로 하위 패키지만 올린다.
+
+```jsonc
+// backend/package.json
+"overrides": {
+  "multer": "^2.4.0"
+}
+```
+
+> 실제 사례: `@nestjs/platform-express@11` 은 `multer` 를 `2.2.0` 으로 고정하는데 이 버전에 DoS 취약점(high)이 있었다.
+> `@nestjs/platform-express@12` 는 `multer@2.4.0` 을 쓰지만, v12 로 올리면 나머지 Nest 생태계(v11)와 호환이 깨진다.
+> **v12 가 하는 일이 결국 multer 를 올리는 것**이므로, override 로 같은 결과를 생태계 업그레이드 없이 얻었다.
+
+규칙:
+
+- override 는 **상위 패키지가 그 버전을 실제로 쓰는지 근거를 확인**하고 적용한다
+  (위 사례는 platform-express v12 가 2.4.0 을 선언하는 것이 근거).
+- 같은 메이저 안에서만 올린다. 메이저를 건너뛰면 API 가 달라져 상위 패키지가 깨질 수 있다.
+- 적용 후 **lint·테스트·빌드·런타임 기동까지 확인**한다. override 는 npm 이 검증해 주지 않는다.
+- 상위 패키지를 정식으로 올릴 때 **override 를 제거**한다. 남겨두면 나중에 버전이 거꾸로 고정된다.
+
+> 환경변수 관리 규칙은 [[env-structure]], 도메인별 적용은 [[nestjs]] · [[flutter]] 참조.

.claude/rules/testing.md

@@ -0,0 +1,72 @@
+---
+name: testing
+description: 세 스택 공통 테스트 규칙 — 테스트 위치/네이밍, 무엇을 테스트할지, 커밋 전 실행. backend Jest, frontend Vitest, flutter flutter_test 기준.
+---
+
+# 테스트 규칙
+
+> 템플릿은 각 스택에 테스트 러너가 준비되어 있다 — backend `jest`, frontend `vitest`, flutter `flutter_test`.
+> 새 로직을 추가하면 최소한의 테스트를 함께 작성한다.
+
+## 공통 원칙
+
+- **무엇을 테스트하나**: 순수 함수(utils), 서비스/비즈니스 로직, 에러 코드 매핑 분기를 우선한다. 프레임워크 기본 동작은 테스트하지 않는다.
+- **공유 계약은 반드시 테스트한다** — 아래 "계약 테스트" 절 참조.
+- **테스트는 결정적(deterministic)** 으로 — 외부 네트워크/시간/랜덤에 의존하지 않도록 모킹한다.
+- **커밋 전 실행** — 변경 영역의 테스트가 통과해야 한다. ([[checklist]])
+- **CI 가 강제한다** — `.github/workflows/ci.yml` 이 세 스택의 lint·test·build 와 에러 코드 동기화를 PR 마다 검사한다.
+- 테스트 설명(it/test 제목)은 한국어로 "무엇을 검증하는지" 명확히 작성한다.
+
+## 스택별 위치·실행
+
+| 스택 | 러너 | 위치·네이밍 | 실행 |
+| --- | --- | --- | --- |
+| backend | Jest | 단위 `*.spec.ts` (소스 옆), e2e `test/*.e2e-spec.ts` | `npm run test`, `npm run test:e2e` |
+
+| frontend | Vitest | `*.spec.ts` / `*.test.ts` (대상 옆 또는 `__tests__/`) | `npm run test:unit` |
+| flutter | flutter_test | `test/` 하위, `*_test.dart` | `flutter test` |
+
+## 예시 (backend 순수 유틸)
+
+```typescript
+// shared/utils/format.spec.ts
+import { formatSomething } from './format';
+
+describe('formatSomething', () => {
+  it('빈 입력이면 빈 문자열을 반환한다', () => {
+    expect(formatSomething('')).toBe('');
+  });
+});
+```
+
+---
+
+## 계약 테스트 (삭제·비활성화 금지)
+
+세 플랫폼이 공유하는 계약은 어긋나도 컴파일 에러가 나지 않는다. 아래 테스트가 그 안전망이다.
+
+| 대상 | 위치 | 검증 내용 |
+| --- | --- | --- |
+| 에러 코드 레지스트리 | `backend/src/common/errors/error-codes.spec.ts` | 네이밍 규약, 상태 역매핑, 클라이언트 전용 코드가 서버에서 선택되지 않음 |
+| 에러 응답 포맷 | `backend/src/common/filters/http-exception.filter.spec.ts` | 코드/상태/traceId, **내부 정보 미노출**, 검증 상세 사유 미노출 |
+| 프론트 에러 사전 | `frontend/src/composables/useApi.spec.ts` | 코드 목록이 백엔드와 일치, 폴백 동작 |
+| 앱 에러 사전 | `flutter/test/error_lexicon_test.dart` | 코드 목록이 백엔드와 일치, 폴백 동작 |
+| 응답 계약 (e2e) | `backend/test/app.e2e-spec.ts` | 실제 HTTP 로 래퍼·에러코드·traceId·페이지네이션·헬스체크 형식 검증 |
+
+> **e2e 는 DB 가 필요하다** (AppModule 이 TypeORM 을 초기화한다).
+> 로컬에서는 개발 스택을 띄운 뒤 컨테이너 안에서 실행하는 것이 가장 간단하다.
+> ```bash
+> docker exec <프로젝트>-backend npx jest --config ./test/jest-e2e.json
+> ```
+> CI 는 postgres 서비스 컨테이너를 띄워 자동으로 실행한다.
+
+- 에러 코드를 추가/삭제하면 **세 곳의 기대 목록을 함께 갱신**한다 ([[checklist]] 3절).
+- 매핑 로직(응답 래퍼·상태 역매핑)을 바꾸면 해당 분기 테스트를 추가한다.
+
+## 테스트하지 않아도 되는 것
+
+- 프레임워크가 보장하는 동작 (라우팅, DI 주입 자체, ORM 쿼리 빌더)
+- 단순 getter/setter, 위임만 하는 컨트롤러 메서드
+- 화면 스타일·레이아웃 값
+
+> API 응답 래퍼/에러 코드는 세 플랫폼 공유 계약이다 ([[response-format]] · [[error-codes]]).