9.0 KiB
ncrc-pairing
엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다.
현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 PairingScheduleService입니다.
실행 흐름
-
PairingController/api/v1/pairing/run으로 엑셀 파일을 업로드받습니다.- 결과 엑셀 파일을 반환합니다.
-
PairingService- 전체 유스케이스를 순서대로 호출합니다.
엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성
-
PairingExcelService- 입력 엑셀 시트를 DTO로 읽습니다.
- 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다.
-
PairingNormalizeService- 엑셀 문자열을 내부 모델로 변환합니다.
- 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다.
-
PairingHolidayServiceDatagoHolidayCache를 통해 공휴일을 조회합니다.- 토/일은
DatagoHolidayCache#getWeekend에서 생성해 공통 불가능일로 합칩니다. - 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다.
-
PairingValidationService- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다.
- 검증 실패는
BusinessException.badRequest(code, message)를 사용합니다.
-
PairingCandidateService- 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다.
- 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다.
-
PairingMemberPairService- 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다.
- 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다.
-
PairingScheduleService- 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
- 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다.
-
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 우선순위
- 배정 센터 수 최대화
- 위원별 방문 수 균형
- 희망지역 매칭표 우선순위
- 희망지역 99 wildcard fallback
- 거주지 유사도
- 같은 조/같은 날짜/같은 인접지역 분류 재사용
관련 설정:
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
-
pairingCandidateService.generate- 가능한 후보를 생성합니다.
-
pairingMemberPairService.select- 모든 위원을 먼저 조편성합니다.
-
assignRemainingCenters- 후보가 적은 센터부터 선택합니다.
- 해당 센터에 가능한 후보 중 점수가 가장 높은 후보를 배정합니다.
-
repairUnassignedCenters- 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다.
-
repairLowVisitMembers- 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다.
-
repairByDonorSwap- 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다.
-
repairWildcardFallbackCenters- 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다.
OR-Tools CP-SAT 설명
사용 라이브러리:
implementation("com.google.ortools:ortools-java:9.15.6755")
CP-SAT는 "조건을 모두 지키면서 가장 점수가 높은 조합을 찾는 도구"입니다.
예를 들어 A조가 2026-05-01에 100번 센터를 방문한다라는 후보가 있으면, CP-SAT 안에서는 이 후보가 0/1 변수 하나가 됩니다.
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... 메서드 |
테스트
컴파일:
.\gradlew.bat compileJava
전체 테스트:
.\gradlew.bat test
샘플 엑셀 기반 테스트:
.\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest
결과 파일은 테스트 실행 시 build/pairing-result*.xlsx로 생성됩니다.