marketplaces/docs/platform/10-product-domain.md

10. Домен товаров

Назначение

Товарный домен определяет контракт карточки товара, листингов, ценовых и складских атрибутов.

Поведение системы

• Товары загружаются по API для листинга, карточки и связанных коллекций.
• Frontend отображает только те поля, которые есть в контракте.
• Бизнес-правила доступности товара приходят из backend.

Обязательные JSON-свойства товара

• itemID
• name
• price
• currency
• categoryID
• visible

Опциональные свойства

• discount
• images
• badges
• simpleDescription
• attributes
• stockStatus
• rating

Product Engagement Models

• RatingSummary
  • average: number
  • totalReviews: number
  • distribution: [{ stars, count, share }]
• Review
  • id, rating, title, text, author, anonymous, verifiedPurchase, createdAt
  • likes/dislikes placeholders
  • photos: string[] (reserved for future uploads)
• Question
  • id, text, author, createdAt, likes, dislikes
  • answers: Answer[]
• Answer
  • id, text, author, createdAt
  • isOfficialSeller, isAccepted

Строгие правила

• Цена и валюта должны передаваться как валидная пара.
• Скрытые товары не участвуют в публичных витринах.
• categoryID должен ссылаться на существующую категорию.
• Виджет не изменяет товарные данные, только отображает.
• Frontend feature-слой работает только через ProductFacade.
• DTO/API shape не импортируется в feature components.
• reviews/questions не хранятся в bootstrap, только их feature-конфиг.

Пример JSON товара

{
  "itemID": 7812,
  "name": "Laptop Pro 14",
  "price": 129990,
  "currency": "RUB",
  "categoryID": 55,
  "visible": true,
  "discount": 10,
  "images": [
    { "url": "https://cdn.example.com/items/7812/main.jpg", "isMain": true }
  ],
  "badges": ["featured", "new"]
}

Ответственность Frontend

• Показывать корректную цену, скидку, бейджи и доступность.
• Поддерживать переход из листинга в карточку товара.
• Учитывать locale/currency из tenant-конфигурации.

Ответственность Backend

• Возвращать актуальные цены и доступность.
• Стабильно поддерживать идентификаторы товаров.
• Предоставлять медиа и атрибуты в согласованном формате.