Add microservices, web UI, and replay tooling

README.md

@@ -0,0 +1,140 @@
+# Settlers of Catan in Python
+
+Полная реализация «Колонизаторов» (Catan) на Python: ядро движка со всеми правилами базовой версии, SDK для обучения моделей, CLI для аналитики и GUI для ручной игры.
+
+## Возможности
+
+- Полный набор правил: генерация поля, стартовые постройки в два раунда, добыча ресурсов, разбойник, торговля, развитие, карты развития, «Самая длинная дорога» и «Самая большая армия».
+- Модели гекс/вершин/ребер в виде графа с проверками расстояния и связности.
+- SDK (`catan.sdk.CatanEnv`) c перечислением допустимых действий и API, похожим на gym.
+- CLI на Typer + Rich для пошаговых партий и дебага.
+- GUI на Tkinter с визуализацией гексов, дорог и построек.
+- ML-модуль с кодировщиками состояний/действий, случайным агентом, REINFORCE-тренером (PyTorch) и эволюционной стратегией.
+
+## Установка
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## CLI
+
+Запуск новой партии для трёх игроков:
+
+```bash
+catan-cli "Alice,Bob,Carla"
+```
+
+Основные команды в интерактивном режиме:
+
+- `state`, `board`, `corners`, `edges` — вывод состояния.
+- `actions` — список допустимых действий из текущего состояния (на базе SDK).
+- `roll`, `place <corner> <road>`, `build settlement|city|road <id>` — действия на поле.
+- `buy dev`, `play knight|road|yop|monopoly`, `trade bank ...`, `trade player ...`.
+- `move robber <hex> [victim]`, `discard <player> <resource> <amount> ...`, `end` для завершения хода.
+- `--random-bot <имя>` — назначает игрока случайному агенту (можно указать несколько флагов) для режимов «человек против случайной модели».
+
+Пример игры против случайного соперника:
+
+```bash
+catan-cli "You,Bot" --random-bot Bot
+```
+
+## GUI
+
+```
+catan-gui --players "Alice,Bob,Carla" --seed 42
+```
+
+На панели справа расположены кнопки для всех правил: бросок кубиков, строительство, обмены, карты развития, перемещение разбойника и т.д. При необходимости вводов появляются диалоговые окна. Внизу лог событий, на канвасе отображаются гексы, дороги и постройки.
+
+## SDK / Использование в обучении
+
+```python
+from catan import GameConfig
+from catan.sdk import CatanEnv, Action, ActionType
+
+config = GameConfig(player_names=["Alice", "Bob", "Carla"], seed=123)
+env = CatanEnv(config)
+obs = env.reset()
+
+for step in range(10):
+    legal = env.legal_actions()
+    action = next(a for a in legal if a.type == ActionType.ROLL)
+    obs, reward, done, info = env.step(action)
+    if done:
+        break
+```
+
+`legal_actions()` возвращает список `Action`, содержащих тип действия и полезные параметры (например, доступные гексы для разбойника или список ребер для дороги). `env.step()` применяет действие к текущему `Game`, возвращает новое наблюдение, награду (дельта очков) и флаг завершения партии.
+
+## Структура проекта
+
+- `catan/data.py` — перечисления и константы (ресурсы, карты, порты, стоимости).
+- `catan/board.py` — генерация поля, гексов, перекрестков и портов.
+- `catan/player.py` — модель игрока и операции с ресурсами.
+- `catan/game.py` — движок игры, правила, учет победных очков.
+- `catan/sdk.py` — окружение для обучения / автоматизации.
+- `catan/cli.py` и `catan/gui.py` — интерфейсы для людей (CLI поддерживает ботов).
+- `catan/ml/` — агенты, кодировщики, обучающие циклы RL/эволюции.
+- `catan/learning.py` — CLI-утилиты для запуска reinforcement learning (REINFORCE).
+
+## Reinforcement Learning
+
+```bash
+catan-learn reinforce --players "Alpha,Beta,Gamma,Delta" --episodes 100 --output policy.pt
+```
+
+По окончании обучения выводится история наград; при указании `--output` сохраняется `state_dict` PyTorch.
+
+## Web платформа (микросервисы)
+
+Монорепозиторий содержит backend-сервисы и веб-интерфейс:
+
+- `services/api` — gateway + auth + websockets.
+- `services/game` — игровой сервер (правила + состояния + трейды).
+- `services/ai` — инференс моделей (random / .pt).
+- `services/analytics` — статистика, реплеи, экспорт/импорт.
+- `web` — React-интерфейс (лобби, партии, реплеи).
+
+### Запуск в Docker
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+По умолчанию UI доступен на `http://localhost` (если проксировать через Caddy), а API — на `/api`.
+
+### Caddy (пример)
+
+```
+catan.danosito.com {
+  reverse_proxy /api/* api:8000
+  reverse_proxy /ws/* api:8000
+  reverse_proxy web:80
+}
+```
+
+### Реплеи
+
+- Экспорт: `/api/replays/{id}/export` (JSON).
+- Импорт: `/api/replays/import` (JSON).
+- В UI доступны импорт/экспорт и пошаговый просмотр.
+
+## Тестирование
+
+Минимальная проверка:
+
+```bash
+python -m catan.cli "Alice,Bob,Carla"
+python -m catan.gui --players "Alice,Bob,Carla"
+```
+
+Авто-тесты:
+
+```bash
+pytest
+```