Expand dashboard analytics and document production implementation

mockups/METRICS.md

@@ -43,9 +43,27 @@ Each sale row records its product, price **at sale time**, quantity, receipt ide
 
 ## Gamepass ownership and activity stages
 
+The Summaries page reuses the two daily report snapshots. Its combined overview includes CCU, active players/DAU, rolling MAU, new/returning period actives, sessions/playtime, first-session retention, mature D1/D7/D30 returns, revenue/payers/conversion, ARPPU/ARPDAU, leading products, prompt-source conversion, and the largest observed ordered-stage loss. Rolling MAU covers the 30 complete days ending on the report's final day. D7/D30 use acquisition cohorts whose exact observation day falls within the report window, avoiding immature cohorts. Product totals, payer concentration, prompt timing, and activity funnels are independently scoped to the same game and complete UTC window. Suggestions are mockup editorial text; observed differences are not causal claims. Older cached prototype payloads are upgraded once to include the added summaries, then remain stable for that report date.
+
+Game Health reports use yesterday `[UTC today-1, today)` and the last seven complete days `[today-7, today)`, compared with the immediately preceding equal-length window. Yesterday also compares with the same weekday seven days earlier. The latest day in a report is always complete; chart date selection does not change these windows.
+
+Reports count unique period-active players and mean daily DAU separately. New/returning period actives are split by whether first seen falls in the window or earlier. Sessions and average completed-session duration use starts in the window; known playtime is split across midnight and clipped to the window. CCU averages/peaks use only known hourly reports, with coverage notes; a zero baseline displays "up from zero" rather than an infinite growth percentage. First-session five-minute retention excludes unknown first-session ends. Report D1 covers acquisition cohorts whose complete next-day observation falls inside the report window, so yesterday's new users are not incorrectly counted as failed returns. Revenue uses historical recorded prices; missing payer attribution makes payer conversion N/A.
+
+`daily_health_reports` stores two snapshots per game/report date. A background task checks for missing reports every minute and builds new snapshots after UTC rollover, with catch-up on startup/first request. Existing daily snapshots remain unchanged. The prototype uses measured, deterministic sample narratives, not an external AI service.
+
+Prompt `trigger_source` is explicitly reported as `game`, `player`, or `unknown`. Game-induced means an automatic offer or game trigger; player-induced means an explicit purchase action such as clicking a buy button. These identify the cause of the purchase prompt, not merely whether the shop was opened. Missing source remains unknown in storage and is listed in the settings log. The source filter affects prompt totals, product rows, and product trend lines; the source comparison table and graph always show both known sources within the selected game/date window. Conversion and timing formulas are unchanged. Differences are observational, not evidence that a source caused higher conversion. The bundled data uses synthetic source labels with differing response patterns; no real source is inferred from whether a purchase occurred.
+
+Graphs with more than two available series expose searchable line selection and All/None controls. Two-line and single-line charts are unchanged. Selecting fewer lines does not remove the picker. Empty selection remains reversible, hidden lines do not affect the axis or tooltip, and original colors stay fixed.
+
+Player ownership lists use explicit `purchased_at`, sorted oldest first with unknown dates last. `checked_at` is not treated as a purchase date. The bundled synthetic observations include generated purchase dates; real missing dates remain N/A. Product inventory counts all reported units for the player and lists lifetime spending separately from individual receipts.
+
+Product prompts are stored in `interaction_events` (`kind=product_prompt`) rather than activity runs. Each prompt records its shown time, resolved time when available, product, bought/closed outcome, and optional player/session/receipt. Buy rate is bought prompts / resolved bought-or-closed prompts with a known game/player source. Unresolved outcomes and unknown sources are excluded from regular prompt analytics. Average buy/close time includes only prompts with that reported outcome and a known end. Unresolved diagnostics are listed in Project settings; empty denominators or unavailable durations show N/A. Daily conversion uses the same definition per product. The generic interaction dataset supports other small timed events through `kind` and `properties`.
+
+The Day 1–7 retention curve uses only cohorts within the selected period with all seven observation days complete. All seven points share the same denominator. The existing cohort grid and acquisition-date trend remain available; exact-day curves can fluctuate rather than decline perfectly at every point.
+
 The Monetization page has Revenue and Gamepasses tabs. Gamepass ownership uses explicit per-player true/false observations, independent of purchase reports. The all-player percentage divides owners by all tracked players in this game. The paying-player percentage divides paying owners by lifetime players with a recorded positive-price purchase. An incomplete set of ownership checks displays N/A for the affected percentage; reporting coverage is displayed separately. No paying players means N/A for the paying-player percentage. These ownership percentages are current snapshots and do not use the selected revenue date range.
 
-Activity stages use ordered `stage_progress` event observations. Stage reach is the percentage of all activity starts reaching that stage in sequence. Conversion divides stage reach count by the previous stage count; drop-off is its complement. A later event does not count if a required earlier stage was skipped. Unknown stage observations make subsequent percentages N/A rather than fabricated drop-offs.
+Activity stages use ordered `stage_progress` event observations. Stage reach is the percentage of all activity starts reaching that stage in sequence. Conversion divides stage reach count by the previous stage count; drop-off is its complement. A later event does not count if a required earlier stage was skipped. Unknown stage observations are excluded from stage reach/drop-off denominators and listed in the settings log, rather than becoming fabricated drop-offs.
 
 Events show one daily graph line and one summary row per event name. Global recent-event, recent-session, and recent-sale tables are removed; individual records remain in player info. Game-root metric categories remain stored but have no overview or project-settings table. Session aggregates and charts accept the same player groups as activity analytics.
 
@@ -56,3 +74,9 @@ Player history accepts `value` and optional `value2` and plots them at stored sn
 The Events chart filters lines using a searchable checkbox picker with All/None controls. Selection is stored locally per internal game ID. Hidden series are excluded from hover tooltips and axis scaling, while summary totals remain unchanged.
 
 Whales are the top 20% of players with known positive lifetime recorded Robux spending. Top playtime is the top 20% with known positive completed-session playtime. First-time players were first seen in the last 24 hours. These are sample group definitions, not fixed business rules; the intended product should allow configurable thresholds and periods.
+
+## Data quality presentation
+
+Project settings has a game-scoped diagnostic log at `/api/games/{game_id}/data-quality?page=1&issue=all`. It uses retained source records to show unresolved prompt outcomes/sources, stale session ends (older than six hours), incomplete activity outcomes/stages, null metric reports, missing sale attribution, missing ownership checks, and missing pass purchase dates. Categories filter before counting and 20-row pagination. It is a live issue view, not a separate permanent audit trail; corrected records stop appearing.
+
+Main analytics omit unresolved counters, unknown-source prompt rows, coverage columns, and report warning notes. Prompt ratios use only resolved outcomes with known sources; activity result analytics exclude unknown end/outcome, and stage funnels use observed stage lists only. Missing actual metrics still show N/A, including ownership percentages whose all-player denominator cannot be established. The reports cache is refreshed once for this presentation/calculation revision. Raw records and report evidence remain stored.