feat(backend): модуль «замена фона» и хранилище своих картинок

Отключаемый в админке модуль `virtual_background` (дефолт — выключен, чтобы
обновление не меняло продукт у тех, кто ничего не просил). Флаг едет клиенту
двумя путями: на публичные страницы входа — через `GET /public/settings`,
участнику комнаты — в join-ответе (`JoinOut`), потому что значение нужно на
руках ДО первого рендера комнаты, а `/admin/settings` доступен только админу.

Свои картинки пользователя (`/users/me/backgrounds`, GET/POST/DELETE):
файлы на диске (`backgrounds/{user_id}/{id}.{ext}`), в БД только путь — как у
аватаров, «чтобы не грузили БД». Лимит в 10 штук проверяется на сервере под
блокировкой строки пользователя: две одновременные загрузки иначе обе увидели
бы «уже девять» и обе прошли бы. Удаление сносит и запись, и файл; чужую
картинку по её id удалить нельзя — владелец в условии запроса.

Валидация загрузки (допустимые форматы, магические байты, реальный размер)
выделена из `services/avatars.py` в общий `services/images.py`: правила у
аватара и фона одни и те же, а разъехавшись, они дали бы дыру ровно там, ради
чего проверка и написана. Публичный API аватаров не изменился.

Сжимает картинку клиент (Pillow на бэкенде нет), но серверная валидация
остаётся полноценной — запрос может прийти и мимо интерфейса.

Новый ключ настройки вписан в `_MANAGED_KEYS` тестов: без этого включённый
в общей dev-БД модуль ронял чужие тесты, которые считают себя изолированными.

backend/tests/test_conferences_api.py

@@ -21,6 +21,7 @@ from models.guest import GuestAccess
 from models.invitee import ConferenceInvitee
 from models.user import User
 from services.conference_ids import generate_number, generate_slug
+from services.instance_settings import InstanceSettingsService, SettingsUpdateIn
 
 FUTURE = datetime.now(UTC) + timedelta(days=3)
 
