Remove outdated architecture documentation and add a new simplified architecture document for Village Sim, detailing the client-server model, backend and frontend structures, data flow, and technology stack.
This commit is contained in:
elit3guzhva
parent
0720dde31f
commit
59ac1133ce
@ -1,78 +0,0 @@
|
|||||||
# Архитектура сервера симуляции (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
|
|
||||||
```
|
|
||||||
121
docs/design/simple-architecture.md
Normal file
121
docs/design/simple-architecture.md
Normal file
@ -0,0 +1,121 @@
|
|||||||
|
# Simple Village Simulation Architecture (MVP)
|
||||||
|
|
||||||
|
This document outlines the architecture for the Village Simulation based on [Village TZ v2](./village-tz-v2.md). The system follows a client-server model to ensure strict separation between the simulation logic (Backend) and the visualization (Frontend).
|
||||||
|
|
||||||
|
## 1. System Overview
|
||||||
|
|
||||||
|
The system consists of two distinct applications communicating via HTTP (REST API):
|
||||||
|
1. **Backend (Server)**: Responsible for the entire simulation state, economic logic, AI decision-making, and turn management.
|
||||||
|
2. **Frontend (Client)**: A "dumb" terminal using **Pygame** that queries the current state to render it and sends user commands (if any) to the server.
|
||||||
|
|
||||||
|
This separation allows replacing the Pygame frontend with Web (React/Vue) or Unity in the future without changing the backend logic.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Backend Architecture (Python)
|
||||||
|
|
||||||
|
We adhere to a simplified **Clean Architecture** to keep business logic isolated from the API framework.
|
||||||
|
|
||||||
|
### 2.1. Layered Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
backend/
|
||||||
|
├── main.py # Entry point, API configuration
|
||||||
|
├── api/ # Interface Layer (FastAPI)
|
||||||
|
│ ├── routes.py # Endpoints (GET /state, POST /next_turn)
|
||||||
|
│ └── schemas.py # Pydantic models for request/response
|
||||||
|
├── core/ # Business Logic Layer (The "Brain")
|
||||||
|
│ ├── engine.py # Game Loop manager (Day/Night cycle)
|
||||||
|
│ ├── world.py # Container for all entities
|
||||||
|
│ └── market.py # Order Book matching logic
|
||||||
|
└── domain/ # Data Models (Pure Python)
|
||||||
|
├── agent.py # Agent logic (stats, inventory, survival rules)
|
||||||
|
├── resources.py # Resource definitions (Meat, Wood, etc.)
|
||||||
|
└── action.py # Action definitions (Hunt, Sleep, Trade)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2. Key Components
|
||||||
|
|
||||||
|
1. **Domain Models (`domain/`)**:
|
||||||
|
* `Agent`: Stores state (Energy, Hunger, Money, Inventory). Contains methods like `eat()`, `work()`, but does *not* know about the game loop.
|
||||||
|
* `Resource`: Enum or classes defining resource properties (decay rate, base value).
|
||||||
|
|
||||||
|
2. **Core Engine (`core/`)**:
|
||||||
|
* `GameEngine`: Singleton that holds the `World` state.
|
||||||
|
* **Turn Processing**:
|
||||||
|
* The simulation is **Turn-Based**.
|
||||||
|
* The Engine waits for a "Next Turn" signal (or runs on a timer).
|
||||||
|
* Processing order: `Collect Actions` -> `Resolve Market` -> `Update Agent Stats` -> `Remove Dead Agents`.
|
||||||
|
|
||||||
|
3. **API (`api/`)**:
|
||||||
|
* **`GET /state`**: Returns the full snapshot of the world (Agents, Market Order Book, Global Stats) in JSON format.
|
||||||
|
* **`POST /control/next_step`**: Forces the simulation to advance one tick (useful for debugging/manual control).
|
||||||
|
* **`POST /market/order`**: (Optional) Allows manual intervention to place orders.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Frontend Architecture (Pygame)
|
||||||
|
|
||||||
|
The frontend acts as a **Visualizer**. It does not calculate simulation logic.
|
||||||
|
|
||||||
|
### 3.1. Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
frontend/
|
||||||
|
├── main.py # Pygame Game Loop
|
||||||
|
├── client.py # Network Client (requests lib)
|
||||||
|
├── assets/ # Sprites/Fonts
|
||||||
|
└── renderer/ # Drawing Logic
|
||||||
|
├── map_renderer.py # Draws the grid/terrain
|
||||||
|
├── agent_renderer.py # Draws agents and their status bars
|
||||||
|
└── ui_renderer.py # Draws text info (Market prices, Day/Night)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2. Flow
|
||||||
|
|
||||||
|
1. **Network Step**:
|
||||||
|
* Call `GET http://localhost:8000/state`.
|
||||||
|
* Receive JSON: `{"turn": 5, "time_of_day": "day", "agents": [...], "market": [...]}`.
|
||||||
|
2. **Update Step**:
|
||||||
|
* Parse JSON into local simplified objects.
|
||||||
|
3. **Draw Step**:
|
||||||
|
* Clear screen.
|
||||||
|
* Render Agents at their coordinates.
|
||||||
|
* Render UI overlays (e.g., "Day 1, Step 5", "Total Coins: 500").
|
||||||
|
* `pygame.display.flip()`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Data Flow & Synchronization
|
||||||
|
|
||||||
|
Since the simulation involves AI agents acting autonomously, the Frontend is primarily an **Observer**.
|
||||||
|
|
||||||
|
1. **Initialization**: Server starts, generates N agents.
|
||||||
|
2. **Loop**:
|
||||||
|
* Server calculates the turn results (AI decisions -> Outcomes).
|
||||||
|
* Frontend polls `/state` every X milliseconds (or every frame).
|
||||||
|
* Frontend updates the screen.
|
||||||
|
|
||||||
|
### 4.1. The "God Mode" Problem
|
||||||
|
To test the simulation efficiently, the Server will expose a **Simulation Controller**:
|
||||||
|
* **Manual Mode**: The server waits for a `POST /next_step` call to advance. The User presses `SPACE` in Pygame -> Pygame sends request -> Server updates -> Pygame fetches new state.
|
||||||
|
* **Auto Mode**: Server runs a background thread updating every N seconds. Frontend just polls.
|
||||||
|
|
||||||
|
*Recommended for MVP: Manual Mode (Spacebar to advance turn).*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Technology Stack
|
||||||
|
|
||||||
|
* **Language**: Python 3.11+
|
||||||
|
* **Backend Framework**: FastAPI (for speed and auto-generated docs).
|
||||||
|
* **Data Validation**: Pydantic.
|
||||||
|
* **Frontend**: Pygame Community Edition (pygame-ce).
|
||||||
|
* **Communication**: HTTP (Requests/Uvicorn).
|
||||||
|
|
||||||
|
## 6. Future Extensibility (Why this architecture?)
|
||||||
|
|
||||||
|
* **Switch to Web**: Replace `frontend/` folder with a React app. The React app simply calls the same `GET /state` endpoint.
|
||||||
|
* **Switch to Unity**: Unity `UnityWebRequest` calls `GET /state`.
|
||||||
|
* **Database**: Currently state is in-memory (`core/engine.py`). Easy to swap for SQLite/Postgres later by adding a `repository` layer in Backend.
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user