# 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