Files
ncrc-pairing/README.md

10 KiB

ncrc-pairing

엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다.

개요

처리는 크게 2단계입니다.

  1. 현장위원 100명과 외부위원 100명을 1:1 페어로 매칭
  2. 생성된 페어를 사용해 인접지역분류 단위로 최종 배정

배정 결과는 엑셀로 반환합니다.

실행 환경

  • 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 내용을 담은 오류 엑셀을 반환합니다.

전체 처리 흐름

현재 실제 구동 순서는 아래와 같습니다.

  1. PairingController
  2. PairingService#pairingMemberByCenterNew
  3. PairingExcelService#read
  4. PairingNormalizeService#normalize
  5. PairingHolidayService#applyHolidayUnavailableDates
  6. PairingValidationService#validate
  7. PairingNewService#pair
  8. PairingExcelService#writeNew

입력 엑셀 시트

현재 필수 시트는 5개입니다.

  1. 위원정보
  2. 지자체 정보
  3. 센터정보
  4. 센터 인접지역표
  5. 희망지역 매칭표

더 이상 사용하지 않는 시트:

  • 위원 지역코드표

현재 코드에서는 읽지 않습니다.

핵심 모델

Member

위원 기본 정보입니다.

  • 성별
  • 경력
  • 역할(현장 / 외부)
  • 가능 시작일 / 종료일
  • 불가일
  • 활동지역
  • 2023년 진행 센터 이력
  • 거주지
  • 선호지역 1~4

NewCenter

센터와 지자체 정보를 합쳐 만든 센터 단위 모델입니다.

  • availableStartDate: 센터 시작일과 지자체 시작일 중 더 늦은 값
  • availableEndDate: 센터 종료일과 지자체 종료일 중 더 이른 값
  • unavailableDates: 센터 불가일 + 지자체 불가일

NewAdjacentRegion

실제 배정의 기본 단위입니다.

  • 기준: dispatchRegion + adjacentRegionClassification
  • 포함 센터: 같은 adjacentRegionClassification을 가진 센터 묶음
  • womenOnly: 포함 센터 중 하나라도 여성전용이면 true
  • availableStartDate: 포함 센터들의 시작일 중 가장 늦은 값
  • availableEndDate: 포함 센터들의 종료일 중 가장 이른 값
  • unavailableDates: 포함 센터들의 불가일 합집합 + 공통 제외일(토/일/공휴일)

주의:

  • 센터 인접지역표의 dispatchRegion 셀에는 12,15,16처럼 여러 코드가 들어올 수 있습니다.
  • 현재는 정규화 단계에서 이 값을 행확장합니다.
  • 예: dispatchRegion=12,15,16, adjacentRegionClassification=A001
    • (12, A001)
    • (15, A001)
    • (16, A001)

페어 생성 규칙

페어 생성은 PairingNewService에서 처리합니다.

하드룰

  1. 현장위원 수와 외부위원 수는 같아야 함
  2. 모든 현장위원과 모든 외부위원이 정확히 1:1로 사용되어야 함
  3. 신규 + 신규 페어는 금지

페어 점수 기준

현재 페어 점수는 아래 항목으로 계산합니다.

  1. 활동지역 겹침 수
  2. 공통 가능일 수
  3. 선호지역 겹침 수
  4. 2023년 진행 센터 이력 점수
  5. 거주지 유사도
  6. 배정 가능한 인접지역 수

현재 코드 기준:

private static final boolean USE_AVAILABLE_ADJACENT_REGION_IN_PAIR_SCORE = true;

즉, 배정 가능한 인접지역 수가 많은 페어가 페어 생성 단계의 점수에도 반영됩니다.

추가로 생성된 페어는 아래 기준으로 다시 정렬됩니다.

  1. 배정 가능 인접지역 수 오름차순
  2. 중복제거 가능 날짜 수 오름차순
  3. 페어 점수 내림차순
  4. 현장위원 id
  5. 외부위원 id

이 정렬 순서는 이후 최종 배정 순서에도 영향을 줍니다.

최종 배정 규칙

