260420_01_ENH: split 마감
This commit is contained in:
449
README.md
449
README.md
@@ -1,336 +1,201 @@
|
||||
# ncrc-pairing
|
||||
|
||||
엑셀 파일을 입력받아 위원 페어 후보와 센터 배정 후보를 만들고, Google OR-Tools CP-SAT으로 배정 결과를 계산하는 Spring Boot API입니다.
|
||||
엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다.
|
||||
|
||||
현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 `PairingScheduleService`입니다.
|
||||
|
||||
## 실행 흐름
|
||||
|
||||
1. `PairingController`
|
||||
- `/api/v1/pairing/run`으로 엑셀 파일을 업로드받습니다.
|
||||
- 처리 결과를 엑셀 파일로 반환합니다.
|
||||
- 결과 엑셀 파일을 반환합니다.
|
||||
|
||||
2. `PairingService`
|
||||
- 전체 유스케이스 흐름을 순서대로 호출합니다.
|
||||
- `엑셀 읽기 -> 정규화 -> 공휴일 반영 -> 검증 -> 후보 생성 -> solver 실행 -> 결과 엑셀 생성`
|
||||
- 전체 유스케이스를 순서대로 호출합니다.
|
||||
- `엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성`
|
||||
|
||||
3. `PairingExcelService`
|
||||
- 입력 엑셀의 6개 시트를 `dto.excel` DTO로 읽습니다.
|
||||
- 결과 엑셀은 `배정결과`, `미배정센터`, `미사용위원`, `처리요약`, `AB페어목록`, `후보요약`, `검증오류`, `규칙위반검사` 시트로 씁니다.
|
||||
- `/run`에서 입력/검증 오류가 발생하면 오류 내용을 담은 엑셀 파일을 반환합니다.
|
||||
- 입력 엑셀 시트를 DTO로 읽습니다.
|
||||
- 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다.
|
||||
|
||||
4. `PairingNormalizeService`
|
||||
- 엑셀 문자열을 내부 모델로 변환합니다.
|
||||
- 날짜, CSV, 성별, 경력여부, 현장/외부 구분, 지역코드, 선호지역을 정리합니다.
|
||||
- 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다.
|
||||
|
||||
5. `PairingValidationService`
|
||||
- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표 등을 검증합니다.
|
||||
- 실패 시 `BusinessException.badRequest(code, message)`를 사용합니다.
|
||||
5. `PairingHolidayService`
|
||||
- `DatagoHolidayCache`를 통해 공휴일을 조회합니다.
|
||||
- 토/일은 `DatagoHolidayCache#getWeekend`에서 생성해 공통 불가능일로 합칩니다.
|
||||
- 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다.
|
||||
|
||||
6. `PairingHolidayService`
|
||||
- `DatagoExtentionApiClient.getHoliDayList(year)`로 국공휴일을 조회합니다.
|
||||
- 조회된 날짜는 모든 위원/지자체/센터에 공통 적용되는 진행 불가일자로 처리합니다.
|
||||
- 공휴일 목록은 `DatagoHolidayCache`에서 공용 `AbstractListCache` 기반으로 캐싱합니다.
|
||||
6. `PairingValidationService`
|
||||
- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다.
|
||||
- 검증 실패는 `BusinessException.badRequest(code, message)`를 사용합니다.
|
||||
|
||||
7. `PairingCandidateService`
|
||||
- solver가 선택할 수 있는 후보만 생성합니다.
|
||||
- 불가능한 조합은 이 단계에서 제거합니다.
|
||||
- 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다.
|
||||
- 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다.
|
||||
|
||||
8. `PairingSolverService`
|
||||
- OR-Tools CP-SAT 모델을 만들고 최적 배정을 계산합니다.
|
||||
8. `PairingMemberPairService`
|
||||
- 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다.
|
||||
- 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다.
|
||||
|
||||
## OR-Tools 사용 개요
|
||||
9. `PairingScheduleService`
|
||||
- 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
|
||||
- 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다.
|
||||
|
||||
현재 사용하는 라이브러리는 `com.google.ortools:ortools-java`입니다.
|
||||
10. `PairingSolverService`
|
||||
- 결과 DTO 생성과 규칙 위반 검사를 담당합니다.
|
||||
- CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다.
|
||||
|
||||
OR-Tools CP-SAT은 "조건을 만족하는 조합 중 점수가 가장 좋은 조합"을 찾는 최적화 solver입니다. 이 프로젝트에서는 각 배정 후보를 boolean 변수로 만듭니다.
|
||||
## 현재 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` |
|
||||
|
||||
```text
|
||||
2026-05-01에 fieldMember=100, externalMember=200 페어가 center=300을 방문한다
|
||||
## 현재 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
|
||||
```
|
||||
|
||||
solver 안에서는 이 후보가 하나의 `BoolVar`가 됩니다.
|
||||
## 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 = 이 후보를 선택하지 않는다
|
||||
```
|
||||
|
||||
`PairingSolverService`는 이런 boolean 변수들을 놓고 아래를 수행합니다.
|
||||
|
||||
- hard rule: 반드시 지켜야 하는 제약
|
||||
- soft rule: 지키면 점수가 좋아지는 목표
|
||||
|
||||
## 현재 적용된 Hard Rule
|
||||
|
||||
후보 생성 단계와 solver 단계에 나뉘어 적용되어 있습니다.
|
||||
|
||||
### 후보 생성 단계
|
||||
|
||||
위치: `PairingCandidateService`
|
||||
|
||||
- 현장위원 + 외부위원 페어만 생성
|
||||
- 신규 + 신규 페어 제외
|
||||
- 두 위원의 일정 범위가 겹치지 않으면 제외
|
||||
- 파견 권역이 위원의 활동지역과 같으면 제외
|
||||
- 희망지역 매칭표에 없는 선호 조합 제외
|
||||
- 센터 인접지역표를 통해 파견 권역과 센터 연결
|
||||
- 여성 전용 센터는 여성 2명 페어만 허용
|
||||
- 2023년 진행 센터는 해당 위원에게 재배정 금지
|
||||
- 위원/지자체/센터의 시작일, 종료일, 불가일자를 모두 반영
|
||||
- 국공휴일은 모든 배정 후보에서 제외
|
||||
|
||||
현재 후보 수 폭증을 막기 위해 각 페어/센터 조합에서 가장 빠른 feasible 일자 1개만 후보로 만듭니다.
|
||||
|
||||
### Solver 단계
|
||||
|
||||
위치: `PairingSolverService`
|
||||
|
||||
- 한 센터는 최대 1번만 배정
|
||||
- 한 페어는 하루 최대 3개 센터만 방문
|
||||
- 한 위원은 같은 날짜에 하나의 페어로만 활동
|
||||
- 한 페어는 같은 날짜에 하나의 인접지역 분류만 방문
|
||||
- 한 위원은 전체 기간 동안 최대 2명의 상대 파트너만 가짐
|
||||
|
||||
## 현재 적용된 Soft Rule
|
||||
|
||||
위치: `PairingSolverService#createObjective`
|
||||
|
||||
현재 목적함수는 아래 순서가 강하게 반영되도록 가중치를 둡니다.
|
||||
|
||||
1. 배정 센터 수 최대화
|
||||
2. 희망지역 매칭 순위가 좋은 후보 선호
|
||||
3. 거주지 앞 3자리 일치 페어 선호
|
||||
|
||||
배정 센터 수가 가장 중요하므로 가장 큰 가중치를 사용합니다. 선호도와 거주지 유사도는 배정 수가 같은 후보들 사이에서 더 나은 해를 고르는 보조 점수입니다. 현재 업무 기준상 거주지 유사도도 중요한 soft rule이지만, 배정 센터 수보다 우선하지는 않습니다.
|
||||
|
||||
## OR-Tools 관련 주요 파일
|
||||
|
||||
### `build.gradle`
|
||||
|
||||
OR-Tools 의존성을 관리합니다.
|
||||
|
||||
```gradle
|
||||
implementation("com.google.ortools:ortools-java:9.15.6755")
|
||||
```
|
||||
|
||||
OR-Tools 버전을 바꾸면 native library 로딩 방식이나 Java API가 바뀔 수 있으므로 `PairingSolverService` 컴파일과 테스트를 반드시 확인해야 합니다.
|
||||
|
||||
### `OrToolsConfig`
|
||||
|
||||
Spring Boot 기동 시 `Loader.loadNativeLibraries()`를 실행합니다.
|
||||
|
||||
OR-Tools는 Java 라이브러리처럼 보이지만 내부적으로 OS별 native library를 사용합니다. 이 로딩이 빠지면 `UnsatisfiedLinkError`가 발생합니다.
|
||||
|
||||
### `PairingSolverService`
|
||||
|
||||
실제 CP-SAT 모델을 구성합니다.
|
||||
|
||||
수정이 필요한 대표 위치:
|
||||
|
||||
- 변수 추가/변경: `createAssignmentVars`, `createPairUsedVars`, `createPairDayVars`
|
||||
- hard rule 추가: `add...` 형태의 constraint 메서드 추가
|
||||
- soft rule 변경: `createObjective`
|
||||
- solver 시간 제한 변경: `solver.getParameters().setMaxTimeInSeconds(...)`
|
||||
- 결과 해석 변경: `collectSelectedAssignments`, `toResult`
|
||||
|
||||
## 결과 엑셀 시트
|
||||
|
||||
정상 처리 결과는 항상 아래 8개 시트를 포함합니다.
|
||||
|
||||
- `배정결과`: 최종 센터 배정 결과와 위원/센터 주요 속성, AB 보완 페어 정보
|
||||
- `미배정센터`: 최종 배정되지 않은 센터와 누적 미배정 사유
|
||||
- `미사용위원`: 최종 배정에 포함되지 않은 위원
|
||||
- `처리요약`: 전체 입력/후보/배정/AB 그룹 요약
|
||||
- `AB페어목록`: 후처리로 묶인 AB 페어 그룹 목록
|
||||
- `후보요약`: 후보 생성 및 solver 입력 규모
|
||||
- `검증오류`: 정상 처리 시 빈 시트, 입력/검증 오류 엑셀에서는 오류 내용
|
||||
- `규칙위반검사`: 결과가 hard rule을 위반하지 않았는지 PASS/FAIL 검사
|
||||
|
||||
`/run`에서 엑셀 파싱이나 입력 검증 오류가 발생하면 HTTP 200으로 오류 엑셀을 반환합니다. 공휴일 API 실패 같은 시스템 오류는 숨기지 않고 실패 응답으로 처리합니다.
|
||||
|
||||
## 업무 조건 변경 시 수정 위치
|
||||
|
||||
### 자주 조정될 수 있는 값
|
||||
|
||||
아래 값들은 `application.yaml`의 `pairing.*` 설정으로 관리합니다.
|
||||
|
||||
```yaml
|
||||
pairing:
|
||||
excel:
|
||||
header-row-index: 1
|
||||
code:
|
||||
region-code-length: 2
|
||||
residence-code-length: 5
|
||||
residence-match-prefix-length: 3
|
||||
any-region-code: "00"
|
||||
rule:
|
||||
max-centers-per-pair-per-day: 3
|
||||
max-counterparts-per-member: 2
|
||||
preference:
|
||||
anywhere-rank: 0
|
||||
ignored-rank: 99
|
||||
objective:
|
||||
assignment-weight: 1000000
|
||||
preference-base-weight: 1000
|
||||
preference-rank-penalty: 100
|
||||
residence-match-weight: 10000
|
||||
solver:
|
||||
max-time-seconds: 30.0
|
||||
num-search-workers: 15
|
||||
```
|
||||
|
||||
배정 센터 수 최우선 원칙을 유지하려면 `objective.assignment-weight`가 선호지역, 거주지, 향후 추가될 soft score의 최대 합보다 충분히 커야 합니다.
|
||||
|
||||
### 엑셀 시트명 또는 컬럼명이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingConstant`
|
||||
- `dto.excel.*`
|
||||
- `PairingExcelService`
|
||||
|
||||
시트명이 바뀌면 `PairingConstant`의 `SHEET_*` 값을 수정합니다. 컬럼명이 바뀌면 해당 `dto.excel` 클래스의 `@ExcelColumn(header = "...")` 값을 수정합니다.
|
||||
|
||||
### 결과 엑셀 시트를 바꾸는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingConstant`
|
||||
- `dto.*ExcelDto`
|
||||
- `PairingExcelService#write`
|
||||
- `PairingSolverService#toResult`
|
||||
|
||||
### 지역 코드 자리수가 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingConstant`
|
||||
- `PairingNormalizeService`
|
||||
- `PairingCandidateService`
|
||||
|
||||
현재 활동지역/선호지역은 2자리, 거주지는 5자리, 거주지 비교는 앞 3자리 기준입니다.
|
||||
|
||||
### 선호지역 `00` 규칙이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingNormalizeService#normalizePreferenceRegions`
|
||||
- `PairingCandidateService#findPreferenceRank`
|
||||
|
||||
현재는 `00`이 나오면 그 위치와 뒤쪽 선호지역을 모두 `00`으로 처리합니다.
|
||||
|
||||
### 희망지역 매칭표 해석이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingCandidateService#findPreferenceRank`
|
||||
- `PairingCandidateService#findPreferenceMatchRule`
|
||||
- `PairingSolverService#createObjective`
|
||||
|
||||
현재는 현장위원 rank와 외부위원 rank를 구한 뒤, 엑셀의 `희망지역 매칭표`에서 매칭 순위를 찾습니다.
|
||||
|
||||
현재 rank 해석:
|
||||
|
||||
- `0`: 위원이 선호지역에 `00`을 입력한 anywhere 응답
|
||||
- `99`: 해당 위원의 선호지역을 고려하지 않는 wildcard 조건
|
||||
|
||||
### 하루 최대 센터 수가 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `application.yaml`의 `pairing.rule.max-centers-per-pair-per-day`
|
||||
- `PairingSolverService#addPairDailyCapacity`
|
||||
|
||||
### 한 위원의 상대 파트너 수 제한이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `application.yaml`의 `pairing.rule.max-counterparts-per-member`
|
||||
- `PairingSolverService#addBuddyLimit`
|
||||
|
||||
### 하루 1개 지역 제한 기준이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `AssignmentCandidate`
|
||||
- `PairingCandidateService#createAssignmentCandidates`
|
||||
- `PairingSolverService#addPairDailyOneAdjacentClassification`
|
||||
|
||||
현재는 `인접지역 분류` 기준입니다. 나중에 권역 단위로 바뀌면 `pairDayAdjacentKey`가 사용하는 값을 바꿔야 합니다.
|
||||
|
||||
### 불가일자 또는 일정 조건이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingNormalizeService#parseDateSet`
|
||||
- `PairingHolidayService`
|
||||
- `PairingCandidateService#findFirstAssignableDate`
|
||||
- `PairingCandidateService#isAvailableOn`
|
||||
|
||||
국공휴일 조회 방식이 바뀌면 `PairingHolidayService`와 `DatagoExtentionApiClient`를 함께 확인해야 합니다.
|
||||
캐시 동작을 바꾸려면 `DatagoHolidayCache`를 확인합니다.
|
||||
|
||||
### 여성 전용 센터 규칙이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingNormalizeService#parseBooleanFlag`
|
||||
- `PairingCandidateService#isAssignableCenter`
|
||||
|
||||
### 2023년 진행 센터 제외 규칙이 바뀌는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingNormalizeService#parseCsv`
|
||||
- `PairingCandidateService#isAssignableCenter`
|
||||
|
||||
### A/B pair 운영 로직을 추가하는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingCandidateService`
|
||||
- `PairingSolverService`
|
||||
- 필요 시 `model`에 `ABPairCandidate` 추가
|
||||
|
||||
현재 A/B pair는 solver 결과 후처리로 구성합니다. 같은 파견 권역과 같은 인접지역 분류를 공유하고, 배정 날짜가 겹치지 않는 페어끼리 `AB 그룹`으로 묶습니다. 이는 A/B가 완전 대체 전담 관계가 아니라, 각자 배정은 유지하되 유사시에 서로 공백을 보완할 수 있는 관계라는 업무 해석을 따른 것입니다.
|
||||
|
||||
### 인접지역 분류 랜덤 선택을 엄격하게 적용하는 경우
|
||||
|
||||
수정 위치:
|
||||
|
||||
- `PairingCandidateService#createAssignmentCandidates`
|
||||
- `PairingSolverService`
|
||||
- 별도 후처리 서비스 추가 가능
|
||||
|
||||
현재 solver는 랜덤 없이 최적 선택을 하며, 같은 날짜/페어에 대해 하나의 인접지역 분류만 선택하도록 hard rule을 걸고 있습니다. 따라서 한 팀이 여러 인접지역 분류 그룹을 갈 수 있는 경우에도 solver가 objective에 가장 유리한 하나의 그룹만 선택합니다.
|
||||
|
||||
## 현재 구현상 주의점
|
||||
|
||||
- 모든 가능한 날짜를 후보로 만들지 않고, 각 페어/센터 조합의 가장 빠른 feasible 일자만 후보로 만듭니다.
|
||||
- 이 방식은 후보 수를 줄여 빠르게 동작하지만, 날짜 선택 자유도가 낮아 실제 최적 배정률이 떨어질 수 있습니다.
|
||||
- 배정률이 부족하면 `PairingCandidateService#findFirstAssignableDate`를 확장해 feasible 일자 여러 개를 후보로 생성해야 합니다.
|
||||
- A/B pair는 현재 후처리 방식입니다. 배정 자체를 막는 hard constraint가 아니며, 결과 엑셀의 `AB 그룹`, `보완 현장위원 id`, `보완 외부위원 id` 컬럼으로 표시합니다.
|
||||
- 결과 엑셀은 성공 시 파일로 반환합니다. 입력/검증 오류는 오류 엑셀로 반환하고, 시스템 오류는 공통 `BusinessException` 실패 응답을 사용합니다.
|
||||
현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 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 clean test
|
||||
.\gradlew.bat test
|
||||
```
|
||||
|
||||
샘플 엑셀 전체 흐름 테스트:
|
||||
샘플 엑셀 기반 테스트:
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat test --tests "com.kri.p6.ncrc.pairing.service.PairingServiceTest.pairingMemberByCenterCreatesResultWorkbook"
|
||||
.\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest
|
||||
```
|
||||
|
||||
실제 API 실행 테스트:
|
||||
|
||||
```powershell
|
||||
.\gradlew.bat bootJar
|
||||
java -jar build/libs/ncrc-pairing-0.0.1-SNAPSHOT.jar
|
||||
curl.exe -X POST "http://localhost:6111/api/v1/pairing/run" -F "file=@src/main/resources/sample/기초 data dummy.xlsx" -o build/api-result.xlsx
|
||||
```
|
||||
결과 파일은 테스트 실행 시 `build/pairing-result*.xlsx`로 생성됩니다.
|
||||
|
||||
Reference in New Issue
Block a user