493 lines
39 KiB
Markdown
493 lines
39 KiB
Markdown
## Введение
|
||
|
||
**Sunrise Station** — это крупный форк и серверная сборка игры Space Station 14, вдохновлённой культовой Space Station 13. Проект развивается как открытое сообщество, ориентированное на создание глубокой, хаотичной и весёлой ролевой среды в научно-фантастическом сеттинге космической станции. Данный документ предназначен для использования ИИ-агентами, осуществляющими автоматическую проверку пулл-реквестов (PR) и предоставляющими рекомендации по улучшению кода и контента. GDD структурирован так, чтобы обеспечить чёткие критерии оценки изменений, облегчить автоматизацию ревью и поддерживать высокое качество проекта.
|
||
|
||
---
|
||
|
||
## 1. Цели проекта
|
||
|
||
### 1.1 Основные задачи
|
||
|
||
- **Создание уникального игрового опыта**: развитие форка SS14 с акцентом на глубокую механику, ролевое взаимодействие и разнообразие сценариев.
|
||
- **Поддержка и развитие сообщества**: обеспечение открытости кода, прозрачности процессов и вовлечения новых участников.
|
||
- **Совместимость с upstream**: регулярная синхронизация с основным репозиторием Space Wizards Federation для получения обновлений и исправлений.
|
||
- **Высокое качество кода и контента**: внедрение строгих стандартов, автоматических тестов и CI/CD для предотвращения деградации качества.
|
||
- **Масштабируемость и модульность**: архитектура, позволяющая легко добавлять новые механики, карты, ассеты и сценарии.
|
||
|
||
### 1.2 Ключевые игровые цели
|
||
|
||
- **Постройка и поддержка функционирующей станции** с множеством отделов (инженерный, научный, медицинский, служба безопасности и др.).
|
||
- **Выполнение сменных задач**: от строительства шаттлов и генераторов до исследования артефактов и обеспечения выживания экипажа.
|
||
- **Ролевое взаимодействие**: поддержка сложных сценариев, антагонистов, событий и уникальных профессий.
|
||
|
||
---
|
||
|
||
## 2. Основные игровые механики
|
||
|
||
### 2.1 Обзор
|
||
|
||
Sunrise Station реализует широкий спектр механик, охватывающих симуляцию физиологии персонажей, взаимодействие с окружением, управление станцией и социальные аспекты. Особое внимание уделяется глубине и взаимосвязанности систем, что обеспечивает богатый игровой опыт.
|
||
|
||
### 2.2 Подсистемы физиологии
|
||
|
||
#### 2.2.1 Здоровье
|
||
|
||
- **Показатель здоровья** отражает степень ранения персонажа. Диапазон от 0 (здоров) до 200+ (смерть).
|
||
- **Типы урона**: механический (удары, порезы, уколы), термический, электрический, токсический, генетический, удушье, кровотечение, структурный, взрывной, стаминный.
|
||
- **Кровотечение**: отдельная шкала, зависящая от типа урона. Максимум — 10 единиц, влияет на потерю крови и состояние персонажа.
|
||
- **Регенерация**: при уроне <20 — восстановление по 0,07 механического и ожогового урона в секунду.
|
||
- **Модификаторы**: при 60+ урона — замедление, при 100+ — критическое состояние, пассивный урон.
|
||
|
||
#### 2.2.2 Выносливость
|
||
|
||
- **Базовое значение** — 100 единиц.
|
||
- **Урон по выносливости**: при 50+ — замедление на 80% (3 сек), при 100+ — падение (6 сек).
|
||
- **Регенерация**: 3 единицы в секунду, если не получал урон по выносливости 3 сек.
|
||
- **Влияние веществ**: стимуляторы, дезоксиэфедрин, эфедрин изменяют длительность оглушения и максимальную выносливость.
|
||
|
||
#### 2.2.3 Голод и жажда
|
||
|
||
- **Голод**: шкала сытости (0–200), влияет на скорость переваривания, замедление при сильном голоде.
|
||
- **Жажда**: шкала насыщения (0–150), влияет на скорость обработки жидкости и замедление.
|
||
- **Вещества**: витамины, протеин, другие реагенты оказывают различные эффекты на организм.
|
||
|
||
#### 2.2.4 Дыхание
|
||
|
||
- **Потребность в газе**: разные расы требуют кислород или азот, отсутствие — урон удушьем.
|
||
- **Таблица соответствия**: для каждой расы указан тип газа и урон при его отсутствии.
|
||
|
||
#### 2.2.5 Защита
|
||
|
||
- **Броня и скафандры**: уменьшают урон определённых типов по формуле: `Урон - Урон * защита% = итоговый урон`.
|
||
- **Взрывной урон**: игнорирует большинство видов защиты, кроме специальной.
|
||
|
||
### 2.3 Архитектура станции и карты
|
||
|
||
- **Станции определяются YAML-прототипами**, включающими метаданные, компоненты, распределение профессий, параметры биома и освещения.
|
||
- **Биомы**: задают визуальные и геймплейные эффекты (цвет освещения, параллакс, атмосфера).
|
||
- **Рабочие места**: для каждого отдела определён диапазон доступных позиций.
|
||
|
||
---
|
||
|
||
## 3. Архитектура и структура кода
|
||
|
||
### 3.1 Общая структура репозитория
|
||
|
||
| Папка/Файл | Назначение |
|
||
|---------------------------|----------------------------------------------------|
|
||
| `.github/` | CI/CD, workflows, шаблоны PR/ISSUE |
|
||
| `BuildChecker/` | Скрипты и утилиты для сборки |
|
||
| `BuildFiles/` | Файлы для сборки под разные ОС |
|
||
| `Content.Client/` | Клиентская часть |
|
||
| `Content.Server/` | Серверная часть |
|
||
| `Content.Shared/` | Общие компоненты и системы |
|
||
| `Content.IntegrationTests/`| Интеграционные тесты |
|
||
| `Content.Tests/` | Юнит-тесты |
|
||
| `Content.Benchmarks/` | Бенчмарки производительности |
|
||
| `Content.MapRenderer/` | Рендеринг карт |
|
||
| `Content.Packaging/` | Сборка и упаковка ассетов |
|
||
| `Content.YAMLLinter/` | Линтер YAML-файлов |
|
||
| `Resources/` | Ассеты, карты, локализация |
|
||
| `RobustToolbox/` | Игровой движок (подмодуль) |
|
||
| `Sunrise/` | Специфичные для Sunrise расширения |
|
||
| `Tools/` | Вспомогательные инструменты |
|
||
| `README.md`, `README.ru.md`| Документация |
|
||
| `LICENSE.TXT`, `CLA.txt` | Лицензии и соглашения |
|
||
|
||
**Пояснения**:
|
||
- Вся логика разделена на клиентскую, серверную и общую части (Client/Server/Shared), что облегчает поддержку и расширение.
|
||
- Тесты и бенчмарки вынесены в отдельные папки для автоматизации проверки качества.
|
||
- Ассеты и карты структурированы по типу и назначению, YAML-файлы проходят автоматическую валидацию.
|
||
|
||
### 3.2 Модули и ключевые компоненты
|
||
|
||
- **Content.Server**: логика сервера, обработка событий, симуляция мира.
|
||
- **Content.Client**: интерфейс пользователя, визуализация, клиентские системы.
|
||
- **Content.Shared**: общие компоненты ECS, прототипы, сетевые сообщения.
|
||
- **RobustToolbox**: движок, реализующий ECS, сетевой стек, рендеринг, физику.
|
||
- **Content.IntegrationTests/Content.Tests**: тестовые сценарии, покрывающие как отдельные компоненты, так и интеграцию систем.
|
||
- **Content.YAMLLinter**: автоматическая проверка YAML-файлов на корректность и стиль.
|
||
|
||
---
|
||
|
||
## 4. Используемые технологии и зависимости
|
||
|
||
### 4.1 Языки и платформы
|
||
|
||
- **C#**: основной язык разработки, поддержка .NET 7+.
|
||
- **.NET**: кроссплатформенная среда выполнения, сборка и запуск на Windows, Linux, MacOS.
|
||
- **YAML**: описание карт, прототипов, ассетов.
|
||
|
||
### 4.2 Системы сборки и зависимости
|
||
|
||
- **NuGet**: управление внешними пакетами, централизовано через `Directory.Packages.props`.
|
||
- **Nix**: reproducible-сборки, управление окружением для разработчиков (`flake.nix`, `shell.nix`).
|
||
- **CI/CD**: GitHub Actions, автоматическая сборка, тестирование, обновление кредитов, проверка CRLF и др.
|
||
- **RobustToolbox**: подмодуль, обновляется автоматически через скрипт `RUN_THIS.py`.
|
||
- **Скрипты запуска**: `runserver.sh`, `runclient.sh` (и .bat-версии) для локального тестирования и разработки.
|
||
|
||
### 4.3 Внешние инструменты
|
||
|
||
- **YAMLLinter**: проверка стиля и структуры YAML-файлов.
|
||
- **DocFX**: генерация документации.
|
||
- **BenchmarkDotNet**: бенчмарки производительности.
|
||
- **Git**: контроль версий, поддержка ветвления и PR.
|
||
|
||
---
|
||
|
||
## 5. Принципы дизайна и кодирования
|
||
|
||
### 5.1 Стиль кода
|
||
|
||
- **Соблюдение C# Coding Conventions**: отступы, именование, оформление блоков.
|
||
- **Единый стиль для всех файлов**: enforced через `.editorconfig`, автоматическая проверка на CI.
|
||
- **Документирование**: XML-комментарии для публичных методов и классов, README для модулей.
|
||
- **Минимизация дублирования**: выносить общие компоненты в Shared, использовать наследование и композицию.
|
||
|
||
### 5.2 Архитектурные принципы
|
||
|
||
- **ECS (Entity-Component-System)**: все игровые объекты реализованы как сущности с компонентами, системы обрабатывают логику.
|
||
- **Модульность**: новые механики и контент добавляются через отдельные модули/прототипы.
|
||
- **Сетевое разделение**: чёткое разграничение клиентской и серверной логики, минимизация дублирования.
|
||
- **Конфигурируемость**: параметры вынесены в YAML/JSON, легко изменяются без перекомпиляции.
|
||
|
||
### 5.3 Соглашения по именованию
|
||
|
||
- **Папки и файлы**: PascalCase для C# файлов, snake_case для ассетов и YAML.
|
||
- **Классы и интерфейсы**: PascalCase, интерфейсы с префиксом `I`.
|
||
- **Методы и свойства**: PascalCase.
|
||
- **Переменные**: camelCase.
|
||
- **Константы**: ALL_CAPS.
|
||
|
||
---
|
||
|
||
## 6. Критерии качества для Pull Request (PR)
|
||
|
||
### 6.1 Автоматические проверки
|
||
|
||
- **Сборка без ошибок**: PR не должен ломать сборку ни на одной поддерживаемой платформе.
|
||
- **Прохождение всех тестов**: юнит, интеграционные, игровые тесты.
|
||
- **Проверка форматирования**: соответствие `.editorconfig`, отсутствие лишних пробелов, правильные отступы.
|
||
- **Валидация YAML**: автоматическая проверка структуры и стиля YAML-файлов.
|
||
- **Отсутствие конфликтов с upstream**: PR должен быть синхронизирован с последним master/main.
|
||
- **Проверка лицензий**: новые ассеты и код должны иметь корректные лицензии и соответствовать CLA.
|
||
|
||
### 6.2 Ручная и полуавтоматическая проверка
|
||
|
||
- **Код-ревью**: анализ логики, читаемости, архитектурных решений.
|
||
- **Покрытие тестами**: новые функции должны сопровождаться тестами.
|
||
- **Документация**: наличие описания изменений, комментариев, обновление README при необходимости.
|
||
- **Обратная совместимость**: изменения не должны ломать существующий функционал без веской причины.
|
||
|
||
### 6.3 Критерии приёма изменений
|
||
|
||
| Критерий | Обязателен | Примечания |
|
||
|-------------------------|:----------:|---------------------------------------------|
|
||
| Сборка проходит | ✔ | На всех поддерживаемых ОС |
|
||
| Все тесты проходят | ✔ | Включая интеграционные и игровые |
|
||
| Нет конфликтов | ✔ | С master/main и upstream |
|
||
| Документация обновлена | ✔ | README, комментарии, changelog |
|
||
| Лицензии соблюдены | ✔ | Для кода и ассетов |
|
||
| Нет деградации качества | ✔ | Производительность, безопасность, стиль |
|
||
| Покрытие тестами | ✔ | Для новых/изменённых функций |
|
||
| Обратная совместимость | ✔ | Если не указано иное в описании PR |
|
||
|
||
---
|
||
|
||
## 7. Автоматическая проверка изменений: правила для ИИ
|
||
|
||
### 7.1 Общие принципы
|
||
|
||
- **Сравнивать изменения с текущим master/main**: анализировать diff, выявлять потенциальные проблемы.
|
||
- **Проверять соответствие стилю и архитектуре**: использовать встроенные линтеры и анализаторы.
|
||
- **Оценивать влияние на производительность и безопасность**: выявлять потенциальные bottleneck'и, утечки, уязвимости.
|
||
- **Проверять наличие и качество тестов**: новые функции должны сопровождаться тестами.
|
||
- **Анализировать документацию**: изменения должны быть отражены в README, комментариях, changelog.
|
||
|
||
### 7.2 Алгоритм автоматической проверки
|
||
|
||
1. **Извлечь diff PR**: определить изменённые файлы и области кода.
|
||
2. **Проверить сборку и тесты**: убедиться в отсутствии ошибок.
|
||
3. **Запустить линтеры и форматтеры**: проверить стиль кода и YAML.
|
||
4. **Проверить лицензии и CLA**: новые файлы должны иметь корректные лицензии.
|
||
5. **Проверить документацию**: наличие и актуальность описаний.
|
||
6. **Проверить обратную совместимость**: нет ли breaking changes без обоснования.
|
||
7. **Сравнить с примерами хороших/плохих изменений**: выявить паттерны и антипаттерны.
|
||
8. **Сформировать рекомендации**: указать на найденные проблемы, предложить улучшения.
|
||
|
||
---
|
||
|
||
## 8. Примеры хороших и плохих изменений
|
||
|
||
### 8.1 Примеры хороших изменений (паттерны)
|
||
|
||
| Изменение | Почему хорошо |
|
||
|------------------------------------------------|----------------------------------------------------|
|
||
| Добавлен новый компонент с тестами и документацией | Повышает покрытие, облегчает поддержку |
|
||
| Оптимизация алгоритма с бенчмарком | Улучшает производительность, подтверждено метриками |
|
||
| Исправление бага с подробным описанием | Улучшает стабильность, облегчает ревью |
|
||
| Рефакторинг с сохранением обратной совместимости| Повышает читаемость, не ломает существующий код |
|
||
| Добавление новых YAML-прототипов с валидацией | Расширяет контент, не нарушая структуру |
|
||
|
||
**Анализ**:
|
||
Хорошие изменения сопровождаются тестами, документацией, не ломают существующий функционал, проходят все проверки и улучшают проект по одному из критериев: производительность, стабильность, расширяемость, удобство поддержки.
|
||
|
||
### 8.2 Примеры плохих изменений (антипаттерны)
|
||
|
||
| Изменение | Почему плохо |
|
||
|------------------------------------------------|----------------------------------------------------|
|
||
| Изменение логики без тестов и документации | Усложняет поддержку, повышает риск багов |
|
||
| Ломает обратную совместимость без обоснования | Приводит к деградации пользовательского опыта |
|
||
| Добавление ассетов без лицензии | Нарушает юридические требования |
|
||
| Игнорирование стиля и форматирования | Усложняет ревью, снижает читаемость |
|
||
| Изменение в core-модулях без обсуждения | Риск конфликтов и деградации архитектуры |
|
||
|
||
**Анализ**:
|
||
Плохие изменения часто сопровождаются отсутствием тестов, документации, нарушают стиль, ломают существующий функционал или не учитывают юридические аспекты. Такие изменения должны быть отклонены или доработаны.
|
||
|
||
---
|
||
|
||
## 9. Тестирование
|
||
|
||
### 9.1 Виды тестов
|
||
|
||
- **Юнит-тесты**: проверяют отдельные компоненты и системы на корректность работы.
|
||
- **Интеграционные тесты**: моделируют взаимодействие между модулями, проверяют сценарии использования.
|
||
- **Игровые тесты**: автоматизированные сценарии, эмулирующие поведение игроков, загрузку карт, запуск раундов.
|
||
- **Бенчмарки**: измеряют производительность критичных участков кода.
|
||
|
||
### 9.2 Инфраструктура тестирования
|
||
|
||
- **PoolManager**: управление парами сервер-клиент для интеграционных тестов.
|
||
- **PostMapInitTest**: валидация карт, прототипов, YAML-файлов.
|
||
- **CI/CD**: автоматический запуск тестов при каждом PR.
|
||
- **Отчёты о покрытии**: анализируются на CI, минимальный порог покрытия обязателен для новых функций.
|
||
|
||
### 9.3 Критерии успешного тестирования
|
||
|
||
- **100% прохождение тестов**: PR не должен ломать существующие тесты.
|
||
- **Покрытие новых функций**: все новые/изменённые компоненты должны иметь тесты.
|
||
- **Валидация YAML и карт**: автоматическая проверка структуры и корректности.
|
||
|
||
---
|
||
|
||
## 10. Документация и комментарии в коде
|
||
|
||
### 10.1 Требования к документации
|
||
|
||
- **README.md/README.ru.md**: актуальное описание проекта, инструкции по сборке и запуску.
|
||
- **XML-комментарии**: для всех публичных методов, классов, интерфейсов.
|
||
- **Комментарии в коде**: пояснения к сложной логике, TODO/FIXME только при необходимости.
|
||
- **Документация для новых модулей**: отдельные файлы или разделы в README.
|
||
|
||
### 10.2 Автоматизация
|
||
|
||
- **DocFX**: генерация HTML-документации из XML-комментариев.
|
||
- **Проверка на CI**: наличие и актуальность документации для новых функций.
|
||
|
||
---
|
||
|
||
## 11. Лицензирование и CLA
|
||
|
||
### 11.1 Лицензии
|
||
|
||
- **MIT**: для кода, заимствованного из Space Wizards Federation.
|
||
- **CLA (Contributor License Agreement)**: для всех изменений, внесённых в Sunrise Station. Подразумевает передачу прав на использование и модификацию кода проекту, запрещает коммерческое использование без разрешения, требует передачи изменений обратно в проект.
|
||
- **CC-BY-SA 3.0**: для большинства ассетов (графика, звуки), если не указано иное в метаданных.
|
||
|
||
### 11.2 Правила использования кода
|
||
|
||
- **Коммерческое использование**: запрещено без отдельного разрешения.
|
||
- **Публичный хостинг**: только с разрешения владельцев проекта.
|
||
- **Внесение изменений**: любые модификации должны быть переданы обратно в проект на условиях CLA.
|
||
- **Лицензии ассетов**: каждый ассет должен иметь явное указание лицензии в метаданных.
|
||
|
||
---
|
||
|
||
## 12. Процесс работы с пулл-реквестами и ветвлением
|
||
|
||
### 12.1 Ветвление
|
||
|
||
- **Основная ветка**: `master` (или `main`).
|
||
- **Фичевые ветки**: для каждой новой функции или исправления создаётся отдельная ветка.
|
||
- **Синхронизация с upstream**: регулярное обновление ветки от основного репозитория Space Wizards Federation.
|
||
- **Запрет на PR из master**: все изменения должны идти из отдельных веток.
|
||
|
||
### 12.2 Процесс PR
|
||
|
||
1. **Создание ветки**: от master/main.
|
||
2. **Внесение изменений**: с соблюдением всех критериев качества.
|
||
3. **Добавление тестов и документации**.
|
||
4. **Проверка локально**: сборка, тесты, линтеры.
|
||
5. **Открытие PR**: с подробным описанием изменений.
|
||
6. **Автоматическая проверка**: CI, тесты, линтеры.
|
||
7. **Код-ревью**: ручная или полуавтоматическая проверка.
|
||
8. **Мерж или доработка**: после одобрения и устранения замечаний.
|
||
|
||
---
|
||
|
||
## 13. Безопасность и политика безопасности
|
||
|
||
### 13.1 Общие принципы
|
||
|
||
- **Ответственное раскрытие уязвимостей**: сообщения о проблемах безопасности принимаются через Discord или email, публичное раскрытие запрещено до разрешения.
|
||
- **Проверка кода на уязвимости**: автоматические анализаторы, ручной аудит для критичных изменений.
|
||
- **Ограничение доступа**: права доступа к CI/CD, секретам и инфраструктуре только у доверенных участников.
|
||
- **Логирование и аудит**: все действия по безопасности должны быть зафиксированы.
|
||
|
||
### 13.2 Политика обработки инцидентов
|
||
|
||
- **Быстрое реагирование**: при обнаружении уязвимости — немедленное исправление и уведомление участников.
|
||
- **Документирование инцидентов**: ведение журнала инцидентов и принятых мер.
|
||
- **Обновление зависимостей**: регулярная проверка и обновление внешних библиотек.
|
||
|
||
---
|
||
|
||
## 14. Производительность и оптимизация
|
||
|
||
### 14.1 Профилирование
|
||
|
||
- **Бенчмарки**: регулярное измерение производительности критичных систем (загрузка карт, обработка событий, сетевой стек).
|
||
- **Анализ bottleneck'ов**: выявление и устранение узких мест.
|
||
- **Мониторинг логов**: анализ ошибок и предупреждений для выявления деградации.
|
||
|
||
### 14.2 Оптимизация
|
||
|
||
- **Асинхронность**: использование асинхронных операций для I/O и сетевых задач.
|
||
- **Кэширование**: для часто используемых данных и ресурсов.
|
||
- **Минимизация аллокаций**: оптимизация работы с памятью, особенно в горячих путях.
|
||
- **Логирование**: структурированное, с учётом производительности и объёма данных.
|
||
|
||
---
|
||
|
||
## 15. Модули и ключевые компоненты
|
||
|
||
### 15.1 Server, Client, Shared
|
||
|
||
- **Server**: обработка симуляции, событий, логики NPC, взаимодействие с базой данных.
|
||
- **Client**: визуализация, UI, обработка пользовательского ввода.
|
||
- **Shared**: компоненты ECS, прототипы, сетевые сообщения, общие утилиты.
|
||
|
||
### 15.2 Дополнительные модули
|
||
|
||
- **Content.Benchmarks**: тесты производительности.
|
||
- **Content.MapRenderer**: визуализация карт.
|
||
- **Content.Packaging**: упаковка ассетов и билдов.
|
||
- **Content.YAMLLinter**: автоматическая проверка YAML.
|
||
- **Pow3r, Tools**: вспомогательные утилиты и инструменты.
|
||
|
||
---
|
||
|
||
## 16. Система сборки и упаковки
|
||
|
||
### 16.1 BuildFiles и Packaging
|
||
|
||
- **BuildFiles/**: специфичные для платформ файлы сборки (Mac, Windows, Linux).
|
||
- **Content.Packaging/**: скрипты и конфиги для упаковки ассетов, генерации билдов.
|
||
- **RUN_THIS.py**: автоматизация инициализации подмодулей и зависимостей.
|
||
- **Скрипты запуска**: `runserver.sh`, `runclient.sh` для локального тестирования.
|
||
|
||
### 16.2 Локальная сборка и запуск
|
||
|
||
- **Инструкции**: описаны в README.ru.md, поддерживаются для всех основных ОС.
|
||
- **Требования**: установленный Git, Python 3.7+, .NET 7+, Nix (опционально).
|
||
- **Процесс**: клонирование репозитория, запуск скрипта и сборка через dotnet.
|
||
|
||
---
|
||
|
||
## 17. Критерии приёма изменений: функциональность и совместимость
|
||
|
||
### 17.1 Функциональность
|
||
|
||
- **Изменения должны быть обоснованы**: каждая новая функция или исправление должно иметь чёткое описание и цель.
|
||
- **Покрытие тестами**: обязательное для всех новых функций.
|
||
- **Документация**: обновление README, комментариев, changelog.
|
||
|
||
### 17.2 Обратная совместимость
|
||
|
||
- **Не ломать существующий функционал**: breaking changes допускаются только с веской причиной и обсуждением.
|
||
- **Сохранение форматов данных**: YAML, прототипы, карты должны быть совместимы с предыдущими версиями.
|
||
- **Синхронизация с upstream**: регулярное обновление и разрешение конфликтов.
|
||
|
||
---
|
||
|
||
## 18. Локализация и ресурсы
|
||
|
||
### 18.1 Локализация
|
||
|
||
- **README.ru.md**: основной файл документации на русском.
|
||
- **Локали**: все игровые строки вынесены в отдельные файлы локализации, поддержка нескольких языков.
|
||
- **Требования к новым строкам**: обязательное добавление в локализационные файлы, поддержка fallback на английский.
|
||
|
||
### 18.2 Ассеты и YAML
|
||
|
||
- **Стиль оформления**: карты, ассеты, YAML-файлы должны соответствовать единому стилю и структуре.
|
||
- **Линтеры**: автоматическая проверка на CI.
|
||
- **Лицензии**: каждый ассет должен иметь явное указание лицензии.
|
||
|
||
---
|
||
|
||
## 19. Мониторинг и логирование
|
||
|
||
### 19.1 Серверные логи
|
||
|
||
- **Структурированное логирование**: использование формата JSON или аналогичного для автоматического анализа.
|
||
- **Уровни логов**: INFO, WARN, ERROR, FATAL, DEBUG.
|
||
- **Агрегация и централизованное хранение**: все логи собираются в единую систему для анализа и мониторинга.
|
||
- **Политика хранения**: ротация, удаление старых логов, защита от утечек данных.
|
||
- **Не логировать чувствительные данные**: пароли, токены, персональные данные должны быть исключены из логов.
|
||
|
||
### 19.2 Мониторинг
|
||
|
||
- **Метрики производительности**: загрузка процессора, памяти, сетевой трафик, время отклика.
|
||
- **Алерты**: автоматическое оповещение о сбоях, ошибках, превышении пороговых значений.
|
||
- **Дашборды**: визуализация состояния сервера и ключевых метрик.
|
||
|
||
---
|
||
|
||
## 20. Совместимость с upstream Space Wizards Federation
|
||
|
||
### 20.1 Синхронизация
|
||
|
||
- **Регулярное обновление**: слияние изменений из основного репозитория Space Wizards Federation.
|
||
- **Разделение кода**: собственные изменения Sunrise Station выделены, чтобы облегчить мержи и разрешение конфликтов.
|
||
- **Соблюдение лицензий**: заимствованный код — под MIT, собственные изменения — под CLA.
|
||
- **Обратная совместимость**: поддержка форматов данных и протоколов, используемых в upstream.
|
||
|
||
### 20.2 Политика обновлений
|
||
|
||
- **Тестирование после мержей**: обязательный прогон всех тестов после синхронизации.
|
||
- **Документирование конфликтов**: ведение журнала изменений и конфликтов при обновлениях.
|
||
- **Обратная связь с upstream**: при необходимости — отправка багфиксов и улучшений обратно в основной репозиторий.
|
||
|
||
---
|
||
|
||
## 21. Приложения: чек-листы для автоматической проверки
|
||
|
||
### 21.1 Чек-лист для ИИ-ревью
|
||
|
||
- [ ] Сборка проходит на всех платформах
|
||
- [ ] Все тесты (юнит, интеграционные, игровые) проходят
|
||
- [ ] Нет конфликтов с master/main и upstream
|
||
- [ ] Изменения покрыты тестами
|
||
- [ ] Документация обновлена (README, комментарии)
|
||
- [ ] YAML-файлы валидны и соответствуют стилю
|
||
- [ ] Лицензии и CLA соблюдены
|
||
- [ ] Нет деградации производительности
|
||
- [ ] Нет утечек или уязвимостей безопасности
|
||
- [ ] Логирование структурировано, не содержит чувствительных данных
|
||
- [ ] Обратная совместимость сохранена
|
||
|
||
### 21.2 Примеры сообщений для ИИ
|
||
|
||
**Положительный пример**:
|
||
> ✅ Изменения соответствуют стилю, покрыты тестами, документация обновлена. Производительность не ухудшена, обратная совместимость сохранена.
|
||
|
||
**Отрицательный пример**:
|
||
> ❌ Внесённые изменения ломают обратную совместимость (формат карты изменён без миграции). Нет тестов для новых функций. YAML-файлы не проходят валидацию.
|
||
|
||
---
|
||
|
||
## 22. Заключение
|
||
|
||
Данный GDD служит основой для автоматической и ручной проверки изменений в проекте Sunrise Station. Соблюдение описанных стандартов, критериев качества и процессов обеспечивает стабильное развитие, высокое качество кода и контента, а также безопасность и удобство для всех участников сообщества. ИИ-агенты, использующие этот документ, должны строго следовать указанным правилам, обеспечивая объективную и прозрачную оценку каждого пулл-реквеста.
|