From 3090ce8b7e5bab67d127688d32e7ca1a46fe2a5f Mon Sep 17 00:00:00 2001 From: Damir Date: Tue, 7 Apr 2026 21:56:44 +0300 Subject: [PATCH] docs: expand README with comprehensive documentation --- README.md | 188 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 155 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 548cc01..372db03 100644 --- 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 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 + +# 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/ +``` + +## Лицензия + +Внутренний инструмент, все права защищены.