starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: approve analytics presentation defaults

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 17:29:27 +03:30
parent a70fc15517
commit 96e045c4e1
2 changed files with 17 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/ANALYTICS-SPEC.md
View File

@@ -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