[DABOM-459] family_quota 변경, 레디스 suffix 적용

[k0081915]

🍀 이슈 & 티켓 넘버

• closed: [DABOM-459] family_quota 변경, 레디스 suffix 적용 #53
• jira: DABOM-459

---

🎯 목적

• family 테이블에 섞여 있던 월별 가족 사용량 집계 책임을 family_quota로 분리
• processor-usage의 family Redis 키를 모두 {yyyyMM} suffix 기반으로 통일해 월경계 정합성을 높임
• usage sync, warmup, Lua, persist 경로가 동일한 eventMonth를 기준으로 동작하도록 맞춤

📝 변경 사항

• Family 엔티티에서 totalQuotaBytes, usedBytes, currentMonth 의존을 제거
• FamilyQuota, FamilyQuotaRepository, FamilyQuotaWriter를 추가하고 허용 이벤트 집계를 family_quota upsert로 전환
• UsagePersistServiceImpl가 허용 이벤트에서 family_quota를 갱신하고 차단 이벤트에서는 기존처럼 customer_quota만 반영하도록 정리
• RedisKeyGenerator, UsageSyncServiceImpl, UsageRedisWarmupHelper, UsageLuaExecutor, usage_update.lua를 월 suffix 키 구조로 변경
• Family Redis warmup이 family + family_quota 조합으로 info, remaining을 시드하도록 수정
• 구형 FamilyCacheRepository, FamilyCacheDto, familyCacheRedisTemplate, FamilyUsageWriter를 제거
• UsageSyncServiceImplTest, UsagePersistServiceImplTest, UsageLuaExecutorTest를 수정하고 FamilyQuotaWriterTest, UsageRedisWarmupHelperTest를 추가

📂 변경 범위

도메인	controller	service	repository	entity	infra	global
usage/family		[x]	[x]	[x]	[x]	[x]

---

🖥️ 주요 코드 설명

public void persistAllowedQuota(
        Long familyId,
        LocalDate currentMonth,
        Long bytesUsed,
        String eventId,
        String originEventId) {
    if (tryUpdateExistingQuota(familyId, currentMonth, bytesUsed, eventId, originEventId)) {
        return;
    }
    createQuotaRow(familyId, currentMonth, bytesUsed, eventId, originEventId);
}

• FamilyQuotaWriter는 현재 월 row가 있으면 update로 끝내고 없으면 최신 family_quota 스냅샷의 totalQuotaBytes를 복사해 새 월 row를 생성한다
• insert race가 발생하면 DataIntegrityViolationException 이후 update를 다시 시도해 복구한다
• UsageSyncServiceImpl는 eventTime에서 계산한 eventMonth를 info, remaining, alert, customer monthly usage 키 전부에 공통으로 사용한다
• UsageRedisWarmupHelper는 현재 월 family_quota가 없으면 최신 스냅샷으로 info와 remaining을 시드해 월초 첫 이벤트를 처리할 수 있게 한다
• usage_update.lua는 alert prefix를 조합하지 않고 family:{fid}:alert:THRESHOLD:{threshold}:{yyyyMM} 완성 키를 직접 받아 같은 달 같은 임계치 알림만 한 번 발행한다

💬 리뷰어에게

• FamilyQuotaWriter의 update -> insert -> retry update 패턴과 월 suffix Redis key contract가 잘 적용됐는지 확인해주시면 됩니다

---

📋 체크리스트

기본

• Merge 대상 브랜치가 올바른가?
• ./gradlew build가 정상적으로 통과하는가?
• Spotless / Checkstyle을 통과하는가? (./gradlew spotlessApply checkstyleMain)
• 전체 변경사항이 500줄을 넘지 않는가?

코드 품질

• 의존성 방향을 준수하는가? (Controller → Service → Repository → Entity)
• Setter 없이 비즈니스 메서드로 상태를 변경하는가?
• @Transactional은 Service에만 선언했는가?

테스트

• 신규 비즈니스 로직에 대한 단위 테스트를 작성했는가?

