docs: expand README with comprehensive documentation

2026-04-07 21:56:44 +03:00
parent 0e05143fd9
commit 3090ce8b7e
1 changed files with 155 additions and 33 deletions
--- a/README.md
+++ b/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
- Бэкенд API: http://localhost:8000
+После запуска приложение будет доступно по адресам:
+- **Фронтенд:** http://localhost:3000
+- **Бэкенд API:** http://localhost:8000
+- **API документация (Swagger):** http://localhost:8000/docs

 ## API Endpoints

-| Метод | Endpoint | Описание |
-|-------|----------|----------|
-| GET | `/api/employees` | Получить всех сотрудников |
-| POST | `/api/employees` | Добавить сотрудника |
-| PUT | `/api/employees/{id}/status` | Обновить статус |
-| DELETE | `/api/employees/{id}` | Удалить сотрудника |
+| Метод | Endpoint | Описание | Статус-код |
+|-------|----------|----------|------------|
+| `GET` | `/api/employees` | Получить всех сотрудников | 200 |
+| `POST` | `/api/employees` | Добавить сотрудника | 201 |
+| `PUT` | `/api/employees/{id}/status` | Обновить статус сотрудника | 200 |
+| `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 приложение
-│   ├── requirements.txt # Python зависимости
-│   └── team_status.db   # SQLite база данных (создается автоматически)
+│   ├── main.py              # FastAPI приложение + CRUD
+│   ├── requirements.txt     # Python зависимости
+│   └── team_status.db       # SQLite БД (создается автоматически)
 ├── frontend/
 │   ├── src/
-│   │   ├── App.jsx      # Основной компонент React
-│   │   ├── App.css      # Стили
-│   │   ├── main.jsx     # Точка входа
-│   │   └── index.css    # Глобальные стили
-│   ├── index.html
-│   ├── package.json
-│   └── vite.config.js
-├── .gitignore
-├── start.sh             # Скрипт автозапуска
-└── README.md
+│   │   ├── App.jsx          # Основной React компонент
+│   │   ├── App.css          # Стили компонента
+│   │   ├── main.jsx         # Точка входа React
+│   │   └── index.css        # Глобальные стили
+│   ├── index.html           # HTML шаблон
+│   ├── package.json         # Node.js зависимости
+│   └── vite.config.js       # Конфигурация Vite
+├── .gitignore               # Игнорируемые файлы
+├── start.sh                 # Скрипт автозапуска
+└── 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/
+```
+
+## Лицензия
+
+Внутренний инструмент, все права защищены.