From 96e045c4e1d73ce3fd2f0f66864d419d466b0492 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 17:29:27 +0330 Subject: [PATCH] docs: approve analytics presentation defaults --- docs/ANALYTICS-SPEC.md | 12 +++++++----- docs/METRIC-CATALOGUE.md | 11 ++++++++++- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/ANALYTICS-SPEC.md b/docs/ANALYTICS-SPEC.md index 92dd665..8753cf0 100644 --- a/docs/ANALYTICS-SPEC.md +++ b/docs/ANALYTICS-SPEC.md @@ -55,11 +55,12 @@ Every section uses a versioned typed contract and has independent `queued`, `cal ## Metric and period contract -- `METRIC-CATALOGUE.md` version `0.3.0` is canonical for formulas, units, grains, missing-data behavior, and peer direction. +- `METRIC-CATALOGUE.md` version `0.4.0` is canonical for formulas, units, grains, missing-data behavior, and peer direction. - `Paid` and `Verified` both mean bank payment succeeded; only `Verified` is finalized. Never label `Paid` as failure. - Amount and fee calculations count each eligible payment session once. Attempt rows cannot multiply session values. - Rates are calculated from summed numerator and denominator components for the selected period, never averaged from daily percentages. - Timing percentiles exclude null values and expose sample size and non-null coverage; missing time never becomes zero. +- `NoAttempt` markers create zero-attempt sessions and never count as attempts or retries. `InBank` is an observed attempt stage, not proof of rejection. - Every result states the exact Tehran-local half-open period, Jalali label, unit, sample/denominator, source revision, metric-definition version, and calculation timestamp. - Approved period types are one Tehran-local day, one Saturday–Friday week, one Jalali month, or one Persian season. Holiday/event dimensions do not exist in the MVP contract. @@ -127,6 +128,7 @@ Every section uses a versioned typed contract and has independent `queued`, `cal - Timeouts, transient retry limits/backoff, failed-section isolation, manual retry, rate limits, heartbeat, replay, and snapshot fallback behave as specified. - Peer results exclude the active merchant, use equal merchant weighting, obey both suppression thresholds, and never expose individual peers. - Tenant-bound drill-downs reconcile to aggregates and cannot expose another merchant through parameter manipulation. +- Read-only drill-downs cover unverified-paid, failed, and retried sessions. Failed-session filters may distinguish zero-attempt and reached-bank stages without exposing payer tokens or claiming undocumented causes. - No raw payer token, credential, cross-tenant row, or AvalAI secret enters results, logs, cache payloads, or browser data. ## Boundaries @@ -143,11 +145,11 @@ Every section uses a versioned typed contract and has independent `queued`, `cal - Peer comparison uses same-category merchant-weighted medians and direction-aware percentiles with the approved suppression threshold. - Payment lifecycle, retry, timing, and real-fee definitions follow `METRIC-CATALOGUE.md` and ADR 0013. - Asynq `v0.26.0` is pinned and acknowledged as pre-1.0; jobs have bounded concurrency, timeouts, rate limits, and exponential-backoff retries. +- Default first view is the latest complete Jalali month containing source data, avoiding an empty current month in the static demo. +- Compare with the immediately previous equivalent complete period. If it is empty or unavailable, return an explicit unavailable comparison rather than silently substituting another baseline. +- Overview priority is bank-paid amount, bank-paid session count, payment success rate, then verification completion. Retry, timing, and fee analysis follow below. +- MVP read-only drill-downs cover unverified-paid, failed, and retried sessions; payer tokens and peer-level rows are excluded. ## Open product decisions -- Default reporting period on first dashboard access, especially when the current period has no source data -- Default previous-period comparison behavior when an equivalent baseline is empty or incomplete -- Exact overview KPI order and which deterministic insight appears first -- Which tenant-scoped drill-down tables are MVP-visible versus definition-only - Deterministic threshold/severity rules for surfacing actionable findings diff --git a/docs/METRIC-CATALOGUE.md b/docs/METRIC-CATALOGUE.md index e5b67ed..6898f7f 100644 --- a/docs/METRIC-CATALOGUE.md +++ b/docs/METRIC-CATALOGUE.md @@ -1,7 +1,7 @@ # Analytics Metric Catalogue - Status: Draft — listed definitions approved -- Version: 0.3.0 +- Version: 0.4.0 - Last updated: 2026-08-20 Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version. @@ -61,6 +61,14 @@ Every merchant-facing number identifies its grain, formula, source fields, filte - Grain/unit: distinct sessions - Traceability: ordered merchant-scoped attempt history; never depend on CSV row order +## Payment-stage diagnostics + +- `no_attempt_sessions`: count sessions with zero normalized payment attempts. During challenge bootstrap this corresponds to the source marker `try_seq = 0 AND try_status = 'NoAttempt'`; the marker itself is not an attempt. +- `reached_bank_sessions`: count distinct sessions containing at least one attempt with `try_status IN ('InBank', 'Paid', 'Verified', 'Reversed')`. +- `in_bank_without_result_sessions`: count sessions whose latest positive-sequence attempt is `InBank` and which have no later `Paid`, `Verified`, `Failed`, or `Reversed` attempt. +- `failed_sessions`: count sessions with final `session_status = 'Failed'`; drill-down may distinguish zero-attempt, reached-bank, and other observable stages without inventing undocumented failure causes. +- Grain/unit: distinct payment sessions; attempt-stage counts must deduplicate by session when presented as sessions. + ## Processing time - Report median (p50) and p95 separately for `init_time_ms` and `verify_time_ms` @@ -83,6 +91,7 @@ Every merchant-facing number identifies its grain, formula, source fields, filte - Zero, undefined, missing, suppressed peer value, and calculation failure remain distinct states. - `Paid` and `Verified` are both bank-payment successes, but only `Verified` is finalized. - `Reversed` is not in the success numerator; display it separately when non-zero. +- `NoAttempt` is a source session marker, not a failed payment attempt. `InBank` means the user reached a bank gateway but no later outcome was recorded for that attempt; do not call it a bank rejection. ## Peer comparison