c3lf-system-3/core/shipments

Shipment Management

Functional Description

This module handles shipments that are processed by the lost&found team.

Feature List

• Shipment can contain n (often one, but a lostee can also be sent multiple items) items
• Shipment is linked to n tickets (for informative purposes)
• Shipment holds the address of the parcel
• Shipment holds the dhl voucher used
• On creation of a shipment, the agent can activate the features "adress retrieval", "item validation" and/or tracking
  • address retrieval: the lostee recieves a email with publicly accessible link, on this page the user can enter his address.
    • address sanitation
    • address validation
    • automatic state change after successful address entry (-> waiting for shipping)
  • item validation: the lostee recieves a email with publicly accessible link, on this page the user see the images and confirm the items
    • automatic state change after confirmation
  • tracking: the lostee recieves a email with publicly accessible link, on this page the user can enter his address
• Returning parcels could be managed to (e.g. if a shipment is marked as returned, the items will be unfound again)

State Model

The shipment process follows a defined state model to ensure proper workflow and validation:

States

1. CREATED (Initial State)

   • Shipment is created without address, items, or tickets
   • No validation requirements

2. PENDING_REVIEW

   • Items have been added to the shipment
   • Waiting for requester to verify items and/or address
   • Requires specification of what needs to be reviewed:
     • Items only
     • Address only
     • Both items and address
   • Validation requirements depend on review type

3. READY_FOR_SHIPPING

   • All required reviews completed
   • All required fields validated
   • Ready for shipping process

4. REJECTED

   • Shipment was reviewed and rejected
   • Terminal state (no further transitions possible)

5. SHIPPED

   • Package has been shipped
   • Requires complete address information
   • Timestamp of shipping is recorded

6. COMPLETED

   • Package has been delivered
   • Terminal state (no further transitions possible)
   • Timestamp of completion is recorded

State Transitions

• CREATED → PENDING_REVIEW (when items are added, requires specification of review type)
• PENDING_REVIEW → READY_FOR_SHIPPING (when approved and all required reviews completed)
• PENDING_REVIEW → REJECTED (when rejected)
• READY_FOR_SHIPPING → SHIPPED (when marked as shipped)
• SHIPPED → COMPLETED (when marked as delivered)

Validation Rules

• Review requirement must be specified when entering PENDING_REVIEW state
• Address fields are required for shipping-related states (READY_FOR_SHIPPING, SHIPPED, COMPLETED)
• At least one item is required for any state beyond CREATED
• Invalid state transitions will raise validation errors
• Terminal states (REJECTED, COMPLETED) cannot transition to other states
• Approval requires completion of all specified review requirements:
  • For ITEMS review: items must be added
  • For ADDRESS review: all address fields must be complete
  • For BOTH review: both items and complete address are required