📌 참고 사항

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 풀 리퀘스트는 가족 할당량 관리 시스템의 아키텍처를 개선하고 Redis 키 관리의 일관성을 강화하는 데 중점을 둡니다. 가족 할당량 데이터를 전용 엔티티로 분리하여 데이터 모델의 명확성을 높이고, 월별 데이터 정합성을 위해 Redis 키에 월별 접미사를 도입함으로써 시스템의 안정성과 확장성을 향상시켰습니다. 또한, 관련 서비스 로직과 캐싱 메커니즘을 업데이트하여 새로운 구조를 지원하도록 변경했습니다.

Highlights

• 가족 할당량 관리 분리: Family 엔티티에서 월별 가족 사용량 집계 책임을 family_quota라는 별도의 엔티티로 분리했습니다. 이를 위해 FamilyQuota, FamilyQuotaRepository, FamilyQuotaWriter를 새로 추가했습니다.
• Redis 키 월별 접미사 적용: processor-usage의 Redis 키들이 월별 정합성을 높이기 위해 {yyyyMM} 접미사를 기반으로 통일되었습니다. RedisKeyGenerator, UsageSyncServiceImpl, UsageRedisWarmupHelper, UsageLuaExecutor, usage_update.lua가 모두 이 새로운 키 구조를 따르도록 변경되었습니다.
• 사용량 지속성 로직 개선: UsagePersistServiceImpl이 허용 이벤트에 대해서는 family_quota를 갱신하고, 차단 이벤트에 대해서는 기존처럼 customer_quota만 반영하도록 로직이 정리되었습니다.
• Redis 웜업 로직 업데이트: Family Redis 웜업 시 info 및 remaining 데이터를 시드할 때 family 엔티티와 family_quota 엔티티의 조합을 사용하도록 수정되었습니다.
• 레거시 코드 제거: 더 이상 사용되지 않는 FamilyCacheRepository, FamilyCacheDto, familyCacheRedisTemplate, FamilyUsageWriter가 제거되어 코드베이스가 간결해졌습니다.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/main/java/com/project/domain/family/entity/Family.java
  • totalQuotaBytes, usedBytes, currentMonth 필드와 관련 메서드를 제거했습니다.
• src/main/java/com/project/domain/family/entity/FamilyQuota.java
  • FamilyQuota 엔티티를 추가했습니다.
• src/main/java/com/project/domain/family/infra/cache/FamilyCacheRepository.java
  • FamilyCacheRepository 파일을 제거했습니다.
• src/main/java/com/project/domain/family/infra/cache/dto/FamilyCacheDto.java
  • FamilyCacheDto 파일을 제거했습니다.
• src/main/java/com/project/domain/family/repository/FamilyQuotaRepository.java
  • FamilyQuotaRepository 인터페이스를 추가했습니다.
• src/main/java/com/project/domain/family/repository/FamilyRepository.java
  • 가족 사용량 업데이트 관련 메서드를 제거했습니다.
• src/main/java/com/project/domain/usage/service/UsagePersistServiceImpl.java
  • FamilyUsageWriter 대신 FamilyQuotaWriter를 사용하도록 변경했습니다.
• src/main/java/com/project/domain/usage/service/UsageSyncServiceImpl.java
  • Redis 키 생성 및 웜업 로직을 월별 접미사 기반으로 업데이트했습니다.
• src/main/java/com/project/domain/usage/service/helper/FamilyQuotaWriter.java
  • FamilyQuotaWriter 클래스를 추가했습니다.
• src/main/java/com/project/domain/usage/service/helper/FamilyUsageWriter.java
  • FamilyUsageWriter 파일을 제거했습니다.
• src/main/java/com/project/domain/usage/service/helper/UsageLuaExecutor.java
  • Lua 스크립트 실행 명령에서 알림 키를 월별 접미사 기반으로 변경했습니다.
• src/main/java/com/project/domain/usage/service/helper/UsageRedisWarmupHelper.java
  • 가족 정보 및 잔여 바이트 캐싱 로직을 FamilyQuota 엔티티와 월별 접미사 기반으로 업데이트했습니다.
• src/main/java/com/project/global/config/RedisConfig.java
  • familyCacheRedisTemplate 빈 정의를 제거했습니다.
• src/main/java/com/project/global/util/RedisKeyGenerator.java
  • 가족 알림, 정보, 잔여 데이터 키 생성 시 월별 접미사를 포함하도록 변경했습니다.
