2026-02-27 16:52:42 +09:00
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@ -48,13 +48,18 @@ jobs:
      - name: Install backend dependencies
        run: |
          cd backend
-          npm ci --omit=dev
+          npm ci

      - name: Build backend
        run: |
          cd backend
          npx tsc

+      - name: Prune dev dependencies
+        run: |
+          cd backend
+          npm prune --omit=dev
+
      - name: Deploy backend
        run: |
          mkdir -p /deploy/wing-demo-backend/dist
--- a/docs/DEVELOPMENT-GUIDE.md
+++ b/docs/DEVELOPMENT-GUIDE.md
@ -0,0 +1,433 @@
+# WING 개발 워크플로우 가이드
+
+## 목차
+1. [전체 흐름 요약](#1-전체-흐름-요약)
+2. [계획 수립 (Plan)](#2-계획-수립-plan)
+3. [브랜치 생성 및 개발](#3-브랜치-생성-및-개발)
+4. [커밋 & 푸시](#4-커밋--푸시)
+5. [MR 생성 (feature → develop)](#5-mr-생성-feature--develop)
+6. [릴리즈 PR (develop → main)](#6-릴리즈-pr-develop--main)
+7. [자동 배포](#7-자동-배포)
+8. [프로젝트 문서 최신화](#8-프로젝트-문서-최신화)
+9. [실전 예시: 기능 추가 A to Z](#9-실전-예시-기능-추가-a-to-z)
+
+---
+
+## 1. 전체 흐름 요약
+
+```
+계획 수립 → 브랜치 생성 → 개발 → 커밋/푸시 → develop MR → main PR → 자동 배포
+```
+
+```
+[Plan Mode]          Claude가 코드베이스 분석 후 구현 계획 작성
+     ↓
+[Branch]             feature/기능명 브랜치 생성 (develop 기반)
+     ↓
+[Develop]            코드 작성 + TypeScript/ESLint 검증
+     ↓
+[Commit & Push]      Conventional Commits 형식 + pre-commit 자동 검증
+     ↓
+[MR → develop]       코드 리뷰 + 머지
+     ↓
+[PR → main]          릴리즈 MR + 머지
+     ↓
+[Auto Deploy]        Gitea Actions → 빌드 → 서버 배포
+```
+
+---
+
+## 2. 계획 수립 (Plan)
+
+3개 이상 파일 수정이 예상되거나 아키텍처에 영향을 주는 작업은 **Plan Mode**로 시작합니다.
+
+### Claude에게 요청하는 방법
+
+```
+"사용자 프로필 페이지를 추가해줘"
+→ Claude가 자동으로 Plan Mode 진입 → 코드베이스 분석 → 구현 계획 제시
+→ 사용자 승인 후 구현 시작
+```
+
+### 계획에 포함되는 내용
+- 수정/생성할 파일 목록
+- 변경 범위 및 영향도
+- 기술적 선택지와 권장안
+- 구현 순서
+
+### Plan Mode가 불필요한 경우
+- 단순 버그 수정 (1~2개 파일)
+- 텍스트/스타일 수정
+- 설정 변경
+
+---
+
+## 3. 브랜치 생성 및 개발
+
+### 브랜치 네이밍 규칙
+
+| 유형 | 형식 | 예시 |
+|------|------|------|
+| 기능 | `feature/설명` | `feature/user-profile` |
+| 이슈 | `feature/ISSUE-번호-설명` | `feature/ISSUE-42-login-fix` |
+| 버그 | `bugfix/ISSUE-번호-설명` | `bugfix/ISSUE-15-token-expired` |
+| 긴급 | `hotfix/설명` | `hotfix/security-patch` |
+
+### 브랜치 생성
+
+```bash
+# develop에서 분기
+git checkout develop
+git pull origin develop
+git checkout -b feature/user-profile
+```
+
+### 개발 중 검증
+
+로컬에서 타입 체크와 린트를 수시로 확인합니다:
+
+```bash
+# Frontend
+cd frontend && npx tsc --noEmit && npx eslint src/
+
+# Backend
+cd backend && npx tsc --noEmit
+```
+
+---
+
+## 4. 커밋 & 푸시
+
+### Conventional Commits 형식
+
+```
+type(scope): 한국어 설명
+```
+
+| type | 용도 | 예시 |
+|------|------|------|
+| `feat` | 새 기능 | `feat(auth): Google OAuth 로그인 추가` |
+| `fix` | 버그 수정 | `fix(map): 레이어 겹침 오류 수정` |
+| `refactor` | 리팩토링 | `refactor(api): 중복 호출 제거` |
+| `docs` | 문서 | `docs: API 엔드포인트 문서 추가` |
+| `chore` | 설정/빌드 | `chore: 의존성 버전 업데이트` |
+| `ci` | CI/CD | `ci: 백엔드 빌드 스텝 추가` |
+| `style` | 포맷팅 | `style: ESLint 경고 수정` |
+
+### pre-commit 자동 검증
+
+커밋 시 `.githooks/pre-commit`이 자동 실행됩니다:
+1. Frontend TypeScript 타입 체크
+2. Frontend ESLint 검증
+3. Backend TypeScript 타입 체크
+
+**하나라도 실패하면 커밋이 차단됩니다.**
+
+### 푸시
+
+```bash
+git push origin feature/user-profile
+```
+
+### Claude 스킬 활용
+
+```
+/push                    # 변경사항 확인 → 커밋 → 푸시 (한 번에)
+/mr                      # 커밋 → 푸시 → MR 생성 (한 번에)
+/mr main                 # 커밋 → 푸시 → main으로 MR 생성
+```
+
+---
+
+## 5. MR 생성 (feature → develop)
+
+### Gitea에서 MR 생성
+
+1. https://gitea.gc-si.dev/gc/wing-ops/compare/develop...feature/user-profile
+2. 제목: Conventional Commits 형식
+3. 본문: 변경 내용 요약 + 테스트 계획
+
+### Claude로 MR 생성
+
+```
+/create-mr develop       # feature → develop MR 자동 생성
+```
+
+### MR 본문 템플릿
+
+```markdown
+## Summary
+- 사용자 프로필 페이지 추가
+- 프로필 수정 API 연동
+
+## 변경 파일
+- frontend/src/components/views/ProfileView.tsx (신규)
+- backend/src/users/userRouter.ts (수정)
+
+## Test plan
+- [ ] 프로필 페이지 접근 확인
+- [ ] 프로필 수정 후 저장 확인
+```
+
+### 머지 후
+
+```bash
+# 로컬 develop 동기화
+git checkout develop
+git pull origin develop
+```
+
+---
+
+## 6. 릴리즈 PR (develop → main)
+
+develop에 기능이 머지된 후, 배포를 위해 main으로 릴리즈 MR을 생성합니다.
+
+### Claude로 릴리즈 MR 생성
+
+```
+/release                 # develop → main 릴리즈 MR 자동 생성
+```
+
+### 릴리즈 MR 체크리스트
+
+```markdown
+## Release v2.x.x
+
+### 포함 기능
+1. feat(auth): Google OAuth 로그인
+2. fix(map): 레이어 오류 수정
+
+### 배포 전 확인
+- [ ] 로컬 빌드 성공 (frontend + backend)
+- [ ] 서버 환경변수 설정 완료
+- [ ] DB 마이그레이션 적용 (필요 시)
+```
+
+### main 머지 → 자동 배포 트리거
+
+main에 머지되면 `.gitea/workflows/deploy.yml`이 자동 실행됩니다.
+
+---
+
+## 7. 자동 배포
+
+### CI/CD 파이프라인 (Gitea Actions)
+
+```
+main 브랜치 push
+  ↓
+[Frontend]  npm ci → vite build → /deploy/wing-demo/
+  ↓
+[Backend]   npm ci → tsc → /deploy/wing-demo-backend/
+  ↓
+[Server]    .deploy-trigger 감지 → wing-demo-api 재시작
+```
+
+### 배포 환경
+
+| 항목 | 값 |
+|------|---|
+| 프론트엔드 | https://wing-demo.gc-si.dev |
+| 백엔드 API | https://wing-demo.gc-si.dev/api/ |
+| 서버 | rocky-211 (Rocky Linux 9.6) |
+| 프로세스 | systemd `wing-demo-api.service` |
+
+### 배포 확인
+
+```bash
+# 프론트엔드 응답 확인
+curl -s -o /dev/null -w '%{http_code}' https://wing-demo.gc-si.dev/
+
+# 백엔드 API 확인
+curl -s https://wing-demo.gc-si.dev/api/auth/me
+```
+
+### 환경변수 관리
+
+| 위치 | 용도 |
+|------|------|
+| systemd 서비스 파일 | 서버 런타임 환경변수 (DB, JWT 등) |
+| Gitea Secrets | CI/CD 빌드 시 환경변수 (API 키 등) |
+
+```bash
+# Gitea Secret 등록 (API)
+curl -X PUT "https://gitea.gc-si.dev/api/v1/repos/gc/wing-ops/actions/secrets/KEY_NAME" \
+  -H "Authorization: token <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"data":"secret-value"}'
+
+# Gitea Secret 등록 (Web UI)
+# Settings → Actions → Secrets → Add Secret
+```
+
+---
+
+## 8. 프로젝트 문서 최신화
+
+### 자동 관리되는 문서
+
+Claude 세션 중 커밋/컴팩트 시 hook이 자동으로 갱신을 안내합니다:
+
+| 문서 | 위치 | 갱신 시점 |
+|------|------|----------|
+| MEMORY.md | `~/.claude/projects/.../memory/` | 매 세션 |
+| project-snapshot.md | 위와 동일 | 구조 변경 시 |
+| project-history.md | 위와 동일 | 매 커밋 |
+| api-types.md | 위와 동일 | API 변경 시 |
+| CHANGELOG.md | `docs/CHANGELOG.md` | 매 커밋 |
+
+### 수동으로 최신화해야 하는 문서
+
+| 문서 | 위치 | 갱신 주기 |
+|------|------|----------|
+| CLAUDE.md | 프로젝트 루트 | 기술 스택 변경 시 |
+| INSTALL_GUIDE.md | `docs/` | 배포 환경 변경 시 |
+| auth_init.sql | `database/` | DB 스키마 변경 시 |
+
+### 주기적 최신화 체크리스트
+
+**매 기능 개발 완료 시:**
+```
+Claude에게: "memory 파일 최신화해줘"
+→ project-snapshot.md 갱신
+→ api-types.md 갱신 (API 변경 시)
+→ project-history.md에 변경 이력 추가
+```
+
+**매주 또는 스프린트 종료 시:**
+```
+Claude에게: "프로젝트 문서 전체 점검해줘"
+→ CLAUDE.md 기술 스택 확인
+→ CHANGELOG.md 누락 항목 보충
+→ 의존성 버전 확인 (npm outdated)
+```
+
+**팀 워크플로우 업데이트 시:**
+```
+/sync-team-workflow      # Gitea에서 최신 팀 규칙 동기화
+```
+
+---
+
+## 9. 실전 예시: 기능 추가 A to Z
+
+### 시나리오: "사고 상세 조회 페이지 추가"
+
+#### Step 1. 계획
+
+```
+사용자: "사고 상세 조회 페이지를 추가해줘. 사고 목록에서 클릭하면 상세 정보를 보여주는 페이지야"
+
+Claude: (Plan Mode 진입)
+  → 코드베이스 분석
+  → 구현 계획 제시:
+    1. backend/src/incidents/incidentService.ts - 상세 조회 함수
+    2. backend/src/incidents/incidentRouter.ts - GET /api/incidents/:id
+    3. frontend/src/services/incidentApi.ts - API 함수
+    4. frontend/src/components/views/IncidentDetailView.tsx - 상세 화면
+    5. frontend/src/App.tsx - 라우팅 연결
+
+사용자: (계획 승인)
+```
+
+#### Step 2. 브랜치 생성
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/incident-detail
+```
+
+#### Step 3. 개발
+
+Claude가 계획에 따라 코드 작성 (5개 파일 수정/생성)
+
+#### Step 4. 커밋 & 푸시
+
+```
+사용자: "커밋하고 푸시해줘"
+
+Claude:
+  git add backend/src/incidents/... frontend/src/...
+  git commit -m "feat(incidents): 사고 상세 조회 페이지 추가"
+  # pre-commit: TypeScript ✓, ESLint ✓
+  git push origin feature/incident-detail
+```
+
+또는 스킬 사용:
+
+```
+/push feat(incidents): 사고 상세 조회 페이지 추가
+```
+
+#### Step 5. develop MR
+
+```
+사용자: "develop MR 만들어줘"
+
+Claude:
+  → Gitea API로 MR 생성
+  → feature/incident-detail → develop
+  → MR #5: https://gitea.gc-si.dev/gc/wing-ops/pulls/5
+```
+
+또는:
+```
+/create-mr develop
+```
+
+#### Step 6. 코드 리뷰 & 머지
+
+- Gitea에서 MR 리뷰
+- 승인 후 Squash Merge
+
+#### Step 7. 릴리즈 PR
+
+```
+사용자: "main으로 릴리즈 MR 만들어줘"
+
+Claude:
+  → develop → main MR 생성
+  → MR #6 (release)
+```
+
+또는:
+```
+/release
+```
+
+#### Step 8. main 머지 → 자동 배포
+
+- main에 머지 → Gitea Actions 실행
+- Frontend 빌드 (Vite) → /deploy/wing-demo/
+- Backend 빌드 (tsc) → /deploy/wing-demo-backend/
+- .deploy-trigger → cron이 감지 → wing-demo-api 재시작
+- https://wing-demo.gc-si.dev 에서 확인
+
+#### Step 9. 문서 최신화
+
+```
+사용자: "memory 파일 최신화해줘"
+
+Claude:
+  → project-snapshot.md: incidents 모듈 추가 반영
+  → api-types.md: GET /api/incidents/:id 추가
+  → project-history.md: "사고 상세 조회 페이지 추가" 기록
+```
+
+---
+
+## 부록: 자주 쓰는 Claude 명령
+
+| 명령 | 설명 |
+|------|------|
+| `"커밋하고 푸시해줘"` | 변경사항 커밋 + 푸시 |
+| `"develop MR 만들어줘"` | feature → develop MR |
+| `"memory 최신화해줘"` | 프로젝트 문서 갱신 |
+| `/push` | 커밋 + 푸시 (스킬) |
+| `/mr` | 커밋 + 푸시 + MR (스킬) |
+| `/release` | develop → main 릴리즈 MR (스킬) |
+| `/create-mr develop` | MR만 생성 (스킬) |
+| `/sync-team-workflow` | 팀 워크플로우 동기화 (스킬) |
+| `/changelog` | CHANGELOG.md 갱신 (스킬) |