ttipo
dac1603b03
지금까지 "커밋 전 lint/test 통과"는 문서상의 약속일 뿐 강제되지 않았다. - CI(GitHub Actions) 추가 — 세 스택의 lint·test·build 와 backend e2e 를 PR 마다 실행. error-codes-sync 잡은 sync 를 재실행한 뒤 git diff 로 생성 파일 드리프트를 검사한다. 레지스트리만 고치고 sync 를 빠뜨리면 클라이언트 사전이 조용히 어긋나기 때문. - lint 스크립트에 --max-warnings 0 적용. 기존에는 경고가 있어도 통과해 "Warning 0" 규칙이 사실상 무의미했다. 자동 수정은 lint:fix 로 분리. - 문서로만 있던 규칙을 린트로 이관: any/dynamic 금지, console/print 금지, Vue 인라인 스타일·Options API 금지, Dart const 누락·await 누락, HttpException 직접 생성 차단(BusinessException 유도). - backend 에 @/ 경로 alias 설정 (tsconfig paths + jest moduleNameMapper). 공통 규칙이 요구하는 절대경로 alias 가 backend 에만 빠져 있었다. - npm audit 취약점 10건 중 9건 해결. 남은 multer(high)는 platform-express v12 가 필요해 Nest v11 생태계와 충돌하고, 파일 업로드 엔드포인트가 없어 도달 경로가 없다 — security.md 에 재검토 조건 기록. - PR 템플릿 추가. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
풀스택 모노레포 기본 템플릿
NestJS(백엔드) · Vue 3(웹) · Flutter(모바일)를 하나의 저장소에서 운영하는 풀스택 템플릿입니다. 세 클라이언트는 동일한 표준 응답 포맷과 공통 에러 코드 맵을 공유하며, Docker Compose로 한 번에 구동됩니다.
구성
| 디렉터리 | 스택 | 역할 | 포트(기본) |
|---|---|---|---|
backend/ |
NestJS + TypeORM | REST API 서버 | 3000 |
frontend/ |
Vue 3 + Vite | 웹 프론트엔드 | 5173 |
flutter/ |
Flutter + Riverpod | 모바일 앱 | - |
db |
PostgreSQL | 데이터베이스 | 5432 |
redis |
Redis | 캐시 / 세션 | 6379 |
사전 요구사항
- Docker / Docker Compose — backend·frontend·db·redis 구동
- Flutter SDK
^3.11— 모바일 앱 실행용 (compose 대상 아님)
빠른 시작 (Docker)
# 1) 환경변수 파일 생성 (예제 복사)
# 실제 설정값은 루트 .env.development 한 곳에서 관리한다 (SSOT).
# backend/frontend 는 docker-compose 가 값을 주입하므로 예제만 복사하면 된다.
cp .env.development.example .env.development # ← 여기에만 값 입력
cp backend/.env.development.example backend/.env.development # (존재 필요: JWT 등 고유 시크릿)
# frontend 는 compose 가 빌드 시 값을 주입하므로 자체 env 복사 불필요
# 2) 개발 환경 기동 (코드만 수정 시)
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d
# 3) 의존성 변경 시에만 --build
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d --build
기동 후:
- 웹: http://localhost:5173
- API: http://localhost:3000/api
- Swagger 문서: http://localhost:3000/api-docs
전체 실행/배포 명령어는 .claude/skills/docker/SKILL.md 참조.
모바일 앱 실행 (Flutter)
Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합니다.
cd flutter && cp .env.example .env && flutter pub get && flutter run
flutter/.env의API_URL을 백엔드 주소로 설정합니다. (Android 에뮬레이터는http://10.0.2.2:3000/api)
환경변수
.env* 는 커밋하지 않습니다. 각 디렉터리의 *.example 파일을 복사해 사용하세요.
루트 .env.{env} 가 단일 진실 공급원(SSOT) 입니다. backend·frontend 는 docker-compose 가
루트 값을 주입하므로 자체 env 에 값을 중복 작성하지 않습니다. (자세한 위임 구조는 CLAUDE.md 의 "환경변수 구조" 참조)
| 파일 | 용도 | 값 작성 위치 |
|---|---|---|
.env.{env}.example |
루트 — 모든 설정의 SSOT (compose 주입) | ✅ 여기에 작성 |
backend/.env.{env}.example |
백엔드 — 고유 시크릿(JWT 등)만 | 최소 (존재 필수) |
frontend/.env.{env}.example |
프론트 — 빌드 시 루트 BACKEND_API_URL 주입 |
작성 불필요 |
flutter/.env.example |
모바일 — API_URL (compose 비대상) |
✅ 독립 관리 |
{env} = development | production
표준 응답 포맷
// 성공
{ "success": true, "data": { /* ... */ } }
// 실패
{ "success": false, "error": { "code": "VAL_001", "message": "..." } }
에러 코드 맵과 코딩 규칙 전문은 CLAUDE.md 및 .claude/rules/·.claude/skills/ 의 규칙 문서를 참고하세요.
개발 규칙
| 영역 | 문서 |
|---|---|
| 공통/보안 | CLAUDE.md · .claude/rules/ |
| NestJS | .claude/skills/nestjs/SKILL.md |
| Vue 3 | .claude/skills/vue3/SKILL.md |
| Flutter | .claude/skills/flutter/SKILL.md |
| Docker | .claude/skills/docker/SKILL.md |
디렉터리 구조
.
├── backend/ # NestJS API (Controller / Service / DTO / 공통 필터·인터셉터)
├── frontend/ # Vue 3 (pages / components / composables / stores / router)
├── flutter/ # Flutter (core / features / widgets)
├── docker-compose.yml # 베이스 정의
├── docker-compose.dev.yml # 개발 오버라이드 (핫리로드, 포트 노출)
├── CLAUDE.md # 프로젝트 개요 + 공통 규칙 @import
└── .claude/
├── settings.json # Claude Code 권한·환경 설정
├── rules/ # 공통 규칙 (코딩·응답 포맷·에러 코드·커밋·보안·환경변수)
└── skills/ # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)