chore(docs & backup): update documentation to v3.0, add database backup script and update gitignore

2026-09-22 09:25:27 +00:00
parent 50eadb4b5e
commit 6129ed26f0
5 changed files with 460 additions and 68 deletions
@@ -1,62 +1,117 @@
-# 🌻 Plants vs. Zombies — Web Edition
+# 🌻 Plants vs. Zombies — Web Edition (v3.0)

-Полноценная браузерная реализация культовой игры **Plants vs. Zombies** на чистом HTML5 Canvas и Web Audio API (0 внешних JS-фреймворков и библиотек) с серверной частью на Python и SQLite.
+Полноценная браузерная реализация культовой игры **Plants vs. Zombies** на чистом HTML5 Canvas и Web Audio API (0 внешних JS-фреймворков и библиотек) с серверной частью на Python, базой данных SQLite, визуальным конфигуратором уровней, автоматическим бэкапом и тестовым покрытием **404/404 тестов (100% PASS)**.

 ---

-## 🎮 Особенности игры
+## 🎮 Особенности и игровые механики

- **5 Биомов газона:**
-  - ☀️ **День** (Day) — классический газон с падающим солнцем.
-  - 🌙 **Ночь** (Night) — отсутствие солнца с неба, грибы и могилы.
-  - 🏊 **Бассейн** (Pool) — 6 линий, водные дорожки, кувшинки.
-  - 🌫️ **Туман** (Fog) — ночной бассейн со сложной видимостью.
-  - 🏠 **Крыша** (Roof) — наклонные скаты, цветочные горшки и катапульты.
+### 🌿 5 Биомов газона
+- ☀️ **День (Day)** — классический газон с падающим с неба солнцем (уровни 1-1 .. 1-5).
+- 🌙 **Ночь (Night)** — темнота, отсутствие небесного солнца, грибная экономика, могилы и растение Могилоед (уровни 2-1 .. 2-5).
+- 🏊 **Бассейн (Pool)** — 6 дорожек газона, две центральные линии с водой, кувшинки и очистители бассейна (уровни 3-1 .. 3-5).
+- 🌫️ **Туман (Fog)** — ночной бассейн с густым туманом, скрывающим правую половину поля, плантернами и воздуходувами (уровни 4-1 .. 4-5).
+- 🏠 **Крыша (Roof)** — наклонный черепичный скат, цветочные горшки, капусто- и арбузопульты (уровни 5-1 .. 5-5).

- **Режимы игры:**
-  - 🌿 **Кампания (Приключение):** 25 уровней с прогрессией и наградами.
-  - ⚔️ **Выживание (Survival):** бесконечные флаги с нарастающей сложностью.
-  - 🎳 **Боулинг (Wall-nut Bowling):** мини-игра с конвейерной подачей орехов.
-  - 🧠 **Я, Зомби (I, Zombie):** игра за сторону зомби против обороны растений.
-  - 🎲 **Садовый Рогалик (Roguelike):** драфт реликвий, случайные этажи и баффы.
-  - 👑 **Битва с Боссом & Boss Rush:** доктор Зомбосс на боевом роботе Зомботе.
+### ⚔️ Режимы игры
+- 🌿 **Кампания (Приключение):** 25 сюжетных уровней с прогрессией, наградами и кат-сценами с репликами Безумного Дэйва.
+- ⚔️ **Выживание (Survival):** бесконечные волны зомби с флагами и нарастающей интенсивностью.
+- 🎳 **Боулинг (Wall-nut Bowling):** конвейерная подача катящихся орехов и взрывных вишен с рикошетом по диагоналям.
+- 🧠 **Я, Зомби (I, Zombie):** игра за сторону зомби против оборонительных линий растений с добычей мозгов.
+- 🎲 **Садовый Рогалик (Garden Roguelike):** драфт случайных семян и реликвий после каждой волны (молнии, яд, вампиризм).
+- 👑 **Битва с Боссом & Boss Rush:** доктор Эдгар Зомбосс на гигантском шагающем боевом роботе Зомботе.

