diff --git a/README.md b/README.md index deafe98..fb26685 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,374 @@ # 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= +``` + +정상 처리 시 결과 엑셀을 반환합니다. +검증 실패 시에도 공통 `BusinessException` 내용을 담은 오류 엑셀을 반환합니다. + +## 전체 처리 흐름 + +현재 실제 구동 순서는 아래와 같습니다. 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` - - 입력 엑셀 시트를 DTO로 읽습니다. - - 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다. +현재 필수 시트는 5개입니다. -4. `PairingNormalizeService` - - 엑셀 문자열을 내부 모델로 변환합니다. - - 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다. +1. `위원정보` +2. `지자체 정보` +3. `센터정보` +4. `센터 인접지역표` +5. `희망지역 매칭표` -5. `PairingHolidayService` - - `DatagoHolidayCache`를 통해 공휴일을 조회합니다. - - 토/일은 `DatagoHolidayCache#getWeekend`에서 생성해 공통 불가능일로 합칩니다. - - 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다. +더 이상 사용하지 않는 시트: -6. `PairingValidationService` - - 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다. - - 검증 실패는 `BusinessException.badRequest(code, message)`를 사용합니다. +- `위원 지역코드표` -7. `PairingCandidateService` - - 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다. - - 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다. +현재 코드에서는 읽지 않습니다. -8. `PairingMemberPairService` - - 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다. - - 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다. +## 핵심 모델 -9. `PairingScheduleService` - - 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다. - - 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다. +### Member -10. `PairingSolverService` - - 결과 DTO 생성과 규칙 위반 검사를 담당합니다. - - CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다. +위원 기본 정보입니다. -## 현재 Hard Rule +- 성별 +- 경력 +- 역할(현장 / 외부) +- 가능 시작일 / 종료일 +- 불가일 +- 활동지역 +- 2023년 진행 센터 이력 +- 거주지 +- 선호지역 1~4 -| 규칙 | 구현 위치 | -| --- | --- | -| 모든 위원은 최소 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` | +### NewCenter -## 현재 Soft Rule 우선순위 +센터와 지자체 정보를 합쳐 만든 센터 단위 모델입니다. -1. 배정 센터 수 최대화 -2. 위원별 방문 수 균형 -3. 희망지역 매칭표 우선순위 -4. 희망지역 99 wildcard fallback +- `availableStartDate`: 센터 시작일과 지자체 시작일 중 더 늦은 값 +- `availableEndDate`: 센터 종료일과 지자체 종료일 중 더 이른 값 +- `unavailableDates`: 센터 불가일 + 지자체 불가일 + +### 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. 거주지 유사도 -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 pairing: - rule: - max-centers-per-pair-per-day: 3 - max-counterparts-per-member: 3 - max-member-visit-average-ratio-percent: 130 + excel: + header-row-index: 1 + code: + region-code-length: 2 + residence-code-length: 5 + any-region-code: "00" 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` +- `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` - - 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다. +- `DatagoHolidayCache` +- `DatagoExtentionApiClient` -5. `repairLowVisitMembers` - - 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다. +포함 범위: -6. `repairByDonorSwap` - - 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다. +- 공휴일 +- 토요일 +- 일요일 -7. `repairWildcardFallbackCenters` - - 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다. +이 값들은 `PairingData.commonUnavailableDates`로 들어가고, 이후 `NewAdjacentRegion.unavailableDates`에 합쳐집니다. -## OR-Tools CP-SAT 설명 +## 주요 클래스 -사용 라이브러리: +### Controller -```gradle -implementation("com.google.ortools:ortools-java:9.15.6755") -``` +- [PairingController.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/controller/PairingController.java) -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 -1 = 이 후보를 선택한다 -0 = 이 후보를 선택하지 않는다 -``` +### Config -현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 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 -.\gradlew.bat compileJava +.\gradlew.bat compileJava compileTestJava ``` -전체 테스트: +테스트: ```powershell .\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`에서 행확장 +- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다 + +## 비고 + +- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다. diff --git a/src/main/resources/sample/배정_규칙_및_완화_검토.md b/src/main/resources/sample/배정_규칙_및_완화_검토.md deleted file mode 100644 index c9609e3..0000000 --- a/src/main/resources/sample/배정_규칙_및_완화_검토.md +++ /dev/null @@ -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을 어느 수준까지 완화할 수 있는지"가 배정률 개선의 핵심입니다.