docs: expand README with comprehensive documentation

README.md

@@ -1,60 +1,182 @@
 # Team Status Board
 
-Панель управления статусами команды.
+Панель управления статусами команды — внутренний инструмент для отслеживания состояния сотрудников в реальном времени.
 
-## Стек
+## Возможности
 
-- **Бэкенд:** Python, FastAPI, SQLAlchemy, SQLite
+- ✅ **Просмотр** всех сотрудников команды
-- **Фронтенд:** React, Vite
+- ➕ **Добавление** новых сотрудников (имя, должность)
-- **API:** REST
+- 🔄 **Изменение** статуса в реальном времени без перезагрузки страницы
+- 🗑️ **Удаление** сотрудников из списка
+- 🔔 **Уведомления** о выполненных операциях
+- 📱 **Адаптивный** дизайн
+
+## Стек технологий
+
+### Бэкенд
+- **Python 3.8+**
+- **FastAPI** — современный веб-фреймворк
+- **SQLAlchemy** — ORM для работы с БД
+- **SQLite** — встроенная база данных
+- **Uvicorn** — ASGI сервер
+
+### Фронтенд
+- **React 18** — библиотека UI
+- **Vite** — сборщик и dev-сервер
+- **Axios** — HTTP-клиент
+
+### Инфраструктура
+- **Git** — контроль версий
+- **Bash** — автоматизация запуска
 
 ## Быстрый старт
 
+### Требования
+
+- Python 3.8 или выше
+- Node.js 18 или выше
+- Bash (WSL2 на Windows, Linux или macOS)
+
+### Запуск
+
 ```bash
+# Клонирование репозитория
 git clone <repository-url>
 cd "Team status board"
+
+# Запуск (автоматическая установка зависимостей и запуск)
 ./start.sh
 ```
 
-Приложение будет доступно:
+После запуска приложение будет доступно по адресам:
-- Фронтенд: http://localhost:3000
+- **Фронтенд:** http://localhost:3000
-- Бэкенд API: http://localhost:8000
+- **Бэкенд API:** http://localhost:8000
+- **API документация (Swagger):** http://localhost:8000/docs
 
 ## API Endpoints
 
-| Метод | Endpoint | Описание |
+| Метод | Endpoint | Описание | Статус-код |
-|-------|----------|----------|
+|-------|----------|----------|------------|
-| GET | `/api/employees` | Получить всех сотрудников |
+| `GET` | `/api/employees` | Получить всех сотрудников | 200 |
-| POST | `/api/employees` | Добавить сотрудника |
+| `POST` | `/api/employees` | Добавить сотрудника | 201 |
-| PUT | `/api/employees/{id}/status` | Обновить статус |
+| `PUT` | `/api/employees/{id}/status` | Обновить статус сотрудника | 200 |
-| DELETE | `/api/employees/{id}` | Удалить сотрудника |
+| `DELETE` | `/api/employees/{id}` | Удалить сотрудника | 204 |
+
+### Примеры запросов
+
+**Добавить сотрудника:**
+```bash
+curl -X POST http://localhost:8000/api/employees \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Иван Иванов", "position": "Разработчик"}'
+```
+
+**Изменить статус:**
+```bash
+curl -X PUT http://localhost:8000/api/employees/1/status \
+  -H "Content-Type: application/json" \
+  -d '{"status": "На встрече"}'
+```
+
+**Удалить сотрудника:**
+```bash
+curl -X DELETE http://localhost:8000/api/employees/1
+```
+
+## Доступные статусы
+
+| Статус | Описание | Цвет |
+|--------|----------|------|
+| 🟢 Online | В сети, доступен | Зеленый |
+| 🟡 На встрече | Занят на встрече | Желтый |
+| ⚫ Offline | Не в сети | Серый |
+| 🔵 В отпуске | В отпуске | Синий |
+| 🔴 Болеет | На больничном | Красный |
 
 ## Структура проекта
 
 ```
 .
 ├── backend/
-│   ├── main.py          # FastAPI приложение
+│   ├── main.py              # FastAPI приложение + CRUD
-│   ├── requirements.txt # Python зависимости
+│   ├── requirements.txt     # Python зависимости
-│   └── team_status.db   # SQLite база данных (создается автоматически)
+│   └── team_status.db       # SQLite БД (создается автоматически)
 ├── frontend/
 │   ├── src/
-│   │   ├── App.jsx      # Основной компонент React
+│   │   ├── App.jsx          # Основной React компонент
-│   │   ├── App.css      # Стили
+│   │   ├── App.css          # Стили компонента
-│   │   ├── main.jsx     # Точка входа
+│   │   ├── main.jsx         # Точка входа React
-│   │   └── index.css    # Глобальные стили
+│   │   └── index.css        # Глобальные стили
-│   ├── index.html
+│   ├── index.html           # HTML шаблон
-│   ├── package.json
+│   ├── package.json         # Node.js зависимости
-│   └── vite.config.js
+│   └── vite.config.js       # Конфигурация Vite
-├── .gitignore
+├── .gitignore               # Игнорируемые файлы
-├── start.sh             # Скрипт автозапуска
+├── start.sh                 # Скрипт автозапуска
-└── README.md
+└── README.md                # Документация
 ```
 
-## Статусы
+## Разработка
 
-- Online
+### Ручной запуск бэкенда
-- На встрече
+
-- Offline
+```bash
-- В отпуске
+cd backend
-- Болеет
+python -m venv venv
+source venv/bin/activate  # или venv\Scripts\activate на Windows
+pip install -r requirements.txt
+python main.py
+```
+
+### Ручной запуск фронтенда
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+## Git-гигиена
+
+Проект использует `.gitignore` для исключения:
+- `node_modules/` — зависимости Node.js
+- `venv/` — виртуальное окружение Python
+- `__pycache__/` — кэш Python
+- `*.db` — файлы базы данных
+- `.env` — файлы окружения
+
+Коммиты выполняются атомарно — одно изменение = один коммит.
+
+## Устранение неполадок
+
+### Порт 8000 или 3000 уже занят
+
+Скрипт `start.sh` автоматически освобождает порты. Если это не помогло:
+```bash
+# Linux/WSL
+lsof -i :8000  # найти PID
+kill -9 <PID>
+
+# Windows (PowerShell)
+Get-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess | Stop-Process
+```
+
+### Ошибки при установке зависимостей
+
+```bash
+# Обновить pip
+pip install --upgrade pip
+
+# Очистить кэш npm
+npm cache clean --force
+```
+
+### База данных не создается
+
+Убедитесь, что у скрипта есть права на запись в директорию `backend/`:
+```bash
+ls -la backend/
+```
+
+## Лицензия
+
+Внутренний инструмент, все права защищены.