diff --git a/task4/TT.typ b/task4/TT.typ new file mode 100644 index 0000000..6c16eae --- /dev/null +++ b/task4/TT.typ @@ -0,0 +1,309 @@ +// Technical Task File + += Спецификация требований к программному обеспечению «Хуангджа Маджонг» + +== 1. Введение + +=== 1.1 Цель +Настоящий документ определяет функциональные и нефункциональные требования к разработке кроссплатформенного приложения «Хуангджа Маджонг» --- цифровой адаптации классической игры Маджонг с элементами кастомизации, ИИ-помощниками и системой сезонов. Документ предназначен для команды разработки, тестирования, заказчика и всех заинтересованных лиц. + +=== 1.2 Соглашения, принятые в документе +- Требования нумеруются по схеме: `[Тип]-[Раздел].[Номер]`, где `Тип` = FUNC (функциональное), `NONFUNC` (нефункциональное), `DATA` (требование к данным), `UI` (требование к интерфейсу). +- Термины «плитка», «фишка», «кость» используются как синонимы. +- Все требования обязательны к реализации, если не помечены как «Опционально». + +=== 1.3 Границы проекта +*Продукт может:* +- Реализовывать классическую механику маджонга (4 группы по 3 фишки + 1 пара). +- Поддерживать игру онлайн (4 игрока) и офлайн (против ИИ). +- Предоставлять кастомизацию (скины фишек, столов, аватары). +- Включать ИИ-тренера, ИИ-соперников, ИИ-чат поддержки. +- Иметь систему сезонов (времена года, провинции Китая). +- Включать мастерскую сообщества. + +*Продукт НЕ может:* +- Изменять базовые правила победы. +- Разрешать читерство или нечестные покупки (лутбоксы содержат только косметические предметы и не влияют на игровой процесс). + +=== 1.4 Ссылки +- бизнес-требования проекта. +- описание идеи и MVP. +- Apple Human Interface Guidelines, Google Material Design --- стандарты UI/UX. +- WCAG AA --- стандарты доступности. + +== 2. Общее описание + +=== 2.1 Общий взгляд на продукт +«Хуангджа Маджонг» --- это новый кроссплатформенный продукт (iOS, Android, Web), ориентированный на азиатский рынок. Игра сочетает классические правила маджонга с современными механиками: кастомизация, ИИ-помощники, комьюнити-функции (мастерская, таблицы лидеров). Продукт не является заменой существующих маджонг-игр, а выделяется за счёт коллабораций с аниме-студиями и глубокой локализации. + +=== 2.2 Классы пользователей и их характеристики + +#table( + columns: 2, + table.header( + [Класс пользователя], [Характеристика] + ), + [Новый игрок], [Не знаком с правилами, нуждается в туториале.], + [Опытный игрок], [Знает правила, участвует в рейтингах, покупает скины.], + [Модератор], [Сотрудник платформы, следящий за соблюдением правил сообщества. Отвечает за обработку жалоб и модерацию контента в мастерской.], + [Администратор], [Сотрудник платформы с расширенными правами: управление модераторами, настройка системы сезонов, просмотр расширенной статистики.], +) + +*Примечание*: ИИ-тренер, ИИ-игрок и ИИ-чат поддержки являются программными модулями, а не классами пользователей. + +=== 2.3 Операционная среда +- *Клиент*: iOS 13+, Android 8+, веб-браузеры (Chromium, Safari, Firefox) с разрешением от 1280×720. +- *Сервер*: Linux, облачная инфраструктура с поддержкой WebSockets. +- *Сеть*: 4G / Wi-Fi. + +=== 2.4 Ограничения проектирования и реализации +- Использование кроссплатформенного фреймворка (например, Flutter или React Native). +- Серверная часть должна поддерживать WebSockets для real-time синхронизации. +- БД должна хранить историю партий (30 дней) и профили игроков бессрочно. + +=== 2.5 Предположения и зависимости +- Пользователи имеют базовое понимание мобильных приложений. +- Игроки готовы к косметическим микроплатежам (покупка предметов, влияющих только на внешний вид, но не на игровую механику). +- Серверная инфраструктура масштабируется при пиковых нагрузках. + +== 3. Функции системы + +=== 3.1 Управление игровой сессией +==== 3.1.1 Use Case +*Название*: Начать онлайн-партию +*Актор*: Игрок +*Предусловие*: Игрок авторизован, выбран режим «Онлайн» +*Основной сценарий*: +1. Система ищет 3 других игроков (или заполняет ИИ). +2. После сбора раздаются фишки (лидеру --- 14, остальным --- 13). +3. Игроки ходят по кругу. +4. При сборе 4 сетов и пары игрок объявляет маджонг. +5. Система подсчитывает очки. + +==== 3.1.2 Функциональные требования +- FUNC-3.1.1: Система должна автоматически распределять фишки в начале партии. +- FUNC-3.1.2: Система должна фиксировать все сбросы и взятия. +- FUNC-3.1.3: При разрыве соединения у игрока есть 60 секунд на переподключение. По истечении этого времени: + - Игрок считается отключившимся. + - Система заменяет его ИИ-игроком, который продолжает партию с текущей рукой отключившегося игрока. + - Остальные игроки получают уведомление о замене. + - Если отключившийся игрок переподключается позже, он не может вернуться в завершённую партию, но может начать новую. + - Результаты партии сохраняются с учётом игры ИИ-заменителя. +- FUNC-3.1.4: Подсчёт очков должен учитывать сложность комбинации. + +=== 3.2 ИИ-тренер +==== 3.2.1 Use Case +*Название*: Получить подсказку +*Актор*: Игрок +*Предусловие*: Игрок в партии, активен режим обучения +*Основной сценарий*: +1. Игрок нажимает кнопку «Совет». +2. ИИ анализирует текущую руку и подсвечивает оптимальную фишку для сброса. + +==== 3.2.2 Функциональные требования +- FUNC-3.2.1: ИИ-тренер должен работать в тренировочных партиях. +- FUNC-3.2.2: Подсказки должны быть опциональными (вкл/выкл в настройках). +- FUNC-3.2.3: ИИ не должен давать советы в рейтинговых играх. + +=== 3.3 Мастерская сообщества (Community Workshop) + +==== 3.3.1 Use Case +*Название*: Опубликовать пользовательский скин +*Актор*: Зарегистрированный игрок (контент-мейкер) +*Предусловие*: Игрок авторизован, имеет готовый файл скина (изображение, соответствующее техническим требованиям) +*Основной сценарий*: +1. Игрок заходит в раздел «Мастерская», затем «Мои работы», затем «Загрузить новую работу». +2. Система предлагает выбрать тип скина (фишка, стол, аватар, фон). +3. Игрок загружает изображение, указывает название и теги. +4. Система проверяет файл на соответствие техническим требованиям (размер, формат, разрешение). +5. Работа отправляется на модерацию. Статус меняется на «На проверке». +6. После прохождения модерации скин появляется в галерее мастерской. +7. Другие игроки могут просматривать, оценивать, комментировать и скачивать/покупать скин (в зависимости от настроек автора). + +*Альтернативный сценарий (отклонение)*: +1. Модератор отклоняет работу (например, из-за нарушения правил сообщества). +2. Автор получает уведомление с причиной отказа. +3. Автор может исправить замечания и отправить работу повторно. + +==== 3.3.2 Функциональные требования +- FUNC-3.3.1: Система должна поддерживать загрузку изображений в форматах PNG, JPG, WebP (для фишек --- с прозрачностью). +- FUNC-3.3.2: Система должна автоматически проверять загружаемые файлы на соответствие техническим требованиям (размер не более 5 МБ, разрешение не менее 128×128 и не более 1024×1024). +- FUNC-3.3.3: Загруженные работы не отображаются в общем доступе до прохождения модерации. +- FUNC-3.3.4: Система должна вести историю изменений статуса работы (отправлено, на проверке, одобрено, отклонено). +- FUNC-3.3.5: У каждой работы должен быть рейтинг (лайки/дизлайки) и возможность комментирования. + - *Комментарий*: текстовое сообщение, оставленное пользователем под работой в мастерской. Комментарии проходят автоматическую фильтрацию на предмет оскорблений. Модератор может удалять комментарии, нарушающие правила. +- FUNC-3.3.6: Автор может установить цену на свою работу (бесплатно / за игровую валюту / за премиальную валюту). Система удерживает комиссию платформы. +- FUNC-3.3.7: Система должна уведомлять автора об изменении статуса работы (push-уведомление, уведомление в приложении). + +=== 3.4 Модерация контента и сообщества + +==== 3.4.1 Use Case +*Название*: Обработать жалобу на пользователя +*Актор*: Модератор +*Предусловие*: Модератор авторизован в админ-панели, поступила новая жалоба +*Основной сценарий*: +1. Модератор заходит в раздел «Жалобы» (или получает уведомление о новой жалобе). +2. Система отображает список активных жалоб с указанием: дата, жалобщик, нарушитель, причина, приложенные доказательства (скриншоты/логи чата). +3. Модератор открывает конкретную жалобу. +4. Система показывает полную историю нарушений пользователя (если были ранее) и логи чата за последние 24 часа. +5. Модератор принимает решение: + - Отклонить жалобу (если нарушение не подтвердилось). + - Вынести предупреждение. + - Заблокировать чат (временная блокировка возможности писать). + - Заблокировать аккаунт (временная или постоянная блокировка входа). +6. Модератор обязан указать причину решения (выбирает из шаблонов или пишет вручную). +7. Система отправляет уведомление нарушителю о принятом решении с указанием причины. +8. Система фиксирует действие модератора в логах. + +*Альтернативный сценарий (экстренная блокировка/заморозка)*: +1. Модератор видит особо тяжёлое нарушение (спам-атака, дискриминационные высказывания, читерство). +2. Модератор использует функцию «Заморозить аккаунт». +3. Система немедленно: + - Блокирует вход в аккаунт. + - Завершает все активные сессии пользователя. + - Заменяет его на ИИ во всех текущих партиях. + - Блокирует возможность создавать новые комнаты и писать в чат. +4. Аккаунт переводится в статус «Заморожен». +5. Модератор в течение 24 часов оформляет подробное обоснование блокировки в специальной форме (с приложением доказательств). +6. Если обоснование не предоставлено в срок, заморозка автоматически снимается. +7. Пользователь при попытке входа видит сообщение: «Ваш аккаунт заморожен. Подробности в письме/уведомлении». + +==== 3.4.2 Функциональные требования +- FUNC-3.4.1: Админ-панель (веб-интерфейс) должна содержать раздел «Модерация» с подразделами: «Жалобы», «Контент мастерской», «Логи чата». +- FUNC-3.4.2: Система должна автоматически фильтровать явные нарушения (мат, оскорбления) в чате и направлять их на приоритетную модерацию. +- FUNC-3.4.3: У модератора должна быть возможность просмотреть полную историю нарушений пользователя (с датами, решениями, скриншотами). +- FUNC-3.4.4: При блокировке аккаунта система должна: + - Завершить все активные сессии пользователя. + - Уведомить других игроков в текущих партиях о замене нарушителя на ИИ. + - Заблокировать возможность создавать новые комнаты и писать в чат. +- FUNC-3.4.5: Действия модератора логируются (кто, когда, в отношении кого, причина). +- FUNC-3.4.6: Пользователь должен получать уведомление о решении по его жалобе. +- FUNC-3.4.7: Модератор не может модерировать свои собственные работы или жалобы на друзей (система предотвращает конфликт интересов). + +== 4. Требования к данным + +=== 4.1 Логическая модель данных + +*Пользователь (User)* +Хранит информацию о зарегистрированном игроке. Участвует в партиях, создаёт скины, оставляет комментарии, получает награды. +- ID, ник, аватар, валюта (премиальная/игровая), история игр, статус модерации (норма/предупреждение/под наблюдением/заблокирован/заморожен), счётчик нарушений, дата последнего нарушения, ID блокирующего модератора, причина последней блокировки. + +*Партия (Game)* +Фиксирует завершённую игру. Участвует в расчёте рейтинга и статистики игроков. +- ID, список игроков, последовательность ходов, результат. + +*Скин (Skin)* +Представляет кастомизируемый визуальный элемент. Создаётся игроками, проходит модерацию, может быть бесплатным или платным. Используется в профиле и за игровым столом. +- ID, тип (фишка/стол/аватар/фон), владелец, цена, статус модерации (на проверке/одобрено/отклонено), рейтинг, количество скачиваний/покупок. + +*Комментарий (Comment)* +Текстовое сообщение под скином в мастерской. Проходит фильтрацию, может быть удалён модератором. +- ID, ID автора, ID скина, текст, дата, статус (активен/удалён модератором). + +*Сезон (Season)* +Определяет временной период с уникальной тематикой и набором наград. Участвует в прогрессе игрока. +- ID, название (например, «Провинция Сычуань»), даты начала и конца, набор наград. + +*Модератор (Moderator)* +Сотрудник платформы с правами на модерацию. Связан с учётной записью пользователя. +- ID, ID пользователя (связь с таблицей Users), уровень доступа (модератор чата / модератор контента / супер-админ), дата назначения, назначивший администратор, статус (активен/заблокирован), последняя активность. + +*Жалоба (Complaint)* +Фиксирует обращение игрока на нарушение. Обрабатывается модератором. +- ID, ID жалобщика, ID нарушителя, тип жалобы (чат/скин/поведение), статус (новая/в работе/решена/отклонена), приоритет (низкий/средний/высокий), дата создания, дата решения, ID модератора, решение (предупреждение/блокировка чата/блокировка аккаунта/отказ/заморозка), причина решения, приложенные доказательства (ссылки на логи/скриншоты). + +*Нарушение (Violation)* +Фиксирует факт нарушения правил пользователем. Используется для истории и автоматического усиления наказаний. +- ID, ID пользователя, ID модератора, тип нарушения, дата, мера воздействия, срок действия (для временных блокировок), статус (активно/истекло/отменено). + +*Лог модерации (ModerationLog)* +Аудит действий модераторов для безопасности и контроля качества. +- ID, ID модератора, тип действия, ID целевого объекта (пользователь/скин/сообщение), дата, детали действия, IP-адрес модератора. + +=== 4.2 Словарь данных +- *Премиальная валюта*: покупается за реальные деньги, тратится на эксклюзивные скины. +- *Игровая валюта*: зарабатывается за партии, тратится на базовые скины. +- *Уровень доступа модератора*: + - *Модератор чата*: может обрабатывать жалобы на общение, выдавать предупреждения, блокировать чат. + - *Модератор контента*: проверяет загруженные скины в мастерской. + - *Супер-админ*: полный доступ, может назначать модераторов. +- *Тип жалобы*: + - *Чат*: оскорбления, спам, токсичное поведение. + - *Скин*: нарушение авторских прав, неприемлемое содержание. + - *Поведение*: читерство, намеренный слив игры, гриферство. +- *Мера воздействия*: + - *Предупреждение*: запись в профиле, без ограничений. + - *Блокировка чата*: временное (от 1 до 30 дней) отключение возможности писать. + - *Блокировка аккаунта*: временная или постоянная блокировка входа. + - *Заморозка*: экстренная блокировка на время разбирательства (до 24 часов) с автоматической заменой на ИИ в текущих партиях. + +=== 4.3 Хранение и утилизация данных +- Данные партий хранятся 30 дней, затем анонимизируются. +- Профили пользователей хранятся бессрочно до запроса на удаление. +- Логи чата модерации хранятся 1 год. +- Жалобы хранятся 1 год после решения (для апелляций и анализа). +- Логи действий модераторов хранятся 3 года (аудит безопасности). +- Информация о блокировках хранится бессрочно (для выявления повторных нарушителей). +- Удалённые аккаунты нарушителей хранятся в архиве 90 дней (возможность восстановления по запросу), затем анонимизируются. + +== 5. Требования к внешним интерфейсам + +=== 5.1 Пользовательский интерфейс +- UI-5.1.1: Главное меню содержит кнопки: «Играть», «Мастерская», «Сезон», «Профиль». +- UI-5.1.2: Игровое поле отображает фишки текущего игрока внизу, соперников --- сверху и по бокам. +- UI-5.1.3: Анимации действий не превышают 0.3 сек. +- UI-5.1.4: Админ-панель модератора (веб-интерфейс) + - Дашборд с метриками и уведомлениями. + - Раздел «Жалобы» с фильтрацией и сортировкой. + - Карточка жалобы с историей нарушений и панелью решений. + - Раздел «Модерация контента» для проверки скинов. + - Раздел «Пользователи» для поиска и просмотра профилей. + - Раздел «Логи» для аудита действий модераторов. +- UI-5.1.5: Уведомления для пользователей о результатах модерации + - При блокировке: экран с причиной и сроком. + - При предупреждении: всплывающее уведомление. + - При одобрении скина: уведомление о публикации. + +=== 5.2 API +- API-5.2.1: Сервер предоставляет REST API для клиентских приложений (фронтенда) с целью авторизации, загрузки скинов, получения рейтингов и т.д. +- API-5.2.2: WebSocket используется для синхронизации партий в реальном времени. +- API-5.2.3: Отдельные эндпоинты для админ-панели модераторов (защищены дополнительной авторизацией). + +== 6. Атрибуты качества + +=== 6.1 Производительность +- NONFUNC-6.1.1: Время отклика сервера на игровое действие ≤ 500 мс. +- NONFUNC-6.1.2: Uptime сервиса ≥ 99.5%. + +=== 6.2 Безопасность +- NONFUNC-6.2.1: Все платежи проходят через защищённые протоколы (PCI DSS). +- NONFUNC-6.2.2: Чат фильтруется автоматически (мат, оскорбления). + +=== 6.3 Удобство использования +- NONFUNC-6.3.1: Интерфейс соответствует принципу «3 клика». +- NONFUNC-6.3.2: Контрастность текста ≥ 4.5:1. +- NONFUNC-6.3.3: Туториал обязателен для новых игроков (возможность пропуска с предупреждением). + +== 7. Диаграммы вариантов использования (Use Case) + +=== 7.1 Диаграмма для игрока (основные сценарии) +#image("uml_usecase_3_1_start_online_game.png") +#image("uml_usecase_3_2_get_hint.png") +#image("uml_usecase_3_3.drawio.png") +*Акторы*: Игрок, ИИ-тренер, ИИ-игрок +*Варианты использования*: +- Начать онлайн-партию +- Получить подсказку от ИИ-тренера +- Опубликовать скин в мастерской +// - Комментировать скин +- Пожаловаться на нарушение + +=== 7.2 Диаграмма для модератора и администратора +#image("uml_usecas_3_4.drawio.png") +*Акторы*: Модератор, Администратор +*Варианты использования*: +- Обработать жалобу +- Заблокировать/заморозить аккаунт +//- Проверить скин в мастерской +//- Просмотреть логи модерации +//- Назначить модератора (только администратор) \ No newline at end of file diff --git a/task4/uml_usecas_3_4.drawio.png b/task4/uml_usecas_3_4.drawio.png new file mode 100644 index 0000000..deb69dc Binary files /dev/null and b/task4/uml_usecas_3_4.drawio.png differ diff --git a/task4/uml_usecase_3_1_start_online_game.png b/task4/uml_usecase_3_1_start_online_game.png new file mode 100644 index 0000000..974a0a4 Binary files /dev/null and b/task4/uml_usecase_3_1_start_online_game.png differ diff --git a/task4/uml_usecase_3_2_get_hint.png b/task4/uml_usecase_3_2_get_hint.png new file mode 100644 index 0000000..7be6d7f Binary files /dev/null and b/task4/uml_usecase_3_2_get_hint.png differ diff --git a/task4/uml_usecase_3_3.drawio.png b/task4/uml_usecase_3_3.drawio.png new file mode 100644 index 0000000..b5998bb Binary files /dev/null and b/task4/uml_usecase_3_3.drawio.png differ diff --git a/task4/usecase_3_1_start_online_game.png b/task4/usecase_3_1_start_online_game.png new file mode 100644 index 0000000..b9d83b8 Binary files /dev/null and b/task4/usecase_3_1_start_online_game.png differ diff --git a/task4/usecase_3_2_get_hint.png b/task4/usecase_3_2_get_hint.png new file mode 100644 index 0000000..dc1d110 Binary files /dev/null and b/task4/usecase_3_2_get_hint.png differ diff --git a/task4/usecase_3_3_publish_skin.png b/task4/usecase_3_3_publish_skin.png new file mode 100644 index 0000000..b386e54 Binary files /dev/null and b/task4/usecase_3_3_publish_skin.png differ diff --git a/task4/usecase_3_4_handle_report.png b/task4/usecase_3_4_handle_report.png new file mode 100644 index 0000000..7243092 Binary files /dev/null and b/task4/usecase_3_4_handle_report.png differ