From b9f4103c8e4aa2b0f814f1d3451751406182b6a3 Mon Sep 17 00:00:00 2001
From: sdarbinyan <sdarbinyan@4pay.ru>
Date: Sun, 5 Jul 2026 01:13:03 +0400
Subject: [PATCH] Add marketplace MVP report

---
 docs/Marketplace-MVP-Report.md | 92 ++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/Marketplace-MVP-Report.md

diff --git a/docs/Marketplace-MVP-Report.md b/docs/Marketplace-MVP-Report.md
new file mode 100644
index 0000000..22c881f
--- /dev/null
+++ b/docs/Marketplace-MVP-Report.md
@@ -0,0 +1,92 @@
+# Marketplace MVP Report
+
+## Scope
+
+Sprint 3 delivered the first client-ready marketplace flow on the frozen architecture. The implemented path is configuration-driven and contract-compatible:
+
+Component -> Facade -> ProductDataService -> Provider -> Mock/API
+
+Builder, Backoffice, admin, database, auth contract redesign, payment contract redesign, routing redesign, and dynamic renderer redesign were intentionally left untouched.
+
+## Completed Flow
+
+### Product Data Layer
+
+- Added product domain contracts and provider interfaces.
+- Added `ProductDataService` and `PRODUCT_DATA_PROVIDER` abstraction.
+- Implemented API-backed product provider over existing `ApiService`.
+- Preserved mock/API switching through the existing mock-data interceptor and runtime provider strategy.
+
+Commit: `05d7542 Add product data domain layer`
+
+### Marketplace Facade Migration
+
+- Added `ProductFacade` as the component-facing product API.
+- Migrated visible marketplace product/category reads through the facade.
+- Kept cart payment and product review submission on existing API contracts.
+
+Commit: `ae3512a Route marketplace data through product facade`
+
+### Reusable Product Card
+
+- Added reusable, input/output-only product card component.
+- Integrated the card into category and search product grids.
+- Kept routing, add-to-cart, preview/prefetch, price, stock, discount, rating, and description display reusable.
+
+Commit: `d7d73c2 Add reusable marketplace product card`
+
+### Product Detail
+
+- Product detail continues to support gallery, localized title/description, price, discount, attributes, variants, stock, badges, tags, SEO, reviews, and Q&A.
+- Added related products through `ProductFacade.getRelatedProducts()`.
+- Rendered related products with the reusable product card.
+- Added localized related-products labels for English, Russian, and Armenian.
+
+Commit: `b676cec Add related products to detail page`
+
+### Category Navigation
+
+- Preserved existing language-prefixed category routing.
+- Added recursive nested-category lookup so API descendants can route correctly even when they are not repeated as root categories.
+- Kept legacy flat-category fallback.
+- Added localized category/product count labels and visible mixed-content indicators.
+
+Commit: `3974eef Support nested marketplace categories`
+
+### Search
+
+- Search remains facade/provider/API driven.
+- Added short-query handling so queries below the backend threshold show a localized prompt instead of stale results or false empty states.
+- Trimmed outgoing queries and cleared stale errors before new searches.
+- Fixed the no-results icon path.
+
+Commit: `3f5aa2a Polish marketplace search states`
+
+### Cart Integration
+
+- Preserved existing cart persistence, Telegram auth gate, delivery selection, QR/card payment creation, payment polling, and post-payment email/phone handling.
+- Made cart add/update/remove operations variant-aware by product, color, and size.
+- Prevented separate variants of the same product from merging or being removed together.
+- Payment payload continues to include variant details in item names.
+
+Commit: `01d2b26 Support variant-aware cart lines`
+
+## CMS Readiness
+
+- Hardcoded informational/legal pages remain disabled for backend CMS ownership.
+- Header/footer/static route placeholders are marked with `TODO(CMS)` comments.
+- Cart legal labels remain non-linked placeholders pending backend-configured legal document links.
+
+## Validation
+
+Each implementation phase was built before commit with:
+
+```bash
+npm run build
+```
+
+Final validation also passed with the same build command after the Marketplace MVP report was added.
+
+## Current Approval Boundary
+
+Marketplace MVP flow is complete for the requested Sprint 3 scope. Stop here and wait for approval before starting Builder or Backoffice work.