[Holliverse] 이탈률 구현 설계 (2) - 오케스트레이션 구축

app:
  churn:
    # 최종 이탈 점수 구간별 위험도 기준.
    grade:
      high: ${APP_CHURN_GRADE_HIGH:80}
      medium: ${APP_CHURN_GRADE_MEDIUM:50}
    rules:
      contract:
        # 약정 종료가 가까울수록 구조적 churn risk를 높게 본다.
        remaining-weeks:
          - min: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_1_MIN:0}
            max: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_1_MAX:2}
            score: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_1_SCORE:20}
          - min: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_2_MIN:3}
            max: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_2_MAX:4}
            score: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_2_SCORE:16}
          - min: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_3_MIN:5}
            max: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_3_MAX:8}
            score: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_3_SCORE:12}
          - min: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_4_MIN:9}
            max: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_4_MAX:12}
            score: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_4_SCORE:8}
          - min: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_5_MIN:13}
            score: ${APP_CHURN_RULE_CONTRACT_REMAINING_WEEKS_5_SCORE:0}
        # 가입 초기 churn 가능성을 반영
        tenure-weeks:
          - min: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_1_MIN:0}
            max: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_1_MAX:4}
            score: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_1_SCORE:10}
          - min: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_2_MIN:5}
            max: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_2_MAX:12}
            score: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_2_SCORE:6}
          - min: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_3_MIN:13}
            score: ${APP_CHURN_RULE_CONTRACT_TENURE_WEEKS_3_SCORE:0}
      usage:
        # 제공량 대비 실제 사용률이 낮을수록 요금 대비 체감 가치가 낮다고 본다.
        allowance-usage-rate-pct:
          - min: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_1_MIN:0}
            max: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_1_MAX:10}
            score: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_1_SCORE:15}
          - min: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_2_MIN:11}
            max: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_2_MAX:30}
            score: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_2_SCORE:12}
          - min: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_3_MIN:31}
            max: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_3_MAX:50}
            score: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_3_SCORE:8}
          - min: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_4_MIN:51}
            score: ${APP_CHURN_RULE_USAGE_ALLOWANCE_USAGE_RATE_PCT_4_SCORE:0}
      member-action:
        # 최근 요금제 변경 횟수. 가격 민감도 signal이지만 비교/위약금 조회보다는 약하게 반영한다.
        change-mobile-count:
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_1_MIN:0}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_1_MAX:0}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_1_SCORE:0}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_2_MIN:1}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_2_MAX:1}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_2_SCORE:5}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_3_MIN:2}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_3_MAX:2}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_3_SCORE:8}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_4_MIN:3}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHANGE_MOBILE_COUNT_4_SCORE:15}
        # 요금제 비교 행동은 실시간 churn intent signal로 취급
        comparison-count:
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_1_MIN:0}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_1_MAX:0}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_1_SCORE:0}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_2_MIN:1}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_2_MAX:1}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_2_SCORE:8}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_3_MIN:2}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_3_MAX:2}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_3_SCORE:12}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_4_MIN:3}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_COMPARISON_COUNT_4_SCORE:15}
        # 위약금 조회는 churn intent signal 높은 점수 부여
        checked-penalty-fee-count:
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_1_MIN:0}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_1_MAX:0}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_1_SCORE:0}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_2_MIN:1}
            max: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_2_MAX:1}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_2_SCORE:25}
          - min: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_3_MIN:2}
            score: ${APP_CHURN_RULE_MEMBER_ACTION_CHECKED_PENALTY_FEE_COUNT_3_SCORE:35}
      member-dissatisfaction:
        # 상담 만족도 평균은 batch/default 성격의 불만 signal
        star-mean-score:
          - min: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_1_MIN:1.0}
            max: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_1_MAX:1.9}
            score: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_1_SCORE:15}
          - min: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_2_MIN:2.0}
            max: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_2_MAX:2.9}
            score: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_2_SCORE:10}
          - min: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_3_MIN:3.0}
            max: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_3_MAX:3.9}
            score: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_3_SCORE:5}
          - min: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_4_MIN:4.0}
            score: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_STAR_MEAN_SCORE_4_SCORE:0}
        # 상담 전체 감정 분석 결과 점수
        sentiment:
          negative: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_SENTIMENT_NEGATIVE:10}
          positive: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_SENTIMENT_POSITIVE:0}
          none: ${APP_CHURN_RULE_MEMBER_DISSATISFACTION_SENTIMENT_NONE:0}

