Первоначальная версия VidConf

2026-07-23 01:04:01 +03:00
commit 896455381a
335 changed files with 61527 additions and 0 deletions
--- a/docs/api/teams.md
+++ b/docs/api/teams.md
@@ -0,0 +1,111 @@
+# Справочник команд
+
+Публичный API для получения списка команд. Для CRUD операций над командами см. [Администраторский API](./admin.md#команды).
+
+## Быстрый старт
+
+```bash
+# Получить список команд
+curl http://localhost:8000/api/v1/teams \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## Эндпоинты
+
+### GET /api/v1/teams
+
+**Получить полный справочник команд (отсортирован по названию).**
+
+**Требует auth:** JWT Bearer token
+
+**Response (200 OK):**
+```json
+[
+  {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "Backend"
+  },
+  {
+    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+    "name": "Frontend"
+  },
+  {
+    "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c9",
+    "name": "DevOps"
+  }
+]
+```
+
+**Поля:**
+- `id` — UUID команды
+- `name` — название (уникально)
+
+**Примечание:** Список возвращается для **всех аутентифицированных пользователей** (не зависит от роли). Этот эндпоинт используется:
+- На странице профиля пользователя для выбора своей команды (PATCH /api/v1/users/me)
+- При создании конференции с приглашением участников (информационно, для фронтенда)
+- На администраторской странице управления пользователями
+
+---
+
+## Использование
+
+### На странице профиля
+
+Пользователь может выбрать команду из этого справочника и назначить себе через:
+
+```bash
+curl -X PATCH http://localhost:8000/api/v1/users/me \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"team_id":"550e8400-e29b-41d4-a716-446655440000"}'
+```
+
+### Администратор
+
+Администратор может управлять командами (создание, редактирование, удаление) через [Администраторский API](./admin.md#команды):
+
+```bash
+# Создать команду
+curl -X POST http://localhost:8000/api/v1/admin/teams \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"QA"}'
+
+# Переименовать команду
+curl -X PATCH http://localhost:8000/api/v1/admin/teams/550e8400-e29b-41d4-a716-446655440000 \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"QA & Testing"}'
+
+# Удалить команду
+curl -X DELETE http://localhost:8000/api/v1/admin/teams/550e8400-e29b-41d4-a716-446655440000 \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+---
+
+## Типы данных
+
+### TeamOut
+```json
+{
+  "id": "uuid",
+  "name": "string"
+}
+```
+
+---
+
+## Примечания
+
+- **Привязка опциональна:** пользователь может работать без команды (`team_id` = null в профиле)
+- **Каскадное удаление:** при удалении команды пользователи, состоявшие в ней, остаются (ON DELETE SET NULL), их `team_id` становится null
+- **Выбор при регистрации:** настройка `registration_team_choice` (в администраторских настройках) определяет, виден ли выбор команды на публичной форме регистрации
+
+---
+
+## Ссылки
+
+- [Профиль пользователя](./users.md) — использует этот справочник для выбора команды
+- [Администраторский API / Команды](./admin.md#команды) — CRUD операции (только админ)
+- [Аутентификация / Опции регистрации](./auth.md#get-apiv1authregistration-options) — включает список команд если выбор включён