Модель данных (ER)

Диаграмма отражает основные таблицы MariaDB и связи между ними.

Связи: - users ↔ cargo_requests (1:M) — владелец заявки. - users ↔ dialogue_history (1:M) — история диалога по пользователю. - users ↔ transporter_matches (1:M) — перевозчик в конкретном матче. - users ↔ user_state (1:0..1) — служебное состояние (JSON) для Telegram‑бота. - cargo_requests ↔ transporter_matches (1:M) — матчи по заявке (один перевозчик на заявку по уникальному индексу).

Important

Telegram‑ID (tg_id) может не помещаться в 32‑битный INT, поэтому в MariaDB используйте BIGINT (это соответствует тому, как идентификаторы объявлены в коде Telegram‑бота).

Note

Канонический формат телефона в системе — 380XXXXXXXXX (E.164 без плюса). Телефон в этом виде хранится в users.phone и используется для сопоставления пользователя между сервисами. Формат с плюсом (+380...) применяется только там, где это требуется внешней библиотекой/интеграцией (например, Telethon), и не должен попадать в БД.

Note

Таблица user_state хранит JSON‑состояние, которое Telegram‑бот использует для служебных вещей: последняя роль, previous_response_id, doc‑flow и последние вызовы MCP‑инструментов. Если таблицы нет, бот будет работать, но часть поведения (например, «память» роли после перезапуска) пропадёт.

Таблица request_serials используется MCP‑инструментом send_docx_form для генерации последовательного номера заявки (через автоинкремент id).