--- id: WF-COM-FUL-010 title: 'Prepare an order''s goods: shipment, release, pick and pack' trigger: Warehouse staff create or progress shipment preparation. product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-COM-FUL-012 moves: - STATE-COM-FUL-005 - STATE-COM-FUL-007 - STATE-COM-FUL-009 crosses: - SVC-COM-FUL-shipping - SVC-COM-FUL-inventory - SVC-COM-FUL-fulfillment idempotency: >- Shipment candidates exclude assigned allocations, and packing checks the unpacked picked remainder. Pick-list exclusion is a precheck rather than a concurrent-membership guarantee. concurrency: >- Candidate selection precedes creation writes. Pick-list exclusion is read before insertion, and database membership uniqueness is per list, so competing list creation can duplicate a shipment line. hops: - 'n': 1 actor_or_service: Shipping API (create) action: >- Select unassigned committed or picked units at a chosen warehouse, group contiguous ranges and retain order shipping facts and unit assignments. anchor: >- services-commerce:modules/shipping/services/fulfillment/shipment-creation.ts:createShipmentFromOrder seam: sync on_failure: Refuse creation when there is no eligible work. left_inconsistent: A refused creation retains no new shipment. observer: Creation response and shipment history. provenance: observed source: >- services-commerce:modules/shipping/services/fulfillment/shipment-creation.ts - 'n': 2 actor_or_service: 'Shipping API (create, second wave)' action: >- Pick filled-backorder allocations under their in-flight obligation during shipment creation. anchor: >- services-commerce:modules/inventory/services/persistence/inventory-allocations.ts:pickUnitsOfLine seam: sync on_failure: Rollback creation on refusal. left_inconsistent: No partial creation survives its transaction. observer: Allocation records. provenance: documented source: 'services-commerce:docs/migrations/shipping/README.md#D-P8S-12' - 'n': 3 actor_or_service: Shipping API (release and pick list) action: >- Release work and gather available warehouse lines into a pick list using their recorded locations. anchor: >- services-commerce:modules/shipping/services/fulfillment/picking.ts:createPickListForWarehouse seam: sync on_failure: Refuse an empty pick candidate set. left_inconsistent: >- Concurrent lists can duplicate membership because the precheck is outside insertion. observer: Pick-list reads. provenance: observed source: >- services-commerce:modules/shipping/services/fulfillment/shipment-creation.ts:releaseShipment - 'n': 4 actor_or_service: Picker action: >- Assign the picker and retain full or short line results, raising a SKU finding for shortages. anchor: >- services-commerce:modules/shipping/services/fulfillment/picking.ts:recordPickOnList seam: sync on_failure: Refuse invalid membership or an already decided line. left_inconsistent: A completed pick result stands independently of later warehouse requests. observer: Inventory finding list. provenance: observed source: 'services-commerce:modules/shipping/services/fulfillment/picking.ts' - 'n': 5 actor_or_service: Packer action: >- Pack eligible unpacked quantities into parcels and derive weights only when content weights are known. anchor: >- services-commerce:modules/shipping/services/fulfillment/packing.ts:packShipment seam: sync on_failure: Reject invalid state or quantities beyond the picked remainder. left_inconsistent: Earlier picking or packing requests remain stored. observer: Shipment preparation history. provenance: observed source: 'services-commerce:modules/shipping/services/fulfillment/packing.ts' branches: - >- Order 360's Create Shipment sends only the chosen lines and notes; the service ships each committed unit of each chosen line including the order's own charged carrier and address. - >- A pick-up choice makes a pick-up shipment including no carrier and no charge. waits: - Stock for backordered units; the floor's work. evidence: - >- services-commerce at c8b66a98: modules/shipping/services/fulfillment/shipment-creation.ts, picking.ts, packing.ts; services/persistence/shipments.ts, pick-lists.ts, packages.ts; docs/migrations/shipping/README.md (D-P8S-12, D-P8S-13, D-P8S-14). - 'react-console at baf6dae3: lib/commerce/order-flows/live.ts:createShipment.' controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Prepare an Order's Goods: Shipment, Release, Pick and Pack ## What It Does Shipment creation gathers eligible unassigned allocations at one warehouse and groups contiguous units. Release makes floor work available, picking records full or short results, and packing distributes picked quantities among parcels. Filled backorders can be picked under their retained obligations during creation. ## The Flow ```mermaid sequenceDiagram participant S as Staff participant H as Shipping API participant I as Allocation ledger S->>H: create shipment for order H->>I: unshipped committed and picked units H->>I: stamp units with lines (pick filled backorders) S->>H: release S->>H: create pick list, claim, pick lines H-->>S: short pick finding when units are missing S->>H: pack into parcels ``` ## When Something Fails Each request can refuse invalid state or quantity without completing that act. Creation and pick-list membership checks do not establish every concurrency guarantee claimed by the draft. Short picks raise stock findings, and the console does not supply a complete warehouse workflow.