Backed и api не сложное для МП

ТЗ для Backend-разработчика (Laravel/PHP)

1) Стек и инфраструктура

Срок : 7 дней

Оплата поэтапная.

• Язык/Фреймворк: PHP 8.2+, Laravel 10/11.

• БД: MySQL 8+.

• Очереди/кэш: Redis (для генерации PDF/отправки ссылок/очередей).

• Хранилище файлов: локально (storage) с выдачей подписанных временных ссылок на PDF/QR.

• API-авторизация: Laravel Sanctum (token-based).

• Таймзона: Asia/Almaty.

• Документация: Swagger/OpenAPI + Postman-коллекция.

• Сборка/деплой: .env.example, миграции/сиды, инструкция деплоя.

• Хостинг: по выбору Заказчика (ps.kz / hoster.kz / собственный сервер) — поддержать обе опции.

2) Роли (минимум для модуля путевых листов)

• Суперадмин (офис) — доступ к справочникам и реестрам, выгрузка, просмотр PDF.

• Старший бригады (моб.) — работает через мобильное приложение; доступ к API мобилки.

3) Справочники (админ-панель)

• Сотрудники: водители-инкассаторы; старшие бригады (ФИО, № служ. удостоверения, привязка к бригаде). CRUD.

• Автотранспорт: марка (например, JAC SUNRAY C4), гос. номер. (см. дизайн).

• Маршруты/смены: список маршрутов, номер смены (числовой).

• Параметры печати: шрифты/макеты (для pixel-perfect PDF).

4) Модель данных (основные сущности)

• users (id, fio, role, pin_hash для мобилки при необходимости, active).

• drivers (id, fio, badge_no, brigade_id, active).

• vehicles (id, brand, plate, active).

• routes (id, route_no, active).

• shifts (id, shift_no, active).

• waybills (id, server_date, shift_no, route_no, chief_id, driver1_id, driver2_id,
  fuel_left, odometer_start, distance, vehicle_id, vehicle_brand, vehicle_plate,
  depart_ts, arrive_ts, status[draft|submitted|synced], pdf_path, qr_token, created_by, created_at…).
  Поля соответствуют дизайну экранов: остаток топлива, спидометр (начало смены), пробег за смену вводится вручную; выбор водителей, марка/номер ТС, номер маршрута и смена.

5) Бизнес-правила (по договору/ТЗ)

• Автоподстановка серверных значений: текущая дата (с сервера), номер смены, номер маршрута.

• Фиксация времени выезда/заезда по времени устройства (мобилки); сервер сохраняет метки при приёме.

• PDF путевого листа формируется по согласованному шаблону (Приложение №5); генерируется QR-код со ссылкой на PDF.

• Оффлайн-поведение: если интернета нет, данные копятся у клиента и будут отправлены автоматически при восстановлении связи; сервер принимает пачки событий без дублей (идемпотентность).

• Админ-панель: реестр всех сданных листов с фильтрами (период, ФИО старшего, ФИО водителя, номер маршрута, № бригады), быстрый просмотр/скачивание PDF.

6) REST API (черновик маршрутов)

Auth

• POST /api/v1/auth/pin-login — вход по PIN/ID (вернёт токен).

• POST /api/v1/auth/logout

Справочники (для мобилки, кеш оффлайн)

• GET  /api/v1/mobile/dictionaries — сотрудники (водители/старшие), ТС, маршруты, смены (etag/версии).

Путевой лист (мобилка)

• GET  /api/v1/mobile/waybill/template — сервер возвращает server_date, shift_no, route_no (автоподстановка) и профиль старшего.

• POST /api/v1/mobile/waybill/save — черновик/обновление (все поля формы).

• POST /api/v1/mobile/waybill/submit — финализация; сервер генерирует PDF+QR и ставит статус submitted. Возвращает pdf_signed_url, qr_token.

• GET  /api/v1/mobile/waybill/last — один последний отправленный лист для показа на главном экране (каратетка). (История в приложении не требуется.)

Служебные

• POST /api/v1/mobile/sync/batch — приём пачки событий оффлайн-очереди; Idempotency-Key (header) обязателен. Ответ — статусы/конфликты.

• GET  /api/v1/waybills/{id}/pdf — защищённая выдача PDF по подписанной ссылке (короткий TTL).

Админ-панель (офис)

• CRUD: /api/v1/admin/drivers, /chiefs, /vehicles, /routes, /shifts

• Реестр путевых: GET /api/v1/admin/waybills?filters… (+ экспорт XLS/PDF)

7) Валидации/правила

• Числовые поля (fuel_left, odometer_start, distance) — >= 0.

• При submit: обязательны depart_ts (время выезда) и arrive_ts (время заезда) — приходят с устройства и сохраняются сервером; arrive_ts >= depart_ts.

• Водитель(и), смена, маршрут, ТС — обязательны (по дизайну форм).

8) Генерация PDF и QR

• Шаблон PDF — Приложение №5 договора; соответствие макету pixel-perfect.

• Шрифты и пропись чисел (RU, «тенге/тиын») при необходимости.

• QR ведёт на защищённую ссылку (подписанный URL, TTL).

9) Админ-панель (веб)

• Авторизация (guard: web), RBAC (admin/superadmin).

• Справочники (CRUD).

• Реестр путевых: таблица с полями (дата, смена, маршрут, ФИО, № бригады, ссылка на PDF, QR-ссылка), фильтры (период, ФИО старшего, ФИО водителя, № маршрута, № бригады), поиск, экспорт XLS/PDF, просмотр PDF в браузере.

10) Логи/аудит/безопасность

• Аудит: кто/что/когда изменил в waybill/справочниках.

• Подписанные URL, HTTPS; rate-limit на API мобилки.

• Идемпотентность для оффлайн-пакетов (ключ запроса).

11) Сдача/передача

• Исходники backend+админка, миграции, сиды, Swagger/Postman, инструкция деплоя.

• Формат передачи исходников — Git-репозиторий или ZIP-архив (на электронном/физическом носителе) — по выбору Заказчика.

12) Критерии приёмки

• Поля/правила формы соответствуют дизайну (остаток топлива, спидометр-начало, пробег, выбор водителей, смена, маршрут, марка/номер ТС; PIN-логин; сообщения об оффлайне).

• PDF путевого листа соответствует шаблону; QR работает; список/фильтры и выгрузка на админке — по договору.