Barcode Normalization

Scope

Item server normalizes barcode lookup fields when an item is created or updated. The original barcode value is still stored as entered. Normalization writes additional fields used for matching scanned barcodes.

Code references:

Area	File
Create/update write path	`ktpv5-item/src/item/item.service.ts`
Normalization rules	`ktpv5-item/src/libs/barcode-utils.ts`
Barcode lookup helpers	`ktpv5-item/src/item/item.barcode.service.ts`
Item model fields	`ktpv5-item/prisma/schema.prisma`

Stored Fields

Item stores both the raw barcode and normalized lookup fields:

Field	Meaning
`barcode`	Raw item barcode entered by the client.
`barcodeType`	Detected type: `RAW`, `GTIN`, `PLU`, `UPC`, or `EAN`.
`barcodeGTIN`	Normalized GTIN-14 lookup value when the barcode can be converted to GTIN-14.
`barcodePLU`	Normalized PLU lookup value for scale/internal labels.

Create And Update Behavior

createItem(companyId, data) and updateItem(companyId, itemId, data) both:

Validate raw barcode uniqueness through validateBarcode(...).
Call getNormalizedBarcode(barcode).
Save the raw barcode.
Save derived barcodeType, barcodeGTIN, and barcodePLU.

This means new and edited items should always carry normalized lookup fields when their barcode matches a supported pattern.

Normalization Rules

Normalization only runs for digits-only raw barcode strings. If the raw value contains any non-digit character, it is treated as RAW.

Raw barcode shape	Result
7 digits starting with `02`	`barcodeType = PLU`, `barcodePLU = raw barcode`, `barcodeGTIN = null`
13 digits starting with `02`	`barcodeType = PLU`, `barcodePLU = first 7 digits`, `barcodeGTIN = null`
Valid EAN-13	`barcodeType = EAN`, `barcodeGTIN = "0" + barcode`
Valid UPC-A	`barcodeType = UPC`, `barcodeGTIN = "00" + barcode`
Valid GTIN-14	`barcodeType = GTIN`, `barcodeGTIN = barcode`
More than 14 digits starting with `01`, with valid GTIN-14 at digits 3-16	`barcodeType = GTIN`, `barcodeGTIN = extracted GTIN-14`
Anything else	`barcodeType = RAW`, normalized fields are null

Lookup Behavior

Barcode lookup uses normalized fields before falling back to raw matching:

Normalize the scanned barcode.
If a GTIN-14 is available, search barcodeGTIN.
For short 02... or 2... labels, extract a candidate PLU and search barcodePLU.
Fall back to raw barcode matching.

The rapid lookup path follows the same priority but uses narrower selected fields for POS/device use.

Backfill Helper

The item server also exposes a barcode normalization backfill path:

GET /barcode/normalize

It finds items where both barcodePLU and barcodeGTIN are null, runs getNormalizedBarcode(item.barcode), and updates barcodeType, barcodeGTIN, and barcodePLU.

Use this only as an operational backfill helper. Normal create/update flows already write normalized fields.