# Продукты (Products)

Система продуктов и товаров в игре.

## Обзор

Продукты — основа экономической модели. Каждый продукт имеет тип (конфигурацию) и экземпляр (количество).

📂 **Код:** [`backend/src/MyBiz.Core/Product*.cs`](../../backend/src/MyBiz.Core/)

---

## Архитектура

```
┌─────────────────┐         ┌─────────────────┐
│  ProductType    │         │   Product       │
│  (конфигурация) │ ──────► │  (экземпляр)    │
│  - Id           │  Type   │  - Quantity     │
│  - Name         │         │  - CurrentPrice │
│  - BasePrice    │         │  - Quality      │
│  - ShelfLife    │         │  - IsSpoiled    │
└─────────────────┘         └─────────────────┘
         ▲
         │
┌─────────────────┐
│ ProductRegistry │
│  (реестр типов) │
└─────────────────┘
```

---

## ProductType

**Назначение:** Конфигурация типа продукта для моддинга.

📂 **Исходный код:** [`ProductType.cs`](../../backend/src/MyBiz.Core/ProductType.cs)

### Основные свойства

| Свойство | Тип | Описание |
|----------|-----|----------|
| `Id` | string | Уникальный идентификатор (для моддинга) |
| `Name` | string | Отображаемое имя |
| `Description` | string | Описание продукта |
| `Category` | ProductCategory | Категория (сырьё/компонент/товар) |
| `BasePrice` | decimal | Базовая цена |
| `BaseDemand` | int | Базовый спрос в тик |
| `DemandElasticity` | float | Эластичность спроса (0-1) |
| `ShelfLife` | int | Срок хранения в тиках (0 = бессрочно) |
| `StackSize` | int | Размер стека в инвентаре |
| `AvailableFromYear` | int | Год доступности (исторический режим) |
| `RequiredTechnologies` | List<string> | Требуемые технологии |

### Вычисляемые свойства

- `IsPerishable` — портится ли продукт (ShelfLife > 0)

### Методы

- `Clone()` — создание независимой копии

---

## Product

**Назначение:** Экземпляр продукта в инвентаре/на складе.

📂 **Исходный код:** [`Product.cs`](../../backend/src/MyBiz.Core/Product.cs)

### Основные свойства

| Свойство | Тип | Описание |
|----------|-----|----------|
| `Id` | Guid | Уникальный ID экземпляра |
| `Type` | ProductType | Ссылка на конфигурацию типа |
| `Quantity` | int | Количество |
| `CurrentPrice` | decimal | Текущая цена за единицу |
| `CreatedAtTick` | int | Тик создания (для срока годности) |
| `Quality` | int | Качество (0-100) |
| `IsSpoiled` | bool | Испорчен ли |

### Вычисляемые свойства

- `TotalValue` — общая стоимость (Quantity × CurrentPrice)
- `IsUsable` — можно ли использовать (Quantity > 0 && !IsSpoiled)

### Методы

| Метод | Описание |
|-------|----------|
| `Add(int amount)` | Добавить количество |
| `Remove(int amount)` | Удалить количество (возвращает факт. удалённое) |
| `Update(int currentTick)` | Обновить состояние (проверка срока годности) |

---

## ProductRegistry

**Назначение:** Централизованный реестр типов продуктов.

📂 **Исходный код:** [`ProductRegistry.cs`](../../backend/src/MyBiz.Core/ProductRegistry.cs)

### Методы

| Метод | Описание |
|-------|----------|
| `Register(ProductType)` | Зарегистрировать тип |
| `GetById(string)` | Получить по ID |
| `GetOrThrow(string)` | Получить или выбросить исключение |
| `Exists(string)` | Проверка существования |
| `GetByCategory(ProductCategory)` | Фильтр по категории |
| `GetAvailableInYear(int)` | Фильтр по году доступности |
| `Remove(string)` | Удалить тип |
| `LoadFromConfig(string)` | Загрузить из JSON (TODO) |
| `ExportToJson()` | Экспорт в JSON (TODO) |

