13 KiB
ncrc-pairing
엑셀 파일을 입력받아 위원 페어 후보와 센터 배정 후보를 만들고, Google OR-Tools CP-SAT으로 배정 결과를 계산하는 Spring Boot API입니다.
실행 흐름
-
PairingController/api/v1/pairing/run으로 엑셀 파일을 업로드받습니다.- 처리 결과를 엑셀 파일로 반환합니다.
-
PairingService- 전체 유스케이스 흐름을 순서대로 호출합니다.
엑셀 읽기 -> 정규화 -> 공휴일 반영 -> 검증 -> 후보 생성 -> solver 실행 -> 결과 엑셀 생성
-
PairingExcelService- 입력 엑셀의 6개 시트를
dto.excelDTO로 읽습니다. - 결과 엑셀은
배정결과,미배정센터,미사용위원,처리요약,AB페어목록,후보요약,검증오류,규칙위반검사시트로 씁니다. /run에서 입력/검증 오류가 발생하면 오류 내용을 담은 엑셀 파일을 반환합니다.
- 입력 엑셀의 6개 시트를
-
PairingNormalizeService- 엑셀 문자열을 내부 모델로 변환합니다.
- 날짜, CSV, 성별, 경력여부, 현장/외부 구분, 지역코드, 선호지역을 정리합니다.
-
PairingValidationService- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표 등을 검증합니다.
- 실패 시
BusinessException.badRequest(code, message)를 사용합니다.
-
PairingHolidayServiceDatagoExtentionApiClient.getHoliDayList(year)로 국공휴일을 조회합니다.- 조회된 날짜는 모든 위원/지자체/센터에 공통 적용되는 진행 불가일자로 처리합니다.
- 공휴일 목록은
DatagoHolidayCache에서 공용AbstractListCache기반으로 캐싱합니다.
-
PairingCandidateService- solver가 선택할 수 있는 후보만 생성합니다.
- 불가능한 조합은 이 단계에서 제거합니다.
-
PairingSolverService- OR-Tools CP-SAT 모델을 만들고 최적 배정을 계산합니다.
OR-Tools 사용 개요
현재 사용하는 라이브러리는 com.google.ortools:ortools-java입니다.
OR-Tools CP-SAT은 "조건을 만족하는 조합 중 점수가 가장 좋은 조합"을 찾는 최적화 solver입니다. 이 프로젝트에서는 각 배정 후보를 boolean 변수로 만듭니다.
예를 들어 어떤 후보가 다음 의미를 가진다고 하면:
2026-05-01에 fieldMember=100, externalMember=200 페어가 center=300을 방문한다
solver 안에서는 이 후보가 하나의 BoolVar가 됩니다.
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
현재 목적함수는 아래 순서가 강하게 반영되도록 가중치를 둡니다.
- 배정 센터 수 최대화
- 희망지역 매칭 순위가 좋은 후보 선호
- 거주지 앞 3자리 일치 페어 선호
배정 센터 수가 가장 중요하므로 가장 큰 가중치를 사용합니다. 선호도와 거주지 유사도는 배정 수가 같은 후보들 사이에서 더 나은 해를 고르는 보조 점수입니다. 현재 업무 기준상 거주지 유사도도 중요한 soft rule이지만, 배정 센터 수보다 우선하지는 않습니다.
OR-Tools 관련 주요 파일
build.gradle
OR-Tools 의존성을 관리합니다.
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.* 설정으로 관리합니다.
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의 최대 합보다 충분히 커야 합니다.
엑셀 시트명 또는 컬럼명이 바뀌는 경우
수정 위치:
PairingConstantdto.excel.*PairingExcelService
시트명이 바뀌면 PairingConstant의 SHEET_* 값을 수정합니다. 컬럼명이 바뀌면 해당 dto.excel 클래스의 @ExcelColumn(header = "...") 값을 수정합니다.
결과 엑셀 시트를 바꾸는 경우
수정 위치:
PairingConstantdto.*ExcelDtoPairingExcelService#writePairingSolverService#toResult
지역 코드 자리수가 바뀌는 경우
수정 위치:
PairingConstantPairingNormalizeServicePairingCandidateService
현재 활동지역/선호지역은 2자리, 거주지는 5자리, 거주지 비교는 앞 3자리 기준입니다.
선호지역 00 규칙이 바뀌는 경우
수정 위치:
PairingNormalizeService#normalizePreferenceRegionsPairingCandidateService#findPreferenceRank
현재는 00이 나오면 그 위치와 뒤쪽 선호지역을 모두 00으로 처리합니다.
희망지역 매칭표 해석이 바뀌는 경우
수정 위치:
PairingCandidateService#findPreferenceRankPairingCandidateService#findPreferenceMatchRulePairingSolverService#createObjective
현재는 현장위원 rank와 외부위원 rank를 구한 뒤, 엑셀의 희망지역 매칭표에서 매칭 순위를 찾습니다.
현재 rank 해석:
0: 위원이 선호지역에00을 입력한 anywhere 응답99: 해당 위원의 선호지역을 고려하지 않는 wildcard 조건
하루 최대 센터 수가 바뀌는 경우
수정 위치:
application.yaml의pairing.rule.max-centers-per-pair-per-dayPairingSolverService#addPairDailyCapacity
한 위원의 상대 파트너 수 제한이 바뀌는 경우
수정 위치:
application.yaml의pairing.rule.max-counterparts-per-memberPairingSolverService#addBuddyLimit
하루 1개 지역 제한 기준이 바뀌는 경우
수정 위치:
AssignmentCandidatePairingCandidateService#createAssignmentCandidatesPairingSolverService#addPairDailyOneAdjacentClassification
현재는 인접지역 분류 기준입니다. 나중에 권역 단위로 바뀌면 pairDayAdjacentKey가 사용하는 값을 바꿔야 합니다.
불가일자 또는 일정 조건이 바뀌는 경우
수정 위치:
PairingNormalizeService#parseDateSetPairingHolidayServicePairingCandidateService#findFirstAssignableDatePairingCandidateService#isAvailableOn
국공휴일 조회 방식이 바뀌면 PairingHolidayService와 DatagoExtentionApiClient를 함께 확인해야 합니다.
캐시 동작을 바꾸려면 DatagoHolidayCache를 확인합니다.
여성 전용 센터 규칙이 바뀌는 경우
수정 위치:
PairingNormalizeService#parseBooleanFlagPairingCandidateService#isAssignableCenter
2023년 진행 센터 제외 규칙이 바뀌는 경우
수정 위치:
PairingNormalizeService#parseCsvPairingCandidateService#isAssignableCenter
A/B pair 운영 로직을 추가하는 경우
수정 위치:
PairingCandidateServicePairingSolverService- 필요 시
model에ABPairCandidate추가
현재 A/B pair는 solver 결과 후처리로 구성합니다. 같은 파견 권역과 같은 인접지역 분류를 공유하고, 배정 날짜가 겹치지 않는 페어끼리 AB 그룹으로 묶습니다. 이는 A/B가 완전 대체 전담 관계가 아니라, 각자 배정은 유지하되 유사시에 서로 공백을 보완할 수 있는 관계라는 업무 해석을 따른 것입니다.
인접지역 분류 랜덤 선택을 엄격하게 적용하는 경우
수정 위치:
PairingCandidateService#createAssignmentCandidatesPairingSolverService- 별도 후처리 서비스 추가 가능
현재 solver는 랜덤 없이 최적 선택을 하며, 같은 날짜/페어에 대해 하나의 인접지역 분류만 선택하도록 hard rule을 걸고 있습니다. 따라서 한 팀이 여러 인접지역 분류 그룹을 갈 수 있는 경우에도 solver가 objective에 가장 유리한 하나의 그룹만 선택합니다.
현재 구현상 주의점
- 모든 가능한 날짜를 후보로 만들지 않고, 각 페어/센터 조합의 가장 빠른 feasible 일자만 후보로 만듭니다.
- 이 방식은 후보 수를 줄여 빠르게 동작하지만, 날짜 선택 자유도가 낮아 실제 최적 배정률이 떨어질 수 있습니다.
- 배정률이 부족하면
PairingCandidateService#findFirstAssignableDate를 확장해 feasible 일자 여러 개를 후보로 생성해야 합니다. - A/B pair는 현재 후처리 방식입니다. 배정 자체를 막는 hard constraint가 아니며, 결과 엑셀의
AB 그룹,보완 현장위원 id,보완 외부위원 id컬럼으로 표시합니다. - 결과 엑셀은 성공 시 파일로 반환합니다. 입력/검증 오류는 오류 엑셀로 반환하고, 시스템 오류는 공통
BusinessException실패 응답을 사용합니다.
테스트
전체 테스트:
.\gradlew.bat clean test
샘플 엑셀 전체 흐름 테스트:
.\gradlew.bat test --tests "com.kri.p6.ncrc.pairing.service.PairingServiceTest.pairingMemberByCenterCreatesResultWorkbook"
실제 API 실행 테스트:
.\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