ttipo
6306160dda
- 슬래시 커맨드(nestjs/vue3/flutter)를 정식 스킬(.claude/skills)로 전환하고 docker 스킬을 신설(루트 command.md 이관) - 공통 규칙을 .claude/rules 로 모듈화(coding-common·response-format·error-codes· git-convention·security·env-structure·testing·checklist)하고 CLAUDE.md 에서 @import - 파일·식별자 네이밍 규약, 테스트 규칙 추가 - .claude/settings.json(권한·환경) 추가 - CLAUDE.md·README.md 참조 갱신, 단독 실행(non-Docker) 안내 정리 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# 풀스택 모노레포 기본 템플릿
|
|
|
|
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)
|
|
|
|
```bash
|
|
# 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`](./.claude/skills/docker/SKILL.md) 참조.
|
|
|
|
## 모바일 앱 실행 (Flutter)
|
|
|
|
Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합니다.
|
|
|
|
```bash
|
|
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`](./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`
|
|
|
|
## 표준 응답 포맷
|
|
|
|
```jsonc
|
|
// 성공
|
|
{ "success": true, "data": { /* ... */ } }
|
|
// 실패
|
|
{ "success": false, "error": { "code": "VAL_001", "message": "..." } }
|
|
```
|
|
|
|
에러 코드 맵과 코딩 규칙 전문은 [`CLAUDE.md`](./CLAUDE.md) 및 `.claude/rules/`·`.claude/skills/` 의 규칙 문서를 참고하세요.
|
|
|
|
## 개발 규칙
|
|
|
|
| 영역 | 문서 |
|
|
| --------- | ------------------------------------------------- |
|
|
| 공통/보안 | [`CLAUDE.md`](./CLAUDE.md) · [`.claude/rules/`](./.claude/rules/) |
|
|
| NestJS | [`.claude/skills/nestjs/SKILL.md`](./.claude/skills/nestjs/SKILL.md) |
|
|
| Vue 3 | [`.claude/skills/vue3/SKILL.md`](./.claude/skills/vue3/SKILL.md) |
|
|
| Flutter | [`.claude/skills/flutter/SKILL.md`](./.claude/skills/flutter/SKILL.md) |
|
|
| Docker | [`.claude/skills/docker/SKILL.md`](./.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)
|
|
```
|