10 KiB
ncrc-pairing
엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다.
개요
처리는 크게 2단계입니다.
- 현장위원 100명과 외부위원 100명을 1:1 페어로 매칭
- 생성된 페어를 사용해 인접지역분류 단위로 최종 배정
배정 결과는 엑셀로 반환합니다.
실행 환경
- Java 17
- Spring Boot 3.5.x
- Gradle
기본 포트:
server:
port: 6111
API
엔드포인트:
POST /api/v1/pairing/run/new
Content-Type: multipart/form-data
file=<xlsx 파일>
정상 처리 시 결과 엑셀을 반환합니다.
검증 실패 시에도 공통 BusinessException 내용을 담은 오류 엑셀을 반환합니다.
전체 처리 흐름
현재 실제 구동 순서는 아래와 같습니다.
PairingControllerPairingService#pairingMemberByCenterNewPairingExcelService#readPairingNormalizeService#normalizePairingHolidayService#applyHolidayUnavailableDatesPairingValidationService#validatePairingNewService#pairPairingExcelService#writeNew
입력 엑셀 시트
현재 필수 시트는 5개입니다.
위원정보지자체 정보센터정보센터 인접지역표희망지역 매칭표
더 이상 사용하지 않는 시트:
위원 지역코드표
현재 코드에서는 읽지 않습니다.
핵심 모델
Member
위원 기본 정보입니다.
- 성별
- 경력
- 역할(현장 / 외부)
- 가능 시작일 / 종료일
- 불가일
- 활동지역
- 2023년 진행 센터 이력
- 거주지
- 선호지역 1~4
NewCenter
센터와 지자체 정보를 합쳐 만든 센터 단위 모델입니다.
availableStartDate: 센터 시작일과 지자체 시작일 중 더 늦은 값availableEndDate: 센터 종료일과 지자체 종료일 중 더 이른 값unavailableDates: 센터 불가일 + 지자체 불가일
NewAdjacentRegion
실제 배정의 기본 단위입니다.
- 기준:
dispatchRegion + adjacentRegionClassification - 포함 센터: 같은
adjacentRegionClassification을 가진 센터 묶음 womenOnly: 포함 센터 중 하나라도 여성전용이면trueavailableStartDate: 포함 센터들의 시작일 중 가장 늦은 값availableEndDate: 포함 센터들의 종료일 중 가장 이른 값unavailableDates: 포함 센터들의 불가일 합집합 + 공통 제외일(토/일/공휴일)
주의:
센터 인접지역표의dispatchRegion셀에는12,15,16처럼 여러 코드가 들어올 수 있습니다.- 현재는 정규화 단계에서 이 값을 행확장합니다.
- 예:
dispatchRegion=12,15,16,adjacentRegionClassification=A001(12, A001)(15, A001)(16, A001)
페어 생성 규칙
페어 생성은 PairingNewService에서 처리합니다.
하드룰
- 현장위원 수와 외부위원 수는 같아야 함
- 모든 현장위원과 모든 외부위원이 정확히 1:1로 사용되어야 함
신규 + 신규페어는 금지
페어 점수 기준
현재 페어 점수는 아래 항목으로 계산합니다.
- 활동지역 겹침 수
- 공통 가능일 수
- 선호지역 겹침 수
- 2023년 진행 센터 이력 점수
- 거주지 유사도
- 배정 가능한 인접지역 수
현재 코드 기준:
private static final boolean USE_AVAILABLE_ADJACENT_REGION_IN_PAIR_SCORE = true;
즉, 배정 가능한 인접지역 수가 많은 페어가 페어 생성 단계의 점수에도 반영됩니다.
추가로 생성된 페어는 아래 기준으로 다시 정렬됩니다.
- 배정 가능 인접지역 수 오름차순
- 중복제거 가능 날짜 수 오름차순
- 페어 점수 내림차순
- 현장위원 id
- 외부위원 id
이 정렬 순서는 이후 최종 배정 순서에도 영향을 줍니다.
최종 배정 규칙
최종 배정은 PairingNewService#assignAdjacentRegions에서 처리합니다.
기본 개념은 단순 그리디입니다.
- 정렬된 페어를 앞에서부터 순회
- 각 페어가 갈 수 있는 인접지역분류 후보를 찾음
희망지역 매칭표순위가 가장 높은 후보부터 선택- 배정 직후 그 페어의 해당 날짜를 사용 처리
- 이미 배정된 인접지역분류는 다시 배정하지 않음
- 더 이상 배정할 수 없을 때까지 반복
최종 배정 하드룰
현재 코드에서 적용되는 하드룰은 아래와 같습니다.
- 같은 페어는 같은 날짜에 하나의 인접지역분류만 방문 가능
- 같은 인접지역분류는 한 번만 배정 가능
- 위원 가능일 / 지자체 가능일 / 센터 가능일 범위를 만족해야 함
- 위원 불가일 / 센터 불가일 / 지자체 불가일 / 토요일 / 일요일 / 공휴일은 제외
- 상피제 적용
- 현장위원 또는 외부위원의 활동지역에 해당
dispatchRegion이 있으면 배정 불가
- 현장위원 또는 외부위원의 활동지역에 해당
- 여성전용 인접지역은 여성 + 여성 페어만 가능
- 2023년 진행 센터 이력이 포함된 인접지역은 배정 불가
- 희망지역 매칭표 조합에 맞는 경우만 후보 인정
규칙검사 시트
결과 엑셀의 규칙검사 시트에는 현재 아래 항목을 검사합니다.
- 현장위원 전체 사용
- 외부위원 전체 사용
- 1:1 페어 수
- 신규+신규 페어 금지
- 페어별 하루 하나의 인접지역
- 인접지역 분류 중복 배정 금지
- 가능 날짜/불가일 준수
- 상피제 준수
- 여성위원만 조건 준수
- 2023년 진행 센터 재배정 제외
- 희망지역 매칭표 조합 준수
위반 시 FAIL과 상세 내역을 기록합니다.
결과 엑셀 시트
현재 결과 시트 순서는 아래와 같습니다.
페어결과최종 배정최종 배정 with 센터인접지역목록센터목록페어후보요약페어점수계산규칙검사
1. 페어결과
생성된 1:1 페어 목록입니다.
포함 정보:
- 페어번호
- 현장위원 / 외부위원 id
- 성별 / 경력 / 활동지역 / 거주지
- 2023년 진행 센터
- 배정 가능 인접지역 수
- 중복제거 가능 날짜 수
- 총점 및 각 점수 항목
2. 최종 배정
인접지역분류 단위 배정 결과입니다.
포함 정보:
- 일자
- 페어번호
- 현장위원 id
- 외부위원 id
- 희망지역 매칭표 상의 순위
- 인접지역 분류
3. 최종 배정 with 센터
최종 배정을 센터 단위로 펼친 시트입니다.
포함 정보:
- 센터 id
- 지자체 id
- 인접지역 분류
- 여성위원만
- 센터+지자체 시작일
- 센터+지자체 종료일
- 센터+지자체 불가일
- 일자
- 페어번호
- 현장위원 id
- 외부위원 id
- 희망지역 매칭표 상의 순위
- 인접지역 분류
설정값
현재 사용 중인 설정은 아래뿐입니다.
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-rank00이 희망지역 매칭표에서 의미하는 순위
ignored-rank- 선호지역을 고려하지 않음을 의미하는 wildcard 순위
공휴일 / 주말 처리
PairingHolidayService에서 공통 제외일을 만듭니다.
데이터 소스:
DatagoHolidayCacheDatagoExtentionApiClient
포함 범위:
- 공휴일
- 토요일
- 일요일
이 값들은 PairingData.commonUnavailableDates로 들어가고, 이후 NewAdjacentRegion.unavailableDates에 합쳐집니다.
주요 클래스
Controller
Service
- PairingService.java
- PairingExcelService.java
- PairingNormalizeService.java
- PairingHolidayService.java
- PairingValidationService.java
- PairingNewService.java
Config
빌드 / 테스트
컴파일:
.\gradlew.bat compileJava compileTestJava
테스트:
.\gradlew.bat test
현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다.
유지보수 포인트
1. 새 시트가 추가될 때
- 입력 시트라면
PairingExcelService#read - 정규화가 필요하면
PairingNormalizeService - 검증이 필요하면
PairingValidationService
2. 최종 배정 규칙이 바뀔 때
- 대부분 PairingNewService.java 수정
- 페어 생성 규칙 변경
matchMemberscreatePairCandidatesscorePair
- 최종 배정 규칙 변경
assignAdjacentRegionsfindBestAssignmentChoicefirstAvailableDateForRegion
3. 규칙검사 기준이 바뀔 때
createRuleCheckscreateAssignmentRuleChecks
4. dispatchRegion 복수 입력 형식이 바뀔 때
- 현재는
PairingNormalizeService#toCenterAdjacentRegions에서 행확장 - 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
비고
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.