Shipment Generation

What It Does

The source-reviewed sale:expedition:import path consumes shipment CSV records, creates a Magento shipment with order-item quantities and tracking data, then updates matching Logidav sale lines. A separate tracking synchronizer records normalized tracking-status changes. The reviewed path does not establish carrier-label generation, PDF storage, marketplace propagation, or physical delivery confirmation. See the source-backed order-to-delivery flow for the full evidence boundary.

How It Connects

View diagram source

flowchart LR
    CSV["Shipment import record + carrier CSV"] --> EI["ExpeditionImportCommand"]
    EI --> Parser["Chronopost / GLS / generic CSV dispatcher"]
    Parser --> Match["Match SKU + quantity to unshipped SaleProduct"]
    Match --> Create["SaleService.createShipmentCsv"]
    Create --> Mag["Magento createOrderShipment API"]
    Mag --> Local["Mark Logidav sale lines shipped"]
    Local --> Complete["Complete when every line is shipped or canceled"]
    Local -. "separate path" .-> Track["ShipmentTrackingSynchronizer"]
    Track -. "status history on normalized change" .-> Mag

Diagram

Dashed edges mark the separate tracking record path. This diagram does not show label generation or a carrier API call.

Trigger

Source	Schedule	Purpose
sale:expedition:import	Invocation schedule unknown	Selects pending/processing import records with zero errors and dispatches a file importer.
Order status change	Not established by the reviewed shipment-import path	The source review does not prove an event-driven label-generation trigger.

Components

Component	File Path	Role
ExpeditionImportCommand::runExpedition()	src/AppBundle/Command/Sale/V2/ExpeditionImportCommand.php	Selects import rows, marks a row processing, and dispatches by filename.
SaleExpeditionCsvCommand::execute()	src/AppBundle/Command/Sale/Expedition/SaleExpeditionCsvCommand.php	Matches CSV SKU/quantity rows to unshipped local sale lines and calls shipment creation.
SaleService::createShipmentCsv()	src/AppBundle/Services/SaleService.php	Builds Magento order-item quantities and carrier/tracking data, then calls createOrderShipment().
SaleService::checkSaleAndSetComplete()	src/AppBundle/Services/SaleService.php	Completes the order only when each sale line is shipped or canceled; Menzzo orders are then switched to Magento complete.
ShipmentTrackingSynchronizer::sync()	src/AppBundle/Services/ShipmentTrackingSynchronizer.php	Stores shipment/tracking data and status history when normalized status changes; separate from CSV shipment creation.

Earlier versions of this page listed carrier service classes, label APIs, and PDF paths. Those details were not established as part of the reviewed CSV import path and should not be used as its operational contract.

Shipment Lifecycle

View diagram source

stateDiagram-v2
    [*] --> Pending: Import record selected
    Pending --> Processing: Record marked processing
    Processing --> ShipmentCreated: Magento shipment API accepted
    ShipmentCreated --> LinesShipped: Matching local lines updated
    LinesShipped --> Complete: Every line shipped or canceled
    Processing --> Error: Import throws
    Error --> Error: Not selected by the zero-error query
    LinesShipped --> TrackingUpdate: Separate tracking path
    TrackingUpdate --> TrackingHistory: Normalized status changes

Diagram

ShipmentCreated and Complete are application states; neither means that the parcel was physically delivered.

Step-by-Step Flow

View diagram source

sequenceDiagram
    participant File as Import record and CSV
    participant Cmd as ExpeditionImportCommand
    participant CSV as SaleExpeditionCsvCommand
    participant Sale as SaleService
    participant Mag as Magento sale API
    participant DB as Logidav sale lines

    File->>Cmd: pending/processing row with zero errors
    Cmd->>Cmd: Dispatch by filename
    Cmd->>CSV: Parse supported shipment CSV
    CSV->>CSV: Match SKU and quantity to unshipped sale lines
    CSV->>Sale: createShipmentCsv(order, tracking data)
    Sale->>Mag: createOrderShipment(order-item quantities, carrier/tracking)
    Mag-->>Sale: Shipment API result
    Sale-->>CSV: Return from Magento call
    CSV->>DB: Mark matching lines shipped and record import/tracking fields
    CSV->>DB: Dispatch event and check order completion

