Skip to content

TMS: build shipments from orders on the create-shipment page #328

Closed

Description

@Connor-Finn

Problem

  • Shipping an order forces "custom route". Shipping an order opens the create page with "Use a custom route instead of a lane" forced on and locked. A custom route has no road route, so these shipments get no checkpoints, no route deviation alerts, and only straight lines on the map.
  • Several orders can only be combined through the API (POST /api/v1/orders/batch-convert, mode: combine). There's no way to do it in the app.
  • The Waypoints card isn't connected to the lane. With a lane picked, the lane's stops aren't used, so the shipment's stops can differ from the route that checkpoints and the map follow.
  • Autofilled fields are locked. Fields filled from an order can't be changed.

Scope

  1. An Orders card on the create-shipment page, listing the attached orders. Three ways in:
    • order detail → "Create shipment"
    • orders list → select several → "Ship together"
    • "Add order" on the create page: a search limited to compatible orders (same customer, same origin, same service level, not assigned; only LTL can have more than one)
  2. Editable autofill
    • Attaching orders fills in customer, service level, origin, a drop per distinct destination, the final destination (last drop), earliest pickup and latest delivery dates, and the strictest temperature and hazmat needs.
    • Every field stays editable. A later order only fills empty fields, widens the dates and adds drops; it never overwrites your edits.
    • Saving is refused when a field conflicts with an attached order: a different origin, a different customer, more than one FTL order, or mixed FTL/LTL. These are the same rules the commands enforce.
  3. Choose lane or custom route
    • Lane: stops come from the lane, plus the orders' drops. The route is the lane's. The lane picker puts lanes first whose origin, stops and destination match.
    • Custom route: origin, waypoints and destination, prefilled from the orders. A road route is calculated for the shipment and stored on it (Google Maps server key, see [BUG] At the moment we dont have the right authentication in order to generate a route #196), and recalculated when stops change while the shipment is draft or ready.
    • The Waypoints card only appears for a custom route. With a lane, the stop list shows the lane's stops.
    • An optional "Save as lane" on a custom route, for journeys that repeat.
    • No forced custom route when coming from an order. A matching lane is preselected if there is one; otherwise custom route.
  4. Checkpoints, route deviation alerts and the map use the shipment's own route if it has one, otherwise its lane's.
  5. Adding an order to an existing draft or ready shipment adds its drop as a stop:
    • Custom route: the route is recalculated automatically.
    • Lane: a warning that the stops no longer match the lane, offering "switch to custom route" or "save as new lane".
  6. The API combine endpoint stays for automation. It uses a matching lane if one exists; otherwise it uses a custom route with a calculated route.
  7. Saving creates the shipment through CreateShipmentCommand, then attaches the orders.

Out of scope:

Acceptance criteria

  • "Create shipment" from an order opens the create page with the order attached and its fields filled in, all editable.
  • "Ship together" with two compatible orders for one customer creates one shipment with both attached and a drop for each.
  • Saving is refused on an origin, customer or service level conflict, or more than one FTL order.
  • A custom-route shipment gets a calculated route; its checkpoints and map use it.
  • A lane shipment's stops match the lane's; adding an order with a new drop warns and offers the two options.
  • Every field the Orders card fills in is checked in create and edit mode (per the UI verification rule).

Related: #196, #103, #324, #325, #329

Activity

  1. Connor-Finn commented on Oct 4, 2026

    @Connor-Finn
    CollaboratorAuthor

    Done across #336 (shipment routes), #337 (create page) and #338 (changing shipments). Differences from the plan:

    • "Save as lane" is on the shipment page (when a lane shipment's stops no longer match its lane), not on the create page for custom routes.
    • Also fixed on the way: editing a draft shipment used to delete and recreate its stops, cutting its orders off their drop stops (Keep stops and order links when shipments change; flag lane mismatches (#328) #338).
    • Route planning needs a Google Maps server key in the org's maps settings; without one it is skipped and logged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    TMSTransport management

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions