2149e6435a
Updates FRONTEND-API-SURFACE-COMPLETE.md to cover everything built after it
was first generated - this is the final version for this pass, not a
snapshot mid-way through.
Added, none of which existed in the doc before:
- §18: the 4 marketplace revision endpoints (create draft/validate/
publish/rollback) - built this session, missing from the census entirely.
Flags the same draft/validated/preview/published ambiguity already
documented in the model itself, so backend sees it without having to
read source.
- §19: RoutingContext as an optional field addition on GET
/api/admin/v2/orders/{id} - not a new endpoint, a response-shape ask.
- §20: order pricing-breakdown fields (unitPriceMinor, lineTotalMinor,
priceSnapshotId, discountMinor, fxQuoteId, deliveryMinor) feeding the new
total-formula panel. States plainly that the panel shows nothing rather
than a wrong number while these are absent.
- §21: 8 optional dashboard-metrics fields (GMV, conversion, moderation
queue, etc.) - explicitly labelled a genuine ask, not a confirmed
contract, since no spec exists for this endpoint at all (§15).
- §22: states directly that the frontend's new double-click guard does not
replace backend idempotency enforcement and was never meant to - closes
one UI race, does nothing for a retried request or a duplicate webhook.
Counts updated (47->51 specified, 86->90 total; +3 response-shape asks that
aren't new endpoints). Closing section states the one item genuinely
blocked pending a live backend (F60, the full acceptance-path E2E) so
nobody mistakes "frontend backlog complete" for "nothing left to build."
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Backend Contracts Index — Product Plan v3.1
New here? Start with BACKEND-HANDOFF.md — reading order, current infrastructure state, auth surface, and what a working dev environment still needs.
Want every endpoint in one place? FRONTEND-API-SURFACE-COMPLETE.md — the final handoff doc. Generated directly from source, all 90 endpoints the frontend currently calls plus 3 response-shape additions on existing endpoints, marked Specified / Inferred / Undocumented against the contracts below. Use it to see gaps across all contracts at once; use the individual Phase/Track docs for full entity shapes and invariants.
This directory is the complete set of wire contracts for building the backend behind Product Plan v3.1. Each doc specifies entities, endpoints, and invariants only — never DB schema or service boundaries, which stay backend's own call.
Read order matches build order. Every doc after Phase 1 depends on the ones before it (noted at the top of each). All Sprint 0.1 decisions referenced throughout were answered 2026-08-17 — see PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md Sprint 0.1 for the full record.
Launch-gate phases (P0 — required before production)
| Doc | Covers | Status |
|---|---|---|
| PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md | Money model, FX quote, price snapshot, server-authoritative checkout amount, payment state machine | Ready |
| PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md | Canonical Order/OrderLine/Fulfillment (unified multi-seller), event bus, Notification Center | Ready |
| PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md | Product/Offer split, inventory/reservations, publish-time executability | Ready |
| PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md | Generic external-order connector framework (no fixed marketplace list) | Ready |
Post-launch-gate phases (P1/P2)
| Doc | Covers | Status |
|---|---|---|
| PHASE-5-SELLER-PORTAL-CONTRACT.md | Seller org/user/membership, seller-scoped order/fulfillment views | Ready |
| PHASE-6-CART-CHECKOUT-CONTRACT.md | Server-owned cart, checkout session | Ready |
| PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md | Refunds, reconciliation, settlements | Ready |
| PHASE-8-IDENTITY-MESSAGING-CONTRACT.md | Customer identity, VK ID (built first), OTP, MAX/Telegram bots, Notification Orchestrator | Ready |
| PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md | Marketplace registry, Hostinger DNS automation, publish/revision model | Ready |
| PHASE-10-CONTENT-MODULES-CONTRACT.md | Gorbushka-class mall/directory content entities | Ready, lowest priority |
Cross-cutting tracks
| Doc | Covers | Status |
|---|---|---|
| TRACK-A-ANALYTICS-CONTRACT.md | Event pipeline, funnel, operational/quality metrics, synthetic-traffic separation | Ready — start alongside Phase 1, longest lead time |
| TRACK-S-SECURITY-RBAC-CONTRACT.md | 17 roles/3 scopes, enforcement, audit log, secrets, rate limiting, step-up auth | Ready — gates the launch |
| PARTNER-PROVISIONING-API-CONTRACT.md | Inbound partner API: merchant hierarchy provisioning, idempotency, public-key credentials, payment routing context | Draft — mapping decided, needs Company/Project entities |
What is deliberately not in this directory
- API namespace migration — Sprint 0.1 decision: new endpoints only use
/api/v2/...etc; legacy endpoints (/cart,/orders,/items) are not being migrated as part of this contract set. SeeBACKEND-API-REFERENCE.mdfor the current live surface. - Per-connector adapters (Ozon, Wildberries, etc.) — Sprint 0.1 decision: no fixed list. Phase 4 §8 is the onboarding runbook; each partner's adapter is written when that partner is actually onboarded.
- Additional payment providers (wallets, BNPL) — open business decision, not yet made. Phase 7 §4.
One open item across all of these
Backend ownership — answered 2026-08-18. A separate backend developer implements against these contracts. This repository's team owns the frontend and owns this contract set — the docs here are the handoff surface between the two, so a change to any contract is a change both sides must see. Keep them current; they are not a one-time deliverable.