daniel-c-harvey
be1a55fd37
Add TotalPlays + UniqueListeners to HomeStatsDto, composed at StatsController from IEventService (no migration). Card reads via existing persistent-state-bridged round-trip.
47 lines
2.7 KiB
C#
47 lines
2.7 KiB
C#
using DeepDrftModels.Enums;
|
|
using NetBlocks.Models;
|
|
|
|
namespace DeepDrftData;
|
|
|
|
/// <summary>
|
|
/// SQL-side anonymous telemetry service (Phase 16). Records play and share events to the append-only
|
|
/// logs and maintains the incremental play-counter rollup. The release dimension on a play is resolved
|
|
/// server-side from the track key (§2.3 / D4) — callers pass only what the client cheaply knows.
|
|
/// Returns NetBlocks <see cref="Result"/> at the boundary; the controller maps that to 202/4xx/5xx.
|
|
/// </summary>
|
|
public interface IEventService
|
|
{
|
|
/// <summary>
|
|
/// Record one play: append a <c>play_event</c> row (release resolved from the track key) and bump
|
|
/// the track's <c>play_counter</c> in the same transaction. A play of an unknown/removed track key
|
|
/// still logs (with a null release and no counter bump) rather than failing.
|
|
/// </summary>
|
|
Task<Result> RecordPlay(string trackEntryKey, PlayBucket bucket, string? anonId = null, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Record one share: append a <c>share_event</c> row. Target and channel come straight from the client.</summary>
|
|
Task<Result> RecordShare(ShareTargetType targetType, string targetKey, ShareChannel channel, string? anonId = null, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Site-wide total play count (Phase 16 §5 — all-time): the sum of every <c>play_counter</c> row's
|
|
/// three bucket columns. Zero until the telemetry migration is applied. The home Plays card's primary
|
|
/// figure; the controller composes it onto <c>HomeStatsDto</c> alongside the track-domain figures.
|
|
/// </summary>
|
|
Task<ResultContainer<long>> GetTotalPlayCount(CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Site-wide distinct-listener count (Phase 16 §3, D3 — all-time): distinct non-null <c>anon_id</c>
|
|
/// values across all play events. Null tokens are excluded (not a known listener). The capability for
|
|
/// wave 16.5's "N listeners" card; nothing surfaces it via API or UI in wave 16.3.
|
|
/// </summary>
|
|
Task<ResultContainer<int>> GetDistinctListenerCount(CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>Distinct listeners who played the given track (by vault entry key). Null tokens excluded.</summary>
|
|
Task<ResultContainer<int>> GetDistinctListenerCountForTrack(string trackEntryKey, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Distinct listeners across the release's tracks (derived, D4) — a listener who played any track in
|
|
/// the release counts once. Null tokens excluded.
|
|
/// </summary>
|
|
Task<ResultContainer<int>> GetDistinctListenerCountForRelease(long releaseId, CancellationToken cancellationToken = default);
|
|
}
|