4 Commits

5 changed files with 329 additions and 254 deletions

459
README.md
View File

@@ -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`에서 행확장
- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
## 비고
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.

View File

@@ -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) {

View File

@@ -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"

Binary file not shown.

View File

@@ -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을 어느 수준까지 완화할 수 있는지"가 배정률 개선의 핵심입니다.