@@ -117,6 +118,12 @@ async def test_create_instant_conference_returns_active_with_join(
     # инсталляции не должны получить внезапно ухудшенное качество).
     assert body["join"]["publish_quality_cap"] == "off"
     assert body["join"]["stage_max_tiles"] == 25
+    # Замена фона — отключаемый модуль (сессия 35); значение нужно клиенту ДО
+    # первого рендера комнаты, поэтому едет в join. Здесь проверяется только
+    # НАЛИЧИЕ поля: тумблер живёт в общей dev-БД, и сравнение с дефолтом
+    # ломалось бы от того, что разработчик включил модуль руками (см.
+    # `test_join_reports_virtual_background_toggle` — там значение задаётся явно).
+    assert isinstance(body["join"]["virtual_background_enabled"], bool)
 
 
 async def test_create_instant_conference_join_metadata_contains_owner_avatar_url(
@@ -718,6 +725,30 @@ async def test_join_closed_conference_correct_password_returns_200(
     assert response.json()["room_name"] == conference.slug
 
 
+@pytest.mark.parametrize("enabled", [True, False])
+async def test_join_reports_virtual_background_toggle(
+    client: httpx.AsyncClient, db_session: AsyncSession, enabled: bool
+) -> None:
+    """Тумблер модуля «замена фона» доезжает до участника в ответе join.
+
+    Значение задаётся ЯВНО, а не берётся из общей dev-БД: клиенту оно нужно до
+    первого рендера комнаты, и подмена тумблера обязана менять ответ join, а не
+    только `/admin/settings` (тот доступен лишь администратору).
+    """
+    owner = await _make_user(db_session)
+    conference = await _make_conference(db_session, owner_id=owner.id)
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(virtual_background_enabled=enabled)
+    )
+    await db_session.commit()
+
+    response = await client.post(
+        f"/api/v1/conferences/{conference.id}/join", json={}, headers=_auth_headers(owner)
+    )
+    assert response.status_code == 200, response.text
+    assert response.json()["virtual_background_enabled"] is enabled
+
+
 # --- Аватар в метаданных LiveKit-токена -----------------------------------------
 
 

backend/tests/test_instance_settings.py

@@ -76,6 +76,7 @@ _MANAGED_KEYS = (
     "media_limits",
     "consent_policy",
     "device_check",
+    "virtual_background",
 )
 
 
@@ -135,6 +136,7 @@ async def test_ensure_bootstrapped_imports_yaml_defaults(
         "media_limits",
         "consent_policy",
         "device_check",
+        "virtual_background",
     }
     cfg = await service.get()
     assert cfg.transcriber.provider == "faster_whisper_cpu"
@@ -164,6 +166,9 @@ async def test_ensure_bootstrapped_imports_yaml_defaults(
     # Проверка устройств на входе (сессия 33) — выключена по умолчанию,
     # существующие инсталляции не должны молча начать спрашивать доступ.
     assert cfg.device_check_enabled is False
+    # Замена фона видео (сессия 35) — выключена по умолчанию: фича постоянно
+    # считает сегментацию на клиенте, включать её обновлением нельзя.
+    assert cfg.virtual_background_enabled is False
 
 
 async def test_ensure_bootstrapped_is_idempotent_and_keeps_admin_edits(
@@ -214,6 +219,22 @@ async def test_update_device_check_enabled(
     assert cfg.device_check_enabled is False
 
 
+async def test_update_virtual_background_enabled(
+    db_session: AsyncSession, clean_instance_settings: None
+) -> None:
+    service = InstanceSettingsService(db_session)
+    await service.ensure_bootstrapped(PLUGINS_YAML)
+
+    cfg = await service.update(SettingsUpdateIn(virtual_background_enabled=True))
+    assert cfg.virtual_background_enabled is True
+
+    cfg = await service.get()
+    assert cfg.virtual_background_enabled is True
+
+    cfg = await service.update(SettingsUpdateIn(virtual_background_enabled=False))
+    assert cfg.virtual_background_enabled is False
+
+
 @pytest.mark.parametrize(
     ("preset", "chat_enabled", "ai_enabled", "ai_level"),
     [

backend/tests/test_public_api.py

@@ -8,11 +8,13 @@ from services.instance_settings import InstanceSettingsService, SettingsUpdateIn
 
 
 @pytest_asyncio.fixture(autouse=True)
-async def _reset_device_check(db_session: AsyncSession) -> None:
-    """Сбросить `device_check_enabled` перед каждым тестом — общая dev-БД не изолирована
+async def _reset_public_flags(db_session: AsyncSession) -> None:
+    """Сбросить публичные тогглы перед каждым тестом — общая dev-БД не изолирована
     от ручных правок администратора (та же дисциплина, что и `_reset_registration_gating`
     в `test_auth.py`); `db_session` не коммитится в реальную БД, см. `conftest.py`."""
-    await InstanceSettingsService(db_session).update(SettingsUpdateIn(device_check_enabled=False))
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(device_check_enabled=False, virtual_background_enabled=False)
+    )
 
 
 async def test_public_settings_disabled_by_default(
@@ -20,7 +22,7 @@ async def test_public_settings_disabled_by_default(
 ) -> None:
     response = await client.get("/api/v1/public/settings")
     assert response.status_code == 200, response.text
-    assert response.json() == {"device_check_enabled": False}
+    assert response.json() == {"device_check_enabled": False, "virtual_background_enabled": False}
 
 
 async def test_public_settings_reflects_enabled(
@@ -31,7 +33,21 @@ async def test_public_settings_reflects_enabled(
 
     response = await client.get("/api/v1/public/settings")
     assert response.status_code == 200, response.text
-    assert response.json() == {"device_check_enabled": True}
+    assert response.json()["device_check_enabled"] is True
+
+
+async def test_public_settings_reflects_virtual_background_enabled(
+    client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Замена фона нужна и на публичном превью входа (`JoinPage`) — до аутентификации."""
+    await InstanceSettingsService(db_session).update(
+        SettingsUpdateIn(virtual_background_enabled=True)
+    )
+    await db_session.commit()
+
+    response = await client.get("/api/v1/public/settings")
+    assert response.status_code == 200, response.text
+    assert response.json()["virtual_background_enabled"] is True
 
 
 async def test_public_settings_requires_no_auth(

backend/tests/test_users_api.py

@@ -1,4 +1,4 @@
-"""Интеграционные тесты `/api/v1/users`: список пользователей, профиль, аватар."""
+"""Интеграционные тесты `/api/v1/users`: список пользователей, профиль, аватар, картинки фона."""
 
 import uuid
 from collections.abc import Generator
@@ -12,6 +12,7 @@ from core.config import get_settings
 from core.security import create_access_token, hash_password
 from models.team import Team
 from models.user import User
+from services.backgrounds import MAX_BACKGROUNDS_PER_USER
 
 # Минимальные валидные по магическим байтам содержимые (без полноценного
 # декодирования — `services/avatars.py` проверяет только сигнатуру/размер).
@@ -393,3 +394,150 @@ async def test_list_users_search_by_q_filters_by_name_or_email(
     ids = {item["id"] for item in response.json()}
     assert str(match.id) in ids
     assert str(requester.id) not in ids
+
+
+# --- Свои картинки фона (`/users/me/backgrounds`) -----------------
+
+
+async def _upload_background(
+    client: httpx.AsyncClient, user: User, *, name: str = "bg.webp"
+) -> httpx.Response:
+    return await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": (name, _WEBP_BYTES, "image/webp")},
+    )
+
+
+async def test_backgrounds_list_is_empty_by_default_and_reports_limit(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert response.status_code == 200, response.text
+    body = response.json()
+    assert body["items"] == []
+    assert body["limit"] == MAX_BACKGROUNDS_PER_USER
+
+
+async def test_upload_background_saves_file_and_returns_url(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await _upload_background(client, user)
+    assert response.status_code == 201, response.text
+    items = response.json()["items"]
+    assert len(items) == 1
+    url = items[0]["url"]
+    assert url == f"/media/backgrounds/{user.id}/{items[0]['id']}.webp"
+    # Файл лежит на диске, в БД только путь — см. `services/backgrounds.py`.
+    assert (media_root / url.removeprefix("/media/")).read_bytes() == _WEBP_BYTES
+
+
+async def test_upload_background_spoofed_content_type_returns_415(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """`Content-Type: image/webp`, но байты — JPEG: клиенту не верим и здесь."""
+    user = await _make_user(db_session)
+    await db_session.commit()
+
+    response = await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": ("bg.webp", _JPEG_BYTES, "image/webp")},
+    )
+    assert response.status_code == 415
+    assert response.json()["detail"] == "background_invalid_type"
+
+
+async def test_upload_background_too_large_returns_413(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+    oversized = _WEBP_BYTES + b"\x00" * (2 * 1024 * 1024)
+
+    response = await client.post(
+        "/api/v1/users/me/backgrounds",
+        headers=_auth_headers(user),
+        files={"file": ("bg.webp", oversized, "image/webp")},
+    )
+    assert response.status_code == 413
+    assert response.json()["detail"] == "background_too_large"
+
+
+async def test_upload_background_over_limit_returns_409_and_keeps_ten(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Лимит держится на СЕРВЕРЕ: интерфейс можно обойти прямым запросом."""
+    user = await _make_user(db_session)
+    await db_session.commit()
+    for _ in range(MAX_BACKGROUNDS_PER_USER):
+        assert (await _upload_background(client, user)).status_code == 201
+
+    response = await _upload_background(client, user)
+    assert response.status_code == 409
+    assert response.json()["detail"] == "background_limit_reached"
+
+    listing = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert len(listing.json()["items"]) == MAX_BACKGROUNDS_PER_USER
+
+
+async def test_delete_background_removes_file_and_row(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    user = await _make_user(db_session)
+    await db_session.commit()
+    created = (await _upload_background(client, user)).json()["items"][0]
+    file_path = media_root / created["url"].removeprefix("/media/")
+    assert file_path.exists()
+
+    response = await client.delete(
+        f"/api/v1/users/me/backgrounds/{created['id']}", headers=_auth_headers(user)
+    )
+    assert response.status_code == 204
+    assert not file_path.exists()
+
+    listing = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(user))
+    assert listing.json()["items"] == []
+
+
+async def test_delete_other_users_background_returns_404(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    """Знание id чужой картинки не даёт её удалить — владелец в условии запроса."""
+    owner = await _make_user(db_session)
+    stranger = await _make_user(db_session)
+    await db_session.commit()
+    created = (await _upload_background(client, owner)).json()["items"][0]
+
+    response = await client.delete(
+        f"/api/v1/users/me/backgrounds/{created['id']}", headers=_auth_headers(stranger)
+    )
+    assert response.status_code == 404
+    assert (media_root / created["url"].removeprefix("/media/")).exists()
+
+
+async def test_backgrounds_list_does_not_leak_other_users_images(
+    media_root: Path, client: httpx.AsyncClient, db_session: AsyncSession
+) -> None:
+    owner = await _make_user(db_session)
+    stranger = await _make_user(db_session)
+    await db_session.commit()
+    await _upload_background(client, owner)
+
+    response = await client.get("/api/v1/users/me/backgrounds", headers=_auth_headers(stranger))
+    assert response.json()["items"] == []
+
+
+async def test_backgrounds_require_authentication(
+    media_root: Path, client: httpx.AsyncClient
+) -> None:
+    assert (await client.get("/api/v1/users/me/backgrounds")).status_code == 401
+    assert (
+        await client.delete(f"/api/v1/users/me/backgrounds/{uuid.uuid4()}")
+    ).status_code == 401