Compare commits
4 Commits
9d9736451f
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| d5160a50f0 | |||
| 6a31fedc64 | |||
| af92f18574 | |||
| 4c11636588 |
459
README.md
459
README.md
@@ -1,201 +1,374 @@
|
|||||||
# ncrc-pairing
|
# ncrc-pairing
|
||||||
|
|
||||||
엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다.
|
엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다.
|
||||||
|
|
||||||
현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 `PairingScheduleService`입니다.
|
## 개요
|
||||||
|
|
||||||
## 실행 흐름
|
처리는 크게 2단계입니다.
|
||||||
|
|
||||||
|
1. 현장위원 100명과 외부위원 100명을 1:1 페어로 매칭
|
||||||
|
2. 생성된 페어를 사용해 인접지역분류 단위로 최종 배정
|
||||||
|
|
||||||
|
배정 결과는 엑셀로 반환합니다.
|
||||||
|
|
||||||
|
## 실행 환경
|
||||||
|
|
||||||
|
- Java 17
|
||||||
|
- Spring Boot 3.5.x
|
||||||
|
- Gradle
|
||||||
|
|
||||||
|
기본 포트:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
server:
|
||||||
|
port: 6111
|
||||||
|
```
|
||||||
|
|
||||||
|
## API
|
||||||
|
|
||||||
|
엔드포인트:
|
||||||
|
|
||||||
|
```text
|
||||||
|
POST /api/v1/pairing/run/new
|
||||||
|
Content-Type: multipart/form-data
|
||||||
|
file=<xlsx 파일>
|
||||||
|
```
|
||||||
|
|
||||||
|
정상 처리 시 결과 엑셀을 반환합니다.
|
||||||
|
검증 실패 시에도 공통 `BusinessException` 내용을 담은 오류 엑셀을 반환합니다.
|
||||||
|
|
||||||
|
## 전체 처리 흐름
|
||||||
|
|
||||||
|
현재 실제 구동 순서는 아래와 같습니다.
|
||||||
|
|
||||||
1. `PairingController`
|
1. `PairingController`
|
||||||
- `/api/v1/pairing/run`으로 엑셀 파일을 업로드받습니다.
|
2. `PairingService#pairingMemberByCenterNew`
|
||||||
- 결과 엑셀 파일을 반환합니다.
|
3. `PairingExcelService#read`
|
||||||
|
4. `PairingNormalizeService#normalize`
|
||||||
|
5. `PairingHolidayService#applyHolidayUnavailableDates`
|
||||||
|
6. `PairingValidationService#validate`
|
||||||
|
7. `PairingNewService#pair`
|
||||||
|
8. `PairingExcelService#writeNew`
|
||||||
|
|
||||||
2. `PairingService`
|
## 입력 엑셀 시트
|
||||||
- 전체 유스케이스를 순서대로 호출합니다.
|
|
||||||
- `엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성`
|
|
||||||
|
|
||||||
3. `PairingExcelService`
|
현재 필수 시트는 5개입니다.
|
||||||
- 입력 엑셀 시트를 DTO로 읽습니다.
|
|
||||||
- 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다.
|
|
||||||
|
|
||||||
4. `PairingNormalizeService`
|
1. `위원정보`
|
||||||
- 엑셀 문자열을 내부 모델로 변환합니다.
|
2. `지자체 정보`
|
||||||
- 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다.
|
3. `센터정보`
|
||||||
|
4. `센터 인접지역표`
|
||||||
|
5. `희망지역 매칭표`
|
||||||
|
|
||||||
5. `PairingHolidayService`
|
더 이상 사용하지 않는 시트:
|
||||||
- `DatagoHolidayCache`를 통해 공휴일을 조회합니다.
|
|
||||||
- 토/일은 `DatagoHolidayCache#getWeekend`에서 생성해 공통 불가능일로 합칩니다.
|
|
||||||
- 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다.
|
|
||||||
|
|
||||||
6. `PairingValidationService`
|
- `위원 지역코드표`
|
||||||
- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다.
|
|
||||||
- 검증 실패는 `BusinessException.badRequest(code, message)`를 사용합니다.
|
|
||||||
|
|
||||||
7. `PairingCandidateService`
|
현재 코드에서는 읽지 않습니다.
|
||||||
- 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다.
|
|
||||||
- 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다.
|
|
||||||
|
|
||||||
8. `PairingMemberPairService`
|
## 핵심 모델
|
||||||
- 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다.
|
|
||||||
- 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다.
|
|
||||||
|
|
||||||
9. `PairingScheduleService`
|
### Member
|
||||||
- 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
|
|
||||||
- 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다.
|
|
||||||
|
|
||||||
10. `PairingSolverService`
|
위원 기본 정보입니다.
|
||||||
- 결과 DTO 생성과 규칙 위반 검사를 담당합니다.
|
|
||||||
- CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다.
|
|
||||||
|
|
||||||
## 현재 Hard Rule
|
- 성별
|
||||||
|
- 경력
|
||||||
|
- 역할(현장 / 외부)
|
||||||
|
- 가능 시작일 / 종료일
|
||||||
|
- 불가일
|
||||||
|
- 활동지역
|
||||||
|
- 2023년 진행 센터 이력
|
||||||
|
- 거주지
|
||||||
|
- 선호지역 1~4
|
||||||
|
|
||||||
| 규칙 | 구현 위치 |
|
### NewCenter
|
||||||
| --- | --- |
|
|
||||||
| 모든 위원은 최소 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. 배정 센터 수 최대화
|
- `availableStartDate`: 센터 시작일과 지자체 시작일 중 더 늦은 값
|
||||||
2. 위원별 방문 수 균형
|
- `availableEndDate`: 센터 종료일과 지자체 종료일 중 더 이른 값
|
||||||
3. 희망지역 매칭표 우선순위
|
- `unavailableDates`: 센터 불가일 + 지자체 불가일
|
||||||
4. 희망지역 99 wildcard fallback
|
|
||||||
|
### NewAdjacentRegion
|
||||||
|
|
||||||
|
실제 배정의 기본 단위입니다.
|
||||||
|
|
||||||
|
- 기준: `dispatchRegion + adjacentRegionClassification`
|
||||||
|
- 포함 센터: 같은 `adjacentRegionClassification`을 가진 센터 묶음
|
||||||
|
- `womenOnly`: 포함 센터 중 하나라도 여성전용이면 `true`
|
||||||
|
- `availableStartDate`: 포함 센터들의 시작일 중 가장 늦은 값
|
||||||
|
- `availableEndDate`: 포함 센터들의 종료일 중 가장 이른 값
|
||||||
|
- `unavailableDates`: 포함 센터들의 불가일 합집합 + 공통 제외일(토/일/공휴일)
|
||||||
|
|
||||||
|
주의:
|
||||||
|
|
||||||
|
- `센터 인접지역표`의 `dispatchRegion` 셀에는 `12,15,16`처럼 여러 코드가 들어올 수 있습니다.
|
||||||
|
- 현재는 정규화 단계에서 이 값을 행확장합니다.
|
||||||
|
- 예: `dispatchRegion=12,15,16`, `adjacentRegionClassification=A001`
|
||||||
|
- `(12, A001)`
|
||||||
|
- `(15, A001)`
|
||||||
|
- `(16, A001)`
|
||||||
|
|
||||||
|
## 페어 생성 규칙
|
||||||
|
|
||||||
|
페어 생성은 `PairingNewService`에서 처리합니다.
|
||||||
|
|
||||||
|
### 하드룰
|
||||||
|
|
||||||
|
1. 현장위원 수와 외부위원 수는 같아야 함
|
||||||
|
2. 모든 현장위원과 모든 외부위원이 정확히 1:1로 사용되어야 함
|
||||||
|
3. `신규 + 신규` 페어는 금지
|
||||||
|
|
||||||
|
### 페어 점수 기준
|
||||||
|
|
||||||
|
현재 페어 점수는 아래 항목으로 계산합니다.
|
||||||
|
|
||||||
|
1. 활동지역 겹침 수
|
||||||
|
2. 공통 가능일 수
|
||||||
|
3. 선호지역 겹침 수
|
||||||
|
4. 2023년 진행 센터 이력 점수
|
||||||
5. 거주지 유사도
|
5. 거주지 유사도
|
||||||
6. 같은 조/같은 날짜/같은 인접지역 분류 재사용
|
6. 배정 가능한 인접지역 수
|
||||||
|
|
||||||
관련 설정:
|
현재 코드 기준:
|
||||||
|
|
||||||
|
```java
|
||||||
|
private static final boolean USE_AVAILABLE_ADJACENT_REGION_IN_PAIR_SCORE = true;
|
||||||
|
```
|
||||||
|
|
||||||
|
즉, `배정 가능한 인접지역 수가 많은 페어`가 페어 생성 단계의 점수에도 반영됩니다.
|
||||||
|
|
||||||
|
추가로 생성된 페어는 아래 기준으로 다시 정렬됩니다.
|
||||||
|
|
||||||
|
1. 배정 가능 인접지역 수 오름차순
|
||||||
|
2. 중복제거 가능 날짜 수 오름차순
|
||||||
|
3. 페어 점수 내림차순
|
||||||
|
4. 현장위원 id
|
||||||
|
5. 외부위원 id
|
||||||
|
|
||||||
|
이 정렬 순서는 이후 최종 배정 순서에도 영향을 줍니다.
|
||||||
|
|
||||||
|
## 최종 배정 규칙
|
||||||
|
|
||||||
|
최종 배정은 `PairingNewService#assignAdjacentRegions`에서 처리합니다.
|
||||||
|
|
||||||
|
기본 개념은 단순 그리디입니다.
|
||||||
|
|
||||||
|
1. 정렬된 페어를 앞에서부터 순회
|
||||||
|
2. 각 페어가 갈 수 있는 인접지역분류 후보를 찾음
|
||||||
|
3. `희망지역 매칭표` 순위가 가장 높은 후보부터 선택
|
||||||
|
4. 배정 직후 그 페어의 해당 날짜를 사용 처리
|
||||||
|
5. 이미 배정된 인접지역분류는 다시 배정하지 않음
|
||||||
|
6. 더 이상 배정할 수 없을 때까지 반복
|
||||||
|
|
||||||
|
### 최종 배정 하드룰
|
||||||
|
|
||||||
|
현재 코드에서 적용되는 하드룰은 아래와 같습니다.
|
||||||
|
|
||||||
|
1. 같은 페어는 같은 날짜에 하나의 인접지역분류만 방문 가능
|
||||||
|
2. 같은 인접지역분류는 한 번만 배정 가능
|
||||||
|
3. 위원 가능일 / 지자체 가능일 / 센터 가능일 범위를 만족해야 함
|
||||||
|
4. 위원 불가일 / 센터 불가일 / 지자체 불가일 / 토요일 / 일요일 / 공휴일은 제외
|
||||||
|
5. 상피제 적용
|
||||||
|
- 현장위원 또는 외부위원의 활동지역에 해당 `dispatchRegion`이 있으면 배정 불가
|
||||||
|
6. 여성전용 인접지역은 여성 + 여성 페어만 가능
|
||||||
|
7. 2023년 진행 센터 이력이 포함된 인접지역은 배정 불가
|
||||||
|
8. 희망지역 매칭표 조합에 맞는 경우만 후보 인정
|
||||||
|
|
||||||
|
## 규칙검사 시트
|
||||||
|
|
||||||
|
결과 엑셀의 `규칙검사` 시트에는 현재 아래 항목을 검사합니다.
|
||||||
|
|
||||||
|
1. 현장위원 전체 사용
|
||||||
|
2. 외부위원 전체 사용
|
||||||
|
3. 1:1 페어 수
|
||||||
|
4. 신규+신규 페어 금지
|
||||||
|
5. 페어별 하루 하나의 인접지역
|
||||||
|
6. 인접지역 분류 중복 배정 금지
|
||||||
|
7. 가능 날짜/불가일 준수
|
||||||
|
8. 상피제 준수
|
||||||
|
9. 여성위원만 조건 준수
|
||||||
|
10. 2023년 진행 센터 재배정 제외
|
||||||
|
11. 희망지역 매칭표 조합 준수
|
||||||
|
|
||||||
|
위반 시 `FAIL`과 상세 내역을 기록합니다.
|
||||||
|
|
||||||
|
## 결과 엑셀 시트
|
||||||
|
|
||||||
|
현재 결과 시트 순서는 아래와 같습니다.
|
||||||
|
|
||||||
|
1. `페어결과`
|
||||||
|
2. `최종 배정`
|
||||||
|
3. `최종 배정 with 센터`
|
||||||
|
4. `인접지역목록`
|
||||||
|
5. `센터목록`
|
||||||
|
6. `페어후보요약`
|
||||||
|
7. `페어점수계산`
|
||||||
|
8. `규칙검사`
|
||||||
|
|
||||||
|
### 1. 페어결과
|
||||||
|
|
||||||
|
생성된 1:1 페어 목록입니다.
|
||||||
|
|
||||||
|
포함 정보:
|
||||||
|
|
||||||
|
- 페어번호
|
||||||
|
- 현장위원 / 외부위원 id
|
||||||
|
- 성별 / 경력 / 활동지역 / 거주지
|
||||||
|
- 2023년 진행 센터
|
||||||
|
- 배정 가능 인접지역 수
|
||||||
|
- 중복제거 가능 날짜 수
|
||||||
|
- 총점 및 각 점수 항목
|
||||||
|
|
||||||
|
### 2. 최종 배정
|
||||||
|
|
||||||
|
인접지역분류 단위 배정 결과입니다.
|
||||||
|
|
||||||
|
포함 정보:
|
||||||
|
|
||||||
|
- 일자
|
||||||
|
- 페어번호
|
||||||
|
- 현장위원 id
|
||||||
|
- 외부위원 id
|
||||||
|
- 희망지역 매칭표 상의 순위
|
||||||
|
- 인접지역 분류
|
||||||
|
|
||||||
|
### 3. 최종 배정 with 센터
|
||||||
|
|
||||||
|
최종 배정을 센터 단위로 펼친 시트입니다.
|
||||||
|
|
||||||
|
포함 정보:
|
||||||
|
|
||||||
|
- 센터 id
|
||||||
|
- 지자체 id
|
||||||
|
- 인접지역 분류
|
||||||
|
- 여성위원만
|
||||||
|
- 센터+지자체 시작일
|
||||||
|
- 센터+지자체 종료일
|
||||||
|
- 센터+지자체 불가일
|
||||||
|
- 일자
|
||||||
|
- 페어번호
|
||||||
|
- 현장위원 id
|
||||||
|
- 외부위원 id
|
||||||
|
- 희망지역 매칭표 상의 순위
|
||||||
|
- 인접지역 분류
|
||||||
|
|
||||||
|
## 설정값
|
||||||
|
|
||||||
|
현재 사용 중인 설정은 아래뿐입니다.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
pairing:
|
pairing:
|
||||||
rule:
|
excel:
|
||||||
max-centers-per-pair-per-day: 3
|
header-row-index: 1
|
||||||
max-counterparts-per-member: 3
|
code:
|
||||||
max-member-visit-average-ratio-percent: 130
|
region-code-length: 2
|
||||||
|
residence-code-length: 5
|
||||||
|
any-region-code: "00"
|
||||||
preference:
|
preference:
|
||||||
anywhere-rank: 0
|
anywhere-rank: 0
|
||||||
ignored-rank: 99
|
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`
|
- `header-row-index`
|
||||||
|
- 엑셀 헤더 행 번호
|
||||||
|
- `region-code-length`
|
||||||
|
- 활동지역 / 선호지역 / 파견권역 코드 정규화 길이
|
||||||
|
- `residence-code-length`
|
||||||
|
- 거주지 코드 정규화 길이
|
||||||
|
- `any-region-code`
|
||||||
|
- 선호지역의 `어디든 가능` 코드
|
||||||
|
- `anywhere-rank`
|
||||||
|
- `00`이 희망지역 매칭표에서 의미하는 순위
|
||||||
|
- `ignored-rank`
|
||||||
|
- 선호지역을 고려하지 않음을 의미하는 wildcard 순위
|
||||||
|
|
||||||
1. `pairingCandidateService.generate`
|
## 공휴일 / 주말 처리
|
||||||
- 가능한 후보를 생성합니다.
|
|
||||||
|
|
||||||
2. `pairingMemberPairService.select`
|
`PairingHolidayService`에서 공통 제외일을 만듭니다.
|
||||||
- 모든 위원을 먼저 조편성합니다.
|
|
||||||
|
|
||||||
3. `assignRemainingCenters`
|
데이터 소스:
|
||||||
- 후보가 적은 센터부터 선택합니다.
|
|
||||||
- 해당 센터에 가능한 후보 중 점수가 가장 높은 후보를 배정합니다.
|
|
||||||
|
|
||||||
4. `repairUnassignedCenters`
|
- `DatagoHolidayCache`
|
||||||
- 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다.
|
- `DatagoExtentionApiClient`
|
||||||
|
|
||||||
5. `repairLowVisitMembers`
|
포함 범위:
|
||||||
- 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다.
|
|
||||||
|
|
||||||
6. `repairByDonorSwap`
|
- 공휴일
|
||||||
- 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다.
|
- 토요일
|
||||||
|
- 일요일
|
||||||
|
|
||||||
7. `repairWildcardFallbackCenters`
|
이 값들은 `PairingData.commonUnavailableDates`로 들어가고, 이후 `NewAdjacentRegion.unavailableDates`에 합쳐집니다.
|
||||||
- 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다.
|
|
||||||
|
|
||||||
## OR-Tools CP-SAT 설명
|
## 주요 클래스
|
||||||
|
|
||||||
사용 라이브러리:
|
### Controller
|
||||||
|
|
||||||
```gradle
|
- [PairingController.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/controller/PairingController.java)
|
||||||
implementation("com.google.ortools:ortools-java:9.15.6755")
|
|
||||||
```
|
|
||||||
|
|
||||||
CP-SAT는 "조건을 모두 지키면서 가장 점수가 높은 조합을 찾는 도구"입니다.
|
### Service
|
||||||
|
|
||||||
예를 들어 `A조가 2026-05-01에 100번 센터를 방문한다`라는 후보가 있으면, CP-SAT 안에서는 이 후보가 0/1 변수 하나가 됩니다.
|
- [PairingService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingService.java)
|
||||||
|
- [PairingExcelService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingExcelService.java)
|
||||||
|
- [PairingNormalizeService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNormalizeService.java)
|
||||||
|
- [PairingHolidayService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingHolidayService.java)
|
||||||
|
- [PairingValidationService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingValidationService.java)
|
||||||
|
- [PairingNewService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNewService.java)
|
||||||
|
|
||||||
```text
|
### Config
|
||||||
1 = 이 후보를 선택한다
|
|
||||||
0 = 이 후보를 선택하지 않는다
|
|
||||||
```
|
|
||||||
|
|
||||||
현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 CP-SAT만으로는 시간이 오래 걸릴 수 있습니다. 그래서 주 배정은 Greedy가 담당하고, CP-SAT 코드는 향후 부분 최적화나 비교 실험을 위해 유지합니다.
|
- [PairingProperties.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/config/PairingProperties.java)
|
||||||
|
- [application.yaml](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/resources/application.yaml)
|
||||||
|
|
||||||
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
|
```powershell
|
||||||
.\gradlew.bat compileJava
|
.\gradlew.bat compileJava compileTestJava
|
||||||
```
|
```
|
||||||
|
|
||||||
전체 테스트:
|
테스트:
|
||||||
|
|
||||||
```powershell
|
```powershell
|
||||||
.\gradlew.bat test
|
.\gradlew.bat test
|
||||||
```
|
```
|
||||||
|
|
||||||
샘플 엑셀 기반 테스트:
|
현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다.
|
||||||
|
|
||||||
```powershell
|
## 유지보수 포인트
|
||||||
.\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest
|
|
||||||
```
|
|
||||||
|
|
||||||
결과 파일은 테스트 실행 시 `build/pairing-result*.xlsx`로 생성됩니다.
|
### 1. 새 시트가 추가될 때
|
||||||
|
|
||||||
|
- 입력 시트라면 `PairingExcelService#read`
|
||||||
|
- 정규화가 필요하면 `PairingNormalizeService`
|
||||||
|
- 검증이 필요하면 `PairingValidationService`
|
||||||
|
|
||||||
|
### 2. 최종 배정 규칙이 바뀔 때
|
||||||
|
|
||||||
|
- 대부분 [PairingNewService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNewService.java) 수정
|
||||||
|
- 페어 생성 규칙 변경
|
||||||
|
- `matchMembers`
|
||||||
|
- `createPairCandidates`
|
||||||
|
- `scorePair`
|
||||||
|
- 최종 배정 규칙 변경
|
||||||
|
- `assignAdjacentRegions`
|
||||||
|
- `findBestAssignmentChoice`
|
||||||
|
- `firstAvailableDateForRegion`
|
||||||
|
|
||||||
|
### 3. 규칙검사 기준이 바뀔 때
|
||||||
|
|
||||||
|
- `createRuleChecks`
|
||||||
|
- `createAssignmentRuleChecks`
|
||||||
|
|
||||||
|
### 4. dispatchRegion 복수 입력 형식이 바뀔 때
|
||||||
|
|
||||||
|
- 현재는 `PairingNormalizeService#toCenterAdjacentRegions`에서 행확장
|
||||||
|
- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
|
||||||
|
|
||||||
|
## 비고
|
||||||
|
|
||||||
|
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.
|
||||||
|
|||||||
@@ -43,7 +43,8 @@ public class PairingNormalizeService {
|
|||||||
.municipalities(workbookData.getMunicipalities().stream().map(this::toMunicipality).toList())
|
.municipalities(workbookData.getMunicipalities().stream().map(this::toMunicipality).toList())
|
||||||
.centers(workbookData.getCenters().stream().map(this::toCenter).toList())
|
.centers(workbookData.getCenters().stream().map(this::toCenter).toList())
|
||||||
.centerAdjacentRegions(workbookData.getCenterAdjacentRegions().stream()
|
.centerAdjacentRegions(workbookData.getCenterAdjacentRegions().stream()
|
||||||
.map(this::toCenterAdjacentRegion).toList())
|
.flatMap(row -> toCenterAdjacentRegions(row).stream())
|
||||||
|
.toList())
|
||||||
.preferenceMatchRules(workbookData.getPreferenceMatchRules().stream()
|
.preferenceMatchRules(workbookData.getPreferenceMatchRules().stream()
|
||||||
.map(this::toPreferenceMatchRule).toList())
|
.map(this::toPreferenceMatchRule).toList())
|
||||||
.commonUnavailableDates(Set.of())
|
.commonUnavailableDates(Set.of())
|
||||||
@@ -87,11 +88,14 @@ public class PairingNormalizeService {
|
|||||||
.build();
|
.build();
|
||||||
}
|
}
|
||||||
|
|
||||||
private CenterAdjacentRegion toCenterAdjacentRegion(CenterAdjacentRegionExcelDto row) {
|
private List<CenterAdjacentRegion> toCenterAdjacentRegions(CenterAdjacentRegionExcelDto row) {
|
||||||
return CenterAdjacentRegion.builder()
|
String adjacentRegionClassification = required(row.getAdjacentRegionClassification(), "인접지역 분류");
|
||||||
.dispatchRegion(normalizeCode(row.getDispatchRegion(), regionCodeLength(), "파견 권역"))
|
return parseCsv(row.getDispatchRegion()).stream()
|
||||||
.adjacentRegionClassification(required(row.getAdjacentRegionClassification(), "인접지역 분류"))
|
.map(dispatchRegion -> CenterAdjacentRegion.builder()
|
||||||
.build();
|
.dispatchRegion(normalizeCode(dispatchRegion, regionCodeLength(), "파견 권역"))
|
||||||
|
.adjacentRegionClassification(adjacentRegionClassification)
|
||||||
|
.build())
|
||||||
|
.toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
private PreferenceMatchRule toPreferenceMatchRule(PreferenceMatchExcelDto row) {
|
private PreferenceMatchRule toPreferenceMatchRule(PreferenceMatchExcelDto row) {
|
||||||
|
|||||||
@@ -29,6 +29,9 @@ kri:
|
|||||||
|
|
||||||
swagger:
|
swagger:
|
||||||
enabled: true
|
enabled: true
|
||||||
|
allowed-ips:
|
||||||
|
- 211.254.145.130
|
||||||
|
- 1.235.195.3
|
||||||
title: "KRI P6 NCRC Pairing API"
|
title: "KRI P6 NCRC Pairing API"
|
||||||
description: "아동권리보장원 조편성 API"
|
description: "아동권리보장원 조편성 API"
|
||||||
version: "v1.0.0"
|
version: "v1.0.0"
|
||||||
|
|||||||
BIN
src/main/resources/sample/기초 data TEST.xlsx
Normal file
BIN
src/main/resources/sample/기초 data TEST.xlsx
Normal file
Binary file not shown.
@@ -1,105 +0,0 @@
|
|||||||
# 배정 규칙 및 완화 검토 자료
|
|
||||||
|
|
||||||
이 문서는 개발자가 아닌 업무 담당자와 배정 기준을 논의하기 위한 설명 자료입니다.
|
|
||||||
|
|
||||||
현재 프로그램은 "모든 위원을 조편성한 뒤, 가능한 많은 센터를 일정표에 배정"하는 것을 목표로 합니다. 단, 일부 규칙은 반드시 지켜야 하므로 센터가 남을 수 있습니다.
|
|
||||||
|
|
||||||
## 용어 설명
|
|
||||||
|
|
||||||
| 용어 | 설명 |
|
|
||||||
| --- | --- |
|
|
||||||
| 현장위원/외부위원 | 한 조를 구성하는 두 역할입니다. 현재 기본 조는 현장위원 1명 + 외부위원 1명입니다. |
|
|
||||||
| 센터 배정 | 특정 날짜에 특정 조가 특정 센터를 방문하도록 정하는 것입니다. |
|
|
||||||
| 상피제 | 위원의 활동지역과 같은 파견 권역에는 배정하지 않는 규칙입니다. |
|
|
||||||
| 희망지역 00 | 어디든 가능하다는 응답입니다. |
|
|
||||||
| 희망지역 99 | 희망지역을 고려하지 않는다는 매칭표의 wildcard 규칙입니다. |
|
|
||||||
| Greedy | 그때그때 가장 좋아 보이는 선택을 빠르게 고르는 방식입니다. 사람으로 비유하면 "막히기 쉬운 센터부터 먼저 잡고, 가능한 후보 중 점수가 좋은 조를 넣는 방식"입니다. |
|
|
||||||
| CP-SAT | 여러 조건을 동시에 만족하는 조합을 찾는 최적화 도구입니다. 모든 후보를 놓고 수학적으로 좋은 조합을 찾지만, 후보가 많으면 시간이 오래 걸립니다. |
|
|
||||||
| repair pass | 1차 배정 후 남은 센터를 줄이기 위해 일부 배정을 빼고 다시 끼워 넣어 보는 후처리입니다. |
|
|
||||||
|
|
||||||
## 현재 처리 순서
|
|
||||||
|
|
||||||
1. 엑셀 파일을 읽습니다.
|
|
||||||
2. 날짜, 지역코드, 성별, 경력, 불가능일, 희망지역 등 입력값을 정리합니다.
|
|
||||||
3. 공휴일과 토/일을 공통 불가능일로 추가합니다.
|
|
||||||
4. 입력 데이터의 필수값과 참조 오류를 검증합니다.
|
|
||||||
5. 가능한 후보를 생성합니다.
|
|
||||||
6. 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 합니다.
|
|
||||||
7. 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
|
|
||||||
8. 미배정 센터를 줄이기 위해 후처리를 순서대로 수행합니다.
|
|
||||||
9. 결과 엑셀을 생성합니다.
|
|
||||||
|
|
||||||
## 현재 Hard Rule
|
|
||||||
|
|
||||||
Hard Rule은 반드시 지켜야 하는 규칙입니다. 이 규칙을 어기면서 센터를 더 배정하지 않습니다.
|
|
||||||
|
|
||||||
| 우선순위 | 규칙 | 설명 | 현재 완화 가능성 |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| 0 | 모든 위원 조편성 | 모든 위원은 최소 1개 이상의 조에 포함되어야 합니다. | 완화 불가 |
|
|
||||||
| 1 | 역할 조합 | 현장위원 1명 + 외부위원 1명으로 조를 구성합니다. | 낮음 |
|
|
||||||
| 2 | 위원 활동 가능 기간 | 두 위원의 활동 가능 기간이 겹쳐야 조 후보가 됩니다. | 낮음 |
|
|
||||||
| 3 | 날짜 불가 | 위원, 지자체, 센터의 불가능일에는 배정하지 않습니다. | 중간 |
|
|
||||||
| 4 | 공통 불가능일 | 공휴일과 토/일에는 배정하지 않습니다. | 중간 |
|
|
||||||
| 5 | 상피제 | 위원의 활동지역과 같은 파견 권역에는 배정하지 않습니다. | 높음 |
|
|
||||||
| 6 | 여성전용센터 | 여성전용센터는 여성 위원 2명 조만 배정합니다. | 중간 |
|
|
||||||
| 7 | 기방문센터 제외 | 2023년에 해당 위원이 진행한 센터는 제외합니다. | 높음 |
|
|
||||||
| 8 | 센터 중복 배정 금지 | 센터 1개는 결과에서 최대 1번만 배정됩니다. | 완화 불가 |
|
|
||||||
| 9 | 같은 날짜 위원 중복 금지 | 한 위원은 같은 날짜에 여러 조로 동시에 활동할 수 없습니다. | 낮음 |
|
|
||||||
| 10 | 같은 조의 하루 방문 상한 | 같은 조는 하루 최대 3개 센터까지 방문합니다. | 높음 |
|
|
||||||
| 11 | 같은 조/날짜의 인접지역 분류 | 같은 조가 같은 날짜에는 하나의 인접지역 분류만 방문합니다. | 높음 |
|
|
||||||
| 12 | 위원당 상대 파트너 수 | 위원 1명당 최대 3명의 상대 위원까지만 허용합니다. | 높음 |
|
|
||||||
| 13 | 위원별 최대 방문 상한 | 전체 센터가 모두 배정됐을 때의 평균 방문 수 대비 130%를 넘지 않게 합니다. | 높음 |
|
|
||||||
|
|
||||||
## 현재 Soft Rule
|
|
||||||
|
|
||||||
Soft Rule은 가능하면 지키는 규칙입니다. Hard Rule을 모두 지킨 후보 중에서 더 좋은 후보를 고르는 기준입니다.
|
|
||||||
|
|
||||||
| 우선순위 | 규칙 | 설명 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 1 | 배정 센터 수 최대화 | 가장 중요한 목표입니다. 희망지역 품질보다 센터를 더 많이 배정하는 것이 우선입니다. |
|
|
||||||
| 2 | 위원별 방문 수 균형 | 특정 위원에게 센터가 과도하게 몰리지 않도록 합니다. |
|
|
||||||
| 3 | 희망지역 매칭 품질 | 희망지역 매칭표의 우선순위가 좋은 후보를 선호합니다. |
|
|
||||||
| 4 | 희망지역 99 wildcard 활용 | 선호지역이 직접 맞지 않아도 "선호지역 고려하지 않음" 규칙으로 후보를 살릴 수 있습니다. 현재 옵션으로 켜져 있습니다. |
|
|
||||||
| 5 | 거주지 유사도 | 거주지 코드 앞 3자리, 없으면 2자리가 같은 조를 선호합니다. |
|
|
||||||
| 6 | 같은 조/같은 날짜 묶음 | 이미 같은 조가 같은 날짜에 같은 인접지역 분류를 방문한다면 추가 센터를 묶어서 배정하려고 합니다. |
|
|
||||||
|
|
||||||
## 후처리 방식
|
|
||||||
|
|
||||||
1차 Greedy 배정 후에도 남은 센터가 있으면 아래 순서로 다시 시도합니다.
|
|
||||||
|
|
||||||
| 순서 | 후처리 | 설명 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 1 | 일반 repair | 미배정 센터 하나를 넣기 위해 충돌되는 기존 배정을 최대 2개까지 빼고 다시 배정합니다. |
|
|
||||||
| 2 | 저방문 위원 중심 repair | 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 먼저 봅니다. |
|
|
||||||
| 3 | donor-swap repair | 방문 수가 많은 위원의 기존 배정을 빼고, 같은 센터를 저방문 위원이 포함된 조로 넘길 수 있는지 봅니다. |
|
|
||||||
| 4 | wildcard repair | 희망지역 99 wildcard로 살아난 후보를 남은 센터에 우선 적용해 봅니다. |
|
|
||||||
|
|
||||||
## Greedy와 CP-SAT의 현재 역할
|
|
||||||
|
|
||||||
현재 1차 배정은 Greedy 중심입니다.
|
|
||||||
|
|
||||||
Greedy는 빠르고 큰 데이터에 비교적 안정적으로 동작합니다. 대신 처음 선택한 조합이 뒤쪽 선택에 영향을 주므로, 항상 이론상 최적이라고 보장하지는 않습니다. 그래서 후처리 단계에서 일부 배정을 교환하면서 보정합니다.
|
|
||||||
|
|
||||||
CP-SAT는 조건을 모두 수학 모델로 만들어 더 좋은 조합을 찾는 방식입니다. 다만 후보 수가 커지면 시간이 매우 오래 걸리고 PC 사양 영향을 크게 받습니다. 현재 프로젝트에서는 CP-SAT 코드를 유지하되, 전체 배정의 중심은 Greedy로 옮겨 둔 상태입니다.
|
|
||||||
|
|
||||||
## 완화하면 미배정 센터가 늘어날 가능성이 큰 순서
|
|
||||||
|
|
||||||
아래 순서는 "센터 배정 수 증가 가능성" 기준입니다. 실제 정책적으로 허용 가능한지는 별도 협의가 필요합니다.
|
|
||||||
|
|
||||||
| 추천 순서 | 완화 대상 | 기대 효과 | 업무 리스크 |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| 1 | 위원별 최대 방문 상한 130% | 현재 max=24에서 더 많은 센터를 넣을 여지가 생깁니다. | 일부 위원에게 방문이 몰릴 수 있습니다. |
|
|
||||||
| 2 | 위원당 상대 파트너 수 3명 | 조 선택지가 늘어나 날짜/센터 후보가 크게 늘 수 있습니다. | 한 위원이 여러 사람과 조를 이루게 되어 운영 복잡도가 증가합니다. |
|
|
||||||
| 3 | 같은 조 하루 최대 3개 센터 | 같은 날짜에 더 많은 센터를 묶을 수 있습니다. | 이동 가능성, 업무 피로도 확인이 필요합니다. |
|
|
||||||
| 4 | 같은 조/날짜의 인접지역 분류 1개 제한 | 인접지역 분류가 다른 센터도 같은 날 묶을 수 있습니다. | 실제 이동 동선이 나빠질 수 있습니다. |
|
|
||||||
| 5 | 기방문센터 제외 | 특정 위원이 과거 방문한 센터도 다시 갈 수 있어 후보가 늘어납니다. | 기존 정책 취지와 충돌할 수 있습니다. |
|
|
||||||
| 6 | 상피제 | 활동지역과 파견 권역이 같은 경우도 허용하면 후보가 늘어납니다. | 이해충돌 방지 취지와 충돌할 수 있습니다. |
|
|
||||||
| 7 | 날짜 불가 일부 완화 | 위원/센터/지자체 일정 제약이 줄어듭니다. | 실제 운영 가능 여부 확인이 필요합니다. |
|
|
||||||
| 8 | 공휴일/토/일 배정 허용 | 날짜 후보가 늘어납니다. | 운영 정책상 허용 가능성이 낮습니다. |
|
|
||||||
| 9 | 여성전용센터 성별 조건 | 일부 센터 후보가 늘어납니다. | 정책 리스크가 큽니다. |
|
|
||||||
|
|
||||||
## 현재 결과 해석 시 주의점
|
|
||||||
|
|
||||||
미배정 센터가 남는다고 해서 희망지역만 문제라는 뜻은 아닙니다. 현재는 희망지역 99 wildcard도 사용하도록 열어 둔 상태입니다. 그래도 남는 센터는 날짜, 상피제, 성별, 기방문센터, 하루 방문 상한, 파트너 수, 방문 수 상한이 복합적으로 막고 있을 가능성이 큽니다.
|
|
||||||
|
|
||||||
따라서 클라이언트와 논의할 때는 "희망지역을 더 넓게 보는 것"보다 "어떤 Hard Rule을 어느 수준까지 완화할 수 있는지"가 배정률 개선의 핵심입니다.
|
|
||||||
Reference in New Issue
Block a user