feat(shipments): implement state model and validation for shipment workflow

core/shipments/README.md

@@ -15,4 +15,58 @@ This module handles shipments that are processed by the lost&found team.
   - **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)
+- 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