@Override
public List<ChurnFeatureContribution> contribute(ChurnFeature feature) {
    MemberActionFeature memberActionFeature = (MemberActionFeature) feature;
    int comparisonScore = churnScoreBandResolver.resolveIntScore(
            churnScoringProperties.getRules().getMemberAction().getComparisonCount(),
            memberActionFeature.comparisonCount()
    );

    return List.of(
            new ChurnFeatureContribution(
                    ChurnSignalType.COMPARISON_COUNT,
                    String.valueOf(memberActionFeature.comparisonCount()),
                    comparisonScore
            )
    );
}

/**
 * 최종 점수 기준 등급 판정 정책.
 */
@Profile("admin")
@Component
@RequiredArgsConstructor
public class ChurnRiskGradePolicy {

    private final ChurnScoringProperties churnScoringProperties;

    public ChurnRiskGrade classify(int score) {
        if (score >= churnScoringProperties.getGrade().getHigh()) {
            return ChurnRiskGrade.HIGH;
        }

        if (score >= churnScoringProperties.getGrade().getMedium()) {
            return ChurnRiskGrade.MEDIUM;
        }

        return ChurnRiskGrade.LOW;
    }
}

POST /internal/v1/analysis-consultation
{
  "dispatchRequestId": "dispatch-001",
  "caseId": 101,
  "analyzeVersion": 1,
  "analysisId": 5001,
  "memberId": 10001,
  "status": "COMPLETED",
  "keywordTypes": 2,
  "keywordHits": 3,
  "consultationType": "NEGATIVE",
  "keywordCounts": [
    {
      "keywordId": 1,
      "businessKeywordId": 10,
      "keywordCode": "terminate",
      "keywordName": "해지",
      "count": 2,
      "negativeWeight": 10
    }
  ],
  "producedAt": "2026-03-27T10:15:00Z"
}

@Profile("admin")
@RequiredArgsConstructor
@RestController
@RequestMapping("/internal/v1/analysis-consultation")
public class InternalAnalysisWebhookController {
    private final HandleAnalysisConsultationUseCase useCase;

    @PostMapping
    public ResponseEntity<Void> receive(@RequestBody @Valid AnalysisResponseWebhookRequest request) {
        // 요청 처리
        useCase.execute(toCommand(request));

        // 응답 반환
        return ResponseEntity.accepted().build();
    }

    private AnalysisResponseCommand toCommand(AnalysisResponseWebhookRequest request) {
        // 키워드 목록 변환
        List<AnalysisResponseCommand.KeywordCountCommand> keywordCounts = request.keywordCounts() == null
                ? List.of()
                : request.keywordCounts().stream()
                .map(item -> new AnalysisResponseCommand.KeywordCountCommand(
                        item.keywordId(),
                        item.businessKeywordId(),
                        item.keywordCode(),
                        item.keywordName(),
                        item.count(),
                        item.negativeWeight()
                ))
                .toList();

        // 명령 변환
        return new AnalysisResponseCommand(
                "analysis.response.v1",
                request.dispatchRequestId(),
                null,
                request.caseId(),
                (long) request.analyzeVersion(),
                (long) request.analysisId(),
                request.memberId(),
                request.status().name(),
                toSentimentType(request.consultationType()),
                request.keywordTypes(),
                request.keywordHits(),
                keywordCounts,
                null,
                request.producedAt() != null ? request.producedAt() : java.time.Instant.now()
        );
    }

    private ConsultationSentimentType toSentimentType(Enum<?> consultationType) {
        // 기본 감정
        if (consultationType == null) {
            return ConsultationSentimentType.NONE;
        }

        // 감정 변환
        return ConsultationSentimentType.valueOf(consultationType.name());
    }
}

@Service
@Profile("admin")
@RequiredArgsConstructor
public class HandleAnalysisConsultationUseCase {
    private final ConsultationAnalysisPersistenceService persistenceService;
    private final MemberDissatisfactionAssembler assembler;
    private final CalculateChurnScoreService calculateChurnScoreService;

