Add technical documentation structure
This commit is contained in:
sokol
46
docs/tech/README.md
Normal file
46
docs/tech/README.md
Normal file
@@ -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
|
||||||
196
docs/tech/buildings.md
Normal file
196
docs/tech/buildings.md
Normal file
@@ -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
|
||||||
165
docs/tech/core.md
Normal file
165
docs/tech/core.md
Normal file
@@ -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
|
||||||
220
docs/tech/production.md
Normal file
220
docs/tech/production.md
Normal file
@@ -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
|
||||||
235
docs/tech/products.md
Normal file
235
docs/tech/products.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user