- **Пассивные механики и прокачка:**
-  - 🧪 **Сад-Мастерская:** 3-уровневая прокачка растений и 5 пассивных перков.
-  - 🪴 **Дзен-Сад:** выращивание ростков, сбор монет и улитка Стинки.
-  - 📖 **Пригородный Альманах:** справочник всех 13 растений и 8 зомби.
-  - 🏆 **Зал Достижений:** система трофеев и наград.
-  - 🌳 **Древо Мудрости:** прокачка высоты и открытие скрытых чит-кодов.
-  - 🎨 **Темы оформления:** Классическая, Киберпанк, Ретро 8-bit, Зима.
+### 🎰 Казино и Банк Безумного Дэйва ([`casino.js`](file:///home/kopri/agy/game/js/systems/casino.js))
+- **Слот-машина:** 7 уникальных барабанных символов (🌻 Подсолнух x4, 🟢 Горох x8, 🌰 Орех x12, 🍒 Вишня x25, 💎 Алмаз x60 + кристаллы, 7️⃣ Семёрка x200 + 5 кристаллов, 🧠 Зомби-мозги).
+- **Банковские депозиты:** надежное хранение монет с начислением **5% в час** сложного процента (до 48 часов пассивного дохода).
+- **Срочные займы:** кредитная линия Безумного Дэйва до 2500 монет с фиксированной 10% комиссией для быстрого старта.

