Traceability Module¶

Purpose¶

Owns batch genealogy (the immutable record of which input LOTs went into which output LOTs) and provides fast forward/backward trace queries and recall management workflows. This module is the investigative and regulatory layer over the stock movement data created by Warehouse and Manufacturing. It does not own stock — it builds a genealogy graph from movement events published by other modules.

Actors¶

Use Cases¶

TRC-UC-01: Build and Maintain Batch Genealogy¶

Actor: System (auto — event-driven) Phase: 1

The Traceability module listens to events published by Warehouse and Manufacturing: - StockReceived (from Warehouse PZ approval) → records: LOT created, item, supplier, date, quantity - MaterialConsumed (from ZP execution) → records: input LOT consumed, quantity, linked ZP - ProductionLOTCreated (from ZP completion) → records: output LOT created, linked to all input LOTs from that ZP - StockDispatched (from WZ approval) → records: LOT shipped, customer, date, quantity

Each genealogy link (input LOT → output LOT) is recorded as an immutable fact once the ZP completes. Links cannot be edited or deleted.

Business rules: 1. Genealogy links are immutable once recorded — no corrections possible (any error in source events propagates to genealogy as-is) 2. Traceability module does not own stock quantities — it only records movement events for query purposes 3. System-level items (is_system = true) are included in genealogy with the same rules

TRC-UC-02: Backward Trace Query¶

Actor: Admin, Manager, QA Specialist Phase: 1

"What went into this finished product LOT?"

Input: a finished good or semi-finished LOT number.

System traverses genealogy backward: 1. Find the ZP that produced this LOT 2. List all ingredient LOTs consumed in that ZP (with quantities, suppliers, PZ dates, expiry dates) 3. For each semi-finished ingredient LOT: recursively trace its own inputs (up to 10 levels)

Display: tree visualization + flat list. Response time target: < 5 seconds.

Business rules: 1. Maximum trace depth: 10 levels (covers any realistic multi-level BOM with buffer) 2. If any genealogy link is missing (e.g., LOT pre-dates the system), trace shows partial result with gap warning — does NOT refuse to run 3. Query is read-only — no state changes

TRC-UC-03: Forward Trace Query¶

Actor: Admin, Manager, QA Specialist Phase: 1

"Where did this raw material LOT end up?"

Input: any LOT number (typically an ingredient/raw material LOT).

System traverses genealogy forward: 1. Find all ZPs where this LOT was consumed 2. For each ZP: find the output LOT(s) produced 3. For each output LOT: find all WZ shipments (with customer, date, quantity) 4. Recurse if output LOT was used as ingredient in another ZP (semi-finished flow)

Display: tree visualization + flat list of affected customers and shipments. Response time target: < 5 seconds.

Business rules: 1. Forward trace terminates when a LOT appears on a WZ (shipped to customer) or is identified as still in stock (not yet shipped) 2. Held LOTs appear in results clearly marked as "Currently on Hold"

TRC-UC-04: Export Traceability Report¶

Actor: Admin, Manager, QA Specialist Phase: 1

Generate a PDF traceability report from any trace query result. Report generation target: < 30 seconds.

PDF sections: 1. Header: company logo, generation timestamp, operator name, searched LOT 2. Lot data: item name, production date, expiry date, quantity, recipe and version (if FG) 3. Composition: input LOTs with item names, suppliers, supplier LOT numbers, expiry dates, quantities 4. Customers (forward trace only): customer names, shipment dates, WZ numbers, quantities 5. QC results (if Quality module active — Phase 3): CCP measurements linked to the ZP 6. HACCP results (if HACCP module active — Phase 3) 7. Footer: "Generated in GrinSystem [timestamp]"

TRC-UC-05: Expiry Alerts for LOTs Near Expiry¶

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

Daily consolidated email alert for LOTs approaching expiry. Configurable thresholds per item category: - Raw materials: default alerts at 30, 14, 7 days before expiry - Finished goods: default alerts at 7, 3 days before expiry

Dashboard section: "Warning — Expiring Lots" showing item name, LOT number, remaining quantity, expiry date, warehouse location.

Actions available from alert: link to Warehouse module to create a disposal stock adjustment (WH-UC-07). Applicable disposal reasons for end-of-life LOTs from this alert: expired, utilized (used as animal feed or industrial input), for industry use (sold/given to non-food industrial use). Traceability surfaces the alert only; stock changes are owned by Warehouse.

TRC-UC-06: Initiate Recall¶

Actor: Admin, QA Specialist Phase: 2

When a quality or safety issue is identified with a LOT or batch:

1. User searches for the root LOT using the internal GrinSystem LOT number or the supplier LOT number (the supplier_lot field recorded on the PZ). System returns all matching internal LOTs; user confirms the correct one.
2. System automatically runs a forward trace to identify all affected finished good LOTs and shipments
3. User reviews affected list (customers, WZ numbers, quantities, dates)
4. User initiates recall: sets recall reason (safety | quality | labeling | regulatory), severity (Class I: serious health hazard | Class II: health risk unlikely | Class III: no health risk), and description

On recall initiation: - All identified affected LOTs that are still in warehouse are automatically set to "Hold" - RecallInitiated event published (CRM module may use this to trigger customer notifications — Phase 3) - Recall record created with unique recall number: RC-YYYY-MM-NNNNN

Business rules: 1. Only Admin and QA Specialist can initiate a recall 2. A recall cannot be initiated against a LOT that has no genealogy data — user must manually handle pre-system inventory 3. Recall initiation is irreversible — status can progress but recall record cannot be deleted 4. Recall scope includes only directly linked ingredient/child LOTs; cross-contamination/equipment-based LOTs are not automatically included

TRC-UC-07: Manage Recall Workflow¶

Actor: Admin, QA Specialist Phase: 2

Recall lifecycle: Open → In Progress → Closed

Open: recall initiated, affected batches identified, holds placed. User documents: notification channels used (phone, email, public notice), regulatory notifications made (e.g., GIS — Główny Inspektor Sanitarny), timeline.

In Progress: recovery actions tracked — quantities recovered, quantities destroyed, quantities still outstanding. Each action logged with date, responsible person, and quantity.

Closed: all affected products accounted for (recovered or confirmed non-retrievable). Closure requires a summary: total affected quantity, total recovered, total destroyed, regulatory outcome, corrective actions taken. Closure is permitted for: Admin, QA Specialist, and Manager. All three can also manage recall lifecycle actions during In Progress. Only Admin and QA Specialist can initiate a recall (TRC-UC-06).

TRC-UC-08: View Recall History and Reports¶

Actor: Admin, Manager, QA Specialist Phase: 2

List of all recalls with: recall number, root LOT, initiation date, severity class, status, affected customer count, recovered quantity. Filter by status, date range, severity. Export to PDF (audit-ready format).

Business Rules¶

Out of Scope¶

• Stock quantities and physical stock management → owned by Warehouse module
• LOT creation → owned by Warehouse (inbound) and Manufacturing (production output)
• Customer notification workflows → owned by CRM module (Phase 3 — triggered by RecallInitiated event)
• HACCP/CCP quality records → future Quality module (Phase 3)
• Regulatory submission documents → not in scope; system provides data, user submits to authorities manually

Open Questions¶