Warehouse Module¶

Purpose¶

Manages all physical stock movements: inbound (deliveries/PZ), outbound (shipments/WZ), internal adjustments, and FEFO-based lot management. Owns the stock ledger, LOT lifecycle (creation through depletion), storage rules per item, and supplier relationships. The warehouse is the source of truth for "what do we have and where."

Actors¶

Use Cases — Inbound (Deliveries)¶

WH-UC-01: Create Goods Receipt (PZ — Purchase Receipt)¶

Actor: Magazynier, Admin, Manager Phase: 1

Overview¶

The Magazynier is the primary actor responsible for receiving goods and creating PZ documents. The preferred workflow is barcode-scan-first: the Magazynier scans the product barcode on the delivery packaging and the system auto-fills the item. Manual item selection via search is available as fallback.

Step-by-Step Flow¶

1. Select or create PZ — Magazynier opens a new PZ, selects the supplier.
2. Physical inspection on delivery — before entering data, Magazynier verifies:
3. Delivery note (document from supplier) matches the actual goods on the pallet/box.
4. No visible damage to packaging. Damaged packaging is flagged immediately (see Damaged Packaging Procedure below).
5. Item count / weight checked against delivery note.
6. Scan product barcodes — Magazynier scans the barcode on each item or carton. The system looks up the item in ItemCatalog by EAN/barcode. If not found, falls back to manual item selection.
7. Enter line details per item:
8. Quantity and unit (must match item's storage_unit)
9. Net purchase price per unit (required — used for actual cost calculation in ZPs)
10. Supplier LOT number (optional — stored as reference, supplier-assigned)
11. Production date (optional)
12. Expiry date (required for food items; optional for packaging/services)
13. Warehouse bin location (defaults from WarehouseItemExtension; Magazynier can confirm or override per line)
14. Handle quantity discrepancy — if received quantity differs from delivery note, Magazynier enters the actual received quantity and notes the discrepancy in the free-text field. If discrepancy exceeds 3% of the delivery note quantity, the system flags the PZ for Manager review and prevents auto-approval (see Business Rule BR-WH-PZ-01 below).
15. Approve PZ — Magazynier approves the document. On approval:
16. System generates internal LOT numbers (format: GS-YYYYMMDD-NNNNN).
17. Stock increases immediately per LOT.
18. StockReceived event published (Traceability module records the LOT entry).
19. Print LOT labels — immediately after approval, the system prompts Magazynier to print LOT labels. One label per PZ line. Each label contains:
20. LOT number (human-readable + barcode/QR code)
21. Item name and item code
22. Expiry date
23. Quantity and unit
24. Warehouse bin location
25. Supplier LOT number (if provided)
26. PZ document number
27. Print is recorded in the system (label_printed: true/false, printed_at timestamp, printed_by user ID).

Damaged Packaging Procedure¶

If Magazynier notices damaged packaging on arrival: 1. Mark the affected PZ line as "Packaging damaged." 2. Enter a description of the damage in the free-text field. 3. Attach a photo (optional, Phase 2). 4. System places the LOT on automatic Hold status with reason "Damaged packaging — pending QA inspection." 5. QA Specialist must release the Hold (WH-UC-09) before the LOT can be used in ZPs or shipped. 6. Delivery note discrepancy is recorded for the supplier scorecard (WH-UC-16).

Business rules: 1. Net purchase price is required — no PZ line can be saved without a price (it is used for ZP actual cost calculation). 2. LOT number format is GS-YYYYMMDD-NNNNN where NNNNN is a 5-digit tenant-scoped sequential number (optional yearly reset). 3. One PZ line = one internal LOT; if the same ingredient arrives in two batches with different expiry dates, they must be entered as separate lines. 4. Expiry date is required for all ingredient items — missing expiry blocks PZ approval. 5. supplier_lot is stored separately and may not be unique (suppliers can reuse lot numbers). 6. Auto-numbered PZ: PZ-YYYY-MM-NNNNN. 7. (BR-WH-PZ-01) If received quantity differs from delivery note by more than 3%, the system flags the PZ for Manager review and blocks auto-approval. The Manager must explicitly approve or reject.

Acceptance criteria: - Magazynier can scan a product barcode to fill the item field without typing. - LOT appears immediately in stock after PZ approval. - LOT label (PDF or ZPL for label printer) is printed from PZ confirmation screen; system records whether label was printed. - Quantity discrepancy >3% blocks auto-approval and routes PZ to Manager review queue. - Damaged packaging auto-places LOT on Hold. - Supplier invoice scan (PDF) can be attached to PZ.

WH-UC-02: Supplier Certificate Warning on PZ¶

Actor: System (auto-check on PZ creation) Phase: 1

When user selects a supplier on a PZ, the system checks if the supplier has any active required certificates. If a required certificate is expired or expiring within 30 days: - Expired: warning banner shown; PZ can still be saved (does not block) but warning is logged. - Expiring within 30 days: advisory notice.

Business rules: 1. Certificate expiry does NOT block PZ creation for any item type — it only warns, even for certified organic/halal ingredients. Blocking would prevent production in emergency sourcing scenarios. 2. Warning is recorded in the PZ document and visible in audit history. 3. Certified ingredients: Even for items tagged as organic/halal, expired certificates never block PZ — only warnings generated for compliance tracking

WH-UC-03: Manage Warehouse Item Extension¶

Actor: Admin, Manager Phase: 1

For each item in ItemCatalog, Warehouse module maintains extension data: - Default storage location (zone/bin — e.g., "Cold Storage / B3") - Minimum stock level (alert threshold) - Reorder point (generates "To Order" report entry) - LOT tracking required: yes | no (default: yes for all food items) - Weight and dimensions (for storage planning and CMR/WDT documents) - picking_strategy: FEFO (default) | FIFO. FEFO is mandatory for all ingredient, intermediate, and product type items. FIFO is available for packaging and consumable items where expiry is irrelevant.

Use Cases — Stock Management¶

WH-UC-04: View Stock Levels¶

Actor: Admin, Manager, Magazynier Phase: 1

Dashboard table: item name, current stock (available = total − reserved), unit, bin location, earliest LOT expiry date.

Color indicators: stock < minimum → red; stock < 2×minimum → yellow; OK → green.

Expand item row to see all LOTs with quantities, expiry dates, and current bin location per LOT.

Filters: warehouse, zone, item type, category, supplier, status. Sort: name, stock level, earliest expiry.

Business rules: 1. "Available stock" = total stock − reserved stock (reservations are created when ZPs are approved). 2. Stock can never go below zero — any movement that would cause negative stock is blocked with a clear error.

WH-UC-05: FEFO Lot Selection¶

Actor: System (auto-suggest) + Magazynier/Manager (confirmation) Phase: 1

When any stock release is triggered (ZP material consumption, WZ shipment, picking list), the system suggests LOTs in FEFO order: 1. Filter: item matches, available_quantity > 0, status ≠ Hold. 2. Sort: expiry_date ASC (shortest first); tie-break: PZ date ASC (FIFO). 3. Propose first matching LOT.

If user selects a different LOT (deviating from FEFO), they may optionally provide a reason from a dropdown: "Damaged packaging" | "Quality testing" | "Customer request" | "Other". The deviation is logged (with reason if provided) and included in FEFO deviation audit report.

Picking list integration (WH-UC-18): When Magazynier is doing physical picking via a tablet, the FEFO suggestion is displayed in a scan-friendly format:

"Go to shelf B3 — LOT GS-20260101-00042 — 5 kg"

LOTs near expiry (flagged by Traceability module per TRC-UC-05) are shown with a prominent warning indicator during picking so the Magazynier can prioritize them. If the nearest-expiry LOT is within the warning threshold, a banner is shown before the Magazynier confirms the pick.

Business rules: 1. FEFO is the default and mandatory strategy for all ingredient food items. 2. FEFO can be configured to FIFO per item category (e.g., packaging materials where expiry is irrelevant). 3. Deviations are logged — visible to Admin and Manager in FEFO deviation audit report.

WH-UC-06: Minimum Stock Alerts¶

Actor: System (auto) / Admin, Manager Phase: 1

When stock falls below the minimum level for an item: email alert sent (max once per day per item) and red indicator shown on dashboard. "To Order" report shows all items below reorder point with suggested order quantity.

Alerts can be disabled per item (for seasonal ingredients).

WH-UC-07: Stock Adjustment (Correction)¶

Actor: Admin, Manager Phase: 1

Manual correction when physical count differs from system stock (e.g., damage, spillage not linked to a ZP, or LOT disposal). Adjustment requires: item, LOT, quantity change (positive or negative), reason (required — dropdown + optional free text), and Admin/Manager role.

Reason options: physical count correction | spillage | expired | quality rejection | damaged | utilized | for industry use | other

• utilized — LOT used as animal feed or industrial input (non-food end use)
• for industry use — LOT sold or given to a non-food industrial buyer

LOT disposal: To permanently remove a LOT from stock (e.g., expired goods, QA-rejected material), Admin/Manager creates a negative stock adjustment equal to the full remaining quantity with reason expired, quality rejection, or damaged. This brings the LOT quantity to zero and creates an immutable disposal record.

Business rules: 1. Negative adjustment cannot bring LOT quantity below zero. 2. Adjustments are logged permanently (who, when, reason, old quantity, new quantity). 3. Adjustment does not generate a ZP record — it is a direct stock correction.

WH-UC-08: Inventory Count¶

Actor: Admin, Manager, Magazynier Phase: 1

Standard (Full) Inventory¶

Create inventory session (full count, or selective by warehouse/zone/category). Export to Excel with current system quantities for manual physical count. Import results (Excel or direct entry). System calculates differences (overages and shortages with values). Approve correction — saves a correction document.

Scan-Based Counting Mode (Magazynier-Friendly)¶

Magazynier uses a barcode scanner or tablet to count without paper: 1. Start inventory session (full or partial by zone/category). 2. Scan LOT barcode → system displays item name, current system quantity, and bin location. 3. Magazynier enters the physical count for that LOT. 4. System immediately shows the difference (e.g., "+2 kg" or "−1 kg") so the Magazynier can recount if the gap is large. 5. Move to next LOT; repeat until all LOTs in the session are counted. 6. Submit session → Manager/Admin reviews and approves corrections.

Partial Inventory (Zone or Category Count)¶

A full warehouse stop is not required. Magazynier can count a single zone (e.g., "Cold Storage") or a single item category (e.g., "Dairy ingredients") without touching other zones. Results are reconciled only for the counted scope.

Spot Check Mode¶

Count 10 random LOTs (system selects randomly) to verify overall accuracy without a full inventory stop. Result: accuracy score (% of spot-checked LOTs matching system quantity). Useful for routine accuracy audits between full inventory sessions.

Business rules: 1. An active inventory session locks all LOTs within the counted scope — no stock movements (PZ/WZ/temporary reservations/virtual allocations) are allowed on locked LOTs during the session, preventing concurrent changes from invalidating the count. 2. If a Manufacturing ZP requires a locked LOT, the Warehouse operation is rejected with "LOTS_IN_INVENTORY" error — Warehouse module does not know Manufacturing internals and does not auto-redirect. 3. Lock is automatically released when the session is approved or cancelled. 4. Spot check mode does not lock LOTs (read-only comparison).

WH-UC-09: LOT Hold / Quarantine¶

Actor: Admin, Manager, QA Specialist, Magazynier Phase: 1

Mark a LOT as "Hold" (quarantine) with reason and date. Effects: - Held LOTs flagged red in stock view. - ZP attempt to consume held LOT: alert + requires Admin/Manager confirmation to override. - WZ attempt to ship held LOT: hard blockade — no override allowed.

Release from hold: Any role can release with mandatory comment field. Full hold/release history stored on the LOT record.

Business rules: 1. Trial LOTs (is_trial = true) are treated as permanently held for WZ purposes — they cannot be shipped. 2. Hold/release actions are immutable in the audit log. 3. Release from hold is permitted for any authenticated user with mandatory reason comment.

WH-UC-17: Manage Bin Locations¶

Actor: Admin, Manager, Magazynier Phase: 1

Warehouse Structure¶

Warehouses are divided into zones (logical areas with different storage conditions), and each zone is divided into bins/shelves (physical positions). Example structure:

Warehouse: Main
├── Zone: Cold Storage
│   ├── Bin: A1
│   └── Bin: A2
├── Zone: Dry Goods
│   ├── Bin: B1
│   ├── Bin: B2
│   └── Bin: B3
└── Zone: Packaging Materials
    ├── Bin: C1
    └── Bin: C2

Setup and Configuration (Admin/Manager)¶

Admin and Manager can: - Create and name zones (with optional temperature range or storage condition label). - Create bins within zones (with optional capacity in kg or number of pallets). - Assign a default bin to each item via WarehouseItemExtension. - Deactivate bins (e.g., zone under maintenance) — active LOTs on deactivated bins remain visible but a warning is shown.

PZ Bin Assignment (Magazynier)¶

When creating a PZ line, the system pre-fills the bin location from WarehouseItemExtension. Magazynier can confirm or override this default for the specific lot being received (e.g., an item normally stored in B2 may be placed in B3 if B2 is full). The selected bin is stored on the LOT record.

Stock View with Bin Location¶

The stock view (WH-UC-04) shows bin location per LOT. Magazynier can filter stock by zone or bin to see what is on a specific shelf.

Internal Bin Transfer¶

Magazynier can move a LOT from one bin to another without generating a WZ or PZ: 1. Select the LOT to transfer. 2. Select the destination bin. 3. Confirm. System records: LOT ID, from-bin, to-bin, timestamp, user ID. 4. The LOT's bin location is updated immediately.

This creates an immutable transfer record for audit purposes (answers OQ-WH-03 for bin-to-bin moves within the same warehouse).

Business rules: 1. A LOT can only be in one bin at a time. 2. Internal bin transfers are logged and auditable but do not affect stock quantity. 3. A bin can hold multiple LOTs simultaneously (the system does not enforce bin capacity in Phase 1 — capacity is informational only).

WH-UC-20: Cross-Warehouse Transfer¶

Actor: Admin, Manager, Magazynier Phase: 1

Transfer LOTs between two physical warehouse sites (e.g., from "Main Warehouse" to "Cold Storage Annex"). The system generates an internal WZ/PZ document pair for audit purposes.

Flow¶

1. Magazynier selects LOTs to transfer and the destination warehouse.
2. System creates an internal WZ (deducting stock from source warehouse) and a corresponding internal PZ (adding stock to destination warehouse).
3. Stock is affected immediately — no confirmation step at the receiving site.
4. Both documents are linked together and marked as "Internal Transfer" (distinct from customer WZ or supplier PZ).

Business rules: 1. Cross-warehouse transfers generate an internal WZ/PZ pair for full audit trail. 2. Stock effect is immediate — no in-transit state. 3. LOT identity (LOT number, expiry date, purchase price) is preserved across the transfer. 4. Internal WZ/PZ documents are excluded from supplier/customer reports.

Use Cases — Outbound (Shipments)¶

WH-UC-10: Create Shipment (WZ — External Release)¶

Actor: Magazynier, Admin, Manager Phase: 1

Create WZ document: customer, date, line items (product item, quantity, LOT selection). System suggests LOTs via FEFO for each line (same logic as WH-UC-05). WZ approval decreases stock per LOT.

WZ can be linked to a Sales Order (ZS) from CRM or created standalone.

Generate PDF WZ document (logo, customer data, positions, LOT numbers). Auto-numbered: WZ-YYYY-MM-NNNNN. Optional email to customer.

Business rules: 1. Cannot ship held LOTs (hard blockade). 2. Cannot ship trial LOTs (is_trial = true) (hard blockade). 3. Stock quantity must be sufficient — partial WZ requires explicit split or back-order. 4. StockDispatched event published on WZ approval (Traceability module records the outbound movement). 5. WZApproved event published on WZ approval, containing: WZ number, list of dispatched LOTs with quantities, and the linked ZS reference (if the WZ was created from a CRM Sales Order). CRM module consumes this event to update the ZS status to PartiallyShipped or Shipped.

WH-UC-11: Courier Integration¶

Actor: Admin, Manager Phase: 2

From WZ confirmation screen: "Order shipment" button. Select courier: InPost (Paczkomat/Courier API v2) or DPD (Web Services). Enter package dimensions manually. System retrieves tracking number and saves to WZ. Print shipping label (PDF). Tracking status visible on WZ (in transit / delivered).

WH-UC-12: Export WDT and CMR Documents¶

Actor: Admin, Manager Phase: 2

Generate WDT (Intra-EU transfer document) or CMR (transport list) as PDF from WZ and customer data. Fields auto-populated from WZ: shipper/receiver, goods description, quantity, weight, value, Incoterms. Ready for print and manual signature. Not full customs handling — document generation only.

WH-UC-19: Prepare and Dispatch Shipment (WZ Physical Workflow)¶

Actor: Magazynier, Manager Phase: 2

This use case describes the physical dispatch workflow that follows WZ document creation (WH-UC-10). It separates document creation (performed by Manager or Magazynier) from the physical picking and handover (performed by Magazynier).

Dispatch Task Generation¶

When a WZ document is approved, the system automatically creates a Dispatch Task assigned to the Magazynier. The task contains all information needed to physically pick and hand over the goods.

Dispatch Task List¶

Magazynier views a list of dispatch tasks with statuses: Pending → In Progress → Dispatched. Each task shows: deadline, customer name, number of lines, and courier (if configured).

Per-Task Detail View¶

For each dispatch task, Magazynier sees: - Product list with quantities and the LOTs specified in the WZ. - Bin location per LOT (so Magazynier knows exactly where to go). - Customer shipping address. - Courier and any special handling notes. - Deadline for handover.

Physical Picking Confirmation¶

Magazynier physically retrieves each LOT from the shelf and scans its barcode to confirm: - System validates: scanned LOT must match the LOT recorded in the WZ. - If scanned LOT does not match: system blocks confirmation and displays an error ("Wrong batch — WZ requires LOT GS-20260101-00042"). This prevents shipping the wrong batch. - All lines must be confirmed before the task can be completed.

Completion¶

Once all LOTs are scanned and confirmed: - WZ status updates to Dispatched. - Stock is decremented for each confirmed LOT. - If courier integration is active (WH-UC-11): courier label is printed automatically. - Dispatch record is saved: Magazynier user ID, timestamp, list of actual LOTs dispatched.

Business rules: 1. Wrong-LOT protection is a hard block — no override. Magazynier must return the wrong item and retrieve the correct one, or contact Manager to amend the WZ. 2. Partial dispatch is not allowed in Phase 2 — all WZ lines must be dispatched together. Split-WZ must be created at the document level (WH-UC-10). 3. Dispatch confirmation is immutable — once dispatched, the record cannot be edited (only audited).

Use Cases — Returns and Corrections¶

WH-UC-13: Customer Return and Correction Document¶

Actor: Admin, Manager Phase: 2

Create return document: customer, date, line items (product, LOT, quantity, return reason). Returned goods initially placed in "Hold for QC" — not added to available stock. QA decision: - Resaleable: WZ-correction created (adds back to available stock). - Not resaleable: marked "For utilization" (removed from stock permanently).

WZ-correction is linked to the original WZ for traceability.

Use Cases — Production Material Flow¶

WH-UC-18: Generate Picking List for Production¶

Actor: Magazynier, Manager Phase: 1

Trigger¶

When a ZP (Production Order) transitions to Planned status, the Manufacturing module publishes a ZPApproved event. The Warehouse module consumes this event and automatically generates a Picking List for the Magazynier covering all ingredient LOTs needed for that ZP.

Picking List Content¶

The picking list groups ingredients and shows per line: - Ingredient name and item code - Quantity needed (from the ZP BOM) - FEFO-suggested LOT number - Bin location ("Go to shelf B3") - Reserved quantity already allocated to this ZP

Picking List Workflow¶

1. Pending — picking list created automatically on ZPApproved event.
2. In Progress — Magazynier opens the picking list on a tablet and starts picking.
3. For each line: Magazynier physically retrieves the item from the suggested bin, then scans the LOT barcode to confirm the pick.
4. Confirmed picks update the reservation status: from "reserved" to "picked" — marking the specific LOT as physically collected, not just reserved in the system.
5. Completed — all lines confirmed. System sends a "materials ready" notification to the Worker assigned to the ZP, so they know they can start on the production floor.

FEFO Deviation During Picking¶

If Magazynier scans a different LOT than the FEFO-suggested one: - System detects the deviation (different LOT for the same ingredient). - Magazynier may optionally provide a deviation reason (same dropdown as WH-UC-05): "Damaged packaging" | "Quality testing" | "Customer request" | "Other." - Deviation is logged and appears in the FEFO deviation audit report.

LOT Unavailability During Picking¶

If the suggested LOT is not physically available when Magazynier arrives at the shelf (e.g., consumed by another process between picking list creation and physical pick): - System detects insufficient quantity on scanned LOT. - System automatically suggests next FEFO LOT for the same ingredient. - Magazynier confirms the suggested alternative LOT or scans a different one. - If a different LOT is chosen, optional deviation reason can be logged.

Business rules: 1. A picking list is created automatically — Magazynier does not need to create it manually. 2. All LOTs must be physically scanned and confirmed before the picking list status changes to Completed. 3. "Materials ready" notification is sent to the Worker only after the picking list is Completed — Worker does not start picking themselves (BR-WH-12). 4. Picking list is linked to the ZP; if the ZP is cancelled, the picking list is also cancelled and reservations released. 5. LOT substitution during picking does not require Manager approval; system auto-suggests next FEFO alternative.

Use Cases — Supplier Management¶

WH-UC-14: Manage Supplier Base¶

Actor: Admin, Manager Phase: 1

Supplier card: company name, NIP/VAT-EU, address, contacts, category (ingredients / packaging / services).

WH-UC-15: Manage Supplier Certificates¶

Actor: Admin, Manager Phase: 1

Per supplier: certificate list — type (IFS, BRC, ISO 22000, Halal, Organic, etc.), certificate number, issue date, expiry date, status (active / expired), PDF upload.

Alerts: 90, 60, 30 days before expiry → email notification sent to all users with Admin or Manager role, and dashboard warning.

Certificate dashboard view: expired count / expiring <30d / current.

WH-UC-16: Supplier Scorecard¶

Actor: Admin, Manager Phase: 3

Optional delivery rating on PZ completion: 1–5 per criterion (Goods quality, On-time delivery, Documentation, Price/value). Free text comment. Supplier scorecard shows average per criterion over last 12 months. Alert: average < 3/5 over 3 consecutive deliveries.

Business Rules¶

Out of Scope¶

• Item identity (code, name, type, UOM) → owned by ItemCatalog module
• Allergens, nutritional values, yield parameters → owned by Manufacturing module
• Batch genealogy, traceability queries, recall management → owned by Traceability module
• Sale price, pricing tiers, product descriptions → owned by CRM module
• Invoice generation → owned by Invoicing module
• CCP/HACCP quality records → future Quality module (Phase 3)
• Worker (Pracownik) role does NOT create PZ or WZ — that is Magazynier's responsibility. Worker only interacts with materials during ZP execution via the Manufacturing tablet flow.

Open Questions¶