sodalive-backend-spring-boot/docs/20260407_콘텐츠별정산요율추가.md

• 변수명 확정: 엔티티 내부 추가 변수는 AudioContent.settlementRatio: Int?로 사용한다.

  • 이유: AudioContent는 이미 콘텐츠 도메인 엔티티이므로 contentSettlementRatio는 중복 표현에 가깝다.
  • 근거: 이 저장소의 엔티티 필드는 AudioContent.price, LiveRoom.price, CreatorCommunity.price처럼 엔티티 스코프 안에서는 도메인 접두어를 반복하지 않는다.
  • 예외 기준: CreatorSettlementRatio.contentSettlementRatio처럼 하나의 엔티티 안에서 live/content/community 여러 정산 대상을 함께 구분해야 할 때만 content 접두어가 필요하다.
  • DTO/API 정책: 해당 값은 관리자에서만 사용하므로 관리자 요청/응답 DTO와 API 필드명도 예외 없이 settlementRatio로 통일한다.
  • nullable 정책: 기존 데이터와 크리에이터 정산 요율 미등록 케이스를 안전하게 수용하기 위해 초기 도입 시 Int?로 두고, 계산 시 콘텐츠별 요율 -> 크리에이터 기본 요율 -> 70% 기본값 순서로 fallback 하도록 설계한다.

• AudioContent 엔티티에 콘텐츠별 정산 요율 필드를 추가한다.

  • 대상 파일: src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContent.kt
  • 작업 내용: price 인접 위치에 settlementRatio: Int? 필드를 추가하고, 기존 생성자 호출부가 모두 컴파일되도록 생성 경로를 함께 정리한다.

• 관리자 콘텐츠 목록 조회 응답에 콘텐츠별 정산 요율을 노출한다.

  • 대상 파일: src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentRepository.kt, src/main/kotlin/kr/co/vividnext/sodalive/admin/content/GetAdminContentListResponse.kt, src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt
  • 작업 내용:
    • QGetAdminContentListItem(...) QueryProjection에 audioContent.settlementRatio를 추가한다.
    • GetAdminContentListItem에 settlementRatio: Int?를 추가하고, 관리자 목록 응답 필드명도 동일하게 settlementRatio로 맞춘다.
    • AdminContentController.getAudioContentList 응답에 정산 요율이 함께 내려가도록 조회 체인을 맞춘다.

• 관리자 콘텐츠 수정 API에서 콘텐츠별 정산 요율을 수정할 수 있게 한다.

  • 대상 파일: src/main/kotlin/kr/co/vividnext/sodalive/admin/content/UpdateAdminContentRequest.kt, src/main/kotlin/kr/co/vividnext/sodalive/admin/content/AdminContentService.kt
  • 작업 내용:
    • UpdateAdminContentRequest에 settlementRatio: Int?를 추가하고, 관리자 수정 요청 필드명도 동일하게 settlementRatio로 맞춘다.
    • AdminContentService.updateAudioContent에서 요청값이 들어오면 audioContent.settlementRatio를 갱신한다.
    • 숫자 범위 정책은 0~100으로 검증한다.
    • 개별 콘텐츠 정산 요율 삭제는 isSettlementRatioDeleted: true 플래그로만 처리하고, settlementRatio와 동시 전달 시 invalid request 로 처리한다.

• 실제 콘텐츠 정산 계산이 크리에이터 기본 요율이 아니라 콘텐츠별 요율을 우선 사용하도록 변경한다.

  • 대상 파일: src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/AdminCalculateQueryRepository.kt, src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/CreatorAdminCalculateQueryRepository.kt, src/main/kotlin/kr/co/vividnext/sodalive/admin/calculate/GetCalculateContentQueryData.kt
  • 작업 내용:
    • 콘텐츠 판매/누적 판매 집계 쿼리에서 creatorSettlementRatio.contentSettlementRatio 직접 사용 부분을 점검한다.
    • 정산 대상 비율은 audioContent.settlementRatio를 우선 사용하고, 값이 없을 때만 creatorSettlementRatio.contentSettlementRatio를 fallback 하도록 쿼리 또는 계산 DTO를 조정한다.
    • 현재 GetCalculateContentQueryData의 70% 기본값 정책은 마지막 fallback 으로 유지한다.

• 크리에이터 관리자 정산 조회도 동일 기준을 사용하도록 맞춘다.

  • 대상 파일: src/main/kotlin/kr/co/vividnext/sodalive/creator/admin/calculate/CreatorAdminCalculateQueryRepository.kt
  • 작업 내용: 관리자 정산 조회와 동일하게 콘텐츠별 정산 요율 우선 정책을 반영해 관리자/크리에이터 화면 간 계산 기준이 달라지지 않게 한다.

