Behavior-Driven Development¶

This page specifies the acceptance behavior for the User Stories. Each user-story epic becomes a Feature, and each story is expressed as one or more Given / When / Then scenarios.

These are reviewable acceptance examples in Markdown, not executable Gherkin files. A scenario does not imply that the capability is implemented. Scenarios explicitly marked Planned must not be reported as passing until an automated or documented manual check exists.

Feature 1: Scan a product¶

In order to understand a product at the shelf,
as a shopper,
I want to scan its code and receive a useful product passport without signing in.

Scenario 1.1: Resolve a supported product code¶

Given an Anonymous Shopper has a supported GS1 Digital Link URL or retail barcode
And the product exists in the synchronized producer catalog or community cache
When the shopper opens the URL with the phone camera or reads the retail barcode with the in-app scanner
Then a Digital Link preserves its supported encoded qualifiers, while the current retail barcode path resolves GTIN only
And the complete public scan satisfies the target in QAS-1
And no account is required.

Scenario 1.2: Read the digital label¶

Given a resolved product has ingredients, allergens and nutrition data
When the shopper opens its product passport
Then the ingredients, EU allergens and nutrition table are shown clearly
And allergens are visually highlighted
And community-sourced data is marked as unverified.

Scenario 1.3: View the product journey¶

Given a resolved product has traceability data
When the shopper opens the Journey section
Then the system shows the journey as ordered origin, processing and distribution steps
And each available step includes its place and date.

Scenario 1.4: View sustainability information¶

Given a resolved product has sustainability data
When the shopper opens the Eco section
Then the system shows one score from 0 to 100
And the shopper can inspect the CO₂, recyclability, animal welfare, local sourcing and packaging pillars.

Scenario 1.5: Scan an unknown product¶

Given the scanned GTIN is not available from a local or external product source
When the shopper scans it
Then the system shows a clear "We don't know this product yet" state
And offers one action to report or request the product
And never exposes a raw technical error.

Scenario 1.6: Continue after one source fails¶

Given the product identity is available
And one optional data source is unavailable
When the shopper scans the product
Then the available passport sections still render
And only the affected section is marked temporarily unavailable.

Feature 2: My profile and goals¶

In order to receive personalization while controlling sensitive information,
as an account holder,
I want to create and manage a consent-gated health profile.

Scenario 2.1: Create an optional account¶

Given an Anonymous Shopper can already scan without an account
When the shopper chooses to register
Then sign-up requests only the minimum account information
And authentication is handled by the identity provider
And PackyTrace does not store a password itself.

Scenario 2.2a: Grant health-profile consent¶

Given Sara is signed in and has not granted health-profile consent
When she explicitly accepts the current policy
Then the system records the consent timestamp and policy version in the consent ledger
And allows her to create a health profile.

Scenario 2.2b: Decline health-profile consent¶

Given Sara is signed in and has not granted health-profile consent
When she declines the consent request
Then no health profile or health details are saved.

Scenario 2.3: Record and edit allergies and conditions¶

Given Sara has granted health-profile consent
When she selects EU allergens and health conditions
Then the system saves the selected codes
And lets her change them later.

Scenario 2.4: Record dietary preferences and a goal¶

Given Sara has granted health-profile consent
When she selects dietary preferences and a primary goal
Then the system saves the selected codes
And keeps only one primary goal active at a time.

Scenario 2.5a: Delete only the health profile¶

Given Sara has an account and a health profile
When she chooses "delete health profile"
Then the system erases the health profile
And confirms the deletion
And keeps her account usable.

Scenario 2.5b: Delete the whole account: Planned¶

The exact treatment of Fridge and Shopping List event streams is pending a maintainer retention decision. This scenario is not acceptance-ready until that choice is recorded in an ADR.

Given Sara has an account
When she chooses "delete account" and confirms the action
Then the system erases the account-owned data
And nullifies the account link on retained scan records
And retains only already-published privacy-thresholded aggregate batches
And reports completion only after the erasure workflow completes.

Feature 3: Does this fit me?¶

In order to make a quick and safe choice,
as an account holder with a health profile,
I want to receive a personal verdict, prominent safety warnings and goal-fit guidance.

Scenario 3.1a: Show a personal verdict¶

Given Sara is signed in with consent, a health profile and a selected goal
And the scanned product has enough verified label data
When the scan result opens
Then a Good, Be careful or Avoid verdict appears before the other details
And the verdict appears within the scan's 3-second response budget
And Sara can open it to read the reasons.

Scenario 3.1b: Avoid a false positive verdict¶

Given the product label is too incomplete for a safe assessment
When Sara opens the scan result
Then the verdict is Unknown
And it is never silently presented as Good.

Scenario 3.2: Warn about a profile conflict¶

Given Sara's profile contains an allergy, condition or dietary restriction
And the scanned product conflicts with it
When the verdict is computed
Then an allergen match produces an Avoid verdict using color, icon and text
And a condition or diet conflict produces a medium-severity warning with a reason.

Scenario 3.3: Explain goal fit¶

Given Sara has one primary goal
And the product has relevant nutrition data
When the verdict is shown
Then one or two plain-language statements explain how the product supports or conflicts with that goal.

Scenario 3.4: Invite an anonymous shopper to personalize¶

Given an Anonymous Shopper opens a scan result
When no personal profile is available
Then the result explains that a profile enables a personal verdict
And the invitation is dismissible
And it never blocks the product information.

Feature 4: My Fridge¶

In order to use food before it expires and understand waste,
as an account holder,
I want to track the physical products I have at home.

