배포 QA 고도화 PRD
배경 (Background)
stock-application은 현재 로컬 개발 환경에서만 동작하며, 코드 변경이 프로덕션에 배포되는 자동화 파이프라인이 없다. git hooks로 로컬 품질 게이트는 구축했으나, CI/CD와 E2E 테스트가 없어 PR 품질을 서버 환경에서 보장할 수 없다.
main 브랜치를 TBD(Trunk-Based Development)로 운영하려면 다음이 선행되어야 한다:
- PR 시 전체 테스트 + UI 검증을 자동으로 수행하는 CI
- main 머지 즉시 프로덕션 배포되는 CD
- UI에서 API 장애가 없음을 보장하는 E2E
Goals
| # | 목표 | 검증 방법 |
|---|---|---|
| G1 | main 브랜치는 언제든지 배포 가능한 상태 유지 | CI 필수 통과 후 머지 (Branch Protection) |
| G2 | PR 머지 전 UI API 장애 0건 검증 | Playwright E2E — 모든 API 호출 모니터링 |
| G3 | main 머지 시 5분 이내 프로덕션 배포 완료 | CD 파이프라인 소요 시간 측정 |
요구사항
| ID | 요구사항 | 우선순위 |
|---|---|---|
| R-01 | PR 생성/업데이트 시 GitHub Actions 자동 실행 | 상 |
| R-02 | 백엔드 전체 테스트 통과 필수 (unit + integration, TestContainers) | 상 |
| R-03 | 프론트엔드 테스트 통과 필수 (vitest) | 상 |
| R-04 | E2E 스모크 테스트 통과 필수 (Playwright, 핵심 UI 플로우 6개) | 상 |
| R-05 | Docker 빌드 가능 필수 (이미지 빌드 체크) | 상 |
| R-06 | CI 실패 시 GitHub Branch Protection으로 머지 불가 | 상 |
| R-07 | E2E — UI에서 어떤 API 장애도 없어야 하며, 기능 사용에 문제 없는 상태 검증 | 상 |
| R-08 | E2E 검증 플로우 6개: 메인 화면 로딩·종목 목록 조회·관심종목 CRUD·주문 화면·알림 설정·AI 챗봇 | 상 |
| R-09 | API 장애 감지: page.on('response') 훅으로 4xx/5xx 자동 감지 → 테스트 실패 | 상 |
| R-10 | main 브랜치 머지 시 Docker 이미지 빌드 후 ghcr.io 푸시 | 상 |
| R-11 | SSH를 통해 프로덕션 서버에 docker-compose로 자동 배포 | 상 |
| R-12 | main 브랜치: 직접 push 금지, PR 필수, CI 필수 통과 | 상 |
사용자 시나리오
시나리오 1 — PR 코드 품질 자동 검증 개발자가 feature 브랜치에서 main으로 PR을 생성하면, GitHub Actions CI가 자동으로 백엔드 테스트·프론트엔드 테스트·E2E 스모크·Docker 빌드 체크를 순서대로 실행한다. 4개 잡이 모두 통과해야 머지 버튼이 활성화된다. 하나라도 실패하면 개발자는 실패 원인을 Actions 로그와 Playwright HTML Report로 확인하고 코드를 수정한다.
시나리오 2 — main 머지 후 자동 배포
CI를 통과한 PR이 main에 머지되면, CD 파이프라인이 자동으로 트리거된다. 백엔드·프론트엔드 Docker 이미지가 ghcr.io에 푸시되고, SSH를 통해 프로덕션 서버에서 docker-compose up -d가 실행된다. 5분 이내에 새 버전이 서비스된다.
범위 외
- 멀티 스테이징 환경 (dev/staging/prod)
- 무중단 배포 (블루그린, Canary)
- 모니터링 대시보드 (Grafana, Prometheus)
- 로드 테스트 / 성능 테스트
제약 조건
- GitHub Free 계정: CI 2,000분/월 (PR당 약 10분 → 월 200 PR 처리 가능)
- CI 목표 소요 시간: 10분 이내 (백엔드 테스트 5분 + E2E 3분 + 빌드 2분)
- 배포 환경: SSH 접근 가능한 서버 (GitHub Secrets에 SSH_HOST, SSH_USER, SSH_PRIVATE_KEY 등록 필요)