# ncrc-pairing 엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다. ## 개요 처리는 크게 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` 2. `PairingService#pairingMemberByCenterNew` 3. `PairingExcelService#read` 4. `PairingNormalizeService#normalize` 5. `PairingHolidayService#applyHolidayUnavailableDates` 6. `PairingValidationService#validate` 7. `PairingNewService#pair` 8. `PairingExcelService#writeNew` ## 입력 엑셀 시트 현재 필수 시트는 5개입니다. 1. `위원정보` 2. `지자체 정보` 3. `센터정보` 4. `센터 인접지역표` 5. `희망지역 매칭표` 더 이상 사용하지 않는 시트: - `위원 지역코드표` 현재 코드에서는 읽지 않습니다. ## 핵심 모델 ### Member 위원 기본 정보입니다. - 성별 - 경력 - 역할(현장 / 외부) - 가능 시작일 / 종료일 - 불가일 - 활동지역 - 2023년 진행 센터 이력 - 거주지 - 선호지역 1~4 ### NewCenter 센터와 지자체 정보를 합쳐 만든 센터 단위 모델입니다. - `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. 배정 가능한 인접지역 수 현재 코드 기준: ```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: 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 ``` 설명: - `header-row-index` - 엑셀 헤더 행 번호 - `region-code-length` - 활동지역 / 선호지역 / 파견권역 코드 정규화 길이 - `residence-code-length` - 거주지 코드 정규화 길이 - `any-region-code` - 선호지역의 `어디든 가능` 코드 - `anywhere-rank` - `00`이 희망지역 매칭표에서 의미하는 순위 - `ignored-rank` - 선호지역을 고려하지 않음을 의미하는 wildcard 순위 ## 공휴일 / 주말 처리 `PairingHolidayService`에서 공통 제외일을 만듭니다. 데이터 소스: - `DatagoHolidayCache` - `DatagoExtentionApiClient` 포함 범위: - 공휴일 - 토요일 - 일요일 이 값들은 `PairingData.commonUnavailableDates`로 들어가고, 이후 `NewAdjacentRegion.unavailableDates`에 합쳐집니다. ## 주요 클래스 ### Controller - [PairingController.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/controller/PairingController.java) ### Service - [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) ### Config - [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) ## 빌드 / 테스트 컴파일: ```powershell .\gradlew.bat compileJava compileTestJava ``` 테스트: ```powershell .\gradlew.bat test ``` 현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다. ## 유지보수 포인트 ### 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`에서 행확장 - 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다 ## 비고 - 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.