Overview
The traceability module provides two complementary mechanisms:
- TraceabilityRecord — lightweight records linking a product to a batch, origin, destination, and compliance status
- ProductTraceability + ProcessingStage — detailed supply chain tracking with ordered processing stages, automatic distance and CO₂ aggregation
Entities
TraceabilityRecord
Simple traceability records for tracking product movement and compliance.
| Field | Type | Description |
|---|---|---|
id | Long | Auto PK |
productId | String | Associated product identifier |
batchNumber | String | Batch/lot number |
origin | String | Origin location |
destination | String | Destination location |
supplierId | Long | FK to Supplier.id |
processingFacility | String | Name of processing facility |
certifications | String | Certifications held |
isCompliant | Boolean | Compliance flag |
userId | Long | Creator user ID |
companyId | Long | Company ID |
notes | String | Notes |
metadata | Map<String, Object> | Custom JSON metadata |
createdAt / updatedAt | LocalDateTime | Timestamps |
ProductTraceability
The aggregate root for detailed product traceability with processing stages.
| Field | Type | Description |
|---|---|---|
id | Long | Auto PK |
userId | Long | Creator user ID |
productId | String | Associated product ID |
pfcrCalculationId | String | External calculation reference |
traceabilityName | String | Name for this traceability record |
description | String | Description |
totalCo2PerKg | Double | Sum of all stage CO₂ (auto-recalculated) |
totalDistanceKm | Double | Sum of all stage distances (auto-recalculated) |
processingStages | List<ProcessingStage> | Ordered child stages (@OneToMany) |
metadata | Map<String, Object> | Custom JSON metadata |
createdAt / updatedAt | LocalDateTime | Timestamps |
ProcessingStage
Individual processing steps in a product's supply chain.
| Field | Type | Description |
|---|---|---|
id | Long | Auto PK |
traceabilityId | Long | FK to ProductTraceability.id |
userId | Long | Creator user ID |
sequenceOrder | Integer | Position in the processing chain |
stageName | String | e.g. Spinning, Dyeing, Cutting |
companyType | String | Type of company performing the stage |
supplierId | Long | Supplier performing this stage |
companyId | Long | Company performing this stage |
internalProcess | Boolean | Whether this is an internal process |
transportMode | String | Transport mode to this stage |
startsFromCompany | Boolean | Whether transport starts from company |
distanceKm | Double | Transport distance from previous stage |
co2Emissions | Double | CO₂ emissions for this stage |
certificationsSnapshot | String | Certifications at this stage |
createdAt / updatedAt | LocalDateTime | Timestamps |
Automatic Totals Recalculation
Whenever a ProcessingStage is added, updated, or deleted, ProductTraceabilityCalculationService automatically recalculates the parent ProductTraceability totals:
totalDistanceKm= sum of all childdistanceKmtotalCo2PerKg= sum of all childco2Emissions
This happens transparently in the service layer — no manual recalculation is needed.
Distance & Emission Calculation
The GeolocationService computes distances using the Haversine formula when company/supplier coordinates are available. The EmissionCalculationService applies configurable emission factors per transport mode:
| Transport Mode | Default Factor (g CO₂ / tonne·km) |
|---|---|
TRUCK | 96 |
SHIP | 11 |
TRAIN | 28 |
PLANE | 602 |
These defaults are configured in application.properties under traceability.emission.factor.*.