Development Guide

Development Guide

이슈를 시작해 PR을 완료할 때까지 따르는 개발 규칙입니다. 버전 결정과 배포 브랜치 운영은 Release Management를 따릅니다.

작업 시작

작업 브랜치는 GitHub Issue와 연결하고 feat/{issue-number} 형식을 사용합니다.

git fetch origin
git checkout -b feat/123 origin/dev

현재 작업 디렉터리에 다른 변경이 있다면 덮어쓰지 않습니다. 별도 worktree를 사용해 작업을 분리합니다.

브랜치

목적	시작점	브랜치	병합 대상
일반 작업	dev	feat/{issue-number}	dev
정식 릴리즈 QA	dev	release/v{MAJOR.MINOR.PATCH}	main
릴리즈 QA 수정	대상 release/v{버전}	fix/{issue-number}	대상 release/v{버전}
긴급 수정	main	hotfix/{issue-number}	main

기능 작업은 Issue를 만든 뒤 feat/*에서 시작합니다. 정식 릴리즈와 hotfix의 버전 결정, QA, 역병합 순서는 Release Management를 따릅니다.

변경 순서

1. 관련 Controller, Service, Repository, DTO와 테스트를 찾습니다.
2. 실패를 재현하는 가장 작은 테스트를 추가합니다.
3. 기존 구조를 유지하며 필요한 코드만 수정합니다.
4. 관련 테스트를 먼저 실행합니다.
5. 설정, 보안, DB, 외부 연동 변경이면 전체 테스트를 실행합니다.
6. 공개 API가 바뀌면 Swagger 문서 인터페이스를 갱신합니다.
7. DB가 바뀌면 Flyway SQL을 추가합니다.

테스트

관련 테스트만 실행합니다.

./gradlew test --tests 'com.chukchuk.haksa.application.portal.PortalLinkJobServiceUnitTests'

전체 테스트를 실행합니다.

./gradlew test

CI와 같은 검증을 실행합니다.

./gradlew check --stacktrace --no-daemon

CI는 dev와 main의 push·PR에서 check를 실행합니다. 실패하면 로그의 첫 번째 원인을 해결한 뒤 전체 명령을 다시 실행합니다.

API 변경

• Controller의 path와 HTTP method를 확인합니다.
• 요청·응답 DTO의 Swagger annotation을 갱신합니다.
• 해당 controller/docs 인터페이스를 갱신합니다.
• 인증 공개 범위가 바뀌면 SecurityConfig를 검토합니다.
• Controller 테스트와 Service 테스트를 함께 갱신합니다.
• 로컬 /v3/api-docs와 Swagger UI에서 변경이 보이는지 확인합니다.

공개 endpoint를 추가하면서 Security 설정을 빼먹으면 인증되지 않은 호출이 401이 됩니다. 반대로 보호 endpoint를 공개 목록에 넣으면 보안 문제가 됩니다.

DB와 Flyway

마이그레이션 파일은 src/main/resources/db/migration에 둡니다. 현재 마지막 버전의 다음 번호를 사용합니다.

V9__describe_the_schema_change.sql

규칙입니다.

• 이미 dev 또는 prod에 적용된 파일은 수정하지 않습니다.
• 수정이 필요하면 다음 버전의 보정 마이그레이션을 추가합니다.
• 테이블, 컬럼, 인덱스, 제약 조건 변경을 Java 코드로만 끝내지 않습니다.
• dev·prod에서 Hibernate ddl-auto를 스키마 변경 수단으로 사용하지 않습니다.
• 대용량 UPDATE나 lock 가능성이 있는 DDL은 적용 시간과 복구 방안을 PR에 적습니다.

배포 전에 GitHub Actions가 flyway info와 migrate를 실행합니다. 마이그레이션이 실패하면 Lambda 배포는 시작하지 않습니다.

포털 연동 변경

포털 연동은 API, DB, SQS, Worker, HMAC, S3가 연결된 흐름입니다. 한 컴포넌트만 보고 완료를 판단하지 않습니다.

확인할 항목입니다.

• Idempotency-Key 재사용과 충돌.
• scrape_jobs와 scrape_job_outbox의 같은 트랜잭션 저장.
• SQS 발행 성공과 queue_message_id 저장.
• 콜백 원문 Body 기반 HMAC 검증.
• S3 Bucket, Prefix, job scope 검증.
• 중복 콜백 멱등성.
• 실패 시 error_code, retryable, 종료 시각 저장.
• 성공 후 사용자·학사·졸업 데이터 반영.

관련 핵심 테스트는 src/test/java/com/chukchuk/haksa/application/portal, infrastructure/portal, infrastructure/security에 있습니다.

로그와 개인정보

• 포털 username·password, request_payload_json, Outbox payload_json을 출력하지 않습니다.
• JWT, OIDC ID Token, HMAC Secret, DB 비밀번호를 출력하지 않습니다.
• 진단에는 jobId, outboxId, workerRequestId, 오류 code, hash를 사용합니다.
• 사용자 식별자가 필요한 Sentry tag는 기존 SentryMdcContext 경로를 사용합니다.

커밋과 PR

커밋 메시지는 Issue 번호, type, 한국어 설명 순서로 작성합니다.

{issue-number} {type}: {message}

type은 변경의 주된 목적을 기준으로 선택합니다.

type	용도
feat	기능 추가
fix	버그 수정
refactor	동작을 유지하는 코드 구조 변경
docs	문서 수정
test	테스트 추가·수정
chore	빌드, 패키지, 개발 환경 설정 변경
comment	주석만 추가·수정
style	동작 변화가 없는 코드 형식 변경
rename	파일·디렉터리 이름 변경
remove	파일·기능 제거

한 커밋은 한 문장으로 설명할 수 있는 변경만 포함합니다. 기능, 문서, 설정처럼 독립적으로 되돌릴 수 있는 변경은 가능한 한 나눕니다.

123 feat: 포털 작업 상태 조회 추가
123 fix: 콜백 중복 처리 보정
123 docs: 운영 장애 대응 절차 추가

PR에는 변경 이유, API·DB 영향, 테스트 명령과 결과, 배포·롤백 방법을 적습니다. Wiki에 영향을 주는 변경이면 수정할 페이지를 함께 적습니다.

기존 API 사용 방식에 영향을 주는 변경은 commit type만으로 표시하지 않습니다. PR 본문에 영향받는 client, 이전 방법, 전환 방법을 구체적으로 적습니다.

Wiki 갱신

현재 동작이 바뀌면 관련 Wiki 한 곳을 기준 문서로 갱신합니다.

변경	기준 문서
공개 API와 인증	API and Authentication
런타임과 핵심 처리 흐름	Project Architecture, Core Domain Flows
주요 기술 결정	Architecture Decision Records
버전, 브랜치, 태그와 릴리즈 노트	Release Management
배포 실행, 환경 설정과 롤백	Deployment and Operations
반복 가능한 장애 대응	Troubleshooting
재사용할 가치가 있는 장애·성능 개선	Troubleshooting Case Studies

Wiki를 게시하기 전에는 코드와 설정을 근거로 내용을 확인하고, 비밀정보와 사용자 원문 데이터가 없는지 검사합니다. 별도 Wiki 저장소의 master에 반영한 뒤 내부 링크, Sidebar와 공개 렌더링을 확인하고 코드 PR에 변경한 페이지 링크를 남깁니다.

README.md는 프로젝트 소개와 문서 진입점, AGENTS.md는 지속적인 저장소 작업 규칙만 담당합니다. 아직 main에 없는 계획은 현재 동작처럼 쓰지 않습니다.