Mini Auth Project

Учебный full-stack проект для изучения авторизации, роутинга и взаимодействия фронтенда с бэкендом.

Стек:

• Backend — Python · FastAPI · JWT-like токены · HttpOnly cookies
• Frontend — React 19 · TypeScript · Vite · Zustand · TanStack Query

mini-project/
├── backend/          # FastAPI — порт 8000
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
└── frontend/         # React + Vite — порт 5173
    ├── src/
    │   ├── pages/    # LoginPage, ProfilePage, AdminPage
    │   ├── stores/   # Zustand: authStore
    │   ├── api/      # axios-клиент, auth.ts, users.ts
    │   └── hooks/    # useSessionRestore
    ├── package.json
    └── Dockerfile

---

Быстрый старт — Docker Compose

Самый простой способ запустить всё одной командой. Docker поднимет бэкенд и фронтенд вместе, настроит сеть между ними и включит hot-reload.

Требования

• Docker Desktop (включает docker compose)

Запуск

docker compose up --build

Флаг --build пересобирает образы при каждом запуске — это нужно, если вы меняли Dockerfile или package.json. Для последующих запусков без изменений можно использовать просто docker compose up.

После запуска:

Сервис	URL
Frontend	http://localhost:5173
Backend	http://localhost:8000
API docs	http://localhost:8000/docs

Тестовые пользователи

Логин	Пароль	Роль
admin	admin123	admin
alice	alice123	user
bob	bob123	user

⚠️ Данные хранятся в памяти — при перезапуске сбрасываются. Это нормально для учёбы.

Остановка

docker compose down

---

Запуск вручную (без Docker)

Удобно для разработки, особенно если хотите полноценную поддержку IDE.

Backend (Python)

cd backend

Создание виртуального окружения:

python -m venv venv

python -m venv venv создаёт изолированную папку venv/ внутри проекта со своей копией Python и pip. Это нужно, чтобы зависимости проекта не конфликтовали с другими проектами на вашем компьютере — у каждого проекта своя "песочница".

Активация окружения:

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

После активации в начале строки терминала появится (venv) — это значит, что теперь python и pip работают внутри изолированного окружения, а не глобально. Все пакеты, установленные через pip install, попадут только в эту папку.

Установка зависимостей и запуск:

pip install -r requirements.txt
uvicorn main:app --reload

Бэкенд будет доступен на http://localhost:8000

---

Frontend (React + Vite)

cd frontend

Для управления версиями Node.js рекомендуется использовать nvm — это позволяет легко переключаться между версиями Node в разных проектах.

Установка nvm:

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

После установки перезапустите терминал, затем:

nvm install 20       # установить Node.js 20 LTS
nvm use 20           # переключиться на эту версию

Установка зависимостей и запуск:

npm install
npm run dev

Фронтенд будет доступен на http://localhost:5173

---

VS Code — Go to Definition

Чтобы работал переход по коду (F12 / Ctrl+Click / Cmd+Click), нужна правильная настройка TypeScript.

1. Установите расширение ESLint и TypeScript и JavaScript Language Features (встроено в VS Code)
2. Откройте папку frontend/ как корень проекта в VS Code (важно — именно frontend/, там лежит tsconfig.json)
3. Убедитесь, что установлены зависимости: npm install

После этого VS Code подхватит tsconfig.json и Go to Definition будет работать для всех .ts и .tsx файлов.

💡 Если переход не работает — откройте любой .tsx файл и нажмите Ctrl+Shift+P → "TypeScript: Restart TS Server"

---

API endpoints

Метод	Путь	Доступ	Описание
POST	/api/auth/login	Все	Логин, возвращает access_token
POST	/api/auth/refresh	Все	Обновить токен через cookie
POST	/api/auth/logout	Авторизованные	Выйти из аккаунта
GET	/api/users/me	Авторизованные	Текущий пользователь
GET	/api/users	Только admin	Список всех пользователей
POST	/api/users	Только admin	Создать пользователя
DELETE	/api/users/{username}	Только admin	Удалить пользователя

Интерактивная документация: http://localhost:8000/docs

---

Что изучается в этом проекте

• Access + Refresh токены — как работает двухтокенная авторизация
• HttpOnly cookie — почему refresh_token нельзя украсть через JS
• Zustand — простое глобальное состояние (authStore)
• TanStack Query — кэширование и синхронизация серверных данных
• Роутинг вручную — гарды без react-router, через useState
• FastAPI — декларативные эндпоинты, Depends, Pydantic-схемы