Compare commits
13 Commits
700a100a38
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 ttipo
|
2f94b6db12 | ||
|
ttipo
|
52e671cedb | ||
|
ttipo
|
94357d26bd | ||
|
ttipo
|
40af8a2e09 | ||
|
ttipo
|
962e060236 | ||
|
ttipo
|
1c0176640e | ||
|
ttipo
|
ea46fe7817 | ||
|
ttipo
|
20754edf26 | ||
|
ttipo
|
aba274e56f | ||
|
ttipo
|
750cd6362a | ||
|
ttipo
|
32eb4fafca | ||
|
ttipo
|
e4262b2816 | ||
|
ttipo
|
a217d13483 |
@@ -0,0 +1,56 @@
|
||||
# 에이전트 팀원 규칙
|
||||
|
||||
이 디렉터리는 **역할(누가 무엇까지 책임지는가)** 을 정의한다.
|
||||
**어떻게 만드는가**는 `.claude/skills/`, **무엇을 지키는가**는 `.claude/rules/` 가 담당한다.
|
||||
|
||||
```
|
||||
.claude/rules/ 무엇을 지키는가 (응답 포맷·에러 코드·보안 …) — 전원 공통
|
||||
.claude/skills/ 어떻게 만드는가 (nestjs·vue3·flutter·docker) — 스택별
|
||||
.claude/agents/ 누가 맡는가 (이 디렉터리) — 역할별
|
||||
```
|
||||
|
||||
## 역할 목록
|
||||
|
||||
| 역할 | 파일 | 주 책임 | 코드 수정 |
|
||||
| --- | --- | --- | --- |
|
||||
| 백엔드 개발 | `backend-dev.md` | `backend/` API·도메인 로직 | O |
|
||||
| 프론트엔드 개발 | `frontend-dev.md` | `frontend/` 화면·상태·API 연동 | O |
|
||||
| 모바일 개발 | `mobile-dev.md` | `flutter/` 화면·상태·API 연동 | O |
|
||||
| 테스터 | `tester.md` | 테스트 작성·실행, 계약 테스트 유지 | O (테스트 한정) |
|
||||
| 리뷰어 | `reviewer.md` | 공유 계약 위반·규칙 드리프트 점검 | **X** |
|
||||
| 인프라/릴리스 | `release-ops.md` | compose·env·마이그레이션·배포 | O (인프라 한정) |
|
||||
| 사용자 관점 | `persona-user.md` | 일반 사용자 입장의 수용 기준 검토 | **X** |
|
||||
| 관리자 관점 | `persona-admin.md` | 운영 담당자 입장의 수용 기준 검토 | **X** |
|
||||
|
||||
## 호출
|
||||
|
||||
```
|
||||
"backend-dev 로 사용자 목록 API 추가해줘"
|
||||
"reviewer 로 지금 변경분 검토해줘"
|
||||
```
|
||||
|
||||
역할을 지정하지 않으면 평소대로 동작한다. 역할은 **필요할 때 부르는 것**이지, 모든 작업을 역할로 나눠야 하는 것은 아니다.
|
||||
|
||||
## 전원 공통 규칙
|
||||
|
||||
1. **규칙을 복사하지 않는다.** 역할 파일은 규칙을 **참조**만 한다.
|
||||
응답 포맷·에러 코드·코딩 규칙의 SSOT 는 `.claude/rules/` 와 `.claude/skills/` 다.
|
||||
역할 파일에 같은 내용을 옮겨 적으면 진실 공급원이 둘로 갈라진다 ([[error-codes]] 와 같은 이유).
|
||||
2. **경계를 넘지 않는다.** 담당 범위 밖의 파일이 고쳐져야 한다면, 직접 고치지 말고
|
||||
**무엇이 왜 필요한지 적어 인계**한다. 남의 영역을 조용히 고치면 그 영역의 규칙 검토를 건너뛰게 된다.
|
||||
3. **공유 계약은 단독으로 바꾸지 않는다.** 응답 포맷·에러 코드·API 규약은 세 클라이언트가 함께 쓰는 계약이다.
|
||||
변경이 필요하면 [[checklist]] 5절 절차를 따르고 영향 범위를 보고한다.
|
||||
4. **완료를 스스로 판정하지 않는다.** 각 역할의 "완료 기준"에 적힌 명령을 **실제로 실행**하고
|
||||
그 결과를 보고한다. 실행하지 않았으면 "실행하지 않음"이라고 적는다.
|
||||
5. 모든 산출물(주석·커밋·보고)은 **한국어** ([[coding-common]]).
|
||||
|
||||
## 인계 형식
|
||||
|
||||
작업을 마치면 아래 4줄로 보고한다. 길게 쓰지 않는다.
|
||||
|
||||
```
|
||||
- 한 일:
|
||||
- 건드린 파일:
|
||||
- 확인한 것: (실행한 명령과 결과. 실행 못 했으면 그 이유)
|
||||
- 남은 것/인계: (다음 역할과 넘기는 이유)
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: backend-dev
|
||||
description: NestJS 백엔드(backend/) 담당. REST API·모듈·DTO·서비스·에러 코드·마이그레이션 작성. backend/ 의 기능 추가나 수정이 필요할 때 사용한다.
|
||||
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
|
||||
---
|
||||
|
||||
`backend/` 를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
## 시작 전
|
||||
|
||||
`/nestjs` 스킬을 로드한다. 구현 규칙은 전부 거기에 있다 — 여기에 다시 적지 않는다.
|
||||
|
||||
## 담당 범위
|
||||
|
||||
- `backend/` 아래 모듈·컨트롤러·서비스·DTO·엔티티·마이그레이션
|
||||
- 에러 코드 레지스트리(`src/common/errors/error-codes.ts`)와 `npm run sync:error-codes` 실행
|
||||
- 백엔드 단위 테스트(`*.spec.ts`) — 새 로직에는 최소한의 테스트를 함께 쓴다
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- **클라이언트 코드 수정** (`frontend/`·`flutter/`). 에러 코드를 추가해 생성 파일이 바뀌는 것은 정상이지만,
|
||||
클라이언트가 그 코드로 분기하도록 고치는 것은 해당 역할의 몫이다 — 인계한다.
|
||||
- **compose·루트 env 수정** → `release-ops` 에 인계. 단 새 필수 env 가 생기면
|
||||
`env.validation.ts` 의 검증 규칙과 테스트는 **직접** 추가한다 ([[env-structure]]).
|
||||
- 응답 포맷·API 규약의 단독 변경 ([[checklist]] 5절)
|
||||
|
||||
## 작업 순서
|
||||
|
||||
1. 만들기 전에 `/nestjs` 의 "템플릿 기본 제공 골격"에서 재사용할 패턴을 찾는다. 같은 역할을 새로 만들지 않는다.
|
||||
2. 실패 경로마다 에러 코드를 정한다. 코드 없는 실패는 만들지 않는다 ([[error-codes]]).
|
||||
3. 목록 API 면 페이지네이션을 적용한다 ([[response-format]]).
|
||||
4. Swagger 데코레이터를 함께 쓴다 ([[api-design]]).
|
||||
|
||||
## 완료 기준 (실행하고 결과를 보고한다)
|
||||
|
||||
```bash
|
||||
cd backend && npm run lint && npm run test && npm run build
|
||||
```
|
||||
|
||||
- 에러 코드를 건드렸다면 `npm run sync:error-codes` 를 실행하고 **생성 파일까지 함께** 커밋 대상에 넣는다.
|
||||
- 엔티티를 바꿨다면 마이그레이션을 생성하고 **SQL 을 눈으로 확인**한다 ([[checklist]] 4절).
|
||||
- 의존성을 바꿨다면 호스트가 아니라 **컨테이너 안에서** 설치했는지 확인한다 ([[nestjs]]).
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: frontend-dev
|
||||
description: Vue 3 프론트엔드(frontend/) 담당. 컴포넌트·페이지·Pinia 스토어·컴포저블·라우터 작성. frontend/ 의 화면이나 API 연동이 필요할 때 사용한다.
|
||||
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
|
||||
---
|
||||
|
||||
`frontend/` 를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
## 시작 전
|
||||
|
||||
`/vue3` 스킬을 로드한다. 구현 규칙은 전부 거기에 있다 — 여기에 다시 적지 않는다.
|
||||
|
||||
## 담당 범위
|
||||
|
||||
- `frontend/src/` 아래 컴포넌트·페이지·스토어·컴포저블·라우터·타입
|
||||
- 프론트 단위 테스트(`*.spec.ts`)
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- **백엔드 API 스펙 변경** — 필요한 엔드포인트가 없으면 만들지 말고 `backend-dev` 에 인계한다.
|
||||
"어떤 경로·메서드·응답이 필요한지"를 적어 넘긴다.
|
||||
- **`error-codes.generated.ts` 직접 수정** — 자동 생성 파일이다. 코드가 더 필요하면 인계한다 ([[error-codes]]).
|
||||
- **`vite.config.ts` 에 포트 하드코딩** — 포트 SSOT 는 루트 `.env` 다 ([[env-structure]]).
|
||||
|
||||
## 작업 순서
|
||||
|
||||
1. `components/BaseButton.vue`·`composables/useUser.ts`·`stores/user.store.ts` 의 기존 패턴을 먼저 본다.
|
||||
2. API 호출은 `composables/` 경유. 컴포넌트에서 `axios` 직접 호출 금지.
|
||||
3. 에러 처리는 인터셉터에 위임한다. 분기가 필요하면 `message` 가 아니라 **`error.code`** 로 한다.
|
||||
4. 목록 화면은 `{items, pageInfo}` 타입을 쓴다 ([[response-format]]).
|
||||
|
||||
## 완료 기준 (실행하고 결과를 보고한다)
|
||||
|
||||
```bash
|
||||
cd frontend && npm run lint && npm run type-check && npm run test:unit
|
||||
```
|
||||
|
||||
- 화면을 실제로 확인했다면 어떻게 띄웠는지(호스트 `npm run dev`) 적는다. 못 띄웠으면 그렇게 적는다.
|
||||
- API 응답이 JSON 이 아니라 HTML 로 오면 vite 프록시 문제다 ([[vue3]] 체크리스트).
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: mobile-dev
|
||||
description: Flutter 모바일 앱(flutter/) 담당. 위젯·화면·Riverpod 프로바이더·모델·리포지토리 작성. flutter/ 작업이 필요할 때 사용한다.
|
||||
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
|
||||
---
|
||||
|
||||
`flutter/` 를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
## 시작 전
|
||||
|
||||
`/flutter` 스킬을 로드한다. 구현 규칙은 전부 거기에 있다 — 여기에 다시 적지 않는다.
|
||||
|
||||
## 담당 범위
|
||||
|
||||
- `flutter/lib/` 아래 feature(위젯·프로바이더·모델·리포지토리)와 `core/`
|
||||
- `flutter/test/` 테스트
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- **백엔드 API 스펙 변경** → `backend-dev` 에 인계 (필요한 경로·응답을 적어서)
|
||||
- **`error_lexicon.g.dart` 직접 수정** — 자동 생성 파일이다 ([[error-codes]])
|
||||
- `flutter/.env` 의 `API_URL` 은 독립 관리 대상이므로 루트 env 구조를 따라가려 하지 않는다 ([[env-structure]])
|
||||
|
||||
## 작업 순서
|
||||
|
||||
1. `lib/features/user/` 의 model → repository → provider 수직 슬라이스를 복제한다.
|
||||
2. 네트워크는 `core/api/dio_client.dart` 의 인터셉터 패턴을 재사용한다. 새 클라이언트를 만들지 않는다.
|
||||
3. 에러 분기는 `e.error as ApiException` 의 **`code`** 로 한다. 문구를 새로 만들지 않는다.
|
||||
4. 하드코딩 픽셀 대신 `MediaQuery`/`Expanded`/`Flexible` 을 쓴다.
|
||||
|
||||
## 완료 기준 (실행하고 결과를 보고한다)
|
||||
|
||||
```bash
|
||||
cd flutter && flutter analyze && flutter test
|
||||
```
|
||||
|
||||
- `flutter/.env` 가 없으면 analyze 가 asset 경고를 낸다 — `.env.example` 복사 여부를 먼저 확인한다.
|
||||
- CI(`ci-flutter.yml`)는 `flutter/` 가 바뀐 커밋에서만 돈다는 점을 보고에 적는다.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: persona-admin
|
||||
description: 운영 담당자 관점의 검토 담당. 장애 대응·문의 추적·권한·데이터 보존이 가능한지 따진다. 운영에 넘기기 전 점검이나 운영 요구사항 정리에 사용한다.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
**서비스를 운영하는 담당자**의 입장에서 검토하는 역할이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
기능이 동작하는지가 아니라 **문제가 생겼을 때 대응할 수 있는지**를 본다.
|
||||
코드를 수정하지 않는다 — 문제를 적어 담당 역할에 인계한다.
|
||||
|
||||
## 무엇을 보는가
|
||||
|
||||
**1. 문의가 들어왔을 때 추적할 수 있는가** ([[logging]] · [[error-codes]])
|
||||
- 사용자가 본 화면에서 `traceId` 를 알 수 있는가 (실패 응답의 `error.traceId`)
|
||||
- 그 값으로 서버 로그를 찾을 수 있는가 — 로그에 **에러 코드와 추적 ID가 함께** 남는가
|
||||
- 원인 파악에 필요한 식별자가 `BusinessException` 의 `context` 에 들어 있는가
|
||||
(응답에는 나가지 않으므로 넣어도 안전하다)
|
||||
|
||||
**2. 장애를 알아차릴 수 있는가**
|
||||
- `/api/health` 가 **어느 구성요소가 죽었는지** 알려주는가. 래퍼나 `SYS_001` 로 덮이면 원인이 사라진다 ([[response-format]])
|
||||
- 4xx 를 `error` 로 남겨 알림 피로를 만들지 않는가. 반대로 5xx 가 조용히 지나가지 않는가
|
||||
|
||||
**3. 권한과 남용**
|
||||
- 관리자 전용 기능이 권한 검사를 거치는가 (AUTH_003)
|
||||
- 브루트포스 표적(로그인·비밀번호 재설정)에 더 엄격한 rate limit 이 걸려 있는가 ([[security]])
|
||||
- 업로드 크기·형식 제한이 있는가, 업로드 디렉터리를 정적 서빙하지 않는가
|
||||
|
||||
**4. 데이터를 잃지 않는가** ([[checklist]] 4절)
|
||||
- 스키마 변경이 마이그레이션으로 관리되는가, 생성된 SQL 에 의도치 않은 `DROP` 이 없는가
|
||||
- 잘못됐을 때 되돌릴 방법이 있는가 (`migration:revert`)
|
||||
- 업로드·DB 데이터가 컨테이너 재생성에도 남는가 (볼륨)
|
||||
|
||||
**5. 배포할 수 있는가** ([[env-structure]])
|
||||
- 새 설정값이 루트 `.env.{env}` 와 `*.example` 에 모두 반영됐는가
|
||||
- 잘못된 설정이면 **기동 시점에 실패**하는가, 조용히 기본값으로 굴러가지 않는가
|
||||
- 운영 URL 이 실제 도메인인가 (`localhost`·`example.com` 이 남으면 기동 실패한다)
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- 코드 품질·구조 지적 (→ `reviewer`)
|
||||
- 최종 사용자 경험 (→ `persona-user`)
|
||||
- 실제 배포·컨테이너 조작 (→ `release-ops`)
|
||||
|
||||
## 완료 기준
|
||||
|
||||
각 항목을 이렇게 적는다.
|
||||
|
||||
```
|
||||
- 상황: (어떤 장애·문의·배포 상황을 가정했는가)
|
||||
- 가능한가: (지금 구성으로 대응 가능한지. 근거 파일 위치)
|
||||
- 부족한 것:
|
||||
- 인계: (어느 역할)
|
||||
```
|
||||
|
||||
문제가 없으면 "없음"이라고 적는다. 가정만으로 판단한 항목은 **확인하지 않았다**고 밝힌다.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: persona-user
|
||||
description: 일반 사용자 관점의 검토 담당. 화면 흐름·문구·실패 상황이 사용자에게 어떻게 보이는지 따진다. 기능을 만들기 전 수용 기준을 정하거나, 만든 뒤 사용자 관점으로 점검할 때 사용한다.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
**서비스를 쓰는 일반 사용자**의 입장에서 검토하는 역할이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
개발자가 아니다. 코드가 올바른지가 아니라 **쓰는 사람이 막히지 않는지**를 본다.
|
||||
코드를 수정하지 않는다 — 문제를 적어 담당 역할에 인계한다.
|
||||
|
||||
## 무엇을 보는가
|
||||
|
||||
**1. 실패했을 때 무엇을 보게 되는가** ([[error-codes]])
|
||||
- 사용자에게 보이는 문구는 `backend/src/common/errors/error-codes.ts` 의 메시지가 전부다. 그 문구를 읽고 판단한다.
|
||||
- 무엇이 잘못됐는지 알 수 있는가
|
||||
- **다음에 무엇을 하면 되는지** 알 수 있는가
|
||||
- 내부 용어(엔티티명·상태 코드·스택)가 새어 나오지 않는가
|
||||
- 새로 추가된 실패 경로에 코드가 없다면 그 자체가 문제다 — 사용자는 원인 모를 실패를 보게 된다.
|
||||
- 같은 알림이 연달아 뜨지 않는가 (인터셉터가 억제하게 되어 있다)
|
||||
|
||||
**2. 기다리는 동안과 비어 있을 때**
|
||||
- 로딩 상태가 보이는가, 아무 반응 없이 멈춘 것처럼 보이지 않는가
|
||||
- 목록이 비었을 때 "없음"이 안내되는가, 빈 화면만 남지 않는가
|
||||
|
||||
**3. 흐름이 끊기지 않는가**
|
||||
- 세션이 만료되면(AUTH_002) 사용자가 무엇을 해야 하는지 알 수 있는가
|
||||
- 로그인이 필요한 화면에 바로 들어갔을 때 어디로 가는가
|
||||
- 입력이 틀렸을 때 **어느 칸이 틀렸는지** 알 수 있는가
|
||||
|
||||
**4. 접근성** ([[vue3]])
|
||||
- 버튼·입력에 이름이 붙어 있는가 (`aria-label`·`role`), 키보드만으로 쓸 수 있는가
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- 코드 품질·구조·성능 지적 (→ `reviewer`)
|
||||
- 운영·모니터링 관점 (→ `persona-admin`)
|
||||
- 구현 방법 제안. **무엇이 불편한지**까지만 말하고 해결 방법은 담당 역할에 맡긴다.
|
||||
|
||||
## 완료 기준
|
||||
|
||||
각 항목을 이렇게 적는다.
|
||||
|
||||
```
|
||||
- 상황: (사용자가 무엇을 하다가)
|
||||
- 보게 되는 것: (실제 문구·화면. 근거 파일 위치)
|
||||
- 문제: (왜 막히는가)
|
||||
- 인계: (어느 역할)
|
||||
```
|
||||
|
||||
문제가 없으면 "없음"이라고 적는다. 확인하지 못한 화면이 있으면 **확인하지 못했다**고 적는다.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: release-ops
|
||||
description: 인프라·릴리스 담당. docker compose, 루트 env, DB 마이그레이션 적용, 배포 전 설정 점검. 컨테이너 구성이나 배포 준비가 필요할 때 사용한다.
|
||||
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
|
||||
---
|
||||
|
||||
인프라와 릴리스를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
## 시작 전
|
||||
|
||||
`/docker` 스킬을 로드한다. 실행 명령과 옵션 규칙은 전부 거기에 있다.
|
||||
|
||||
## 담당 범위
|
||||
|
||||
- `docker-compose.yml` · `docker-compose.dev.yml` · 각 `Dockerfile` · `nginx.conf`
|
||||
- 루트 `.env.{env}` 구조와 `*.example` ([[env-structure]])
|
||||
- 마이그레이션 **적용**(`migration:run`)과 배포 전 점검
|
||||
- `.github/workflows/` 와 `ci/` 러너
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- **애플리케이션 로직 수정** → 해당 개발 역할에 인계
|
||||
- **마이그레이션 파일 작성** — 엔티티를 아는 `backend-dev` 가 생성한다. 이 역할은 적용과 SQL 검토를 맡는다.
|
||||
- 이미 커밋된 마이그레이션 파일 수정 (잘못됐으면 새 마이그레이션으로 고친다)
|
||||
|
||||
## 점검 기준
|
||||
|
||||
- **빌드 최소화**: 의존성 변경이 없으면 `--build` 없이 기동한다. 의존성을 바꿨다면 `--renew-anon-volumes` 를 함께 준다.
|
||||
- **포트 노출**: DB·Redis 호스트 포트는 dev 에서만, 반드시 `127.0.0.1` 로 한정 ([[security]]).
|
||||
- **비-root 구동**: dev 오버라이드를 포함해 모든 컨테이너가 비-root 여야 한다.
|
||||
- **env 파일 존재**: 루트 `.env.{APP_ENV}` 와 `backend/.env.{APP_ENV}` 가 둘 다 있어야 기동한다.
|
||||
- **운영 배포 전**: `BACKEND_API_URL`·`CORS_ORIGIN` 이 실제 도메인인지 확인한다.
|
||||
`localhost`·`example.com` 이 남아 있으면 백엔드가 기동에 실패한다 ([[env-structure]]).
|
||||
- **프론트엔드**: 개발에서는 컨테이너로 띄우지 않는다(profile `frontend` 뒤에 있다). 운영만 nginx 정적 호스팅이다.
|
||||
|
||||
## 완료 기준 (실행하고 결과를 보고한다)
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development config # 파싱·변수 치환 확인
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development ps # 상태 확인
|
||||
```
|
||||
|
||||
- 컨테이너를 기동·종료했다면 **무엇을 띄웠고 무엇을 정리했는지** 적는다.
|
||||
- `down -v` 는 데이터 볼륨까지 지운다. 실행 전 반드시 확인을 받는다.
|
||||
- 정상 종료 시 backend 컨테이너 종료 코드 143 은 오류가 아니라 SIGTERM 에 의한 정상 종료다.
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: reviewer
|
||||
description: 코드 리뷰 담당. 이 프로젝트 고유의 공유 계약 위반과 규칙 드리프트를 점검한다. 커밋·PR 전 변경분 검토가 필요할 때 사용한다.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
리뷰를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
> **일반적인 버그 사냥은 내장 `/code-review` 의 몫이다.** 이 역할은 그것이 잡지 못하는
|
||||
> **이 저장소 고유의 계약**을 본다. 범위를 넓히지 말고 아래 목록에 집중한다.
|
||||
|
||||
## 코드를 고치지 않는다
|
||||
|
||||
수정 권한 없이 **지적만** 한다. 파일·줄 위치와 근거 규칙을 함께 적어 담당 역할에 인계한다.
|
||||
고쳐야 할 것이 명백해도 직접 고치지 않는다 — 그 영역의 완료 기준(lint·test)을 건너뛰게 된다.
|
||||
|
||||
## 점검 목록
|
||||
|
||||
**1. 응답 계약** ([[response-format]])
|
||||
- 컨트롤러가 `{success,data}` 를 직접 래핑하지 않는가 (인터셉터 담당)
|
||||
- 목록 응답이 배열이 아니라 `{items, pageInfo}` 인가
|
||||
- 스트림·204·헬스체크에 `@SkipTransform()` 이 붙어 있는가
|
||||
|
||||
**2. 에러 코드 SSOT 드리프트** ([[error-codes]])
|
||||
- `error-codes.ts` 를 고쳤는데 `npm run sync:error-codes` 결과가 빠지지 않았는가
|
||||
(CI 의 `error-codes-sync` 잡이 같은 검사를 한다 — 여기서 먼저 잡는다)
|
||||
- 생성 파일(`*.generated.ts`·`*.g.dart`)을 손으로 고치지 않았는가
|
||||
- 코드 없는 실패(`BusinessException` 없이 던진 실패)가 없는가
|
||||
- 클라이언트가 `message` 로 분기하지 않는가 (`code` 로 해야 한다)
|
||||
|
||||
**3. 경계 위반**
|
||||
- 한 역할의 변경이 남의 영역 파일까지 조용히 고치지 않았는가
|
||||
- 자동 생성 파일·계약 테스트가 삭제되거나 skip 되지 않았는가
|
||||
|
||||
**4. 설정·보안** ([[security]] · [[env-structure]])
|
||||
- `.env*` 실값이 커밋에 섞이지 않았는가, `*.example` 값이 placeholder 인가
|
||||
- 새 필수 env 에 `env.validation.ts` 검증과 테스트가 함께 왔는가
|
||||
- 로그에 토큰·비밀번호·요청 본문 전체가 남지 않는가 ([[logging]])
|
||||
|
||||
**5. 커밋 위생** ([[git-convention]])
|
||||
- 메시지가 `<type>(<scope>): <한국어 제목>` 형식인가, 한 커밋에 한 변경인가
|
||||
|
||||
## 작업 순서
|
||||
|
||||
```bash
|
||||
git status --short && git diff # 무엇이 바뀌었는지부터 본다
|
||||
```
|
||||
|
||||
1. 변경 파일 목록에서 **어느 역할의 영역이 섞였는지** 먼저 확인한다.
|
||||
2. 위 목록 순서대로 본다. 목록 밖의 취향 문제는 지적하지 않는다.
|
||||
3. 지적은 **근거 규칙과 함께** 적는다. 근거를 댈 수 없으면 지적하지 않는다.
|
||||
|
||||
## 완료 기준
|
||||
|
||||
- 지적 사항마다 `파일:줄` · 무엇이 · 어느 규칙 위반인지 · 누구에게 넘기는지를 적는다.
|
||||
- 지적할 것이 없으면 "없음"이라고 명확히 적는다. 억지로 만들지 않는다.
|
||||
- [[checklist]] 2절(커밋 전 공통 점검) 통과 여부를 함께 보고한다.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: tester
|
||||
description: 테스트 담당. 변경 영역의 단위·계약 테스트 작성과 실행, 세 스택 테스트 수트 유지. 테스트가 빠졌거나 계약 테스트가 깨졌을 때 사용한다.
|
||||
tools: Read, Grep, Glob, Edit, Write, Bash, Skill
|
||||
---
|
||||
|
||||
테스트를 담당하는 팀원이다. 공통 계약은 `.claude/agents/README.md` 를 따른다.
|
||||
|
||||
## 시작 전
|
||||
|
||||
[[testing]] 규칙을 기준으로 삼는다. 스택별 실행 방법은 해당 스킬을 로드해 확인한다.
|
||||
|
||||
## 담당 범위
|
||||
|
||||
- 변경된 로직에 대한 단위 테스트 (backend `*.spec.ts` / frontend `*.spec.ts` / flutter `*_test.dart`)
|
||||
- **계약 테스트 유지** — 세 스택이 공유하는 계약은 어긋나도 컴파일 에러가 나지 않는다. 이 테스트가 유일한 안전망이다.
|
||||
|
||||
| 대상 | 위치 |
|
||||
| --- | --- |
|
||||
| 에러 코드 레지스트리 | `backend/src/common/errors/error-codes.spec.ts` |
|
||||
| 에러 응답 포맷 | `backend/src/common/filters/http-exception.filter.spec.ts` |
|
||||
| 프론트 에러 사전 | `frontend/src/composables/useApi.spec.ts` |
|
||||
| 앱 에러 사전 | `flutter/test/error_lexicon_test.dart` |
|
||||
| 응답 계약 (e2e) | `backend/test/app.e2e-spec.ts` |
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- **계약 테스트를 삭제하거나 skip 하지 않는다.** 깨졌다면 테스트가 아니라 **구현이 계약을 벗어난 것**이다.
|
||||
구현을 고칠 권한이 없으면 무엇이 어떻게 어긋났는지 적어 해당 개발 역할에 인계한다.
|
||||
- **테스트를 통과시키기 위한 구현 수정** — 테스트 외 파일을 고쳐야 한다면 인계한다.
|
||||
- 프레임워크 기본 동작(라우팅·DI·ORM 쿼리 빌더)이나 스타일 값 테스트 ([[testing]])
|
||||
|
||||
## 작업 순서
|
||||
|
||||
1. 무엇이 바뀌었는지 먼저 본다 (`git diff`). 바뀐 로직에만 테스트를 붙인다.
|
||||
2. 순수 함수 → 서비스/비즈니스 로직 → 에러 코드 분기 순으로 우선한다.
|
||||
3. 외부 네트워크·시간·랜덤은 모킹해 **결정적**으로 만든다.
|
||||
4. 테스트 제목은 한국어로 "무엇을 검증하는지" 적는다.
|
||||
|
||||
## 완료 기준 (실행하고 결과를 보고한다)
|
||||
|
||||
```bash
|
||||
cd backend && npm run test
|
||||
cd frontend && npm run test:unit
|
||||
cd flutter && flutter test
|
||||
```
|
||||
|
||||
- e2e 는 DB 가 필요하다. 로컬이면 개발 스택을 띄운 뒤 컨테이너 안에서 실행한다 ([[testing]]).
|
||||
- 실행하지 못한 수트가 있으면 **어느 것을 왜 못 돌렸는지** 반드시 적는다. 통과했다고 뭉뚱그리지 않는다.
|
||||
@@ -8,12 +8,16 @@
|
||||
## 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 개발 환경 기동으로 동작 확인 ([[docker]])
|
||||
- [ ] Docker 개발 환경 기동으로 동작 확인 — backend + db ([[docker]])
|
||||
(Redis 와 프론트엔드 컨테이너는 기본 비활성이다 — 필요하면 루트 `.env` 에 `COMPOSE_PROFILES=redis,frontend`)
|
||||
- [ ] 프론트엔드 dev 서버는 **호스트에서** 기동 — `cd frontend && npm run dev` (→ <http://localhost:5173>)
|
||||
컨테이너 vite 는 바인드 마운트 때문에 첫 서빙까지 수 분이 걸려 profile 뒤로 숨겨 두었다 ([[docker]])
|
||||
|
||||
## 2. 커밋 전 공통 점검 (매 작업)
|
||||
|
||||
@@ -39,14 +43,24 @@
|
||||
- [ ] `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`)
|
||||
- [ ] 세 스택 테스트 통과 확인 (`error-codes.spec.ts` · `useApi.spec.ts` · `error_lexicon_test.dart`)
|
||||
— 계약 테스트는 **클라이언트가 실제로 참조하는 코드의 존재**와 네이밍 규약만 검사한다.
|
||||
도메인 코드를 추가했다고 테스트를 고칠 필요는 없다.
|
||||
단, 클라이언트가 그 코드로 분기한다면 해당 목록에 추가한다.
|
||||
- [ ] 생성 파일까지 함께 커밋
|
||||
(CI 의 `error-codes-sync` 잡이 `sync` 재실행 후 `git diff` 로 드리프트를 검사하므로, 빠뜨리면 PR 이 실패한다)
|
||||
|
||||
> `AUTH_002`(세션 만료)는 **클라이언트 전용** 코드로 서버 응답에는 나타나지 않는다. 자세한 내용은 [[error-codes]].
|
||||
|
||||
## 4. 공유 계약을 바꿀 때 (응답 포맷 · 페이지네이션 · API 규약)
|
||||
## 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` · 공유 타입 파일)
|
||||
@@ -55,7 +69,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 5. 기능 확장 시 따르는 순서
|
||||
## 6. 기능 확장 시 따르는 순서
|
||||
|
||||
새 기능은 만들기 전에, 해당 스킬의 **"템플릿 기본 제공 골격"** 에서 재사용할 패턴을 먼저 찾는다(같은 역할을 새로 만들지 말 것).
|
||||
|
||||
|
||||
@@ -14,6 +14,8 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{
|
||||
├─▶ 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 볼륨
|
||||
```
|
||||
@@ -26,6 +28,10 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{
|
||||
숫자 설정값은 `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).** 조용히 기본값으로 굴러가다 운영에서 터지는 것이 더 위험하다.
|
||||
@@ -33,6 +39,10 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{
|
||||
- 숫자 항목은 형식 검사 (모든 환경)
|
||||
- 운영 환경: `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 에 주입한다)
|
||||
- 문제는 하나씩이 아니라 **한 번에 모아서** 보여준다 (재기동 반복 방지)
|
||||
- 새 필수 설정을 추가하면 이 파일의 목록과 테스트도 함께 갱신한다
|
||||
|
||||
|
||||
@@ -21,7 +21,24 @@
|
||||
- 입력값은 DTO(`class-validator`) 검증을 거친 뒤 서비스 계층에 전달한다. 전역 `ValidationPipe` 의 `whitelist`/`forbidNonWhitelisted` 를 끄지 않는다
|
||||
- TypeORM ORM 쿼리 사용으로 SQL Injection 차단 (Raw 쿼리 시 파라미터 바인딩 필수)
|
||||
- 에러 응답에 스택·쿼리·내부 호스트명을 싣지 않는다 — 미정의 예외는 항상 `SYS_001` 로 수렴시킨다 ([[error-codes]])
|
||||
- 파일 업로드는 확장자·MIME·용량을 서버에서 검증하고, 업로드 경로를 실행 가능한 위치에 두지 않는다
|
||||
### 파일 업로드
|
||||
|
||||
템플릿은 `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` 등)를 파이프라인에 추가한다.
|
||||
|
||||
## 네트워크 · 인프라
|
||||
|
||||
@@ -68,10 +85,30 @@
|
||||
2. **수정이 다른 것을 깨뜨리는가** — 생태계 버전이 어긋나면 더 큰 위험
|
||||
3. 미룬다면 **언제 다시 볼지** 조건을 적어둔다
|
||||
|
||||
> **현재 유예 중인 항목**
|
||||
> - `multer` (high, DoS via deeply nested field names) — `@nestjs/platform-express` 의 전이 의존성.
|
||||
> 수정하려면 `@nestjs/platform-express@12` 가 필요한데 나머지 Nest 생태계가 v11 이라 호환이 깨진다.
|
||||
> **이 템플릿에는 파일 업로드 엔드포인트가 없어 도달 경로가 없다**(`FileInterceptor` 미사용).
|
||||
> → **파일 업로드를 구현하는 시점에 반드시 재검토**한다. Nest v12 로 일괄 업그레이드하는 것이 정석.
|
||||
> **현재 유예 중인 항목**: 없음 (`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]] 참조.
|
||||
|
||||
@@ -12,8 +12,12 @@ description: Docker Compose 기반 로컬·운영 오케스트레이션 실행/
|
||||
|
||||
## 개발 환경
|
||||
|
||||
> **개발 환경에서 프론트엔드는 컨테이너로 뜨지 않는다.** compose profile `frontend` 뒤에 숨겨져 있다.
|
||||
> vite 를 컨테이너에서 돌리면 소스가 바인드 마운트(`./frontend:/app`) 너머라 첫 서빙까지 수 분이 걸린다.
|
||||
> 프론트엔드는 호스트에서 `cd frontend && npm run dev` 로 띄운다 (아래 "프론트엔드는 호스트에서" 참조).
|
||||
|
||||
```bash
|
||||
# 코드만 수정했을 때 (의존성 변경 없음)
|
||||
# 코드만 수정했을 때 (의존성 변경 없음) — backend + db 가 뜬다
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d
|
||||
|
||||
# 의존성 변경 시에만 --build
|
||||
@@ -25,6 +29,10 @@ docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.d
|
||||
|
||||
## 운영 환경
|
||||
|
||||
> ⚠️ `.env.production` 의 `BACKEND_API_URL`·`CORS_ORIGIN` 을 **실제 도메인으로 교체**해야 한다.
|
||||
> `localhost` 나 예시 도메인(`example.com`)이 남아 있으면 백엔드가 기동에 실패한다 ([[env-structure]]).
|
||||
> 로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓰는 경우에만 `ALLOW_LOCALHOST_URL=true` 를 함께 준다.
|
||||
|
||||
```bash
|
||||
# 운영 환경 배포
|
||||
sudo docker compose --env-file .env.production up -d --build
|
||||
@@ -35,6 +43,44 @@ sudo docker compose --env-file .env.production logs -f backend
|
||||
|
||||
---
|
||||
|
||||
## 프론트엔드는 호스트에서 (개발 환경)
|
||||
|
||||
```bash
|
||||
cd frontend && npm install && npm run dev # → http://localhost:5173
|
||||
```
|
||||
|
||||
- **포트는 루트 `.env.{APP_ENV}` 가 SSOT 다** ([[env-structure]]). `vite.config.ts` 가 루트 env 를 직접 읽어
|
||||
`FRONTEND_PORT` 로 열고, `/api` 프록시 대상은 `http://localhost:${BACKEND_PORT}`(백엔드 컨테이너가
|
||||
호스트에 노출한 포트)로 잡는다. 포트를 바꿀 때 루트 env 한 줄만 고치면 된다.
|
||||
백엔드를 아예 다른 주소에 띄웠다면 `VITE_DEV_API_PROXY` 로 대상을 덮어쓴다.
|
||||
- `strictPort: true` 라 포트가 이미 사용 중이면 **다음 포트로 옮기지 않고 실패**한다.
|
||||
`CORS_ORIGIN` 과 compose 포트 매핑이 그 포트에 묶여 있어, 조용히 5174 로 옮겨가면
|
||||
API 요청이 원인 모르게 막힌다 (fail-fast).
|
||||
- 폴링 감시(`watch.usePolling`)는 **컨테이너에서만** 켜진다 (`CHOKIDAR_USEPOLLING` 로 판별).
|
||||
호스트에서는 OS 파일 감시 이벤트로 충분하며, 폴링을 켜면 기동이 느려지고 CPU 만 쓴다.
|
||||
- 의존성 설치는 호스트에서 해도 된다 — 프론트엔드 dev 는 컨테이너를 쓰지 않으므로
|
||||
lock 파일이 깨지는 문제([[nestjs]] 의 Windows 주의 항목)는 **backend 에만** 해당한다.
|
||||
단 `frontend` 프로필이나 운영 이미지를 빌드할 계획이라면 같은 주의가 적용된다.
|
||||
|
||||
### 컨테이너로 띄워야 할 때 (선택)
|
||||
|
||||
호스트에 Node 를 둘 수 없는 환경 등에서만 쓴다. 느린 것은 정상이다.
|
||||
|
||||
```bash
|
||||
# 일회성
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development --profile frontend up -d
|
||||
|
||||
# 상시 — 루트 .env.development 에 (redis 와 함께 켤 때는 frontend,redis)
|
||||
COMPOSE_PROFILES=frontend
|
||||
```
|
||||
|
||||
- 호스트 vite 와 컨테이너 vite 는 같은 호스트 포트(`FRONTEND_PORT`)를 쓴다 — **동시에 띄우지 말 것.**
|
||||
- 컨테이너 **내부** 포트는 5173 고정이다 (compose 의 `--port`·healthcheck·포트 매핑이 함께 묶여 있다).
|
||||
루트 env 는 컨테이너 안에 없으므로 `vite.config.ts` 는 기본값으로 떨어지고, compose 의 `--port` 가 이긴다.
|
||||
- 운영(`docker-compose.yml` 단독)에는 profile 이 없으므로 nginx 정적 호스팅이 그대로 동작한다.
|
||||
|
||||
---
|
||||
|
||||
## 자주 쓰는 보조 명령
|
||||
|
||||
> 개발 prefix가 길어 아래는 다음 별칭으로 줄여 표기한다.
|
||||
@@ -76,6 +122,48 @@ dc exec redis redis-cli -a <REDIS_PASSWORD>
|
||||
|
||||
---
|
||||
|
||||
## CI 러너 (별도 스택)
|
||||
|
||||
`.github/workflows/ci.yml` 을 실행하는 Gitea Actions 러너는 **앱 스택과 생명주기가 다르다.**
|
||||
앱은 개발할 때만 띄우지만 러너는 항상 켜져 있어야 하므로 `ci/` 에 별도 compose 로 분리했다.
|
||||
|
||||
```bash
|
||||
cd ci
|
||||
cp .env.example .env # 등록 토큰 입력 (커밋되지 않음)
|
||||
docker compose -f docker-compose.runner.yml --env-file .env up -d
|
||||
```
|
||||
|
||||
- 러너가 없으면 워크플로는 **"Waiting for a runner"** 로 대기만 한다.
|
||||
- `RUNNER_LABELS` 의 라벨이 워크플로의 `runs-on` 과 **일치해야** 잡을 집는다.
|
||||
- 러너는 도커 소켓에 접근하므로 사실상 호스트 관리자 권한을 갖는다 — 신뢰할 수 있는 워크플로만 실행되게 한다.
|
||||
|
||||
설치·문제 해결은 [`ci/README.md`](../../../ci/README.md) 참조.
|
||||
|
||||
---
|
||||
|
||||
## 선택적 서비스 (Redis)
|
||||
|
||||
**Redis 는 기본적으로 기동하지 않는다.** 단일 인스턴스에서는 in-memory 캐시로 충분하고,
|
||||
쓰지 않는 컨테이너는 메모리만 차지하며 혼란을 준다.
|
||||
|
||||
```bash
|
||||
# 켜기 — 루트 .env.{APP_ENV} 한 줄 수정 (이후 평소 명령 그대로)
|
||||
COMPOSE_PROFILES=redis
|
||||
# (프론트엔드 컨테이너도 함께 켤 때는 COMPOSE_PROFILES=redis,frontend)
|
||||
|
||||
# 또는 일회성
|
||||
dc --profile redis up -d
|
||||
```
|
||||
|
||||
- compose `profiles: ["redis"]` 로 숨겨져 있고, backend 의 의존성은 `required: false` 라
|
||||
Redis 가 없어도 정상 기동한다.
|
||||
- 데이터 볼륨(`${REDIS_DATA_DIR}`)과 `REDIS_*` 환경변수는 그대로 유지되므로,
|
||||
켜면 이전 데이터와 설정이 그대로 이어진다.
|
||||
- **애플리케이션 코드는 아직 Redis 를 사용하지 않는다.** 실제 연결 절차는 [[nestjs]] 참조.
|
||||
- 끝까지 쓰지 않을 프로젝트라면 compose 에서 redis 서비스와 관련 env 를 지우는 편이 낫다.
|
||||
|
||||
---
|
||||
|
||||
## 규칙
|
||||
|
||||
- **빌드 최소화**: 의존성(package.json / pubspec 등) 변경이 없으면 `--build` 없이 기동한다.
|
||||
@@ -95,6 +183,7 @@ dc exec redis redis-cli -a <REDIS_PASSWORD>
|
||||
- 정상 종료 시 컨테이너 **종료 코드는 143**(=128+SIGTERM)이다. 오류가 아니라 시그널에 의한 정상 종료다.
|
||||
- ⚠️ dev 오버라이드는 PID 1 이 `npm` 이라 SIGTERM 이 앱까지 전달되지 않는다(개발 편의상 허용).
|
||||
graceful shutdown 동작 확인은 **운영 이미지**(`--target production`)로 해야 한다.
|
||||
이때 로컬 주소를 쓰게 되므로 `ALLOW_LOCALHOST_URL=true` 로 공개 주소 검사를 건너뛴다 ([[env-structure]]).
|
||||
- **컨테이너 비-root 구동**: 모든 서비스 컨테이너는 비-root 로 실행한다 — **dev 오버라이드도 포함** ([[security]] 참조).
|
||||
- 프론트엔드 운영 컨테이너는 `nginx-unprivileged` 라 **8080** 포트를 쓴다 (`expose`·healthcheck·nginx.conf 가 모두 8080).
|
||||
- 프론트엔드 dev 컨테이너는 vite 를 **5173** 으로 띄운다 (비-root 는 80 포트 바인드 불가).
|
||||
|
||||
@@ -250,6 +250,8 @@ await storage.deleteAll();
|
||||
- [ ] **구조 보완 시**: `app.dart` 분리, `core/{constants,theme,storage}` 생성. 공통 위젯은 `lib/shared/widgets/` 에 둔다(이동 완료).
|
||||
- [ ] **권장 패키지**: 모델(`freezed`/`json_serializable`)·라우팅(`go_router`) 도입 시 `pubspec.yaml` 추가 후 `flutter pub get`.
|
||||
- [ ] **analyze/test**: 커밋 전 `flutter analyze` (Warning 0) + `flutter test` 통과.
|
||||
CI(`ci-flutter.yml`)는 **flutter/ 가 바뀐 커밋에서만** 자동 실행된다 (SDK 다운로드가 느려 분리).
|
||||
다른 시점에 검사가 필요하면 Actions 탭의 "Run workflow" 로 수동 실행한다.
|
||||
- [ ] **린트로 강제되는 항목**: `dynamic` 호출·`print`·`const` 누락·await 누락·작은따옴표·import 정렬 (`analysis_options.yaml`).
|
||||
- [ ] **env**: `flutter/.env.example` → `.env` 복사 후 `API_URL` 설정 (Android 에뮬레이터는 `10.0.2.2`).
|
||||
`.env` 는 `pubspec.yaml` 의 asset 이라 **없으면 `flutter analyze` 가 경고**한다.
|
||||
|
||||
@@ -28,15 +28,19 @@ description: NestJS 백엔드(backend/) 개발 규칙 — 컨트롤러/서비스
|
||||
| Rate Limiting | `app.module.ts` 의 `ThrottlerGuard`(APP_GUARD) | 초과 시 429 → `REQ_001`. 루트 `.env` 의 `THROTTLE_*` 로 조정 |
|
||||
| 로깅 | `shared/logger/winston.config.ts` | `console.log` 대신 사용 ([[logging]]) |
|
||||
| env 검증 | `shared/config/env.validation.ts` | 잘못된 설정이면 **기동 실패**(fail-fast) ([[env-structure]]) |
|
||||
| DB 설정 | `shared/config/database.config.ts` | 앱·CLI 공유 SSOT. `synchronize` 기본 off |
|
||||
| 마이그레이션 | `src/data-source.ts` + `src/migrations/` | `npm run migration:*` (아래 "DB 마이그레이션") |
|
||||
| Graceful shutdown | `main.ts` 의 `enableShutdownHooks()` + `shared/logger/shutdown.logger.ts` | SIGTERM 시 요청/커넥션 정리 후 종료 |
|
||||
| 예제 모듈(참조용) | `modules/user`(DTO+Swagger+페이지네이션) | 새 모듈 패턴 참고. in-memory 데모 저장소 |
|
||||
| 파일 업로드 | `modules/upload` | 로컬 디스크 저장 + 형식·크기 검증 + 안전한 파일명 생성 ([[security]]) |
|
||||
| 헬스체크 | `modules/health` | `@SkipThrottle`+`@SkipTransform` — 기계가 읽는 엔드포인트 패턴 ([[response-format]]) |
|
||||
| 순수 유틸 | `shared/utils/` | 순수 함수 분리 위치 |
|
||||
|
||||
> **확장 시 따르는 규칙** (기능이 필요해지면 규칙대로 구현):
|
||||
> - **인증(JWT)**: `@nestjs/jwt`·`@nestjs/passport` 설치 → `common/guards/` 생성 → AUTH_001/AUTH_003 흐름 검증
|
||||
> - **DB 영속화**: TypeORM 엔티티/리포지토리 추가 (예제의 in-memory 저장 대체).
|
||||
> `app.module.ts` 는 이미 `TypeOrmModule.forRootAsync` 로 연결되어 있으며 **운영에서는 `synchronize:false` + 마이그레이션**이 강제된다 — 이 설정을 바꾸지 말 것
|
||||
> `app.module.ts` 는 이미 `TypeOrmModule.forRootAsync` 로 연결되어 있다.
|
||||
> 스키마는 **마이그레이션으로 관리**하며 `synchronize` 는 기본 off 다 (아래 "DB 마이그레이션" 참조)
|
||||
> - **도메인 에러 코드**: `error-codes.ts` 의 `DOMAIN_ERROR_CODES` 에 등록 → `npm run sync:error-codes`
|
||||
> - `common/{guards,pipes}/` 는 해당 관심사 등장 시 생성 (아래 "모듈 구조"는 목표 구조)
|
||||
|
||||
@@ -199,16 +203,17 @@ SwaggerModule.setup('api-docs', app, document);
|
||||
## 성능 & 최신 트렌드 추가 규칙
|
||||
|
||||
- **캐싱**: `@nestjs/cache-manager` 가 전역 등록되어 있으나 **현재 저장소는 in-memory** 다.
|
||||
> 📐 **Redis 는 확장 지점이다.** compose 에 redis 컨테이너가 뜨고 `REDIS_HOST`/`REDIS_PORT`/`REDIS_PASSWORD` 가
|
||||
> 백엔드로 주입되지만, **아직 이를 사용하는 코드는 없다.** 단일 인스턴스에서는 in-memory 로 충분하다.
|
||||
> 📐 **Redis 는 확장 지점이다.** compose 에서 **기본 비활성**(profile)이며 애플리케이션도 사용하지 않는다.
|
||||
> 단일 인스턴스에서는 in-memory 로 충분하다.
|
||||
>
|
||||
> Redis 가 실제로 필요해지는 시점(다중 인스턴스 운영, 세션·캐시 공유, 분산 락)에 연결한다:
|
||||
> 0. 컨테이너 활성화 — 루트 `.env` 에 `COMPOSE_PROFILES=redis` ([[docker]])
|
||||
> 1. Redis store 패키지 설치 (**컨테이너 안에서** — 위 의존성 주의 항목 참조)
|
||||
> 2. `app.module.ts` 의 `CacheModule.register` 를 `registerAsync` + Redis store 로 교체
|
||||
> 3. `modules/health` 에 Redis 인디케이터 추가 (지금은 DB 만 검사한다)
|
||||
> 4. 연결 실패 시 앱이 죽지 않도록 폴백 전략을 정한다
|
||||
>
|
||||
> 끝까지 쓰지 않을 프로젝트라면 compose 에서 redis 서비스를 빼는 편이 낫다 — 쓰지 않는 컨테이너는 혼란만 준다.
|
||||
> 끝까지 쓰지 않을 프로젝트라면 compose 에서 redis 서비스와 관련 env 를 지우는 편이 낫다.
|
||||
- **Rate Limiting**: `@nestjs/throttler` 로 일원화 (`app.module.ts` 의 `APP_GUARD`). 초과 시 429 → `REQ_001`.
|
||||
라우트 단위 조정은 `@Throttle({ default: { ttl, limit } })`, 제외는 `@SkipThrottle()` (헬스체크에 적용되어 있다).
|
||||
**rate limiter 를 중복으로 추가하지 말 것** ([[security]])
|
||||
@@ -224,6 +229,53 @@ SwaggerModule.setup('api-docs', app, document);
|
||||
|
||||
---
|
||||
|
||||
## DB 마이그레이션
|
||||
|
||||
스키마 변경은 **마이그레이션으로 관리**한다. `synchronize` 는 기본적으로 꺼져 있다.
|
||||
|
||||
> **왜 끄는가**: `synchronize: true` 는 엔티티를 DB 에 자동 반영하므로 개발 DB 가 항상 최신 상태가 된다.
|
||||
> 그러면 `migration:generate` 가 "변경 없음"만 내놓고, 그 코드를 운영에 배포하면
|
||||
> (운영은 synchronize 가 꺼져 있고 실행할 마이그레이션도 없어) **테이블이 만들어지지 않는다.**
|
||||
> 개발과 운영이 같은 경로를 쓰도록 마이그레이션으로 통일한다.
|
||||
|
||||
### 엔티티 추가/변경 절차
|
||||
|
||||
```bash
|
||||
# 0) 개발 스택이 떠 있어야 한다 (DB 접속 정보는 루트 .env → compose 주입)
|
||||
# dc = docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development
|
||||
|
||||
# 1) 엔티티 작성 (src/**/*.entity.ts)
|
||||
|
||||
# 2) 마이그레이션 생성 — 엔티티와 실제 DB 스키마의 차이를 자동으로 계산한다
|
||||
dc exec backend npm run migration:generate -- src/migrations/AddUser
|
||||
|
||||
# 3) 생성된 SQL 을 반드시 눈으로 확인한다 (의도치 않은 DROP 이 없는지)
|
||||
# 4) 적용
|
||||
dc exec backend npm run migration:run
|
||||
|
||||
# 5) 엔티티와 마이그레이션 파일을 함께 커밋
|
||||
```
|
||||
|
||||
| 명령 | 용도 |
|
||||
| --- | --- |
|
||||
| `npm run migration:generate -- src/migrations/<이름>` | 엔티티 ↔ DB 차이로 자동 생성 |
|
||||
| `npm run migration:create -- src/migrations/<이름>` | 빈 마이그레이션 (데이터 이관 등 수동 SQL) |
|
||||
| `npm run migration:run` | 미적용 마이그레이션 실행 |
|
||||
| `npm run migration:revert` | 마지막 마이그레이션 롤백 |
|
||||
| `npm run migration:show` | 적용 상태 확인 |
|
||||
|
||||
규칙:
|
||||
|
||||
- **명령은 컨테이너 안에서 실행**한다. DB 접속 정보가 compose 로 주입되기 때문이다.
|
||||
- 생성된 SQL 을 **검토 없이 커밋하지 않는다.** 컬럼 rename 이 DROP+ADD 로 생성되면 데이터가 날아간다.
|
||||
- 마이그레이션 파일은 **한번 커밋되면 수정하지 않는다.** 잘못됐으면 새 마이그레이션으로 고친다.
|
||||
- 운영 배포 시 `migrationsRun: true` 로 자동 실행된다 — 별도 명령이 필요 없다.
|
||||
- 빠른 실험이 필요하면 개발 환경에서만 `DB_SYNCHRONIZE=true` 로 임시 활성화하되,
|
||||
**커밋 전에는 끄고 마이그레이션을 생성**한다. 운영에서는 이 값과 무관하게 항상 비활성화된다.
|
||||
- 접속 설정은 `shared/config/database.config.ts` 하나만 수정한다 (앱과 CLI 가 공유).
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 의존성 추가/제거 (Windows 개발 환경 주의)
|
||||
|
||||
**Windows 에서 `npm install` / `npm uninstall` 을 실행하면 lock 파일에서 Linux 전용 optional 의존성이 잘려나간다.**
|
||||
@@ -245,6 +297,8 @@ dc exec backend npm uninstall <패키지>
|
||||
- 변경 후 호스트의 `package.json`·`package-lock.json` 이 갱신됐는지 확인하고 **함께 커밋**한다 (bind mount 라 호스트에 반영된다).
|
||||
- 호스트에서 실행해버렸다면 `git checkout backend/package-lock.json` 으로 되돌린 뒤 위 방법으로 다시 한다.
|
||||
- 커밋 전 `docker compose ... build backend` 로 `npm ci` 가 통과하는지 확인한다. CI 도 같은 검사를 한다.
|
||||
- 전이 의존성의 취약점이 `npm audit fix` 로 안 풀리면 `package.json` 의 `overrides` 를 쓴다 ([[security]]).
|
||||
현재 `multer: ^2.4.0` 이 걸려 있다 — `@nestjs/platform-express` 를 v12 로 올릴 때 제거한다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -27,6 +27,13 @@ description: Vue 3 프론트엔드(frontend/) 개발 규칙 — Composition API
|
||||
| 공통 컴포넌트 예제 | `src/components/BaseButton.vue` | 재사용 컴포넌트 기준 패턴(타입 Props/Emits·scoped·rem·a11y) |
|
||||
| 라우터 | `src/router/index.ts` | lazy import + `auth.store` 연동 `requiresAuth` 가드 |
|
||||
| env 타입 선언 | `frontend/env.d.ts` | `VITE_API_BASE_URL` |
|
||||
| dev API 프록시 | `vite.config.ts` 의 `server.proxy` | `/api` → 백엔드. 없으면 vite 가 SPA 폴백으로 **HTML 을 200 으로** 돌려줘 조용히 실패한다 |
|
||||
| dev 서버 포트 | `vite.config.ts` 의 `loadEnv` | 루트 `.env.{mode}` 의 `FRONTEND_PORT`/`BACKEND_PORT` 를 읽는다. `strictPort` 로 포트 충돌 시 fail-fast ([[env-structure]]) |
|
||||
|
||||
> **개발 서버는 호스트에서 띄운다** — `cd frontend && npm run dev` (→ `http://localhost:${FRONTEND_PORT}`).
|
||||
> 컨테이너 vite 는 바인드 마운트 때문에 첫 서빙에 수 분이 걸려 compose profile `frontend` 뒤로 숨겼다 ([[docker]]).
|
||||
> 백엔드·DB 는 평소대로 컨테이너로 띄우고, `/api` 는 vite 프록시가 `localhost:${BACKEND_PORT}` 로 넘긴다.
|
||||
> 두 포트 모두 `vite.config.ts` 가 **루트 `.env.{mode}` 에서 직접 읽는다** — 프론트 쪽에 포트를 중복 작성하지 않는다.
|
||||
|
||||
> **확장 시 따르는 규칙:**
|
||||
> - **로그인 연동**: 실제 `/auth/login` 엔드포인트 연결 → 성공 시 `useAuth` 가 `authStore.markAuthenticated()` 호출
|
||||
@@ -216,3 +223,8 @@ router.beforeEach((to) => {
|
||||
- [ ] **lint/test**: 커밋 전 `npm run lint` (`--max-warnings 0`) + `npm run type-check` + `npm run test:unit` 통과. 자동 수정은 `npm run lint:fix`.
|
||||
- [ ] **린트로 강제되는 항목**: Options API·인라인 스타일·`console`·`any` 는 빌드가 실패한다.
|
||||
- [ ] **env**: `VITE_API_BASE_URL` 은 빌드 시 루트 `BACKEND_API_URL` 에서 주입된다 — `frontend/.env` 에 별도 작성 불필요.
|
||||
- [ ] **dev 서버**: 프론트엔드는 호스트에서 `npm run dev` 로 띄운다 (컨테이너는 `--profile frontend` 선택, [[docker]]).
|
||||
- [ ] **포트**: `vite.config.ts` 에 포트를 새로 하드코딩하지 않는다 — 루트 `.env.{mode}` 의 `FRONTEND_PORT`/`BACKEND_PORT` 가 SSOT ([[env-structure]]).
|
||||
- [ ] **dev 에서 API 가 안 될 때**: 응답이 JSON 이 아니라 HTML 이면 vite 프록시(`server.proxy`) 문제다.
|
||||
`baseURL` 이 `/api` 상대경로라 프록시가 없으면 index.html 이 200 으로 돌아온다.
|
||||
백엔드 컨테이너가 떠 있는지(`docker compose ... ps`), 프록시 대상 포트가 맞는지 확인한다.
|
||||
|
||||
@@ -9,6 +9,10 @@ BACKEND_DIR=backend
|
||||
|
||||
# ==========================================
|
||||
# 포트 설정
|
||||
#
|
||||
# 컨테이너 포트 매핑뿐 아니라 **호스트에서 띄우는 vite dev 서버**도 이 값을 따른다.
|
||||
# (frontend/vite.config.ts 가 이 파일을 직접 읽는다 — FRONTEND_PORT 로 열고
|
||||
# /api 프록시는 BACKEND_PORT 로 보낸다. 포트를 바꾸면 CORS_ORIGIN 도 함께 고칠 것)
|
||||
# ==========================================
|
||||
FRONTEND_PORT=5173
|
||||
BACKEND_PORT=3000
|
||||
@@ -44,3 +48,34 @@ CORS_ORIGIN=http://localhost:5173
|
||||
# ==========================================
|
||||
THROTTLE_TTL_MS=60000
|
||||
THROTTLE_LIMIT=100
|
||||
|
||||
# ==========================================
|
||||
# DB 스키마 동기화 (개발 전용, 기본 false)
|
||||
# true 로 켜면 엔티티 변경이 DB 에 자동 반영되어 빠르게 실험할 수 있지만,
|
||||
# 그 상태에서는 migration:generate 가 "변경 없음"만 내놓는다.
|
||||
# 운영으로 갈 코드라면 꺼둔 채 마이그레이션으로 관리할 것.
|
||||
# (운영 환경에서는 이 값과 무관하게 항상 비활성화된다)
|
||||
# ==========================================
|
||||
DB_SYNCHRONIZE=false
|
||||
|
||||
# ==========================================
|
||||
# 선택적 서비스 (Compose profiles)
|
||||
#
|
||||
# 기본값(비어 있음) = redis 와 frontend 컨테이너를 기동하지 않는다.
|
||||
#
|
||||
# redis 캐시·세션 공유가 필요해질 때 → COMPOSE_PROFILES=redis
|
||||
# frontend vite 를 컨테이너로 띄워야 할 때 → COMPOSE_PROFILES=frontend
|
||||
# 둘 다 → COMPOSE_PROFILES=redis,frontend
|
||||
#
|
||||
# 일회성으로 켜려면: docker compose --profile redis ... up -d
|
||||
#
|
||||
# ⚠️ 개발 환경의 프론트엔드는 호스트에서 띄우는 것이 기본이다 (`cd frontend && npm run dev`).
|
||||
# 컨테이너 vite 는 바인드 마운트 때문에 첫 서빙까지 수 분이 걸린다.
|
||||
# ==========================================
|
||||
COMPOSE_PROFILES=
|
||||
|
||||
# ==========================================
|
||||
# 파일 업로드 (로컬 디스크)
|
||||
# ==========================================
|
||||
UPLOAD_DATA_DIR=./data/uploads
|
||||
UPLOAD_MAX_SIZE_MB=5
|
||||
|
||||
+38
-2
@@ -34,9 +34,20 @@ REDIS_DATA_DIR=./data/redis
|
||||
|
||||
# ==========================================
|
||||
# API 경로 설정
|
||||
#
|
||||
# ⚠️ 운영에서는 **반드시 실제 공개 도메인**으로 교체한다.
|
||||
# - BACKEND_API_URL : 브라우저가 호출할 API 주소 (프론트엔드 번들에 그대로 박힌다)
|
||||
# - CORS_ORIGIN : 백엔드가 허용할 오리진 (scheme+host[+port], 여러 개면 콤마 구분)
|
||||
#
|
||||
# 아래 example.com 이나 localhost 가 남아 있으면 **백엔드가 기동에 실패한다**
|
||||
# (backend/src/shared/config/env.validation.ts — fail-fast).
|
||||
# 기동은 되는데 브라우저만 조용히 실패하는 상황을 막기 위한 검사다.
|
||||
#
|
||||
# 로컬에서 운영 이미지를 검증하느라 일부러 localhost 를 쓰는 경우에만
|
||||
# ALLOW_LOCALHOST_URL=true 로 이 검사를 건너뛴다. 실제 배포에는 설정하지 않는다.
|
||||
# ==========================================
|
||||
BACKEND_API_URL=http://localhost:3000/api
|
||||
CORS_ORIGIN=http://localhost:5173
|
||||
BACKEND_API_URL=https://api.example.com/api
|
||||
CORS_ORIGIN=https://app.example.com
|
||||
|
||||
# ==========================================
|
||||
# Rate Limiting (API 남용 방지)
|
||||
@@ -44,3 +55,28 @@ CORS_ORIGIN=http://localhost:5173
|
||||
# ==========================================
|
||||
THROTTLE_TTL_MS=60000
|
||||
THROTTLE_LIMIT=100
|
||||
|
||||
# ==========================================
|
||||
# DB 스키마 동기화 (개발 전용, 기본 false)
|
||||
# true 로 켜면 엔티티 변경이 DB 에 자동 반영되어 빠르게 실험할 수 있지만,
|
||||
# 그 상태에서는 migration:generate 가 "변경 없음"만 내놓는다.
|
||||
# 운영으로 갈 코드라면 꺼둔 채 마이그레이션으로 관리할 것.
|
||||
# (운영 환경에서는 이 값과 무관하게 항상 비활성화된다)
|
||||
# ==========================================
|
||||
DB_SYNCHRONIZE=false
|
||||
|
||||
# ==========================================
|
||||
# 선택적 서비스 (Compose profiles)
|
||||
#
|
||||
# 기본값(비어 있음) = redis 를 기동하지 않는다.
|
||||
# 캐시·세션 공유가 필요해지면 아래를 redis 로 바꾸면 컨테이너가 함께 뜬다.
|
||||
# COMPOSE_PROFILES=redis
|
||||
# 일회성으로 켜려면: docker compose --profile redis ... up -d
|
||||
# ==========================================
|
||||
COMPOSE_PROFILES=
|
||||
|
||||
# ==========================================
|
||||
# 파일 업로드 (로컬 디스크)
|
||||
# ==========================================
|
||||
UPLOAD_DATA_DIR=./data/uploads
|
||||
UPLOAD_MAX_SIZE_MB=5
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
name: CI (Flutter)
|
||||
|
||||
# Flutter 는 기본 CI 에서 분리되어 있다.
|
||||
#
|
||||
# 이유: SDK 다운로드로 매 실행마다 수 분이 걸리는데,
|
||||
# backend/frontend 만 고친 커밋에서는 검사할 것이 없다.
|
||||
#
|
||||
# 언제 도는가:
|
||||
# - flutter/ 아래 파일이 바뀐 푸시·PR (= 실제로 Flutter 를 쓸 때 자동으로)
|
||||
# - Actions 탭의 "Run workflow" 버튼으로 수동 실행
|
||||
#
|
||||
# 모바일 앱을 아예 쓰지 않는 프로젝트라면 이 파일을 지우면 된다.
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'flutter/**'
|
||||
- '.github/workflows/ci-flutter.yml'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'flutter/**'
|
||||
- '.github/workflows/ci-flutter.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
flutter:
|
||||
name: Flutter (analyze · test)
|
||||
runs-on: ubuntu-latest
|
||||
# 멈춘 잡이 러너를 무한 점유하지 않도록 상한을 둔다
|
||||
timeout-minutes: 25
|
||||
defaults:
|
||||
run:
|
||||
working-directory: flutter
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: subosito/flutter-action@v2
|
||||
with:
|
||||
channel: stable
|
||||
cache: true
|
||||
|
||||
# .env 는 pubspec 의 asset 이라 없으면 analyze 가 경고를 낸다
|
||||
- name: Prepare .env
|
||||
run: cp .env.example .env
|
||||
|
||||
- run: flutter pub get
|
||||
|
||||
- name: Analyze
|
||||
run: flutter analyze
|
||||
|
||||
- name: Test
|
||||
run: flutter test
|
||||
+15
-30
@@ -14,10 +14,18 @@ jobs:
|
||||
backend:
|
||||
name: Backend (lint · test · e2e · build)
|
||||
runs-on: ubuntu-latest
|
||||
# 멈춘 잡이 러너를 무한 점유하지 않도록 상한을 둔다
|
||||
timeout-minutes: 20
|
||||
defaults:
|
||||
run:
|
||||
working-directory: backend
|
||||
# e2e 는 응답 계약을 실제 HTTP 로 검증하므로 DB 가 필요하다
|
||||
# e2e 는 응답 계약을 실제 HTTP 로 검증하므로 DB 가 필요하다.
|
||||
#
|
||||
# ⚠️ 호스트 포트 매핑(ports)을 두지 않는다.
|
||||
# Gitea Actions 러너는 잡을 **컨테이너로** 실행하고 서비스와 같은 네트워크에 붙여준다.
|
||||
# 따라서 서비스 이름(postgres)으로 바로 접근할 수 있고, 호스트 포트는 필요 없다.
|
||||
# 오히려 개발 DB 가 이미 5432 를 쓰고 있으면 충돌해 잡 전체가 시작조차 못 한다.
|
||||
# (GitHub Actions 는 잡이 VM 위에서 직접 돌아 localhost + ports 를 쓰는 점이 다르다)
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
@@ -25,8 +33,6 @@ jobs:
|
||||
POSTGRES_USER: ci_user
|
||||
POSTGRES_PASSWORD: ci_password
|
||||
POSTGRES_DB: ci_db
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd "pg_isready -U ci_user -d ci_db"
|
||||
--health-interval 10s
|
||||
@@ -55,7 +61,8 @@ jobs:
|
||||
run: npm run test:e2e
|
||||
env:
|
||||
NODE_ENV: test
|
||||
DB_HOST: localhost
|
||||
# 서비스 컨테이너의 네트워크 별칭 (localhost 는 잡 컨테이너 자신을 가리킨다)
|
||||
DB_HOST: postgres
|
||||
DB_PORT: 5432
|
||||
DB_USER: ci_user
|
||||
DB_PASSWORD: ci_password
|
||||
@@ -67,6 +74,8 @@ jobs:
|
||||
frontend:
|
||||
name: Frontend (lint · type-check · test)
|
||||
runs-on: ubuntu-latest
|
||||
# 멈춘 잡이 러너를 무한 점유하지 않도록 상한을 둔다
|
||||
timeout-minutes: 15
|
||||
defaults:
|
||||
run:
|
||||
working-directory: frontend
|
||||
@@ -90,35 +99,11 @@ jobs:
|
||||
- name: Test
|
||||
run: npm run test:unit -- --run
|
||||
|
||||
flutter:
|
||||
name: Flutter (analyze · test)
|
||||
runs-on: ubuntu-latest
|
||||
defaults:
|
||||
run:
|
||||
working-directory: flutter
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: subosito/flutter-action@v2
|
||||
with:
|
||||
channel: stable
|
||||
cache: true
|
||||
|
||||
# .env 는 pubspec 의 asset 이라 없으면 analyze 가 경고를 낸다
|
||||
- name: Prepare .env
|
||||
run: cp .env.example .env
|
||||
|
||||
- run: flutter pub get
|
||||
|
||||
- name: Analyze
|
||||
run: flutter analyze
|
||||
|
||||
- name: Test
|
||||
run: flutter test
|
||||
|
||||
error-codes-sync:
|
||||
name: 에러 코드 SSOT 동기화 검사
|
||||
runs-on: ubuntu-latest
|
||||
# 멈춘 잡이 러너를 무한 점유하지 않도록 상한을 둔다
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
|
||||
@@ -15,6 +15,11 @@
|
||||
!/data/.gitkeep
|
||||
/db-data/
|
||||
/redis-data/
|
||||
# CI 러너 등록 정보
|
||||
ci/runner-data/
|
||||
# 업로드 파일 (로컬 저장) — 코드가 아니다
|
||||
/data/uploads/
|
||||
backend/uploads/
|
||||
|
||||
# ==========================================
|
||||
# 의존성/빌드 산출물
|
||||
|
||||
@@ -15,6 +15,8 @@
|
||||
> - `.claude/rules/` — 세 플랫폼 공통 규칙 (코딩·응답 포맷·에러 코드·API 설계·로깅·커밋·보안·환경변수·테스트)
|
||||
> 새 규칙 파일을 추가하면 **반드시 아래 `@` import 목록에도 등록**한다(등록하지 않으면 로드되지 않는다).
|
||||
> - `.claude/skills/` — 도메인별 개발 규칙 (스킬). 슬래시 명령(`/nestjs` 등) 또는 해당 디렉터리 작업 시 자동 적용
|
||||
> - `.claude/agents/` — 역할별 규칙 (에이전트 팀원). 역할을 지정해 호출할 때 적용
|
||||
> **`@` import 하지 않는다** — 규칙이 아니라 호출 시점에 로드되는 역할 정의다 (아래 목록 참조)
|
||||
> - `.claude/settings.json` — Claude Code 권한·환경 설정
|
||||
|
||||
---
|
||||
@@ -40,3 +42,29 @@
|
||||
- 프론트엔드(Vue 3): @.claude/skills/vue3/SKILL.md
|
||||
- 모바일(Flutter): @.claude/skills/flutter/SKILL.md
|
||||
- 실행/배포(Docker): @.claude/skills/docker/SKILL.md
|
||||
|
||||
---
|
||||
|
||||
## 역할별 규칙 (에이전트 팀원)
|
||||
|
||||
세 층의 역할 분담은 다음과 같다. **규칙은 한 곳에만 적는다** — 역할 파일은 규칙을 참조만 한다.
|
||||
|
||||
```
|
||||
.claude/rules/ 무엇을 지키는가 — 전원 공통 (위 @import 목록)
|
||||
.claude/skills/ 어떻게 만드는가 — 스택별
|
||||
.claude/agents/ 누가 맡는가 — 역할별
|
||||
```
|
||||
|
||||
| 역할 | 파일 | 코드 수정 |
|
||||
| --- | --- | --- |
|
||||
| 백엔드 개발 | `.claude/agents/backend-dev.md` | O |
|
||||
| 프론트엔드 개발 | `.claude/agents/frontend-dev.md` | O |
|
||||
| 모바일 개발 | `.claude/agents/mobile-dev.md` | O |
|
||||
| 테스터 | `.claude/agents/tester.md` | O (테스트 한정) |
|
||||
| 리뷰어 | `.claude/agents/reviewer.md` | X |
|
||||
| 인프라/릴리스 | `.claude/agents/release-ops.md` | O (인프라 한정) |
|
||||
| 사용자 관점 | `.claude/agents/persona-user.md` | X |
|
||||
| 관리자 관점 | `.claude/agents/persona-admin.md` | X |
|
||||
|
||||
공통 계약(경계·인계 형식·완료 기준)은 [`.claude/agents/README.md`](.claude/agents/README.md) 참조.
|
||||
역할을 지정하지 않으면 평소대로 동작한다 — 모든 작업을 역할로 나눌 필요는 없다.
|
||||
|
||||
@@ -11,7 +11,7 @@ NestJS(백엔드) · Vue 3(웹) · Flutter(모바일)를 하나의 저장소에
|
||||
| `frontend/` | Vue 3 + Vite | 웹 프론트엔드 | 5173 |
|
||||
| `flutter/` | Flutter + Riverpod | 모바일 앱 | - |
|
||||
| `db` | PostgreSQL | 데이터베이스 | 5432 |
|
||||
| `redis` | Redis | 캐시 / 세션 | 6379 |
|
||||
| `redis` | Redis | 캐시 / 세션 (**기본 비활성**) | 6379 |
|
||||
|
||||
## 사전 요구사항
|
||||
|
||||
@@ -28,11 +28,14 @@ cp .env.development.example .env.development # ← 여기
|
||||
cp backend/.env.development.example backend/.env.development # (존재 필요: JWT 등 고유 시크릿)
|
||||
# frontend 는 compose 가 빌드 시 값을 주입하므로 자체 env 복사 불필요
|
||||
|
||||
# 2) 개발 환경 기동 (코드만 수정 시)
|
||||
# 2) 백엔드 스택 기동 (backend + db)
|
||||
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
|
||||
|
||||
# 4) 프론트엔드는 호스트에서 직접 띄운다 (컨테이너보다 수십 배 빠르다)
|
||||
cd frontend && npm install && npm run dev
|
||||
```
|
||||
|
||||
기동 후:
|
||||
@@ -41,6 +44,31 @@ docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.d
|
||||
- API: <http://localhost:3000/api>
|
||||
- Swagger 문서: <http://localhost:3000/api-docs>
|
||||
|
||||
> **개발 환경에서 프론트엔드는 컨테이너로 뜨지 않습니다.**
|
||||
> vite 를 컨테이너에서 돌리면 소스가 Windows 바인드 마운트 너머에 있어 첫 서빙까지 수 분이 걸립니다.
|
||||
> 호스트에서 `npm run dev` 로 띄우면 1~2초이고, `/api` 요청은 vite 프록시가 백엔드 컨테이너로 넘깁니다.
|
||||
> 컨테이너로 띄워야 한다면 `--profile frontend` 를 붙이세요 (아래 "프론트엔드 실행 방식" 참조).
|
||||
> 운영(`docker-compose.yml` 단독)은 그대로 nginx 정적 호스팅으로 동작합니다.
|
||||
|
||||
> Redis 는 기본적으로 뜨지 않습니다. 필요해지면 루트 `.env.{env}` 에 `COMPOSE_PROFILES=redis` 를 설정하세요.
|
||||
|
||||
### 프론트엔드 실행 방식
|
||||
|
||||
| 방식 | 명령 | 첫 서빙 | 용도 |
|
||||
| --- | --- | --- | --- |
|
||||
| **호스트 vite (개발 기본)** | `cd frontend && npm run dev` | 1~2초 (최초 의존성 사전번들 10초 내외) | 일상 개발 |
|
||||
| 컨테이너 vite (선택) | `docker compose ... --profile frontend up -d` | 수 분 (Windows 바인드 마운트) | 호스트에 Node 를 둘 수 없을 때 |
|
||||
| nginx 정적 (운영) | `docker compose --env-file .env.production up -d --build` | - | 배포 |
|
||||
|
||||
> 컨테이너 방식을 상시 사용하려면 루트 `.env.development` 에 `COMPOSE_PROFILES=frontend` 를 넣습니다.
|
||||
> (redis 와 함께 켤 때는 `COMPOSE_PROFILES=frontend,redis`)
|
||||
> 호스트 vite 와 컨테이너 vite 는 같은 호스트 포트를 쓰므로 **동시에 띄우지 마세요.**
|
||||
|
||||
> **포트는 루트 `.env.{env}` 를 따릅니다.** 호스트에서 띄우는 vite 도 `FRONTEND_PORT` 로 열리고,
|
||||
> `/api` 프록시 대상은 `BACKEND_PORT` 에서 나옵니다 — `vite.config.ts` 가 루트 env 를 직접 읽습니다.
|
||||
> 포트가 이미 사용 중이면 조용히 다른 포트로 옮기지 않고 **실패**합니다
|
||||
> (`CORS_ORIGIN` 과 compose 포트 매핑이 그 값에 묶여 있어, 말없이 옮겨가면 원인 모르게 어긋납니다).
|
||||
|
||||
전체 실행/배포 명령어는 [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md) 참조.
|
||||
|
||||
## 모바일 앱 실행 (Flutter)
|
||||
@@ -101,17 +129,25 @@ backend/src/common/errors/error-codes.ts ← 여기만 수정
|
||||
|
||||
## 로컬 개발 (Docker 없이)
|
||||
|
||||
DB 는 컨테이너로 띄우고 앱만 호스트에서 실행하는 방식이 가장 간단합니다.
|
||||
|
||||
```bash
|
||||
# backend
|
||||
# 1) DB 만 컨테이너로 기동 (127.0.0.1:5432 로 노출된다)
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d db
|
||||
|
||||
# 2) backend — DB_HOST 기본값이 localhost 라 그대로 붙는다
|
||||
cd backend && npm ci && npm run start:dev
|
||||
|
||||
# frontend
|
||||
# 3) frontend — vite dev 서버가 /api 를 localhost:3000 으로 프록시한다 (개발 기본 방식)
|
||||
cd frontend && npm ci && npm run dev
|
||||
|
||||
# flutter
|
||||
# 4) flutter
|
||||
cd flutter && flutter pub get && flutter run
|
||||
```
|
||||
|
||||
> 프론트엔드의 API 요청은 `/api` 상대경로로 나가고 vite dev 프록시가 백엔드로 넘깁니다.
|
||||
> 백엔드를 다른 주소에서 띄웠다면 `VITE_DEV_API_PROXY` 로 대상을 바꾸세요.
|
||||
|
||||
### 커밋 전 검사
|
||||
|
||||
```bash
|
||||
@@ -142,6 +178,7 @@ lint 는 `--max-warnings 0` 이라 경고 하나만 있어도 실패합니다.
|
||||
| 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) |
|
||||
| 역할 분담 | [`.claude/agents/README.md`](./.claude/agents/README.md) |
|
||||
|
||||
## 디렉터리 구조
|
||||
|
||||
@@ -156,8 +193,10 @@ lint 는 `--max-warnings 0` 이라 경고 하나만 있어도 실패합니다.
|
||||
├── .github/
|
||||
│ ├── workflows/ci.yml # lint·test·build + 에러 코드 동기화 검사
|
||||
│ └── pull_request_template.md
|
||||
├── ci/ # CI 러너 (Gitea Actions) — 앱 스택과 분리
|
||||
└── .claude/
|
||||
├── settings.json # Claude Code 권한·환경 설정
|
||||
├── rules/ # 공통 규칙 (코딩·응답 포맷·에러 코드·API 설계·로깅·보안·환경변수·테스트)
|
||||
└── skills/ # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)
|
||||
├── skills/ # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)
|
||||
└── agents/ # 역할별 규칙 (개발 3종·테스터·리뷰어·인프라·사용자/관리자 관점)
|
||||
```
|
||||
|
||||
Generated
+132
-28
@@ -40,6 +40,7 @@
|
||||
"@swc/core": "^1.15.24",
|
||||
"@types/express": "^5.0.0",
|
||||
"@types/jest": "^30.0.0",
|
||||
"@types/multer": "^2.2.0",
|
||||
"@types/node": "^22.10.7",
|
||||
"@types/supertest": "^6.0.2",
|
||||
"chokidar": "^5.0.0",
|
||||
@@ -176,6 +177,24 @@
|
||||
"url": "https://github.com/sponsors/epoberezkin"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics-cli/node_modules/chokidar": {
|
||||
"version": "4.0.3",
|
||||
"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
|
||||
"integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"readdirp": "^4.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 14.16.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics-cli/node_modules/json-schema-traverse": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
|
||||
@@ -183,6 +202,22 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics-cli/node_modules/readdirp": {
|
||||
"version": "4.1.2",
|
||||
"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
|
||||
"integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">= 14.18.0"
|
||||
},
|
||||
"funding": {
|
||||
"type": "individual",
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics-cli/node_modules/rxjs": {
|
||||
"version": "7.8.1",
|
||||
"resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
|
||||
@@ -248,6 +283,24 @@
|
||||
"url": "https://github.com/sponsors/epoberezkin"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics/node_modules/chokidar": {
|
||||
"version": "4.0.3",
|
||||
"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
|
||||
"integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"readdirp": "^4.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 14.16.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics/node_modules/json-schema-traverse": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
|
||||
@@ -255,6 +308,22 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics/node_modules/readdirp": {
|
||||
"version": "4.1.2",
|
||||
"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
|
||||
"integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">= 14.18.0"
|
||||
},
|
||||
"funding": {
|
||||
"type": "individual",
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@angular-devkit/schematics/node_modules/rxjs": {
|
||||
"version": "7.8.1",
|
||||
"resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
|
||||
@@ -3023,6 +3092,24 @@
|
||||
"url": "https://github.com/sponsors/epoberezkin"
|
||||
}
|
||||
},
|
||||
"node_modules/@nestjs/schematics/node_modules/chokidar": {
|
||||
"version": "4.0.3",
|
||||
"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
|
||||
"integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"readdirp": "^4.0.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">= 14.16.0"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@nestjs/schematics/node_modules/json-schema-traverse": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
|
||||
@@ -3030,6 +3117,22 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@nestjs/schematics/node_modules/readdirp": {
|
||||
"version": "4.1.2",
|
||||
"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
|
||||
"integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"optional": true,
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">= 14.18.0"
|
||||
},
|
||||
"funding": {
|
||||
"type": "individual",
|
||||
"url": "https://paulmillr.com/funding/"
|
||||
}
|
||||
},
|
||||
"node_modules/@nestjs/schematics/node_modules/rxjs": {
|
||||
"version": "7.8.1",
|
||||
"resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz",
|
||||
@@ -3431,7 +3534,7 @@
|
||||
"version": "1.15.41",
|
||||
"resolved": "https://registry.npmjs.org/@swc/core/-/core-1.15.41.tgz",
|
||||
"integrity": "sha512-03nQq/082QRJJiOvp3FGbgxTGyyxMxohPTjhk/W9bD2J0tk4ukITI7goOhOO2WbaHn/lsPmo/zf8+DIXhwpgYQ==",
|
||||
"devOptional": true,
|
||||
"dev": true,
|
||||
"hasInstallScript": true,
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {
|
||||
@@ -3475,6 +3578,7 @@
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3491,6 +3595,7 @@
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3507,6 +3612,7 @@
|
||||
"cpu": [
|
||||
"arm"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3523,6 +3629,7 @@
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3539,6 +3646,7 @@
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3555,6 +3663,7 @@
|
||||
"cpu": [
|
||||
"ppc64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3571,6 +3680,7 @@
|
||||
"cpu": [
|
||||
"s390x"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3587,6 +3697,7 @@
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3603,6 +3714,7 @@
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3619,6 +3731,7 @@
|
||||
"cpu": [
|
||||
"arm64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3635,6 +3748,7 @@
|
||||
"cpu": [
|
||||
"ia32"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3651,6 +3765,7 @@
|
||||
"cpu": [
|
||||
"x64"
|
||||
],
|
||||
"dev": true,
|
||||
"license": "Apache-2.0 AND MIT",
|
||||
"optional": true,
|
||||
"os": [
|
||||
@@ -3664,14 +3779,14 @@
|
||||
"version": "0.1.3",
|
||||
"resolved": "https://registry.npmjs.org/@swc/counter/-/counter-0.1.3.tgz",
|
||||
"integrity": "sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==",
|
||||
"devOptional": true,
|
||||
"dev": true,
|
||||
"license": "Apache-2.0"
|
||||
},
|
||||
"node_modules/@swc/types": {
|
||||
"version": "0.1.26",
|
||||
"resolved": "https://registry.npmjs.org/@swc/types/-/types-0.1.26.tgz",
|
||||
"integrity": "sha512-lyMwd7WGgG79RS7EERZV3T8wMdmPq3xwyg+1nmAM64kIhx5yl+juO2PYIHb7vTiPgPCj8LYjsNV2T5wiQHUEaw==",
|
||||
"devOptional": true,
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {
|
||||
"@swc/counter": "^0.1.3"
|
||||
@@ -3938,6 +4053,16 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/multer": {
|
||||
"version": "2.2.0",
|
||||
"resolved": "https://registry.npmjs.org/@types/multer/-/multer-2.2.0.tgz",
|
||||
"integrity": "sha512-3U1troeqGV8Ntp7Q3klwf4zr23VEoqYVocYXaswm9+8z3O9UHDYAqLxjJ/h550iRADTjKdOdhhasXw6gD6kYtg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/express": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "22.19.21",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.21.tgz",
|
||||
@@ -5817,6 +5942,7 @@
|
||||
"version": "1.1.2",
|
||||
"resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz",
|
||||
"integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/busboy": {
|
||||
@@ -6338,21 +6464,6 @@
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/concat-stream": {
|
||||
"version": "2.0.0",
|
||||
"resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-2.0.0.tgz",
|
||||
"integrity": "sha512-MWufYdFw53ccGjCA+Ol7XJYpAlW6/prSMzuPOTRnJGcGzuhLn4Scrz7qf6o8bROZ514ltazcIFJZevcfbo0x7A==",
|
||||
"engines": [
|
||||
"node >= 6.0"
|
||||
],
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"buffer-from": "^1.0.0",
|
||||
"inherits": "^2.0.3",
|
||||
"readable-stream": "^3.0.2",
|
||||
"typedarray": "^0.0.6"
|
||||
}
|
||||
},
|
||||
"node_modules/content-disposition": {
|
||||
"version": "2.0.1",
|
||||
"resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-2.0.1.tgz",
|
||||
@@ -9942,14 +10053,13 @@
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/multer": {
|
||||
"version": "2.2.0",
|
||||
"resolved": "https://registry.npmjs.org/multer/-/multer-2.2.0.tgz",
|
||||
"integrity": "sha512-6rdyFg2kLrMh9Jee7/BMPuV9lEAd7lLW2YUpF9/YxR7njyoUwwQ0ZPh3TaIY50Sw6vlyD2HW3wGOkTS4P79xrQ==",
|
||||
"version": "2.4.0",
|
||||
"resolved": "https://registry.npmjs.org/multer/-/multer-2.4.0.tgz",
|
||||
"integrity": "sha512-7dqa0ZcFfzbefdTuIkzOSMvZWC0J7FLqBOjJUZvDCXShIURWKxAyTT1wHhnE5q19c7jOJf43IYYKjBmZVZmvhg==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"append-field": "^1.0.0",
|
||||
"busboy": "^1.6.0",
|
||||
"concat-stream": "^2.0.0",
|
||||
"type-is": "^1.6.18"
|
||||
},
|
||||
"engines": {
|
||||
@@ -12508,12 +12618,6 @@
|
||||
"node": ">= 0.4"
|
||||
}
|
||||
},
|
||||
"node_modules/typedarray": {
|
||||
"version": "0.0.6",
|
||||
"resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz",
|
||||
"integrity": "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/typeorm": {
|
||||
"version": "0.3.31",
|
||||
"resolved": "https://registry.npmjs.org/typeorm/-/typeorm-0.3.31.tgz",
|
||||
|
||||
+11
-1
@@ -19,7 +19,13 @@
|
||||
"test:cov": "jest --coverage",
|
||||
"test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
|
||||
"test:e2e": "jest --config ./test/jest-e2e.json",
|
||||
"sync:error-codes": "ts-node -P tsconfig.json scripts/sync-error-codes.ts"
|
||||
"sync:error-codes": "ts-node -P tsconfig.json scripts/sync-error-codes.ts",
|
||||
"typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/data-source.ts",
|
||||
"migration:generate": "npm run typeorm -- migration:generate",
|
||||
"migration:create": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js migration:create",
|
||||
"migration:run": "npm run typeorm -- migration:run",
|
||||
"migration:revert": "npm run typeorm -- migration:revert",
|
||||
"migration:show": "npm run typeorm -- migration:show"
|
||||
},
|
||||
"dependencies": {
|
||||
"@nestjs/cache-manager": "^3.0.1",
|
||||
@@ -53,6 +59,7 @@
|
||||
"@swc/core": "^1.15.24",
|
||||
"@types/express": "^5.0.0",
|
||||
"@types/jest": "^30.0.0",
|
||||
"@types/multer": "^2.2.0",
|
||||
"@types/node": "^22.10.7",
|
||||
"@types/supertest": "^6.0.2",
|
||||
"chokidar": "^5.0.0",
|
||||
@@ -71,6 +78,9 @@
|
||||
"typescript": "^5.7.3",
|
||||
"typescript-eslint": "^8.20.0"
|
||||
},
|
||||
"overrides": {
|
||||
"multer": "^2.4.0"
|
||||
},
|
||||
"jest": {
|
||||
"moduleFileExtensions": [
|
||||
"js",
|
||||
|
||||
@@ -7,12 +7,28 @@
|
||||
* 생성 파일은 직접 수정하지 말 것 — 레지스트리를 고치고 다시 실행한다.
|
||||
* CI 는 이 스크립트를 실행한 뒤 git diff 로 드리프트를 검사한다.
|
||||
*/
|
||||
import { mkdirSync, writeFileSync } from 'fs';
|
||||
import { existsSync, mkdirSync, writeFileSync } from 'fs';
|
||||
import { dirname, resolve } from 'path';
|
||||
|
||||
import { ERROR_CODES } from '../src/common/errors/error-codes';
|
||||
|
||||
const REPO_ROOT = resolve(__dirname, '..', '..');
|
||||
|
||||
// 이 스크립트는 저장소 루트 기준으로 frontend/·flutter/ 에 파일을 쓴다.
|
||||
// 컨테이너 안에서는 backend/ 만 마운트되어 형제 디렉터리가 없으므로 실행할 수 없다.
|
||||
if (!existsSync(resolve(REPO_ROOT, 'frontend'))) {
|
||||
console.error(
|
||||
[
|
||||
'저장소 루트를 찾을 수 없습니다: ' + REPO_ROOT,
|
||||
'',
|
||||
'이 스크립트는 frontend/·flutter/ 에 사전 파일을 생성하므로',
|
||||
'저장소 전체가 보이는 곳에서 실행해야 합니다.',
|
||||
'컨테이너 안(backend/ 만 마운트됨)이 아니라 **호스트에서** 실행하세요:',
|
||||
' cd backend && npm run sync:error-codes',
|
||||
].join('\n'),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
const GENERATED_NOTICE =
|
||||
'backend/src/common/errors/error-codes.ts 에서 자동 생성된 파일입니다. 직접 수정하지 마세요.';
|
||||
|
||||
|
||||
@@ -8,8 +8,10 @@ import { APP_GUARD } from '@nestjs/core';
|
||||
|
||||
import { RequestIdMiddleware } from '@/common/middleware/request-id.middleware';
|
||||
import { HealthModule } from '@/modules/health/health.module';
|
||||
import { UploadModule } from '@/modules/upload/upload.module';
|
||||
import { UserModule } from '@/modules/user/user.module';
|
||||
import { parsePositiveInt } from '@/shared/utils/env';
|
||||
import { buildDatabaseOptions } from '@/shared/config/database.config';
|
||||
import { validateEnv } from '@/shared/config/env.validation';
|
||||
import { ShutdownLogger } from '@/shared/logger/shutdown.logger';
|
||||
|
||||
@@ -17,16 +19,6 @@ import { ShutdownLogger } from '@/shared/logger/shutdown.logger';
|
||||
const THROTTLE_DEFAULT_TTL_MS = 60_000; // 집계 구간: 60초
|
||||
const THROTTLE_DEFAULT_LIMIT = 100; // 구간당 IP별 최대 요청 수
|
||||
|
||||
// 개발 환경 DB 기본값 — compose 가 주입하는 값과 동일해야 한다.
|
||||
// 운영에서는 validateEnv 가 DB_* 를 필수로 요구하므로 이 값들이 쓰이지 않는다.
|
||||
const DEV_DB_DEFAULTS = {
|
||||
host: 'db',
|
||||
port: 5432,
|
||||
username: 'postgres',
|
||||
password: 'postgres',
|
||||
database: 'project_db',
|
||||
} as const;
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
ScheduleModule.forRoot(),
|
||||
@@ -57,34 +49,16 @@ const DEV_DB_DEFAULTS = {
|
||||
),
|
||||
},
|
||||
]),
|
||||
// DB 접속 설정은 database.config.ts 하나만 수정한다 (CLI 와 공유)
|
||||
TypeOrmModule.forRootAsync({
|
||||
useFactory: () => {
|
||||
const isProduction = process.env.NODE_ENV === 'production';
|
||||
return {
|
||||
type: 'postgres',
|
||||
// 개발 편의를 위한 기본값 — 운영 환경 필수값은 validateEnv 가 기동 전에 보장한다.
|
||||
// (약한 기본값 'password' 로 조용히 동작하던 문제를 제거)
|
||||
host: process.env.DB_HOST ?? DEV_DB_DEFAULTS.host,
|
||||
port: parsePositiveInt(process.env.DB_PORT, DEV_DB_DEFAULTS.port),
|
||||
username: process.env.DB_USER ?? DEV_DB_DEFAULTS.username,
|
||||
password: process.env.DB_PASSWORD ?? DEV_DB_DEFAULTS.password,
|
||||
database: process.env.DB_NAME ?? DEV_DB_DEFAULTS.database,
|
||||
autoLoadEntities: true,
|
||||
// 운영 환경에서는 절대 synchronize 사용 금지 (스키마 자동 변경 → 데이터 손실 위험)
|
||||
synchronize: !isProduction,
|
||||
migrationsRun: isProduction,
|
||||
logging: !isProduction,
|
||||
extra: {
|
||||
max: 100,
|
||||
connectionTimeoutMillis: 5000,
|
||||
idleTimeoutMillis: 30000,
|
||||
},
|
||||
entities: [__dirname + '/**/*.entity{.ts,.js}'],
|
||||
migrations: [__dirname + '/migrations/*{.ts,.js}'],
|
||||
};
|
||||
},
|
||||
useFactory: () => ({
|
||||
...buildDatabaseOptions(),
|
||||
// Nest 모듈에 등록된 엔티티를 자동으로 수집한다 (CLI 는 glob 경로를 사용)
|
||||
autoLoadEntities: true,
|
||||
}),
|
||||
}),
|
||||
HealthModule,
|
||||
UploadModule,
|
||||
UserModule,
|
||||
],
|
||||
providers: [
|
||||
|
||||
@@ -64,10 +64,16 @@ const COMMON_ERROR_CODES = {
|
||||
* message: '이미 가입된 이메일입니다. 다른 이메일을 사용해 주세요.',
|
||||
* },
|
||||
*/
|
||||
const DOMAIN_ERROR_CODES = {} as const satisfies Record<
|
||||
string,
|
||||
ErrorCodeDefinition
|
||||
>;
|
||||
const DOMAIN_ERROR_CODES = {
|
||||
FILE_001: {
|
||||
status: HttpStatus.BAD_REQUEST,
|
||||
message: '허용되지 않는 파일 형식입니다. 파일을 확인해 주세요.',
|
||||
},
|
||||
FILE_002: {
|
||||
status: HttpStatus.PAYLOAD_TOO_LARGE,
|
||||
message: '파일 크기가 허용 범위를 초과했습니다.',
|
||||
},
|
||||
} as const satisfies Record<string, ErrorCodeDefinition>;
|
||||
|
||||
export const ERROR_CODES = {
|
||||
...COMMON_ERROR_CODES,
|
||||
@@ -90,6 +96,8 @@ const STATUS_TO_ERROR_CODE: ReadonlyMap<number, ErrorCode> = new Map<
|
||||
[HttpStatus.BAD_REQUEST, 'VAL_001'],
|
||||
[HttpStatus.UNPROCESSABLE_ENTITY, 'VAL_001'],
|
||||
[HttpStatus.TOO_MANY_REQUESTS, 'REQ_001'],
|
||||
// multer 가 파일 크기 한도 초과 시 던지는 상태 코드
|
||||
[HttpStatus.PAYLOAD_TOO_LARGE, 'FILE_002'],
|
||||
]);
|
||||
|
||||
/** 등록된 에러 코드인지 확인한다. */
|
||||
|
||||
@@ -5,6 +5,7 @@ import {
|
||||
HttpStatus,
|
||||
Logger,
|
||||
NotFoundException,
|
||||
PayloadTooLargeException,
|
||||
} from '@nestjs/common';
|
||||
|
||||
import { HttpExceptionFilter } from './http-exception.filter';
|
||||
@@ -95,6 +96,17 @@ describe('HttpExceptionFilter', () => {
|
||||
expect(result.body.error.message).toBe(ERROR_CODES.VAL_001.message);
|
||||
});
|
||||
|
||||
it('라이브러리가 만든 영문 메시지를 사용자에게 노출하지 않는다', () => {
|
||||
// multer 는 크기 초과 시 "File too large" 라는 영문 메시지로 예외를 만든다.
|
||||
// 사용자 노출 문구는 에러 코드 사전에만 존재해야 한다.
|
||||
const result = runFilter(new PayloadTooLargeException('File too large'));
|
||||
|
||||
expect(result.status).toBe(HttpStatus.PAYLOAD_TOO_LARGE);
|
||||
expect(result.body.error.code).toBe('FILE_002');
|
||||
expect(result.body.error.message).toBe(ERROR_CODES.FILE_002.message);
|
||||
expect(JSON.stringify(result.body)).not.toContain('File too large');
|
||||
});
|
||||
|
||||
it('미정의 예외는 내부 정보 없이 SYS_001 로 수렴한다', () => {
|
||||
const result = runFilter(new Error('DB 커넥션 풀 고갈: host=10.0.0.5'));
|
||||
|
||||
|
||||
@@ -75,8 +75,9 @@ export class HttpExceptionFilter implements ExceptionFilter {
|
||||
return {
|
||||
status,
|
||||
code,
|
||||
// 내장 예외의 영문 기본 메시지는 노출하지 않고 레지스트리 문구를 사용한다.
|
||||
message: this.extractMessage(body) ?? getErrorDefinition(code).message,
|
||||
// 프레임워크/라이브러리가 만든 영문 메시지("File too large" 등)가 그대로 새어나가지 않도록
|
||||
// **항상 레지스트리 문구**를 쓴다. 사용자 노출 문구를 재정의하려면 BusinessException 을 사용한다.
|
||||
message: getErrorDefinition(code).message,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -97,18 +98,6 @@ export class HttpExceptionFilter implements ExceptionFilter {
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 직접 문자열 메시지를 지정해 던진 경우에만 사용자 문구로 채택한다.
|
||||
* (ValidationPipe 처럼 message 가 배열이면 상세 사유가 노출되므로 무시한다.)
|
||||
*/
|
||||
private extractMessage(body: unknown): string | null {
|
||||
if (typeof body === 'object' && body !== null && 'message' in body) {
|
||||
const message: unknown = body.message;
|
||||
if (typeof message === 'string') return message;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** 5xx 는 error, 4xx 는 warn 으로 남긴다. 추적을 위해 traceId 를 함께 기록한다. */
|
||||
private log(
|
||||
exception: unknown,
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
import 'reflect-metadata';
|
||||
import { DataSource } from 'typeorm';
|
||||
|
||||
import { buildDatabaseOptions } from '@/shared/config/database.config';
|
||||
|
||||
/**
|
||||
* TypeORM CLI 전용 DataSource.
|
||||
*
|
||||
* 앱 런타임은 app.module.ts 의 TypeOrmModule 을 사용하고,
|
||||
* 이 파일은 `migration:generate` / `migration:run` 같은 CLI 명령에만 쓰인다.
|
||||
* 접속 설정은 database.config.ts 를 공유하므로 두 경로가 어긋나지 않는다.
|
||||
*
|
||||
* ⚠️ DB 접속 정보(DB_*)는 루트 .env 에서 docker-compose 가 주입하므로,
|
||||
* 마이그레이션 명령은 **컨테이너 안에서** 실행해야 한다.
|
||||
* 자세한 절차는 .claude/skills/nestjs/SKILL.md 의 "DB 마이그레이션" 참조.
|
||||
*/
|
||||
export default new DataSource(buildDatabaseOptions());
|
||||
@@ -0,0 +1,22 @@
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
|
||||
/** 업로드 결과 — 저장 경로(절대경로)는 노출하지 않는다 */
|
||||
export class UploadResponseDto {
|
||||
@ApiProperty({
|
||||
description: '서버가 생성한 파일 식별자 (저장 파일명)',
|
||||
example: 'b1f0c2e4-8a3d-4c7e-9f21-0d5a6b7c8e9f.png',
|
||||
})
|
||||
fileName!: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '업로드 당시 원본 파일명',
|
||||
example: '프로필.png',
|
||||
})
|
||||
originalName!: string;
|
||||
|
||||
@ApiProperty({ description: 'MIME 타입', example: 'image/png' })
|
||||
mimeType!: string;
|
||||
|
||||
@ApiProperty({ description: '파일 크기 (바이트)', example: 20480 })
|
||||
size!: number;
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
import { allowedExtensionList, isAllowedFile } from './upload.config';
|
||||
|
||||
describe('파일 업로드 검증', () => {
|
||||
it('확장자와 MIME 이 모두 맞으면 통과한다', () => {
|
||||
expect(isAllowedFile('photo.png', 'image/png')).toBe(true);
|
||||
expect(isAllowedFile('scan.PDF', 'application/pdf')).toBe(true);
|
||||
});
|
||||
|
||||
it('허용되지 않은 MIME 은 거부한다', () => {
|
||||
expect(isAllowedFile('script.js', 'application/javascript')).toBe(false);
|
||||
expect(isAllowedFile('page.html', 'text/html')).toBe(false);
|
||||
});
|
||||
|
||||
it('MIME 은 허용이지만 확장자가 불일치하면 거부한다 (확장자 위장 방지)', () => {
|
||||
expect(isAllowedFile('payload.html', 'image/png')).toBe(false);
|
||||
expect(isAllowedFile('payload.exe', 'application/pdf')).toBe(false);
|
||||
});
|
||||
|
||||
it('확장자가 없으면 거부한다', () => {
|
||||
expect(isAllowedFile('nofile', 'image/png')).toBe(false);
|
||||
});
|
||||
|
||||
it('실행 가능한 형식은 허용 목록에 없다', () => {
|
||||
const allowed = allowedExtensionList();
|
||||
|
||||
for (const dangerous of ['.html', '.svg', '.js', '.exe', '.sh']) {
|
||||
expect(allowed).not.toContain(dangerous);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,48 @@
|
||||
import { extname } from 'path';
|
||||
|
||||
import { parsePositiveInt } from '@/shared/utils/env';
|
||||
|
||||
/**
|
||||
* 파일 업로드 정책 (로컬 디스크 기준).
|
||||
*
|
||||
* 오브젝트 스토리지(S3 등)로 전환할 때는 저장 어댑터만 교체하고
|
||||
* 검증 규칙(허용 형식·크기)은 그대로 재사용한다.
|
||||
*/
|
||||
|
||||
/** 업로드 파일 저장 디렉터리 — 컨테이너에서는 compose 볼륨이 연결된다 */
|
||||
export const UPLOAD_DIR = process.env.UPLOAD_DIR ?? './uploads';
|
||||
|
||||
const MEGABYTE = 1024 * 1024;
|
||||
|
||||
/** 파일 1개 최대 크기 (기본 5MB) */
|
||||
export const MAX_FILE_SIZE_BYTES =
|
||||
parsePositiveInt(process.env.UPLOAD_MAX_SIZE_MB, 5) * MEGABYTE;
|
||||
|
||||
/**
|
||||
* 허용 형식 — 확장자와 MIME 타입을 **둘 다** 검사한다.
|
||||
* 확장자만 보면 위장이 쉽고, MIME 만 보면 클라이언트가 보낸 값이라 신뢰할 수 없다.
|
||||
*
|
||||
* ⚠️ 실행 가능한 형식(.html, .svg, .js 등)은 넣지 말 것 —
|
||||
* 저장된 파일을 그대로 서빙할 경우 XSS 로 이어진다.
|
||||
*/
|
||||
export const ALLOWED_FILE_TYPES: ReadonlyMap<string, readonly string[]> =
|
||||
new Map([
|
||||
['image/jpeg', ['.jpg', '.jpeg']],
|
||||
['image/png', ['.png']],
|
||||
['image/webp', ['.webp']],
|
||||
['image/gif', ['.gif']],
|
||||
['application/pdf', ['.pdf']],
|
||||
]);
|
||||
|
||||
/** 허용 형식인지 검사한다 (확장자 ↔ MIME 조합이 일치해야 통과) */
|
||||
export function isAllowedFile(originalName: string, mimeType: string): boolean {
|
||||
const allowedExtensions = ALLOWED_FILE_TYPES.get(mimeType);
|
||||
if (!allowedExtensions) return false;
|
||||
|
||||
return allowedExtensions.includes(extname(originalName).toLowerCase());
|
||||
}
|
||||
|
||||
/** 사용자에게 안내할 허용 확장자 목록 */
|
||||
export function allowedExtensionList(): string {
|
||||
return [...ALLOWED_FILE_TYPES.values()].flat().join(', ');
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
import {
|
||||
Controller,
|
||||
Post,
|
||||
UploadedFile,
|
||||
UseInterceptors,
|
||||
} from '@nestjs/common';
|
||||
import { FileInterceptor } from '@nestjs/platform-express';
|
||||
import { ApiBody, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger';
|
||||
|
||||
import {
|
||||
ApiErrorResponse,
|
||||
ApiStandardResponse,
|
||||
} from '@/common/decorators/api-standard-response.decorator';
|
||||
import { BusinessException } from '@/common/errors/business.exception';
|
||||
import { UploadResponseDto } from './dto/upload-response.dto';
|
||||
import { UploadService } from './upload.service';
|
||||
|
||||
// 파일 업로드 샘플 — 새 업로드 엔드포인트는 이 패턴을 복제한다.
|
||||
// 검증(형식·크기)과 안전한 파일명 생성은 UploadModule 의 multer 설정이 담당한다.
|
||||
@ApiTags('Upload')
|
||||
@Controller('files')
|
||||
export class UploadController {
|
||||
constructor(private readonly uploadService: UploadService) {}
|
||||
|
||||
@Post()
|
||||
@UseInterceptors(FileInterceptor('file'))
|
||||
@ApiOperation({ summary: '파일 업로드 (단일)' })
|
||||
@ApiConsumes('multipart/form-data')
|
||||
@ApiBody({
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
file: { type: 'string', format: 'binary' },
|
||||
},
|
||||
required: ['file'],
|
||||
},
|
||||
})
|
||||
@ApiStandardResponse(UploadResponseDto, {
|
||||
status: 201,
|
||||
description: '업로드 성공',
|
||||
})
|
||||
@ApiErrorResponse('FILE_001', '허용되지 않는 파일 형식')
|
||||
@ApiErrorResponse('FILE_002', '파일 크기 초과')
|
||||
upload(@UploadedFile() file?: Express.Multer.File): UploadResponseDto {
|
||||
if (!file) {
|
||||
// 파일 없이 요청한 경우 — multer 는 오류를 내지 않으므로 여기서 막는다
|
||||
throw new BusinessException('VAL_001', {
|
||||
message: '업로드할 파일을 선택해 주세요.',
|
||||
});
|
||||
}
|
||||
|
||||
return this.uploadService.toResponse(file);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
import { Module } from '@nestjs/common';
|
||||
import { MulterModule } from '@nestjs/platform-express';
|
||||
import { randomUUID } from 'crypto';
|
||||
import { diskStorage } from 'multer';
|
||||
import { mkdirSync } from 'fs';
|
||||
import { extname } from 'path';
|
||||
|
||||
import { BusinessException } from '@/common/errors/business.exception';
|
||||
import {
|
||||
MAX_FILE_SIZE_BYTES,
|
||||
UPLOAD_DIR,
|
||||
isAllowedFile,
|
||||
} from './upload.config';
|
||||
import { UploadController } from './upload.controller';
|
||||
import { UploadService } from './upload.service';
|
||||
|
||||
// 저장 디렉터리는 기동 시 한 번 보장한다 (없으면 multer 가 매 요청 실패한다)
|
||||
mkdirSync(UPLOAD_DIR, { recursive: true });
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
MulterModule.register({
|
||||
storage: diskStorage({
|
||||
destination: UPLOAD_DIR,
|
||||
filename: (_req, file, callback) => {
|
||||
// ⚠️ 클라이언트가 보낸 파일명을 경로에 쓰지 않는다.
|
||||
// '../../etc/passwd' 같은 값이 그대로 들어오면 경로 탈출이 된다.
|
||||
// 서버가 생성한 UUID + 검증된 확장자만 사용한다.
|
||||
const safeExtension = extname(file.originalname).toLowerCase();
|
||||
callback(null, `${randomUUID()}${safeExtension}`);
|
||||
},
|
||||
}),
|
||||
limits: {
|
||||
fileSize: MAX_FILE_SIZE_BYTES,
|
||||
// 파일 외 필드 수를 제한해 과도한 파싱을 막는다
|
||||
files: 1,
|
||||
fields: 10,
|
||||
},
|
||||
fileFilter: (_req, file, callback) => {
|
||||
if (!isAllowedFile(file.originalname, file.mimetype)) {
|
||||
// 에러 코드와 함께 거부한다 (전역 필터가 표준 응답으로 변환)
|
||||
callback(new BusinessException('FILE_001'), false);
|
||||
return;
|
||||
}
|
||||
callback(null, true);
|
||||
},
|
||||
}),
|
||||
],
|
||||
controllers: [UploadController],
|
||||
providers: [UploadService],
|
||||
exports: [UploadService],
|
||||
})
|
||||
export class UploadModule {}
|
||||
@@ -0,0 +1,36 @@
|
||||
import { Injectable, Logger } from '@nestjs/common';
|
||||
import { unlink } from 'fs/promises';
|
||||
import { join } from 'path';
|
||||
|
||||
import { UPLOAD_DIR } from './upload.config';
|
||||
import { UploadResponseDto } from './dto/upload-response.dto';
|
||||
|
||||
// 업로드된 파일의 메타데이터를 다루는 계층.
|
||||
// 저장 자체는 multer(diskStorage)가 수행하며, 여기서는 그 결과를 정리한다.
|
||||
@Injectable()
|
||||
export class UploadService {
|
||||
private readonly logger = new Logger(UploadService.name);
|
||||
|
||||
/** multer 가 저장한 파일 정보를 응답 DTO 로 변환한다 */
|
||||
toResponse(file: Express.Multer.File): UploadResponseDto {
|
||||
this.logger.log(
|
||||
`파일 업로드 완료: ${file.filename} (${file.size} bytes, ${file.mimetype})`,
|
||||
);
|
||||
|
||||
return {
|
||||
fileName: file.filename,
|
||||
// 원본 파일명은 표시용 메타데이터일 뿐이며 경로 조립에 사용하지 않는다
|
||||
originalName: file.originalname,
|
||||
mimeType: file.mimetype,
|
||||
size: file.size,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 저장된 파일을 삭제한다.
|
||||
* 파일명은 서버가 생성한 값만 받아야 한다 — 외부 입력을 그대로 넘기면 경로 탈출 위험이 있다.
|
||||
*/
|
||||
async remove(fileName: string): Promise<void> {
|
||||
await unlink(join(UPLOAD_DIR, fileName));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
import { join } from 'path';
|
||||
import { DataSourceOptions } from 'typeorm';
|
||||
|
||||
import { parsePositiveInt } from '@/shared/utils/env';
|
||||
|
||||
/**
|
||||
* DB 접속 설정 — 앱(TypeOrmModule)과 CLI(data-source.ts)가 **같은 설정을 공유**한다.
|
||||
* 두 곳에 따로 적으면 반드시 어긋나므로 여기서만 정의한다.
|
||||
*/
|
||||
|
||||
// 개발 환경 기본값 — **호스트에서 직접 실행할 때** 기준이다.
|
||||
// docker 환경에서는 compose 가 DB_HOST=db 등을 항상 주입하므로 이 값들이 쓰이지 않고,
|
||||
// 운영에서는 validateEnv 가 DB_* 를 필수로 요구한다.
|
||||
const DEV_DB_DEFAULTS = {
|
||||
host: 'localhost',
|
||||
port: 5432,
|
||||
username: 'postgres',
|
||||
password: 'postgres',
|
||||
database: 'project_db',
|
||||
} as const;
|
||||
|
||||
/** 커넥션 풀 설정 */
|
||||
const POOL_OPTIONS = {
|
||||
max: 100,
|
||||
connectionTimeoutMillis: 5000,
|
||||
idleTimeoutMillis: 30000,
|
||||
} as const;
|
||||
|
||||
export function isProductionEnv(): boolean {
|
||||
return process.env.NODE_ENV === 'production';
|
||||
}
|
||||
|
||||
/**
|
||||
* 스키마 자동 동기화 사용 여부.
|
||||
*
|
||||
* **기본값은 false** 다. synchronize 를 켜두면 개발 DB 가 항상 최신 스키마와 일치해
|
||||
* `migration:generate` 가 "변경 없음"만 내놓는다. 그 상태로 운영에 배포하면
|
||||
* (운영은 synchronize 가 꺼져 있고 실행할 마이그레이션도 없어) 테이블이 만들어지지 않는다.
|
||||
*
|
||||
* 스키마 변경은 마이그레이션으로 관리한다 — 개발/운영이 같은 경로를 쓰게 된다.
|
||||
* 엔티티를 빠르게 실험할 때만 `DB_SYNCHRONIZE=true` 로 임시 활성화한다(개발 환경 한정).
|
||||
*/
|
||||
function shouldSynchronize(): boolean {
|
||||
// 운영에서는 어떤 값을 주더라도 절대 허용하지 않는다 (스키마 자동 변경 → 데이터 손실 위험)
|
||||
if (isProductionEnv()) return false;
|
||||
return process.env.DB_SYNCHRONIZE === 'true';
|
||||
}
|
||||
|
||||
/**
|
||||
* 엔티티·마이그레이션 파일 경로.
|
||||
* `__dirname` 기준이라 ts-node(src)와 빌드 산출물(dist) 양쪽에서 동작한다.
|
||||
*/
|
||||
function resolvePaths(baseDir: string) {
|
||||
return {
|
||||
entities: [join(baseDir, '..', '..', '**', '*.entity{.ts,.js}')],
|
||||
migrations: [join(baseDir, '..', '..', 'migrations', '*{.ts,.js}')],
|
||||
};
|
||||
}
|
||||
|
||||
export function buildDatabaseOptions(): DataSourceOptions {
|
||||
const isProduction = isProductionEnv();
|
||||
const paths = resolvePaths(__dirname);
|
||||
|
||||
return {
|
||||
type: 'postgres',
|
||||
host: process.env.DB_HOST ?? DEV_DB_DEFAULTS.host,
|
||||
port: parsePositiveInt(process.env.DB_PORT, DEV_DB_DEFAULTS.port),
|
||||
username: process.env.DB_USER ?? DEV_DB_DEFAULTS.username,
|
||||
password: process.env.DB_PASSWORD ?? DEV_DB_DEFAULTS.password,
|
||||
database: process.env.DB_NAME ?? DEV_DB_DEFAULTS.database,
|
||||
synchronize: shouldSynchronize(),
|
||||
// 운영 배포 시 미적용 마이그레이션을 자동 실행한다
|
||||
migrationsRun: isProduction,
|
||||
logging: !isProduction,
|
||||
extra: { ...POOL_OPTIONS },
|
||||
entities: paths.entities,
|
||||
migrations: paths.migrations,
|
||||
};
|
||||
}
|
||||
@@ -61,6 +61,55 @@ describe('validateEnv', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('공개 주소에 로컬 주소가 남아 있으면 실패한다', () => {
|
||||
expect(() =>
|
||||
validateEnv(prod({ CORS_ORIGIN: 'http://localhost:5173' })),
|
||||
).toThrow(/CORS_ORIGIN 가 운영에서 쓸 수 없는 주소입니다/);
|
||||
|
||||
expect(() =>
|
||||
validateEnv(prod({ BACKEND_API_URL: 'http://127.0.0.1:3000/api' })),
|
||||
).toThrow(/BACKEND_API_URL 가 운영에서 쓸 수 없는 주소입니다/);
|
||||
});
|
||||
|
||||
it('예시 파일의 example.com 이 그대로면 실패한다', () => {
|
||||
expect(() =>
|
||||
validateEnv(prod({ CORS_ORIGIN: 'https://app.example.com' })),
|
||||
).toThrow(/CORS_ORIGIN 가 운영에서 쓸 수 없는 주소입니다/);
|
||||
});
|
||||
|
||||
it('실제 도메인이면 통과한다', () => {
|
||||
expect(() =>
|
||||
validateEnv(
|
||||
prod({
|
||||
CORS_ORIGIN: 'https://app.myservice.io',
|
||||
BACKEND_API_URL: 'https://api.myservice.io/api',
|
||||
}),
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('ALLOW_LOCALHOST_URL=true 면 공개 주소 검사를 건너뛴다 (운영 이미지 로컬 검증용)', () => {
|
||||
expect(() =>
|
||||
validateEnv(
|
||||
prod({
|
||||
CORS_ORIGIN: 'http://localhost:5173',
|
||||
BACKEND_API_URL: 'http://localhost:3000/api',
|
||||
ALLOW_LOCALHOST_URL: 'true',
|
||||
}),
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('공개 주소 검사는 운영 환경에서만 동작한다', () => {
|
||||
expect(() =>
|
||||
validateEnv({
|
||||
NODE_ENV: 'development',
|
||||
CORS_ORIGIN: 'http://localhost:5173',
|
||||
BACKEND_API_URL: 'http://localhost:3000/api',
|
||||
}),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it('문제가 여러 개면 한 번에 모두 보여준다', () => {
|
||||
const partial = omit(prod(), 'DB_HOST', 'DB_NAME');
|
||||
|
||||
|
||||
@@ -33,6 +33,29 @@ const NO_PLACEHOLDER_IN_PRODUCTION = [
|
||||
'JWT_SECRET',
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* 운영에서 **공개 주소**여야 하는 키.
|
||||
* 로컬 주소가 남은 채 배포되면 서버는 정상 기동하지만
|
||||
* 브라우저가 API 에 닿지 못하거나 CORS 화이트리스트가 실제 도메인을 막아 **조용히** 실패한다.
|
||||
*/
|
||||
const PUBLIC_URL_IN_PRODUCTION = ['CORS_ORIGIN', 'BACKEND_API_URL'] as const;
|
||||
|
||||
/** 공개 주소로 쓸 수 없는 값 — 로컬 주소와 예시 파일의 예시 도메인 */
|
||||
const NON_PUBLIC_URL_PATTERNS = [
|
||||
/localhost/i,
|
||||
/127\.0\.0\.1/,
|
||||
/\[::1\]/,
|
||||
/0\.0\.0\.0/,
|
||||
/example\.com/i,
|
||||
];
|
||||
|
||||
/**
|
||||
* 위 공개 주소 검사를 건너뛰는 탈출구.
|
||||
* 로컬에서 **운영 이미지를 검증**할 때만 쓴다 (예: graceful shutdown 확인 — .claude/skills/docker/SKILL.md).
|
||||
* 실제 배포에서는 절대 설정하지 않는다.
|
||||
*/
|
||||
const ALLOW_LOCALHOST_URL_KEY = 'ALLOW_LOCALHOST_URL';
|
||||
|
||||
function readString(
|
||||
config: Record<string, unknown>,
|
||||
key: string,
|
||||
@@ -47,6 +70,10 @@ function looksLikePlaceholder(value: string): boolean {
|
||||
return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(value));
|
||||
}
|
||||
|
||||
function looksNonPublic(value: string): boolean {
|
||||
return NON_PUBLIC_URL_PATTERNS.some((pattern) => pattern.test(value));
|
||||
}
|
||||
|
||||
/**
|
||||
* 환경변수를 검증한다. 문제가 있으면 **모든 문제를 모아** 예외를 던진다.
|
||||
* (하나씩 고쳐가며 재기동하는 낭비를 막기 위해 한 번에 보여준다)
|
||||
@@ -85,6 +112,22 @@ export function validateEnv(
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// 4. 공개 주소가 로컬 주소·예시 도메인으로 남은 채 배포되는 것을 막는다
|
||||
const allowLocalhostUrl =
|
||||
readString(config, ALLOW_LOCALHOST_URL_KEY) === 'true';
|
||||
|
||||
if (!allowLocalhostUrl) {
|
||||
for (const key of PUBLIC_URL_IN_PRODUCTION) {
|
||||
const value = readString(config, key);
|
||||
if (value !== undefined && looksNonPublic(value)) {
|
||||
errors.push(
|
||||
`${key} 가 운영에서 쓸 수 없는 주소입니다. 실제 도메인으로 교체해 주세요. (현재 값: "${value}")` +
|
||||
` — 로컬에서 운영 이미지를 검증하는 중이라면 ${ALLOW_LOCALHOST_URL_KEY}=true`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (errors.length > 0) {
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# ==========================================
|
||||
# Gitea Actions 러너 설정
|
||||
#
|
||||
# 사용법: cp .env.example .env 후 토큰을 채운다.
|
||||
# ⚠️ .env 는 커밋되지 않는다 (루트 .gitignore). 토큰을 이 예시 파일에 적지 말 것.
|
||||
# ==========================================
|
||||
|
||||
# Gitea 인스턴스 주소 (끝에 / 없이)
|
||||
GITEA_INSTANCE_URL=https://git.wandergo.net
|
||||
|
||||
# 등록 토큰 — 저장소 Settings → Actions → Runners → Create new Runner 에서 발급
|
||||
# (여러 저장소에서 공용으로 쓰려면 관리자 화면의 인스턴스 레벨 토큰을 사용)
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN=
|
||||
|
||||
# 러너 식별 이름 — 여러 대를 띄운다면 구분되게 짓는다
|
||||
RUNNER_NAME=gitea-runner
|
||||
|
||||
# 라벨: <워크플로의 runs-on>:docker://<잡을 실행할 이미지>
|
||||
# ci.yml 이 ubuntu-latest 를 쓰므로 그대로 두면 된다.
|
||||
RUNNER_LABELS=ubuntu-latest:docker://gitea/runner-images:ubuntu-latest
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
# CI 러너 설정
|
||||
|
||||
`.github/workflows/ci.yml` 을 실제로 실행하는 Gitea Actions 러너 설정입니다.
|
||||
**러너가 없으면 워크플로는 "Waiting for a runner" 상태로 대기만 합니다.**
|
||||
|
||||
## 어디에 띄울 것인가
|
||||
|
||||
| 위치 | 장점 | 단점 |
|
||||
| --- | --- | --- |
|
||||
| **Gitea 서버** (권장) | 항상 켜져 있어 CI 가 늘 동작 | 서버에 Docker 필요 |
|
||||
| 개발 PC | 바로 시작 가능 | PC 가 꺼지면 CI 도 멈춤 |
|
||||
|
||||
CI 의 목적이 "내가 없어도 검사되는 것"이므로 서버 쪽을 권장합니다.
|
||||
|
||||
## 설치
|
||||
|
||||
```bash
|
||||
# 1) 저장소 Settings → Actions → Runners → Create new Runner 에서 토큰 발급
|
||||
# 2) 설정 파일 준비
|
||||
cd ci
|
||||
cp .env.example .env # 편집기로 열어 GITEA_RUNNER_REGISTRATION_TOKEN 채우기
|
||||
|
||||
# 3) 기동
|
||||
docker compose -f docker-compose.runner.yml --env-file .env up -d
|
||||
|
||||
# 4) 등록 확인
|
||||
docker compose -f docker-compose.runner.yml --env-file .env logs -f runner
|
||||
# "Runner registered successfully" 가 보이면 성공
|
||||
```
|
||||
|
||||
저장소 **Settings → Actions → Runners** 에서 러너가 **Idle** 로 표시되면 준비 완료입니다.
|
||||
이후 푸시하면 Actions 탭에서 실행이 시작됩니다.
|
||||
|
||||
## 잘 안 될 때
|
||||
|
||||
| 증상 | 원인 | 해결 |
|
||||
| --- | --- | --- |
|
||||
| 잡이 계속 대기 중 | 라벨 불일치 | `RUNNER_LABELS` 의 `ubuntu-latest` 가 워크플로 `runs-on` 과 같은지 확인 |
|
||||
| `uses:` 액션 다운로드 실패 | 서버에서 github.com 접근 불가 | 방화벽 확인. 폐쇄망이면 액션 미러 필요 |
|
||||
| 등록 실패 (401/404) | 토큰 만료·오타, URL 끝 `/` | 토큰 재발급, `GITEA_INSTANCE_URL` 확인 |
|
||||
| 잡 시작 직후 실패 | 도커 소켓 마운트 누락 | `/var/run/docker.sock` 마운트 확인 (Windows 는 `//var/run/docker.sock`) |
|
||||
| **모든 스텝이 한꺼번에 실패**(checkout 포함) | 서비스 컨테이너가 뜨지 못함 | 아래 "서비스 컨테이너" 참고 |
|
||||
|
||||
## 서비스 컨테이너 주의 (GitHub Actions 와 다른 점)
|
||||
|
||||
Gitea 러너는 잡을 **컨테이너로** 실행하고 서비스와 같은 네트워크에 붙인다.
|
||||
GitHub Actions 는 잡이 VM 위에서 직접 돌기 때문에 관례가 다르다.
|
||||
|
||||
| | GitHub Actions | Gitea act_runner |
|
||||
| --- | --- | --- |
|
||||
| 서비스 접근 주소 | `localhost` + `ports` 매핑 | **서비스 이름** (`postgres:5432`) |
|
||||
| `ports:` 필요 여부 | 필요 | **불필요 — 오히려 해롭다** |
|
||||
|
||||
`ports: - 5432:5432` 를 두면 호스트 포트를 점유하려 하는데,
|
||||
개발 DB 가 이미 그 포트를 쓰고 있으면 **잡이 시작조차 못 하고 모든 스텝이 failure 로 표시된다.**
|
||||
(스텝이 실패한 게 아니라 잡 준비 단계에서 죽은 것이다)
|
||||
|
||||
`ci.yml` 의 backend 잡은 이 규칙에 맞춰 `ports` 없이 `DB_HOST: postgres` 를 쓴다.
|
||||
|
||||
## 리소스 참고
|
||||
|
||||
워크플로는 두 개로 나뉘어 있습니다.
|
||||
|
||||
**`ci.yml`** — 모든 푸시·PR 에서 실행
|
||||
|
||||
- `backend` — postgres 서비스 컨테이너를 띄워 단위 테스트와 e2e 를 실행
|
||||
- `frontend` — lint·type-check·테스트
|
||||
- `error-codes-sync` — 에러 코드 생성 파일 드리프트 검사
|
||||
|
||||
**`ci-flutter.yml`** — **기본적으로 돌지 않는다**
|
||||
|
||||
Flutter 는 SDK 다운로드로 매 실행 수 분이 걸리는데, backend/frontend 만 고친 커밋에서는
|
||||
검사할 것이 없다. 그래서 다음 경우에만 실행된다.
|
||||
|
||||
- `flutter/` 아래 파일이 바뀐 푸시·PR — **실제로 Flutter 를 쓰기 시작하면 자동으로 동작한다**
|
||||
- Actions 탭의 **Run workflow** 버튼으로 수동 실행
|
||||
|
||||
모바일 앱을 쓰지 않는 프로젝트라면 `ci-flutter.yml` 을 지우면 된다.
|
||||
|
||||
> 러너는 기본적으로 잡을 **하나씩** 처리한다. 전체 시간을 줄이려면 러너를 여러 개 띄우거나
|
||||
> `act_runner` 설정에서 동시 실행 수를 늘린다.
|
||||
|
||||
## 잡이 멈출 때
|
||||
|
||||
컨테이너 환경에서 잡이 간헐적으로 멈추는 경우가 있다 (CPU 0%, 네트워크 정지 상태로 진행 없음).
|
||||
러너가 하나뿐이면 **멈춘 잡 하나가 이후 모든 잡을 굶긴다.**
|
||||
|
||||
그래서 모든 잡에 `timeout-minutes` 를 둔다. 상한에 걸리면 강제 종료되고 다음 잡으로 넘어간다.
|
||||
새 잡을 추가할 때도 반드시 상한을 지정할 것.
|
||||
|
||||
멈춘 잡을 즉시 해제하려면 해당 컨테이너를 중지하면 된다 (러너가 실패로 처리하고 다음 잡을 집는다).
|
||||
|
||||
```bash
|
||||
docker ps --format "{{.Names}}" | grep GITEA-ACTIONS # 실행 중인 잡 컨테이너
|
||||
docker stop <컨테이너명>
|
||||
```
|
||||
|
||||
## 주의
|
||||
|
||||
- **토큰은 `ci/.env` 에만** 둡니다. 이 파일은 루트 `.gitignore` 로 커밋되지 않습니다.
|
||||
- `runner-data/` 에 등록 정보가 저장됩니다. 지우면 토큰으로 재등록해야 합니다.
|
||||
- 러너는 도커 소켓에 접근하므로 **호스트에 대한 사실상의 관리자 권한**을 갖습니다.
|
||||
신뢰할 수 있는 저장소의 워크플로만 실행되도록 하세요 (공개 저장소의 PR 실행 정책 확인).
|
||||
@@ -0,0 +1,26 @@
|
||||
# Gitea Actions 러너 — CI 를 실제로 실행하는 주체
|
||||
#
|
||||
# 이 파일은 애플리케이션 스택(루트 docker-compose.yml)과 **생명주기가 다르다.**
|
||||
# 앱은 개발할 때만 띄우지만 러너는 항상 켜져 있어야 CI 가 동작한다.
|
||||
#
|
||||
# 사용법은 ci/README.md 참조.
|
||||
|
||||
services:
|
||||
runner:
|
||||
image: gitea/act_runner:latest
|
||||
container_name: ${RUNNER_NAME:-gitea-runner}
|
||||
restart: always
|
||||
environment:
|
||||
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL}
|
||||
# ⚠️ 등록 토큰 — ci/.env 에만 두고 절대 커밋하지 않는다
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_REGISTRATION_TOKEN}
|
||||
GITEA_RUNNER_NAME: ${RUNNER_NAME:-gitea-runner}
|
||||
# ⚠️ 워크플로의 runs-on 과 일치해야 잡을 집는다.
|
||||
# .github/workflows/ci.yml 은 모든 잡이 ubuntu-latest 다.
|
||||
GITEA_RUNNER_LABELS: ${RUNNER_LABELS:-ubuntu-latest:docker://gitea/runner-images:ubuntu-latest}
|
||||
volumes:
|
||||
# 잡을 컨테이너로 띄우므로 도커 소켓이 필요하다.
|
||||
# (Windows Docker Desktop 에서 Git Bash 를 쓰면 경로 변환 때문에 //var/run/... 로 적어야 할 수 있다)
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
# 등록 정보를 보존한다 — 지우면 토큰으로 재등록해야 한다
|
||||
- ./runner-data:/data
|
||||
+22
-1
@@ -1,5 +1,20 @@
|
||||
services:
|
||||
# ----------------------------------------
|
||||
# frontend — dev 에서는 기본 기동하지 않는다 (profile 로 숨김)
|
||||
#
|
||||
# vite 를 컨테이너에서 돌리면 소스가 Windows 바인드 마운트(./frontend:/app) 너머에 있어
|
||||
# 수천 개 파일을 매 요청마다 가상 파일시스템으로 읽는다. 여기에 폴링 감시까지 겹쳐
|
||||
# 첫 서빙까지 수 분이 걸린다. 호스트에서 직접 띄우면 같은 작업이 1~2초다.
|
||||
#
|
||||
# cd frontend && npm install && npm run dev # → http://localhost:5173
|
||||
#
|
||||
# vite dev 프록시가 /api 를 localhost:${BACKEND_PORT} 로 넘기므로 백엔드는 컨테이너 그대로 쓴다.
|
||||
# 그래도 컨테이너로 띄워야 한다면 (호스트에 Node 를 깔 수 없는 환경 등):
|
||||
# docker compose ... --profile frontend up -d
|
||||
# 또는 루트 .env.development 에 COMPOSE_PROFILES=frontend
|
||||
# ----------------------------------------
|
||||
frontend:
|
||||
profiles: ["frontend"]
|
||||
# dev에서는 Docker Desktop 시작 시 자동 실행 방지 (수동 up 때만 실행)
|
||||
restart: "no"
|
||||
build:
|
||||
@@ -12,8 +27,12 @@ services:
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:5173/ || exit 1"]
|
||||
environment:
|
||||
# 바인드 마운트 너머의 변경은 inotify 가 잡지 못하므로 컨테이너에서만 폴링을 켠다
|
||||
# (vite.config.ts 가 이 값을 보고 watch.usePolling 을 결정한다 — 호스트 실행 시엔 꺼진다)
|
||||
- CHOKIDAR_USEPOLLING=true
|
||||
- WATCHPACK_POLLING=true
|
||||
# vite dev 서버가 /api 요청을 백엔드 컨테이너로 프록시한다 (vite.config.ts)
|
||||
- VITE_DEV_API_PROXY=http://backend:${BACKEND_PORT}
|
||||
volumes:
|
||||
- ./${FRONTEND_DIR}:/app
|
||||
- /app/node_modules
|
||||
@@ -36,6 +55,8 @@ services:
|
||||
volumes:
|
||||
- ./${BACKEND_DIR}:/app
|
||||
- /app/node_modules
|
||||
# base 의 업로드 볼륨을 소스 바인드 마운트 위에 다시 얹는다
|
||||
- ${UPLOAD_DATA_DIR:-./data/uploads}:/app/uploads
|
||||
# dev에서는 리버스 프록시 미사용 — base의 networks 목록을 덮어씀
|
||||
networks: !override
|
||||
- app-network
|
||||
@@ -56,4 +77,4 @@ services:
|
||||
|
||||
# base의 proxy 외부 네트워크 의존을 dev에서 제거
|
||||
networks:
|
||||
proxy: !reset null
|
||||
proxy: !reset null
|
||||
|
||||
+21
-3
@@ -55,16 +55,27 @@ services:
|
||||
- PORT=${BACKEND_PORT}
|
||||
- WEBSOCKET_PORT=${WEBSOCKET_PORT}
|
||||
- CORS_ORIGIN=${CORS_ORIGIN}
|
||||
- THROTTLE_TTL_MS=${THROTTLE_TTL_MS}
|
||||
- THROTTLE_LIMIT=${THROTTLE_LIMIT}
|
||||
# 앱이 직접 쓰지는 않는다. 로컬 주소가 남은 채 운영에 배포되는 것을
|
||||
# 기동 시점에 잡기 위해 검증용으로 주입한다 (shared/config/env.validation.ts)
|
||||
- BACKEND_API_URL=${BACKEND_API_URL}
|
||||
# 위 공개 주소 검사를 건너뛰는 탈출구 — 로컬에서 운영 이미지를 검증할 때만 true
|
||||
- ALLOW_LOCALHOST_URL=${ALLOW_LOCALHOST_URL:-}
|
||||
- THROTTLE_TTL_MS=${THROTTLE_TTL_MS:-60000}
|
||||
- THROTTLE_LIMIT=${THROTTLE_LIMIT:-100}
|
||||
- DB_HOST=db
|
||||
- DB_PORT=5432
|
||||
- DB_USER=${DB_USER}
|
||||
- DB_PASSWORD=${DB_PASSWORD}
|
||||
- DB_NAME=${DB_NAME}
|
||||
- DB_SYNCHRONIZE=${DB_SYNCHRONIZE:-false}
|
||||
- UPLOAD_DIR=/app/uploads
|
||||
- UPLOAD_MAX_SIZE_MB=${UPLOAD_MAX_SIZE_MB:-5}
|
||||
- REDIS_HOST=redis
|
||||
- REDIS_PORT=6379
|
||||
- REDIS_PASSWORD=${REDIS_PASSWORD}
|
||||
# 업로드 파일은 컨테이너 재생성과 무관하게 보존되어야 한다
|
||||
volumes:
|
||||
- ${UPLOAD_DATA_DIR:-./data/uploads}:/app/uploads
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- app-network
|
||||
@@ -72,8 +83,10 @@ services:
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
# redis 는 profile 로 비활성화될 수 있으므로 선택적 의존으로 둔다
|
||||
redis:
|
||||
condition: service_healthy
|
||||
required: false
|
||||
healthcheck:
|
||||
# localhost 는 컨테이너 안에서 ::1 로 먼저 해석되는데 Node 는 0.0.0.0(IPv4) 바인딩이므로 127.0.0.1 을 명시한다
|
||||
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:${BACKEND_PORT}/ || exit 1"]
|
||||
@@ -119,9 +132,14 @@ services:
|
||||
- "com.centurylinklabs.watchtower.enable=true"
|
||||
|
||||
# ----------------------------------------
|
||||
# 4. Redis — 내부 네트워크 전용
|
||||
# 4. Redis — 내부 네트워크 전용 · 기본 비활성
|
||||
#
|
||||
# 기본적으로 기동하지 않는다. 캐시/세션 공유가 실제로 필요해질 때 켠다.
|
||||
# 루트 .env.{APP_ENV} 에서 COMPOSE_PROFILES=redis
|
||||
# 또는 일회성으로 docker compose --profile redis up -d
|
||||
# ----------------------------------------
|
||||
redis:
|
||||
profiles: ["redis"]
|
||||
container_name: ${PROJECT_NAME}-redis
|
||||
image: ${REDIS_IMAGE}
|
||||
command: redis-server --requirepass ${REDIS_PASSWORD}
|
||||
|
||||
@@ -9,6 +9,8 @@ const Map<String, String> kErrorCodeMessages = {
|
||||
'VAL_001': '입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)',
|
||||
'RES_001': '요청하신 정보나 페이지를 찾을 수 없습니다.',
|
||||
'BIZ_001': '요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요.',
|
||||
'FILE_001': '허용되지 않는 파일 형식입니다. 파일을 확인해 주세요.',
|
||||
'FILE_002': '파일 크기가 허용 범위를 초과했습니다.',
|
||||
};
|
||||
|
||||
/// 매핑 실패 시 사용하는 폴백 코드
|
||||
|
||||
@@ -18,9 +18,13 @@ void main() {
|
||||
);
|
||||
});
|
||||
|
||||
test('세 플랫폼 공유 에러 코드가 모두 등록되어 있다', () {
|
||||
// backend error-codes.ts 레지스트리와 동일한 목록이어야 한다.
|
||||
const expected = [
|
||||
test('클라이언트 로직이 참조하는 코드가 사전에 존재한다', () {
|
||||
// dio_client 의 상태코드 역매핑과 세션 만료 승격이 이 코드들을 직접 사용한다.
|
||||
//
|
||||
// ⚠️ 전체 목록을 비교하지 않는 이유: 세 플랫폼의 사전은 backend 레지스트리에서
|
||||
// 생성되므로 목록 일치는 구조적으로 보장되고, CI 가 드리프트를 검사한다.
|
||||
// 전수 비교를 하면 도메인 코드를 추가할 때마다 무의미하게 깨진다.
|
||||
const usedByClient = [
|
||||
'SYS_001',
|
||||
'REQ_001',
|
||||
'AUTH_001',
|
||||
@@ -31,7 +35,17 @@ void main() {
|
||||
'BIZ_001',
|
||||
];
|
||||
|
||||
expect(ErrorLexicon.codes.keys.toSet(), expected.toSet());
|
||||
for (final code in usedByClient) {
|
||||
expect(ErrorLexicon.contains(code), isTrue, reason: '$code 누락');
|
||||
}
|
||||
});
|
||||
|
||||
test('모든 코드는 DOMAIN_NNN 네이밍 규약을 따른다', () {
|
||||
final pattern = RegExp(r'^[A-Z]+_\d{3}$');
|
||||
|
||||
for (final code in ErrorLexicon.codes.keys) {
|
||||
expect(pattern.hasMatch(code), isTrue, reason: '규약 위반: $code');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -19,9 +19,14 @@ describe('에러 코드 사전', () => {
|
||||
)
|
||||
})
|
||||
|
||||
it('세 플랫폼 공유 에러 코드가 모두 등록되어 있다', () => {
|
||||
// backend error-codes.ts 레지스트리와 동일한 목록이어야 한다.
|
||||
const expected = [
|
||||
it('클라이언트 로직이 참조하는 코드가 사전에 존재한다', () => {
|
||||
// useApi 의 상태코드 역매핑과 세션 만료 승격이 이 코드들을 직접 사용한다.
|
||||
// 사전에서 빠지면 폴백 메시지가 나가므로 반드시 존재해야 한다.
|
||||
//
|
||||
// ⚠️ 전체 목록을 비교하지 않는 이유: 세 플랫폼의 사전은 backend 레지스트리에서
|
||||
// 생성되므로 목록 일치는 구조적으로 보장되고, CI 가 드리프트를 검사한다.
|
||||
// 여기서 전수 비교를 하면 도메인 코드를 추가할 때마다 무의미하게 깨진다.
|
||||
const usedByClient = [
|
||||
'SYS_001',
|
||||
'REQ_001',
|
||||
'AUTH_001',
|
||||
@@ -32,7 +37,9 @@ describe('에러 코드 사전', () => {
|
||||
'BIZ_001',
|
||||
]
|
||||
|
||||
expect(Object.keys(ERROR_CODE_MESSAGES).sort()).toEqual(expected.sort())
|
||||
for (const code of usedByClient) {
|
||||
expect(ERROR_CODE_MESSAGES).toHaveProperty(code)
|
||||
}
|
||||
})
|
||||
|
||||
it('모든 코드는 DOMAIN_NNN 네이밍 규약을 따른다', () => {
|
||||
|
||||
@@ -9,6 +9,8 @@ export const ERROR_CODE_MESSAGES = {
|
||||
VAL_001: '입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)',
|
||||
RES_001: '요청하신 정보나 페이지를 찾을 수 없습니다.',
|
||||
BIZ_001: '요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요.',
|
||||
FILE_001: '허용되지 않는 파일 형식입니다. 파일을 확인해 주세요.',
|
||||
FILE_002: '파일 크기가 허용 범위를 초과했습니다.',
|
||||
} as const
|
||||
|
||||
export type ErrorCode = keyof typeof ERROR_CODE_MESSAGES
|
||||
|
||||
+71
-18
@@ -1,28 +1,81 @@
|
||||
import { fileURLToPath, URL } from 'node:url'
|
||||
|
||||
import { defineConfig } from 'vite'
|
||||
import { defineConfig, loadEnv } from 'vite'
|
||||
import vue from '@vitejs/plugin-vue'
|
||||
import vueJsx from '@vitejs/plugin-vue-jsx'
|
||||
import vueDevTools from 'vite-plugin-vue-devtools'
|
||||
|
||||
/** 루트 .env 에 값이 없을 때만 쓰는 기본 포트 (.env.*.example 과 같은 값) */
|
||||
const DEFAULT_FRONTEND_PORT = 5173
|
||||
const DEFAULT_BACKEND_PORT = 3000
|
||||
|
||||
/**
|
||||
* 환경변수를 양의 정수로 파싱한다.
|
||||
* 값이 없거나(undefined·빈 문자열) 숫자가 아니거나 0 이하면 기본값을 반환한다.
|
||||
* (compose 는 정의되지 않은 변수를 빈 문자열로 주입한다 — `Number('') === 0` 방어.
|
||||
* backend 의 `shared/utils/env.ts` 와 같은 규칙)
|
||||
*/
|
||||
function parsePositiveInt(value: string | undefined, fallback: number): number {
|
||||
if (value === undefined || value.trim() === '') return fallback
|
||||
|
||||
const parsed = Number(value)
|
||||
if (!Number.isInteger(parsed) || parsed <= 0) return fallback
|
||||
|
||||
return parsed
|
||||
}
|
||||
|
||||
// https://vite.dev/config/
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
vue(),
|
||||
vueJsx(),
|
||||
vueDevTools(),
|
||||
],
|
||||
resolve: {
|
||||
alias: {
|
||||
'@': fileURLToPath(new URL('./src', import.meta.url))
|
||||
export default defineConfig(({ mode }) => {
|
||||
// 포트·주소의 SSOT 는 루트 `.env.{mode}` 다 (.claude/rules/env-structure.md).
|
||||
// 프론트엔드 디렉터리 밖이라 vite 가 자동으로 읽지 않으므로 여기서 직접 로드한다.
|
||||
// 접두어 ''(전체)로 읽지만, 읽은 값은 **dev 서버 설정에만** 쓰고 클라이언트 번들에는 넣지 않는다
|
||||
// (VITE_ 접두어가 없는 값을 번들에 넣으면 시크릿이 노출된다 — .claude/rules/security.md).
|
||||
// 파일이 없으면(클론 직후 등) process.env 만 반영되고 아래 기본값으로 떨어진다.
|
||||
const rootEnv = loadEnv(mode, fileURLToPath(new URL('..', import.meta.url)), '')
|
||||
|
||||
const frontendPort = parsePositiveInt(rootEnv.FRONTEND_PORT, DEFAULT_FRONTEND_PORT)
|
||||
const backendPort = parsePositiveInt(rootEnv.BACKEND_PORT, DEFAULT_BACKEND_PORT)
|
||||
|
||||
// 컨테이너(바인드 마운트) 환경에서만 true — docker-compose.dev.yml 이 주입한다.
|
||||
// 호스트에서 직접 `npm run dev` 로 띄울 때는 OS 파일 감시 이벤트가 정상 동작하므로
|
||||
// 폴링을 켜면 CPU 만 쓰고 기동이 느려진다.
|
||||
const usePolling = rootEnv.CHOKIDAR_USEPOLLING === 'true'
|
||||
|
||||
return {
|
||||
plugins: [
|
||||
vue(),
|
||||
vueJsx(),
|
||||
vueDevTools(),
|
||||
],
|
||||
resolve: {
|
||||
alias: {
|
||||
'@': fileURLToPath(new URL('./src', import.meta.url))
|
||||
},
|
||||
},
|
||||
server: {
|
||||
// ngrok 등 외부 도메인 접근 허용 (DNS Rebinding 보호 비활성화)
|
||||
allowedHosts: true,
|
||||
// 루트 .env 의 FRONTEND_PORT 를 따른다.
|
||||
// 컨테이너로 띄울 때는 compose 의 `--port`(컨테이너 내부 고정 포트)가 이 값을 덮어쓴다.
|
||||
port: frontendPort,
|
||||
// 포트가 이미 사용 중이면 조용히 다음 포트로 옮기지 않고 실패한다.
|
||||
// 루트 .env 의 CORS_ORIGIN 과 compose 포트 매핑이 이 포트에 묶여 있어,
|
||||
// 말없이 5174 로 옮겨가면 API 요청이 원인 모르게 막힌다 (fail-fast).
|
||||
strictPort: true,
|
||||
// 도커 바인드 마운트에서는 inotify 가 호스트 쪽 변경을 잡지 못해 폴링이 필요하다
|
||||
watch: usePolling ? { usePolling: true } : undefined,
|
||||
// 개발 서버 API 프록시.
|
||||
// useApi 의 baseURL 은 '/api'(상대경로)라 프록시가 없으면 vite 가 SPA 폴백으로
|
||||
// index.html 을 200 으로 돌려준다 — 요청이 조용히 HTML 을 받아 실패한다.
|
||||
//
|
||||
// 기본 대상은 호스트에서 띄울 때 기준이고(백엔드 컨테이너가 BACKEND_PORT 를 호스트에 노출한다),
|
||||
// 프론트까지 docker 로 띄울 때는 compose 가 VITE_DEV_API_PROXY=http://backend:${BACKEND_PORT} 를 주입한다.
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: rootEnv.VITE_DEV_API_PROXY || `http://localhost:${backendPort}`,
|
||||
changeOrigin: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
server: {
|
||||
// ngrok 등 외부 도메인 접근 허용 (DNS Rebinding 보호 비활성화)
|
||||
allowedHosts: true,
|
||||
// 도커/윈도우 환경 파일 핫 리로딩 강제 활성화
|
||||
watch: {
|
||||
usePolling: true,
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
@@ -2,8 +2,11 @@ import { fileURLToPath } from 'node:url'
|
||||
import { mergeConfig, defineConfig, configDefaults } from 'vitest/config'
|
||||
import viteConfig from './vite.config'
|
||||
|
||||
// vite.config 는 mode 별 설정(포트·프록시)을 계산하는 함수다.
|
||||
// mergeConfig 는 함수를 병합하지 못하므로 테스트용 ConfigEnv 로 먼저 평가한다.
|
||||
// (테스트는 dev 서버를 띄우지 않아 포트·프록시 값에 영향받지 않는다)
|
||||
export default mergeConfig(
|
||||
viteConfig,
|
||||
viteConfig({ command: 'serve', mode: 'test' }),
|
||||
defineConfig({
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
|
||||
Reference in New Issue
Block a user