260420_01_ENH: split 마감

This commit is contained in:
2026-04-20 16:58:35 +09:00
parent 51a2712066
commit 9e58f5b361
16 changed files with 1881 additions and 640 deletions

View File

@@ -18,6 +18,8 @@ public final class PairingConstant {
public static final String RESULT_SHEET_VALIDATION_ERROR = "검증오류";
public static final String RESULT_SHEET_RULE_CHECK = "규칙위반검사";
public static final String RESULT_SHEET_APPLIED_SETTING = "적용설정";
private PairingConstant() {
}
}

View File

@@ -36,7 +36,8 @@ public class PairingProperties {
@Setter
public static class Rule {
private int maxCentersPerPairPerDay = 3;
private int maxCounterpartsPerMember = 2;
private int maxCounterpartsPerMember = 3;
private int maxMemberVisitAverageRatioPercent = 130;
}
@Getter
@@ -44,26 +45,28 @@ public class PairingProperties {
public static class Preference {
private int anywhereRank = 0;
private int ignoredRank = 99;
private boolean activeWildcardFallbackEnabled = false;
private long wildcardFallbackScoreBonus = 25_000L;
}
@Getter
@Setter
public static class Objective {
private long assignmentWeight = 1_000_000L;
private long preferenceBaseWeight = 10_000L;
private long preferenceRankPenalty = 100L;
private long residenceMatchWeight = 1_000L;
private long usedMemberWeight = 300_000L;
private long memberBalanceWeight = 1_000L;
private long preferenceBaseWeight = 30_000L;
private long preferenceRankPenalty = 1_000L;
private long residenceMatchWeight = 10_000L;
private long memberBalanceWeight = 20_000L;
}
@Getter
@Setter
public static class Candidate {
private int maxDispatchRegionsPerPair = 5;
private int maxAssignmentsPerCenter = 30;
private int maxAssignmentsPerMember = 80;
private int maxDatesPerAssignmentCandidate = 5;
private int maxPairCandidatesPerMember = 0;
private int maxDispatchRegionsPerPair = 0;
private int maxAssignmentsPerCenter = 1_000;
private int maxAssignmentsPerMember = 3_000;
private int maxDatesPerAssignmentCandidate = 80;
}
@Getter

View File

@@ -0,0 +1,21 @@
package com.kri.p6.ncrc.pairing.dto.excel.output;
import com.kri.common.feature.excel.ExcelColumn;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
public class AppliedSettingExcelDto {
@ExcelColumn(header = "설정명", order = 0, width = 38)
private String name;
@ExcelColumn(header = "설정에 대한 설명", order = 1, width = 70)
private String description;
@ExcelColumn(header = "값", order = 2, width = 24)
private String value;
}

View File

@@ -1,6 +1,7 @@
package com.kri.p6.ncrc.pairing.model;
import com.kri.p6.ncrc.pairing.dto.excel.output.ABPairExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AppliedSettingExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AssignmentResultExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.CandidateSummaryExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.PairingSummaryExcelDto;
@@ -22,6 +23,7 @@ public class PairingResult {
private final List<PairingSummaryExcelDto> summaries;
private final List<ABPairExcelDto> abPairs;
private final List<CandidateSummaryExcelDto> candidateSummaries;
private final List<AppliedSettingExcelDto> appliedSettings;
private final List<ValidationErrorExcelDto> validationErrors;
private final List<RuleViolationExcelDto> ruleViolations;

View File

@@ -22,6 +22,7 @@ import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.PriorityQueue;
import java.util.Set;
import java.util.function.Function;
import java.util.stream.Collectors;
@@ -35,7 +36,10 @@ public class PairingCandidateService {
private final PairingProperties pairingProperties;
public PairingCandidates generate(PairingData data) {
List<PairCandidate> pairCandidates = createPairCandidates(data.getMembers());
// 후보 생성은 "가능한 조합을 넓게 만들고, 명백히 불가능한 조합만 제거"하는 단계입니다.
// 이후 PairingScheduleService가 이 후보들 중 실제 방문 일정을 선택합니다.
List<PairCandidate> pairCandidates = trimPairCandidates(
createPairCandidates(data.getMembers()), data.getMembers());
List<DispatchRegionCandidate> dispatchRegionCandidates = trimDispatchRegionCandidates(
createDispatchRegionCandidates(data, pairCandidates));
Map<String, Set<String>> unassignedCenterReasons = createInitialCenterReasonMap(data);
@@ -53,6 +57,8 @@ public class PairingCandidateService {
}
private List<PairCandidate> createPairCandidates(List<Member> members) {
// 현장위원 1명 + 외부위원 1명을 기본 조로 봅니다.
// 두 위원의 활동 가능 기간이 전혀 겹치지 않으면 이후 센터 배정이 불가능하므로 제외합니다.
List<Member> fieldMembers = members.stream()
.filter(member -> member.getRole() == MemberRole.FIELD).toList();
List<Member> externalMembers = members.stream()
@@ -75,6 +81,8 @@ public class PairingCandidateService {
private List<DispatchRegionCandidate> createDispatchRegionCandidates(PairingData data,
List<PairCandidate> pairCandidates) {
// 조가 갈 수 있는 파견 권역 후보를 만듭니다.
// 상피제(위원 활동지역과 파견 권역 일치)는 여기서 제거합니다.
Map<String, Member> memberMap = toMemberMap(data.getMembers());
Set<String> dispatchRegions = data.getCenterAdjacentRegions().stream()
.map(CenterAdjacentRegion::getDispatchRegion).collect(Collectors.toSet());
@@ -92,6 +100,8 @@ public class PairingCandidateService {
Optional<PreferenceMatchRule> matchRule = findPreferenceMatchRule(
data.getPreferenceMatchRules(), fieldRank, externalRank);
// fieldRank/externalRank가 -1이어도 희망지역 매칭표의 99(wildcard) 규칙은 적용될 수 있습니다.
// 99는 "해당 위원의 희망지역을 고려하지 않음"이라는 후순위 fallback입니다.
candidates.add(DispatchRegionCandidate.builder().fieldMemberId(fieldMember.getId())
.externalMemberId(externalMember.getId()).dispatchRegion(dispatchRegion)
.preferencePriority(matchRule.map(PreferenceMatchRule::getPriority)
@@ -111,6 +121,8 @@ public class PairingCandidateService {
List<DispatchRegionCandidate> dispatchRegionCandidates,
Map<String, Set<String>> unassignedCenterReasons
) {
// 파견 권역 후보를 실제 센터와 날짜 후보로 확장합니다.
// 여성전용, 기방문센터, 위원/지자체/센터 불가능일, 공휴일/주말은 이 단계에서 제외합니다.
Map<String, Member> memberMap = toMemberMap(data.getMembers());
Map<String, Municipality> municipalityMap = data.getMunicipalities().stream()
.collect(Collectors.toMap(Municipality::getId, Function.identity(), (left, right) -> left));
@@ -120,8 +132,13 @@ public class PairingCandidateService {
.stream().collect(Collectors.groupingBy(CenterAdjacentRegion::getDispatchRegion,
Collectors.mapping(CenterAdjacentRegion::getAdjacentRegionClassification,
Collectors.toSet())));
Map<String, List<Center>> centersByAdjacentClassification = data.getCenters().stream()
.collect(Collectors.groupingBy(Center::getAdjacentRegionClassification,
LinkedHashMap::new, Collectors.toList()));
Set<LocalDate> commonUnavailableDates = commonUnavailableDates(data);
List<AssignmentCandidate> candidates = new ArrayList<>();
Map<String, PriorityQueue<AssignmentCandidate>> centerCandidateBuckets = new LinkedHashMap<>();
Map<String, PriorityQueue<AssignmentCandidate>> memberCandidateBuckets = new LinkedHashMap<>();
for (DispatchRegionCandidate dispatchCandidate : dispatchRegionCandidates) {
Member fieldMember = memberMap.get(dispatchCandidate.getFieldMemberId());
@@ -132,7 +149,8 @@ public class PairingCandidateService {
Set<String> adjacentClassifications = adjacentClassificationsByDispatchRegion
.getOrDefault(dispatchCandidate.getDispatchRegion(), Set.of());
for (Center center : data.getCenters()) {
for (Center center : centersForDispatch(adjacentClassifications,
centersByAdjacentClassification)) {
if (!adjacentClassifications.contains(center.getAdjacentRegionClassification())) {
addReason(unassignedCenterReasons, center.getId(), "파견 권역과 센터 인접지역 분류 불일치");
} else {
@@ -145,13 +163,14 @@ public class PairingCandidateService {
reason -> addReason(unassignedCenterReasons, center.getId(), reason));
} else {
List<LocalDate> assignableDates = findAssignableDates(fieldMember,
externalMember, municipality, center, commonUnavailableDates(data));
externalMember, municipality, center, commonUnavailableDates);
if (assignableDates.isEmpty()) {
addReason(unassignedCenterReasons, center.getId(),
"위원/지자체/센터 일정 또는 국공휴일 조건 불일치");
} else {
for (LocalDate assignableDate : assignableDates) {
candidates.add(AssignmentCandidate.builder().fieldMemberId(fieldMember.getId())
addBoundedAssignmentCandidate(centerCandidateBuckets, memberCandidateBuckets,
AssignmentCandidate.builder().fieldMemberId(fieldMember.getId())
.externalMemberId(externalMember.getId()).centerId(center.getId())
.municipalityId(center.getMunicipalityId()).date(assignableDate)
.dispatchRegion(dispatchCandidate.getDispatchRegion())
@@ -168,7 +187,7 @@ public class PairingCandidateService {
}
}
return candidates;
return mergeAssignmentCandidateBuckets(centerCandidateBuckets, memberCandidateBuckets);
}
private List<AssignmentCandidate> preferResidenceMatchesByCenter(
@@ -195,6 +214,116 @@ public class PairingCandidateService {
.toList();
}
private List<PairCandidate> trimPairCandidates(List<PairCandidate> candidates,
List<Member> members) {
int limit = maxPairCandidatesPerMember();
if (limit <= 0) {
return candidates;
}
Map<String, Member> memberMap = toMemberMap(members);
Map<String, Integer> memberUsage = new HashMap<>();
List<PairCandidate> selected = new ArrayList<>();
Set<String> selectedKeys = new LinkedHashSet<>();
for (PairCandidate candidate : candidates.stream()
.sorted(pairCandidateComparator(memberMap))
.toList()) {
int fieldCount = memberUsage.getOrDefault(candidate.getFieldMemberId(), 0);
int externalCount = memberUsage.getOrDefault(candidate.getExternalMemberId(), 0);
if (fieldCount < limit && externalCount < limit) {
addPairCandidate(selected, selectedKeys, memberUsage, candidate);
}
}
Set<String> missingMemberIds = candidates.stream()
.flatMap(candidate -> java.util.stream.Stream.of(candidate.getFieldMemberId(),
candidate.getExternalMemberId()))
.filter(memberId -> memberUsage.getOrDefault(memberId, 0) == 0)
.collect(Collectors.toCollection(LinkedHashSet::new));
for (PairCandidate candidate : candidates.stream()
.sorted(pairCandidateComparator(memberMap))
.toList()) {
if (missingMemberIds.isEmpty()) {
break;
}
if (selectedKeys.contains(pairKey(candidate))) {
continue;
}
if (!missingMemberIds.contains(candidate.getFieldMemberId())
&& !missingMemberIds.contains(candidate.getExternalMemberId())) {
continue;
}
addPairCandidate(selected, selectedKeys, memberUsage, candidate);
missingMemberIds.remove(candidate.getFieldMemberId());
missingMemberIds.remove(candidate.getExternalMemberId());
}
return selected;
}
private void addPairCandidate(List<PairCandidate> selected, Set<String> selectedKeys,
Map<String, Integer> memberUsage, PairCandidate candidate) {
selected.add(candidate);
selectedKeys.add(pairKey(candidate));
memberUsage.merge(candidate.getFieldMemberId(), 1, Integer::sum);
memberUsage.merge(candidate.getExternalMemberId(), 1, Integer::sum);
}
private List<Center> centersForDispatch(Set<String> adjacentClassifications,
Map<String, List<Center>> centersByAdjacentClassification) {
return adjacentClassifications.stream()
.flatMap(adjacentClassification -> centersByAdjacentClassification
.getOrDefault(adjacentClassification, List.of()).stream())
.toList();
}
private void addBoundedAssignmentCandidate(
Map<String, PriorityQueue<AssignmentCandidate>> centerCandidateBuckets,
Map<String, PriorityQueue<AssignmentCandidate>> memberCandidateBuckets,
AssignmentCandidate candidate) {
// 후보 수가 너무 커지면 처리 시간이 급격히 늘어납니다.
// 센터별/위원별 후보 상한을 두되, 0이면 제한하지 않습니다.
addBounded(centerCandidateBuckets, candidate.getCenterId(), candidate,
maxAssignmentsPerCenter());
addBounded(memberCandidateBuckets, candidate.getFieldMemberId(), candidate,
maxAssignmentsPerMember());
addBounded(memberCandidateBuckets, candidate.getExternalMemberId(), candidate,
maxAssignmentsPerMember());
}
private void addBounded(Map<String, PriorityQueue<AssignmentCandidate>> buckets, String key,
AssignmentCandidate candidate, int limit) {
PriorityQueue<AssignmentCandidate> bucket = buckets.computeIfAbsent(key,
ignored -> new PriorityQueue<>(worstAssignmentComparator()));
if (limit <= 0 || bucket.size() < limit) {
bucket.add(candidate);
return;
}
AssignmentCandidate worstCandidate = bucket.peek();
if (worstCandidate != null
&& assignmentCandidateComparator().compare(candidate, worstCandidate) < 0) {
bucket.poll();
bucket.add(candidate);
}
}
private List<AssignmentCandidate> mergeAssignmentCandidateBuckets(
Map<String, PriorityQueue<AssignmentCandidate>> centerCandidateBuckets,
Map<String, PriorityQueue<AssignmentCandidate>> memberCandidateBuckets) {
Map<String, AssignmentCandidate> merged = new LinkedHashMap<>();
centerCandidateBuckets.values().forEach(bucket -> bucket.forEach(candidate ->
merged.putIfAbsent(assignmentKey(candidate), candidate)));
memberCandidateBuckets.values().forEach(bucket -> bucket.forEach(candidate ->
merged.putIfAbsent(assignmentKey(candidate), candidate)));
return merged.values().stream()
.sorted(assignmentCandidateComparator())
.toList();
}
private List<AssignmentCandidate> trimAssignmentCandidates(List<AssignmentCandidate> candidates,
List<Center> centers, Map<String, Set<String>> unassignedCenterReasons) {
List<AssignmentCandidate> trimmedByCenter = trimAssignmentsPerCenter(candidates);
@@ -375,13 +504,14 @@ public class PairingCandidateService {
private Optional<PreferenceMatchRule> findPreferenceMatchRule(List<PreferenceMatchRule> rules,
int fieldRank, int externalRank) {
return fieldRank >= 0 && externalRank >= 0 ?
rules.stream().filter(
// 99 규칙은 wildcard입니다. 예를 들어 fieldRank가 -1이어도
// 매칭표에 99/1 규칙이 있으면 "현장위원 선호지역 고려하지 않음 + 외부위원 1순위"로 인정합니다.
return rules.stream().filter(
rule -> matchesPreferenceRank(rule.getFieldMemberPreferenceRank(), fieldRank)
)
.filter(rule -> matchesPreferenceRank(rule.getExternalMemberPreferenceRank(),externalRank))
.filter(rule -> matchesPreferenceRank(rule.getExternalMemberPreferenceRank(), externalRank))
.min(Comparator.comparingInt(PreferenceMatchRule::getPriority))
: Optional.empty();
;
}
private int fallbackPreferencePriority(List<PreferenceMatchRule> rules) {
@@ -425,14 +555,30 @@ public class PairingCandidateService {
if (isAvailableOn(date, fieldMember, externalMember, municipality, center,
commonUnavailableDates)) {
dates.add(date);
if (dates.size() >= maxDatesPerAssignmentCandidate()) {
break;
}
}
}
}
return dates;
return spreadDates(dates, maxDatesPerAssignmentCandidate());
}
private List<LocalDate> spreadDates(List<LocalDate> dates, int limit) {
if (limit <= 0 || dates.size() <= limit) {
return dates;
}
if (limit == 1) {
return List.of(dates.get(0));
}
List<LocalDate> spread = new ArrayList<>();
for (int i = 0; i < limit; i++) {
int index = (int) Math.round((double) i * (dates.size() - 1) / (limit - 1));
LocalDate date = dates.get(index);
if (!spread.contains(date)) {
spread.add(date);
}
}
return spread;
}
private boolean isAvailableOn(LocalDate date, Member fieldMember, Member externalMember,
@@ -520,10 +666,22 @@ public class PairingCandidateService {
return pairingProperties.getCandidate().getMaxAssignmentsPerMember();
}
private int maxPairCandidatesPerMember() {
return pairingProperties.getCandidate().getMaxPairCandidatesPerMember();
}
private int maxDatesPerAssignmentCandidate() {
return pairingProperties.getCandidate().getMaxDatesPerAssignmentCandidate();
}
private Comparator<PairCandidate> pairCandidateComparator(Map<String, Member> memberMap) {
return Comparator.comparingInt((PairCandidate candidate) -> pairCandidateScore(candidate,
memberMap))
.reversed()
.thenComparing(PairCandidate::getFieldMemberId)
.thenComparing(PairCandidate::getExternalMemberId);
}
private Comparator<DispatchRegionCandidate> dispatchRegionCandidateComparator() {
return Comparator.comparingInt(this::dispatchRegionCandidateScore).reversed()
.thenComparing(DispatchRegionCandidate::getDispatchRegion);
@@ -537,20 +695,72 @@ public class PairingCandidateService {
.thenComparing(AssignmentCandidate::getExternalMemberId);
}
private Comparator<AssignmentCandidate> worstAssignmentComparator() {
return Comparator.comparingInt(this::assignmentCandidateScore)
.thenComparing(AssignmentCandidate::getDate, Comparator.reverseOrder())
.thenComparing(AssignmentCandidate::getCenterId, Comparator.reverseOrder())
.thenComparing(AssignmentCandidate::getFieldMemberId, Comparator.reverseOrder())
.thenComparing(AssignmentCandidate::getExternalMemberId, Comparator.reverseOrder());
}
private int dispatchRegionCandidateScore(DispatchRegionCandidate candidate) {
return preferenceScore(candidate.getPreferencePriority())
+ preferenceRankBonus(candidate.getFieldMemberPreferenceRank())
+ preferenceRankBonus(candidate.getExternalMemberPreferenceRank());
}
private int pairCandidateScore(PairCandidate candidate, Map<String, Member> memberMap) {
Member fieldMember = memberMap.get(candidate.getFieldMemberId());
Member externalMember = memberMap.get(candidate.getExternalMemberId());
return preferenceIntersectionScore(fieldMember, externalMember)
+ candidate.getResidenceMatchScore() * 10;
}
private int preferenceIntersectionScore(Member fieldMember, Member externalMember) {
if (fieldMember == null || externalMember == null) {
return 0;
}
Set<String> externalPreferences = new LinkedHashSet<>(externalMember.getPreferenceRegions());
int score = 0;
for (String preference : fieldMember.getPreferenceRegions()) {
if (ignoredPreferenceCode(preference)) {
continue;
}
if (anyRegionCode().equals(preference) && externalPreferences.contains(preference)) {
score += 10;
} else if (externalPreferences.contains(preference)) {
score += 100;
}
}
return score;
}
private boolean ignoredPreferenceCode(String preference) {
return String.valueOf(ignoredPreferenceRank()).equals(preference);
}
private int assignmentCandidateScore(AssignmentCandidate candidate) {
return preferenceScore(candidate.getPreferencePriority())
+ preferenceRankBonus(candidate.getFieldMemberPreferenceRank())
+ preferenceRankBonus(candidate.getExternalMemberPreferenceRank())
+ wildcardFallbackBonus(candidate)
+ candidate.getResidenceMatchScore() * (int) pairingProperties.getObjective()
.getResidenceMatchWeight();
}
private int wildcardFallbackBonus(AssignmentCandidate candidate) {
// wildcard 적극 사용 옵션입니다. true이면 99 규칙으로 살아난 후보가
// 후보 축소 단계에서 너무 쉽게 밀려나지 않도록 보너스를 줍니다.
if (!activeWildcardFallbackEnabled()) {
return 0;
}
if (!usesWildcardFallback(candidate)) {
return 0;
}
return (int) Math.min(Integer.MAX_VALUE, wildcardFallbackScoreBonus());
}
private int preferenceScore(int priority) {
return (int) Math.max(0L, pairingProperties.getObjective().getPreferenceBaseWeight()
- priority * pairingProperties.getObjective().getPreferenceRankPenalty());
@@ -568,6 +778,19 @@ public class PairingCandidateService {
return Math.max(0, 10 - rank);
}
private boolean usesWildcardFallback(AssignmentCandidate candidate) {
return candidate.getFieldMemberPreferenceRank() < 0
|| candidate.getExternalMemberPreferenceRank() < 0;
}
private boolean activeWildcardFallbackEnabled() {
return pairingProperties.getPreference().isActiveWildcardFallbackEnabled();
}
private long wildcardFallbackScoreBonus() {
return pairingProperties.getPreference().getWildcardFallbackScoreBonus();
}
private LocalDate max(LocalDate left, LocalDate right) {
return left.isAfter(right) ? left : right;
}

View File

@@ -1,6 +1,7 @@
package com.kri.p6.ncrc.pairing.service;
import static com.kri.p6.ncrc.pairing.common.consts.PairingConstant.RESULT_SHEET_AB_PAIR;
import static com.kri.p6.ncrc.pairing.common.consts.PairingConstant.RESULT_SHEET_APPLIED_SETTING;
import static com.kri.p6.ncrc.pairing.common.consts.PairingConstant.RESULT_SHEET_ASSIGNMENT;
import static com.kri.p6.ncrc.pairing.common.consts.PairingConstant.RESULT_SHEET_CANDIDATE_SUMMARY;
import static com.kri.p6.ncrc.pairing.common.consts.PairingConstant.RESULT_SHEET_RULE_CHECK;
@@ -26,6 +27,7 @@ import com.kri.p6.ncrc.pairing.dto.excel.input.MunicipalityExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.input.PairingWorkbookData;
import com.kri.p6.ncrc.pairing.dto.excel.input.PreferenceMatchExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.ABPairExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AppliedSettingExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AssignmentResultExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.CandidateSummaryExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.PairingSummaryExcelDto;
@@ -93,6 +95,8 @@ public class PairingExcelService {
RESULT_SHEET_AB_PAIR, headerRowIndex());
ExcelMapper.appendSheetToWorkbook(workbook, result.getCandidateSummaries(),
CandidateSummaryExcelDto.class, RESULT_SHEET_CANDIDATE_SUMMARY, headerRowIndex());
ExcelMapper.appendSheetToWorkbook(workbook, result.getAppliedSettings(),
AppliedSettingExcelDto.class, RESULT_SHEET_APPLIED_SETTING, headerRowIndex());
ExcelMapper.appendSheetToWorkbook(workbook, result.getValidationErrors(),
ValidationErrorExcelDto.class, RESULT_SHEET_VALIDATION_ERROR, headerRowIndex());
ExcelMapper.appendSheetToWorkbook(workbook, result.getRuleViolations(),
@@ -114,6 +118,7 @@ public class PairingExcelService {
.summaries(List.of(new PairingSummaryExcelDto("처리 상태", "검증 실패")))
.abPairs(List.of())
.candidateSummaries(List.of())
.appliedSettings(appliedSettings())
.validationErrors(List.of(new ValidationErrorExcelDto(code, message, "ERROR")))
.ruleViolations(List.of())
.build();
@@ -135,6 +140,93 @@ public class PairingExcelService {
return pairingProperties.getExcel().getHeaderRowIndex();
}
private List<AppliedSettingExcelDto> appliedSettings() {
PairingProperties.Excel excel = pairingProperties.getExcel();
PairingProperties.Code code = pairingProperties.getCode();
PairingProperties.Rule rule = pairingProperties.getRule();
PairingProperties.Preference preference = pairingProperties.getPreference();
PairingProperties.Objective objective = pairingProperties.getObjective();
PairingProperties.Candidate candidate = pairingProperties.getCandidate();
PairingProperties.Solver solver = pairingProperties.getSolver();
return List.of(
setting("pairing.excel.header-row-index",
"엑셀 헤더로 사용할 행 인덱스",
excel.getHeaderRowIndex()),
setting("pairing.code.region-code-length",
"지역코드 정규화 길이", code.getRegionCodeLength()),
setting("pairing.code.residence-code-length",
"거주지코드 정규화 길이",
code.getResidenceCodeLength()),
setting("pairing.code.residence-match-prefix-length",
"거주지 일치 판단에 사용하는 앞자리 길이",
code.getResidenceMatchPrefixLength()),
setting("pairing.code.any-region-code",
"희망지역 anywhere로 처리하는 코드",
code.getAnyRegionCode()),
setting("pairing.rule.max-centers-per-pair-per-day",
"같은 페어가 하루에 방문할 수 있는 최대 센터 수",
rule.getMaxCentersPerPairPerDay()),
setting("pairing.rule.max-counterparts-per-member",
"위원 1명당 허용되는 상대 위원 최대 수",
rule.getMaxCounterpartsPerMember()),
setting("pairing.rule.max-member-visit-average-ratio-percent",
"위원별 방문 수 상한을 평균 대비 몇 %까지 허용할지",
rule.getMaxMemberVisitAverageRatioPercent()),
setting("pairing.preference.anywhere-rank",
"선호지역 anywhere를 의미하는 순위",
preference.getAnywhereRank()),
setting("pairing.preference.ignored-rank",
"선호지역 고려하지 않음을 의미하는 순위",
preference.getIgnoredRank()),
setting("pairing.preference.active-wildcard-fallback-enabled",
"희망지역 고려하지 않음을 wildcard로 적극 사용할지",
preference.isActiveWildcardFallbackEnabled()),
setting("pairing.preference.wildcard-fallback-score-bonus",
"wildcard 후보에 추가할 점수",
preference.getWildcardFallbackScoreBonus()),
setting("pairing.objective.assignment-weight",
"센터 하나를 더 배정하는 것에 부여하는 기본 점수",
objective.getAssignmentWeight()),
setting("pairing.objective.preference-base-weight",
"희망지역 매칭 품질에 부여하는 기본 점수",
objective.getPreferenceBaseWeight()),
setting("pairing.objective.preference-rank-penalty",
"희망순위가 낮아질 때 감점하는 점수",
objective.getPreferenceRankPenalty()),
setting("pairing.objective.residence-match-weight",
"거주지 유사도 점수에 곱하는 가중치",
objective.getResidenceMatchWeight()),
setting("pairing.objective.member-balance-weight",
"방문 수가 많은 위원을 더 선택하지 않도록 감점하는 가중치",
objective.getMemberBalanceWeight()),
setting("pairing.candidate.max-pair-candidates-per-member",
"위원별 페어 후보 축소 상한, 0이면 무제한",
candidate.getMaxPairCandidatesPerMember()),
setting("pairing.candidate.max-dispatch-regions-per-pair",
"페어별 파견 권역 후보 축소 상한, 0이면 무제한",
candidate.getMaxDispatchRegionsPerPair()),
setting("pairing.candidate.max-assignments-per-center",
"센터별 배정 후보 축소 상한",
candidate.getMaxAssignmentsPerCenter()),
setting("pairing.candidate.max-assignments-per-member",
"위원별 배정 후보 축소 상한",
candidate.getMaxAssignmentsPerMember()),
setting("pairing.candidate.max-dates-per-assignment-candidate",
"하나의 페어-센터 조합에서 확장할 날짜 후보 상한",
candidate.getMaxDatesPerAssignmentCandidate()),
setting("pairing.solver.max-time-seconds",
"CP-SAT 사용 시 허용할 최대 탐색 시간",
solver.getMaxTimeSeconds()),
setting("pairing.solver.num-search-workers",
"CP-SAT 사용 시 사용할 worker 수",
solver.getNumSearchWorkers())
);
}
private AppliedSettingExcelDto setting(String name, String description, Object value) {
return new AppliedSettingExcelDto(name, description, String.valueOf(value));
}
private boolean isBlankRow(Object row) {
return Arrays.stream(row.getClass().getDeclaredFields())
.allMatch(field -> isBlankField(row, field));

View File

@@ -0,0 +1,140 @@
package com.kri.p6.ncrc.pairing.service;
import com.kri.p6.ncrc.pairing.config.PairingProperties;
import com.kri.p6.ncrc.pairing.model.Member;
import com.kri.p6.ncrc.pairing.model.PairCandidate;
import com.kri.p6.ncrc.pairing.model.PairingData;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
@Service
@RequiredArgsConstructor
public class PairingMemberPairService {
private final PairingProperties pairingProperties;
public PairSelection select(PairingData data, List<PairCandidate> pairCandidates) {
return select(data, pairCandidates, Map.of());
}
public PairSelection select(PairingData data, List<PairCandidate> pairCandidates,
Map<String, Long> assignmentCountByPair) {
// 0순위 전제: 모든 위원은 최소 1개 이상의 조에 포함되어야 합니다.
// 그래서 센터 배정 전에 먼저 조편성만 수행합니다.
Set<String> allMemberIds = data.getMembers().stream()
.map(Member::getId)
.collect(Collectors.toCollection(LinkedHashSet::new));
Map<String, Set<String>> counterpartsByMember = createCounterpartMap(allMemberIds);
List<PairCandidate> selectedPairs = new ArrayList<>();
List<PairCandidate> sortedCandidates = pairCandidates.stream()
.sorted(pairComparator(assignmentCountByPair))
.toList();
boolean changed;
do {
// 아직 조가 없는 위원을 우선 포함시키는 greedy 방식입니다.
// assignmentCountByPair가 큰 조는 실제 센터 후보가 많다는 뜻이므로 먼저 선택합니다.
changed = false;
Set<String> unmatchedMemberIds = unmatchedMemberIds(allMemberIds, counterpartsByMember);
for (PairCandidate candidate : sortedCandidates) {
if (unmatchedMemberIds.isEmpty()) {
break;
}
if (!coversUnmatchedMember(candidate, unmatchedMemberIds)) {
continue;
}
if (!canAddPair(candidate, counterpartsByMember)) {
continue;
}
addPair(selectedPairs, counterpartsByMember, candidate);
unmatchedMemberIds.remove(candidate.getFieldMemberId());
unmatchedMemberIds.remove(candidate.getExternalMemberId());
changed = true;
}
} while (changed && !unmatchedMemberIds(allMemberIds, counterpartsByMember).isEmpty());
Set<String> unmatchedMemberIds = unmatchedMemberIds(allMemberIds, counterpartsByMember);
if (!unmatchedMemberIds.isEmpty()) {
return new PairSelection(false, selectedPairs,
"페어링되지 않은 위원이 있습니다: " + String.join(", ", unmatchedMemberIds));
}
selectedPairs.sort(Comparator.comparing(PairCandidate::getFieldMemberId)
.thenComparing(PairCandidate::getExternalMemberId));
return new PairSelection(true, selectedPairs, "GREEDY_PAIRED");
}
private Map<String, Set<String>> createCounterpartMap(Set<String> memberIds) {
Map<String, Set<String>> counterpartsByMember = new HashMap<>();
memberIds.forEach(memberId -> counterpartsByMember.put(memberId, new HashSet<>()));
return counterpartsByMember;
}
private Set<String> unmatchedMemberIds(Set<String> allMemberIds,
Map<String, Set<String>> counterpartsByMember) {
return allMemberIds.stream()
.filter(memberId -> counterpartsByMember.getOrDefault(memberId, Set.of()).isEmpty())
.collect(Collectors.toCollection(LinkedHashSet::new));
}
private boolean coversUnmatchedMember(PairCandidate candidate, Set<String> unmatchedMemberIds) {
return unmatchedMemberIds.contains(candidate.getFieldMemberId())
|| unmatchedMemberIds.contains(candidate.getExternalMemberId());
}
private boolean canAddPair(PairCandidate candidate,
Map<String, Set<String>> counterpartsByMember) {
if (counterpartsByMember.get(candidate.getFieldMemberId())
.contains(candidate.getExternalMemberId())) {
return false;
}
return counterpartsByMember.get(candidate.getFieldMemberId()).size() < maxCounterpartsPerMember()
&& counterpartsByMember.get(candidate.getExternalMemberId()).size()
< maxCounterpartsPerMember();
}
private void addPair(List<PairCandidate> selectedPairs,
Map<String, Set<String>> counterpartsByMember, PairCandidate candidate) {
selectedPairs.add(candidate);
counterpartsByMember.get(candidate.getFieldMemberId()).add(candidate.getExternalMemberId());
counterpartsByMember.get(candidate.getExternalMemberId()).add(candidate.getFieldMemberId());
}
private Comparator<PairCandidate> pairComparator(Map<String, Long> assignmentCountByPair) {
// 1순위: 해당 조가 갈 수 있는 센터/날짜 후보 수
// 2순위: 거주지 유사도
// 이후 id 정렬은 같은 점수일 때 결과가 매번 흔들리지 않게 하기 위한 tie-breaker입니다.
return Comparator.comparingLong((PairCandidate candidate) ->
assignmentCountByPair.getOrDefault(pairKey(candidate), 0L))
.reversed()
.thenComparing(Comparator.comparingInt(this::unmatchedPairScore).reversed())
.thenComparing(PairCandidate::getFieldMemberId)
.thenComparing(PairCandidate::getExternalMemberId);
}
private int unmatchedPairScore(PairCandidate candidate) {
return candidate.getResidenceMatchScore();
}
private int maxCounterpartsPerMember() {
return pairingProperties.getRule().getMaxCounterpartsPerMember();
}
private String pairKey(PairCandidate candidate) {
return candidate.getFieldMemberId() + "|" + candidate.getExternalMemberId();
}
public record PairSelection(boolean hasSolution, List<PairCandidate> selectedPairs,
String status) {
}
}

View File

@@ -11,6 +11,7 @@ import com.kri.p6.ncrc.pairing.common.enums.ExperienceType;
import com.kri.p6.ncrc.pairing.common.enums.Gender;
import com.kri.p6.ncrc.pairing.config.PairingProperties;
import com.kri.p6.ncrc.pairing.dto.excel.output.ABPairExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AppliedSettingExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.AssignmentResultExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.CandidateSummaryExcelDto;
import com.kri.p6.ncrc.pairing.dto.excel.output.PairingSummaryExcelDto;
@@ -52,7 +53,7 @@ public class PairingSolverService {
if (!selection.hasSolution()) {
return emptyResult(data, candidates, selection.status());
}
return toResult(data, candidates, selection.selectedAssignments(), selection.status());
return toResult(data, candidates, selection.selectedAssignments(), selection.status(), Set.of());
}
public SolveSelection select(PairingCandidates candidates) {
@@ -61,65 +62,40 @@ public class PairingSolverService {
public SolveSelection select(PairingCandidates candidates,
Map<String, Set<String>> existingCounterpartsByMember) {
return select(candidates, existingCounterpartsByMember, Map.of(), Set.of());
return select(candidates, existingCounterpartsByMember, Map.of());
}
public SolveSelection select(PairingCandidates candidates,
Map<String, Set<String>> existingCounterpartsByMember, Map<String, Integer> visitCountsByMember,
Set<String> mandatoryMemberIds) {
return select(candidates, existingCounterpartsByMember, visitCountsByMember, mandatoryMemberIds,
true);
}
private SolveSelection select(PairingCandidates candidates,
Map<String, Set<String>> existingCounterpartsByMember, Map<String, Integer> visitCountsByMember,
Set<String> mandatoryMemberIds, boolean enforceCounterpartLimit) {
Map<String, Set<String>> existingCounterpartsByMember,
Map<String, Integer> visitCountsByMember) {
if (candidates.getAssignmentCandidates().isEmpty()) {
return new SolveSelection(false, List.of(), "배정 가능한 후보가 없습니다.");
}
CpModel model = new CpModel();
List<AssignmentCandidate> assignmentCandidates = candidates.getAssignmentCandidates();
// CP-SAT에서는 각 배정 후보를 0/1 변수로 봅니다.
// 1이면 해당 후보 선택, 0이면 미선택입니다.
BoolVar[] assignmentVars = createAssignmentVars(model, assignmentCandidates);
Map<String, BoolVar> pairUsedVars = createPairUsedVars(model, assignmentCandidates);
Map<String, BoolVar> pairDayVars = createPairDayVars(model, assignmentCandidates);
Map<String, BoolVar> pairDayAdjacentVars = createPairDayAdjacentVars(model, assignmentCandidates);
Map<String, BoolVar> memberUsedVars = createMemberUsedVars(model, assignmentCandidates);
Set<String> missingMandatoryMemberIds = mandatoryMemberIds.stream()
.filter(memberId -> !memberUsedVars.containsKey(memberId))
.collect(Collectors.toCollection(LinkedHashSet::new));
if (!missingMandatoryMemberIds.isEmpty()) {
return new SolveSelection(false, List.of(),
"필수 조편성 위원의 배정 후보가 없습니다: " + String.join(", ", missingMandatoryMemberIds));
}
// 현재 메인 배정은 Greedy가 담당하지만, CP-SAT 모델은 부분 최적화와 기존 방식 호환을 위해 유지합니다.
linkHelperVars(model, assignmentCandidates, assignmentVars, pairUsedVars, pairDayVars, pairDayAdjacentVars);
linkMemberUsedVars(model, assignmentCandidates, assignmentVars, memberUsedVars);
addMandatoryMemberUsed(model, memberUsedVars, mandatoryMemberIds);
addCenterAssignedAtMostOnce(model, assignmentCandidates, assignmentVars);
addPairDailyCapacity(model, assignmentCandidates, assignmentVars);
addMemberDailyOnePair(model, assignmentCandidates, pairDayVars);
addPairDailyOneAdjacentClassification(model, assignmentCandidates, pairDayAdjacentVars);
if (enforceCounterpartLimit) {
addCumulativeBuddyLimit(model, assignmentCandidates, pairUsedVars,
existingCounterpartsByMember);
}
model.maximize(createObjective(assignmentCandidates, assignmentVars, memberUsedVars,
visitCountsByMember));
addCumulativeBuddyLimit(model, assignmentCandidates, pairUsedVars,
existingCounterpartsByMember);
model.maximize(createObjective(assignmentCandidates, assignmentVars, visitCountsByMember));
CpSolver solver = new CpSolver();
solver.getParameters().setMaxTimeInSeconds(pairingProperties.getSolver().getMaxTimeSeconds());
solver.getParameters().setNumSearchWorkers(pairingProperties.getSolver().getNumSearchWorkers());
CpSolverStatus status = solver.solve(model);
if (status != CpSolverStatus.OPTIMAL && status != CpSolverStatus.FEASIBLE) {
if (enforceCounterpartLimit && !mandatoryMemberIds.isEmpty()) {
SolveSelection counterpartRelaxedSelection = select(candidates,
existingCounterpartsByMember, visitCountsByMember, mandatoryMemberIds, false);
if (counterpartRelaxedSelection.hasSolution()) {
return new SolveSelection(true, counterpartRelaxedSelection.selectedAssignments(),
counterpartRelaxedSelection.status() + ", counterpartLimitRelaxed=true");
}
}
return new SolveSelection(false, List.of(), "solver가 feasible 해를 찾지 못했습니다: " + status);
}
return new SolveSelection(true, collectSelectedAssignments(assignmentCandidates, assignmentVars, solver), status.name());
@@ -127,7 +103,12 @@ public class PairingSolverService {
public PairingResult buildResult(PairingData data, PairingCandidates candidates,
List<AssignmentCandidate> selectedAssignments, String status) {
return toResult(data, candidates, selectedAssignments, status);
return toResult(data, candidates, selectedAssignments, status, Set.of());
}
public PairingResult buildResult(PairingData data, PairingCandidates candidates,
List<AssignmentCandidate> selectedAssignments, String status, Set<String> pairedMemberIds) {
return toResult(data, candidates, selectedAssignments, status, pairedMemberIds);
}
private BoolVar[] createAssignmentVars(CpModel model, List<AssignmentCandidate> candidates) {
@@ -153,16 +134,6 @@ public class PairingSolverService {
.collect(Collectors.toMap(Function.identity(), key -> model.newBoolVar("pair_day_adjacent_" + key)));
}
private Map<String, BoolVar> createMemberUsedVars(CpModel model,
List<AssignmentCandidate> candidates) {
return candidates.stream()
.flatMap(candidate -> Stream.of(candidate.getFieldMemberId(),
candidate.getExternalMemberId()))
.distinct()
.collect(Collectors.toMap(Function.identity(),
memberId -> model.newBoolVar("member_used_" + memberId)));
}
private void linkHelperVars(CpModel model, List<AssignmentCandidate> candidates,
BoolVar[] assignmentVars, Map<String, BoolVar> pairUsedVars, Map<String, BoolVar> pairDayVars,
Map<String, BoolVar> pairDayAdjacentVars) {
@@ -174,40 +145,16 @@ public class PairingSolverService {
}
}
private void linkMemberUsedVars(CpModel model, List<AssignmentCandidate> candidates,
BoolVar[] assignmentVars, Map<String, BoolVar> memberUsedVars) {
Map<String, List<Integer>> indexesByMember = new HashMap<>();
for (int i = 0; i < candidates.size(); i++) {
AssignmentCandidate candidate = candidates.get(i);
indexesByMember.computeIfAbsent(candidate.getFieldMemberId(), key -> new ArrayList<>())
.add(i);
indexesByMember.computeIfAbsent(candidate.getExternalMemberId(), key -> new ArrayList<>())
.add(i);
model.addLessOrEqual(assignmentVars[i], memberUsedVars.get(candidate.getFieldMemberId()));
model.addLessOrEqual(assignmentVars[i], memberUsedVars.get(candidate.getExternalMemberId()));
}
indexesByMember.forEach((memberId, indexes) -> model.addLessOrEqual(
memberUsedVars.get(memberId), LinearExpr.sum(toLinearArgumentArray(indexes,
assignmentVars))));
}
private void addMandatoryMemberUsed(CpModel model, Map<String, BoolVar> memberUsedVars,
Set<String> mandatoryMemberIds) {
mandatoryMemberIds.stream()
.map(memberUsedVars::get)
.filter(Objects::nonNull)
.forEach(memberUsedVar -> model.addEquality(memberUsedVar, 1));
}
private void addCenterAssignedAtMostOnce(CpModel model, List<AssignmentCandidate> candidates,
BoolVar[] assignmentVars) {
// 하나의 센터는 최대 1번만 배정됩니다.
groupIndexes(candidates, AssignmentCandidate::getCenterId).values()
.forEach(indexes -> model.addAtMostOne(toLiteralArray(indexes, assignmentVars)));
}
private void addPairDailyCapacity(CpModel model, List<AssignmentCandidate> candidates,
BoolVar[] assignmentVars) {
// 같은 조가 하루에 방문할 수 있는 센터 수 상한입니다.
groupIndexes(candidates, this::pairDayKey).values().forEach(indexes -> model.addLessOrEqual(
LinearExpr.sum(toLinearArgumentArray(indexes, assignmentVars)),
pairingProperties.getRule().getMaxCentersPerPairPerDay()));
@@ -215,6 +162,7 @@ public class PairingSolverService {
private void addMemberDailyOnePair(CpModel model, List<AssignmentCandidate> candidates,
Map<String, BoolVar> pairDayVars) {
// 한 위원은 같은 날짜에 여러 조로 동시에 활동할 수 없습니다.
Map<String, Set<String>> pairDayKeysByMemberDay = candidates.stream()
.collect(Collectors.groupingBy(candidate -> candidate.getFieldMemberId() + "|" + candidate.getDate(),
Collectors.mapping(this::pairDayKey, Collectors.toSet())));
@@ -231,6 +179,7 @@ public class PairingSolverService {
private void addPairDailyOneAdjacentClassification(CpModel model,
List<AssignmentCandidate> candidates, Map<String, BoolVar> pairDayAdjacentVars) {
// 같은 조/같은 날짜에는 하나의 인접지역 분류만 방문합니다.
Map<String, Set<String>> adjacentKeysByPairDay = candidates.stream()
.collect(Collectors.groupingBy(this::pairDayKey,
Collectors.mapping(this::pairDayAdjacentKey, Collectors.toSet())));
@@ -240,6 +189,7 @@ public class PairingSolverService {
private void addCumulativeBuddyLimit(CpModel model, List<AssignmentCandidate> candidates,
Map<String, BoolVar> pairUsedVars, Map<String, Set<String>> existingCounterpartsByMember) {
// 위원 1명당 누적 상대 위원 수 제한입니다. 현재 업무 기준은 application.yaml의 max-counterparts-per-member입니다.
Map<String, Set<String>> pairKeysByMember = candidates.stream()
.collect(Collectors.groupingBy(AssignmentCandidate::getFieldMemberId,
Collectors.mapping(this::pairKey, Collectors.toSet())));
@@ -270,8 +220,9 @@ public class PairingSolverService {
}
private LinearExpr createObjective(List<AssignmentCandidate> candidates,
BoolVar[] assignmentVars, Map<String, BoolVar> memberUsedVars,
Map<String, Integer> visitCountsByMember) {
BoolVar[] assignmentVars, Map<String, Integer> visitCountsByMember) {
// soft rule 점수입니다. 센터를 많이 배정하는 점수가 가장 크고,
// 희망지역/거주지/방문 균형은 같은 배정 수 안에서 우열을 정하는 보조 점수입니다.
List<LinearArgument> vars = new ArrayList<>();
List<Long> weights = new ArrayList<>();
for (int i = 0; i < assignmentVars.length; i++) {
@@ -284,13 +235,6 @@ public class PairingSolverService {
- memberBalancePenalty(candidate, visitCountsByMember));
}
memberUsedVars.forEach((memberId, memberUsedVar) -> {
if (visitCountsByMember.getOrDefault(memberId, 0) == 0) {
vars.add(memberUsedVar);
weights.add(pairingProperties.getObjective().getUsedMemberWeight());
}
});
return LinearExpr.weightedSum(vars.toArray(LinearArgument[]::new),
weights.stream().mapToLong(Long::longValue).toArray());
}
@@ -316,11 +260,12 @@ public class PairingSolverService {
return selected;
}
private PairingResult toResult(PairingData data, PairingCandidates candidates,
List<AssignmentCandidate> selectedAssignments, String status) {
List<AssignmentCandidate> selectedAssignments, String status, Set<String> pairedMemberIds) {
Set<String> assignedCenterIds = selectedAssignments.stream().map(AssignmentCandidate::getCenterId).collect(Collectors.toSet());
Set<String> usedMemberIds = selectedAssignments.stream()
.flatMap(candidate -> Stream.of(candidate.getFieldMemberId(), candidate.getExternalMemberId()))
.collect(Collectors.toSet());
usedMemberIds.addAll(pairedMemberIds);
Map<String, Member> memberMap = data.getMembers().stream()
.collect(Collectors.toMap(Member::getId, Function.identity(), (left, right) -> left));
Map<String, Center> centerMap = data.getCenters().stream()
@@ -350,8 +295,9 @@ public class PairingSolverService {
.abPairs(abPairBuildResult.rows())
.candidateSummaries(createCandidateSummaries(data, candidates, assignments.size(),
unassignedCenters.size(), unusedMembers.size(), countABGroups(abPairMatches)))
.appliedSettings(createAppliedSettings())
.validationErrors(List.of())
.ruleViolations(createRuleChecks(data, selectedAssignments, abPairMatches))
.ruleViolations(createRuleChecks(data, selectedAssignments, abPairMatches, pairedMemberIds))
.build();
}
@@ -367,6 +313,7 @@ public class PairingSolverService {
.summaries(createSummaries(data, candidates, 0, data.getCenters().size(), data.getMembers().size(), 0, reason))
.abPairs(List.of())
.candidateSummaries(createCandidateSummaries(data, candidates, 0, data.getCenters().size(), data.getMembers().size(), 0))
.appliedSettings(createAppliedSettings())
.validationErrors(List.of())
.ruleViolations(List.of(new RuleViolationExcelDto("solver feasible 해", "FAIL", reason)))
.build();
@@ -395,8 +342,8 @@ public class PairingSolverService {
}
private UnassignedCenterExcelDto toUnassignedCenter(Center center, Map<String, Set<String>> reasonMap) {
Set<String> reasons = new LinkedHashSet<>((Collection<String>) (reasonMap == null ? Set.of()
: reasonMap.getOrDefault(center.getId(), Set.of())));
Set<String> reasons = new LinkedHashSet<>(reasonMap == null ? Set.of()
: reasonMap.getOrDefault(center.getId(), Set.of()));
reasons.add("solver 최적화에서 선택되지 않음");
return new UnassignedCenterExcelDto(center.getId(), center.getMunicipalityId(), String.join(", ", reasons));
}
@@ -521,8 +468,96 @@ public class PairingSolverService {
new CandidateSummaryExcelDto("AB 그룹 수", String.valueOf(abGroupCount), "후처리로 구성된 AB 그룹 수"));
}
private List<AppliedSettingExcelDto> createAppliedSettings() {
PairingProperties.Excel excel = pairingProperties.getExcel();
PairingProperties.Code code = pairingProperties.getCode();
PairingProperties.Rule rule = pairingProperties.getRule();
PairingProperties.Preference preference = pairingProperties.getPreference();
PairingProperties.Objective objective = pairingProperties.getObjective();
PairingProperties.Candidate candidate = pairingProperties.getCandidate();
PairingProperties.Solver solver = pairingProperties.getSolver();
return List.of(
setting("pairing.excel.header-row-index",
"엑셀 헤더로 사용할 행 인덱스",
excel.getHeaderRowIndex()),
setting("pairing.code.region-code-length",
"지역코드 정규화 길이", code.getRegionCodeLength()),
setting("pairing.code.residence-code-length",
"거주지코드 정규화 길이",
code.getResidenceCodeLength()),
setting("pairing.code.residence-match-prefix-length",
"거주지 일치 판단에 사용하는 앞자리 길이",
code.getResidenceMatchPrefixLength()),
setting("pairing.code.any-region-code",
"희망지역 anywhere로 처리하는 코드",
code.getAnyRegionCode()),
setting("pairing.rule.max-centers-per-pair-per-day",
"페어가 하루에 방문할 수 있는 최대 센터 수",
rule.getMaxCentersPerPairPerDay()),
setting("pairing.rule.max-counterparts-per-member",
"위원 1명당 허용되는 상대 위원 최대 수",
rule.getMaxCounterpartsPerMember()),
setting("pairing.rule.max-member-visit-average-ratio-percent",
"위원별 방문 수 상한을 평균 대비 몇 %까지 허용할지",
rule.getMaxMemberVisitAverageRatioPercent()),
setting("pairing.preference.anywhere-rank",
"선호지역 anywhere를 의미하는 순위",
preference.getAnywhereRank()),
setting("pairing.preference.ignored-rank",
"선호지역 고려하지 않음을 의미하는 순위",
preference.getIgnoredRank()),
setting("pairing.preference.active-wildcard-fallback-enabled",
"희망지역 고려하지 않음을 wildcard로 적극 사용할지",
preference.isActiveWildcardFallbackEnabled()),
setting("pairing.preference.wildcard-fallback-score-bonus",
"wildcard 후보에 추가할 점수",
preference.getWildcardFallbackScoreBonus()),
setting("pairing.objective.assignment-weight",
"센터 하나를 더 배정하는 것에 부여하는 기본 점수",
objective.getAssignmentWeight()),
setting("pairing.objective.preference-base-weight",
"희망지역 매칭 품질에 부여하는 기본 점수",
objective.getPreferenceBaseWeight()),
setting("pairing.objective.preference-rank-penalty",
"희망순위가 낮아질 때 감점하는 점수",
objective.getPreferenceRankPenalty()),
setting("pairing.objective.residence-match-weight",
"거주지 유사도 점수에 곱하는 가중치",
objective.getResidenceMatchWeight()),
setting("pairing.objective.member-balance-weight",
"방문 수가 많은 위원을 더 선택하지 않도록 감점하는 가중치",
objective.getMemberBalanceWeight()),
setting("pairing.candidate.max-pair-candidates-per-member",
"위원별 페어 후보 축소 상한, 0이면 무제한",
candidate.getMaxPairCandidatesPerMember()),
setting("pairing.candidate.max-dispatch-regions-per-pair",
"페어별 파견 권역 후보 축소 상한, 0이면 무제한",
candidate.getMaxDispatchRegionsPerPair()),
setting("pairing.candidate.max-assignments-per-center",
"센터별 배정 후보 축소 상한",
candidate.getMaxAssignmentsPerCenter()),
setting("pairing.candidate.max-assignments-per-member",
"위원별 배정 후보 축소 상한",
candidate.getMaxAssignmentsPerMember()),
setting("pairing.candidate.max-dates-per-assignment-candidate",
"하나의 페어-센터 조합에서 확장할 날짜 후보 상한",
candidate.getMaxDatesPerAssignmentCandidate()),
setting("pairing.solver.max-time-seconds",
"CP-SAT 사용 시 허용할 최대 탐색 시간",
solver.getMaxTimeSeconds()),
setting("pairing.solver.num-search-workers",
"CP-SAT 사용 시 사용할 worker 수",
solver.getNumSearchWorkers())
);
}
private AppliedSettingExcelDto setting(String name, String description, Object value) {
return new AppliedSettingExcelDto(name, description, String.valueOf(value));
}
private List<RuleViolationExcelDto> createRuleChecks(PairingData data,
List<AssignmentCandidate> selectedAssignments, Map<String, ABPairMatch> abPairMatches) {
List<AssignmentCandidate> selectedAssignments, Map<String, ABPairMatch> abPairMatches,
Set<String> pairedMemberIds) {
Map<String, Member> memberMap = data.getMembers().stream()
.collect(Collectors.toMap(Member::getId, Function.identity(), (left, right) -> left));
Map<String, Center> centerMap = data.getCenters().stream()
@@ -538,8 +573,9 @@ public class PairingSolverService {
checks.add(checkHistoryCenter(selectedAssignments, memberMap));
checks.add(checkHoliday(selectedAssignments, commonUnavailableDates(data)));
checks.add(checkABDateOverlap(abPairMatches));
checks.add(checkAllMembersUsed(data, selectedAssignments));
checks.add(checkAllMembersUsed(data, selectedAssignments, pairedMemberIds));
checks.add(checkMemberVisitBalance(data, selectedAssignments));
checks.add(checkMemberVisitUpperBound(data, selectedAssignments));
return checks;
}
@@ -638,11 +674,12 @@ public class PairingSolverService {
}
private RuleViolationExcelDto checkAllMembersUsed(PairingData data,
List<AssignmentCandidate> assignments) {
List<AssignmentCandidate> assignments, Set<String> pairedMemberIds) {
Set<String> usedMemberIds = assignments.stream()
.flatMap(candidate -> Stream.of(candidate.getFieldMemberId(),
candidate.getExternalMemberId()))
.collect(Collectors.toSet());
usedMemberIds.addAll(pairedMemberIds);
List<String> unusedMemberIds = data.getMembers().stream()
.map(Member::getId)
.filter(memberId -> !usedMemberIds.contains(memberId))
@@ -662,10 +699,39 @@ public class PairingSolverService {
long min = visitCounts.values().stream().mapToLong(Long::longValue).min().orElse(0L);
long max = visitCounts.values().stream().mapToLong(Long::longValue).max().orElse(0L);
double average = visitCounts.values().stream().mapToLong(Long::longValue).average().orElse(0.0D);
String detail = "min=" + min + ", max=" + max + ", avg=" + String.format("%.2f", average);
long maxAllowed = maxMemberVisitCount(data);
String detail = "min=" + min + ", max=" + max + ", avg=" + String.format("%.2f", average)
+ ", maxAllowed=" + maxAllowed;
return new RuleViolationExcelDto("위원별 방문 센터 수 균등 배분", "PASS", detail);
}
private long maxMemberVisitCount(PairingData data) {
if (data.getMembers().isEmpty()) {
return 0L;
}
double fullAssignmentAverage = (double) data.getCenters().size() * 2D
/ data.getMembers().size();
return Math.max(1L, (long) Math.ceil(fullAssignmentAverage
* pairingProperties.getRule().getMaxMemberVisitAverageRatioPercent() / 100D));
}
private RuleViolationExcelDto checkMemberVisitUpperBound(PairingData data,
List<AssignmentCandidate> assignments) {
Map<String, Long> visitCounts = data.getMembers().stream()
.collect(Collectors.toMap(Member::getId, member -> 0L, (left, right) -> left));
assignments.forEach(candidate -> {
visitCounts.merge(candidate.getFieldMemberId(), 1L, Long::sum);
visitCounts.merge(candidate.getExternalMemberId(), 1L, Long::sum);
});
long max = visitCounts.values().stream().mapToLong(Long::longValue).max().orElse(0L);
long maxAllowed = maxMemberVisitCount(data);
String detail = "max=" + max + ", maxAllowed=" + maxAllowed
+ ", ratioPercent=" + pairingProperties.getRule()
.getMaxMemberVisitAverageRatioPercent();
return new RuleViolationExcelDto("위원 최대 방문 센터 수 상한",
max <= maxAllowed ? "PASS" : "FAIL", detail);
}
private String formatDates(Set<LocalDate> dates) {
return dates.stream().sorted().map(LocalDate::toString).collect(Collectors.joining(", "));
}

View File

@@ -61,37 +61,44 @@ pairing:
# 한 페어가 하루에 방문할 수 있는 최대 센터 수입니다. (HARD)
max-centers-per-pair-per-day: 3
# 한 위원이 전체 기간 동안 가질 수 있는 최대 상대 파트너 수입니다.(HARD)
max-counterparts-per-member: 2
max-counterparts-per-member: 3
# 위원 1명의 최대 방문 센터 수 상한입니다. 전체 센터가 모두 배정됐을 때 평균 방문 수의 N%를 넘지 못하게 합니다.(HARD)
max-member-visit-average-ratio-percent: 130
preference:
# 선호지역 00(anywhere)을 희망지역 매칭표에서 표현하는 rank 값입니다.(HARD)
anywhere-rank: 0
# 희망지역 매칭표에서 해당 위원의 선호지역을 고려하지 않는 wildcard rank 값입니다.(HARD)
ignored-rank: 99
# true면 선호지역 미일치 후보도 99 wildcard 매칭표 규칙을 적극 활용합니다. false로 바꾸면 기존 보수적 점수로 되돌아갑니다.
active-wildcard-fallback-enabled: true
# wildcard 후보가 후보 축소/배정 선택에서 너무 뒤로 밀리지 않도록 더하는 점수입니다. 값이 클수록 미배정 센터 감소를 우선합니다.
wildcard-fallback-score-bonus: 25_000
objective:
# 센터 1개를 배정했을 때 부여하는 최우선 점수입니다. 다른 soft score 총합보다 충분히 커야 합니다.
assignment-weight: 1_000_000
# 최종 배정에 위원 1명이 새로 포함될 때 부여하는 점수입니다. 값이 클수록 미사용 위원을 줄이는 방향으로 탐색합니다.
used-member-weight: 300_000
# 이미 많이 배정된 위원이 추가 배정될 때 차감하는 점수입니다. 값이 클수록 위원별 방문 센터 수를 평균에 가깝게 분산합니다.
member-balance-weight: 100_000
# 거주지 prefix가 일치하는 페어에 부여하는 점수입니다. 값이 클수록 거주지 유사도를 더 중요하게 봅니다.
residence-match-weight: 30_000
member-balance-weight: 20_000
# 희망지역 매칭 순위 점수의 기준값입니다. 값이 클수록 선호지역 품질 영향이 커집니다.
preference-base-weight: 1_000
preference-base-weight: 30_000
# 매칭 순위가 1 내려갈 때마다 차감하는 점수입니다. 값이 클수록 낮은 순위를 더 강하게 불리하게 봅니다.
preference-rank-penalty: 100
preference-rank-penalty: 1_000
# 거주지 prefix가 일치하는 페어에 부여하는 점수입니다. 값이 클수록 거주지 유사도를 더 중요하게 봅니다.
residence-match-weight: 10_000
candidate:
# 위원 1명당 유지할 상대 위원 후보 수입니다. 0이면 제한하지 않습니다.
# 모든 위원 조편성이 최우선 HARD 룰이므로 기본값은 제한 없음으로 둡니다.
max-pair-candidates-per-member: 0
# 현장+외부 페어 1개가 solver에 넘기기 전에 유지할 최대 파견 권역 후보 수입니다.
max-dispatch-regions-per-pair: 20
max-dispatch-regions-per-pair: 0
# 센터 1개마다 solver에 넘기기 전에 유지할 최대 배정 후보 수입니다.
max-assignments-per-center: 100
max-assignments-per-center: 1_000
# 위원 1명(현장/외부 모두 포함)이 solver 후보에 등장할 수 있는 최대 횟수입니다.
max-assignments-per-member: 160
# 페어-센터 후보 1개에서 생성할 최대 가능 날짜 수입니다. 값이 클수록 전원 조편성 가능성은 커지지만 solver 후보 수가 늘어납니다.
max-dates-per-assignment-candidate: 5
max-assignments-per-member: 3_000
# 페어-센터 후보 1개에서 생성할 최대 가능 날짜 수입니다. 기간 전체에 고르게 분산해 날짜 쏠림을 줄입니다.
max-dates-per-assignment-candidate: 80
solver:
# OR-Tools CP-SAT solver가 한 요청에서 탐색할 최대 시간(초)입니다.
max-time-seconds: 120.0
max-time-seconds: 360.0
# OR-Tools CP-SAT 병렬 탐색 worker 수입니다. 서버 CPU 상황에 맞춰 조정합니다.
num-search-workers: 15

View File

@@ -0,0 +1,105 @@
# 배정 규칙 및 완화 검토 자료
이 문서는 개발자가 아닌 업무 담당자와 배정 기준을 논의하기 위한 설명 자료입니다.
현재 프로그램은 "모든 위원을 조편성한 뒤, 가능한 많은 센터를 일정표에 배정"하는 것을 목표로 합니다. 단, 일부 규칙은 반드시 지켜야 하므로 센터가 남을 수 있습니다.
## 용어 설명
| 용어 | 설명 |
| --- | --- |
| 현장위원/외부위원 | 한 조를 구성하는 두 역할입니다. 현재 기본 조는 현장위원 1명 + 외부위원 1명입니다. |
| 센터 배정 | 특정 날짜에 특정 조가 특정 센터를 방문하도록 정하는 것입니다. |
| 상피제 | 위원의 활동지역과 같은 파견 권역에는 배정하지 않는 규칙입니다. |
| 희망지역 00 | 어디든 가능하다는 응답입니다. |
| 희망지역 99 | 희망지역을 고려하지 않는다는 매칭표의 wildcard 규칙입니다. |
| Greedy | 그때그때 가장 좋아 보이는 선택을 빠르게 고르는 방식입니다. 사람으로 비유하면 "막히기 쉬운 센터부터 먼저 잡고, 가능한 후보 중 점수가 좋은 조를 넣는 방식"입니다. |
| CP-SAT | 여러 조건을 동시에 만족하는 조합을 찾는 최적화 도구입니다. 모든 후보를 놓고 수학적으로 좋은 조합을 찾지만, 후보가 많으면 시간이 오래 걸립니다. |
| repair pass | 1차 배정 후 남은 센터를 줄이기 위해 일부 배정을 빼고 다시 끼워 넣어 보는 후처리입니다. |
## 현재 처리 순서
1. 엑셀 파일을 읽습니다.
2. 날짜, 지역코드, 성별, 경력, 불가능일, 희망지역 등 입력값을 정리합니다.
3. 공휴일과 토/일을 공통 불가능일로 추가합니다.
4. 입력 데이터의 필수값과 참조 오류를 검증합니다.
5. 가능한 후보를 생성합니다.
6. 모든 위원이 최소 1개 조에 포함되도록 조편성을 먼저 합니다.
7. 확정된 조를 기준으로 센터 일정을 Greedy 방식으로 배정합니다.
8. 미배정 센터를 줄이기 위해 후처리를 순서대로 수행합니다.
9. 결과 엑셀을 생성합니다.
## 현재 Hard Rule
Hard Rule은 반드시 지켜야 하는 규칙입니다. 이 규칙을 어기면서 센터를 더 배정하지 않습니다.
| 우선순위 | 규칙 | 설명 | 현재 완화 가능성 |
| --- | --- | --- | --- |
| 0 | 모든 위원 조편성 | 모든 위원은 최소 1개 이상의 조에 포함되어야 합니다. | 완화 불가 |
| 1 | 역할 조합 | 현장위원 1명 + 외부위원 1명으로 조를 구성합니다. | 낮음 |
| 2 | 위원 활동 가능 기간 | 두 위원의 활동 가능 기간이 겹쳐야 조 후보가 됩니다. | 낮음 |
| 3 | 날짜 불가 | 위원, 지자체, 센터의 불가능일에는 배정하지 않습니다. | 중간 |
| 4 | 공통 불가능일 | 공휴일과 토/일에는 배정하지 않습니다. | 중간 |
| 5 | 상피제 | 위원의 활동지역과 같은 파견 권역에는 배정하지 않습니다. | 높음 |
| 6 | 여성전용센터 | 여성전용센터는 여성 위원 2명 조만 배정합니다. | 중간 |
| 7 | 기방문센터 제외 | 2023년에 해당 위원이 진행한 센터는 제외합니다. | 높음 |
| 8 | 센터 중복 배정 금지 | 센터 1개는 결과에서 최대 1번만 배정됩니다. | 완화 불가 |
| 9 | 같은 날짜 위원 중복 금지 | 한 위원은 같은 날짜에 여러 조로 동시에 활동할 수 없습니다. | 낮음 |
| 10 | 같은 조의 하루 방문 상한 | 같은 조는 하루 최대 3개 센터까지 방문합니다. | 높음 |
| 11 | 같은 조/날짜의 인접지역 분류 | 같은 조가 같은 날짜에는 하나의 인접지역 분류만 방문합니다. | 높음 |
| 12 | 위원당 상대 파트너 수 | 위원 1명당 최대 3명의 상대 위원까지만 허용합니다. | 높음 |
| 13 | 위원별 최대 방문 상한 | 전체 센터가 모두 배정됐을 때의 평균 방문 수 대비 130%를 넘지 않게 합니다. | 높음 |
## 현재 Soft Rule
Soft Rule은 가능하면 지키는 규칙입니다. Hard Rule을 모두 지킨 후보 중에서 더 좋은 후보를 고르는 기준입니다.
| 우선순위 | 규칙 | 설명 |
| --- | --- | --- |
| 1 | 배정 센터 수 최대화 | 가장 중요한 목표입니다. 희망지역 품질보다 센터를 더 많이 배정하는 것이 우선입니다. |
| 2 | 위원별 방문 수 균형 | 특정 위원에게 센터가 과도하게 몰리지 않도록 합니다. |
| 3 | 희망지역 매칭 품질 | 희망지역 매칭표의 우선순위가 좋은 후보를 선호합니다. |
| 4 | 희망지역 99 wildcard 활용 | 선호지역이 직접 맞지 않아도 "선호지역 고려하지 않음" 규칙으로 후보를 살릴 수 있습니다. 현재 옵션으로 켜져 있습니다. |
| 5 | 거주지 유사도 | 거주지 코드 앞 3자리, 없으면 2자리가 같은 조를 선호합니다. |
| 6 | 같은 조/같은 날짜 묶음 | 이미 같은 조가 같은 날짜에 같은 인접지역 분류를 방문한다면 추가 센터를 묶어서 배정하려고 합니다. |
## 후처리 방식
1차 Greedy 배정 후에도 남은 센터가 있으면 아래 순서로 다시 시도합니다.
| 순서 | 후처리 | 설명 |
| --- | --- | --- |
| 1 | 일반 repair | 미배정 센터 하나를 넣기 위해 충돌되는 기존 배정을 최대 2개까지 빼고 다시 배정합니다. |
| 2 | 저방문 위원 중심 repair | 방문 수가 적은 위원이 남은 센터에 들어갈 수 있는지 먼저 봅니다. |
| 3 | donor-swap repair | 방문 수가 많은 위원의 기존 배정을 빼고, 같은 센터를 저방문 위원이 포함된 조로 넘길 수 있는지 봅니다. |
| 4 | wildcard repair | 희망지역 99 wildcard로 살아난 후보를 남은 센터에 우선 적용해 봅니다. |
## Greedy와 CP-SAT의 현재 역할
현재 1차 배정은 Greedy 중심입니다.
Greedy는 빠르고 큰 데이터에 비교적 안정적으로 동작합니다. 대신 처음 선택한 조합이 뒤쪽 선택에 영향을 주므로, 항상 이론상 최적이라고 보장하지는 않습니다. 그래서 후처리 단계에서 일부 배정을 교환하면서 보정합니다.
CP-SAT는 조건을 모두 수학 모델로 만들어 더 좋은 조합을 찾는 방식입니다. 다만 후보 수가 커지면 시간이 매우 오래 걸리고 PC 사양 영향을 크게 받습니다. 현재 프로젝트에서는 CP-SAT 코드를 유지하되, 전체 배정의 중심은 Greedy로 옮겨 둔 상태입니다.
## 완화하면 미배정 센터가 늘어날 가능성이 큰 순서
아래 순서는 "센터 배정 수 증가 가능성" 기준입니다. 실제 정책적으로 허용 가능한지는 별도 협의가 필요합니다.
| 추천 순서 | 완화 대상 | 기대 효과 | 업무 리스크 |
| --- | --- | --- | --- |
| 1 | 위원별 최대 방문 상한 130% | 현재 max=24에서 더 많은 센터를 넣을 여지가 생깁니다. | 일부 위원에게 방문이 몰릴 수 있습니다. |
| 2 | 위원당 상대 파트너 수 3명 | 조 선택지가 늘어나 날짜/센터 후보가 크게 늘 수 있습니다. | 한 위원이 여러 사람과 조를 이루게 되어 운영 복잡도가 증가합니다. |
| 3 | 같은 조 하루 최대 3개 센터 | 같은 날짜에 더 많은 센터를 묶을 수 있습니다. | 이동 가능성, 업무 피로도 확인이 필요합니다. |
| 4 | 같은 조/날짜의 인접지역 분류 1개 제한 | 인접지역 분류가 다른 센터도 같은 날 묶을 수 있습니다. | 실제 이동 동선이 나빠질 수 있습니다. |
| 5 | 기방문센터 제외 | 특정 위원이 과거 방문한 센터도 다시 갈 수 있어 후보가 늘어납니다. | 기존 정책 취지와 충돌할 수 있습니다. |
| 6 | 상피제 | 활동지역과 파견 권역이 같은 경우도 허용하면 후보가 늘어납니다. | 이해충돌 방지 취지와 충돌할 수 있습니다. |
| 7 | 날짜 불가 일부 완화 | 위원/센터/지자체 일정 제약이 줄어듭니다. | 실제 운영 가능 여부 확인이 필요합니다. |
| 8 | 공휴일/토/일 배정 허용 | 날짜 후보가 늘어납니다. | 운영 정책상 허용 가능성이 낮습니다. |
| 9 | 여성전용센터 성별 조건 | 일부 센터 후보가 늘어납니다. | 정책 리스크가 큽니다. |
## 현재 결과 해석 시 주의점
미배정 센터가 남는다고 해서 희망지역만 문제라는 뜻은 아닙니다. 현재는 희망지역 99 wildcard도 사용하도록 열어 둔 상태입니다. 그래도 남는 센터는 날짜, 상피제, 성별, 기방문센터, 하루 방문 상한, 파트너 수, 방문 수 상한이 복합적으로 막고 있을 가능성이 큽니다.
따라서 클라이언트와 논의할 때는 "희망지역을 더 넓게 보는 것"보다 "어떤 Hard Rule을 어느 수준까지 완화할 수 있는지"가 배정률 개선의 핵심입니다.