    @Transactional
    public ChurnEvaluationResult execute(AnalysisResponseCommand command) {
        // 입력 검증
        validate(command);

        // 분석 결과 저장
        persistenceService.save(command);

        // 상담 feature 생성
        MemberDissatisfactionFeature dissatisfactionFeature = assembler.assemble(command);

        // 이탈률 계산
        return calculateChurnScoreService.calculateAndStore(
                command,
                resolveBaseDate(command),
                dissatisfactionFeature
        );
    }

    private void validate(AnalysisResponseCommand command) {
        // 회원 확인
        if (command.memberId() == null) {
            throw new IllegalArgumentException("memberId는 필수입니다.");
        }

        // 상태 확인
        if (!CounselAnalysisStatus.COMPLETED.name().equals(command.status())) {
            throw new IllegalArgumentException("완료된 상담 분석 결과만 처리할 수 있습니다. status=" + command.status());
        }
    }
    
    ...
  
}

@Service
@Profile("admin")
@RequiredArgsConstructor
public class CalculateChurnScoreService {

    private final ChurnScorePolicy churnScorePolicy;
    private final ChurnRiskReasonFactory churnRiskReasonFactory;
    private final ChurnSnapshotStoreService churnSnapshotStoreService;
    private final MemberDissatisfactionFeatureSnapshotService memberDissatisfactionFeatureSnapshotService;

    /**
     * 스냅샷 계산.
     */
    public ChurnEvaluationResult calculateAndStore(
            AnalysisResponseCommand command,
            LocalDate baseDate,
            MemberDissatisfactionFeature dissatisfactionFeature
    ) {
        // feature 조립
        ChurnFeatureSet featureSet = new ChurnFeatureSet(Map.of(
                ChurnFeatureType.MEMBER_DISSATISFACTION,
                dissatisfactionFeature
        ));

        // 점수 계산
        ChurnScoreCalculationResult scoreResult = churnScorePolicy.calculateDetails(featureSet);

        // feature 스냅샷 저장
        memberDissatisfactionFeatureSnapshotService.sync(
                command.memberId(),
                command,
                dissatisfactionFeature,
                scoreResult
        );

        // 위험 사유 조립
        List<ChurnRiskReason> riskReasons = buildCounselRiskReasons(command, scoreResult);

        // 스냅샷 저장
        return churnSnapshotStoreService.store(
                command.memberId(),
                baseDate,
                ChurnRiskReason.Feature.COUNSEL,
                riskReasons
        );
    }

    /**
     * 상담 사유 조립.
     */
    private List<ChurnRiskReason> buildCounselRiskReasons(
            AnalysisResponseCommand command,
            ChurnScoreCalculationResult scoreResult
    ) {
        ...
    }

    /**
     * 감정 사유.
     */
    private Optional<ChurnRiskReason> buildSentimentReason(
            AnalysisResponseCommand command,
            ChurnScoreCalculationResult scoreResult
    ) {
       ...
    }

    /**
     * 키워드 사유.
     */
    private Optional<ChurnRiskReason> buildKeywordReason(
            AnalysisResponseCommand command,
            ChurnScoreCalculationResult scoreResult
    ) {
        ...
    }
}

/**
* Admin 이벤트 변환.
*/
private void sendAdminTarget(Long memberId, UserLogRequest request) {
    UserLogEventName eventName = UserLogEventName.from(request.eventName());
    if (!isAdminTarget(eventName)) {
        return;
    }

    adminLogFeaturesClient.sendLogFeature(
            memberId,
            eventName,
            request.timestamp()
    );
 }

/**
* 대상 이벤트.
*/
private boolean isAdminTarget(UserLogEventName eventName) {
   return eventName == UserLogEventName.CLICK_COMPARE
           || eventName == UserLogEventName.CLICK_PENALTY
           || eventName == UserLogEventName.CLICK_CHANGE;
}

/**
 * 실시간 로그 기반 feature customer -> admin 전송 로직
 */
@Profile("admin")
@RestController
@RequestMapping("/internal/v1/log-features")
@RequiredArgsConstructor
public class InternalLogFeatureController {
    private final HandleLogFeatureUseCase useCase;

    @PostMapping
    public ResponseEntity<Void> receive (@RequestBody @Valid LogFeatureWebhookRequest request){
        useCase.execute(request);

        return ResponseEntity.accepted().build();
    }

}

