202 lines
9.0 KiB
Markdown
202 lines
9.0 KiB
Markdown
# 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`로 생성됩니다.
|