# ncrc-pairing 엑셀 파일을 입력받아 위원 페어 후보와 센터 배정 후보를 만들고, Google OR-Tools CP-SAT으로 배정 결과를 계산하는 Spring Boot API입니다. ## 실행 흐름 1. `PairingController` - `/api/v1/pairing/run`으로 엑셀 파일을 업로드받습니다. - 처리 결과를 엑셀 파일로 반환합니다. 2. `PairingService` - 전체 유스케이스 흐름을 순서대로 호출합니다. - `엑셀 읽기 -> 정규화 -> 공휴일 반영 -> 검증 -> 후보 생성 -> solver 실행 -> 결과 엑셀 생성` 3. `PairingExcelService` - 입력 엑셀의 6개 시트를 `dto.excel` DTO로 읽습니다. - 결과 엑셀은 `배정결과`, `미배정센터`, `미사용위원`, `처리요약`, `AB페어목록`, `후보요약`, `검증오류`, `규칙위반검사` 시트로 씁니다. - `/run`에서 입력/검증 오류가 발생하면 오류 내용을 담은 엑셀 파일을 반환합니다. 4. `PairingNormalizeService` - 엑셀 문자열을 내부 모델로 변환합니다. - 날짜, CSV, 성별, 경력여부, 현장/외부 구분, 지역코드, 선호지역을 정리합니다. 5. `PairingValidationService` - 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표 등을 검증합니다. - 실패 시 `BusinessException.badRequest(code, message)`를 사용합니다. 6. `PairingHolidayService` - `DatagoExtentionApiClient.getHoliDayList(year)`로 국공휴일을 조회합니다. - 조회된 날짜는 모든 위원/지자체/센터에 공통 적용되는 진행 불가일자로 처리합니다. - 공휴일 목록은 `DatagoHolidayCache`에서 공용 `AbstractListCache` 기반으로 캐싱합니다. 7. `PairingCandidateService` - solver가 선택할 수 있는 후보만 생성합니다. - 불가능한 조합은 이 단계에서 제거합니다. 8. `PairingSolverService` - OR-Tools CP-SAT 모델을 만들고 최적 배정을 계산합니다. ## OR-Tools 사용 개요 현재 사용하는 라이브러리는 `com.google.ortools:ortools-java`입니다. OR-Tools CP-SAT은 "조건을 만족하는 조합 중 점수가 가장 좋은 조합"을 찾는 최적화 solver입니다. 이 프로젝트에서는 각 배정 후보를 boolean 변수로 만듭니다. 예를 들어 어떤 후보가 다음 의미를 가진다고 하면: ```text 2026-05-01에 fieldMember=100, externalMember=200 페어가 center=300을 방문한다 ``` solver 안에서는 이 후보가 하나의 `BoolVar`가 됩니다. ```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` 실패 응답을 사용합니다. ## 테스트 전체 테스트: ```powershell .\gradlew.bat clean test ``` 샘플 엑셀 전체 흐름 테스트: ```powershell .\gradlew.bat test --tests "com.kri.p6.ncrc.pairing.service.PairingServiceTest.pairingMemberByCenterCreatesResultWorkbook" ``` 실제 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 ```