From b188a6b6a5c183dec8bfcea992e6f49400c2ee08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Fri, 27 Feb 2026 00:48:04 +0100 Subject: [PATCH] docs: add Gherkin spec for short UID generation feature Add comprehensive feature specification for item UID generation with: - 7-character collision-resistant IDs using safe alphabet - Pre-generation on form load with regenerate option - UI/UX guidelines for monospace display and inline controls - Edge case handling for collisions and persistence Co-Authored-By: Claude Sonnet 4.5 --- features/item-uid-generation.feature | 156 +++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 features/item-uid-generation.feature diff --git a/features/item-uid-generation.feature b/features/item-uid-generation.feature new file mode 100644 index 0000000..05088fd --- /dev/null +++ b/features/item-uid-generation.feature @@ -0,0 +1,156 @@ +Feature: Item UID Generation - Short Collision-Resistant IDs + As a user creating a new item + I want to see a pre-generated short UID (7 characters) + So that IDs remain compact, memorable, and shareable while avoiding collisions + + Background: + Given I am on the "New Item" form + + Rule: UIDs are pre-generated on form load + + Scenario: UID is pre-generated when form loads + When the form loads + Then I should see a "UID" field + And the UID field should contain a 7-character ID + And the UID should use only characters from "23456789abcdefghjkmnpqrstuvwxyz" + And the UID should be displayed prominently near the top of the form + + Scenario: UID field is read-only with regenerate option + When the form loads + Then the UID field should be read-only or disabled for manual editing + And I should see a "Regenerate" button/icon next to the UID field + And the regenerate control should be clearly clickable + + Rule: Users can regenerate UIDs before submission + + Scenario: User regenerates UID once + Given the form has loaded with UID "qe3saa3" + When I click the "Regenerate" button + Then a new 7-character UID should be generated + And the new UID should be different from "qe3saa3" + And the new UID should be displayed in the UID field immediately + + Scenario: User regenerates UID multiple times + Given the form has loaded with UID "qe3saa3" + When I click the "Regenerate" button + And the new UID is "n4p7m2k" + And I click the "Regenerate" button again + Then another new 7-character UID should be generated + And each generated UID should be unique + And the latest UID should replace the previous one + + Scenario: Regenerated UID is used on submission + Given the form has loaded with UID "qe3saa3" + And I fill in "Name" with "Cable Drum" + When I click the "Regenerate" button + And the new UID is "n4p7m2k" + And I submit the form + Then the item should be created with shortId "n4p7m2k" + And the barcode URI should be "https://haus.toph.so/n4p7m2k" + And the original UID "qe3saa3" should NOT be used + + Rule: UID format and collision resistance + + Scenario: UID uses safe alphabet + When a UID is generated + Then it should use alphabet "23456789abcdefghjkmnpqrstuvwxyz" + And it should exclude confusing characters (0, 1, i, l, o) + And it should be exactly 7 characters long + And all characters should be lowercase + + Scenario: Collision probability is negligible + Given the alphabet has 29 characters (excluding 0, 1, i, l, o) + And the UID length is 7 characters + Then the total possible IDs should be 29^7 = 17,249,876,309 + And collision probability for 1,000 items should be approximately 0.000003% + And collision probability for 10,000 items should be approximately 0.0003% + And collision probability for 100,000 items should be approximately 0.03% + + Scenario Outline: UID examples are valid + When a UID "" is generated + Then it should match the pattern "^[23456789a-hjkmnp-z]{7}$" + And it should NOT contain any of "0 1 i l o" + + Examples: + | uid | + | qe3saa3 | + | n4p7m2k | + | 2jk8xab | + | zzz9999 | + | 2222222 | + + Rule: UID field UI/UX specifications + + Scenario: UID field placement + When the form loads + Then the UID field should be positioned near the top + And it should appear before or after the "Name" field + And it should be clearly labeled "UID" or "Item ID" + + Scenario: UID field styling + When the form loads + Then the UID field should use monospace font + And it should have larger text size for readability + And it should have letter-spacing for clarity + And the field should visually indicate it's read-only + + Scenario: Regenerate button styling + When the form loads + Then the "Regenerate" button should be compact + And it should use an icon (🔄 or ↻) or short text + And it should be positioned inline with the UID field (right side) + And it should have a clear hover state + And it should have appropriate spacing from the UID field + + Scenario: Regenerate button interaction + When I hover over the "Regenerate" button + Then it should show a visual hover state + And optionally show a tooltip "Generate new ID" + When I click the "Regenerate" button + Then the button should show brief loading/animation feedback + And the new UID should appear immediately + + Rule: UID persistence and submission + + Scenario: UID is submitted with item + Given the form has pre-generated UID "qe3saa3" + And I fill in "Name" with "Laptop" + And I fill in "Category" with "Electronics" + When I submit the form + Then the item should be created with shortId "qe3saa3" + And the database should store shortId as primary key + And the item detail page should display "qe3saa3" + And the barcode should encode "https://haus.toph.so/qe3saa3" + + Scenario: Creation timestamp stored separately + Given the form has pre-generated UID "qe3saa3" + When I submit the form at 2024-02-27T14:30:00Z + Then the item should have shortId "qe3saa3" + And the item should have createdAt "2024-02-27T14:30:00Z" + And the item should have updatedAt "2024-02-27T14:30:00Z" + And timestamps should be independent of the UID + + Rule: Edge cases and validation + + Scenario: Duplicate UID is detected (rare collision) + Given an item exists with UID "qe3saa3" + And the form generates the same UID "qe3saa3" by chance + When I submit the form + Then the system should detect the collision + And the system should automatically generate a new UID + And the item should be created successfully with a different UID + And the user should be notified "ID regenerated due to conflict" + + Scenario: UID persists during form edits + Given the form has loaded with UID "qe3saa3" + When I fill in "Name" with "Cable" + And I change "Name" to "Cable Drum" + And I fill in other fields + Then the UID should remain "qe3saa3" + And the UID should NOT auto-regenerate on field changes + + Scenario: UID regenerates on explicit action only + Given the form has loaded with UID "qe3saa3" + When I interact with any form field + Then the UID should remain unchanged + And the UID should only change when "Regenerate" is clicked