Development Guide

Development Guide

작업 시작

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

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

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

변경 순서

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 번호와 한국어 설명을 사용합니다.

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

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