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

docs(analytics): approve actionable insight thresholds

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 17:40:07 +03:30
parent 96e045c4e1
commit 03c26cc21a
1 changed files with 12 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/ANALYTICS-SPEC.md
View File

@@ -1,6 +1,6 @@
# Analytics Engine Capability Spec
- Status: Draft — not approved for implementation
- Status: Approved specification — implementation not yet authorized
- Capability: Analytics engine
- Depends on: Approved Data Foundation specification
- Last updated: 2026-08-20
@@ -109,6 +109,14 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
- Section publication is atomic; partial/failed calculations never overwrite a valid ready cache entry.
- Database, Redis, queue, timeout, and authorization errors are distinguishable internally while merchant-facing errors remain safe and actionable.
## Actionable insight threshold
- A deterministic actionable insight is eligible only when its comparison contains at least 100 relevant payment sessions.
- Rate insights require an absolute change of at least 3 percentage points. Amount and count insights require an absolute relative change of at least 20 percent.
- The threshold is a display eligibility rule, not a change to the underlying metric. Exact metrics and comparisons remain available even when no insight card is emitted.
- A zero, missing, or undefined baseline cannot produce a relative-change insight. Return the metric and an explicit unavailable comparison instead of dividing by zero or inventing a trend.
- Meeting a threshold does not prove causation. Insight language describes the observed change and a possible merchant action without claiming why it happened.
## Observability
- Measure section queue delay, calculation duration, query duration, cache hit/miss, retry count, failure class, SSE delivery/reconnect, and suppression rate.
@@ -149,7 +157,8 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
- 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.
- Actionable insight cards require at least 100 relevant sessions and either a 3-percentage-point rate change or a 20-percent amount/count change. Below-threshold comparisons remain visible as metrics but do not generate an action claim.
## Open product decisions
## Open product decisions before implementation planning
- Deterministic threshold/severity rules for surfacing actionable findings
- None. Any new or changed metric, period, cohort, threshold, or cross-service contract requires a specification amendment before implementation.