Purchase Records Module — ConformaESG Integration Service

Entity: `SupplierPurchaseRecord`

Field	Type	DB Column	Description
`id`	`Long`	`id`	Auto-generated PK
`supplierId`	`Long`	`supplier_id`	FK to `Supplier` (required)
`supplierProductId`	`Long`	`supplier_product_id`	FK to `SupplierProduct` (optional)
`userId`	`Long`	`user_id`	Operator who created the record
`purchaseDate`	`LocalDateTime`	`purchase_date`	Full datetime of purchase (replaces `purchase_year`)
`productDescription`	`String`	`product_description`	Free-text description
`quantityKg`	`Double`	`quantity_kg`	Quantity in kg
`transportMode`	`String`	`transport_mode`	`ROAD`, `SEA`, `AIR`, `RAIL`
`distanceKm`	`Double`	`distance_km`	Transport distance in km
`weightKg`	`Double`	`weight_kg`	Shipment weight in kg
`co2EmissionsKg`	`Double`	`co2_emissions_kg`	Calculated from transport fields
`purchaseOrderNumber`	`String`	`purchase_order_number`	PO reference, max 100 **
`invoiceNumber`	`String`	`invoice_number`	Invoice reference, max 100 **
`ddtNumber`	`String`	`ddt_number`	DDT delivery note, max 100 **
`transactionCertificateNumber`	`String`	`transaction_certificate_number`	GOTS/GRS TC number, max 100 **
`batchNumber`	`String`	`batch_number`	Batch/lot ID — unique per `supplier_id` **
`deliveryDate`	`LocalDateTime`	`delivery_date`	Actual delivery datetime **
`expectedDeliveryDate`	`LocalDateTime`	`expected_delivery_date`	Expected delivery datetime **
`deliveryNotes`	`String`	`delivery_notes`	Delivery notes (max 2000) **
`purchaseStatus`	`PurchaseStatus`	`purchase_status`	Status enum, default `ORDERED` **
`notes`	`String`	`notes`	General notes
`createdAt`	`LocalDateTime`	`created_at`	Auto-set
`updatedAt`	`LocalDateTime`	`updated_at`	Auto-set

Purchase Status Lifecycle

Shell
ORDERED → IN_TRANSIT → DELIVERED
       ↘              ↗
        CANCELLED ←──

Status	Meaning
`ORDERED`	Purchase placed, awaiting shipment. Default.
`IN_TRANSIT`	Goods dispatched from supplier
`DELIVERED`	Goods received at destination
`CANCELLED`	Order cancelled

Entity: `PurchaseStatusChangeLog`

— Created automatically by the service whenever purchaseStatus changes. Not exposed via a REST endpoint yet.

Field	Type	Description
`purchaseId`	`Long`	FK to `SupplierPurchaseRecord.id`
`fromStatus`	`PurchaseStatus`	Previous status (nullable for initial set)
`toStatus`	`PurchaseStatus`	New status
`changedByUserId`	`Long`	From `X-User-Id` header
`changedAt`	`LocalDateTime`	Auto-set via `@CreationTimestamp`

Business Validations

purchaseDate must be between 1900-01-01T00:00:00 and 2100-12-31T23:59:59
deliveryDate must not be before purchaseDate
Document reference fields (purchaseOrderNumber, etc.) must match ^[\p{L}\p{N}][\p{L}\p{N} ./_-]{0,99}$
batchNumber is unique per supplier_id (enforced at DB level)

Automatic CO₂ Calculation

When transport_mode, distance_km, and weight_kg are provided, the service auto-calculates:

Java

co2 = emissionFactor[transportMode] × distanceKm × (weightKg / 1000.0)

Mode	Factor (kg CO₂/tonne·km)
`ROAD`	0.000096
`SEA`	0.000011
`AIR`	0.000602
`RAIL`	0.000028

Entity: SupplierPurchaseRecord

Purchase Status Lifecycle

Entity: PurchaseStatusChangeLog

Business Validations

Automatic CO₂ Calculation

Entity: `SupplierPurchaseRecord`

Entity: `PurchaseStatusChangeLog`