+7 922 613 01 54

Екатеринбург

BASICS
📘 Документация проекта
«Цифровая Панель Дороги» (MVP)
1. Общее описание
Система автоматизирует сбор оперативной информации о дорожных событиях (ДТП, работы, погода) и визуализирует их для руководства. Суть: Диспетчеры пишут в Telegram → Данные парсятся и сохраняются в БД → Руководство смотрит Веб-дашборд и скачивает отчеты Word.
Основные компоненты:
  1. Telegram Бот: Интерфейс ввода данных диспетчерами.
  2. Backend (API): Прослойка между БД и Фронтендом, генератор отчетов.
  3. Frontend (Web): Дашборд, графики, журнал событий.
  4. Database: PostgreSQL.
2. Стек технологий
  • Язык: Python 3.10+ (Бэкенд/Бот), JavaScript (Фронтенд).
  • БД: PostgreSQL (библиотека asyncpg).
  • Бот: aiogram 3.x.
  • API: FastAPI + Uvicorn.
  • Frontend: React + Vite.
  • UI/Charts: Recharts (графики), Lucide-react (иконки).
  • Отчеты: python-docx.
3. Структура проекта (Папка ROADEMO)
📂 ROADEMO
├── 📄 .env                 # Переменные окружения (Токены, пароли БД) - НЕ ЗАБУДЬ СОЗДАТЬ!
├── 📄 api.py               # Бэкенд: Эндпоинты API и генерация Word
├── 📄 bot.py               # Бот: Логика приема сообщений, парсинг, фото
├── 📄 roads_db.py          # База геометрии дорог (пока используется для привязки КМ)
├── 📄 roads.json           # Данные координат трасс
├── 📂 uploads/             # Папка, куда бот сохраняет фото (создается авто)
│
├── 📂 node_modules/        # Зависимости JS
├── 📄 package.json         # Настройки Frontend
├── 📄 index.html           # Точка входа React
├── 📂 src/
│   ├── 📄 main.jsx         # Монтирование React приложения
│   ├── 📄 App.jsx          # ГЛАВНЫЙ ФАЙЛ ФРОНТЕНДА (Вся верстка и логика тут)
│   └── 📄 App.css          # Стили
│
└── 📄 dashboard.py         # (Legacy) Старый прототип на Streamlit. НЕ ИСПОЛЬЗОВАТЬ.
4. База Данных (Схема)
Используется PostgreSQL. Основные таблицы:
events (Главная таблица событий)
  • id: Primary Key
  • event_type: Тип (ДТП, Работы, Погода...)
  • road_name, km: Местоположение
  • description: Текст описания
  • status: Статус (Новое, В работе, Завершено)
  • injured, dead: Статистика пострадавших (Integer) — Важно!
  • tg_message_id: ID сообщения в ТГ (для связки Reply)
  • tg_chat_id: ID чата
  • created_at: Таймштамп
event_updates (История переписки)
  • event_id: FK на events
  • text: Текст уточнения
event_attachments (Фото)
  • event_id: FK на events
  • file_path: Путь к файлу на диске (например uploads/uuid.jpg)
5. Ключевая логика работыА. Ввод данных (Bot)
  1. Создание: Диспетчер нажимает кнопку, выбирает тип и трассу, вводит КМ.
  2. Парсинг: Бот ищет в описании фразы типа "пострадавших 2", "погибших 1" и пишет их в колонки injured/dead.
  3. Уточнения: Диспетчер делает Reply (Ответ) на сообщение бота.
  • Если текст — добавляется запись в историю + обновляется статус (если есть слова "устранено", "в работе").
  • Если фото — сохраняется в папку uploads/ и привязывается к событию.
Б. Отображение (Frontend + API)
  1. Frontend опрашивает API (/events и /stats/chart) каждые 3 секунды.
  2. Плитки KPI: Фильтруют таблицу по клику (ДТП, Работы, Погода и т.д.).
  3. Модальное окно: При клике на строку таблицы открывается попап с деталями, фото и историей переписки.
6. Как запустить проект (Шпаргалка)

Нужно открыть 3 терминала (PowerShell) и запустить процессы параллельно:
Терминал 1: Бэкенд (API)
# Находясь в папке ROADEMO
python -m uvicorn api:app --reload
Терминал 2: Бот
python bot.py
Терминал 3: Фронтенд
npm run dev
(Открыть ссылку http://localhost:5173)
7. Что реализовано на данный момент
  • [x] Полный цикл создания события через Бота.
  • [x] Парсинг количества пострадавших/погибших из текста.
  • [x] Прикрепление фото через Reply.
  • [x] Обновление статуса через Reply ("устранено").
  • [x] Живой дашборд на React с автообновлением.
  • [x] График динамики за 7 дней (реальные данные).
  • [x] Скачивание отчетов в Word (Сутки/Неделя).
  • [x] Фильтрация по клику на плитки KPI.
  • [x] Модальное окно просмотра события.
8. Известные ограничения (To Do)
  1. Карта: В коде есть координаты (lat, lon), но сама карта на фронтенде временно отключена (чтобы не перегружать MVP).
  2. Авторизация: Пока вход на сайт без пароля.
  3. Валидация: Бот верит пользователю на слово (например, при вводе КМ).
Часть 1. Ответ на вопрос: «Как указывать пострадавших?»
Чтобы не усложнять жизнь диспетчерам лишними кнопками и меню, мы научим Бота искать «магические слова» прямо в тексте описания события.
Правило для диспетчеров будет простым:
«При вводе описания просто напишите цифры словами, например: "Столкновение двух авто, пострадавших: 2, погибших: 1"»
Бот сам найдет эти числа и запишет в базу данных в отдельные колонки для статистики.
кран входа. Без пароля (admin / avtodor2026) дальше не пустит.
Made on
Tilda