POST /internal/v1/log-features
{
  "eventType": "click_compare",
  "memberId": 10001,
  "timeStamp": "2026-03-27T10:30:00Z"
}

@Service
@RequiredArgsConstructor
@Profile("admin")
public class HandleLogFeatureUseCase {

    private final CalculateLogChurnScoreService calculateLogChurnScoreService;

    /**
     * 실시간 로그 처리.
     *
     * 1. feature_snapshot_store memberId 조회
     * 2. member_action_feature 없으면 생성
     * 3. member_action_feature 요금제 비교 이력/위약금 확인 이력 UPDATE
     * 4. feature_snapshot_store:
     *                            feature_type = 'MEMBER_ACTION_FEATURE'
     *                            feature_score 계산(계산 오케스트레이션 계층 사용)
     */
    @Transactional
    public void execute(LogFeatureWebhookRequest request) {

        calculateLogChurnScoreService.calculateAndStore(
                request.memberId(),
                LocalDate.from(request.timeStamp()),
                List.of(new LogFeatureEvent(
                        resolveEventId(request),
                        request.timeStamp(),
                        "click",
                        request.eventType(),
                        Map.of()
                ))
        );
    }

    /**
     * 이벤트 식별자 생성.
     */
    private long resolveEventId(LogFeatureWebhookRequest request) {
        return Integer.toUnsignedLong((request.memberId() + "|" + request.eventType() + "|" + request.timeStamp()).hashCode());
    }

}

package site.holliverse.admin.application.usecase;

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;
import site.holliverse.admin.domain.model.churn.ChurnEvaluationResult;
import site.holliverse.admin.domain.model.churn.ChurnFeatureSet;
import site.holliverse.admin.domain.model.churn.ChurnFeatureType;
import site.holliverse.admin.domain.model.churn.ChurnScoreCalculationResult;
import site.holliverse.admin.domain.model.churn.ChurnSignalType;
import site.holliverse.admin.domain.model.churn.feature.MemberActionFeature;
import site.holliverse.admin.domain.policy.churn.ChurnScorePolicy;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * 로그 이탈 계산 서비스.
 */
@Service
@Profile("admin")
@RequiredArgsConstructor
public class CalculateLogChurnScoreService {

    private final ChurnScorePolicy churnScorePolicy;
    private final ChurnRiskReasonFactory churnRiskReasonFactory;
    private final ChurnSnapshotStoreService churnSnapshotStoreService;
    private final MemberActionFeatureSnapshotService memberActionFeatureSnapshotService;

    /**
     * 로그 스냅샷 계산.
     */
    public ChurnEvaluationResult calculateAndStore(
            Long memberId,
            LocalDate baseDate,
            List<LogFeatureEvent> events
    ) {
        // 스냅샷 준비
        MemberActionFeatureSnapshotService.SnapshotContext snapshotContext =
                memberActionFeatureSnapshotService.prepare(memberId, events);

        // feature 조립
        ChurnFeatureSet featureSet = new ChurnFeatureSet(Map.of(
                ChurnFeatureType.MEMBER_ACTION,
                snapshotContext.feature()
        ));

        // 점수 계산
        ChurnScoreCalculationResult scoreResult = churnScorePolicy.calculateDetails(featureSet);

        // feature 스냅샷 저장
        memberActionFeatureSnapshotService.sync(snapshotContext, scoreResult);

        // 위험 사유 조립
        List<ChurnRiskReason> riskReasons = buildLogRiskReasons(events, snapshotContext.feature(), scoreResult);

        // 스냅샷 저장
        return churnSnapshotStoreService.store(memberId, baseDate, ChurnRiskReason.Feature.LOG, riskReasons);
    }

    /**
     * 로그 사유 조립.
     */
    private List<ChurnRiskReason> buildLogRiskReasons(
            List<LogFeatureEvent> events,
            MemberActionFeature feature,
            ChurnScoreCalculationResult scoreResult
    ) {
		...
    }

    /**
     * 로그 사유.
     */
    private Optional<ChurnRiskReason> buildLogReason(
            List<LogFeatureEvent> events,
            int totalCount,
            ChurnScoreCalculationResult scoreResult,
            ChurnRiskReason.ReasonCode reasonCode,
            ChurnSignalType signalType
    ) {
		...
    }

