Feat(#103): 기관 발신번호 후보 축적 파이프라인 구현

[LATE-BL00MER]

📋 작업 내용

• 기관별 발신번호 후보를 저장하는 InstitutionSenderCandidate 엔티티와 Repository를 추가했습니다.
• 국내 발신번호 형식을 정규화하는 SenderNumberNormalizer를 추가했습니다.
• 기관명과 정규화된 발신번호를 기준으로 후보 관측 횟수를 누적하도록 구현했습니다.
• URL이 없어도 institutionMatch.institution에 감지된 기관명이 있으면 후보를 축적하도록 처리했습니다.
• 동일 후보가 기본 3회 관측되면 REVIEW_REQUIRED 상태로 변경되도록 구현했습니다.
• 검토 기준 횟수는 SENDER_CANDIDATE_REVIEW_THRESHOLD 환경변수로 설정할 수 있습니다.
• 후보 상태를 COLLECTING, REVIEW_REQUIRED, APPROVED, REJECTED로 관리합니다.
• 후보가 자동 승인되지 않고 운영자 검토를 통해서만 승인 또는 거절되도록 구성했습니다.
• 후보 테이블 생성을 위한 V22 DB 마이그레이션을 추가했습니다.
• 운영자 검토 절차와 SQL 예시를 문서화했습니다.
• 외부 API 응답 스키마 변경은 없습니다.

🧪 테스트 결과

• .\gradlew.bat test 전체 테스트 통과
• 국내 일반번호, 휴대전화번호, 대표번호 및 국가번호 정규화 테스트 통과
• URL이 없는 기관 매칭 결과의 후보 축적 테스트 통과
• 동일 후보 3회 관측 시 REVIEW_REQUIRED 전환 테스트 통과
• 승인 또는 거절된 후보의 상태 유지 테스트 통과
• Docker Compose 설정 검증 통과

🔗 관련 이슈

Closes #103

Refs SafeFam/SafeFam_AI#67

✅ 체크리스트

• 관련 이슈를 연결했습니다.
• 구현 범위와 변경 이유를 설명했습니다.
• 로컬 테스트를 통과했습니다.
• API 변경 사항을 Swagger에 반영했습니다. (API 변경 없음)
• DB 변경 사항과 마이그레이션을 포함했습니다.
• 민감 정보가 코드·로그·테스트 데이터에 포함되지 않았습니다.
• 프론트엔드에 영향을 주는 응답 스키마 또는 Enum 변경을 공유했습니다. (외부 변경 없음)
• 병합 전 작업 브랜치를 삭제하지 않았습니다.

[coderabbitai]

Warning

Review limit reached

@LATE-BL00MER, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 90 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7362f83c-a381-4cdb-bed6-979227608735

📥 Commits

Reviewing files that changed from the base of the PR and between 92e8db5 and 5272452.

📒 Files selected for processing (19)

• .env.example
• .env.prod.example
• README.md
• docker-compose.yml
• docs/sender-candidate-review.md
• src/main/java/com/gold/safefam/domain/analysis/entity/InstitutionSenderCandidate.java
• src/main/java/com/gold/safefam/domain/analysis/enums/SenderCandidateStatus.java
• src/main/java/com/gold/safefam/domain/analysis/repository/InstitutionSenderCandidateRepository.java
• src/main/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyService.java
• src/main/java/com/gold/safefam/domain/analysis/service/InstitutionSenderCandidateService.java
• src/main/java/com/gold/safefam/domain/analysis/service/SenderNumberNormalizer.java
• src/main/resources/application.yml
• src/main/resources/db/migration/V22__create_institution_sender_candidates.sql
• src/test/java/com/gold/safefam/domain/analysis/entity/InstitutionSenderCandidateTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyMappingTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyServiceTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/InstitutionSenderCandidateServiceTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/SenderNumberNormalizerTest.java
• src/test/java/com/gold/safefam/support/AnalysisResultEventFixture.java

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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