<p><b>ТЗ для Backend-разработчика (Laravel/PHP)</b></p><p></p><p></p><p></p><p><b>1) Стек и инфраструктура</b></p><p></p><p><b>Срок : 7 дней </b></p><p><b>Оплата поэтапная. </b></p><p></p><ul><li><p>Язык/Фреймворк: PHP 8.2+, Laravel 10/11.</p></li><li><p>БД: MySQL 8+.</p></li><li><p>Очереди/кэш: Redis (для генерации PDF/отправки ссылок/очередей).</p></li><li><p>Хранилище файлов: локально (storage) с выдачей подписанных временных ссылок на PDF/QR.</p></li><li><p>API-авторизация: Laravel Sanctum (token-based).</p></li><li><p>Таймзона: Asia/Almaty.</p></li><li><p>Документация: Swagger/OpenAPI + Postman-коллекция.</p></li><li><p>Сборка/деплой: .env.example, миграции/сиды, инструкция деплоя.</p></li><li><p>Хостинг: по выбору Заказчика (<a href="http://ps.kz">ps.kz</a> / <a href="http://hoster.kz">hoster.kz</a> / собственный сервер) — поддержать обе опции.</p></li></ul><p></p><p></p><p></p><p><b>2) Роли (минимум для модуля путевых листов)</b></p><p></p><ul><li><p>Суперадмин (офис) — доступ к справочникам и реестрам, выгрузка, просмотр PDF.</p></li><li><p>Старший бригады (моб.) — работает через мобильное приложение; доступ к API мобилки.</p></li></ul><p></p><p></p><p></p><p><b>3) Справочники (админ-панель)</b></p><ul><li><p>Сотрудники: водители-инкассаторы; старшие бригады (ФИО, № служ. удостоверения, привязка к бригаде). CRUD.</p></li><li><p>Автотранспорт: марка (например, JAC SUNRAY C4), гос. номер. (см. дизайн).</p></li><li><p>Маршруты/смены: список маршрутов, номер смены (числовой).</p></li><li><p>Параметры печати: шрифты/макеты (для pixel-perfect PDF).</p></li></ul><p></p><p></p><p></p><p><b>4) Модель данных (основные сущности)</b></p><p></p><ul><li><p>users (id, fio, role, pin_hash для мобилки при необходимости, active).</p></li><li><p>drivers (id, fio, badge_no, brigade_id, active).</p></li><li><p>vehicles (id, brand, plate, active).</p></li><li><p>routes (id, route_no, active).</p></li><li><p>shifts (id, shift_no, active).</p></li><li><p>waybills (id, server_date, shift_no, route_no, chief_id, driver1_id, driver2_id,<br />fuel_left, odometer_start, distance, vehicle_id, vehicle_brand, vehicle_plate,<br />depart_ts, arrive_ts, status, pdf_path, qr_token, created_by, created_at…).<br />Поля соответствуют дизайну экранов: остаток топлива, спидометр (начало смены), пробег за смену вводится вручную; выбор водителей, марка/номер ТС, номер маршрута и смена.</p></li></ul><p></p><p></p><p></p><p><b>5) Бизнес-правила (по договору/ТЗ)</b></p><p></p><ul><li><p>Автоподстановка серверных значений: текущая дата (с сервера), номер смены, номер маршрута.</p></li><li><p>Фиксация времени выезда/заезда по времени устройства (мобилки); сервер сохраняет метки при приёме.</p></li><li><p>PDF путевого листа формируется по согласованному шаблону (Приложение №5); генерируется QR-код со ссылкой на PDF.</p></li><li><p>Оффлайн-поведение: если интернета нет, данные копятся у клиента и будут отправлены автоматически при восстановлении связи; сервер принимает пачки событий без дублей (идемпотентность).</p></li><li><p>Админ-панель: реестр всех сданных листов с фильтрами (период, ФИО старшего, ФИО водителя, номер маршрута, № бригады), быстрый просмотр/скачивание PDF.</p><p></p></li></ul><p></p><p><b>6) REST API (черновик маршрутов)</b></p><p></p><p>Auth</p><p></p><ul><li><p>POST /api/v1/auth/pin-login — вход по PIN/ID (вернёт токен).</p></li><li><p>POST /api/v1/auth/logout</p></li></ul><p></p><p>Справочники (для мобилки, кеш оффлайн)</p><p></p><ul><li><p>GET /api/v1/mobile/dictionaries — сотрудники (водители/старшие), ТС, маршруты, смены (etag/версии).</p></li></ul><p></p><p></p><p>Путевой лист (мобилка)</p><p></p><ul><li><p>GET /api/v1/mobile/waybill/template — сервер возвращает server_date, shift_no, route_no (автоподстановка) и профиль старшего.</p></li><li><p>POST /api/v1/mobile/waybill/save — черновик/обновление (все поля формы).</p></li><li><p>POST /api/v1/mobile/waybill/submit — финализация; сервер генерирует PDF+QR и ставит статус submitted. Возвращает pdf_signed_url, qr_token.</p></li><li><p>GET /api/v1/mobile/waybill/last — один последний отправленный лист для показа на главном экране (каратетка). (История в приложении не требуется.)</p></li></ul><p></p><p>Служебные</p><p></p><ul><li><p>POST /api/v1/mobile/sync/batch — приём пачки событий оффлайн-очереди; Idempotency-Key (header) обязателен. Ответ — статусы/конфликты.</p></li><li><p>GET /api/v1/waybills/{id}/pdf — защищённая выдача PDF по подписанной ссылке (короткий TTL).</p><p></p></li></ul><p>Админ-панель (офис)</p><p></p><ul><li><p>CRUD: /api/v1/admin/drivers, /chiefs, /vehicles, /routes, /shifts</p></li><li><p>Реестр путевых: GET /api/v1/admin/waybills?filters… (+ экспорт XLS/PDF)</p><p></p></li></ul><p></p><p><b>7) Валидации/правила</b></p><p></p><ul><li><p>Числовые поля (fuel_left, odometer_start, distance) — >= 0.</p></li><li><p>При submit: обязательны depart_ts (время выезда) и arrive_ts (время заезда) — приходят с устройства и сохраняются сервером; arrive_ts >= depart_ts.</p></li><li><p>Водитель(и), смена, маршрут, ТС — обязательны (по дизайну форм).</p></li></ul><p></p><p></p><p><b>8) Генерация PDF и QR</b></p><p></p><ul><li><p>Шаблон PDF — Приложение №5 договора; соответствие макету pixel-perfect.</p></li><li><p>Шрифты и пропись чисел (RU, «тенге/тиын») при необходимости.</p></li><li><p>QR ведёт на защищённую ссылку (подписанный URL, TTL).</p></li></ul><p></p><p></p><p><b>9) Админ-панель (веб)</b></p><p></p><ul><li><p>Авторизация (guard: web), RBAC (admin/superadmin).</p></li><li><p>Справочники (CRUD).</p></li><li><p>Реестр путевых: таблица с полями (дата, смена, маршрут, ФИО, № бригады, ссылка на PDF, QR-ссылка), фильтры (период, ФИО старшего, ФИО водителя, № маршрута, № бригады), поиск, экспорт XLS/PDF, просмотр PDF в браузере.</p></li></ul><p></p><p></p><p><b>10) Логи/аудит/безопасность</b></p><p></p><ul><li><p>Аудит: кто/что/когда изменил в waybill/справочниках.</p></li><li><p>Подписанные URL, HTTPS; rate-limit на API мобилки.</p></li><li><p>Идемпотентность для оффлайн-пакетов (ключ запроса).</p><p></p></li></ul><p><b>11) Сдача/передача</b></p><p></p><ul><li><p>Исходники backend+админка, миграции, сиды, Swagger/Postman, инструкция деплоя.</p></li><li><p>Формат передачи исходников — Git-репозиторий или ZIP-архив (на электронном/физическом носителе) — по выбору Заказчика.</p></li></ul><p></p><p></p><p><b>12) Критерии приёмки</b></p><p></p><ul><li><p>Поля/правила формы соответствуют дизайну (остаток топлива, спидометр-начало, пробег, выбор водителей, смена, маршрут, марка/номер ТС; PIN-логин; сообщения об оффлайне).</p></li><li><p>PDF путевого листа соответствует шаблону; QR работает; список/фильтры и выгрузка на админке — по договору.</p></li></ul>
