Goal: Item Identifiers

Give every Item a set of externally meaningful identifiers and make items findable by them. Today the Item carries only name and internalSKU (plus supplier-side SKUs); scanned product barcodes have no home — the scan-to-item prototype resorted to stashing them in notes. This project closes that gap on the backend and BFF; UI enablement follows as a separate phase-2 project.

Scope

A. New Item fields

• Standard identifiers (all optional): upc, ean, gtin, isbn, asin — the union of the identifier types handled by the front end’s Amazon search (UPC-A, EAN-8/13, ISBN-10) plus GTIN and ASIN.
• Additional QRs: a list of text values that will be rendered as QR codes for the item.
• Labels: a list of arbitrary free-form text labels (server-enforced limits per DQ-015: at most 128 labels and 64 additional QRs per item, at most 256 characters per entry, no duplicates within a list).

B. New search capabilities

• /lookup — fuzzy matching over the item’s searchable text surface: the curated field set decided in DQ-009 (core descriptive fields, supply references, truncated notes) plus the new identifiers and labels. Follows the shape of the existing /query route family: POST .../lookup?lookup=<string> with a Query body (filter, sort, paginate) and GET .../lookup/{page}?lookup=<string> for subsequent pages.
• /by-code — exact match of a scanned or typed code against any element of the Additional QRs list and any standard identifier, with GTIN-aware normalization so that a scanner’s EAN-13 rendition finds an item stored as UPC-A.

C. Implementation constraints

• Queries must be very performant: the database migration creates the supporting indexes (trigram search document, identifier b-trees, jsonb containment) in the same delivery.
• The QR and label lists are stored as jsonb columns (established Exposed pattern in the demand module).
• Frontend phase-1 scope: BFF routes and TypeScript types for both endpoints, shared identifier validation utilities extended to ASIN and GTIN, and the new fields added to the SSRM/BFF search accessors. No UI changes.

Out of Scope (Phase 2)

Surfacing the new fields and search capabilities in the UI (item form, Items grid, scan flows) is a follow-on project.

References

• Design, Decision Log, Project Plan
• Prototype identifier handling: arda-frontend-app branch callil/pdev-1161-scan-to-item-inspect (src/server/lib/amazon/identifier-mode.ts, enrichment engine identifier namespaces)
• Item domain model