feat: TaxCheck 분석 조회 및 시뮬레이션 API 구현 #5

[foxihyun]

설명

사용자 입력·확인 기반 TaxCheck 1차 백엔드를 구현했습니다. 분석 결과는 세무 확정 판정이 아닌 자료 준비와 참고 계산을 위한 정보입니다.

관련 이슈

Refs #5

구현 내용

• GET /api/tax-checks: 사용자별 분석 이력 조회
• GET /api/tax-checks/{taxCheckId}: 저장된 분석 상세 조회
• POST /api/tax-checks/analyze: 입력 검증, 분석 및 결과 저장
• POST /api/tax-checks/{taxCheckId}/simulate: 원본 스냅샷 기반 조건 변경 결과 반환
• 서버 Paycheck를 귀속연도별로 집계하며, 실입금 합계와 세금 계산용 사용자 확인 소득을 분리
• 미확인 금액은 null과 부족 사유로 반환하고 확인된 0원과 구분
• 19% 적용을 가정한 소득세 참고값만 계산하며 일반세율 예상액·차액은 null 유지
• 단일세율 적용 자격·유불리·환급액 및 거주자/주택 공제 여부를 확정하지 않음
• 실제 분석의 입력·당시 프로필/급여 참고값·규칙 버전·결과를 JSON 스냅샷으로 보존
• 시뮬레이션은 결과만 반환하며 원본 및 다른 DB 기록을 저장·변경하지 않음
• 문서 소유자/유형, 사용자별 조회 범위, 금액·귀속연도 입력 검증
• TaxCheck 전용 BigDecimal JSON converter, 공통 오류 코드 및 시드 삭제 순서 보완
• API 명세, 구현 결정 기록 및 규칙/API/JSON converter 테스트 추가

검증

• 작성자 로컬에서 .\gradlew.bat test --console=plain 전체 테스트 성공
  • 공유한 실행 로그: 2026-09-01 16:25 KST, BUILD SUCCESSFUL in 19s
  • 이는 로컬 테스트 결과이며 GitHub CI 실행 결과를 뜻하지 않습니다.
• dev 대비 1커밋 / 뒤처짐 0개, 변경 파일 19개 확인
• 이번 변경에 IDE·Gradle 캐시·전달용 patch 파일 미포함

docs/TAXCHECK_IMPLEMENTATION.md의 검증 기록은 패키지 생성 당시 환경 기준입니다. 이후 작성자 로컬에서 전체 Gradle 테스트가 통과한 최신 상태를 위에 기록했습니다.

리뷰 요청 사항

• 사용자별 조회/문서 접근 범위, 누락 입력과 0원 처리
• 연도별 Paycheck 집계와 세금 소득 입력의 분리
• JSON 직렬화 정밀도 및 과거 분석 스냅샷 보존
• 시뮬레이션의 비저장 동작과 트랜잭션 경계
• 입력 오류 응답, 경계값 및 회귀 테스트의 충분성

범위 밖 / 후속 작업

• 실제 MySQL 환경·서버 기동 및 브라우저 E2E는 아직 검증하지 않았습니다.
• 프론트 API 연결, Dashboard/Records API, OCR 후보 자동 추출은 별도 작업입니다.
• 일반세율 비교·개별 세법 적용 자격 확정·LLM 계산은 이번 범위에 포함하지 않습니다.

Summary by CodeRabbit

• 새 기능
  • 세금 점검 분석을 저장하고 목록·상세 결과를 조회할 수 있습니다.
  • 소득, 급여, 조건을 바탕으로 참고 세액과 결과 요약을 제공합니다.
  • 기존 분석 결과를 기준으로 입력 조건을 변경해 시뮬레이션할 수 있으며, 원본 데이터는 변경되지 않습니다.
  • 과세연도 및 사용자 기준 필터링을 지원합니다.
• 오류 수정 및 검증
  • 잘못된 요청 형식, 문서 소유권, 누락·유효하지 않은 분석 입력을 검증하고 명확한 오류를 반환합니다.
• 문서
  • TaxCheck API 계약과 계산·검증 규칙을 상세히 문서화했습니다.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Free

Run ID: 971f5eb4-8611-49b1-8cb1-848c73708381

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Free

Run ID: 0fba6417-709a-408f-b6b3-ffd2955a8034

📥 Commits

Reviewing files that changed from the base of the PR and between 9605956 and 30f4dde.

📒 Files selected for processing (19)

