From 3b00408b71b7d65b2c1d9bb7c8f81afae4e5816d Mon Sep 17 00:00:00 2001 From: htlee Date: Fri, 27 Feb 2026 16:51:29 +0900 Subject: [PATCH] =?UTF-8?q?fix(ci):=20backend=20=EB=B9=8C=EB=93=9C=20?= =?UTF-8?q?=EC=8B=9C=20devDependencies=20=EB=88=84=EB=9D=BD=20=EC=88=98?= =?UTF-8?q?=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm ci --omit=dev로 TypeScript가 설치되지 않아 빌드 실패하던 문제 수정. 전체 의존성 설치 → 빌드 → devDependencies prune 순서로 변경. Co-Authored-By: Claude Opus 4.6 --- .gitea/workflows/deploy.yml | 7 +- docs/DEVELOPMENT-GUIDE.md | 433 ++++++++++++++++++++++++++++++++++++ 2 files changed, 439 insertions(+), 1 deletion(-) create mode 100644 docs/DEVELOPMENT-GUIDE.md diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index 437b553..ee6a01f 100644 --- 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 diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md new file mode 100644 index 0000000..68cc157 --- /dev/null +++ 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 " \ + -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 갱신 (스킬) |