feat(product): add reusable Product Experience 2.0

Unify product details modules behind config-driven contracts so teams can extend UX without changing runtime architecture or bootstrap flow. Keep backward compatibility with existing product payloads by treating new media/specification/variant/related structures as optional extensions. Improve conversion and content discoverability with reusable actions, typed media rendering, grouped specifications, dynamic variants, and multi-collection related products.
2026-07-10 13:10:35 +04:00
parent 86de2cc45b
commit aed0a47388
37 changed files with 1257 additions and 77 deletions
--- a/docs/Product-Details-Report.md
+++ b/docs/Product-Details-Report.md
@@ -155,3 +155,118 @@ npm run build
 ## Stop Point

 Product Details Module implementation is complete for Sprint 6. Stop here for approval before starting any further module work.
+
+## Sprint 11 - Product Experience 2.0
+
+Sprint 11 extends Product Details UX with reusable modules and config-driven behavior. Architecture, Widget Manifest, Section Engine, bootstrap loading, authentication, and payment logic remain unchanged.
+
+### New Reusable Modules
+
+- Product Actions module
+	- `Add to Cart`, `Buy Now`, `Wishlist`, `Compare`, `Share`, `Notify Me`
+	- `productPage.actions` controls visibility of each action
+- Product Gallery upgrade
+	- Media renderer by type (`image`, `video`, `pdf`, `manual`, `warranty`)
+	- Thumbnail strip + active media
+	- Mobile swipe support
+	- Zoom/fullscreen extension events (`zoomRequested`, `fullscreenRequested`)
+- Product Specifications upgrade
+	- Grouped attributes via `specificationGroups`
+	- Translated labels via `labels` map
+	- Backward-compatible fallback to `descriptionFields` and `attributes`
+- Variant Selector upgrade
+	- Dynamic option groups via `variantOptions`
+	- No hardcoded variant keys required
+	- Backward-compatible color/size fallback
+- Reviews upgrade
+	- Existing pagination preserved
+	- Optional `load-more` mode added via config
+	- Review form adds explicit validation and success state
+- Questions & Answers upgrade
+	- Existing list/answers/accepted-answer behavior preserved
+	- Submission can be toggled off while component remains future-ready
+- Related Products upgrade
+	- Supports multiple backend-provided collections
+	- Falls back to previous single related collection behavior
+
+### Config Additions (backward-compatible)
+
+`productPage` supports new optional keys:
+
+```json
+{
+	"reviews": {
+		"mode": "pages"
+	},
+	"questions": {
+		"allowSubmission": true
+	},
+	"actions": {
+		"enabled": true,
+		"addToCart": true,
+		"buyNow": true,
+		"wishlist": true,
+		"compare": true,
+		"share": true,
+		"notifyMe": true
+	}
+}
+```
+
+### Product JSON Extension Example
+
+```json
+{
+	"itemID": 7812,
+	"name": "Laptop Pro 14",
+	"media": [
+		{ "type": "image", "url": "https://cdn.example.com/items/7812/main.jpg" },
+		{ "type": "video", "url": "https://cdn.example.com/items/7812/demo.mp4" },
+		{ "type": "pdf", "url": "https://cdn.example.com/items/7812/spec.pdf" },
+		{ "type": "manual", "url": "https://cdn.example.com/items/7812/manual.pdf" },
+		{ "type": "warranty", "url": "https://cdn.example.com/items/7812/warranty.pdf" }
+	],
+	"specificationGroups": [
+		{
+			"key": "display",
+			"label": "Display",
+			"labels": { "en": "Display", "ru": "Экран", "hy": "Էկրան" },
+			"attributes": [
+				{ "key": "size", "value": "14", "unit": "inch", "labels": { "en": "Size", "ru": "Диагональ", "hy": "Չափ" } },
+				{ "key": "resolution", "value": "2880x1800", "labels": { "en": "Resolution", "ru": "Разрешение", "hy": "Լուծաչափ" } }
+			]
+		}
+	],
+	"variantOptions": [
+		{
+			"key": "storage",
+			"label": "Storage",
+			"options": [
+				{ "value": "256GB" },
+				{ "value": "512GB" }
+			]
+		}
+	],
+	"relatedCollections": [
+		{
+			"id": "frequently-bought-together",
+			"title": "Frequently bought together",
+			"titles": { "ru": "Покупают вместе", "hy": "Հաճախ գնում են միասին" },
+			"products": [9021, 9022, 9023]
+		},
+		{
+			"id": "similar-products",
+			"title": "Similar products",
+			"products": [9030, 9031]
+		}
+	]
+}
+```
+
+### Extension Points
+
+- Gallery overlays can subscribe to `zoomRequested` and `fullscreenRequested` without changing gallery internals.
+- Variant logic can add new option groups from backend by extending `variantOptions` only.
+- Specifications can add locale labels without frontend refactor.
+- Related collections can add campaign-specific blocks without changing section engine.
+- Action visibility and review mode can be tuned from config without component rewrites.
--- a/docs/platform/10-product-domain.md
+++ b/docs/platform/10-product-domain.md
@@ -24,6 +24,10 @@
 - attributes
 - stockStatus
 - rating
