Files
ncrc-pairing/README.md

375 lines
10 KiB
Markdown

# ncrc-pairing
엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다.
## 개요
처리는 크게 2단계입니다.
1. 현장위원 100명과 외부위원 100명을 1:1 페어로 매칭
2. 생성된 페어를 사용해 인접지역분류 단위로 최종 배정
배정 결과는 엑셀로 반환합니다.
## 실행 환경
- Java 17
- Spring Boot 3.5.x
- Gradle
기본 포트:
```yaml
server:
port: 6111
```
## API
엔드포인트:
```text
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. 배정 가능한 인접지역 수
현재 코드 기준:
```java
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
- 희망지역 매칭표 상의 순위
- 인접지역 분류
## 설정값
현재 사용 중인 설정은 아래뿐입니다.
```yaml
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
- [PairingController.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/controller/PairingController.java)
### Service
- [PairingService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingService.java)
- [PairingExcelService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingExcelService.java)
- [PairingNormalizeService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNormalizeService.java)
- [PairingHolidayService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingHolidayService.java)
- [PairingValidationService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingValidationService.java)
- [PairingNewService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNewService.java)
### Config
- [PairingProperties.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/config/PairingProperties.java)
- [application.yaml](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/resources/application.yaml)
## 빌드 / 테스트
컴파일:
```powershell
.\gradlew.bat compileJava compileTestJava
```
테스트:
```powershell
.\gradlew.bat test
```
현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다.
## 유지보수 포인트
### 1. 새 시트가 추가될 때
- 입력 시트라면 `PairingExcelService#read`
- 정규화가 필요하면 `PairingNormalizeService`
- 검증이 필요하면 `PairingValidationService`
### 2. 최종 배정 규칙이 바뀔 때
- 대부분 [PairingNewService.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/service/PairingNewService.java) 수정
- 페어 생성 규칙 변경
- `matchMembers`
- `createPairCandidates`
- `scorePair`
- 최종 배정 규칙 변경
- `assignAdjacentRegions`
- `findBestAssignmentChoice`
- `firstAvailableDateForRegion`
### 3. 규칙검사 기준이 바뀔 때
- `createRuleChecks`
- `createAssignmentRuleChecks`
### 4. dispatchRegion 복수 입력 형식이 바뀔 때
- 현재는 `PairingNormalizeService#toCenterAdjacentRegions`에서 행확장
- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
## 비고
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.