From a32c3f241d561a20a0d955f4cd8e555611ad1cd3 Mon Sep 17 00:00:00 2001
From: sdarbinyan <sdarbinyan@4pay.ru>
Date: Sun, 26 Jul 2026 15:57:21 +0400
Subject: [PATCH] docs: fill 2 gaps in BACKEND.md against final handoff
 checklist
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reviewed BACKEND.md top to bottom (4775 lines, 10 sections) against
the full backend-handoff checklist (auth, bootstrap, every endpoint,
media, all domains, pagination/filter/sort/search, error contract,
maintenance mode, status codes, versioning, rate limits, CORS,
security, websocket/events, mock-to-api migration).

Confirmed already covered, no action: Authentication (§4, all
sub-items), Bootstrap (§1, full), every domain's CRUD contract (§3.1-
3.20, includes Moderation under 3.17.b), Media (§7), SEO (bootstrap
SeoConfig + per-page seo + sitemap tracked as remaining work), Error
Model (§6), Maintenance Mode (§10), Migration guide (§8).

Added (genuine gaps, not covered anywhere in the doc):
- §2.10 API path versioning - no endpoint has a version segment/header
  anywhere; only BootstrapConfig.schemaVersion exists and that only
  versions the bootstrap payload shape, not the API surface. Flagged
  as a backend/infra decision with zero frontend impact either way.
- §2.11 Real-time/WebSocket - confirmed no WebSocket/SSE exists
  anywhere in the frontend; consolidated the 5 places that look "live"
  (QR/Telegram login, payment status, session validity, maintenance
  notice, admin monitoring) into one table, all client-side polling.
  Flagged push-vs-poll as a backend decision, most relevant to payment
  latency and the session-revocation propagation delay.
- Renumbered the section's "Consolidated requires-backend-decision"
  list 2.9 -> 2.12 (moved after the two new subsections, no other
  content changed) and added both new items to it. No other §2.x
  cross-references existed elsewhere in the doc to update.

No duplication found requiring merge; docs/archive/BACKEND_API.md
cross-references are intentional (superseded-but-kept historical
detail, per the doc's own stated design), not obsolete/duplicate
content.
---
 docs/BACKEND.md | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/docs/BACKEND.md b/docs/BACKEND.md
index 7bf96fd..336b7ca 100644
--- a/docs/BACKEND.md
+++ b/docs/BACKEND.md
@@ -974,7 +974,48 @@ Example response:
 ]
 ```
 
-### 2.9 Consolidated "Requires backend decision" items (this section)
+### 2.10 API path versioning
+
+No endpoint the frontend calls includes a version segment (no `/v1/`, no
+`Accept-Version`/`Api-Version` header). Every domain path in this document is
+relative to `{base}` = `ApiConfigService.getBaseUrl()` (tenant-resolved; see
+§1.9) with no version component anywhere in that resolution chain
+(`tenant.apiBaseUrl` from bootstrap, or `/api` on localhost — §1.3, §1.9).
+
+The only version field in the entire contract is `BootstrapConfig.schemaVersion`
+(§1.4), which versions the **bootstrap payload shape**, not the API surface —
+it's checked for presence only, not semantically enforced, and doesn't apply to
+any other endpoint.
+
+> **Requires backend decision:** whether the API surface gets a versioning
+> scheme at all (URL path segment, header, or none/evergreen-only), and if so
+> whether it's introduced from day one or deferred until the first breaking
+> change. No frontend code currently assumes or constructs a version segment,
+> so either choice is a pure backend/infra decision with no frontend rework
+> unless breaking changes are introduced later.
+
+### 2.11 Real-time / WebSocket
+
+No WebSocket, Server-Sent Events, or other push channel exists anywhere in the
+frontend. Every case that looks "live" is client-side polling on a plain
+`setInterval`/RxJS `interval`, hitting a normal request/response endpoint:
+
+| What | Mechanism | Where |
+|---|---|---|
+| QR/Telegram login session state | Poll `GET` session-status endpoint until `active`/expired (§4 Mechanism A, `QrLoginEngine`) | Auth |
+| Cart QR/card payment status | Poll cart payment-status endpoint, bounded by response `qrTTL` (min 60s) | §3.3 Orders / payments |
+| Session/token validity | Re-checked on next request or next refresh-interval tick — no push invalidation. A backend-side revocation isn't observed by an already-open session until the refresh interval elapses (§4.8 Session invalidation) | Auth |
+| Maintenance-notice banner (proposed) | Would be a polling `GET /maintenance-notice` endpoint, not a push channel (§10.7) | Maintenance mode |
+| Admin monitoring queue/webhook status (proposed, mock-only today) | Would be plain `GET` on facade refresh, no proposal anywhere for push (§3.19) | Monitoring |
+
+> **Requires backend decision:** whether any of the above should become
+> push-based (WebSocket/SSE) instead of polling — most relevant to payment
+> status (customer-facing latency) and session revocation (security: a
+> revoked admin session stays technically usable client-side for up to one
+> refresh interval, §4.8). No frontend code exists for a push channel today,
+> so adding one is net-new frontend work, not a swap.
+
+### 2.12 Consolidated "Requires backend decision" items (this section)
 
 - Bootstrap: `X-Language`/`Accept-Language` handling on `GET /bootstrap` (§1.1).
 - Bootstrap: whether `schemaVersion` is enforced vs presence-only (§1.4).
@@ -992,6 +1033,9 @@ Example response:
   sentinel (§2.4).
 - Framework: server-side autocomplete/trending search endpoints + min-query
   contract (§2.5).
+- Framework: API path/header versioning scheme, if any — none exists today (§2.10).
+- Framework: whether payment-status polling and session revocation should
+  become push-based (WebSocket/SSE) instead of polling (§2.11).
 
 ---