+- media
+- specificationGroups
+- variantOptions
+- relatedCollections

 ## Product Engagement Models
 - RatingSummary
@@ -41,6 +45,26 @@
  - id, text, author, createdAt
  - isOfficialSeller, isAccepted

+## Product Experience 2.0 Optional Contracts
+
+- media: `[{ type, url, thumbnailUrl?, alt?, title?, labels? }]`
+  - type: `image | video | pdf | manual | warranty`
+  - frontend renderer picks viewer by `type`
+- specificationGroups: `[{ key, label?, labels?, attributes: [{ key, value, label?, labels?, unit? }] }]`
+  - supports grouped specifications and translated labels
+- variantOptions: `[{ key, label?, labels?, options: [{ value, label?, labels?, available? }] }]`
+  - supports arbitrary variant groups (`color`, `size`, `storage`, etc.)
+- relatedCollections: `[{ id, title, titles?, products: number[] }]`
+  - supports multiple related collections from backend
+
+## Product Page Config Extensions
+
+`productPage` optional config additions:
+
+- reviews.mode: `pages | load-more`
+- questions.allowSubmission: `boolean`
+- actions: `{ enabled, addToCart, buyNow, wishlist, compare, share, notifyMe }`
+
 ## Строгие правила
 - Цена и валюта должны передаваться как валидная пара.
 - Скрытые товары не участвуют в публичных витринах.
@@ -63,7 +87,35 @@
  "images": [
    { "url": "https://cdn.example.com/items/7812/main.jpg", "isMain": true }
  ],
-  "badges": ["featured", "new"]
+  "badges": ["featured", "new"],
+  "media": [
+    { "type": "image", "url": "https://cdn.example.com/items/7812/main.jpg" },
+    { "type": "video", "url": "https://cdn.example.com/items/7812/demo.mp4" },
+    { "type": "pdf", "url": "https://cdn.example.com/items/7812/spec.pdf" }
+  ],
+  "specificationGroups": [
+    {
+      "key": "display",
+      "labels": { "en": "Display", "ru": "Экран" },
+      "attributes": [
+        { "key": "size", "value": "14", "unit": "inch" },
+        { "key": "resolution", "value": "2880x1800" }
+      ]
+    }
+  ],
+  "variantOptions": [
+    {
+      "key": "storage",
+      "options": [{ "value": "256GB" }, { "value": "512GB" }]
+    }
+  ],
+  "relatedCollections": [
+    {
+      "id": "similar-products",
+      "title": "Похожие товары",
+      "products": [9030, 9031]
+    }
+  ]
 }
 ```

@@ -76,3 +128,4 @@
 - Возвращать актуальные цены и доступность.
 - Стабильно поддерживать идентификаторы товаров.
 - Предоставлять медиа и атрибуты в согласованном формате.
+- Поддерживать обратную совместимость: новые поля опциональны, старые payload остаются валидными.