260421_03_ENH: README.md 파일 갱신 및 필요없어진 md 파일 제거

This commit is contained in:
2026-04-21 10:07:12 +09:00
parent af92f18574
commit 6a31fedc64
2 changed files with 316 additions and 248 deletions

459
README.md
View File

@@ -1,201 +1,374 @@
# ncrc-pairing
엑셀 파일을 입력받아 위원 조편성 및 센터 방문 일정을 생성하는 Spring Boot API입니다.
엑셀 파일을 입력받아 위원 1:1 페어를 만들고, 인접지역분류 단위의 방문 배정표를 생성하는 Spring Boot API입니다.
현재 배정 엔진은 Greedy 중심으로 동작합니다. 모든 위원을 먼저 조편성하고, 이후 가능한 많은 센터를 일정표에 배정합니다. OR-Tools CP-SAT 코드는 유지되어 있지만 전체 배정의 중심 경로는 `PairingScheduleService`입니다.
## 개요
## 실행 흐름
처리는 크게 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`
- `/api/v1/pairing/run`으로 엑셀 파일을 업로드받습니다.
- 결과 엑셀 파일을 반환합니다.
2. `PairingService#pairingMemberByCenterNew`
3. `PairingExcelService#read`
4. `PairingNormalizeService#normalize`
5. `PairingHolidayService#applyHolidayUnavailableDates`
6. `PairingValidationService#validate`
7. `PairingNewService#pair`
8. `PairingExcelService#writeNew`
2. `PairingService`
- 전체 유스케이스를 순서대로 호출합니다.
- `엑셀 읽기 -> 정규화 -> 공휴일/주말 반영 -> 검증 -> 후보 생성 -> 조편성/스케줄링 -> 결과 엑셀 생성`
## 입력 엑셀 시트
3. `PairingExcelService`
- 입력 엑셀 시트를 DTO로 읽습니다.
- 결과 시트는 배정결과, 미배정센터, 미사용위원, 처리요약, AB페어목록, 후보요약, 검증오류, 규칙위반검사를 포함합니다.
현재 필수 시트는 5개입니다.
4. `PairingNormalizeService`
- 엑셀 문자열을 내부 모델로 변환합니다.
- 날짜, CSV, 성별, 경력, 현장/외부 구분, 지역코드, 희망지역을 정리합니다.
1. `위원정보`
2. `지자체 정보`
3. `센터정보`
4. `센터 인접지역표`
5. `희망지역 매칭표`
5. `PairingHolidayService`
- `DatagoHolidayCache`를 통해 공휴일을 조회합니다.
- 토/일은 `DatagoHolidayCache#getWeekend`에서 생성해 공통 불가능일로 합칩니다.
- 공휴일 API 조회 실패 시 구동되면 안 된다는 정책에 따라 실패 응답을 냅니다.
더 이상 사용하지 않는 시트:
6. `PairingValidationService`
- 필수 데이터, 날짜 범위, 지자체 참조, 희망지역 매칭표를 검증합니다.
- 검증 실패는 `BusinessException.badRequest(code, message)`를 사용합니다.
- `위원 지역코드표`
7. `PairingCandidateService`
- 가능한 조, 파견권역, 센터/날짜 후보를 생성합니다.
- 상피제, 여성전용센터, 기방문센터, 날짜 불가, 공휴일/주말 등 명확한 Hard Rule을 후보 단계에서 제거합니다.
현재 코드에서는 읽지 않습니다.
8. `PairingMemberPairService`
- 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 수행합니다.
- 센터/날짜 후보가 많은 조를 우선 선택하고, 위원당 상대 파트너 수 상한을 지킵니다.
## 핵심 모델
9. `PairingScheduleService`
- 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
- 이후 repair pass를 통해 미배정 센터 감소와 방문 수 균형을 보정합니다.
### Member
10. `PairingSolverService`
- 결과 DTO 생성과 규칙 위반 검사를 담당합니다.
- CP-SAT 기반 선택 로직도 유지하고 있으나 현재 주 경로는 Greedy 스케줄링입니다.
위원 기본 정보입니다.
## 현재 Hard Rule
- 성별
- 경력
- 역할(현장 / 외부)
- 가능 시작일 / 종료일
- 불가일
- 활동지역
- 2023년 진행 센터 이력
- 거주지
- 선호지역 1~4
| 규칙 | 구현 위치 |
| --- | --- |
| 모든 위원은 최소 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` |
### NewCenter
## 현재 Soft Rule 우선순위
센터와 지자체 정보를 합쳐 만든 센터 단위 모델입니다.
1. 배정 센터 수 최대화
2. 위원별 방문 수 균형
3. 희망지역 매칭표 우선순위
4. 희망지역 99 wildcard fallback
- `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. 같은 조/같은 날짜/같은 인접지역 분류 재사용
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:
rule:
max-centers-per-pair-per-day: 3
max-counterparts-per-member: 3
max-member-visit-average-ratio-percent: 130
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
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`
- `header-row-index`
- 엑셀 헤더 행 번호
- `region-code-length`
- 활동지역 / 선호지역 / 파견권역 코드 정규화 길이
- `residence-code-length`
- 거주지 코드 정규화 길이
- `any-region-code`
- 선호지역의 `어디든 가능` 코드
- `anywhere-rank`
- `00`이 희망지역 매칭표에서 의미하는 순위
- `ignored-rank`
- 선호지역을 고려하지 않음을 의미하는 wildcard 순위
1. `pairingCandidateService.generate`
- 가능한 후보를 생성합니다.
## 공휴일 / 주말 처리
2. `pairingMemberPairService.select`
- 모든 위원을 먼저 조편성합니다.
`PairingHolidayService`에서 공통 제외일을 만듭니다.
3. `assignRemainingCenters`
- 후보가 적은 센터부터 선택합니다.
- 해당 센터에 가능한 후보 중 점수가 가장 높은 후보를 배정합니다.
데이터 소스:
4. `repairUnassignedCenters`
- 미배정 센터를 넣기 위해 기존 충돌 배정을 최대 2개까지 제거하고 다시 채웁니다.
- `DatagoHolidayCache`
- `DatagoExtentionApiClient`
5. `repairLowVisitMembers`
- 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 우선 탐색합니다.
포함 범위:
6. `repairByDonorSwap`
- 방문 수가 많은 위원의 배정을 저방문 위원이 포함된 후보로 넘길 수 있는지 봅니다.
- 공휴일
- 토요일
- 일요일
7. `repairWildcardFallbackCenters`
- 99 wildcard 후보를 남은 센터에 우선 적용해 봅니다.
이 값들은 `PairingData.commonUnavailableDates`로 들어가고, 이후 `NewAdjacentRegion.unavailableDates`에 합쳐집니다.
## OR-Tools CP-SAT 설명
## 주요 클래스
사용 라이브러리:
### Controller
```gradle
implementation("com.google.ortools:ortools-java:9.15.6755")
```
- [PairingController.java](D:/___Project/260414_아동권리보장원/DEV/ncrc-pairing/src/main/java/com/kri/p6/ncrc/pairing/controller/PairingController.java)
CP-SAT는 "조건을 모두 지키면서 가장 점수가 높은 조합을 찾는 도구"입니다.
### Service
예를 들어 `A조가 2026-05-01에 100번 센터를 방문한다`라는 후보가 있으면, CP-SAT 안에서는 이 후보가 0/1 변수 하나가 됩니다.
- [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)
```text
1 = 이 후보를 선택한다
0 = 이 후보를 선택하지 않는다
```
### Config
현재 프로젝트에서는 전체 후보가 매우 커질 수 있어 CP-SAT만으로는 시간이 오래 걸릴 수 있습니다. 그래서 주 배정은 Greedy가 담당하고, CP-SAT 코드는 향후 부분 최적화나 비교 실험을 위해 유지합니다.
- [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)
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...` 메서드 |
## 테스트
## 빌드 / 테스트
컴파일:
```powershell
.\gradlew.bat compileJava
.\gradlew.bat compileJava compileTestJava
```
전체 테스트:
테스트:
```powershell
.\gradlew.bat test
```
샘플 엑셀 기반 테스트:
현재 테스트는 최소 Spring Boot 컨텍스트 테스트만 남아 있습니다.
```powershell
.\gradlew.bat test --tests com.kri.p6.ncrc.pairing.service.PairingServiceTest
```
## 유지보수 포인트
결과 파일은 테스트 실행 시 `build/pairing-result*.xlsx`로 생성됩니다.
### 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`에서 행확장
- 이 형식이 바뀌면 여기부터 수정하는 것이 맞습니다
## 비고
- 현재 결과는 “최대한 단순한 방향의 그리디 배정”을 목표로 합니다.