TRK-006 — Gate Pass PDF with QR Code 🔴

[hajk1]

Generate a gate pass document that authorizes a container to enter or leave a port terminal. This is
a standard document in freight operations.

New endpoint:

• GET /api/v1/freight-orders/{id}/gate-pass — returns PDF (Content-Type: application/pdf)

Gate pass should include:

• Gate pass number (auto-generated, e.g. GP-2025-00042)
• QR code encoding the tracking URL for the order
• Container code with Code 128 barcode
• Container size and type
• Voyage number, vessel name
• Departure port and arrival port
• Customer company name
• Agent name (if AGT-001 is done, otherwise orderedBy)
• Valid date range (departure date ± 3 days for buffer)
• Large bold text: GATE IN or GATE OUT (request param: direction=IN|OUT)

New endpoint parameter:

• GET /api/v1/freight-orders/{id}/gate-pass?direction=IN

Gate pass layout suggestion:

┌─────────────────────────────────────┐
│         *** GATE IN PASS ***        │
│         GP-2025-00042               │
│                                     │
│  Container: MSCU1234567             │
│  |||||||||||||||||||||||| (Code128) │
│  Size: 20ft    Type: DRY           │
│                                     │
│  Voyage: VOY-2025-001              │
│  Vessel: MV Freight Star           │
│  Route: Jebel Ali → Shanghai       │
│                                     │
│  Customer: Acme Trading LLC        │
│  Valid: 2025-03-29 to 2025-04-04   │
│                                     │
│  ┌─────────┐                       │
│  │  QR     │  Scan to track        │
│  │  Code   │                       │
│  └─────────┘                       │
└─────────────────────────────────────┘

Business rules:

• Gate pass can only be generated for orders with status PENDING, CONFIRMED, or IN_TRANSIT
• Return 409 if order is CANCELLED or DELIVERED
• direction parameter is required, return 400 if missing

Acceptance criteria:

• PDF generates with both barcode and QR code
• Direction (IN/OUT) shown prominently
• Valid date range calculated from voyage departure
• Returns 409 for cancelled/delivered orders
• Returns 400 for missing direction parameter
• Test verifies PDF generation for both directions
• Code is formatted

---