Skip to content

✨🧑‍💻 - Find household products by manually entered barcode #91

Description

@efraespada

Is there an existing issue or feature request for this?

  • I have searched the existing issues and feature requests.

What area does this improvement affect?

New Feature

What actions does this improvement affect?

No response

Description of the idea or improvement

Let a household member enter the number printed below a retail barcode and
find the product in the local Inventory catalog. An inventory manager can
link a supported GTIN to a selected product and remove an erroneous link.

Current limitations or challenges

Inventory has product and stock records but no way to validate a barcode,
associate it with a product, or search the household catalog by its number.

Expected impact

A member can enter a UPC, find the same product by its equivalent 14-digit
form and open its stock detail. Invalid and unlinked codes have distinct
messages. Local lookup runs within Domus.

Alternatives considered

No response

Version of copilot

No response

Additional context or comments

Owning SDD for this bounded increment is the new companion specs/stock-local-barcode.md, with capability ID stock-local-barcode. Base is develop at 50ddb2d.
Retain specs/household-inventory.md byte-for-byte as the accepted Inventory baseline. Publish the five supplied requirements and eight supplied cases in the new companion. Their identities, assertions and accepted product decisions are preserved.
This increment implements the accepted manual entry, validation and local
catalog portions of A14 and household-inventory-R7. It covers the original
validation case household-inventory-C20 and the manual local-only part of household-inventory-C28. Camera and
configured external lookup have separate acceptance. Use existing
published ha-ui controls, scope reads and writes to current household access
and preserve exact product and ledger identities.

Find household products by manually entered barcode

  • Status: Draft
  • Owners: Domus maintainers and Inventory
  • Scope: Manual GTIN validation, local catalog search and barcode associations
  • Open decisions blocking readiness: none

1. Executive summary

Enter the number printed under a retail barcode and find the corresponding
product in the household catalog. Inventory managers can associate a validated
number with an existing catalog product and correct an erroneous association.

2. Problem, current behavior, and evidence

Inventory supports product registration and stock workflows. Its catalog
has no local barcode associations or lookup. The owner confirmed manual
entry and local matching in the existing Inventory specification.

3. Actors, surfaces, and terminology

A household reader can search Inventory. A member with current inventory
management authority can maintain the association. A GTIN is the retail
trade item number printed alongside a barcode. The local association points
to the stable product identity.

4. Goals, non-goals, and fixed invariants

Requirement Behavior
stock-local-barcode-R01 Accept manually entered GS1 GTIN-8, GTIN-12, GTIN-13 and GTIN-14 text, validate the check digit and use the zero-padded 14-character identity for matching.
stock-local-barcode-R02 A current household reader can find at most one catalog product by a valid barcode. Distinguish invalid input, an unlinked barcode and an unavailable lookup. Keep requests within Domus.
stock-local-barcode-R03 An inventory manager can link or explicitly remove a barcode association in the current household. Concurrent updates preserve uniqueness. Original operations can be recovered. Product identity, quantities and existing ledger history are preserved.
stock-local-barcode-R04 Migrate and restore the local association index safely. Preserve representative older inventory and its receipts.
stock-local-barcode-R05 Support an accessible manual workflow in English and Spanish through both deployment compositions and the installed Edge candidate.

The manual workflow forms the local lookup shared by future camera and
configured provider adapters. Package quantities follow the owning conversion
contract.

5. Current versus proposed product journey

Open Inventory, type or paste a GTIN, and search. If a product matches, see
its name and open its existing stock detail. When there is no association,
a manager can attach the code to an existing product. Ordinary product
registration remains available.

6. Functional behavior and state model

Validate ASCII digits, the supported lengths and the GS1 check digit before
deriving the canonical string. Preserve leading zeroes. Apply the same
canonical identity to every lookup and association. Equivalent forms
resolve the same link. A code belongs to at most one product in a household.
Remove a link only when it is still the association the manager reviewed.
Link changes and their original command receipts commit atomically.

7. User-facing configuration

Use the existing household locale and inventory grants. The lookup reads
the current household database and uses existing Inventory navigation.

8. Clean Architecture design

A pure domain value validates the GTIN. Application services own grants,
association commands and exact queries. SQLite enforces the household key
and the product reference. The HTTP entry point validates transport input.
The browser uses published ha-ui field, button and feedback components.

9. UI/UX and content contract

Label the field for the printed barcode digits, preserve zeroes when
pasting and use a numeric keyboard hint. Give an example of the supported
lengths. State whether the code is invalid, unlinked, found or temporarily
unavailable and offer the relevant next action. Show the product name before
the manager submits a link or removal. Preserve a correctable draft.

10. Failure, recovery, and cleanup

A duplicate association displays the conflict while retaining the entered
code. An unavailable query offers retry. A lost successful reply recovers the
original result. A stale removal leaves a newer association intact.

11. Security, permissions, and privacy

Authorize exact reads under the verified current household. Recheck
inventory management authority for writes and original receipt access.
Validate before querying and resolve products within the current household.
Keep lookup data within the Domus installation.

12. Observability and operational UX

Operation receipts record association changes. Product history continues to
report its existing movement identities and quantities.

13. Compatibility, migration, rollout, and rollback

Initialize an empty barcode index for existing households. Test
representative data from the current previous schema 34, schema 30 and schema 20. Verify restart and activated
compatible restore of a barcode link and its receipt. Qualify the installed
candidate with its exact version and a compatible rollback checkpoint.

14. Testing strategy and numeric budget

Minimum eight distinct cases.

{{SDD_CASE_BUDGET}}

