ANTOOZA-BACKEND/Application/Abstractions/Paper/IPaperLeaderboardCache.cs

using Application.Abstractions.Data;
using Application.Helpers;

namespace Application.Abstractions.Paper;

/// <summary>리더보드 페이지 1행 — 회원 PK·점수·순위(0-based).</summary>
public sealed record PaperLeaderboardRow(int MemberID, int Score, long Rank);

/// <summary>내 순위 조회 결과 — 순위(0-based)·점수·전체 등재 수.</summary>
public sealed record PaperLeaderboardMyRank(long Rank, int Score, long Total);

/// <summary>
/// 모의투자 리더보드 Redis Sorted Set 캐시 (d4 M3 리더보드 백엔드 구현).
/// (sort, period) 조합별 Sorted Set. 캐시 미스 시 DB 재시드(TTL ~25h) — RedisChatLeaderboard 패턴 복제.
/// return/winrate 는 높을수록 상위, mdd 는 낮을수록 상위.
/// </summary>
public interface IPaperLeaderboardCache
{
    /// <summary>
    /// 지정 (sort, period)의 순위 페이지(offset, count)를 반환. 캐시 미스 시 DB 로 재시드.
    /// 등재 계좌가 없으면 빈 목록.
    /// </summary>
    Task<IReadOnlyList<PaperLeaderboardRow>> GetPageAsync(
        PaperLeaderboardSort sort,
        PaperLeaderboardPeriod period,
        int offset,
        int count,
        IAppDbContext db,
        int minFillsForRank,
        CancellationToken ct = default);

    /// <summary>
    /// 지정 (sort, period)에서 회원의 순위·점수·전체 등재 수. 미등재면 null.
    /// </summary>
    Task<PaperLeaderboardMyRank?> GetMyRankAsync(
        PaperLeaderboardSort sort,
        PaperLeaderboardPeriod period,
        int memberID,
        IAppDbContext db,
        int minFillsForRank,
        CancellationToken ct = default);

    /// <summary>
    /// 전체 (sort, period) 캐시 무효화 — 스냅샷 배치 직후 호출하면 다음 조회가 최신 스냅샷으로 재시드된다 (warm-refresh).
    /// </summary>
    Task InvalidateAllAsync(CancellationToken ct = default);
}