Skip to content
marensovichPublic

About

Формы заявок для Discord-серверов: проверка ролей, очередь модерации, отчёты в каналы и журнал действий · Moderated application forms for Discord communities

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

MarForms — формы заявок для Discord-серверов

Русский · English

CI Java 25 Spring Boot 3.5 React 19 PostgreSQL 16 JDA 6.6

Зачем · Возможности · Как это работает · Быстрый старт · Архитектура · Документация


MarForms — платформа модерируемых форм для Discord-сообществ и RP-серверов: набор во фракции, whitelist, жалобы, апелляции. Игрок входит через Discord, MarForms сам проверяет, что он на сервере и у него нужные роли. Ответ уходит в очередь модераторов и отчётом в каналы Discord, а о решении бот пишет автору в личные сообщения.

Главная страница MarForms

Зачем

Сейчас набор на RP-серверах обычно выглядит так: Google Form, ссылка в канале и модератор, который вручную сверяет ник с Discord, копирует ответы в канал и пишет каждому «вас приняли». Кто угодно может отправить форму, роли никто не проверяет, а через месяц уже не понять, кто какое решение принял.

MarForms закрывает этот цикл целиком:

Было Стало
Форму заполняет кто угодно Вход через Discord и доступ по ролям сервера: разрешённые и запрещённые
Ответы копируют в Discord вручную Отчёт сам приходит в выбранные каналы, со своим текстом и embed в каждом
Решение — сообщение в личку от модератора Принять, отклонить или вернуть на доработку в одном окне, бот сам напишет автору
«Кто его принял?» Журнал действий по каждому серверу, с живой лентой
Один человек с доступом к таблице Модераторы, роли администраторов, баны и тайм-ауты для каждого сервера

Возможности

Для игроков

  • Вход через Discord, пароли не нужны. MarForms запрашивает только identify и guilds.
  • «Мои заявки»: статус каждой отправленной формы и комментарий модератора.
  • Решение приходит в личные сообщения от бота.
  • Работает на телефоне, есть тёмная тема и русский / английский интерфейс.

Для модераторов

  • Очередь заявок с фильтрами: принять, отклонить или вернуть на доработку с комментарием.
  • Проверка на сайте опциональна: форма может просто отправлять ответы в Discord.
  • История заявок одного пользователя, баны и тайм-ауты.
  • Экспорт в CSV.

Для владельцев серверов

  • Конструктор форм: 15 типов полей (текст, выбор, дата, рейтинг, файлы до 25 МБ и другие), разделы и условная логика: вопрос появляется только после нужного ответа.
  • Доступ по ролям Discord: разрешённые и запрещённые роли, запрет всегда сильнее. Есть открытые и анонимные формы.
  • Расписание открытия и закрытия, лимит ответов на человека, черновик изменений поверх опубликованной формы и автосохранение с защитой от одновременной правки.
  • Уведомления в каналы: бот сам создаёт вебхук в выбранном канале. У каждого канала свой текст с упоминаниями ролей и своё оформление embed (цвет, автор, картинки, подвал), с живым предпросмотром.
  • Каналы логов на сервере: категория с каналом аудита, доступ только у ролей администраторов.
  • Профиль бота на сервере: ник, аватар, баннер, описание.
  • Журнал действий: крупные правки сворачиваются в одну запись («15:25 – 15:29 Форма изменена»).

Для платформы

  • Админка: пользователи, роли и права, все формы и заявки, состояние системы, настройки, статус бота.
  • Страница обратной связи (баг, идея, проблема) с отправкой в вебхук команды.
  • Безопасность: токены Discord и адреса вебхуков зашифрованы AES-GCM, токены вебхуков в API маскируются, вебхуки собираются заново только на discord.com (защита от SSRF), лимиты запросов по IP.

Как это работает

sequenceDiagram
    autonumber
    actor P as Игрок
    participant M as MarForms
    participant D as Discord
    actor S as Модератор

    P->>M: Открывает ссылку на форму
    M->>D: Вход через Discord (OAuth2)
    M->>D: Есть ли игрок на сервере и какие у него роли? (бот)
    D-->>M: Роли участника
    M-->>P: Форма открыта или доступ закрыт
    P->>M: Отправляет ответ
    M->>D: Отчёт в каналы сервера (вебхуки)
    S->>M: Принимает / отклоняет / возвращает на доработку
    M->>D: Личное сообщение игроку (бот)
    M->>M: Запись в журнал действий
Loading

Скриншоты

Главная Вход
Главная страница, светлая тема Экран входа через Discord

Исходники всех утверждённых экранов (конструктор, модерация, админка, мобильные версии) лежат в docs/design/mockups, как их читать — в docs/design/README.md.

Быстрый старт

