Files
ncrc-pairing/README.md

9.0 KiB

ncrc-pairing

엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다.

현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 PairingScheduleService입니다.

실행 흐름

  1. PairingController

    • /api/v1/pairing/run으로 엑셀 파일을 업로드받습니다.
    • 결과 엑셀 파일을 반환합니다.
  2. PairingService

    • 전체 유스케이스를 순서대로 호출합니다.
    • 엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성
  3. PairingExcelService

    • 입력 엑셀 시트를 DTO로 읽습니다.
    • 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다.
  4. PairingNormalizeService

    • 엑셀 문자열을 내부 모델로 변환합니다.
    • 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다.
  5. PairingHolidayService

    • DatagoHolidayCache를 통해 공휴일을 조회합니다.
    • 토/일은 DatagoHolidayCache#getWeekend에서 생성해 공통 불가능일로 합칩니다.
    • 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다.
  6. PairingValidationService

    • 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다.
    • 검증 실패는 BusinessException.badRequest(code, message)를 사용합니다.
  7. PairingCandidateService

    • 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다.
    • 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다.
  8. PairingMemberPairService

    • 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다.
    • 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다.
  9. PairingScheduleService

    • 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
    • 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다.
  10. PairingSolverService

  • 결과 DTO 생성과 규칙 위반 검사를 담당합니다.
  • CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다.

현재 Hard Rule

규칙 구현 위치
모든 위원은 최소 1개 조에 포함 PairingMemberPairService, PairingSolverService#checkAllMembersUsed
현장위원 + 외부위원 조 구성 PairingCandidateService#createPairCandidates
위원 활동 가능 기간 겹침 PairingCandidateService#hasDateOverlap
상피제 PairingCandidateService#isConflictRegion
여성전용센터는 여성 2명 조만 허용 PairingCandidateService#findCenterHardRuleReasons
기방문센터 제외 PairingCandidateService#findCenterHardRuleReasons
위원/지자체/센터 불가능일 제외 PairingCandidateService#findAssignableDates, isAvailableOn
공휴일/토/일 제외 PairingHolidayService, DatagoHolidayCache, PairingCandidateService#commonUnavailableDates
센터 1개는 최대 1번 배정 PairingScheduleService#isFeasible, PairingSolverService#addCenterAssignedAtMostOnce
한 위원은 같은 날짜에 다른 조와 중복 활동 불가 PairingScheduleService#isFeasible, GreedyState#isMemberBusyWithOtherPair
같은 조는 하루 최대 N개 센터 방문 application.yaml, PairingScheduleService#isFeasible
같은 조/같은 날짜에는 하나의 인접지역 분류만 방문 PairingScheduleService#isFeasible, GreedyState#isAllowedAdjacentClassification
위원당 상대 파트너 수 최대 N명 application.yaml, PairingMemberPairService, PairingScheduleService#isFeasible
위원별 최대 방문 수 상한 application.yaml, PairingScheduleService#maxMemberVisitCount

현재 Soft Rule 우선순위

  1. 배정 센터 수 최대화
  2. 위원별 방문 수 균형
  3. 희망지역 매칭표 우선순위
  4. 희망지역 99 wildcard fallback
  5. 거주지 유사도
  6. 같은 조/같은 날짜/같은 인접지역 분류 재사용

관련 설정:

pairing:
  rule:
    max-centers-per-pair-per-day: 3
    max-counterparts-per-member: 3
    max-member-visit-average-ratio-percent: 130
  preference:
    anywhere-rank: 0
    ignored-rank: 99
    active-wildcard-fallback-enabled: true
    wildcard-fallback-score-bonus: 25_000
  objective:
    assignment-weight: 1_000_000
    member-balance-weight: 20_000
    preference-base-weight: 30_000
    preference-rank-penalty: 1_000
    residence-match-weight: 10_000
  candidate:
    max-pair-candidates-per-member: 0
    max-dispatch-regions-per-pair: 0
    max-assignments-per-center: 1_000
    max-assignments-per-member: 3_000
    max-dates-per-assignment-candidate: 80

Greedy 스케줄링 구조

핵심 파일: PairingScheduleService

  1. pairingCandidateService.generate

    • 가능한 후보를 생성합니다.
  2. pairingMemberPairService.select

    • 모든 위원을 먼저 조편성합니다.
  3. assignRemainingCenters

    • 후보가 적은 센터부터 선택합니다.
    • 해당 센터에 가능한 후보 중 점수가 가장 높은 후보를 배정합니다.
  4. repairUnassignedCenters

    • 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다.
  5. repairLowVisitMembers

    • 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다.
  6. repairByDonorSwap

    • 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다.
  7. repairWildcardFallbackCenters

    • 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다.

OR-Tools CP-SAT 설명

사용 라이브러리:

implementation("com.google.ortools:ortools-java:9.15.6755")

CP-SAT는 "조건을 모두 지키면서 가장 점수가 높은 조합을 찾는 도구"입니다.

예를 들어 A조가 2026-05-01에 100번 센터를 방문한다라는 후보가 있으면, CP-SAT 안에서는 이 후보가 0/1 변수 하나가 됩니다.

1 = 이 후보를 선택한다
0 = 이 후보를 선택하지 않는다

현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 CP-SAT만으로는 시간이 오래 걸릴 수 있습니다. 그래서 주 배정은 Greedy가 담당하고, CP-SAT 코드는 향후 부분 최적화나 비교 실험을 위해 유지합니다.

CP-SAT 관련 수정 위치:

변경 내용 수정 위치
후보 0/1 변수 PairingSolverService#createAssignmentVars
센터 중복 금지 PairingSolverService#addCenterAssignedAtMostOnce
하루 방문 센터 수 PairingSolverService#addPairDailyCapacity
같은 날짜 위원 중복 금지 PairingSolverService#addMemberDailyOnePair
인접지역 분류 제한 PairingSolverService#addPairDailyOneAdjacentClassification
상대 파트너 수 제한 PairingSolverService#addCumulativeBuddyLimit
점수 조정 PairingSolverService#createObjective

규칙 변경 시 수정 위치

업무 변경 수정 위치
엑셀 시트명 변경 PairingConstant
엑셀 컬럼명 변경 dto.excel.input, dto.excel.output의 @ExcelColumn
입력 정규화 변경 PairingNormalizeService
공휴일/주말 정책 변경 PairingHolidayService, DatagoHolidayCache
상피제 변경 PairingCandidateService#isConflictRegion, hasActivityRegion
여성전용센터 정책 변경 PairingCandidateService#findCenterHardRuleReasons
기방문센터 제외 정책 변경 PairingCandidateService#findCenterHardRuleReasons
희망지역 00/99 해석 변경 PairingCandidateService#findPreferenceRank, findPreferenceMatchRule, matchesPreferenceRank
wildcard 적극 사용 롤백 application.yaml의 active-wildcard-fallback-enabled: false
위원당 상대 파트너 수 변경 application.yaml의 max-counterparts-per-member
하루 센터 방문 수 변경 application.yaml의 max-centers-per-pair-per-day
위원 최대 방문 상한 변경 application.yaml의 max-member-visit-average-ratio-percent
배정 점수 튜닝 application.yaml의 objective.*
repair 전략 변경 PairingScheduleService의 repair... 메서드

테스트

컴파일:

.\gradlew.bat compileJava

전체 테스트:

.\gradlew.bat test

샘플 엑셀 기반 테스트:

.\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest

결과 파일은 테스트 실행 시 build/pairing-result*.xlsx로 생성됩니다.