itcloud/README.md

# ITCloud - Облачное хранилище фото и видео

Современное облачное хранилище для фото и видео с удобным веб-интерфейсом, построенное на React + Material UI и Python FastAPI.

## Особенности

- 📸 **Загрузка фото и видео** - поддержка drag & drop, пакетная загрузка
- 🖼️ **Удобная галерея** - сетка с превью, быстрый просмотр
- 🎬 **Видео плеер** - встроенный плеер для просмотра видео
- 🗑️ **Корзина** - мягкое удаление с возможностью восстановления
- 🔗 **Шаринг** - публичные ссылки с возможностью установить срок действия и пароль
- 📱 **Responsive дизайн** - отлично работает на мобильных устройствах и десктопе
- 🔐 **Безопасность** - JWT аутентификация, pre-signed URLs для S3

## Технологии

### Backend
- **FastAPI** - современный асинхронный веб-фреймворк
- **SQLAlchemy 2.0** - ORM с асинхронной поддержкой
- **SQLite / PostgreSQL** - база данных (легкая миграция)
- **S3 / MinIO** - хранилище объектов
- **Alembic** - миграции базы данных
- **JWT** - аутентификация

### Frontend
- **React 18** - современная библиотека для UI
- **TypeScript** - типизированный JavaScript
- **Material UI (MUI)** - готовые компоненты с Material Design
- **Vite** - быстрая сборка
- **React Router** - маршрутизация
- **Axios** - HTTP клиент

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

### Предварительные требования

- Docker и Docker Compose
- Node.js 20+ (для разработки фронтенда без Docker)
- Python 3.11+ (для разработки backend без Docker)

### Запуск с Docker Compose (рекомендуется)

1. Клонируйте репозиторий:
```bash
git clone <repository-url>
cd itcloud
```

2. Запустите все сервисы:
```bash
docker-compose up
```

Это запустит:
- Backend API на http://localhost:8000
- Frontend на http://localhost:5173
- MinIO (S3) на http://localhost:9000 (консоль: http://localhost:9001)
- Redis на localhost:6379

3. Откройте браузер и перейдите на http://localhost:5173

### Разработка без Docker

#### Backend

1. Установите зависимости:
```bash
cd backend
pip install poetry
poetry install
```

2. Создайте файл `.env`:
```bash
cp .env.example .env
# Отредактируйте .env с вашими настройками
```

3. Примените миграции:
```bash
poetry run alembic upgrade head
```

4. Запустите сервер:
```bash
poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### Frontend

1. Установите зависимости:
```bash
cd frontend
npm install
```

2. Создайте файл `.env`:
```bash
echo "VITE_API_URL=http://localhost:8000" > .env.local
```

3. Запустите dev сервер:
```bash
npm run dev
```

## Структура проекта

```
itcloud/
├── backend/                 # Python FastAPI backend
│   ├── src/app/
│   │   ├── api/            # API routes
│   │   │   └── v1/         # API v1 endpoints
│   │   ├── services/       # Business logic
│   │   ├── repositories/   # Data access layer
│   │   ├── infra/          # Infrastructure (S3, DB, config)
│   │   └── domain/         # Domain models
│   ├── alembic/            # Database migrations
│   ├── tests/              # Tests
│   └── pyproject.toml      # Python dependencies
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── pages/          # Page components
│   │   ├── services/       # API client
│   │   ├── hooks/          # Custom hooks
│   │   ├── types/          # TypeScript types
│   │   └── theme/          # MUI theme
│   └── package.json        # Node dependencies
├── docker-compose.yml      # Docker Compose configuration
└── CLAUDE.md              # Developer documentation
```

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

После запуска backend, документация доступна по адресу:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## Основные эндпоинты

### Аутентификация
- `POST /api/v1/auth/register` - Регистрация
- `POST /api/v1/auth/login` - Вход
- `GET /api/v1/auth/me` - Получить текущего пользователя

### Файлы
- `GET /api/v1/assets` - Список файлов
- `GET /api/v1/assets/{id}` - Информация о файле
- `DELETE /api/v1/assets/{id}` - Удалить (в корзину)
- `POST /api/v1/assets/{id}/restore` - Восстановить из корзины
- `DELETE /api/v1/assets/{id}/purge` - Удалить навсегда

### Загрузка
- `POST /api/v1/uploads/create` - Создать загрузку
- `POST /api/v1/uploads/{id}/finalize` - Завершить загрузку

### Шаринг
- `POST /api/v1/shares` - Создать публичную ссылку
- `GET /api/v1/shares/{token}` - Получить информацию о ссылке
- `GET /api/v1/shares/{token}/download-url` - Получить URL для скачивания

## Переменные окружения

### Backend
```env
APP_ENV=dev
DATABASE_URL=sqlite+aiosqlite:///./app.db
S3_ENDPOINT_URL=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
MEDIA_BUCKET=itcloud-media
JWT_SECRET=your-secret-key
CORS_ORIGINS=http://localhost:5173
```

### Frontend
```env
VITE_API_URL=http://localhost:8000
```

## Миграция на PostgreSQL

1. Обновите `DATABASE_URL` в `.env`:
```env
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/itcloud
```

2. Примените миграции:
```bash
poetry run alembic upgrade head
```

## Деплой

### Production Build Frontend
```bash
cd frontend
npm run build
```

Файлы будут собраны в `static/` и готовы для хостинга в S3 или через nginx.

### Backend в Production
1. Используйте PostgreSQL вместо SQLite
2. Настройте CORS для вашего домена
3. Используйте сильный JWT_SECRET
4. Настройте SSL/TLS
5. Используйте gunicorn/uvicorn с несколькими воркерами

## Следующие шаги (TODO)

- [ ] Redis + RQ для фоновых задач
- [ ] Генерация превью для фото
- [ ] Генерация постеров для видео
- [ ] Извлечение EXIF данных
- [ ] Альбомы
- [ ] Теги
- [ ] Поиск по метаданным
- [ ] Квоты пользователей
- [ ] Тесты

## Лицензия

MIT

## Поддержка

Для вопросов и предложений создавайте issue в репозитории.