- **Серверная часть и профили:**
-  - 👤 **Система аккаунтов и гостевой режим** (SQLite + REST API).
-  - 💾 **Автоматическая синхронизация сохранений** и прогресса на сервере.
-  - 🐛 **Интегрированная система баг-репортов** и обратной связи.
-  - 📱 **PWA:** поддержка автономной игры (Offline Service Worker).
+### 🧪 Лаборатория Мутаций Зомби ([`zombielab.js`](file:///home/kopri/agy/game/js/systems/zombielab.js))
+Глубокая 3-уровневая система мутаций для режима «Я, Зомби» с расходом монет, био-гумуса, шестеренок и кристаллов:
+- **Обычный зомби:** Базовый ходок ➔ Спринтер (+35% скорости) ➔ Зомби-Вампир (+45 HP за укус).
+- **Зомби с конусом:** Дорожный конус ➔ Титановый конус (800 HP) ➔ Шипованный шлем (отражает 25% урона стрелкам).
+- **Зомби с шестом:** Легкоатлет ➔ Двойной шест (перепрыгивает 2 растения подряд) ➔ Турбо-спринтер (+50% скорости после приземления).
+- **Зомби с ведром:** Стальное ведро ➔ Тяжелый сплав (1800 HP) ➔ Крио-изоляция (2300 HP + иммунитет к заморозке).
+- **Зомби-футболист:** Квотербек ➔ Тяжелый лайнмен (поглощение 20% урона) ➔ Безумный таран (2800 HP, сминает картофельную мину без взрыва).
+
+### 🛠️ Панель Администратора и Конфигуратор ([`game/configurator/`](file:///home/kopri/agy/game/configurator/index.html))
+Полнофункциональный Cyberpunk Botanical веб-интерфейс администратора:
+- **Визуальный редактор 25 уровней кампании:** редактирование волн зомби, наград, биомов, модификаторов и диалогов Безумного Дэйва с мгновенным сохранением в базу данных.
+- **Динамический баланс игры в реальном времени ([`config.js`](file:///home/kopri/agy/game/js/systems/config.js)):** множители солнца, монет, здоровья и урона зомби/растений, готовые пресеты (*Classic 2009*, *Hardcore*, *Turbo*, *Casual*, *Custom*).
+- **Управление игроками:** просмотр, создание, редактирование монет, уровней и ресурсов, сброс паролей, блокировка/разблокировка с указанием причины.
+- **Менеджер активных сессий:** онлайн-мониторинг токенов игроков, IP-адресов, браузеров/устройств и принудительный отзыв сессий.
+- **Журнал аудита входов (`login_logs`):** детализированная история авторизаций, статусы успехов и сработок rate-limit защиты.
+- **Управление безопасностью:** смена мастер-пароля администратора с PBKDF2-SHA256 хешированием.
+
+### 💾 Автоматический бэкап и ротация базы данных ([`backup_db.py`](file:///home/kopri/agy/scripts/backup_db.py))
+- Горячее неблокирующее копирование через online SQLite Backup API.
+- Именование снимков по стандарту: `backups/pvz_YYYYMMDD_HHMMSS.db`.
+- Автоматическая ротация (pruning) устаревших копий с сохранением последних 7 снимков.
+
+### 🕹️ Классический DOOM Web Edition ([`game/doom/`](file:///home/kopri/agy/game/doom/index.html))
+- Встроенная пасхалка и отдельный полноценный 3D WebGL ретро-шутер.
+- Аутентичный HUD оригинального DOOM: шкалы AMMO, HEALTH, ARMOR, матрица оружия (1-7) и анимированное лицо Doomguy.
+- CRT-сканлайны, динамические вспышки урона и олдскульная эстетика.
+
+### 🪴 Пассивная прогрессия и кастомизация
+- **Сад-Мастерская:** 3 уровня прокачки каждого растения и 5 пассивных перков садовника (магнетизм, стартовое солнце и др.).
+- **Дзен-Сад:** полив ростков, сбор пассивного дохода и улитка Стинки под шоколадом.
+- **Пригородный Альманах:** иллюстрированная энциклопедия всех растений и зомби, включая скрытого Зомби-Йети.
+- **Система достижений:** 30+ уникальных трофеев и наград.
+- **Древо Мудрости:** выращивание древа и активация клавиатурных чит-кодов (`mustache`, `future`, `dance`, `pinata`).
+- **Темы оформления:** Классическая, Киберпанк, Ретро 8-bit, Зима.

 ---

 ## 📁 Структура проекта

 ```text
-├── game/                    # Frontend игры
-│   ├── index.html           # Главный HTML-документ
-│   ├── css/style.css        # Стили и адаптивный UI
-│   ├── js/
-│   │   ├── main.js          # Точка входа
-│   │   ├── game.js          # Игровой движок (GameEngine)
-│   │   ├── entities/        # Сущности (растения, зомби, снаряды)
-│   │   ├── systems/         # Игровые системы (экономика, волны, комбат, сад и т.д.)
-│   │   └── utils/           # Аудио, тест-API, спрайты
-│   └── manifest.json        # PWA манифест
-├── scripts/                 # Backend & скрипты
-│   ├── feedback_server.py   # HTTP REST сервер (Auth & Bug Reports)
-│   ├── db.py                # Менеджер SQLite базы данных
-│   └── test_game.py         # Автономный тест-раннер (235+ тестов)
-├── nginx/                   # Конфигурации Nginx
-├── docker-compose.yml       # Развертывание Nginx в Docker
-└── .env.example             # Пример переменных окружения
+/home/kopri/agy/
+├── data/
+│   └── pvz.db                     # Основная база данных SQLite (WAL-режим)
+├── backups/                       # Каталог резервных копий базы данных (*.db)
+├── game/                          # Frontend игры (HTML5 Canvas / SPA / PWA)
+│   ├── index.html                 # Главный экран игры и модальные окна
+│   ├── manifest.json              # PWA манифест
+│   ├── sw.js                      # Offline Service Worker кэш
+│   ├── configurator/              # Панель администратора и редактор уровней
+│   │   ├── index.html             # UI панели конфигуратора
+│   │   ├── css/style.css          # Стили Cyberpunk Botanical
+│   │   └── js/configurator.js     # Клиентское SPA конфигуратора
+│   ├── doom/                      # Классический DOOM Web Edition
+│   │   ├── index.html             # 3D WebGL канвас и аутентичный HUD
+│   │   ├── css/style.css          # Ретро CRT-стили
+│   │   └── js/                    # Движок DOOM и рендерер
+│   ├── css/style.css              # Стили основной игры
+│   └── js/
+│       ├── main.js                # Точка инициализации
+│       ├── game.js                # Игровой цикл и рендерер (GameEngine)
+│       ├── entities/              # Сущности (Plant, Zombie, Projectile, LawnCleaner)
+│       ├── systems/               # Игровые подсистемы:
+│       │   ├── auth.js            # Авторизация (PvZAuth), сессии и синхронизация
+│       │   ├── config.js          # Динамический баланс и пресеты (PvZConfig)
+│       │   ├── campaign.js        # Движок кампании (25 уровней) и диалоги Дэйва
+│       │   ├── casino.js          # Казино и Банк Безумного Дэйва (слоты, вклады)
+│       │   ├── zombielab.js       # Лаборатория мутаций зомби (3 тира)
+│       │   ├── combat.js          # Физика снарядов, коллизии и урон
+│       │   ├── economy.js         # Экономика солнца/монет и магазин
+│       │   ├── workshop.js        # Сад-мастерская, крафт и перки
+│       │   ├── zengarden.js       # Дзен-сад и улитка Стинки
+│       │   ├── boss.js            # Доктор Зомбосс и робот Zombot
+│       │   ├── roguelike.js       # Садовый Рогалик и драфт реликвий
+│       │   ├── tree.js            # Древо Мудрости и чит-коды
+│       │   ├── achievements.js    # 30+ игровых достижений
+│       │   ├── leaderboard.js     # Глобальные таблицы лидеров
+│       │   └── feedback.js        # Клиент отправки баг-репортов
+│       └── utils/                 # Web Audio API, генератор звуков, Test API
+├── scripts/                       # Backend и серверные утилиты
+│   ├── feedback_server.py         # HTTP REST API сервер (Auth, Config, Admin, Leaderboard)
+│   ├── db.py                      # Менеджер SQLite (схемы, миграции, PBKDF2)
+│   ├── backup_db.py               # Автоматический бэкап и ротация SQLite базы
+│   ├── manage_users.py            # CLI управление игроками
+│   └── test_game.py               # Автономный тест-раннер (404 теста)
+├── nginx/                         # Конфигурации Nginx с SSL и Reverse-Proxy
+└── docker-compose.yml             # Docker-compose стек
 ```

 ---
@@ -65,18 +120,42 @@

 ### Требования
 - Python 3.10+
- Nginx / Docker (опционально)
+- Современный веб-браузер с поддержкой HTML5 Canvas и Web Audio API
+- Nginx / Docker (для продакшн развертывания с SSL)

-### Запуск бэкенда
+### 1. Запуск серверного бэкенда
 ```bash
 python3 scripts/feedback_server.py
 ```
-Сервер запустится на порту `8001` и автоматически создаст базу данных `data/pvz.db`.
+Сервер запустится на порту `8001`, инициализирует базу данных `data/pvz.db`, применит миграции и дефолтные пресеты баланса.

-### Запуск тестов
+### 2. Запуск резервного копирования базы данных
+```bash
+# Создание моментального online-бэкапа с сохранением последних 7 копий:
+python3 scripts/backup_db.py
+
+# Кастомный путь и количество сохраняемых снимков:
+python3 scripts/backup_db.py --keep 14 --dir /home/kopri/agy/backups
+```
+
+### 3. Запуск комплексного тестового набора
 ```bash
 python3 scripts/test_game.py
 ```
+Запускает полный цикл верификации из **404 тестов**, включая проверку HTTP/2, статики, движка Canvas, REST эндпоинтов, админ-панели и механик боя:
+```text
+==================================================
+TEST SUMMARY: 404/404 PASSED (0 FAILED)
+==================================================
+```
+
+---
+
+## 🛡️ Безопасность и администрирование
+- **Пароли:** Хеширование через `PBKDF2-HMAC-SHA256` (100,000 итераций) со случайной криптографической солью.
+- **Защита от перебора:** Встроенный Rate-Limiting по IP-адресам на эндпоинтах авторизации с логгированием инцидентов в `login_logs`.
+- **Сессии:** Токены `secrets.token_hex(32)` со сроком жизни, привязкой к устройству и возможностью принудительного отзыва администратором.
+- **Вход в конфигуратор:** Доступен по адресу `https://<domain>/configurator/` по мастер-паролю администратора.

 ---