acquire-core-x/README.md

카드 매입 승인 경로 - Spring Boot 3 전환

전환 개요

항목	기존	전환 후
Spring Boot	2.7.x	3.2.5
Spring Framework	5.x	6.1.x
Java	11	17
Jakarta EE	8 (javax.*)	10 (jakarta.*)
Hibernate	5.x	6.4.x
JPA	2.2	3.1
Validation	Bean Validation 2.0	Bean Validation 3.0

주요 전환 사항

1. Jakarta EE 9+ 마이그레이션

• javax.* → jakarta.* 네임스페이스 변환
• @Entity, @Table, @Column 등 JPA 어노테이션
• @NotBlank, @NotNull, @Positive 등 Validation 어노테이션

2. Spring Framework 6.x 변경사항

• Jakarta Servlet API 사용
• 개선된 예외 처리 구조

3. Spring Boot 3.x 의존성

• spring-boot-starter-validation (Bean Validation 3.0 내장)
• spring-boot-starter-actuator (헬스체크)
• Jackson 2.15+ (Java 8 Date/Time first-class 지원)

프로젝트 구조

src/main/java/com/acquirex/cardapproval/
├── CardAcquisitionApprovalApplication.java   # 메인 애플리케이션
├── controller/
│   └── AcquisitionApprovalController.java    # REST API 엔드포인트
├── domain/
│   └── AcquisitionApproval.java              # 도메인 엔티티 + Repository
└── service/
    └── AcquisitionApprovalService.java       # 비즈니스 로직 + DTO + Exception Handler

API 엔드포인트

Method	Endpoint	설명
POST	/api/v1/acquisitions	매입 승인 요청 처리
GET	/api/v1/acquisitions/{id}	매입 승인 단건 조회
GET	/api/v1/acquisitions/merchant/{merchantId}	가맹점별 목록 조회
GET	/api/v1/acquisitions/period?startDate=&endDate=	기간별 목록 조회
POST	/api/v1/acquisitions/{id}/cancel	매입 취소 처리

검증 절차

1. 빌드 검증

./mvnw clean compile

2. 테스트 실행

./mvnw test

3. 애플리케이션 실행

./mvnw spring-boot:run

4. API 동작 확인

# 매입 승인 요청
curl -X POST http://localhost:8080/api/v1/acquisitions \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "MERCHANT001",
    "cardNumber": "1234567890123456",
    "acquisitionAmount": 50000,
    "approvalAmount": 50000,
    "approvalNumber": "APPR123456",
    "acquisitionDatetime": "2024-01-15T10:30:00"
  }'

# 매입 승인 조회
curl http://localhost:8080/api/v1/acquisitions/1

# 매입 취소
curl -X POST http://localhost:8080/api/v1/acquisitions/1/cancel \
  -H "Content-Type: application/json" \
  -d '{"reason": "고객 요청"}'

5. H2 콘솔

• URL: http://localhost:8080/h2-console
• JDBC URL: jdbc:h2:mem:acquirex

테스트 커버리지

테스트	검증 내용
contextLoads	스프링 컨텍스트 로드
processAcquisition_Success	매입 승인 처리 성공
processAcquisition_AmountMismatch_ThrowsException	금액 불일치 예외
cancelAcquisition_Success	매입 취소 처리 성공
cancelAcquisition_AlreadyCancelled_ThrowsException	중복 취소 예외
getAcquisition_NotFound_ThrowsException	존재하지 않는 ID 조회 예외
getAcquisitionsByMerchant_Success	가맹점별 목록 조회
entityCancelMethod_WorksCorrectly	엔티티 취소 메서드 동작

전환 체크리스트

• javax.persistence → jakarta.persistence 마이그레이션
• javax.validation → jakarta.validation 마이그레이션
• Java 17 이상 요구사항 반영
• Spring Boot 3.2.x 의존성 적용
• 통합 테스트 작성 및 통과 확인
• README 문서화

의존성 버전

Dependency	Version
Spring Boot	3.2.5
Spring Framework	6.1.5
Hibernate	6.4.4
Jakarta EE	10.0.0
Java	17
Lombok	1.18.30
H2 Database	2.2.224