375 lines
10 KiB
Markdown
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`에서 행확장
|
|
- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
|
|
|
|
## 비고
|
|
|
|
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.
|