Waybill Document — Full Implementation Notes¶

Date: 2026-02-27 Status: ✅ Backend complete | ✅ Frontend complete | ✅ Migrations applied

Overview¶

Доопрацьовано документ Путній лист (Waybill) — додані три табличні частини та два оборотних регістри пального з логікою проведення.

Табличні частини документа¶

1. Планування завдань (`WaybillTask`)¶

Поле	Тип	Опис
`waybill`	FK(Waybill)	Батьківський документ
`sequence`	int	Порядковий номер
`order`	FK(Order, null)	Прив'язка до замовлення
`point_from`	FK(LocationPoint, null)	Пункт відправлення
`point_to`	FK(LocationPoint, null)	Пункт призначення
`cargo_description`	str(255)	Опис вантажу
`weight`	decimal(10,3)	Вага (т)
`planned_departure`	datetime, null	Планований виїзд
`planned_arrival`	datetime, null	Планований приїзд
`distance_planned`	decimal(10,2)	Планована відстань (км)
`notes`	text	Примітки

API: GET/POST /api/v1/fleet/waybill-tasks/?waybill={id}

2. Результати роботи (`WaybillWorkResult`)¶

Поле	Тип	Опис
`waybill`	FK(Waybill)	Батьківський документ
`sequence`	int	Порядковий номер
`task`	FK(WaybillTask, null)	Прив'язка до завдання
`point_from`	FK(LocationPoint, null)	Фактичний пункт відправлення
`point_to`	FK(LocationPoint, null)	Фактичний пункт призначення
`actual_departure`	datetime, null	Фактичний виїзд
`actual_arrival`	datetime, null	Фактичний приїзд
`distance_actual`	decimal(10,2)	Фактична відстань (км)
`cargo_delivered`	bool	Вантаж доставлено
`notes`	text	Примітки

API: GET/POST /api/v1/fleet/waybill-work-results/?waybill={id}

3. Витрата пального (`WaybillFuelRecord`)¶

Поле	Тип	Опис
`waybill`	FK(Waybill)	Батьківський документ
`sequence`	int	Порядковий номер
`fuel_type`	FK(FuelType)	Вид пального
`quantity_start`	decimal(10,3)	Залишок на початку (л)
`quantity_issued`	decimal(10,3)	Видано (л)
`quantity_end`	decimal(10,3)	Залишок наприкінці (л)
`quantity_consumed`	decimal(10,3)	Авто: start + issued − end
`norm_per_100km`	decimal(8,3)	Норма витрат (л/100км)
`distance`	decimal(10,2)	Пробіг для цього запису (км)
`notes`	text	Примітки

API: GET/POST /api/v1/fleet/waybill-fuel-records/?waybill={id}

Регістри пального¶

FuelJournal — Журнал руху пального¶

Розташування: backend/registers/models/fuel_journal.py API: /api/v1/registers/journals/fuel/

Оборотний журнал — кожна операція фіксується окремим рядком.

Поле	Тип	Опис
`vehicle`	FK(Vehicle)	Транспортний засіб
`fuel_type`	FK(FuelType, null)	Вид пального
`operation_type`	choices	`issue` / `consumption` / `return` / `adjustment`
`quantity`	decimal(10,3)	Кількість (л)
`notes`	text	Примітки
`date`	date	З RegisterModel
`document_type`	str	`'Waybill'`
`document_id`	int	ID документа

FuelLedger — Регістр залишків пального¶

Розташування: backend/registers/models/fuel_ledger.py API: /api/v1/registers/ledgers/fuel/

Оборотний регістр — кумулятивні залишки по ТЗ / виду пального.

Поле	Тип	Опис
`vehicle`	FK(Vehicle)	Транспортний засіб
`fuel_type`	FK(FuelType, null)	Вид пального
`quantity_in`	decimal(10,3)	Надходження (заправка)
`quantity_out`	decimal(10,3)	Витрата
`quantity_balance`	decimal(10,3)	Залишок = prev_balance + in − out

Логіка проведення¶

`POST /api/v1/fleet/waybills/{id}/post_document/`¶

Перевірка статусу (!= posted, != cancelled)
Встановлення status = 'posted'
Для кожного WaybillFuelRecord:
Якщо quantity_issued > 0 → FuelJournal(operation_type='issue', quantity=issued)
Якщо quantity_consumed > 0 → FuelJournal(operation_type='consumption', quantity=consumed)
FuelLedger(quantity_in=issued, quantity_out=consumed, quantity_balance=prev+in-out)

`POST /api/v1/fleet/waybills/{id}/unpost_document/`¶

Перевірка status == 'posted'
Видалення всіх FuelJournal та FuelLedger записів з document_type='Waybill' і document_id=waybill.pk
Встановлення status = 'draft'

Змінені файли¶

Backend¶

