Files
ncrc-pairing/README.md

13 KiB

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 변수로 만듭니다.

예를 들어 어떤 후보가 다음 의미를 가진다고 하면:

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

현재 목적함수는 아래 순서가 강하게 반영되도록 가중치를 둡니다.

  1. 배정 센터 수 최대화
  2. 희망지역 매칭 순위가 좋은 후보 선호
  3. 거주지 앞 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의 최대 합보다 충분히 커야 합니다.

엑셀 시트명 또는 컬럼명이 바뀌는 경우

수정 위치:

  • 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 실패 응답을 사용합니다.

테스트

전체 테스트:

.\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