From e2834a7a52d85df35e82f78ef0dd591f298f7f82 Mon Sep 17 00:00:00 2001
From: Codex <codex@elcsa.local>
Date: Sun, 5 Jul 2026 16:37:23 +0300
Subject: [PATCH] Document risk frontend requirements

---
 docs/frontend-risk-scoring-requirements.md | 127 +++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 docs/frontend-risk-scoring-requirements.md

diff --git a/docs/frontend-risk-scoring-requirements.md b/docs/frontend-risk-scoring-requirements.md
new file mode 100644
index 0000000..6684da2
--- /dev/null
+++ b/docs/frontend-risk-scoring-requirements.md
@@ -0,0 +1,127 @@
+# Frontend Requirements: Risk, Audit, Funnel
+
+## Scope
+
+Frontend code is not changed in this backend release. The admin frontend should add read-only screens for individual-client risk scoring, security audit events, and the product funnel.
+
+Legal-entity B2B flows are still manual and must not display automatic risk scoring decisions.
+
+## User Payment Gate
+
+Individual users cannot create payment orders until KYC is completed.
+
+Expected client behavior:
+
+- If the payment API returns `403` with `KYC verification is required before creating payment orders`, show a blocking state.
+- Primary action: open or continue KYC.
+- Do not show the QR/payment step.
+- Do not retry order creation automatically.
+
+Suggested copy:
+
+- Title: `Для оплаты нужно пройти KYC`
+- Body: `После подтверждения личности платежи станут доступны.`
+- Button: `Пройти KYC`
+
+## Admin Navigation
+
+Add two admin sections:
+
+- `Risk`
+- `Audit`
+
+Add one analytics section:
+
+- `Funnel`
+
+## Risk Screen
+
+Backend endpoints:
+
+- `GET /v1/risk/summary`
+- `GET /v1/risk/assessments?limit=50&offset=0&decision=&user_id=&order_id=`
+
+Summary cards:
+
+- Total assessments
+- Allowed
+- Manual review
+- Rejected
+- Average score
+- High risk
+
+Assessment table columns:
+
+- Created at
+- User ID
+- Order ID
+- Score
+- Decision
+- Reasons
+
+Filters:
+
+- Decision: `allow`, `manual_review`, `reject`
+- User ID
+- Order ID
+
+Decision badges:
+
+- `allow`: green
+- `manual_review`: yellow
+- `reject`: red
+
+## Audit Screen
+
+Backend endpoint:
+
+- `GET /v1/audit/events?limit=50&offset=0&severity=&action=&entity_type=`
+
+Table columns:
+
+- Created at
+- Severity
+- Action
+- Actor type
+- Actor ID
+- Entity type
+- Entity ID
+- Metadata
+
+Filters:
+
+- Severity
+- Action
+- Entity type
+
+Use collapsible JSON rendering for `metadata`.
+
+## Funnel Screen
+
+Backend endpoint:
+
+- `GET /v1/analytics/funnel`
+
+Display the funnel as ordered steps:
+
+1. Registrations
+2. KYC started
+3. KYC completed
+4. First payment
+5. Successful operations
+
+For each step after the first, show conversion from the previous step and conversion from registrations.
+
+## Grafana Links
+
+Expose optional links from the admin UI:
+
+- `https://corp.grafana.elcsa.ru/d/elcsa-audit-security/infrastructure-audit-and-security`
+- `https://corp.grafana.elcsa.ru/d/elcsa-product-funnel/product-funnel`
+
+## Notes
+
+- Do not show raw internal risk rule weights to end users.
+- User-facing apps should show human states such as `Нужна проверка`, not numeric scores.
+- Admin screens may show score, decision, and reasons.
+- Legal entities should not use automatic risk scoring until KYB automation is added.