최종 배정은 PairingNewService#assignAdjacentRegions에서 처리합니다.

기본 개념은 단순 그리디입니다.

  1. 정렬된 페어를 앞에서부터 순회
  2. 각 페어가 갈 수 있는 인접지역분류 후보를 찾음
  3. 희망지역 매칭표 순위가 가장 높은 후보부터 선택
  4. 배정 직후 그 페어의 해당 날짜를 사용 처리
  5. 이미 배정된 인접지역분류는 다시 배정하지 않음
  6. 더 이상 배정할 수 없을 때까지 반복

최종 배정 하드룰

현재 코드에서 적용되는 하드룰은 아래와 같습니다.

  1. 같은 페어는 같은 날짜에 하나의 인접지역분류만 방문 가능
  2. 같은 인접지역분류는 한 번만 배정 가능
  3. 위원 가능일 / 지자체 가능일 / 센터 가능일 범위를 만족해야 함
  4. 위원 불가일 / 센터 불가일 / 지자체 불가일 / 토요일 / 일요일 / 공휴일은 제외
  5. 상피제 적용
    • 현장위원 또는 외부위원의 활동지역에 해당 dispatchRegion이 있으면 배정 불가
  6. 여성전용 인접지역은 여성 + 여성 페어만 가능
  7. 2023년 진행 센터 이력이 포함된 인접지역은 배정 불가
  8. 희망지역 매칭표 조합에 맞는 경우만 후보 인정

규칙검사 시트

결과 엑셀의 규칙검사 시트에는 현재 아래 항목을 검사합니다.

  1. 현장위원 전체 사용
  2. 외부위원 전체 사용
  3. 1:1 페어 수
  4. 신규+신규 페어 금지
  5. 페어별 하루 하나의 인접지역
  6. 인접지역 분류 중복 배정 금지
  7. 가능 날짜/불가일 준수
  8. 상피제 준수
  9. 여성위원만 조건 준수
  10. 2023년 진행 센터 재배정 제외
  11. 희망지역 매칭표 조합 준수

위반 시 FAIL과 상세 내역을 기록합니다.

결과 엑셀 시트

현재 결과 시트 순서는 아래와 같습니다.

  1. 페어결과
  2. 최종 배정
  3. 최종 배정 with 센터
  4. 인접지역목록
  5. 센터목록
  6. 페어후보요약
  7. 페어점수계산
  8. 규칙검사

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-rank
    • 00이 희망지역 매칭표에서 의미하는 순위
  • ignored-rank
    • 선호지역을 고려하지 않음을 의미하는 wildcard 순위

공휴일 / 주말 처리

PairingHolidayService에서 공통 제외일을 만듭니다.

데이터 소스:

  • DatagoHolidayCache
  • DatagoExtentionApiClient

포함 범위:

  • 공휴일
  • 토요일
  • 일요일

이 값들은 PairingData.commonUnavailableDates로 들어가고, 이후 NewAdjacentRegion.unavailableDates에 합쳐집니다.

주요 클래스

Controller

Service

Config

빌드 / 테스트

컴파일:

.\gradlew.bat compileJava compileTestJava

테스트:

.\gradlew.bat test

현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다.

유지보수 포인트

1. 새 시트가 추가될 때

  • 입력 시트라면 PairingExcelService#read
  • 정규화가 필요하면 PairingNormalizeService
  • 검증이 필요하면 PairingValidationService

2. 최종 배정 규칙이 바뀔 때

  • 대부분 PairingNewService.java 수정
  • 페어 생성 규칙 변경
    • matchMembers
    • createPairCandidates
    • scorePair
  • 최종 배정 규칙 변경
    • assignAdjacentRegions
    • findBestAssignmentChoice
    • firstAvailableDateForRegion

3. 규칙검사 기준이 바뀔 때

  • createRuleChecks
  • createAssignmentRuleChecks

4. dispatchRegion 복수 입력 형식이 바뀔 때

  • 현재는 PairingNormalizeService#toCenterAdjacentRegions에서 행확장
  • 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다

비고

  • 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.