Purchase Records Module — ConformaESG Integration Service

Entity: `SupplierPurchaseRecord`

Field	Type	DB Column	Description
`id`	`Long`	`id`	Auto-generated PK
`companyId`	`Long`	`company_id`	Company making the purchase
`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
`productDescription`	`String`	`product_description`	Free-text description
`quantityKg`	`Double`	`quantity_kg`	Quantity in kg
`consumedKg`	`Double`	`consumed_kg`	Quantity consumed
`currentStockKg`	`Double`	`current_stock_kg`	Current stock
`purchaseValueEur`	`Double`	`purchase_value_eur`	Purchase value in EUR
`transportMethod`	`String`	`transport_method`	`ROAD`, `SEA`, `AIR`, `RAIL`
`distanceKm`	`Double`	`distance_km`	Transport distance in km
`distanceSource`	`String`	`distance_source`	How distance was determined
`transportEmissionsTco2`	`Double`	`transport_emissions_tco2`	Calculated from transport fields
`emissionFactorUsed`	`String`	`emission_factor_used`	Factor used for calculation
`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
`metadata`	`Map<String, Object>`	`metadata`	Arbitrary JSON key-value pairs
`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. Accessible via GET /api/v1/purchases/{id}/status-changes.

Field	Type	Description
`purchaseId`	`Long`	FK to `SupplierPurchaseRecord.id`
`fromStatus`	`PurchaseStatus`	Previous status (nullable for initial set)
`toStatus`	`PurchaseStatus`	New status
`changedByUserId`	`Long`	From `userId` query parameter
`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_method, distance_km, and related weight fields are provided, the service auto-calculates transport emissions:

Java

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

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

Entity Metadata

The metadata field allows custom attributes on purchase records:

JSON
1{
2  "erp_po_id": "ERP-PO-12345",
3  "customs_declaration": "CD-2025-001",
4  "quality_grade": "A"
5}