    /**
     * 이벤트 필터.
     */
    private List<LogFeatureEvent> filter(List<LogFeatureEvent> events, UserActionFeatureEventName eventName) {
        ...
    }

    /**
     * 이벤트 근거.
     */
    private List<ChurnRiskReason.LogEventItem> toLogItems(List<LogFeatureEvent> events) {
        ...
    }
}

/**
 * 계약 기반 feature 점수 계산.
 */
@Profile("admin")
@Component
@RequiredArgsConstructor
public class ContractFeatureScorer implements ChurnFeatureScorer {

    private final ChurnScoringProperties churnScoringProperties;
    private final ChurnScoreBandResolver churnScoreBandResolver;

    @Override
    public ChurnFeatureType supports() {
        return ChurnFeatureType.CONTRACT;
    }

    @Override
    public List<ChurnFeatureContribution> contribute(ChurnFeature feature) {
        ContractFeature contractFeature = (ContractFeature) feature;
        int remainingWeeksScore = churnScoreBandResolver.resolveIntScore(
                churnScoringProperties.getRules().getContract().getRemainingWeeks(),
                contractFeature.contractRemainingWeeks()
        );
        int tenureWeeksScore = churnScoreBandResolver.resolveIntScore(
                churnScoringProperties.getRules().getContract().getTenureWeeks(),
                contractFeature.tenureWeeks()
        );

        return List.of(
                new ChurnFeatureContribution(
                        ChurnSignalType.CONTRACT_REMAINING_WEEKS,
                        String.valueOf(contractFeature.contractRemainingWeeks()),
                        remainingWeeksScore
                ),
                new ChurnFeatureContribution(
                        ChurnSignalType.TENURE_WEEKS,
                        String.valueOf(contractFeature.tenureWeeks()),
                        tenureWeeksScore
                )
        );
    }
}

/**
 * 사용량 기반 feature 점수 계산.
 */
@Profile("admin")
@Component
@RequiredArgsConstructor
public class UsageFeatureScorer implements ChurnFeatureScorer {

    private final ChurnScoringProperties churnScoringProperties;
    private final ChurnScoreBandResolver churnScoreBandResolver;

    @Override
    public ChurnFeatureType supports() {
        return ChurnFeatureType.USAGE;
    }

    @Override
    public List<ChurnFeatureContribution> contribute(ChurnFeature feature) {
        UsageFeature usageFeature = (UsageFeature) feature;
        int usageScore = churnScoreBandResolver.resolveIntScore(
                churnScoringProperties.getRules().getUsage().getAllowanceUsageRatePct(),
                usageFeature.allowanceUsageRatePct()
        );

        return List.of(
                new ChurnFeatureContribution(
                        ChurnSignalType.ALLOWANCE_USAGE_RATE_PCT,
                        String.valueOf(usageFeature.allowanceUsageRatePct()),
                        usageScore
                )
        );
    }
}

return new FeatureScores(
        toShortScore(latestScores.get(FeatureType.CONTRACT_FEATURE)),
        toShortScore(latestScores.get(FeatureType.USAGE_FEATURE)),
        toShortScore(latestScores.get(FeatureType.DISSATISFACTION_FEATURE)),
        toShortScore(latestScores.get(FeatureType.MEMBER_ACTION_FEATURE))
);

@Service
@Profile("admin")
@RequiredArgsConstructor
public class ChurnSnapshotStoreService {
  
    private static final Field<Long> CHURN_REVISION_ID = 
    		DSL.field(DSL.name("revision_id"), Long.class);
    private static final Field<java.time.OffsetDateTime> CHURN_UPDATED_AT =
            DSL.field(DSL.name("updated_at"), java.time.OffsetDateTime.class);
    private static final Field<Long> NEXT_CHURN_REVISION_ID =
            DSL.field("nextval('churn_score_revision_seq')", Long.class);

    private final DSLContext dsl;
    private final ObjectMapper objectMapper;
    private final ChurnRiskGradePolicy churnRiskGradePolicy;