Scenario 4.1: Add a scanned physical item¶

Given Sara is signed in and has scanned a product
When she adds that physical item to her Fridge
Then the system stores its trusted product snapshot and any decoded expiry date
And does not add the same physical item twice
And still permits separate items with the same GTIN.

Scenario 4.2: Order the Fridge by freshness¶

Given Sara's Fridge contains items with different expiry dates
When she opens the Fridge
Then expired and expiring items appear before fresh items
And their states are visually distinct
And freshness is recalculated from the expiry date at view time.

Scenario 4.3: Warn before expiry¶

Given a Fridge item crosses the five-day expiring threshold
When the scheduled freshness check runs
Then the Fridge alert feed contains one reminder for that item and freshness level
And repeated checks do not create duplicate reminders.

Scenario 4.4: Classify an item leaving the Fridge¶

Given Sara has an active Fridge item
When she removes it
Then she must classify it as used or discarded
And the corresponding fact is recorded
And there is no unclassified delete.

Scenario 4.5: View a monthly waste summary¶

Given Sara has used and discarded items during the month
When she opens the waste summary
Then the system shows plain counts for used and wasted items
And does not use points, badges or rewards.

Feature 5: Trust and privacy¶

In order to use personalization with confidence,
as a consumer,
I want to understand and control how my data is used.

Scenario 5.1: Read the privacy summary¶

Given Sara reaches health-profile onboarding
When the privacy explanation is shown
Then it explains in everyday language that health and individual activity stay on the consumer side
And it can be read in about 30 seconds.

Scenario 5.2: Protect identifiable health data¶

Given Sara has health data and scan activity
When Brand analytics are produced
Then no individual health profile, account, visitor or scan record crosses the privacy wall
And a Brand receives only aggregates that meet the minimum group size
And each Brand can query only its own aggregate rows.

Scenario 5.3: Link anonymous activity after sign-up¶

Given an Anonymous Shopper has a pseudonymous Visitor ID and earlier activity
When the shopper creates an account
Then the Visitor ID is linked to the new account rather than replaced
And the earlier activity remains attributable for Consumer-side measurement, not as a user-visible server history
And the link does not expose individual history to Brands.

Feature 6: Brand dashboard¶

In order to measure product engagement without invading consumer privacy,
as a Brand manager,
I want to see my products and privacy-safe aggregate metrics.

Scenario 6.1: See only the authenticated Brand¶

Given Marco signs in with a Brand account
When he opens the dashboard
Then the gateway derives the Brand scope from his verified identity
And the dashboard shows only that Brand's products and metrics
And Marco cannot request another Brand's identifier.

Scenario 6.2: View scan counts¶

Given privacy-safe scan aggregates exist for Marco's products
When he opens the metrics view
Then the dashboard shows total scans by product
And shows their change over time.

Scenario 6.3: View anonymous engagement¶

Given an engagement group has reached the minimum publication size
When Marco opens the dashboard
Then he sees only the published aggregate
And cannot inspect a contributing visitor, account or scan.

Scenario 6.4: Provide product data: Planned dashboard flow¶

Given Marco has label, origin and sustainability information for a product
When he submits it through the supported manual onboarding process
Then the product data is validated and added to the Brand's producer snapshot
And the product becomes resolvable to consumers.

Feature 7: My Shopping List¶

In order to remember what to buy and connect shopping with home inventory,
as an account holder,
I want to manage a product-linked Shopping List.

Scenario 7.1: Add a trusted product¶

Given Sara is signed in
And Product Passport can resolve the product
When she adds it from search or a scan result
Then the Shopping List stores its GTIN and trusted name, Brand and image snapshot
And does not create a free-text item
And adding the same active product again increases its quantity.

Scenario 7.2a: Change an active item's quantity¶

Given Sara has an active Shopping List item
When she changes its quantity
Then the system saves a quantity within the allowed range.

Scenario 7.2b: Complete an active list item¶

Given Sara has an active Shopping List item
When she marks the item as bought or removed
Then the item enters that final state and leaves the active list.

Scenario 7.3: Re-buy a Fridge item¶

Given Sara marks a Fridge item as used or discarded
When the app offers to add it to the Shopping List
Then nothing is added until Sara confirms
And confirmation adds the trusted product without requiring a new search.

Scenario 7.4: Re-stock after a purchase¶

Given Sara marks a Shopping List item as bought
When the app offers to add it to the Fridge
Then nothing is added until Sara confirms
And confirmation uses the product GTIN without requiring another scan.

Feature 8: Revisit and compare products¶

In order to return to useful products and make comparisons,
as a shopper,
I want to search recent scans, compare them and use the interface in my language.

Scenario 8.1: Search recent scan history¶

Given the shopper has scanned products on the current device
When the shopper opens History and searches by product or Brand name
Then matching products appear newest first within the device-local limit of 100 products, deduplicated by product
And no account is required
And the device-local cache is not presented as the authoritative server record.

Scenario 8.2: Compare recent products¶

Given two or three product snapshots exist in the recent-scan cache
When the shopper selects them for comparison
Then the app shows them side by side
And highlights differences such as eco score and sugar
And does not replace the deterministic personal verdict.

Scenario 8.3: Change interface language¶

Given the interface supports English, Italian, Spanish and French
When the shopper selects one of those languages
Then interface labels, verdict reasons and alert reasons use that language
And domain data and events continue to carry stable reason codes rather than localized text
And production-quality localization is not claimed until each locale has native review.