Add technical documentation structure

2026-02-21 10:26:23 +03:00
parent ec3da03bba
commit c80afaaeaa
5 changed files with 862 additions and 0 deletions
--- a/docs/tech/README.md
+++ b/docs/tech/README.md
@@ -0,0 +1,46 @@
+# Техническая документация
+
+Общая структура технической документации проекта MyBiz.
+
+## 📚 Разделы документации
+
+| Раздел | Описание | Файл |
+|--------|----------|------|
+| **Ядро** | Базовые классы и структуры данных | [core.md](core.md) |
+| **Продукты** | Система продуктов и товаров | [products.md](products.md) |
+| **Здания** | Типы зданий и предприятия | [buildings.md](buildings.md) |
+| **Производство** | Цепочки и процессы производства | [production.md](production.md) |
+| **Экономика** | Экономическая модель | [economy.md](economy.md) |
+| **Торговля** | Рынки, спрос, предложение | [trade.md](trade.md) |
+| **Исследования** | Дерево технологий | [research.md](research.md) |
+| **Архитектура** | Общая архитектура системы | [architecture.md](architecture.md) |
+
+## 📁 Структура исходного кода
+
+```
+backend/
+├── src/
+│   ├── MyBiz.Core/           # Базовые модели
+│   │   ├── ProductType.cs    # Типы продуктов
+│   │   ├── Product.cs        # Экземпляры продуктов
+│   │   ├── ProductRegistry.cs # Реестр продуктов
+│   │   ├── Building.cs       # Здания
+│   │   ├── City.cs           # Города
+│   │   ├── Company.cs        # Компания
+│   │   ├── ProductionChain.cs # Производственные цепочки
+│   │   └── DefaultProducts.cs # Дефолтные продукты
+│   ├── MyBiz.Economy/        # Экономическая модель
+│   ├── MyBiz.Production/     # Производство
+│   └── MyBiz.Trade/          # Торговля
+└── tests/
+    └── MyBiz.Tests/          # Тесты
+```
+
+## 🔗 Ссылки
+
+- [Техническое задание](TZ.md)
+- [Репозиторий проекта](https://git.six83.ru/ssa/my-biz.git)
+
+---
+
+**Последнее обновление:** 20.02.2026
--- a/docs/tech/buildings.md
+++ b/docs/tech/buildings.md
@@ -0,0 +1,196 @@
+# Здания (Buildings)
+
+Система зданий и предприятий в игре.
+
+## Обзор
+
+Здания — места, где происходит производство, торговля или хранение товаров.
+
+📂 **Код:** [`backend/src/MyBiz.Core/Building.cs`](../../backend/src/MyBiz.Core/Building.cs)
+
+---
+
+## Архитектура
+
+```
+┌─────────────────────┐         ┌───────────┐
+│ BuildingTypeConfig  │ ──────► │ Building  │
+│ (тип здания)        │  Type   │ (здание)  │
+│ - Id                │ Config  │ - Level   │
+│ - Name              │         │ - Workers │
+│ - Category          │         │ - Inventory│
+│ - BuildCost         │         │ - Efficiency│
+└─────────────────────┘         └───────────┘
+```
+
+---
+
+## BuildingTypeConfig
+
+**Назначение:** Конфигурация типа здания для моддинга.
+
+📂 **Исходный код:** [`Building.cs`](../../backend/src/MyBiz.Core/Building.cs#L10-L75)
+
+### Основные свойства
+
+| Свойство | Тип | Описание |
+|----------|-----|----------|
+| `Id` | string | Уникальный идентификатор |
+| `Name` | string | Отображаемое имя |
+| `Description` | string | Описание |
+| `Category` | BuildingCategory | Категория здания |
+| `BuildCost` | decimal | Стоимость постройки |
+| `UpkeepCost` | decimal | Содержание в тик |
+| `StorageCapacity` | int | Вместимость склада |
+| `WorkerSlots` | int | Количество рабочих мест |
+| `BaseEfficiency` | int | Базовая эффективность (0-100) |
+| `MaxLevel` | int | Максимальный уровень |
+| `AvailableFromYear` | int | Год доступности |
+| `RequiredTechnologies` | List<string> | Требуемые технологии |
+| `OutputProducts` | List<string> | Производимые продукты |
+| `InputProducts` | List<string> | Потребляемые продукты |
+
+### Категории зданий
+
+| Категория | Описание | Примеры |
+|-----------|----------|---------|
+| `RawMaterial` | Добыча сырья | Ферма, шахта |
+| `Production` | Производство | Завод, фабрика |
+| `Trade` | Торговля | Магазин, салон |
+| `Research` | Исследования | Лаборатория |
+| `Storage` | Склад | Складское помещение |
+| `Office` | Офис | Административное здание |
+
+---
+
+## Building
+
+**Назначение:** Экземпляр здания в игре.
+
+📂 **Исходный код:** [`Building.cs`](../../backend/src/MyBiz.Core/Building.cs#L89-L165)
+
+### Основные свойства
+
+| Свойство | Тип | Описание |
+|----------|-----|----------|
+| `Id` | Guid | Уникальный ID здания |
+| `TypeConfig` | BuildingTypeConfig | Конфигурация типа |
+| `Name` | string | Отображаемое имя (кастомизируемое) |
+| `CityId` | string | ID города |
+| `X`, `Y` | int | Координаты на карте |
+| `Level` | int | Уровень здания |
+| `Workers` | int | Количество рабочих |
+| `CurrentEfficiency` | int | Текущая эффективность |
+| `Inventory` | Dictionary<string, int> | Запасы на складе |
+| `IsActive` | bool | Здание работает |
+| `BuiltAtTick` | int | Тик постройки |
+
+### Вычисляемые свойства
+
+- `WorkerSlots` — из конфигурации типа
+- `StorageCapacity` — из конфигурации типа
+
+### Методы
+
+| Метод | Описание |
+|-------|----------|
+| `CalculateEfficiency()` | Расчёт эффективности |
+| `Update()` | Обновление состояния |
+
+### Формула эффективности
+
+```
+Efficiency = BaseEfficiency + (Level - 1) * 5 - WorkerPenalty
+
+WorkerPenalty = (WorkerSlots - Workers) * 100 / WorkerSlots
+```
+
+**Пример:**
+- BaseEfficiency = 100
+- Level = 3 → +10% бонус
+- Workers = 8/10 → -20% штраф
+- **Итого:** 100 + 10 - 20 = **90%**
+
+---
+
+## Примеры использования
+
+### Создание типа здания
+
+```csharp
+var textileFactory = new BuildingTypeConfig
+{
+    Id = "textile_factory",
+    Name = "Текстильная фабрика",
+    Category = BuildingCategory.Production,
+    BuildCost = 50000m,
+    UpkeepCost = 500m,
+    WorkerSlots = 50,
+    StorageCapacity = 1000,
+    BaseEfficiency = 100,
+    AvailableFromYear = 1900,
+    InputProducts = { "raw_cotton" },
+    OutputProducts = { "comp_fabric" }
+};
+```
+
+### Создание здания
+
+```csharp
+var factory = new Building
+{
+    TypeConfig = textileFactory,
+    Name = "Главная фабрика",
+    CityId = "city_1",
+    X = 100,
+    Y = 200,
+    Level = 1,
+    Workers = 0,  // Пока нет рабочих
+    IsActive = true
+};
+
+factory.Workers = 40;  // Наняли рабочих
+factory.Update();      // Пересчитать эффективность
+```
+
+### Расчёт эффективности
+
+```csharp
+var building = new Building
+{
+    TypeConfig = new BuildingTypeConfig
+    {
+        BaseEfficiency = 100,
+        WorkerSlots = 10
+    },
+    Level = 5,
+    Workers = 10
+};
+
+building.CalculateEfficiency();
+// 100 + (5-1)*5 - 0 = 120%
+```
+
+---
+
+## Тесты
+
+📂 **Код:** [`backend/tests/MyBiz.Tests/BuildingTests.cs`](../../backend/tests/MyBiz.Tests/BuildingTests.cs)
+
+| Тест | Описание |
+|------|----------|
+| `Building_CalculateEfficiency_FullWorkers_ShouldBeMax` | Полная укомплектованность |
+| `Building_CalculateEfficiency_NoWorkers_ShouldBeZero` | Нет рабочих |
+| `Building_LevelBonus_ShouldIncreaseEfficiency` | Бонус за уровень |
+
+---
+
+## Связанные документы
+
+- [Ядро](core.md) — базовые классы
+- [Производство](production.md) — использование зданий в производстве
+- [Города](core.md#city) — размещение зданий в городах
+
+---
+
+**Последнее обновление:** 20.02.2026
--- a/docs/tech/core.md
+++ b/docs/tech/core.md
@@ -0,0 +1,165 @@
+# Ядро игры (Core)
+
+Базовые классы и структуры данных, используемые во всём проекте.
+
+## Обзор
+
+Модуль `MyBiz.Core` содержит фундаментальные классы для представления игровых сущностей.
+
+📂 **Код:** [`backend/src/MyBiz.Core/`](../../backend/src/MyBiz.Core/)
+
+---
+
+## Классы
+
+### ProductType
+
+Конфигурация типа продукта. Используется для моддинга.
+
+- **Назначение:** Определение свойств типа продукта (цена, спрос, категория)
+- **Ключевые свойства:** `Id`, `Name`, `Category`, `BasePrice`, `ShelfLife`
+- **Особенности:** Поддержка исторической доступности (год появления)
+
+📂 **Исходный код:** [`ProductType.cs`](../../backend/src/MyBiz.Core/ProductType.cs)
+
+---
+
+### Product
+
+Экземпляр продукта в игре.
+
+- **Назначение:** Представление конкретного количества товара
+- **Ключевые свойства:** `Type`, `Quantity`, `CurrentPrice`, `Quality`
+- **Методы:** `Add()`, `Remove()`, `Update()` (проверка срока годности)
+
+📂 **Исходный код:** [`Product.cs`](../../backend/src/MyBiz.Core/Product.cs)
+
+---
+
+### ProductRegistry
+
+Централизованный реестр типов продуктов.
+
+- **Назначение:** Хранение и управление конфигурациями продуктов
+- **Возможности:** Регистрация, поиск, фильтрация по категории и году
+- **События:** `ProductTypeAdded`, `ProductTypeModified` (для моддинга)
+
+📂 **Исходный код:** [`ProductRegistry.cs`](../../backend/src/MyBiz.Core/ProductRegistry.cs)
+
+---
+
+### Building
+
+Здание предприятия в игре.
+
+- **Назначение:** Представление фабрик, магазинов, складов
+- **Ключевые свойства:** `TypeConfig`, `Level`, `Workers`, `Efficiency`
+- **Методы:** `CalculateEfficiency()`, `Update()`
+
+📂 **Исходный код:** [`Building.cs`](../../backend/src/MyBiz.Core/Building.cs)
+
+---
+
+### BuildingTypeConfig
+
+Конфигурация типа здания.
+
+- **Назначение:** Определение свойств типа здания для моддинга
+- **Ключевые свойства:** `Id`, `Name`, `Category`, `BuildCost`, `WorkerSlots`
+- **Категории:** RawMaterial, Production, Trade, Research, Storage, Office
+
+📂 **Исходный код:** [`Building.cs`](../../backend/src/MyBiz.Core/Building.cs#L10-L75)
+
+---
+
+### City
+
+Город с рынком.
+
+- **Назначение:** Представление локации с экономикой
+- **Ключевые свойства:** `Name`, `Population`, `MarketDemand`, `MarketSupply`, `Prices`
+- **Словари:** Спрос/предложение по типам продуктов, цены
+
+📂 **Исходный код:** [`City.cs`](../../backend/src/MyBiz.Core/City.cs)
+
+---
+
+### Company
+
+Компания игрока.
+
+- **Назначение:** Состояние бизнеса игрока
+- **Ключевые свойства:** `Cash`, `Assets`, `Liabilities`, `Buildings`, `Inventory`
+- **Вычисляемое:** `NetWorth` (чистая стоимость)
+
+📂 **Исходный код:** [`Company.cs`](../../backend/src/MyBiz.Core/Company.cs)
+
+---
+
+### ProductionChainConfig
+
+Конфигурация производственной цепочки.
+
+- **Назначение:** Определение рецепта производства
+- **Ключевые свойства:** `OutputProductId`, `RequiredBuildingId`, `Steps`
+- **Шаги:** Список `ProductionStep` с входными продуктами и временем
+
+📂 **Исходный код:** [`ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs#L25-L68)
+
+---
+
+### ActiveProductionChain
+
+Активный процесс производства на здании.
+
+- **Назначение:** Отслеживание прогресса производства
+- **Ключевые свойства:** `Config`, `Building`, `CurrentStep`, `Progress`
+- **Методы:** `Tick()` (продвижение на 1 тик)
+
+📂 **Исходный код:** [`ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs#L73-L125)
+
+---
+
+## Перечисления
+
+### ProductCategory
+
+Категории продуктов:
+
+| Значение | Описание |
+|----------|----------|
+| `RawMaterial` | Сырьё (хлопок, сталь) |
+| `Component` | Компоненты (ткань, детали) |
+| `ConsumerGoods` | Товары народного потребления |
+| `Luxury` | Предметы роскоши (будущее) |
+
+📂 **Исходный код:** [`ProductType.cs`](../../backend/src/MyBiz.Core/ProductType.cs#L5-L11)
+
+---
+
+### BuildingCategory
+
+Категории зданий:
+
+| Значение | Описание |
+|----------|----------|
+| `RawMaterial` | Добыча сырья |
+| `Production` | Производство |
+| `Trade` | Торговля |
+| `Research` | Исследования |
+| `Storage` | Склад |
+| `Office` | Офис |
+
+📂 **Исходный код:** [`Building.cs`](../../backend/src/MyBiz.Core/Building.cs#L78-L86)
+
+---
+
+## Связанные документы
+
+- [Продукты](products.md) — детальное описание системы продуктов
+- [Здания](buildings.md) — типы предприятий
+- [Производство](production.md) — цепочки производства
+
+---
+
+**Последнее обновление:** 20.02.2026
--- a/docs/tech/production.md
+++ b/docs/tech/production.md
@@ -0,0 +1,220 @@
+# Производство (Production)
+
+Система производственных цепочек и процессов.
+
+## Обзор
+
+Производство преобразует сырьё и компоненты в готовые товары через цепочки операций.
+
+📂 **Код:** [`backend/src/MyBiz.Core/ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs)
+
+---
+
+## Архитектура
+
+```
+┌────────────────────────┐         ┌────────────────────────┐
+│ ProductionChainConfig  │         │ ActiveProductionChain  │
+│ (конфигурация)         │ ──────► │ (активный процесс)     │
+│ - OutputProductId      │  Config │ - CurrentStep          │
+│ - RequiredBuildingId   │         │ - Progress             │
+│ - Steps[]              │         │ - IsActive             │
+└────────────────────────┘         └────────────────────────┘
+                                            │
+                                            ▼
+                                   ┌────────────────────────┐
+                                   │      Building          │
+                                   │ (где происходит)       │
+                                   └────────────────────────┘
+```
+
+---
+
+## ProductionStep
+
+**Назначение:** Один шаг производственного процесса.
+
+📂 **Исходный код:** [`ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs#L5-L22)
+
+### Свойства
+
+| Свойство | Тип | Описание |
+|----------|-----|----------|
+| `InputProductId` | string | ID требуемого продукта |
+| `InputQuantity` | int | Количество |
+| `ProductionTime` | int | Время выполнения в тиках |
+
+---
+
+## ProductionChainConfig
+
+**Назначение:** Конфигурация производственной цепочки (рецепт).
+
+📂 **Исходный код:** [`ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs#L25-L68)
+
+### Свойства
+
+| Свойство | Тип | Описание |
+|----------|-----|----------|
+| `Id` | string | Уникальный идентификатор |
+| `Name` | string | Название цепочки |
+| `OutputProductId` | string | ID выходного продукта |
+| `OutputQuantity` | int | Количество выходного продукта |
+| `RequiredBuildingId` | string | ID требуемого здания |
+| `Steps` | List<ProductionStep> | Шаги производства |
+| `RequiredTechnologies` | List<string> | Требуемые технологии |
+| `AvailableFromYear` | int | Год доступности |
+
+---
+
+## ActiveProductionChain
+
+**Назначение:** Активный процесс производства на здании.
+
+📂 **Исходный код:** [`ProductionChain.cs`](../../backend/src/MyBiz.Core/ProductionChain.cs#L73-L125)
+
+### Свойства
+
+| Свойство | Тип | Описание |
+|----------|-----|----------|
+| `Config` | ProductionChainConfig | Конфигурация |
+| `Building` | Building | Здание, где происходит |
+| `CurrentStep` | int | Текущий шаг (0-based) |
+| `Progress` | int | Прогресс текущего шага (в тиках) |
+| `IsActive` | bool | Процесс активен |
+| `StartedAtTick` | int | Тик запуска |
+
+### Вычисляемые свойства
+
+- `IsStepComplete` — завершён ли текущий шаг
+- `IsComplete` — завершено ли всё производство
+
+### Методы
+
+| Метод | Описание |
+|-------|----------|
+| `Tick()` | Продвинуть производство на 1 тик |
+
+---
+
+## Примеры производственных цепочек
+
+### 🍞 Продукты питания
+
+```
+Сельхозпродукция (100) → [Пищекомбинат] → Продукты питания (80)
+Время: 5 тиков
+```
+
+### 👕 Одежда
+
+```
+Шаг 1: Хлопок (50) → [Текстильная фабрика] → Ткань (40)
+       Время: 10 тиков
+
+Шаг 2: Ткань (40) → [Швейная фабрика] → Одежда (30)
+       Время: 8 тиков
+```
+
+### 📱 Электроника
+
+```
+Шаг 1: Пластик (30) + Сталь (20) → [Завод компонентов] → Электронные компоненты (25)
+       Время: 15 тиков
+
+Шаг 2: Электронные компоненты (25) + Пластик (15) → [Завод электроники] → Электроника (20)
+       Время: 20 тиков
+```
+
+### 🚗 Автомобили
+
+```
+Шаг 1: Сталь (100) → [Сталелитейный завод] → Металлоизделия (80)
+       Время: 20 тиков
+
+Шаг 2: Металлоизделия (80) + Пластик (40) → [Автозавод] → Автомобили (5)
+       Время: 50 тиков
+```
+
+---
+
+## Примеры использования
+
+### Создание конфигурации цепочки
+
+```csharp
+var breadChain = new ProductionChainConfig
+{
+    Id = "chain_bread",
+    Name = "Производство хлеба",
+    OutputProductId = "goods_food",
+    OutputQuantity = 80,
+    RequiredBuildingId = "food_factory",
+    Steps = new List<ProductionStep>
+    {
+        new ProductionStep
+        {
+            InputProductId = "raw_food",
+            InputQuantity = 100,
+            ProductionTime = 5
+        }
+    },
+    AvailableFromYear = 1900
+};
+```
+
+### Запуск производства
+
+```csharp
+var factory = new Building
+{
+    TypeConfig = foodFactoryConfig,
+    Workers = 50
+};
+
+var production = new ActiveProductionChain
+{
+    Config = breadChain,
+    Building = factory,
+    IsActive = true,
+    StartedAtTick = 0
+};
+
+// Каждый тик:
+production.Tick();
+
+if (production.IsComplete)
+{
+    // Производство завершено, забрать продукт
+    var output = production.Config.OutputProductId;
+    var quantity = production.Config.OutputQuantity;
+}
+```
+
+### Отслеживание прогресса
+
+```csharp
+if (production.IsStepComplete)
+{
+    // Шаг завершён, можно забирать промежуточный продукт
+    var step = production.Config.Steps[production.CurrentStep];
+    // ...
+}
+
+Console.WriteLine(
+    $"Прогресс: {production.CurrentStep + 1}/{production.Config.Steps.Count} " +
+    $"({production.Progress}/{production.Config.Steps[production.CurrentStep].ProductionTime} тиков)"
+);
+```
+
+---
+
+## Связанные документы
+
+- [Продукты](products.md) — входные и выходные продукты
+- [Здания](buildings.md) — где происходит производство
+- [Ядро](core.md) — базовые классы
+
+---
+
+**Последнее обновление:** 20.02.2026
--- a/docs/tech/products.md
+++ b/docs/tech/products.md
@@ -0,0 +1,235 @@
+# Продукты (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