• src/main/resources/lua/usage_update.lua
  • Lua 스크립트 내 Redis 키 정의 및 알림 처리 로직을 월별 접미사 기반으로 업데이트했습니다.
• src/test/java/com/project/domain/usage/service/UsagePersistServiceImplTest.java
  • UsagePersistServiceImpl 테스트에서 FamilyUsageWriter 대신 FamilyQuotaWriter를 사용하도록 수정했습니다.
• src/test/java/com/project/domain/usage/service/UsageSyncServiceImplTest.java
  • UsageSyncServiceImpl 테스트에서 Redis 키 생성 및 웜업 관련 스텁을 월별 접미사 기반으로 업데이트했습니다.
• src/test/java/com/project/domain/usage/service/helper/FamilyQuotaWriterTest.java
  • FamilyQuotaWriter에 대한 단위 테스트를 추가했습니다.
• src/test/java/com/project/domain/usage/service/helper/FamilyUsageWriterTest.java
  • FamilyUsageWriterTest 파일을 제거했습니다.
• src/test/java/com/project/domain/usage/service/helper/UsageLuaExecutorTest.java
  • UsageLuaExecutor 테스트에서 Lua 명령의 키 목록을 월별 접미사 기반으로 업데이트했습니다.
• src/test/java/com/project/domain/usage/service/helper/UsageRedisWarmupHelperTest.java
  • UsageRedisWarmupHelper에 대한 단위 테스트를 추가했습니다.

Activity

• k0081915님이 이 풀 리퀘스트를 생성했습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

안녕하세요. 전반적으로 family 테이블의 사용량 집계 책임을 family_quota 테이블로 성공적으로 분리하고, 관련 Redis 키 구조를 월별 suffix({yyyyMM}) 기반으로 통일한 좋은 리팩토링이라고 생각합니다. 특히 FamilyQuotaWriter에 update-insert-retry 패턴을 적용하여 동시성 문제를 안정적으로 처리한 점이 인상적입니다.

리뷰에서는 주로 프로젝트 스타일 가이드 준수와 코드 가독성 개선에 초점을 맞추었습니다. 몇 가지 제안 사항을 코멘트로 남겼으니 확인 부탁드립니다.

스타일 가이드 요약

리뷰는 다음 저장소 스타일 가이드 규칙을 기반으로 작성되었습니다:

• 예외 처리(규칙 6, 14): RuntimeException이나 IllegalStateException 대신 ApplicationException과 ErrorCode를 사용해야 합니다.
• Entity(규칙 10): BaseEntity를 상속받는 엔티티의 updatedAt 필드는 JPA Auditing을 통해 자동으로 관리되어야 합니다.

[github-actions]

SonarQube Quality Summary (Community)

✅ Quality Gate PASSED

Branch: fix/DABOM-459
Compared to: default branch

Issues

• 🐞 Bugs: 8
• 🔐 Vulnerabilities: 0
• 📎 Code Smells: 92

Measures

• Coverage: 0%
• Duplication: 0%

🔗 Dashboard: https://sonarqube.swthewhite.store/dashboard?id=dabom-processor-usage&branch=fix/DABOM-459

Generated automatically by GitHub Actions.

[github-actions]

SonarQube Quality Summary (Community)

✅ Quality Gate PASSED

Branch: fix/DABOM-459
Compared to: default branch

Issues

• 🐞 Bugs: 8
• 🔐 Vulnerabilities: 0
• 📎 Code Smells: 92

Measures

• Coverage: 0%
• Duplication: 0%

🔗 Dashboard: https://sonarqube.swthewhite.store/dashboard?id=dabom-processor-usage&branch=fix/DABOM-459

Generated automatically by GitHub Actions.

[dabom-devops-bot]

👋 PR 리마인드 알림입니다

이 PR이 몇 시간 동안 업데이트되지 않았어요.

• 🙋 PR 작성자: 추가 작업 중이거나 설명이 필요하면 코멘트 남겨주세요
• 👀 리뷰어 / 팀원: 이미 봤다면 LGTM 한 줄도 좋아요!

바쁘실 수 있다는 점 이해합니다 🙏
다만 작은 한 줄이 PR 흐름을 살려줘요 🙂

[ChoiSeungeon]

확인했습니다.
고생하셨습니다.