Нужно: JDK 25, Node.js 22, Docker и приложение Discord с ботом (Developer Portal).

# 1. База данных
docker compose up -d

# 2. Бэкенд (http://localhost:8090)
cd backend
cp .env.example .env        # Discord client id/secret, токен бота, JWT_SECRET, TOKEN_ENCRYPTION_KEY
./gradlew bootRun

# 3. Фронтенд (http://localhost:5173)
cd ../frontend
npm ci
npm run dev

Установка на сервер — один образ marforms: сайт и API на одном порту 8090, рядом Postgres. Установщик спросит адрес сайта, данные приложения Discord, токен бота и Discord ID главного администратора, сам сгенерирует пароль базы и ключи, запишет .env и запустит всё в Docker:

sudo mkdir -p /home/marforms && sudo chown "$USER" /home/marforms && cd /home/marforms \
  && curl -fsSLO https://github.com/marensovich/MarForms/releases/latest/download/install.sh \
  && bash install.sh

В клоне репозитория ./install.sh собирает образ из исходников, ./install.sh --image берёт готовый.

Вручную то же самое:

cp backend/.env.example .env      # секреты, публичный адрес в FRONTEND_URL, свой ID в ADMIN_DISCORD_IDS
docker compose -f docker-compose.prod.yml --env-file .env up -d

Образ берётся из GitHub Packages (ghcr.io/marensovich/marforms, версия в MARFORMS_VERSION), с флагом --build собирается из исходников. Без compose, при своей базе:

docker build -t marforms .
docker run -d -p 8090:8090 --env-file .env -v marforms_uploads:/data/uploads marforms

TLS ставится перед портом 8090. Все переменные окружения описаны в backend/README.md.

Тесты:

cd backend && ./gradlew test      # H2 + Postgres через Testcontainers (нужен Docker)
cd frontend && npm test && npm run lint

Архитектура

flowchart LR
    B[Браузер] -->|HTTPS| S[Spring Boot<br/>сайт + API]
    S --> P[(PostgreSQL<br/>Flyway, JSONB)]
    S <-->|Gateway WebSocket<br/>JDA| G[Discord Bot API]
    S -->|OAuth2| O[Discord OAuth]
    S -->|очередь отправок| W[Вебхуки каналов]
    S -.->|SSE| B
Loading
Часть Стек
Бэкенд Java 25, Spring Boot 3.5, Spring Security + OAuth2, Hibernate 6, Flyway, JDA 6
Фронтенд React 19, TypeScript, Vite, Tailwind CSS, React Router 7, i18next
Данные PostgreSQL 16: схемы форм и ответы хранятся в JSONB
Фоновые задачи Очередь отправок в базе (SKIP LOCKED) с повторами: отчёты в вебхуки и личные сообщения о решении
Тесты JUnit 5, Spring MockMvc, Testcontainers, Vitest, Testing Library
Доставка Один Docker-образ, Docker Compose, GitHub Actions (образ публикуется по тегу)

Ключевые решения записаны в ADR: фоновые задачи, поля форм в JSONB, хранение файлов.

Структура репозитория
.
├── backend/                 Spring Boot: REST API, бот (JDA), очередь отправок, миграции Flyway
│   └── src/main/resources/db/migration
├── frontend/                React SPA: публичные формы, панель сервера, админка
│   ├── src/components/      экраны: builder/, dashboard/, …
│   ├── src/ui/              UI-кит по макетам
│   └── public/locales/      переводы ru / en
├── docs/
│   ├── spec/                техническое задание
│   ├── adr/                 архитектурные решения
│   └── design/              утверждённые макеты экранов
├── Dockerfile               единый образ: сайт и API
├── docker-compose.yml       Postgres для разработки
└── docker-compose.prod.yml  образ + Postgres

Документация

  • Техническое задание — роли, сценарии, требования.
  • Бэкенд — API, переменные окружения, интеграции с Discord, фоновые задачи.
  • Дизайн — токены, артборды, правила чтения макетов.
  • ADR — почему сделано именно так.

Статус

Текущая версия — 1.0.0, что в неё вошло — в CHANGELOG. Готовы формы, модерация, уведомления, журналы, настройки серверов и админка. Заморожены: интеграция с Google Sheets (CSV-экспорт уже есть) и платные тарифы.

Лицензия

© 2026 marensovich. Все права защищены: код открыт для просмотра, но использовать, копировать, изменять и распространять его без письменного разрешения нельзя. Подробности в LICENSE.

MarForms не аффилирован с Discord Inc. и Rockstar Games.

About

Формы заявок для Discord-серверов: проверка ролей, очередь модерации, отчёты в каналы и журнал действий · Moderated application forms for Discord communities

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages