# ncrc-pairing 엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다. 현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 `PairingScheduleService`입니다. ## 실행 흐름 1. `PairingController` - `/api/v1/pairing/run`으로 엑셀 파일을 업로드받습니다. - 결과 엑셀 파일을 반환합니다. 2. `PairingService` - 전체 유스케이스를 순서대로 호출합니다. - `엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성` 3. `PairingExcelService` - 입력 엑셀 시트를 DTO로 읽습니다. - 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다. 4. `PairingNormalizeService` - 엑셀 문자열을 내부 모델로 변환합니다. - 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다. 5. `PairingHolidayService` - `DatagoHolidayCache`를 통해 공휴일을 조회합니다. - 토/일은 `DatagoHolidayCache#getWeekend`에서 생성해 공통 불가능일로 합칩니다. - 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다. 6. `PairingValidationService` - 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다. - 검증 실패는 `BusinessException.badRequest(code, message)`를 사용합니다. 7. `PairingCandidateService` - 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다. - 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다. 8. `PairingMemberPairService` - 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다. - 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다. 9. `PairingScheduleService` - 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다. - 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다. 10. `PairingSolverService` - 결과 DTO 생성과 규칙 위반 검사를 담당합니다. - CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다. ## 현재 Hard Rule | 규칙 | 구현 위치 | | --- | --- | | 모든 위원은 최소 1개 조에 포함 | `PairingMemberPairService`, `PairingSolverService#checkAllMembersUsed` | | 현장위원 + 외부위원 조 구성 | `PairingCandidateService#createPairCandidates` | | 위원 활동 가능 기간 겹침 | `PairingCandidateService#hasDateOverlap` | | 상피제 | `PairingCandidateService#isConflictRegion` | | 여성전용센터는 여성 2명 조만 허용 | `PairingCandidateService#findCenterHardRuleReasons` | | 기방문센터 제외 | `PairingCandidateService#findCenterHardRuleReasons` | | 위원/지자체/센터 불가능일 제외 | `PairingCandidateService#findAssignableDates`, `isAvailableOn` | | 공휴일/토/일 제외 | `PairingHolidayService`, `DatagoHolidayCache`, `PairingCandidateService#commonUnavailableDates` | | 센터 1개는 최대 1번 배정 | `PairingScheduleService#isFeasible`, `PairingSolverService#addCenterAssignedAtMostOnce` | | 한 위원은 같은 날짜에 다른 조와 중복 활동 불가 | `PairingScheduleService#isFeasible`, `GreedyState#isMemberBusyWithOtherPair` | | 같은 조는 하루 최대 N개 센터 방문 | `application.yaml`, `PairingScheduleService#isFeasible` | | 같은 조/같은 날짜에는 하나의 인접지역 분류만 방문 | `PairingScheduleService#isFeasible`, `GreedyState#isAllowedAdjacentClassification` | | 위원당 상대 파트너 수 최대 N명 | `application.yaml`, `PairingMemberPairService`, `PairingScheduleService#isFeasible` | | 위원별 최대 방문 수 상한 | `application.yaml`, `PairingScheduleService#maxMemberVisitCount` | ## 현재 Soft Rule 우선순위 1. 배정 센터 수 최대화 2. 위원별 방문 수 균형 3. 희망지역 매칭표 우선순위 4. 희망지역 99 wildcard fallback 5. 거주지 유사도 6. 같은 조/같은 날짜/같은 인접지역 분류 재사용 관련 설정: ```yaml pairing: rule: max-centers-per-pair-per-day: 3 max-counterparts-per-member: 3 max-member-visit-average-ratio-percent: 130 preference: anywhere-rank: 0 ignored-rank: 99 active-wildcard-fallback-enabled: true wildcard-fallback-score-bonus: 25_000 objective: assignment-weight: 1_000_000 member-balance-weight: 20_000 preference-base-weight: 30_000 preference-rank-penalty: 1_000 residence-match-weight: 10_000 candidate: max-pair-candidates-per-member: 0 max-dispatch-regions-per-pair: 0 max-assignments-per-center: 1_000 max-assignments-per-member: 3_000 max-dates-per-assignment-candidate: 80 ``` ## Greedy 스케줄링 구조 핵심 파일: `PairingScheduleService` 1. `pairingCandidateService.generate` - 가능한 후보를 생성합니다. 2. `pairingMemberPairService.select` - 모든 위원을 먼저 조편성합니다. 3. `assignRemainingCenters` - 후보가 적은 센터부터 선택합니다. - 해당 센터에 가능한 후보 중 점수가 가장 높은 후보를 배정합니다. 4. `repairUnassignedCenters` - 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다. 5. `repairLowVisitMembers` - 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다. 6. `repairByDonorSwap` - 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다. 7. `repairWildcardFallbackCenters` - 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다. ## OR-Tools CP-SAT 설명 사용 라이브러리: ```gradle implementation("com.google.ortools:ortools-java:9.15.6755") ``` CP-SAT는 "조건을 모두 지키면서 가장 점수가 높은 조합을 찾는 도구"입니다. 예를 들어 `A조가 2026-05-01에 100번 센터를 방문한다`라는 후보가 있으면, CP-SAT 안에서는 이 후보가 0/1 변수 하나가 됩니다. ```text 1 = 이 후보를 선택한다 0 = 이 후보를 선택하지 않는다 ``` 현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 CP-SAT만으로는 시간이 오래 걸릴 수 있습니다. 그래서 주 배정은 Greedy가 담당하고, CP-SAT 코드는 향후 부분 최적화나 비교 실험을 위해 유지합니다. CP-SAT 관련 수정 위치: | 변경 내용 | 수정 위치 | | --- | --- | | 후보 0/1 변수 | `PairingSolverService#createAssignmentVars` | | 센터 중복 금지 | `PairingSolverService#addCenterAssignedAtMostOnce` | | 하루 방문 센터 수 | `PairingSolverService#addPairDailyCapacity` | | 같은 날짜 위원 중복 금지 | `PairingSolverService#addMemberDailyOnePair` | | 인접지역 분류 제한 | `PairingSolverService#addPairDailyOneAdjacentClassification` | | 상대 파트너 수 제한 | `PairingSolverService#addCumulativeBuddyLimit` | | 점수 조정 | `PairingSolverService#createObjective` | ## 규칙 변경 시 수정 위치 | 업무 변경 | 수정 위치 | | --- | --- | | 엑셀 시트명 변경 | `PairingConstant` | | 엑셀 컬럼명 변경 | `dto.excel.input`, `dto.excel.output`의 `@ExcelColumn` | | 입력 정규화 변경 | `PairingNormalizeService` | | 공휴일/주말 정책 변경 | `PairingHolidayService`, `DatagoHolidayCache` | | 상피제 변경 | `PairingCandidateService#isConflictRegion`, `hasActivityRegion` | | 여성전용센터 정책 변경 | `PairingCandidateService#findCenterHardRuleReasons` | | 기방문센터 제외 정책 변경 | `PairingCandidateService#findCenterHardRuleReasons` | | 희망지역 00/99 해석 변경 | `PairingCandidateService#findPreferenceRank`, `findPreferenceMatchRule`, `matchesPreferenceRank` | | wildcard 적극 사용 롤백 | `application.yaml`의 `active-wildcard-fallback-enabled: false` | | 위원당 상대 파트너 수 변경 | `application.yaml`의 `max-counterparts-per-member` | | 하루 센터 방문 수 변경 | `application.yaml`의 `max-centers-per-pair-per-day` | | 위원 최대 방문 상한 변경 | `application.yaml`의 `max-member-visit-average-ratio-percent` | | 배정 점수 튜닝 | `application.yaml`의 `objective.*` | | repair 전략 변경 | `PairingScheduleService`의 `repair...` 메서드 | ## 테스트 컴파일: ```powershell .\gradlew.bat compileJava ``` 전체 테스트: ```powershell .\gradlew.bat test ``` 샘플 엑셀 기반 테스트: ```powershell .\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest ``` 결과 파일은 테스트 실행 시 `build/pairing-result*.xlsx`로 생성됩니다.