[Foundation] Spring Boot 개발·검증 기반 정리

[hywznn]

한 줄 요약

누구나 같은 방법으로 서버를 실행·테스트하고, DB 변경과 API 문서를 안전하게 관리할 수 있는 Spring Boot 개발 기반을 완성했습니다.

완료 결과

• Java 17·Spring Boot 4.1 기준 README와 로컬 실행 방법 정리
• gradlew 실행 권한과 Wrapper 실행 확인
• Spring Security 활성화 및 미정의 API 기본 차단
• Springdoc OpenAPI/Swagger UI 구성
• Flyway와 기술 baseline migration 구성
• local, test, dev, prod profile 분리
• 운영 profile에서 ddl-auto: validate 적용
• 공통 오류 응답과 @RestControllerAdvice 구현
• request_id 생성·응답 header·MDC 연동
• 테스트 가능한 UTC Clock, UUID Bean 구성
• CORS 환경변수·profile 정책 정리
• H2 단위 검증과 Testcontainers PostgreSQL migration 검증
• GitHub Actions에서 Java 17 test·build 자동 실행
• .env.example에 변수 이름만 문서화
• Bug·Feature·API Issue Form과 PR Template 제공
• GET /health를 공개 최소 응답으로 유지

현재 확인 방법

./gradlew clean test
./gradlew bootRun --args='--spring.profiles.active=local'
curl http://localhost:8080/health

Swagger UI는 local 환경에서 http://localhost:8080/swagger-ui.html로 확인합니다.

완료 기준 검증

• 새 clone에서 Gradle test가 성공합니다.
• local profile 서버와 /health가 동작합니다.
• Swagger UI와 OpenAPI JSON을 확인할 수 있습니다.
• Flyway가 PostgreSQL 빈 DB에 기술 baseline을 적용합니다.
• 잘못된 요청이 같은 오류 envelope와 request_id를 반환합니다.
• PR마다 CI가 실행됩니다.

현재 V1은 도메인 테이블이 아닌 migration 동작 확인용 기술 baseline입니다. 인증·근로자·Workflow·AI 테이블은 각 기능 이슈에서 별도 migration으로 추가합니다.

범위 밖

• 실제 JWT 인증: [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4
• 근로자·업무·감사 도메인: [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• AI와 외부 LLM: [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• 클라우드 데모 배포: [Deploy] PostgreSQL·AI Runtime 기반 데모 배포 구성 #9

연결

• 구현: PR #22
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

용어 도움말

• Flyway: DB 변경 SQL을 번호 순서대로 적용하고 재현하는 도구입니다.
• Profile: local/test/prod처럼 환경별 설정을 나누는 Spring 기능입니다.
• CI: PR의 빌드와 테스트를 자동 검사하는 과정입니다.