79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Архитектура сервера симуляции (Village Sim)
|
||
|
||
## 1. Технический стек
|
||
|
||
### Phase 1 (MVP)
|
||
* **Core**: Python 3.11+
|
||
* **API**: FastAPI
|
||
* **Hot State / Broker**: Redis (используется и как БД, и как очередь сообщений)
|
||
* **Analytics**: JSON Logs (файловая система)
|
||
|
||
### Phase 2 (Target Production)
|
||
* **Analytics**: **ClickHouse**. Для хранения логов каждого хода (Time-Series) и ML-обучения.
|
||
* **Broker**: **RabbitMQ / Kafka**. Для связи с внешними микросервисами (Внешняя торговля, Auth).
|
||
* **Metrics**: Prometheus + Grafana.
|
||
|
||
## 2. Принципы проектирования (Clean Architecture)
|
||
|
||
Чтобы легко перейти от Phase 1 к Phase 2, жестко соблюдаем слои:
|
||
|
||
1. **Domain Layer (Core)**: *Чистый Python.*
|
||
* Бизнес-правила (Entity, Value Objects).
|
||
* Никаких зависимостей от внешних библиотек.
|
||
2. **Application Layer (Services)**: *Оркестрация.*
|
||
* Use Cases ("Сделать ход", "Создать игру").
|
||
* Работает с интерфейсами (`IEventBus`, `IRepository`), а не конкретными БД.
|
||
3. **Infrastructure Layer (Adapters)**: *Грязная реализация.*
|
||
* Здесь лежат драйверы Redis, ClickHouse, RabbitMQ.
|
||
* Именно этот слой мы будем менять при масштабировании.
|
||
|
||
## 3. Компоненты системы
|
||
|
||
### 4.1. API Gateway (FastAPI)
|
||
* Входная точка для клиентов.
|
||
* Конвертирует HTTP запросы в `Commands`.
|
||
|
||
### 4.2. Game Engine (Domain)
|
||
* **TimeSystem**: Абстракция времени.
|
||
* **EntityManager**: ECS-структура.
|
||
* **MarketCore**: Логика сведения ордеров.
|
||
|
||
### 4.3. Infrastructure Adapters
|
||
* **RedisGameRepository**: Реализация `IGameRepository`.
|
||
* **RedisEventBus**: Реализация `IEventBus` (в Phase 2 заменим на `KafkaEventBus`).
|
||
* **FileAnalyticsRepository**: Реализация `IAnalyticsRepository` (в Phase 2 заменим на `ClickhouseRepository`).
|
||
|
||
## 5. Поток данных (Data Flow)
|
||
|
||
1. **Action**: Клиент шлет `POST /action`.
|
||
2. **Bus**: API кладет команду в `IEventBus` (Redis).
|
||
3. **Worker**:
|
||
* Поднимает состояние из `IGameRepository`.
|
||
* Применяет логику Домена.
|
||
* Генерирует события (`FoodEaten`, `ItemCrafted`).
|
||
4. **Analytics**: События асинхронно пишутся в `IAnalyticsRepository` (ClickHouse/Files).
|
||
|
||
## 6. Структура проекта
|
||
|
||
```text
|
||
/app
|
||
/domain # ЧИСТАЯ ЛОГИКА
|
||
/entities # Agent, Resource
|
||
/interfaces # Абстракции: IGameRepository, IEventBus, IAnalytics
|
||
/events # Domain Events
|
||
|
||
/application # СЦЕНАРИИ
|
||
/commands # DTO
|
||
/use_cases # GameLoopService
|
||
|
||
/infrastructure # РЕАЛИЗАЦИЯ
|
||
/redis # RedisRepo, RedisBus
|
||
/clickhouse # (Заготовка) ClickhouseAnalytics
|
||
/fs # FileAnalytics
|
||
|
||
/web # API
|
||
/api # Routes
|
||
|
||
main.py # Dependency Injection Container
|
||
```
|