    /**
     * 스냅샷 저장.
     */
    @Transactional
    public ChurnEvaluationResult store(
            Long memberId,
            LocalDate baseDate,
            ChurnRiskReason.Feature updatedFeature,
            List<ChurnRiskReason> riskReasons
    ) {
        // 상세 점수
        FeatureScores featureScores = readLatestFeatureScores(memberId);

        // 총점 계산
        ChurnScore churnScore = ChurnScore.fromRaw(featureScores.totalScore());
        int totalScore = churnScore.value();

        // 등급 계산
        ChurnRiskGrade riskGrade = churnRiskGradePolicy.classify(totalScore);

        // 위험 사유 직렬화
        JSONB riskReasonsJson = JSONB.valueOf(writeRiskReasons(mergeRiskReasons(
                memberId,
                baseDate,
                updatedFeature,
                riskReasons
        )));

        // 부모 업서트
        Long snapshotId = dsl.insertInto(CHURN_SCORE_SNAPSHOT)
                .set(CHURN_SCORE_SNAPSHOT.MEMBER_ID, memberId)
                .set(CHURN_SCORE_SNAPSHOT.CHURN_SCORE, totalScore)
                .set(CHURN_SCORE_SNAPSHOT.RISK_LEVEL, riskGrade.name())
                .set(CHURN_SCORE_SNAPSHOT.RISK_REASONS, riskReasonsJson)
                .set(CHURN_SCORE_SNAPSHOT.BASE_DATE, baseDate)
                .set(CHURN_REVISION_ID, NEXT_CHURN_REVISION_ID)
                .set(CHURN_UPDATED_AT, DSL.currentOffsetDateTime())
                .onConflict(CHURN_SCORE_SNAPSHOT.MEMBER_ID, CHURN_SCORE_SNAPSHOT.BASE_DATE)
                .doUpdate()
                .set(CHURN_SCORE_SNAPSHOT.CHURN_SCORE, totalScore)
                .set(CHURN_SCORE_SNAPSHOT.RISK_LEVEL, riskGrade.name())
                .set(CHURN_SCORE_SNAPSHOT.RISK_REASONS, riskReasonsJson)
                .set(CHURN_REVISION_ID, NEXT_CHURN_REVISION_ID)
                .set(CHURN_UPDATED_AT, DSL.currentOffsetDateTime())
                .returning(CHURN_SCORE_SNAPSHOT.SNAPSHOT_ID)
                .fetchOne(CHURN_SCORE_SNAPSHOT.SNAPSHOT_ID);

        // 자식 업서트
        dsl.insertInto(CHURN_FEATURE_SCORE)
                .set(CHURN_FEATURE_SCORE.SNAPSHOT_ID, snapshotId)
                .set(CHURN_FEATURE_SCORE.CHURN_BASE_SCORE, featureScores.baseScore())
                .set(CHURN_FEATURE_SCORE.CHURN_USAGE_SCORE, featureScores.usageScore())
                .set(CHURN_FEATURE_SCORE.CHURN_COUNSEL_SCORE, featureScores.counselScore())
                .set(CHURN_FEATURE_SCORE.CHURN_LOG_SCORE, featureScores.logScore())
                .onConflict(CHURN_FEATURE_SCORE.SNAPSHOT_ID)
                .doUpdate()
                .set(CHURN_FEATURE_SCORE.CHURN_BASE_SCORE, featureScores.baseScore())
                .set(CHURN_FEATURE_SCORE.CHURN_USAGE_SCORE, featureScores.usageScore())
                .set(CHURN_FEATURE_SCORE.CHURN_COUNSEL_SCORE, featureScores.counselScore())
                .set(CHURN_FEATURE_SCORE.CHURN_LOG_SCORE, featureScores.logScore())
                .execute();

        return new ChurnEvaluationResult(
                new ChurnScoreCalculationResult(churnScore, List.of()),
                riskGrade
        );
    }

    /**
     * 점수 변환.
     */
    private Short toShortScore(Integer featureScore) {
        return featureScore == null ? 0 : featureScore.shortValue();
    }

    /**
     * 점수 묶음.
     */
    private record FeatureScores(
            Short baseScore,
            Short usageScore,
            Short counselScore,
            Short logScore
    ) {
        /**
         * 총점 합계.
         */
        private int totalScore() {
            return score(baseScore) + score(usageScore) + score(counselScore) + score(logScore);
        }

        /**
         * 점수 계산.
         */
        private int score(Short value) {
            return value == null ? 0 : value;
        }
    }
}