Diagram

The source does not establish the underlying Magento wire route or whether every filename-specific importer follows the generic CSV code path.

Carrier-Specific Details

Import dispatch documented by the reviewed command	What is established
Chronopost filename path	A filename can dispatch to the Chronopost importer. The packet does not establish label API behavior or PDF storage.
GLS filename path	A filename can dispatch to the GLS importer. The packet does not establish label API behavior or PDF storage.
Generic CSV path	Matches CSV SKU/quantity rows against unshipped sale lines and creates a Magento shipment.
Other carrier names/services	Missing source evidence for their participation in this command.

Carrier selection and labels

The reviewed file-import path does not establish carrier-selection rules, carrier API label generation, ShippingService rate calculations, or stored PDF labels. Carrier selection has a separate source trace in order-line carrier assignment; it does not establish label generation or carrier acceptance.

Side Effects

Database

• Marks matching local sale lines shipped after the Magento shipment call
• Records carrier, import-file, and shipped-at fields; regenerates track links
• Dispatches SaleProductsShippedEvent and checks the sale completion condition

File System

• Consumes a shipment CSV import record; PDF label creation/storage is not established by the reviewed methods

External Systems

• createOrderShipment() sends order-item quantities plus carrier/tracking data to Magento
• A separate tracking synchronizer records shipment/tracking data and status history on normalized status change
• Marketplace propagation and live tracking-provider synchronization are not established by this source review

Failure Modes

Import failure

If an importer throws, the import record is marked error. The reviewed selector only takes pending or processing rows with zero errors, so this code does not establish automatic retry of that error row.

Remote and local state can diverge

Magento shipment creation occurs before the matching Logidav sale lines are marked shipped. The reviewed code does not establish a cross-system transaction or duplicate-submission guard. Reconcile both sides through the approved owner procedure before replaying a file.

Error rows are not an automatic retry signal

An error import row is not selected by the reviewed zero-error query. The operator workflow for correcting and re-queuing it is not established here.

Shipped is not delivered

The CSV path marks local lines shipped and may complete the order after all lines are shipped or canceled. It does not establish physical delivery. Use the separate tracking evidence and the owning project runbook.

Debugging Path

1. Locate the import record using the approved project procedure; record its filename and current status.
2. Confirm the dispatch path for that filename and whether the importer threw. Do not assume a retry because the record is in error.
3. Compare the matching CSV rows with the order's unshipped sale lines through the approved owner tool.
4. Reconcile Magento and Logidav after an uncertain shipment API result. Avoid resubmitting until the existing shipment state and duplicate behavior are known.
5. Separate shipment from delivery. If the parcel is marked shipped but the customer asks where it is, follow the separate tracking-status path.
6. Use the owning operator's runbook for remote state, logs, or any replay. This page does not authorize production access or changes.

Related Commands

Command	Purpose
sale:expedition:import	Selects and dispatches shipment-file import records; installed cadence is unknown here.
ShipmentTrackingSynchronizer::sync()	Separate tracking-status record path; caller/schedule not established here.
Carrier-specific label commands	Missing evidence in this reviewed import path.

Evidence and Open Questions

The CSV import, Magento createOrderShipment() call, subsequent local shipment-line update, completion condition, and separate tracking-status history are source-verified at axelites/logidav@e0b7a25c1912039c1520eb04c1b4c242d74b6d1e: ExpeditionImportCommand, SaleExpeditionCsvCommand, SaleService shipment/completion methods, and ShipmentTrackingSynchronizer.

Carrier label generation, PDF paths, carrier selection/rating, all-carrier parity, the installed schedule, marketplace propagation, a duplicate guard, and physical delivery confirmation remain unverified.