feat: capture and parse Despar store-scoped fixture (#78)

* testdata: add Despar store-scoped flyer fixture

* feat: add deterministic Despar fixture parser

* test: verify deterministic Despar fixture parsing

* docs: record Despar store fixture spike

Author: gcomneno

docs/despar-store-fixture-spike.md

@@ -0,0 +1,122 @@
+# Despar store-scoped fixture spike
+
+## Status
+
+Issue #77.
+
+Recommendation: **promote_to_adapter_implementation**.
+
+## Source
+
+Official public flyer URL:
+
+```text
+https://www.despar.it/it/volantino-digitale/191/
+```
+
+Observed store identity from the same store/flyer identity:
+
+```text
+store_id: 191
+store_name: Interspar Montebelluna
+store_address: Via Schiavonesca Priula, 64
+store_locality: Montebelluna (TV)
+```
+
+Observed campaign:
+
+```text
+Sconti dal 20% al 50%
+valid_from: 2026-08-13
+valid_to: 2026-08-26
+```
+
+The public flyer source rendered Montebelluna locality together with the store-scoped `/191/` URL and exposed real offer rows for that campaign.
+
+## Captured fixture
+
+Committed fixture:
+
+```text
+fixtures/despar/store-191-flyer-2026-08-13.txt
+```
+
+SHA-256:
+
+```text
+54607c3e32d3984d68b6889c522cd17486c31361a8e781f1447c5abe24edaf17
+```
+
+The fixture is a deterministic raw excerpt of observed source facts. It deliberately preserves source text rather than translating the content into the canonical grocery schema.
+
+## Real observed offers in fixture
+
+```text
+Riso Carnaroli Scotti | 1 kg | 2,49 € al pz.
+Birra Speciale Pedavena | 500 ml | 1,29 € al pz.
+Olio Extra Vergine di oliva Grezzo Il Casolare Farchioni | 1 L | 9,49 € | 7,59 € al pz. | Sconto extra App -20%
+```
+
+These rows demonstrate deterministic availability of:
+
+- product identity;
+- package/quantity text;
+- current price text;
+- previous/base price text where present;
+- explicit promotion text where present;
+- campaign validity;
+- store/locality scope.
+
+## Parser contract
+
+`grocery_deal_intelligence.despar_fixture` parses only the committed fixture representation.
+
+It does not:
+
+- access the network;
+- infer missing values;
+- decide canonical promotion semantics;
+- decide loyalty requirements;
+- perform canonical admission;
+- invoke AI.
+
+The parser returns immutable dataclasses and retains price/promotion strings as source evidence. `parse_euro_price()` is deliberately narrow and only converts an explicitly present euro amount to `Decimal`.
+
+## Deterministic boundary
+
+```text
+official store-scoped Despar flyer
+        ↓
+raw source excerpt + SHA-256
+        ↓
+deterministic parser
+        ↓
+source evidence only
+```
+
+## Verification
+
+Tests cover:
+
+- fixture SHA-256 identity;
+- store and campaign metadata;
+- real offer parsing;
+- previous/current price preservation;
+- promotion-text preservation;
+- source-text non-mutation;
+- malformed/missing input rejection.
+
+## Recommendation
+
+**promote_to_adapter_implementation**
+
+The source surface has now demonstrated all minimum properties required for a real retailer adapter implementation spike:
+
+- publicly addressable store-scoped source;
+- explicit store identity/locality;
+- explicit campaign validity;
+- reproducible real offer evidence;
+- deterministic parsing without AI;
+- no need to synthesize provenance from separate browsing context.
+
+A production adapter remains a separate issue and must decide retrieval cadence, raw-response preservation, failure behavior, field mapping, and canonical admission independently.

fixtures/despar/store-191-flyer-2026-08-13.txt

@@ -0,0 +1,11 @@
+source_url: https://www.despar.it/it/volantino-digitale/191/
+store_id: 191
+store_name: Interspar Montebelluna
+store_address: Via Schiavonesca Priula, 64
+store_locality: Montebelluna (TV)
+campaign_title: Sconti dal 20% al 50%
+valid_from: 2026-08-13
+valid_to: 2026-08-26
+offer: Riso Carnaroli Scotti | 1 kg | 2,49 € al pz.
+offer: Birra Speciale Pedavena | 500 ml | 1,29 € al pz.
+offer: Olio Extra Vergine di oliva Grezzo Il Casolare Farchioni | 1 L | 9,49 € | 7,59 € al pz. | Sconto extra App -20%

grocery_deal_intelligence/despar_fixture.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from pathlib import Path
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class DesparOffer:
+    product_name: str
+    package_text: str
+    price_texts: tuple[str, ...]
+    promotion_text: str | None
+
+
+@dataclass(frozen=True)
+class DesparFixture:
+    source_url: str
+    store_id: str
+    store_name: str
+    store_address: str
+    store_locality: str
+    campaign_title: str
+    valid_from: str
+    valid_to: str
+    offers: tuple[DesparOffer, ...]
+
+
+def _parse_offer(parts: list[str]) -> DesparOffer:
+    if len(parts) < 3:
+        raise ValueError("Despar offer line must contain product, package, and price")
+
+    product_name = parts[0]
+    package_text = parts[1]
+    tail = parts[2:]
+
+    promotion_text = None
+    if tail and tail[-1].lower().startswith(("sconto ", "offerta ")):
+        promotion_text = tail[-1]
+        tail = tail[:-1]
+
+    if not tail:
+        raise ValueError("Despar offer line must contain at least one price")
+
+    return DesparOffer(
+        product_name=product_name,
+        package_text=package_text,
+        price_texts=tuple(tail),
+        promotion_text=promotion_text,
+    )
+
+
+def parse_despar_fixture_text(text: str) -> DesparFixture:
+    metadata: dict[str, str] = {}
+    offers: list[DesparOffer] = []
+
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("offer: "):
+            parts = [part.strip() for part in line.removeprefix("offer: ").split("|")]
+            offers.append(_parse_offer(parts))
+            continue
+
+        if ": " not in line:
+            raise ValueError(f"Unrecognized Despar fixture line: {line}")
+        key, value = line.split(": ", 1)
+        metadata[key] = value
+
+    required = (
+        "source_url",
+        "store_id",
+        "store_name",
+        "store_address",
+        "store_locality",
+        "campaign_title",
+        "valid_from",
+        "valid_to",
+    )
+    missing = [key for key in required if not metadata.get(key)]
+    if missing:
+        raise ValueError(f"Missing Despar fixture metadata: {', '.join(missing)}")
+    if not offers:
+        raise ValueError("Despar fixture must contain at least one offer")
+
+    return DesparFixture(
+        source_url=metadata["source_url"],
+        store_id=metadata["store_id"],
+        store_name=metadata["store_name"],
+        store_address=metadata["store_address"],
+        store_locality=metadata["store_locality"],
+        campaign_title=metadata["campaign_title"],
+        valid_from=metadata["valid_from"],
+        valid_to=metadata["valid_to"],
+        offers=tuple(offers),
+    )
+
+
+def load_despar_fixture(path: str | Path) -> DesparFixture:
+    return parse_despar_fixture_text(Path(path).read_text(encoding="utf-8"))
+
+
+def parse_euro_price(price_text: str) -> Decimal:
+    token = price_text.split("€", 1)[0].strip().split()[-1]
+    return Decimal(token.replace(".", "").replace(",", "."))

tests/test_despar_fixture.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import hashlib
+from decimal import Decimal
+from pathlib import Path
+
+import pytest
+
+from grocery_deal_intelligence.despar_fixture import (
+    load_despar_fixture,
+    parse_despar_fixture_text,
+    parse_euro_price,
+)
+
+
+FIXTURE = Path("fixtures/despar/store-191-flyer-2026-08-13.txt")
+EXPECTED_SHA256 = "54607c3e32d3984d68b6889c522cd17486c31361a8e781f1447c5abe24edaf17"
+
+
+def test_fixture_hash_is_stable():
+    payload = FIXTURE.read_bytes()
+    assert hashlib.sha256(payload).hexdigest() == EXPECTED_SHA256
+
+
+def test_parses_store_scope_and_campaign_metadata():
+    parsed = load_despar_fixture(FIXTURE)
+
+    assert parsed.source_url == "https://www.despar.it/it/volantino-digitale/191/"
+    assert parsed.store_id == "191"
+    assert parsed.store_name == "Interspar Montebelluna"
+    assert parsed.store_address == "Via Schiavonesca Priula, 64"
+    assert parsed.store_locality == "Montebelluna (TV)"
+    assert parsed.campaign_title == "Sconti dal 20% al 50%"
+    assert parsed.valid_from == "2026-08-13"
+    assert parsed.valid_to == "2026-08-26"
+
+
+def test_parses_real_offer_without_inventing_fields():
+    parsed = load_despar_fixture(FIXTURE)
+    offer = parsed.offers[0]
+
+    assert offer.product_name == "Riso Carnaroli Scotti"
+    assert offer.package_text == "1 kg"
+    assert offer.price_texts == ("2,49 € al pz.",)
+    assert offer.promotion_text is None
+    assert parse_euro_price(offer.price_texts[0]) == Decimal("2.49")
+
+
+def test_preserves_multiple_prices_and_promotion_text():
+    parsed = load_despar_fixture(FIXTURE)
+    offer = parsed.offers[2]
+
+    assert offer.product_name == "Olio Extra Vergine di oliva Grezzo Il Casolare Farchioni"
+    assert offer.package_text == "1 L"
+    assert offer.price_texts == ("9,49 €", "7,59 € al pz.")
+    assert offer.promotion_text == "Sconto extra App -20%"
+    assert parse_euro_price(offer.price_texts[0]) == Decimal("9.49")
+    assert parse_euro_price(offer.price_texts[1]) == Decimal("7.59")
+
+
+def test_parser_is_read_only_for_source_text():
+    text = FIXTURE.read_text(encoding="utf-8")
+    original = text[:]
+
+    parse_despar_fixture_text(text)
+
+    assert text == original
+
+
+def test_rejects_missing_required_metadata():
+    with pytest.raises(ValueError, match="Missing Despar fixture metadata"):
+        parse_despar_fixture_text("offer: Example | 1 kg | 1,00 € al pz.\n")
+
+
+def test_rejects_offer_without_price():
+    text = """source_url: https://example.test/
+store_id: 1
+store_name: Test
+store_address: Test
+store_locality: Test
+campaign_title: Test
+valid_from: 2026-01-01
+valid_to: 2026-01-02
+offer: Product | 1 kg
+"""
+    with pytest.raises(ValueError, match="product, package, and price"):
+        parse_despar_fixture_text(text)