• 기존 데이터 처리 정책을 정리한다.

  • 대상 범위: 운영 DB 스키마/기존 콘텐츠 데이터
  • 작업 내용:
    • 신규 컬럼 추가 시 nullable 로 도입하고, DDL은 docs/20260407_audio_content_settlement_ratio_ddl.sql 기준으로 관리한다.
    • 콘텐츠 등록 시 크리에이터 기본 정산 요율을 복사하지 않고, NULL 상태에서도 계산이 가능하도록 fallback 순서를 유지한다.
    • 운영 정책상 기존 콘텐츠에도 즉시 고정값이 필요하면 별도 SQL 또는 배치 백필 계획을 추가로 작성한다.

• 영향 DTO/Q 클래스/컴파일 산출물을 재생성하고 검증한다.

  • 작업 내용:
    • QueryDSL projection 변경 후 Q 클래스 재생성이 필요한지 확인하고 빌드로 반영한다.
    • 엔티티/관리자 DTO/API/QueryProjection 필드명이 모두 settlementRatio로 일치하는지 확인해 매핑 누락 가능성을 제거한다.

• 검증을 단계별로 수행한다.

  • 작업 내용:
    • AdminContentController.getAudioContentList에서 정산 요율 조회 포함 여부를 확인한다.
    • AdminContentController.modifyAudioContent에서 정산 요율 수정 반영 여부를 확인한다.
    • AdminContentController.modifyAudioContent에서 isSettlementRatioDeleted = true 요청 시 개별 콘텐츠 정산 요율이 삭제되는지 확인한다.
    • 콘텐츠 등록 시 settlementRatio가 nullable 상태로 유지되어도 계산 fallback 이 정상 동작하는지 확인한다.
    • 콘텐츠 정산 조회(AdminCalculateQueryRepository, CreatorAdminCalculateQueryRepository)가 콘텐츠별 요율을 우선 적용하는지 확인한다.
    • 실행 검증은 최소 ./gradlew build, 필요 시 ./gradlew test까지 수행한다.

1차 구현 검증 기록

• 무엇을: AudioContent.settlementRatio nullable 컬럼 추가, 관리자 목록/수정 API 반영, 콘텐츠/누적 정산 쿼리의 콘텐츠별 요율 우선 fallback 반영, 생성 시 기본 요율 복사 제거.
• 왜: 기존 콘텐츠와 미설정 콘텐츠를 NULL로 유지하면서도 관리자에서 개별 요율을 조회/수정하고 정산 시 올바른 fallback 순서를 적용하기 위해.
• 어떻게:
  • ./gradlew build → 성공
  • ./gradlew test → build 과정에 포함되어 성공
  • 관리자/정산 API의 실서버 수동 호출 검증 → 이 로컬 작업 세션에서는 애플리케이션 실행 및 인증 가능한 테스트 데이터가 없어 미실행

2차 수정 검증 기록

• 무엇을: @SpringBootTest 없이 콘텐츠 정산 계산 DTO의 명시 비율 적용과 null -> 70% fallback을 검증하는 순수 단위 테스트를 추가했다.
• 왜: 정산 쿼리 변경만으로는 계산 결과가 코드상에서 충분히 고정되지 않아, 문서에 적힌 계산 규칙을 재현 가능한 테스트로 보장하기 위해.
• 어떻게:
  • ./gradlew test --tests kr.co.vividnext.sodalive.admin.calculate.ContentSettlementCalculationTest → 성공
  • 검증 대상: GetCalculateContentQueryData, GetCumulativeSalesByContentQueryData
  • 검증 시나리오: settlementRatio = 80 적용, settlementRatio = null 시 70% fallback 적용

3차 수정 검증 기록

• 무엇을: 관리자 콘텐츠 수정 API의 개별 콘텐츠 정산 요율 삭제 방식을 명시적 null 대신 isSettlementRatioDeleted 플래그로 전환한다.
• 왜: 부분 업데이트 요청에서 필드 생략과 null 삭제 의미가 섞이지 않도록 API 계약을 명확히 하기 위해.
• 어떻게:
  • ./gradlew test --tests kr.co.vividnext.sodalive.admin.content.AdminContentServiceTest → 성공
  • ./gradlew test --tests kr.co.vividnext.sodalive.admin.calculate.ContentSettlementCalculationTest → 성공
  • ./gradlew build → 성공
  • 검증 시나리오: 유효한 요율 설정, 삭제 플래그 삭제, 값/삭제 플래그 동시 전달 충돌, null 키/삭제 플래그 동시 전달 충돌, 범위 초과 거부, 정산 fallback 회귀 확인