add registration

2026-09-13 01:42:22 +07:00
parent 0723644d3f
commit c12f81a7c4
20 changed files with 517 additions and 33 deletions
@@ -128,3 +128,62 @@ MCP-эндпоинт: `http://localhost:8090/api/mcp`. ВНИМАНИЕ: REST-ga
  }
 }
 ```
+
+
+## Регистрация команды из Яндекс Форм
+
+`POST /api/games/{id}/registrations` — отдельный HTTP webhook, без пользовательского JWT.
+Капитан не должен иметь учётную запись. Создаётся обычная команда с автоматически
+сгенерированным паролем; почта капитана и количество участников видны организатору
+в списке команд игры. Письма автоматически не отправляются.
+
+Перед запуском примените миграции и задайте `YANDEX_FORMS_TOKEN` в окружении сервера
+(случайный секрет, например результат `openssl rand -hex 32`). Пустое значение отключает ручку.
+Секрет настраивается только в интеграции формы, не в её публичных полях.
+
+В Яндекс Формах откройте **Интеграции → Запрос заданным методом**:
+
+- Метод: `POST`.
+- URL: `https://<адрес-сервера>/api/games/42/registrations`, где `42` — ID игры.
+- Заголовок `Authorization`: `Bearer <YANDEX_FORMS_TOKEN>`.
+- Заголовок `Content-Type`: `application/json`.
+- Тело запроса:
+
+```json
+{
+  "name": "Следствие ведут котики",
+  "email": "captain@example.org",
+  "participantsCount": 5
+}
+```
+
+Подставьте вместо примеров переменные ответов на вопросы «Название команды»,
+«Почта капитана», «Количество участников». Для строк используйте фильтр JSON,
+чтобы кавычки и переносы строк корректно экранировались. Число участников передаётся
+целым JSON-числом без кавычек: от 1 до 2147483647. Название — 1–255 символов после
+удаления пробелов по краям; email — одиночный адрес длиной до 254 байт.
+
+Яндекс передаёт заголовок `X-Delivery-Id`: он обязателен и используется для защиты
+от повторной доставки. Один ID доставки в пределах игры возвращает ту же команду,
+не меняя её данные и пароль. Новая отправка формы с другим ID создаёт новую команду,
+даже если почта и название совпадают. Для ручного теста задайте этот заголовок сами.
+
+Успех: `200 {"id":123}`. Пароль команды в ответ webhook не передаётся.
+Регистрация новой команды доступна только для игры в статусе `draft`.
+Повтор уже принятой доставки успешен и после старта игры.
+Ошибки: `400` — поля/JSON/ID доставки; `401` — токен; `409` — игра отсутствует или
+регистрация закрыта; `503` — интеграция выключена; `500` — внутренняя ошибка.
+Лимит тела — 16 КиБ, время обработки — до 4 секунд.
+
+Сервис должен быть доступен по HTTPS и IPv6: Яндекс Формы отправляют интеграционные
+запросы только с IPv6. При фильтрации входящего трафика разрешите сеть
+`2a02:6b8:c00::/40`. Подробности и настройка переменных — в
+[официальной инструкции Яндекс Форм](https://yandex.ru/support/forms/ru/send-request).
+
+Проверка SQL и повторов на отдельной тестовой PostgreSQL:
+
+```sh
+TEST_DATABASE_URL='postgres://...' go test ./internal/repos/teams_repo -run TestRegistrationPostgres -count=1
+```
+
+Тест создаёт и удаляет собственную схему; требуется право `CREATE SCHEMA`.