Case ID Area Requirements Scenario
stock-local-barcode-C01 Barcode identity stock-local-barcode-R01 Validate GS1 check digits for all four supported lengths. Leading zeroes survive and equivalent strings resolve one canonical key. Reject malformed, wrong-length and check-digit-invalid input.
stock-local-barcode-C02 Local catalog stock-local-barcode-R02 Find a linked product and distinguish a valid unlinked code. Exercise local lookup with external connectivity absent and observe only installation-local requests.
stock-local-barcode-C03 Authorization stock-local-barcode-R02, stock-local-barcode-R03 A current household reader can find an own product. A foreign association is invisible. A reader without management access cannot modify a link or recover its original write.
stock-local-barcode-C04 State and concurrency stock-local-barcode-R03 Race two products for equivalent forms of one code. Exactly one link wins. Explicitly remove it and verify a stale removal cannot delete a later association.
stock-local-barcode-C05 State and recovery stock-local-barcode-R03 Recover the original receipt after a lost reply, reject a different command under the same key and roll back the association on a late failure.
stock-local-barcode-C06 Upgrade and restoration stock-local-barcode-R04 Preserve representative schema 34, schema 30 and schema 20 data during migration. Restart and activate a compatible backup containing a link and its original operation.
stock-local-barcode-C07 Browser acceptance stock-local-barcode-R05 Enter a code, see invalid and unlinked states, link to the selected product and find it again. Verify desktop keyboard and narrow touch use in English and Spanish through Ingress and standalone.
stock-local-barcode-C08 Installed acceptance stock-local-barcode-R05 Verify the installed Edge version, exercise the manual lookup with disposable data and qualify both architecture images.

15. Documentation and discoverability

{{SDD_FILE_NAVIGATION}}

Path Change
specs/stock-local-barcode.md create
docs/roadmap.md update
docs/household-api.md update
backend/src/domus/domain/inventory.py update
backend/src/domus/application/inventory.py update
backend/src/domus/application/inventory_queries.py update
backend/src/domus/infrastructure/sqlite_inventory.py update
backend/src/domus/entrypoints/inventory_http.py update
frontend/src/presentation/domus-inventory.ts update
frontend/src/presentation/inventory-messages.ts update

16. Acceptance scenarios

Enter a valid UPC, link it to an existing product, and look it up using its
zero-padded representation. Observe the product's stable identity and exact
stock. Correct the association through the manager flow.

17. Requirements traceability

{{SDD_REQUIREMENT_CASES}}

18. Implementation sequence

Validate and normalize GTINs. Add protected exact lookup, association
commands and durable storage. Integrate the manual Inventory experience
and qualify the package on both deployment targets.

19. Definition of Done

Verify the eight cases, global and per-file coverage, both architecture
images, deployed Edge version and scoped test cleanup.

20. References and decisions

The owner's decision A14 and household-inventory-R7 accept manual entry
and local catalog search. GS1 defines the supported GTIN lengths, check
digit and the 14-character zero-padded representation.

https://support.gs1.org/support/solutions/articles/43000734355-what-is-the-required-format-of-gtin-in-gs1-edi-standards-
https://ref.gs1.org/guidelines/2d-in-retail/1.1.0/

Activity

  1. added
    enhancementNew feature or request
    featureLabel to manage feature branches
    priority: lowLabel to indicate a priority low
    in-progressStart work on an admitted issue.
    on Nov 11, 2026
  2. moved this to Todo in vypdevon Nov 11, 2026
  3. added
    SDDAn SDD update is required before branch work.
    on Nov 11, 2026
  4. vypbot commented on Nov 11, 2026

    @vypbot

    SDD work status

    Current status: Waiting for specification answers. No SDD draft or branch exists yet.

    Owning SDD: specs/stock-local-barcode.md

    Clarification round: 2

    Draft SHA-256: 46c44d38a1a60d075d809964ae7664fd7bdc183878a25fb4eb2d495800339cb9

    • Q1 · Maintainer: Review the draft and reply exactly with use seed eb6aa3d75575cab3586c4b6ed12f1338109f5de139056414b52544e94adc4b63 or generate eb6aa3d75575cab3586c4b6ed12f1338109f5de139056414b52544e94adc4b63.

    Reply with SDD Q1: your answer (one line per question). The Action will continue after the required people answer every question.

  5. changed the title [-]Find household products by manually entered barcode[/-] [+]✨ - Find household products by manually entered barcode[/+] on Nov 11, 2026
  6. added
    state:specifyingThe issue contract is being clarified and specified.
    state:ai-processingA Copilot agent is analyzing or working on the issue or change.
    and removed
    state:ai-processingA Copilot agent is analyzing or working on the issue or change.
    on Nov 11, 2026
  7. added
    state:ai-processingA Copilot agent is analyzing or working on the issue or change.
    on Nov 19, 2026
  8. 82 remaining items

  9. added
    state:ai-processingA Copilot agent is analyzing or working on the issue or change.
    85%Progress: 85%
    80%Progress: 80%
    90%Progress: 90%
    and removed
    80%Progress: 80%
    state:ai-processingA Copilot agent is analyzing or working on the issue or change.
    85%Progress: 85%
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

90%Progress: 90%SDDAn SDD update is required before branch work.branchedThe linked branch and required SDD commit are verified.enhancementNew feature or requestfeatureLabel to manage feature branchesin-progressStart work on an admitted issue.priority: lowLabel to indicate a priority lowsize: XXLLabel to indicate a task of size XXLstate:ai-processingA Copilot agent is analyzing or working on the issue or change.state:workingWork can proceed on the verified branch or without a branch.

Projects

  • Status
    In Progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions