itcloud/tech_spec_cloud_media_storage.md

Техническое задание (ТЗ)

Проект: облачное хранилище фото и видео (S3 + Python backend + SQLite → PostgreSQL)

Формат фронтенда: статический сайт (SPA) в папке static/, хостинг в S3 UI: Material UI (MUI)
Backend: Python (FastAPI)
Хранилище файлов: S3 / S3-compatible (MinIO и т.п.)
База данных: SQLite на старте, в будущем — PostgreSQL (миграции через Alembic)

---

1. Цели и принципы

1.1 Цель продукта

Создать удобное, быстрое и безопасное облачное хранилище для фото и видео с фокусом на:

• максимально простой и быстрый загрузчик (drag&drop, пакетные загрузки, большие файлы);
• удобную библиотеку (лента/сеткой), быстрый просмотр, поиск/фильтры;
• безопасный доступ и шаринг ссылками;
• готовность к росту: миграция SQLite → PostgreSQL без переписывания бизнес-логики.

1.2 Принципы реализации

• SOLID / DRY / Clean Architecture: разделение слоёв (API → Service → Repository → Infrastructure).
• Докстринги обязательны для публичных методов/классов и основных сервисов.
• Минимум комментариев в коде: предпочтение самодокументирующемуся коду и докстрингам.
• Стабильный API-контракт: OpenAPI/Swagger (FastAPI).
• Сразу закладываем расширяемость (теги, альбомы, шаринг, фоновые задачи).

---

2. Область охвата (Scope)

2.1 MVP (минимально жизнеспособная версия)

1. Регистрация/логин (минимум: email+пароль)
2. Загрузка фото/видео в S3 (через pre-signed URLs)
3. Библиотека медиа:
   • список/сетка,
   • просмотр (лайтбокс) фото,
   • просмотр/проигрывание видео,
   • базовые сортировки (по дате добавления, по дате съёмки).
4. Удаление (корзина/soft-delete) и восстановление.
5. Простой шаринг публичной ссылкой (срок действия).
6. Генерация превью для изображений (thumbnails).
7. Хранение метаданных (SQLite), подготовлено для PostgreSQL (ORM + миграции).

2.2 Версия v1 (после MVP)

• Альбомы/папки (логическая группировка).
• Теги и поиск по тегам/дате/типу/размеру.
• Извлечение EXIF (камера, дата съёмки, гео — опционально).
• Превью/постер для видео.
• Множественный выбор, пакетные операции (переместить/удалить/добавить теги).
• Пользовательские квоты и статистика хранения.
• Логи действий (аудит: загрузка/удаление/шаринг).

2.3 Вне рамок (Non-goals) на старте

• Полноценное видеотранскодирование в HLS/DASH.
• Распознавание лиц/умные альбомы.
• Коллаборация “семейные библиотеки” (несколько владельцев одного альбома).
• End-to-end шифрование на клиенте.

---

3. Роли и сценарии

3.1 Роли

• User: загружает и управляет своей медиатекой.
• Admin (опционально в v1): администрирование пользователей/квот и доступ ко всем облакам пользователей.

3.2 Ключевые user stories (MVP)

1. Как пользователь, я хочу быстро перетащить папку/файлы и загрузить их в облако.
2. Как пользователь, я хочу просматривать фото в полноэкранном режиме и листать стрелками.
3. Как пользователь, я хочу смотреть видео прямо в браузере.
4. Как пользователь, я хочу удалить файлы и при необходимости восстановить из корзины.
5. Как пользователь, я хочу поделиться ссылкой на один файл/альбом на ограниченное время.

---

4. UX/UI требования (фронтенд)

4.1 Технологическое решение фронтенда

Рекомендуемый компромисс “JS чистый + MUI”:

• Реализовать SPA на React + MUI,
• Сборка (Vite) выдаёт статические артефакты в static/,
• На проде в S3 лежит только static/ (HTML/CSS/JS).

Важно: Material UI (MUI) — React-библиотека. “Чистый JS без сборки” возможен через CDN + UMD, но это хуже по производительности и DX. В ТЗ закладываем правильную схему: разработка с Vite, деплой артефактов в static/.

4.2 Страницы/экраны (MVP)

1. Login / Register
2. Library (главная)
   • переключатель “Grid / List”,
   • фильтр по типу (photo/video),
   • сортировка,
   • строка поиска (в MVP можно скрыть за feature-flag).
3. Viewer
   • фото: зум, листание, скачать,
   • видео: плеер (HTML5), скачать.
4. Upload
   • drag&drop зона,
   • прогресс по файлу и общий прогресс,
   • повтор при ошибке.
5. Trash
   • список удалённых, restore/purge.
6. Shared view (страница по публичной ссылке)

4.3 Компоненты UI

• AppBar + боковое меню (Drawer)
• MediaGrid (виртуализация списка, infinite scroll)
• MediaCard (thumbnail, иконка видео, размер/дата)
• UploadDialog (dropzone + очередь + прогресс)
• ViewerModal (keyboard nav: ← → Esc)
• FiltersBar (chips/select)

4.4 Нефункциональные требования к UI

• Responsive: desktop-first, корректно на мобилках.
• Оптимизация:
  • thumbnails грузятся лениво,
  • viewer тянет оригинал только по запросу,
  • infinite scroll.
• Удобство:
  • drag&drop в любом месте Library,
  • горячие клавиши в Viewer,
  • понятные ошибки и “повторить загрузку”.

---

5. Архитектура (общая)

5.1 Компоненты

1. Static SPA (S3 hosting)
2. Backend API (Python)
3. Database (SQLite → PostgreSQL)
4. Object storage (S3)
5. Background worker (опционально сразу, обязательно для v1) — генерация превью/постеров

5.2 Потоки

Upload (рекомендуемый):

1. SPA запрашивает у backend create_upload (получает pre-signed URL / multipart init).
2. SPA грузит файл напрямую в S3.
3. SPA вызывает finalize_upload (backend фиксирует метаданные, ставит задачу на превью).
4. Backend возвращает Asset ID.

Download/View:

• SPA запрашивает get_asset_download_url → получает краткоживущую signed-ссылку на S3 (оригинал/thumbnail).

---

6. Backend требования

6.1 Стек (рекомендуется)

• FastAPI (ASGI)
• Pydantic (схемы)
• SQLAlchemy 2.x (async) + Alembic (миграции)
• SQLite (MVP), конфигурация диалекта для лёгкого перехода на PostgreSQL
• S3 SDK: boto3 (sync) или aioboto3 (async) / или минимальный клиент через presigned
• Auth: JWT access + refresh (HTTP-only cookies) или Bearer tokens
• Logging: structlog/loguru + стандартный logging
• Tests: pytest + httpx

6.2 Слоистая архитектура (Clean)

• api/ — роуты, схемы, зависимости, auth middleware
• services/ — бизнес-логика (upload, library, share)
• repositories/ — доступ к данным (CRUD)
• infra/ — S3 client, db session factory, config, background tasks
• domain/ — модели домена/интерфейсы (по необходимости)

6.3 Обязательные нефункциональные требования

• Валидация входных данных (Pydantic).
• Единый формат ошибок (problem+json либо собственный стандарт).
• Rate limiting (минимально на login/share) — можно отложить до v1.
• Безопасность:
  • пароли хранить только в виде хеша (argon2/bcrypt),
  • все ссылки на S3 — только signed,
  • CORS настроен строго,
  • CSRF защита при cookie-based auth.
• Наблюдаемость:
  • структурные логи,
  • correlation id (request id),
  • healthcheck endpoint.

---

7. Модель данных (SQLite → PostgreSQL)

7.1 Основные сущности

users

• id (UUID)
• email (unique)
• password_hash
• created_at, updated_at
• is_active

assets

• id (UUID)
• user_id (FK users)
• type enum: photo|video
• status enum: uploading|ready|failed|deleted
• original_filename
• content_type
• size_bytes
• sha256 (optional, for dedup)
• captured_at (datetime, optional)
• created_at
• deleted_at (nullable)
• storage_key_original (S3 object key)
• storage_key_thumb (nullable)
• width, height (nullable)
• duration_sec (nullable)

albums (v1)

• id UUID
• user_id
• title
• created_at

album_items (v1)

• album_id
• asset_id
• position (int)

tags (v1)

• id, user_id, name

asset_tags (v1)

• asset_id, tag_id

shares

• id UUID
• owner_user_id
• asset_id (nullable) — если шаринг одного файла
• album_id (nullable) — если шаринг альбома
• token (unique, random)
• expires_at (nullable)
• password_hash (nullable)
• created_at
• revoked_at (nullable)

auth_sessions (опционально)

• id
• user_id
• refresh_token_hash
• created_at, expires_at, revoked_at

7.2 Требования к миграциям

• Все изменения БД — только через Alembic.
• Никаких raw SQL “внутри приложения”, кроме миграций.
• Схема должна работать в SQLite и PostgreSQL:
  • UUID хранить как TEXT (SQLite) и UUID (PostgreSQL) через тип-переопределения,
  • JSON поля избегать в MVP (или хранить TEXT).

---

8. Object Storage (S3)

8.1 Bucket и ключи

• Bucket: MEDIA_BUCKET
• Ключ оригинала: u/{user_id}/o/{yyyy}/{mm}/{asset_id}{ext}
• Ключ превью: u/{user_id}/t/{yyyy}/{mm}/{asset_id}.jpg
• (v1) ключ постера для видео: u/{user_id}/p/{yyyy}/{mm}/{asset_id}.jpg

8.2 Политики доступа

• Bucket private.
• Доступ только через pre-signed URLs с коротким TTL:
  • thumbnails: 5–30 минут,
  • originals: 1–10 минут (настраиваемо).

---

9. API (контракт)

9.1 Общие правила

• Версионирование: /api/v1
• Авторизация: Authorization: Bearer <token> (или cookie-based)
• Ответы: JSON
• Ошибки: единый формат { "error": { "code": "...", "message": "...", "details": ... } }

9.2 Эндпоинты (MVP)

Auth

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/logout
• GET /api/v1/auth/me
• (опц) POST /api/v1/auth/refresh

Assets (library)

• GET /api/v1/assets?cursor=&limit=&type=&sort=
• GET /api/v1/assets/{asset_id}
• DELETE /api/v1/assets/{asset_id} (soft-delete)
• POST /api/v1/assets/{asset_id}/restore
• DELETE /api/v1/assets/{asset_id}/purge (hard-delete, только из Trash)

Upload (direct-to-S3)

• POST /api/v1/uploads/create
  • вход: original_filename, content_type, size_bytes
  • выход: asset_id, upload_method, presigned_url|presigned_post|multipart
• POST /api/v1/uploads/{asset_id}/finalize
  • вход: etag (или parts list), sha256 (опц)
  • выход: asset

URLs (signed access)

• GET /api/v1/assets/{asset_id}/download-url?kind=original|thumb
• GET /api/v1/assets/{asset_id}/stream-url (для видео, kind=original на старте)

Shares

• POST /api/v1/shares (создать ссылку)
• GET /api/v1/shares/{token} (получить метаданные)
• GET /api/v1/shares/{token}/download-url?asset_id=&kind=
• POST /api/v1/shares/{token}/revoke

9.3 Пагинация

• Cursor-based (рекомендуется): cursor = base64(last_created_at, last_id)
• Ответ: { items: [...], next_cursor: "...", has_more: true }

---

10. Превью (thumbnails) и обработка

10.1 MVP: только изображения

• После finalize_upload backend ставит задачу “generate_thumbnail(asset_id)”.

Режим исполнения (на выбор):

1. Inline (допустимо в MVP): генерация превью синхронно при finalize, если файл небольшой.
2. Background worker (лучше): Celery/RQ + Redis, либо встроенный простейший worker.

Рекомендуемый минимум:

• Redis + RQ.

10.2 Технические требования к thumbnails

• Формат: JPEG
• Максимальная сторона: 512px или 1024px (настраиваемо)
• Прогрессивный JPEG (желательно)
• Сохранение в S3 по storage_key_thumb
• При ошибке: assets.status = failed или отдельное поле thumb_status

10.3 v1: видео постеры

• Генерация постера (кадр на 1–3 секунде) через ffmpeg.
• Хранение отдельным ключом.

---

11. Безопасность

11.1 Аутентификация и пароли

• Хэширование argon2id (предпочтительно) или bcrypt.
• Ограничение попыток логина (v1).
• Сессии/refresh токены можно отзывать.

11.2 Доступ к файлам

• Все доступы к S3 только через signed URLs.
• Проверка владения asset’ом во всех endpoints.
• Подпись ссылок короткая и на конкретный объект.

11.3 Публичные ссылки

• token должен быть криптостойким (>= 128 бит энтропии).
• Возможность ограничить срок действия.
• (v1) опциональный пароль на ссылку.

---

12. Производительность и ограничения

12.1 Ограничения MVP

• Максимальный размер видео: конфиг MAX_UPLOAD_SIZE_BYTES (например 5–20 ГБ).
• Для больших файлов — multipart upload (S3 multipart).
• Лимит выдачи списка: 50–200 элементов, infinite scroll.

12.2 Кэширование

• Thumbnails: CDN-friendly, но доступ через signed URL (TTL).
• Статические файлы фронтенда: cache-control immutable для hashed assets.

---

13. Конфигурация (env)

13.1 Backend env variables (пример)

• APP_ENV=dev|prod
• DATABASE_URL=sqlite+aiosqlite:///./app.db (позже: postgresql+asyncpg://...)
• S3_ENDPOINT_URL= (если MinIO)
• S3_REGION=
• S3_ACCESS_KEY_ID=
• S3_SECRET_ACCESS_KEY=
• MEDIA_BUCKET=
• SIGNED_URL_TTL_SECONDS=600
• CORS_ORIGINS=https://your-domain
• JWT_SECRET=
• JWT_ACCESS_TTL_SECONDS=900
• JWT_REFRESH_TTL_SECONDS=1209600
• MAX_UPLOAD_SIZE_BYTES=

---

14. Деплой и окружения

14.1 Static (S3)

• Папка static/ заливается в S3 bucket для сайта.

14.2 Backend

• Docker-образ, запускается как контейнер (uvicorn/gunicorn).
• Рекомендуемый docker-compose для dev: backend + minio + sqlite (локально) + redis.

14.3 База данных

• MVP: SQLite файл в volume.
• v1: PostgreSQL отдельным сервисом, переключение через DATABASE_URL + миграции alembic.

---

15. Структура репозитория (рекомендация)

repo/
  backend/
    src/
      app/
        api/
          v1/
        services/
        repositories/
        infra/
        domain/
        main.py
    alembic/
    tests/
    pyproject.toml
    Dockerfile
  frontend/
    src/
    public/
    vite.config.js
    package.json
  static/              # build output (deploy to S3)
  docker-compose.yml
  README.md

---

16. Критерии приёмки (Acceptance Criteria)

16.1 MVP

• Пользователь может зарегистрироваться/войти.
• Пользователь может загрузить:
  • минимум 1 фото и 1 видео,
  • пакет из 100+ фото,
  • большой файл (в пределах лимита), без падения сервера.
• В библиотеке отображаются thumbnails для фото.
• Просмотр фото/видео работает в браузере.
• Удаление перемещает в корзину, restore возвращает.
• Public share link открывается без логина (если активен) и даёт доступ только к расшаренному объекту.
• База — SQLite, миграции работают, есть путь миграции на PostgreSQL (без изменения кода сервисов).

16.2 Качество кода

• Линтер/форматтер настроен (ruff + black или ruff format).
• Тесты покрывают ключевые сценарии (auth, create/finalize upload, list assets, share).
• Докстринги присутствуют в слоях services/repositories/infra.

---

17. План работ (укрупнённо)

Этап 1 — фундамент (1)

• Скелет backend (FastAPI), конфиг, подключение БД, миграции.
• User + Auth (register/login/me).
• S3 интеграция: pre-signed upload + signed download.

Этап 2 — assets (2)

• CRUD метаданных assets.
• Library list с пагинацией.
• Trash (soft-delete/restore/purge).

Этап 3 — frontend MVP (3)

• Login/Register.
• Library grid + infinite scroll.
• Upload dialog + прогресс.
• Viewer modal.
• Trash page.

Этап 4 — thumbnails (4)

• Генерация превью (inline или background).
• Отображение превью в Library.

Этап 5 — shares (5)

• Создание/открытие share links.
• Shared view UI.

---

18. Риски и решения

• Большие видео: сразу закладываем multipart upload, иначе упремся в лимиты/таймауты.
• MUI и “чистый JS”: реальный путь — React+MUI и сборка в static/.
• SQLite ограничения: используем репозитории/ORM и Alembic, чтобы миграция на PostgreSQL была сменой DATABASE_URL.
• Стоимость S3: thumbnails уменьшают трафик; оригиналы только по запросу.

---

19. Доп. ПО (если понадобятся очереди/воркеры)

• Redis (рекомендуется)
• RQ (проще)
• Для видео в v1: ffmpeg (в контейнере воркера)

---

20. Примечания по лицензиям и приватности

• Пользовательские файлы и метаданные считаются приватными, но админ может всё просматривать.
• Логи не должны содержать содержимое файлов и чувствительные данные (пароли/токены).
• При шаринге — показывать минимум метаданных.