chipcerio/dispatch-module.md

Product Requirements Document (PRD)

Dispatch Module -- Transport Management System

1. Objective

The Dispatch Module is responsible for managing and tracking dispatch operations, including assigning transport units, linking trip tickets, and associating invoices for billing and operational visibility.

It serves as the bridge between operations (Fleet/Dispatch) and revenue (Billing/Accounting).

2. Users

Dispatcher -- creates and manages dispatch records
Operations Manager -- monitors dispatch activities
Billing/Accounting Team -- references invoices tied to dispatch
Fleet Manager -- ensures correct unit assignment

3. Scope

In Scope

Create, update, view Dispatch records
Link Dispatch to Trip Tickets
Attach one or multiple Invoices to a Dispatch
Basic filtering and listing

Out of Scope (for now)

Route optimization
Real-time GPS tracking
Automated dispatching

4. Data Model

4.1 Dispatch Entity

Field	Type	Description
dispatch_id	UUID / String	Unique identifier
trip_ticket_id	UUID / String	Reference to Trip Ticket
datetime	DateTime	Dispatch schedule or execution time
unit	String / FK	Assigned vehicle/unit
date_created	DateTime	Record creation timestamp
created_by	User ID	Creator of dispatch

5. Core Features

5.1 Create Dispatch

Input:

Trip Ticket ID (required)
Datetime (required)
Unit (required)

Auto-fill:

Dispatch ID
Date Created
Created By

5.2 Add / Link Invoices to Dispatch

Attach existing invoices OR create new ones
Multiple invoices allowed per dispatch

5.3 View Dispatch List

Table view with:

Dispatch ID
Trip Ticket ID
Unit
Datetime
Number of Invoices

Filters:

Date range
Unit
Customer (via invoice)
Created by

5.4 View Dispatch Details

Show:

Dispatch info
Linked Trip Ticket
List of Invoices

Actions:

Add/remove invoices
Edit dispatch (restricted fields)

5.5 Update Dispatch

Editable fields:

Datetime
Unit

Non-editable:

Dispatch ID
Created By
Date Created

5.6 Delete Dispatch

Soft delete (recommended)
Prevent deletion if invoices are already processed (optional rule)

6. Permissions & Roles

Action	Dispatcher	Manager	Billing
Create Dispatch	Yes	Yes	No
Edit Dispatch	Yes	Yes	No
View Dispatch	Yes	Yes	Yes
Add Invoice	Yes	Yes	Yes
Delete Dispatch	Limited	Yes	No

7. Business Rules

A Dispatch must have exactly 1 Trip Ticket
A Dispatch must have at least 1 Invoice before completion
A Unit cannot be double-booked at the same datetime (optional constraint)
Invoice must belong to a valid Sales Order
Dispatch datetime cannot be in the past (optional depending on ops)

8. API Design (Sample)

Dispatch APIs

POST /dispatch
GET /dispatch
GET /dispatch/:id
PATCH /dispatch/:id
DELETE /dispatch/:id

Invoice Linking

POST /dispatch/:id/invoices
DELETE /dispatch/:id/invoices/:invoiceId

9. UI/UX Notes

Dispatch List Page

Table with filters
Quick actions: View, Edit

Dispatch Detail Page

Header: Dispatch info
Section: Trip Ticket
Section: Invoices (list + add button)

10. Edge Cases

Dispatch created without invoices -> mark as Pending
Invoice linked to multiple dispatches -> Not allowed (recommended)
Unit reassignment conflicts
Trip ticket already used -> enforce uniqueness (optional)

11. Future Enhancements

GPS tracking integration
Automated dispatch assignment
Driver assignment
Status tracking (Planned -> In Transit -> Completed)
Integration with Accounting module

12. Suggested Status Flow (Optional)

Draft -> Scheduled -> Dispatched -> Completed -> Closed

Engineering Insight

Since you're using:

NestJS
Supabase / Postgres

You should:

Model Dispatch <-> Invoice as one-to-many relation
Use foreign keys + indexes on:
- trip_ticket_id
- unit
- datetime
Add composite index:
```
(unit, datetime)
```
-> prevents double booking