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/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