samsin/.claude/rules/env-structure.md

name, description

name	description
env-structure	환경변수 단일 진실 공급원(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 참조.