Файл	Зміна
`fleet/models/waybill_task.py`	NEW — модель WaybillTask
`fleet/models/waybill_work_result.py`	NEW — модель WaybillWorkResult
`fleet/models/waybill_fuel_record.py`	NEW — модель WaybillFuelRecord (з auto quantity_consumed)
`fleet/models/__init__.py`	Додано 3 нових моделі
`fleet/serializers.py`	Додано 3 нових серіалайзери, WaybillSerializer включає nested `tasks`, `work_results`, `fuel_records`
`fleet/views.py`	Додано `post_document` / `unpost_document` @action, 3 нових ViewSet
`fleet/urls.py`	Зареєстровано waybill-tasks, waybill-work-results, waybill-fuel-records
`fleet/migrations/0003_waybillfuelrecord_waybilltask_waybillworkresult.py`	NEW міграція
`registers/models/fuel_journal.py`	NEW — модель FuelJournal
`registers/models/fuel_ledger.py`	NEW — модель FuelLedger
`registers/models/__init__.py`	Додано FuelJournal, FuelLedger
`registers/serializers.py`	Додано FuelJournalSerializer, FuelLedgerSerializer
`registers/views.py`	Додано FuelJournalViewSet, FuelLedgerViewSet
`registers/urls.py`	Зареєстровано journals/fuel, ledgers/fuel
`registers/migrations/0002_fueljournal_fuelledger.py`	NEW міграція

Frontend¶

Файл	Зміна
`transactionForm.config.ts`	`POSTING_CONFIG.waybills` → `usePostAction: true` + FuelJournal/FuelLedger; додано `MULTI_LINES_CONFIG` для waybills (3 підтаблиці); розширено `LINE_REFERENCE_CONFIG`; додано `LINE_ENTITY_FALLBACKS`; розширено `DATE_KEYS`
`useTransactionData.ts`	Повна переробка: підтримка `MULTI_LINES_CONFIG`, паралельне завантаження metadata для всіх підтаблиць, повернення `multiLinesConfig`, `lineRefConfigMap`, `resolvedLineFieldsMap`, `refDisplayMapsMap`
`useTransactionMutations.ts`	Доданий `activeLinesConfig` параметр; рядкові мутації використовують `activeLinesConfig ?? linesConfig`
`TransactionForm.tsx`	`localLines[]` → `localLinesMap: Record<string, LocalLine[]>`; `editingCell` додано поле `linesCode`; handlers прийомають `linesCode`; render підтаблиць через `allLinesConfigs.map()` (1 або N вкладок)

API Endpoints (нові)¶

# Waybill subtables
GET/POST   /api/v1/fleet/waybill-tasks/
GET/PATCH/DELETE /api/v1/fleet/waybill-tasks/{id}/
GET/POST   /api/v1/fleet/waybill-work-results/
GET/PATCH/DELETE /api/v1/fleet/waybill-work-results/{id}/
GET/POST   /api/v1/fleet/waybill-fuel-records/
GET/PATCH/DELETE /api/v1/fleet/waybill-fuel-records/{id}/

# Waybill posting
POST /api/v1/fleet/waybills/{id}/post_document/
POST /api/v1/fleet/waybills/{id}/unpost_document/

# Fuel registers
GET /api/v1/registers/journals/fuel/
GET /api/v1/registers/ledgers/fuel/

Архітектурні рішення¶

MULTI_LINES_CONFIG (Frontend)¶

Нова конфігурація в transactionForm.config.ts, що дозволяє сутностям мати кілька підтаблиць. Завдяки цьому TransactionForm рендерить вкладки: - details — шапка документа - lines_waybillTasks — Планування завдань - lines_waybillWorkResults — Результати роботи - lines_waybillFuelRecords — Витрата пального

Зворотна сумісність: якщо MULTI_LINES_CONFIG[entityCode] не визначено, система використовує старий LINES_CONFIG[entityCode] (Invoice Lines, Receipt Lines).

Автообчислення quantity_consumed¶

WaybillFuelRecord.save() автоматично обчислює:

quantity_consumed = quantity_start + quantity_issued - quantity_end

Балансування FuelLedger¶

При проведенні кожна нова запис в FuelLedger обчислює баланс від попереднього:

quantity_balance = prev_balance + qty_in - qty_out

При скасуванні — записи видаляються, але перерахунку інших проводок не відбувається (спрощена модель).

Відомі обмеження / TODO¶

[ ] При скасуванні проведення FuelLedger залишки для інших документів не перераховуються (потрібен окремий механізм перебалансування)
[ ] Фільтрація waybill-tasks / waybill-work-results / waybill-fuel-records відбувається через query param ?waybill={id} (записи доступні через TenantFilterMixin, не через вкладені URL)
[ ] quantity_consumed може стати від'ємним — валідація не додана
[ ] Підтримка Zod-валідації для рядків підтаблиць — не реалізована