Address PR review: clarify article_number docs, repr the bad GTIN, inline the migration helper

Three points from the review, all fair.

The article_number description still read 'Vendor article number, e.g. EAN, QR
code, etc.' in both the request and response schemas. That was the wording this
change exists to retire: with a dedicated gtin column, telling an API consumer to
put an EAN in article_number sends the barcode to the wrong field. Both now point
at gtin for the barcode. The client_v2 help text already said this; the OpenAPI
schema was the half that got missed.

The rejection message interpolated the raw value inside hand-written quotes, so a
scanner that appends a newline or a control character produced a mangled,
multi-line 400 body. !r keeps it on one line and escapes the value properly.

The migration imported normalize_gtin from spoolman.gtin. A migration is a
historical record -- replaying it on a fresh database has to produce what it
produced when it was written -- so it must not change when the application helper
is refactored, nor break if that module is moved. The normalization is now
inlined, with a comment saying why the duplication is deliberate. Re-verified on a
scratch SQLite database seeded with a UPC-12, EAN-13, GTIN-14, EAN-8, two
separator forms, three vendor SKUs, a malformed scan, a bad check digit, a wrong
length and a NULL: identical results to the imported version, article_number
untouched, index present, downgrade clean.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: jpapiez

migrations/versions/2026_08_19_2100-c3a7e1f95d02_filament_gtin.py

@@ -8,14 +8,42 @@
 import sqlalchemy as sa
 from alembic import op
 
-from spoolman.gtin import normalize_gtin
-
 # revision identifiers, used by Alembic.
 revision = "c3a7e1f95d02"
 down_revision = "9c1d5f2a7b31"
 branch_labels = None
 depends_on = None
 
+# The GS1 lengths, and the padded width the column stores.
+#
+# This duplicates spoolman.gtin deliberately. A migration is a historical record: replaying it on
+# a fresh database has to produce what it produced the day it was written, so it must not change
+# underneath us when the application helper is refactored, and must not break if that module is
+# ever moved or renamed. Keep the two in step only if the *definition* of a valid GTIN changes,
+# which it will not -- it is a published GS1 standard.
+_GTIN_LENGTHS = (8, 12, 13, 14)
+_GTIN_STORED_LENGTH = 14
+_DIGITS = "0123456789"
+
+
+def _normalize_gtin(value: str | None) -> str | None:
+    """Return a barcode as its zero-padded 14 digit GTIN, or None if it is not a valid one."""
+    if value is None:
+        return None
+
+    digits = "".join(char for char in value if char in _DIGITS)
+    if len(digits) not in _GTIN_LENGTHS:
+        return None
+
+    # GS1 mod-10: weight the digits 3 and 1 alternating from the right, ignoring the check digit.
+    total = 0
+    for i, char in enumerate(reversed(digits[:-1])):
+        total += int(char) * (3 if i % 2 == 0 else 1)
+    if int(digits[-1]) != (10 - total % 10) % 10:
+        return None
+
+    return digits.zfill(_GTIN_STORED_LENGTH)
+
 
 def upgrade() -> None:
     """Add the filament GTIN column and backfill it from article_number.
@@ -50,7 +78,7 @@ def upgrade() -> None:
     rows = connection.execute(sa.select(filament.c.id, filament.c.article_number)).fetchall()
 
     for row in rows:
-        gtin = normalize_gtin(row.article_number)
+        gtin = _normalize_gtin(row.article_number)
         if gtin is not None:
             connection.execute(sa.update(filament).where(filament.c.id == row.id).values(gtin=gtin))
 

spoolman/api/v1/filament.py

@@ -46,7 +46,7 @@ def _normalize_gtin_param(value: str | None) -> str | None:
         return None
     normalized = normalize_gtin(value)
     if normalized is None:
-        raise ValueError(f"'{value}' is not a valid GTIN.")
+        raise ValueError(f"{value!r} is not a valid GTIN.")
     return normalized
 
 
@@ -85,7 +85,7 @@ class FilamentParameters(BaseModel):
     article_number: str | None = Field(
         None,
         max_length=64,
-        description="Vendor article number, e.g. EAN, QR code, etc.",
+        description="Vendor article number or SKU. For the barcode printed on the packaging, use gtin instead.",
         examples=["PM70820"],
     )
     gtin: str | None = Field(

spoolman/api/v1/models.py

@@ -196,7 +196,7 @@ class Filament(BaseModel):
     article_number: str | None = Field(
         None,
         max_length=64,
-        description="Vendor article number, e.g. EAN, QR code, etc.",
+        description="Vendor article number or SKU. For the barcode printed on the packaging, use gtin instead.",
         examples=["PM70820"],
     )
     gtin: str | None = Field(