### События

- `ProductTypeAdded` — добавлен новый тип (для моддинга)
- `ProductTypeModified` — изменён тип

---

## Дефолтные продукты

**12 продуктов в 3 категориях:**

📂 **Исходный код:** [`DefaultProducts.cs`](../../backend/src/MyBiz.Core/DefaultProducts.cs)

### Сырьё (RawMaterial)

| ID | Название | Базовая цена | Портится | С  года |
|----|----------|--------------|----------|---------|
| `raw_cotton` | Хлопок | 5 | ❌ | 1900 |
| `raw_steel` | Сталь | 15 | ❌ | 1900 |
| `raw_plastic` | Пластик | 8 | ❌ | 1950 |
| `raw_food` | Сельхозпродукция | 3 | ✅ (10 тиков) | 1900 |

### Компоненты (Component)

| ID | Название | Базовая цена | Портится | С  года |
|----|----------|--------------|----------|---------|
| `comp_fabric` | Ткань | 12 | ❌ | 1900 |
| `comp_metal_parts` | Металлоизделия | 25 | ❌ | 1900 |
| `comp_plastic_parts` | Пластиковые детали | 18 | ❌ | 1950 |
| `comp_electronics` | Электронные компоненты | 50 | ❌ | 1960 |

### Товары (ConsumerGoods)

| ID | Название | Базовая цена | Портится | С  года |
|----|----------|--------------|----------|---------|
| `goods_food` | Продукты питания | 8 | ✅ (5 тиков) | 1900 |
| `goods_clothing` | Одежда | 35 | ❌ | 1900 |
| `goods_electronics` | Электроника | 150 | ❌ | 1960 |
| `goods_automobile` | Автомобили | 5000 | ❌ | 1920 |

---

## Примеры использования

### Регистрация типа продукта

```csharp
var registry = new ProductRegistry();

var bread = new ProductType
{
    Id = "food_bread",
    Name = "Хлеб",
    Category = ProductCategory.ConsumerGoods,
    BasePrice = 10m,
    ShelfLife = 5,
    AvailableFromYear = 1900
};

registry.Register(bread);
```

### Создание экземпляра продукта

```csharp
var product = new Product
{
    Type = registry.GetOrThrow("goods_food"),
    Quantity = 100,
    CurrentPrice = 8m,
    CreatedAtTick = 0
};

product.Add(50);        // +50 единиц
product.Remove(30);     // -30 единиц
product.Update(10);     // проверка через 10 тиков
```

### Фильтрация продуктов

```csharp
// Все сырьевые продукты
var rawMaterials = registry.GetByCategory(ProductCategory.RawMaterial);

// Доступные в 1950 году
var available1950 = registry.GetAvailableInYear(1950);

// Скоропортящиеся
var perishable = registry.AllProductTypes.Where(p => p.IsPerishable);
```

---

## Тесты

📂 **Код:** [`backend/tests/MyBiz.Tests/ProductTests.cs`](../../backend/tests/MyBiz.Tests/ProductTests.cs)

| Тест | Описание |
|------|----------|
| `ProductType_Creation_ShouldInitializeProperties` | Создание типа продукта |
| `ProductType_Clone_ShouldCreateIndependentCopy` | Клонирование типа |
| `Product_Add_ShouldIncreaseQuantity` | Добавление количества |
| `Product_Remove_ShouldDecreaseQuantity` | Удаление количества |
| `Product_Perishable_ShouldSpoilAfterShelfLife` | Порча продуктов |
| `Registry_*` | Тесты реестра |

---

## Связанные документы

- [Ядро](core.md) — базовые классы
- [Производство](production.md) — использование продуктов в цепочках
- [Торговля](trade.md) — рынки и цены

---

**Последнее обновление:** 20.02.2026