• docs/API_SPEC.md
• docs/TAXCHECK_IMPLEMENTATION.md
• src/main/java/com/foreigninone/backend/common/exception/ErrorCode.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/controller/TaxCheckController.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/dto/TaxCheckAnalyzeRequest.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/dto/TaxCheckResponse.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/dto/TaxCheckSimulateRequest.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/dto/TaxCheckSnapshot.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheck.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheckJsonConverter.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheckStatus.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/repository/TaxCheckRepository.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/rule/TaxCheckRules.java
• src/main/java/com/foreigninone/backend/domain/taxcheck/service/TaxCheckService.java
• src/main/java/com/foreigninone/backend/init/DataInitializer.java
• src/test/java/com/foreigninone/backend/TaxCheckApiIntegrationTest.java
• src/test/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheckJsonConverterTest.java
• src/test/java/com/foreigninone/backend/domain/taxcheck/rule/TaxCheckRulesScenarios.java
• src/test/java/com/foreigninone/backend/domain/taxcheck/rule/TaxCheckRulesTest.java

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

TaxCheck API를 추가하고 분석 결과를 저장·조회한다. 규칙 엔진은 급여 집계와 19% 참고 계산을 수행한다. 스냅샷 기반 시뮬레이션은 원본을 변경하지 않는다. 요청 검증, 오류 코드, 통합 테스트를 추가했다.

Changes

TaxCheck 기능

Layer / File(s)	Summary
API 및 데이터 계약 docs/API_SPEC.md, docs/TAXCHECK_IMPLEMENTATION.md, src/main/java/com/foreigninone/backend/common/exception/ErrorCode.java, src/main/java/com/foreigninone/backend/domain/taxcheck/dto/*, src/main/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheckStatus.java	분석·조회·시뮬레이션 계약과 요청·응답·스냅샷 구조를 정의했다. TAXCHECK_NOT_FOUND와 TAXCHECK_SNAPSHOT_INVALID 오류 코드를 추가했다.
세금 규칙 및 계산 결과 src/main/java/com/foreigninone/backend/domain/taxcheck/rule/TaxCheckRules.java, src/test/java/com/foreigninone/backend/domain/taxcheck/rule/*	귀속연도별 급여 집계, 입력 검증, 19% 참고 세액, 거주일수와 결과 카드를 구현했다. 27개 규칙 시나리오를 동적 테스트로 검증한다.
스냅샷 저장 및 분석 서비스 src/main/java/com/foreigninone/backend/domain/taxcheck/entity/*, src/main/java/com/foreigninone/backend/domain/taxcheck/repository/TaxCheckRepository.java, src/main/java/com/foreigninone/backend/domain/taxcheck/service/TaxCheckService.java, src/main/java/com/foreigninone/backend/init/DataInitializer.java, src/test/java/com/foreigninone/backend/domain/taxcheck/entity/TaxCheckJsonConverterTest.java	TaxCheck 엔티티와 JSON 스냅샷 변환을 추가했다. 사용자별 조회, 신규 분석 저장, 스냅샷 검증, 원본 비변경 시뮬레이션을 구현했다. 시드 초기화 시 TaxCheck 데이터를 삭제한다.
HTTP 엔드포인트 및 통합 검증 src/main/java/com/foreigninone/backend/domain/taxcheck/controller/TaxCheckController.java, src/test/java/com/foreigninone/backend/TaxCheckApiIntegrationTest.java	사용자 식별자 선택과 분석·조회·시뮬레이션 API를 연결했다. 형식 오류를 400 Bad Request로 처리한다. 소유권, 연도 필터, 스냅샷 오류와 비저장 시뮬레이션을 통합 테스트로 검증한다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟠 High · up to 30f4d

The new TaxCheck endpoints let callers choose the user identity through request values, including a default user. This could expose another user’s tax-analysis history and personal tax data or save analyses under the wrong account, so merge should wait until identity is bound to authenticated ownership.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant TaxCheckController
  participant TaxCheckService
  participant TaxCheckRules
  participant TaxCheckRepository
  Client->>TaxCheckController: 분석 요청
  TaxCheckController->>TaxCheckService: 사용자 ID와 분석 입력 전달
  TaxCheckService->>TaxCheckRules: 소득·조건·급여 평가
  TaxCheckRules-->>TaxCheckService: 분석 Result 반환
  TaxCheckService->>TaxCheckRepository: TaxCheck와 스냅샷 저장
  TaxCheckService-->>TaxCheckController: TaxCheckResponse 반환
  TaxCheckController-->>Client: 분석 응답 반환
  Client->>TaxCheckController: 시뮬레이션 요청
  TaxCheckController->>TaxCheckService: TaxCheck ID와 대체 입력 전달
  TaxCheckService->>TaxCheckRules: 원본 스냅샷과 대체 그룹 평가
  TaxCheckRules-->>TaxCheckService: 시뮬레이션 Result 반환
  TaxCheckService-->>Client: 저장하지 않은 TaxCheckResponse 반환

Loading

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}

[foxihyun]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.