Chapter 05: Architecture Components (BRD v20.0)

5.0 About This Chapter

This chapter contains the complete Business Requirements Document (BRD) v20.0 for the POS Platform. It serves as the authoritative source for all functional requirements, business rules, state machines, and module specifications.

Authority Rule: When any other chapter in this Blueprint conflicts with content in this chapter, this chapter (BRD) wins.

Module Overview

How to Use This Chapter

• For implementation: Find the relevant Module and Section number
• For business rules: Check the YAML business rules in each module
• For state machines: See Module 7 (State Machine Reference)
• For decisions: 113 decisions documented throughout, summarized in Appendix
• For user stories: Gherkin acceptance criteria at the end of each module

This document consolidates all features into a modular architecture.

• Module 1 (Sales): Covers Scanner, Financials, Discounts, Post-Sale corrections, Gift Cards, Exchanges, Special Orders, Multi-Store, Commissions, Cash Management, Offline Operations, Tax Engine, Payment Integration, and more.
• Module 2 (Customers): Covers Profiles, Merging, Tax Logic, Data Management, Customer Groups, Notes, Communication Preferences, and Privacy Compliance.
• Module 3 (Catalog): Covers Product Types & Data Model (with retail attributes, custom fields, UoM, shipping, templates, matrix management), Product Lifecycle, Pricing Engine (price hierarchy, price books, promotions, markdowns), Barcode Management, Categories/Seasons/Collections, Multi-Channel Management, Shopify Integration, Vendor Management, Search & Discovery, Label Printing, Media Management, Notes & Attachments, Permissions & Approvals, Product Analytics, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 4 (Inventory): Covers Inventory Status Model, Purchase Orders & Procurement, Receiving & Inspection, Reorder Management, Inventory Counting & Auditing, Inventory Adjustments, Inter-Store Transfers, Vendor RMA & Returns, Serial & Lot Tracking, Landed Cost & Costing, Product Movement History, POS & Sales Integration, Online Order Fulfillment, Offline Operations, Alerts & Notifications, Dashboard & Reports, Business Rules, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 5 (Setup & Configuration): Covers System Settings, Multi-Currency, Location Management, Supplier Configuration, User Profiles & Permissions, Time Tracking (Clock-In/Clock-Out), Register Management, Printers & Peripherals, Tax Configuration, UoM Management, Payment Methods, Custom Fields, Approval Workflows, Receipt Configuration, Email Templates, Loyalty Settings, Audit Logging, Consolidated Business Rules (YAML), Tenant Onboarding Wizard, Field Specifications Reference with Technical User Stories, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 6 (Integrations & External Systems): Covers Integration Architecture (provider abstraction, retry/backoff, circuit breaker, idempotency, rate limiting, webhook pipeline), Shopify Integration (enhanced with GraphQL, bulk operations, third-party POS rules, BOPIS, omnichannel), Amazon SP-API Integration (OAuth/LWA, catalog/listings/orders/FBA APIs, FBA+FBM fulfillment, compliance, safety buffers), Google Merchant API Integration (product data management, local inventory, disapproval prevention, image requirements, GBP integration), Cross-Platform Product Data Requirements (unified validation matrix, strictest-rule-wins), Cross-Platform Inventory Sync Rules (safety buffers, oversell prevention, channel-specific rules), Payment Processor Integration, Email Provider Integration, Carrier & Shipping Integration, Integration Hub, Integration Business Rules (YAML), and comprehensive User Stories with Gherkin acceptance criteria.

1. Sales Module

1.1 Core Sales Workflow (Item Entry & Logic)

Scope: Scanner/Manual Entry, Inventory Checks, Parking, and Customer Association.

Cross-Reference: See Module 4, Section 4.13 for inventory reservation model during sales.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant SC as Scanner
    participant API as Backend
    participant DB as DB
    participant PROMO as Promo Engine

    Note over U, PROMO: Phase 1: Initiation & Entry

    loop Action Loop
        U->>UI: Toggle Mode (Sale / Return / Exchange)

        alt Input Methods
            U->>UI: Scan Barcode / Search SKU
            UI->>API: GET /product/{sku}
        else Scanner Broadcast
            SC->>UI: Tags Detected (Array)
            UI->>API: POST /products/bulk-lookup
            Note right of API: Max 50 tags per request
        end

        API->>DB: Fetch Price, Stock, Tax
        DB-->>UI: Return Product Data

        alt Stock Validation
            opt Mode == Sale
                UI->>UI: Check Stock > 0
                alt Low Stock
                    UI-->>U: Warning / Block Item
                end
            end
        end

        alt Mode Check
            opt Mode == Exchange
                U->>UI: Load Original Sale for Exchange
                UI->>API: GET /orders/{id}
                API-->>UI: Return Original Sale Items
                UI->>UI: Select Items to Exchange OUT
                UI->>UI: Scan/Add New Items IN
                UI->>UI: Calculate Price Difference
                Note right of UI: Links to Exchange flow in Section 1.4
            end
        end

        UI->>UI: Add to Cart

        par Intelligence & Context
            UI->>PROMO: Analyze Cart Context
            PROMO-->>UI: Trigger Upsell Alert ("Buy 1 more for 10% off")
        and Customer Attachment
            opt Attach Customer
                UI->>API: GET /customer/{id} (Loyalty/Debt/Price Tier)
                API-->>UI: Return Profile (Credit Limit, Tax Class, Price Level)
                UI->>UI: Recalculate Prices (if Price Tier applies)
                UI->>UI: Recalculate Tax (if Exempt)
            end
        end
    end

    opt Session Management
        U->>UI: Click "Park Sale"
        UI->>API: POST /sales/park
        API->>DB: Serialize State & Release Locks

        U->>UI: Click "Retrieve Sale"
        UI->>API: GET /sales/parked
        API-->>UI: Restore Cart
    end

1.1.1 Parked Sale State Machine

stateDiagram-v2
    [*] --> ACTIVE: Cart Created
    ACTIVE --> PARKED: Staff Parks Sale
    PARKED --> ACTIVE: Staff Retrieves Sale
    PARKED --> EXPIRED: TTL Exceeded (4 hours)
    EXPIRED --> [*]: Inventory Released
    ACTIVE --> PENDING: Proceed to Payment

Parked Sale Rules:

• Maximum parked sales per terminal: 5
• TTL (Time-to-Live): 4 hours
• Inventory is soft-reserved while parked (visible to other terminals with warning)
• Expired parked sales auto-release inventory and log reason

1.1.2 Reports: Core Sales

1.2 Discounts & Pricing Logic

Scope: Line-item overrides, Global discounts, Promotion application, Price Tiers, and Loyalty Redemptions.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 2: Modification & Pricing

    loop Pricing Actions
        alt Line Item Modification
            U->>UI: Select Item -> Override Price
            opt Manager Auth
                UI-->>U: Prompt PIN
                U->>UI: Enter PIN
            end
            UI->>UI: Apply New Price & Reason Code (e.g., "Damaged")
        end

        alt Discounting
            U->>UI: Apply Global Discount / Promo Code / Coupon
            UI->>API: Validate Code (Expiry/Stacking/Single-Use)
            API-->>UI: Valid

            Note right of UI: Critical Calculation Order:
            UI->>UI: 1. Apply Price Tier (Wholesale/VIP)
            UI->>UI: 2. Apply Line Discounts
            UI->>UI: 3. Apply Global % (Excluding Non-Discountable)
            UI->>UI: 4. Apply Coupons
            UI->>UI: 5. Calculate Tax (on discounted subtotal)
            UI->>UI: 6. Apply Loyalty Redemptions (after tax)
        end
    end

1.2.1 Discount Calculation Order (Definitive)

The system applies discounts in this strict order:

Non-Discountable Items: Gift cards, deposits, and items flagged is_discountable = false are excluded from global discounts.

1.2.2 Reports: Discounts & Pricing

1.3 Financial Settlement (Payments, Layaway, Third-Party Financing)

Scope: Split tenders, Credit Limits, Gift Cards, Third-Party Financing (Affirm), and Finalization.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant PAY as Payment Gateway

    Note over U, DB: Phase 3: Settlement

    U->>UI: Click "Pay"

    loop Tender Processing
        U->>UI: Select Method
        Note right of UI: Multiple tenders allowed: cash + card(s), multiple cards, etc.

        alt Cash
            UI-->>U: Show "Collect: $20.03"
            U->>UI: Enter Amount Received
            UI->>UI: Calculate Change Due

        else Gift Card
            U->>UI: Scan/Enter Gift Card Number
            UI->>API: GET /giftcards/{number}/balance
            API-->>UI: Return Balance & Expiry
            alt Sufficient Balance
                UI->>UI: Deduct from Gift Card
                UI->>UI: Add to Tender List
            else Insufficient Balance
                UI-->>U: "Card Balance: $X. Apply partial?"
                U->>UI: Apply Partial Amount
            end

        else On-Account (Store Credit)
            UI->>API: Check Credit Limit (Balance + Pending Layaways + Cart)
            alt Exceeds Limit
                API-->>UI: Block Transaction
            else Approved
                UI->>UI: Add to Tender List
            end

        else Layaway Deposit
            U->>UI: Select Layaway Mode
            UI->>UI: Validate Min Deposit %
            Note right of UI: Sale Status -> LAYAWAY

        else Credit Card (SAQ-A Flow)
            UI->>API: POST /payments/initiate {amount, order_id}
            API->>PAY: Send amount to terminal
            Note over PAY: Customer taps/inserts card
            PAY-->>API: Token + Approval Code
            API->>DB: Store token (never card data)
            API-->>UI: Payment Approved

        else Third-Party Financing (Affirm)
            U->>UI: Select "Pay with Affirm"
            UI->>API: POST /payments/affirm/initiate {amount, order_id, customer}
            API->>PAY: Create Affirm Checkout Session
            PAY-->>API: Redirect URL / QR Code
            API-->>UI: Display QR Code or Redirect
            Note over PAY: Customer completes Affirm application on their device
            PAY-->>API: Webhook: Loan Approved + Charge ID
            API->>DB: Store Affirm charge_id, loan_id, status
            API-->>UI: Payment Approved (Affirm)
            Note right of API: Full amount received from Affirm; customer pays Affirm directly
        end

        UI->>UI: Update Remaining Balance
    end

    UI->>API: POST /orders/finalize

    par Backend Operations
        API->>DB: Write Order Record
        API->>DB: Update Inventory (Decrement Sale / Increment Return)
        API->>DB: Update Customer (Loyalty Points / Increase Debt)
        API->>DB: Update Gift Card Balance (if used)
        API->>DB: Record Commission (Employee ID + Amount)
    end

    API-->>UI: Transaction Success

    opt Receipt Printing
        U->>UI: Select Template (Thermal / A4 Invoice / Gift Receipt)
        UI->>U: Print / Email Receipt
    end

1.3.1 Order State Machine

stateDiagram-v2
    [*] --> DRAFT: Cart Created
    DRAFT --> PENDING: Click Pay
    PENDING --> PARTIAL_PAID: Partial Payment
    PARTIAL_PAID --> PENDING: More Payment Needed
    PENDING --> PAID: Full Payment
    PARTIAL_PAID --> PAID: Full Payment
    PAID --> COMPLETED: Finalized
    PAID --> HOLD_FOR_PICKUP: Hold Requested
    HOLD_FOR_PICKUP --> READY_FOR_PICKUP: Items Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> HOLD_EXPIRED: Deadline Passed
    HOLD_EXPIRED --> CONTACT_CUSTOMER: Staff Notified
    CONTACT_CUSTOMER --> READY_FOR_PICKUP: Deadline Extended
    CONTACT_CUSTOMER --> REFUNDED: Customer Wants Refund
    COMPLETED --> VOIDED: Void Action (Same Day)
    COMPLETED --> PARTIALLY_RETURNED: Partial Return
    PARTIALLY_RETURNED --> FULLY_RETURNED: All Items Returned
    VOIDED --> [*]
    FULLY_RETURNED --> [*]
    REFUNDED --> [*]

1.3.2 Layaway State Machine

stateDiagram-v2
    [*] --> DEPOSIT_PAID: Min Deposit Received
    DEPOSIT_PAID --> RESERVED: Inventory Reserved
    RESERVED --> RESERVED: Additional Payment
    RESERVED --> PAID_IN_FULL: Final Payment
    PAID_IN_FULL --> COMPLETED: Items Released
    RESERVED --> CANCELLED: Customer Cancels
    RESERVED --> FORFEITED: Payment Deadline Missed
    CANCELLED --> [*]
    FORFEITED --> [*]
    COMPLETED --> [*]

1.3.3 Credit Limit Calculation

When checking if a customer can use On-Account payment:

Available Credit = Credit Limit - (Current Debt + Pending Layaway Balances + Current Cart Total)

Example:

• Credit Limit: $500
• Current Debt: $150
• Pending Layaway (remaining balance): $100
• Current Cart: $200
• Available Credit: $500 - ($150 + $100 + $200) = $50
• Result: Blocked (cart exceeds available credit by $150)

1.3.4 Reports: Financial Settlement

1.4 Post-Sale Management (History, Void, Returns, Exchanges)

Scope: Corrections, History, Returns, Dedicated Exchanges, Receipt Reprinting, and Data Export.

sequenceDiagram
    autonumber
    participant U as Manager
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    U->>UI: Open Sales History
    U->>UI: Apply Filters (Date, User, Status)
    UI->>API: GET /sales/history

    alt Action: Void (Same-Day Correction Only)
        Note right of U: "Oops, wrong item - same day"
        UI->>API: GET /orders/{id}/void-eligibility
        API-->>UI: Check if same business day & drawer still open

        alt Eligible for Void
            U->>UI: Click Void -> Confirm
            UI->>API: POST /sales/{id}/void

            par Reversal
                API->>DB: Reverse Inventory & Loyalty
                API->>DB: Reverse Commission (Full)
                API->>DB: Set Status "VOIDED"
            end

            UI-->>U: Alert: "Manually Refund Card Terminal"
        else Not Eligible (Different Day)
            UI-->>U: "Cannot void - use Return instead"
        end

    else Action: Return (with Policy Check)
        Note right of U: "Customer brought it back"
        U->>UI: Scan Receipt Barcode
        UI->>API: POST /receipts/validate {barcode_data}
        API->>DB: Verify receipt authenticity & match to order
        alt Receipt Valid
            API-->>UI: Receipt Verified - Load Original Sale
        else Receipt Invalid
            API-->>UI: "Invalid Receipt - Cannot Process Return"
            UI-->>U: "Receipt validation failed. Verify receipt."
        end
        UI->>API: GET /sales/{id}/return-eligibility
        API-->>UI: Return Policy Result

        alt Within Policy (Receipt + Time)
            UI->>UI: Select Items to Return
            UI->>UI: Process Refund to Original Payment
            API->>DB: Reverse Commission (Proportional)
        else Outside Policy (No Receipt / Expired)
            UI-->>U: "Policy Exception - Store Credit Only"
            opt Manager Override
                UI-->>U: Prompt Manager PIN
                U->>UI: Enter PIN + Reason Code
            end
            UI->>UI: Issue Store Credit
        end

    else Action: Exchange (Dedicated Flow)
        Note right of U: "Customer wants different size"
        U->>UI: Load Original Sale -> Click "Exchange"
        UI->>UI: Select Item(s) to Exchange OUT
        UI->>UI: Scan/Add New Item(s) IN
        UI->>UI: Calculate Price Difference

        alt Customer Owes Money
            UI-->>U: "Collect: $15.00 difference"
            U->>UI: Process Payment
        else Store Owes Refund
            UI-->>U: "Refund: $10.00 to customer"
            U->>UI: Process Refund
        else Even Exchange
            UI->>UI: No Payment Required
        end

        UI->>API: POST /sales/exchange
        API->>DB: Create Exchange Record (Links Old & New)
        API->>DB: Update Inventory (Both Directions)
        API->>DB: Adjust Commission (if price difference)

    else Action: Reprint Receipt
        U->>UI: Click "Reprint Receipt"
        UI->>API: GET /orders/{id}/receipt
        API-->>UI: Return Receipt Data
        U->>UI: Select Format (Thermal / A4 / Email)
        opt Email to Different Address
            U->>UI: Enter Email Address
            UI->>API: POST /orders/{id}/email-receipt
        end

    else Action: Pay Off Layaway
        U->>UI: Retrieve Layaway
        UI->>UI: Pay Remaining Balance
        UI->>API: Finalize (Status: COMPLETED)
        API->>DB: Release Reserve -> Sold
    end

Cross-Reference: See Module 4, Section 4.13 for POS inventory integration details.

1.4.1 Void vs. Return Rules

Card Refund Method Selection (Returns Only):

• Manual on terminal: Customer presents physical card. Staff processes refund on the payment terminal. Use when customer is present with their card.
• Automatic via token: System uses the stored payment token to process refund without card present. Use when customer does not have their card or for remote returns.
• Cash payments: Refund is always cash from drawer. No token option available for cash transactions.

1.4.2 Reports: Post-Sale

Email Template: TMPL-REFUND-CONFIRMATION

1.5 Gift Card Management

Scope: Selling, Activating, Redeeming, Balance Management, and Jurisdiction Compliance.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Gift Card Operations

    alt Sell New Gift Card
        U->>UI: Scan Gift Card (or Enter Number)
        U->>UI: Enter Load Amount
        UI->>API: POST /giftcards/activate
        API->>DB: Create Gift Card Record (Number, Balance, Expiry)
        API->>DB: Set Jurisdiction Rules (based on store location)
        API-->>UI: Activation Success
        UI->>UI: Add Gift Card to Cart as Product
        Note right of UI: Proceeds through normal checkout
    end

    alt Check Balance
        U->>UI: Click "Gift Card Balance"
        U->>UI: Scan/Enter Card Number
        UI->>API: GET /giftcards/{number}/balance
        API-->>UI: Display Balance & Expiry Date (if applicable)
    end

    alt Reload Existing Card
        U->>UI: Scan Gift Card
        UI->>API: GET /giftcards/{number}
        API-->>UI: Card Found - Current Balance
        U->>UI: Enter Reload Amount
        UI->>UI: Add Reload to Cart
        Note right of UI: Balance updated after payment
    end

    alt Cash Out (California Compliance)
        U->>UI: Scan Gift Card
        UI->>API: GET /giftcards/{number}
        API-->>UI: Return Balance & Jurisdiction
        alt Balance <= Cash Out Threshold
            UI-->>U: "Eligible for Cash Out: $8.50"
            U->>UI: Process Cash Out
            API->>DB: Zero Balance, Record Cash Out
        else Balance > Threshold
            UI-->>U: "Not eligible for cash out"
        end
    end

1.5.1 Gift Card State Machine

stateDiagram-v2
    [*] --> INACTIVE: Card Manufactured
    INACTIVE --> ACTIVE: Activated at POS (Sold)
    ACTIVE --> ACTIVE: Partial Redemption
    ACTIVE --> ACTIVE: Reload
    ACTIVE --> DEPLETED: Balance = $0.00
    ACTIVE --> EXPIRED: Past Expiry Date (where allowed)
    DEPLETED --> ACTIVE: Reloaded
    DEPLETED --> CASHED_OUT: Cash Out Processed
    EXPIRED --> [*]
    CASHED_OUT --> [*]

    note right of ACTIVE
        Balance > $0
        Within expiry (if applicable)
    end note

    note right of DEPLETED
        Balance = $0
        Can be reloaded
    end note

1.5.2 Gift Card Jurisdiction Compliance

Implementation: Store location determines which jurisdiction rules apply. System defaults to most restrictive (California-style) and enables features where permitted.

1.5.3 Reports: Gift Cards

1.6 Special Orders & Back Orders

Scope: Ordering out-of-stock items with customer deposits.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant INV as Inventory/Purchasing

    Note over U, INV: Special Order Flow

    U->>UI: Search Product -> Out of Stock
    UI-->>U: "Available for Special Order"

    U->>UI: Click "Create Special Order"
    UI->>UI: Attach Customer (Required)
    UI->>UI: Enter Quantity Needed
    UI->>UI: Calculate Deposit (Min 50% or Full)

    C->>U: Agrees to Deposit
    U->>UI: Process Deposit Payment
    UI->>API: POST /special-orders/create

    par Order Creation
        API->>DB: Create Special Order Record
        API->>DB: Link Customer & Deposit Payment
        API->>DB: Set Status: DEPOSIT_PAID
        API->>INV: Notify Purchasing Team
    end

    API-->>UI: Order #SO-12345 Created
    UI->>U: Print Special Order Receipt

    Note over INV, DB: Later - Item Arrives

    INV->>API: POST /special-orders/{id}/received
    API->>DB: Update Status: READY_FOR_PICKUP
    API-->>C: Send Notification (SMS/Email)

    Note over U, C: Customer Pickup

    U->>UI: Retrieve Special Order
    UI->>UI: Show Deposit Already Paid
    UI->>UI: Calculate Remaining Balance
    U->>UI: Collect Remaining Payment
    UI->>API: POST /special-orders/{id}/complete
    API->>DB: Status: COMPLETED

1.6.1 Special Order State Machine

stateDiagram-v2
    [*] --> CREATED: Order Initiated
    CREATED --> DEPOSIT_PAID: Deposit Received
    DEPOSIT_PAID --> ORDERED: Sent to Vendor
    ORDERED --> RECEIVED: Item Arrived at Store
    RECEIVED --> READY_FOR_PICKUP: Inspected & Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> ABANDONED: No Pickup (30+ days)

    CREATED --> CANCELLED: Customer Cancels (No Deposit)
    DEPOSIT_PAID --> CANCELLED_REFUND: Customer Cancels (Refund Deposit)

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    COMPLETED --> [*]
    ABANDONED --> [*]

1.6.2 Reports: Special Orders

Email Template: TMPL-SPECIAL-ORDER-READY

1.7 Multi-Store Inventory & Transfers

Scope: Cross-store inventory lookup, transfers, and reservations (requires full payment).

Cross-Reference: See Module 4, Section 4.8 for inter-store transfer details.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant S2 as Store B

    Note over U, S2: Multi-Store Inventory Check

    U->>UI: Search Product -> Low/No Stock
    U->>UI: Click "Check Other Stores"
    UI->>API: GET /inventory/multi-store/{sku}
    Note right of API: Eventually consistent (max 5 min stale)
    API-->>UI: Return Stock Levels (All Locations)

    UI-->>U: Display: "Store B: 5 units, Store C: 2 units"

    alt Request Transfer to This Store
        U->>UI: Select Store B -> "Request Transfer"
        UI->>UI: Enter Quantity
        UI-->>U: "Customer must pay in full to process"

        C->>U: Agrees to Pay
        U->>UI: Add Item to Cart (Status: TRANSFER_PENDING)
        U->>UI: Complete Full Payment

        UI->>API: POST /transfers/request
        API->>DB: Create Transfer Record (PAID)
        API->>S2: Notify Store B to Ship
        API-->>UI: Transfer #TRF-789 Created

        UI-->>U: "Item will arrive in 2-3 days"
        UI->>U: Print Transfer Receipt for Customer

    else Reserve at Other Store (Customer Pickup)
        U->>UI: Select Store B -> "Reserve for Pickup"
        UI-->>U: "Customer must pay in full to reserve"

        C->>U: Agrees to Pay
        U->>UI: Process Full Payment

        UI->>API: POST /reservations/create
        API->>DB: Create Reservation (PAID)
        API->>S2: Reserve Item at Store B
        API-->>UI: Reservation #RES-456 Created

        UI-->>U: "Reserved at Store B until [date]"
        UI->>U: Print Pickup Voucher for Customer
    end

    Note over S2, DB: Store B Fulfillment

    S2->>API: POST /transfers/{id}/picked
    API->>DB: Update Status: PICKING
    S2->>API: POST /transfers/{id}/shipped
    API->>DB: Update Status: SHIPPED
    Note right of DB: Carrier scan triggers IN_TRANSIT
    API-->>U: Notification: "Transfer Shipped"

1.7.1 Transfer State Machine

stateDiagram-v2
    [*] --> REQUESTED: Transfer Initiated
    REQUESTED --> PAID: Customer Paid in Full
    PAID --> PICKING: Source Store Processing
    PICKING --> SHIPPED: Handed to Carrier
    SHIPPED --> IN_TRANSIT: Carrier Scan Confirmed
    IN_TRANSIT --> RECEIVED: Arrived at Destination
    RECEIVED --> COMPLETED: Customer Notified & Picked Up

    REQUESTED --> CANCELLED: Cancelled Before Payment
    PAID --> CANCELLED_REFUND: Cancelled After Payment

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    COMPLETED --> [*]

1.7.2 Reservation State Machine

stateDiagram-v2
    [*] --> REQUESTED: Reservation Initiated
    REQUESTED --> PAID: Customer Paid in Full
    PAID --> RESERVED: Item Held at Store
    RESERVED --> PICKED_UP: Customer Collected
    RESERVED --> EXPIRED: Reservation Deadline Passed
    EXPIRED --> REFUND_PENDING: Auto-Refund Triggered
    REFUND_PENDING --> REFUNDED: Refund Processed

    REQUESTED --> CANCELLED: Cancelled Before Payment

    CANCELLED --> [*]
    PICKED_UP --> [*]
    REFUNDED --> [*]

1.7.3 Ship to Customer from Other Location

Scope: Direct shipping from a source store to the customer’s address, with carrier integration for real-time shipping cost calculation.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant S2 as Source Store
    participant SHIP as Carrier API

    Note over U, SHIP: Ship to Customer from Another Store

    U->>UI: Search Product -> Low/No Stock
    U->>UI: Click "Check Other Stores"
    UI->>API: GET /inventory/multi-store/{sku}
    API-->>UI: Return Stock Levels (All Locations)

    U->>UI: Select Source Store -> "Ship to Customer"
    UI-->>U: "Enter Customer Shipping Address"
    C->>U: Provides Shipping Address
    U->>UI: Enter Address Details

    UI->>API: POST /shipping/calculate
    Note right of API: {origin_store, destination_address, items, weight}
    API->>SHIP: Request Shipping Rates
    SHIP-->>API: Return Shipping Options
    API-->>UI: Display Shipping Options

    UI-->>U: "Standard (3-5 days): $8.99 | Express (1-2 days): $15.99"
    C->>U: Selects Shipping Option

    U->>UI: Add Item + Shipping to Cart
    UI->>UI: Total = Item Price + Shipping Cost
    UI-->>U: "Customer must pay in full"

    C->>U: Pays Full Amount (Item + Shipping)
    U->>UI: Process Payment

    UI->>API: POST /shipments/create
    API->>DB: Create Shipment Record (PAID)
    API->>S2: Notify Source Store to Pack & Ship
    API-->>UI: Shipment #SHP-101 Created

    UI-->>U: "Item will be shipped to customer"
    UI->>U: Print Shipment Receipt for Customer

    Note over S2, SHIP: Source Store Fulfillment

    S2->>API: POST /shipments/{id}/packed
    API->>DB: Update Status: PACKED
    S2->>SHIP: Request Shipping Label
    SHIP-->>S2: Return Label + Tracking Number
    S2->>API: POST /shipments/{id}/shipped {tracking_number}
    API->>DB: Update Status: SHIPPED
    API-->>C: Send Tracking Email to Customer

    Note over SHIP, DB: Delivery
    SHIP->>API: Webhook: Delivered
    API->>DB: Update Status: DELIVERED
    API-->>C: Send Delivery Confirmation Email

1.7.4 Ship-to-Customer State Machine

stateDiagram-v2
    [*] --> REQUESTED: Shipment Initiated
    REQUESTED --> PAID: Customer Paid (Item + Shipping)
    PAID --> PICKING: Source Store Processing
    PICKING --> PACKED: Items Packed
    PACKED --> SHIPPED: Label Generated & Handed to Carrier
    SHIPPED --> IN_TRANSIT: Carrier Pickup Confirmed
    IN_TRANSIT --> DELIVERED: Delivery Confirmed

    REQUESTED --> CANCELLED: Cancelled Before Payment
    PAID --> CANCELLED_REFUND: Cancelled After Payment (Full Refund)

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    DELIVERED --> [*]

1.7.5 Reports: Multi-Store & Shipping

Email Template: TMPL-SHIPMENT-TRACKING

Email Template: TMPL-DELIVERY-CONFIRMATION

1.8 Sales Commissions

Scope: Track employee sales for commission calculation with proportional reversal on returns.

Cross-Reference: See Module 5, Section 5.5 for user commission rate configuration.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Commission Tracking (Per Transaction)

    U->>UI: Login to POS (Employee ID Captured)

    Note right of UI: Throughout Sale...
    UI->>UI: Employee ID attached to session

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Commission Recording
        API->>DB: Calculate Commission Amount
        Note right of API: Based on: Sale Total, Product Categories, Employee Tier
        API->>DB: Insert Commission Record
        Note right of DB: {employee_id, order_id, amount, date, line_items[]}
    end

    Note over U, DB: Commission Reversal on Return

    U->>UI: Process Return (2 of 3 items)
    UI->>API: POST /returns/create

    par Proportional Reversal
        API->>DB: Calculate Return Value / Original Sale Value
        Note right of API: $80 returned / $120 sale = 66.7%
        API->>DB: Reverse 66.7% of Commission
        API->>DB: Update Commission Record
    end

    Note over U, DB: Commission Reporting

    U->>UI: Manager -> Reports -> Commissions
    UI->>API: GET /reports/commissions?date_range&employee
    API->>DB: Aggregate Commission Data
    API-->>UI: Return Commission Summary
    UI-->>U: Display: Employee | Sales | Returns | Net Commission

1.8.1 Commission Calculation Rules

commission_calculation:
  # Base calculation
  base_method: "percentage_of_sale"

  # Reversal rules
  void_reversal: "full"           # 100% reversal on void
  return_reversal: "proportional" # Based on returned value

  # Proportional calculation
  # Commission Adjustment = Original Commission × (Returned Value / Original Sale Value)

  # Example:
  # Original Sale: $120, Commission: $6.00 (5%)
  # Return: $80 worth of items
  # Reversal: $6.00 × ($80/$120) = $4.00
  # Net Commission: $6.00 - $4.00 = $2.00

1.8.2 Reports: Commissions

1.9 Return Policy Engine

Configuration Note: Store return and exchange policies are manually configured in the application’s Settings/Setup module. Policies are NOT hardcoded in the application. Each tenant can configure different policies per store location and per sales channel (online vs in-store).

Scope: Configurable return rules based on receipt, time, and item type.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Return Policy Evaluation

    U->>UI: Start Return

    alt Has Receipt
        U->>UI: Scan Receipt Barcode
        UI->>API: POST /receipts/validate {barcode_data}
        API->>DB: Verify receipt authenticity & match to order
        alt Receipt Valid
            API-->>UI: Receipt Verified
        else Receipt Invalid
            API-->>UI: "Invalid Receipt"
            UI-->>U: "Receipt validation failed"
        end
        UI->>API: GET /orders/{id}
        API-->>UI: Return Original Sale Data
        UI->>UI: Calculate Days Since Purchase

        alt Within 30 Days
            UI-->>U: "Full Refund Eligible"
            UI->>UI: Refund to Original Payment Method
        else 31-90 Days
            UI-->>U: "Store Credit Only"
            UI->>UI: Issue Store Credit
        else Beyond 90 Days
            UI-->>U: "Manager Approval Required"
            U->>UI: Enter Manager PIN
            U->>UI: Select Exception Reason
        end

    else No Receipt
        U->>UI: Scan Item Barcode
        UI->>API: GET /products/{sku}/current-price
        API-->>UI: Return Current Selling Price
        UI-->>U: "No Receipt - Store Credit at Current Price"
        UI-->>U: "Manager Approval Required"
        U->>UI: Enter Manager PIN
        UI->>UI: Issue Store Credit (Current Price)
    end

    alt Item-Specific Rules
        opt Final Sale Item
            UI-->>U: "BLOCKED: Final Sale - No Returns"
        end
        opt Opened Electronics
            UI-->>U: "Restocking Fee: 15%"
            UI->>UI: Deduct Restocking Fee
        end
    end

1.9.1 Default Policy Configuration Examples

Note: These are example default values only. Actual policies are configured per tenant in the application’s Settings/Setup module and are NOT hardcoded.

Online Sales Policy

In-Store Sales Policy

Policy Configuration Fields (Settings/Setup):

• Return window (days/hours per channel)
• Exchange window (days/hours per channel)
• Refund method options (original method, store credit, etc.)
• Restocking fee percentage and applicable categories
• Final sale categories
• Manager override permissions
• Online shipping/processing fee exclusion rules

1.9.2 Reports: Return Policy

1.10 Serial Number Tracking

Scope: Capture serial numbers for designated high-value items.

Cross-Reference: See Module 4, Section 4.10 for serial number tracking lifecycle.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Serial Number Capture at Sale

    U->>UI: Scan Product (Serial Required Flag)
    UI-->>U: "Enter Serial Number"
    U->>UI: Scan/Enter Serial Number

    UI->>API: POST /serials/validate
    alt Serial Already Sold
        API-->>UI: "ERROR: Serial already in system"
        UI-->>U: Block Item - Investigate
    else Serial Valid/New
        API-->>UI: Valid
        UI->>UI: Attach Serial to Line Item
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize
    API->>DB: Store Serial with Order Line
    Note right of DB: {order_id, line_id, serial_number, product_sku}

    Note over U, DB: Serial Lookup (Returns/Warranty)

    U->>UI: Search by Serial Number
    UI->>API: GET /serials/{number}
    API-->>UI: Return Purchase History
    UI-->>U: "Sold on [date] to [customer] - Order #123"

1.10.1 Reports: Serial Number Tracking

1.11 Hold for Pickup (Including BOPIS)

Scope: Fully paid items held for customer pickup at the CURRENT store. This includes both in-store holds and BOPIS (Buy Online, Pick Up In Store) orders. Different from Layaway (partial payment) and Reservation (item at another store).

Cross-Reference: See Module 4, Section 4.13 for inventory reservation model.

Reservation vs Hold for Pickup - Key Distinction:

Aspect	Reservation (Section 1.7.2)	Hold for Pickup (Section 1.11)
What it is	Reserve item at a DIFFERENT store for customer pickup	Pay for items at THIS store, pick up later
Origin	In-store POS (staff-initiated)	In-store POS or Online order (BOPIS)
Payment	Full payment at originating store	Full payment required upfront
Inventory location	At the remote store	At the current store
Customer picks up at	The remote store	The same store (or originating store for BOPIS)
BOPIS	No	Yes - this is the BOPIS flow
Use case	“Store B has it, I’ll drive there to get it”	“I’ll pay now, come back Saturday” or “Order online, pick up in store”

Examples:

Reservation Example: Customer is at Store A. Item is out of stock. Store B has 3 units. Customer pays at Store A. Item is reserved at Store B. Customer drives to Store B to pick it up with their pickup voucher.

Hold for Pickup Example 1 (In-Store): Customer at Store A buys a large piece of furniture. Pays in full. Asks store to hold it until Saturday when they can bring a truck. Store stages the item. Customer returns Saturday to pick up.

Hold for Pickup Example 2 (Online/BOPIS): Customer browses the online store. Selects “Pick Up at Store A.” Pays online. Store A receives the order, stages the items. Customer receives “Ready for Pickup” notification. Customer walks into Store A and picks up.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Hold for Pickup Flow

    U->>UI: Add Items to Cart
    U->>UI: Attach Customer
    U->>UI: Click "Hold for Pickup"

    UI->>UI: Set Pickup Deadline (Default: 7 days)
    UI-->>U: "Customer must pay in full"

    C->>U: Pays Full Amount
    U->>UI: Process Payment

    UI->>API: POST /orders/finalize
    API->>DB: Create Order (Status: HOLD_FOR_PICKUP)
    API->>DB: Set Pickup Deadline
    API->>DB: Reserve Inventory

    API-->>UI: Order Complete
    UI->>U: Print Pickup Slip

    Note over U, DB: Customer Returns to Pickup

    U->>UI: Retrieve Held Order
    UI->>API: GET /orders/held/{id}
    API-->>UI: Display Order Details
    U->>UI: Verify Customer ID
    U->>UI: Click "Release to Customer"

    UI->>API: PATCH /orders/{id}/pickup-complete
    API->>DB: Status: COMPLETED
    API->>DB: Release Inventory Hold

    Note over API, DB: Expiry Handling (Background Job)

    API->>DB: Check Overdue Holds Daily
    alt Hold Expired
        API->>DB: Status: HOLD_EXPIRED
        API-->>U: Alert: "Hold #123 expired - contact customer"
    end

1.11.1 Hold for Pickup State Machine

stateDiagram-v2
    [*] --> HOLD_FOR_PICKUP: Full Payment + Hold Request
    HOLD_FOR_PICKUP --> READY_FOR_PICKUP: Items Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> HOLD_EXPIRED: Deadline Passed
    HOLD_EXPIRED --> CONTACT_CUSTOMER: Staff Notified
    CONTACT_CUSTOMER --> READY_FOR_PICKUP: Deadline Extended
    CONTACT_CUSTOMER --> REFUNDED: Customer Wants Refund

    REFUNDED --> [*]
    COMPLETED --> [*]

1.12 Cash Drawer Management

Scope: Opening float, blind counts, variance tracking, X-reports (mid-shift), and Z-reports (end-of-shift).

Cross-Reference: See Module 5, Section 5.7 for register configuration and Section 5.6 for clock-in/clock-out time tracking.

sequenceDiagram
    autonumber
    participant U as Staff
    participant M as Manager
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Shift Start - Open Drawer

    M->>UI: Open Cash Drawer Session
    M->>UI: Enter Opening Float Amount
    UI->>API: POST /cash-drawer/open
    API->>DB: Create Drawer Session (opening_float, start_time)
    API-->>UI: Drawer Session Started

    Note over U, DB: During Shift - Transactions

    loop Cash Transactions
        U->>UI: Process Cash Sale/Refund
        UI->>DB: Record Cash In/Out
    end

    opt Mid-Shift Check (X-Report)
        U->>UI: Click "X-Report"
        UI->>API: GET /cash-drawer/x-report
        API->>DB: Calculate Current Expected Amount
        Note right of API: Expected = Float + Cash Sales So Far - Cash Refunds - Payouts
        API-->>UI: Return X-Report Data
        UI->>U: Print/Display X-Report
        Note right of UI: X-Report does NOT close the drawer
        Note right of UI: Can be run multiple times per shift
    end

    Note over U, DB: Shift End - Close Drawer

    U->>UI: Click "Close Drawer"
    UI-->>U: "Perform Blind Count"

    U->>UI: Enter Counted Cash (Blind - no expected shown)
    UI->>API: POST /cash-drawer/count

    API->>DB: Calculate Expected Amount
    Note right of API: Expected = Float + Cash Sales - Cash Refunds - Payouts
    API->>DB: Calculate Variance (Counted - Expected)

    alt Variance Within Tolerance
        API-->>UI: "Drawer Balanced"
    else Variance Outside Tolerance
        API-->>UI: "Variance: -$5.00 - Manager Approval Required"
        M->>UI: Enter PIN + Variance Reason
    end

    API->>DB: Close Drawer Session
    API->>DB: Record Final Counts & Variance

    UI->>U: Print Z-Report

    Note over M, DB: Z-Report Contents
    Note right of UI: - Opening Float
    Note right of UI: - Cash Sales Total
    Note right of UI: - Cash Refunds Total
    Note right of UI: - Expected Cash
    Note right of UI: - Counted Cash
    Note right of UI: - Variance (+/-)
    Note right of UI: - Transaction Count

1.12.1 Cash Drawer State Machine

stateDiagram-v2
    [*] --> CLOSED: Drawer Secured
    CLOSED --> OPENING: Manager Opens
    OPENING --> OPEN: Float Entered
    OPEN --> OPEN: Transactions Processed
    OPEN --> COUNTING: Close Initiated
    COUNTING --> BALANCED: Variance Within Tolerance
    COUNTING --> VARIANCE_DETECTED: Variance Outside Tolerance
    VARIANCE_DETECTED --> MANAGER_REVIEW: Awaiting Approval
    MANAGER_REVIEW --> BALANCED: Manager Approved
    BALANCED --> CLOSED: Z-Report Printed

    CLOSED --> [*]

1.12.2 X-Report vs Z-Report

X-Report Use Cases:

• Manager wants to verify cash during a busy period
• Shift handoff between employees (outgoing staff checks before handing off)
• Routine mid-day audit required by store policy
• Investigating a suspected cash handling issue

1.12.3 Reports: Cash Drawer

1.13 Price Check Mode

Scope: Quick price lookup without adding to cart.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend

    C->>U: "How much is this?"

    U->>UI: Click "Price Check" Mode
    UI->>UI: Switch to Price Check Display

    U->>UI: Scan Item Barcode
    UI->>API: GET /products/{sku}
    API-->>UI: Return Product Info

    UI-->>U: Display Large Price
    UI-->>U: Show: Name, SKU, Price, Stock Level

    opt Promotion Active
        UI-->>U: "ON SALE: Was $50, Now $39.99"
    end

    U->>UI: Press Any Key / Timeout
    UI->>UI: Return to Normal Sale Mode

1.14 Coupon System

Scope: Single-use and multi-use coupons (separate from promo codes).

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Coupon Application

    U->>UI: Click "Apply Coupon"
    U->>UI: Scan/Enter Coupon Code

    UI->>API: POST /coupons/validate
    API->>DB: Lookup Coupon

    alt Single-Use Coupon (e.g., Birthday)
        API->>DB: Check if Already Redeemed
        alt Already Used
            API-->>UI: "Coupon Already Redeemed"
        else Valid
            API-->>UI: Return Discount Details
        end

    else Multi-Use Coupon (e.g., SAVE10)
        API->>DB: Check Usage Limit & Expiry
        API-->>UI: Return Discount Details
    end

    alt Valid Coupon
        UI->>UI: Apply Discount
        UI->>UI: Display Savings
        Note right of UI: Coupon marked for redemption at finalize
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Coupon Processing
        API->>DB: Mark Single-Use Coupon as REDEEMED
        API->>DB: Increment Multi-Use Coupon Counter
        API->>DB: Link Coupon to Order
    end

1.14.1 Coupon State Machine

stateDiagram-v2
    [*] --> CREATED: Coupon Generated
    CREATED --> ACTIVE: Published/Distributed

    state ACTIVE {
        [*] --> AVAILABLE
        AVAILABLE --> APPLIED: Added to Cart
        APPLIED --> AVAILABLE: Removed from Cart
        APPLIED --> REDEEMED: Order Finalized
    }

    ACTIVE --> EXPIRED: Past Expiry Date
    ACTIVE --> DEPLETED: Usage Limit Reached (Multi-Use)
    REDEEMED --> [*]: Single-Use Complete
    EXPIRED --> [*]
    DEPLETED --> [*]

1.15 Flexible Loyalty Programs

Scope: Configurable loyalty: points-per-dollar, punch cards, spend thresholds.

Cross-Reference: See Module 5, Section 5.17 for loyalty program settings configuration (point rates, tier thresholds, gift card settings).

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Loyalty Program Types

    U->>UI: Attach Customer to Sale
    UI->>API: GET /customers/{id}/loyalty
    API-->>UI: Return Loyalty Profile & Active Programs

    alt Points Per Dollar Program
        Note right of UI: Earn 1 point per $1 spent
        UI->>UI: Calculate Points to Earn
        UI-->>U: "Customer earns 45 points"

        opt Redeem Points
            U->>UI: Click "Redeem Points"
            UI-->>U: "500 points = $5 off"
            U->>UI: Apply Redemption
        end

    else Punch Card Program
        Note right of UI: Buy 10, Get 1 Free
        UI->>UI: Check Qualifying Items in Cart
        UI-->>U: "Coffee Purchase: Punch 3 of 10"

        opt Card Complete
            UI-->>U: "FREE ITEM EARNED!"
            UI->>UI: Auto-Apply Free Item Discount
        end

    else Spend Threshold Program
        Note right of UI: Spend $100, Get $10 Off
        UI->>UI: Check Customer's Period Spend
        UI-->>U: "Customer has spent $85 this month"

        opt Threshold Reached This Sale
            UI-->>U: "$10 Reward Unlocked!"
            UI->>UI: Apply or Save for Next Visit
        end
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Loyalty Updates
        API->>DB: Award Points Earned
        API->>DB: Update Punch Card Count
        API->>DB: Update Spend Totals
        API->>DB: Check Tier Upgrades
    end

1.15.1 Customer Tier State Machine

stateDiagram-v2
    [*] --> BRONZE: New Customer
    BRONZE --> SILVER: Spend >= $1,000/year
    SILVER --> GOLD: Spend >= $5,000/year
    GOLD --> GOLD: Maintains Spend
    GOLD --> SILVER: Annual Spend < $5,000
    SILVER --> BRONZE: Annual Spend < $1,000

    note right of BRONZE
        1x points
        Standard pricing
    end note

    note right of SILVER
        1.5x points
        5% discount
    end note

    note right of GOLD
        2x points
        10% discount
        Early access
    end note

1.15.2 Reports: Loyalty Programs

1.16 Offline Operations

Scope: Queue-and-sync architecture for network resilience.

Cross-Reference: See Module 4, Section 4.15 for offline inventory operations.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant Q as Local Queue
    participant API as Backend
    participant DB as DB

    Note over U, DB: Network Loss Detected

    UI->>UI: Detect Network Unavailable
    UI-->>U: Display "OFFLINE MODE" Indicator

    Note over U, Q: Processing Sales Offline

    U->>UI: Process Sale
    UI->>Q: Queue Transaction Locally
    Note right of Q: Store: items, customer_id, payments, timestamp
    Q-->>UI: Transaction Queued (#1)
    UI-->>U: "Sale Complete (Pending Sync)"
    UI->>U: Print Receipt with "OFFLINE" watermark

    loop Continue Offline Sales
        U->>UI: Process More Sales
        UI->>Q: Queue Each Transaction
        UI-->>U: Show Queue Count (e.g., "3 pending")
    end

    Note over UI, DB: Network Restored

    UI->>UI: Detect Network Available
    UI-->>U: Display "SYNCING..." Indicator

    loop Sync Queue
        Q->>API: POST /orders/sync
        API->>DB: Validate & Write

        alt Conflict: Item Out of Stock
            API-->>UI: Conflict Detected
            UI-->>U: Alert: "Item X sold out - review order #1"
            Note right of UI: Flag for manager review
        else Success
            API-->>UI: Synced
            Q->>Q: Remove from Queue
        end
    end

    UI-->>U: "All transactions synced"

1.16.1 Offline Mode State Machine

stateDiagram-v2
    [*] --> ONLINE: Network Available
    ONLINE --> OFFLINE: Network Lost
    OFFLINE --> SYNCING: Network Restored
    SYNCING --> ONLINE: Queue Empty
    SYNCING --> CONFLICT_REVIEW: Conflicts Detected
    CONFLICT_REVIEW --> SYNCING: Conflicts Resolved
    CONFLICT_REVIEW --> ONLINE: Manager Override

    note right of OFFLINE
        Queue transactions locally
        Limited operations only
    end note

    note right of SYNCING
        Processing queue
        Show progress
    end note

1.16.2 Offline Operations Rules

offline_mode:
  # Maximum transactions to queue locally
  max_queue_size: 100

  # Auto-sync interval when online (seconds)
  sync_interval_seconds: 30

  # Conflict resolution strategy
  conflict_strategy: "server_wins_with_review"

  # Operations ALLOWED offline
  allowed_offline:
    - sale_new
    - return_with_receipt
    - price_check
    - gift_card_balance_check  # Cached balance, show warning
    - parked_sale_create
    - parked_sale_retrieve

  # Operations BLOCKED offline
  blocked_offline:
    - customer_create          # Requires uniqueness check
    - credit_limit_check       # Requires real-time balance
    - on_account_payment       # Risk of exceeding limit
    - multi_store_inventory    # Requires network
    - gift_card_activation     # Must register immediately
    - gift_card_reload         # Risk of double-load
    - transfer_request         # Requires other store
    - reservation_create       # Requires other store

  # Gift card handling offline
  gift_card_offline:
    balance_check: "use_cached"  # Show cached with warning
    redemption: "block"          # Too risky - balance could be stale

  # Inventory conflict handling
  inventory_conflict:
    # If offline sale sold item that's now out of stock
    resolution: "manager_review"
    auto_backorder: false

1.16.3 Offline Sync Conflict Resolution

1.16.4 Offline Conflict Email Templates

When the system comes back online and discovers that a Transfer, Ship-to-Customer, or Reservation request cannot be fulfilled because the item was sold from the source location during the offline period, the system must automatically notify the customer.

Email Template: TMPL-OFFLINE-SOLD (Item Availability Change Notification)

Offline Conflict Notification Rules:

offline_conflict_notifications:
  # Notify customer when item sold from source location
  item_sold_at_source:
    notify_customer: true
    email_template: "TMPL-OFFLINE-SOLD"
    fallback_if_no_email: "staff_alert"
    # Staff alert appears in manager dashboard
    staff_alert_priority: "high"

1.17 Tax Calculation Engine

Scope: Custom tax engine with jurisdiction support, hierarchy rules, and exemptions.

Cross-Reference: See Module 5, Section 5.9 for tax jurisdiction setup, compound rate configuration (State/County/City), and rate assignment per location.

sequenceDiagram
    autonumber
    participant UI as POS UI
    participant API as Backend
    participant TAX as Tax Engine
    participant DB as DB

    Note over UI, DB: Tax Calculation Flow

    UI->>API: Calculate Tax for Cart
    API->>TAX: Submit Cart + Store Location + Customer

    TAX->>DB: Get Store Tax Jurisdiction
    Note right of DB: Store in Virginia: State 4.3% + Local 1%

    TAX->>DB: Get Customer Tax Status
    Note right of DB: Customer: Regular (no exemption)

    loop For Each Line Item
        TAX->>DB: Get Product Tax Category

        alt Product Override (e.g., Food)
            TAX->>TAX: Apply Product Tax Rate (0% for groceries)
        else Customer Exempt
            TAX->>TAX: Apply 0% Tax
        else Standard
            TAX->>TAX: Apply Jurisdiction Rate (5.3%)
        end
    end

    TAX-->>API: Return Tax Breakdown
    API-->>UI: Display Tax Summary

    Note right of UI: Tax Breakdown:
    Note right of UI: State Tax (4.3%): $4.30
    Note right of UI: Local Tax (1.0%): $1.00
    Note right of UI: Total Tax: $5.30

1.17.1 Tax Hierarchy (Priority Order)

1. Product-Level Override (Highest Priority)
   └── Example: "Grocery - Tax Exempt", "Prepared Food - 10%"

2. Customer-Level Exemption
   └── Example: "Reseller Certificate", "Diplomatic Status", "Non-Profit"

3. Location-Based Tax (Default)
   └── Based on store physical address
   └── Includes: State + County + City + Special District

1.17.2 Virginia Tax Configuration

tax_jurisdictions:
  virginia:
    state_rate: 4.3

    # Regional taxes (in addition to state)
    regions:
      hampton_roads:
        counties: ["Norfolk", "Virginia Beach", "Newport News", "Hampton"]
        additional_rate: 0.7

      northern_virginia:
        counties: ["Arlington", "Fairfax", "Loudoun", "Prince William"]
        additional_rate: 0.7

      central_virginia:
        counties: ["Henrico", "Chesterfield", "Richmond City"]
        additional_rate: 0.0

    # Local tax (most localities)
    default_local_rate: 1.0

    # Product exemptions
    exemptions:
      - category: "grocery_food"
        rate: 1.5  # Reduced rate for groceries
      - category: "prescription_drugs"
        rate: 0.0
      - category: "medical_equipment"
        rate: 0.0

tax_exemption_types:
  - code: "RESALE"
    description: "Reseller Certificate"
    requires_certificate: true
    certificate_expiry: true

  - code: "NONPROFIT"
    description: "501(c)(3) Non-Profit"
    requires_certificate: true
    certificate_expiry: true

  - code: "DIPLOMAT"
    description: "Diplomatic Exemption"
    requires_certificate: true
    certificate_expiry: false

  - code: "NATIVE"
    description: "Native American Tribal Member"
    requires_certificate: true
    certificate_expiry: false

1.17.3 Tax Engine Design for Expansion

Note: The Virginia compound tax jurisdiction model is the active reference implementation. See Section 5.9 for the tax_jurisdictions and tax_rates tables that implement the 3-level compound model (State + County + City).

jurisdiction_modules:
  virginia:
    status: "active"           # Reference implementation
    model: "compound_3_level"  # State + County/Regional + City
    sales_tax: true
    use_tax: false

  california:
    status: "planned"
    sales_tax: true
    district_taxes: true  # Complex district overlay

  oregon:
    status: "planned"
    sales_tax: false  # No sales tax state

  canada:
    status: "planned"
    gst: true
    pst: true  # Varies by province
    hst: true  # Harmonized in some provinces

  european_union:
    status: "planned"
    vat: true
    reverse_charge: true  # B2B cross-border

1.18 Payment Integration (SAQ-A)

Scope: Semi-integrated payment terminal architecture with PCI SAQ-A compliance.

Cross-Reference: Payment data storage rules, terminal communication protocol, processor configuration, and failure handling details have been consolidated into Module 6, Section 6.8. The payment flow sequence diagram below remains in this section as it is part of the core sales workflow.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Your Backend
    participant TERM as Payment Terminal
    participant PROC as Payment Processor

    Note over U, PROC: Card Payment Flow (SAQ-A)

    U->>UI: Click "Pay by Card"
    UI->>API: POST /payments/initiate
    Note right of API: {order_id, amount, terminal_id}

    API->>TERM: Send Payment Request
    Note right of TERM: Amount: $45.00

    TERM-->>U: "Insert/Tap Card"
    Note over TERM: Customer interacts with terminal only

    U->>TERM: Customer taps card
    TERM->>PROC: Encrypted Card Data
    Note right of PROC: Card data NEVER touches your system

    PROC-->>TERM: Authorization Response
    TERM-->>API: Token + Approval Code + Masked Card

    API->>API: Store Token (NOT card data)
    Note right of API: Stored: token, approval_code, ****1234, VISA

    API-->>UI: Payment Approved
    UI-->>U: "Approved - $45.00"

    Note over U, PROC: Refund Flow (Using Token)

    U->>UI: Process Refund
    UI->>API: POST /refunds/create
    Note right of API: {order_id, amount, reason}

    API->>API: Retrieve Stored Token
    API->>PROC: Refund Request with Token
    PROC-->>API: Refund Approved

    API-->>UI: Refund Complete

1.18.1 Payment Data Storage Rules

payment_data:
  # Data your system STORES
  stored:
    - transaction_id        # Your internal ID
    - payment_token         # Processor token for refunds
    - approval_code         # Authorization code
    - masked_card_number    # Last 4 digits only (****1234)
    - card_brand            # Visa, Mastercard, Amex, Discover
    - entry_method          # chip, tap, swipe, manual
    - terminal_id           # Which terminal processed
    - timestamp             # When processed
    - amount                # Transaction amount

  # Data your system NEVER stores (PCI prohibited)
  prohibited:
    - full_card_number      # 16-digit PAN
    - cvv_cvc               # Security code
    - track_data            # Magnetic stripe data
    - pin_block             # Encrypted PIN
    - emv_data              # Chip cryptogram (raw)

1.18.2 Terminal Communication

terminal_integration:
  protocol: "cloud_api"  # Terminal vendor's cloud service

  # Timeout settings
  payment_timeout_seconds: 60
  connection_timeout_seconds: 10

  # Terminal states
  states:
    - IDLE: "Ready for transaction"
    - WAITING_FOR_CARD: "Display amount, await tap/insert"
    - PROCESSING: "Communicating with processor"
    - APPROVED: "Transaction successful"
    - DECLINED: "Transaction declined"
    - ERROR: "Communication or hardware error"
    - CANCELLED: "Customer or staff cancelled"

  # Error handling
  on_timeout: "prompt_retry_or_cancel"
  on_decline: "display_reason_allow_retry"
  on_error: "log_and_alert_manager"

  # Void window (same-day before batch)
  same_day_void: true
  batch_close_time: "23:00"  # Auto-batch at 11 PM

1.18.3 Payment Terminal Failure Handling

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant TERM as Payment Terminal

    U->>UI: Click "Pay by Card"
    UI->>API: POST /payments/initiate
    API->>TERM: Send Payment Request

    alt Terminal Timeout
        TERM--xAPI: No Response (60s)
        API-->>UI: "Terminal not responding"
        UI-->>U: Options: Retry | Different Terminal | Cash | Cancel

    else Terminal Declined
        TERM-->>API: Declined (Insufficient Funds)
        API-->>UI: "Card Declined: Insufficient Funds"
        UI-->>U: Options: Try Another Card | Cash | Cancel

    else Terminal Error
        TERM-->>API: Error (Hardware Issue)
        API-->>UI: "Terminal Error"
        UI-->>U: Options: Different Terminal | Cash | Cancel
        API->>API: Log Error, Alert Manager
    end

1.18.4 Reports: Payment Integration

1.19 Sales User Stories (Epics)

Epic 1.A: Core Sales & Inventory

• Story 1.A.1 (Hybrid Entry): Staff can add items via Scanner (bulk array, max 50 tags) or Barcode (single SKU), with immediate stock validation.
• Story 1.A.2 (Parking): Staff can “Park” a sale (max 5 per terminal, 4-hour TTL) to serve another customer and “Retrieve” it later. Parked items soft-reserve inventory.
• Story 1.A.3 (Mixed Cart): A single transaction can contain both Sales (positive price) and Returns (negative price), calculating a Net Total.
• Story 1.A.4 (Inventory Checks): System validates stock > 0 before adding to cart. Returns trigger INCREMENT stock event; Sales trigger DECREMENT.
• Story 1.A.5 (Price Check Mode): Staff can scan items in “Price Check” mode to display price without adding to cart. Useful for customer inquiries.

Epic 1.B: Pricing & Promotion

• Story 1.B.1 (Smart Promos): The system alerts staff (“Upsell Opportunity”) when a cart is eligible for a promo (e.g., “Buy 2 Get 1 Free”).
• Story 1.B.2 (Granular Discounts): Line-item discounts apply before global discounts. Manager PIN is required for overrides above a certain %.
• Story 1.B.3 (Discount Stacking): System prevents invalid stacking (e.g., cannot use Promo Code on “Clearance” items).
• Story 1.B.4 (Price Tiers): Customers can be assigned price tiers (Retail, Wholesale, VIP, Employee) that apply different base prices before any discounts.
• Story 1.B.5 (Coupon System): System supports both single-use coupons (birthday, referral) and multi-use coupons (promotional codes). Single-use coupons are marked redeemed after use.
• Story 1.B.6 (Discount Order): Discounts apply in strict order: Price Tier → Line Discounts → Auto Promos → Global % → Coupons → Tax → Loyalty Redemptions. Loyalty redemptions apply after tax calculation.

Epic 1.C: Payments & Financials

• Story 1.C.1 (On-Account): Trusted customers can buy on credit. System validates Current Debt + Pending Layaways + Cart <= Credit Limit. Paying off debt requires Cash/Card (prevents circular credit).
• Story 1.C.2 (Layaway): Customers can reserve items with a partial deposit. Inventory is reserved immediately (Status: RESERVED), but revenue is not fully recognized until completion.
• Story 1.C.3 (Split Tender): Transactions support mixed payments (e.g., $20 Cash + Remaining on Card). Customers can use multiple credit cards and combine cash + card(s) in any combination. Each card’s token is stored separately for refund processing.
• Story 1.C.4 (Gift Cards): Staff can sell gift cards, reload existing cards, check balances, and accept gift cards as payment. Partial redemption is supported. Jurisdiction rules apply.
• Story 1.C.5 (Cash Drawer Management): Each shift requires opening float entry, blind cash counts at close, variance tracking, X-report (mid-shift) and Z-report (end-of-shift) generation. Variances outside tolerance require manager approval.
• Story 1.C.6 (Credit Card Payments - SAQ-A): Card payments use semi-integrated terminals. Card data never touches our system. Only tokens, approval codes, and masked card numbers are stored.
• Story 1.C.7 (Payment Failures): When terminal times out, declines, or errors, staff can retry, switch terminals, accept cash, or cancel. All failures are logged.
• Story 1.C.8 (Third-Party Financing - Affirm): Staff can offer Affirm as a payment option. Customer completes financing on their device. Store receives full payment from Affirm immediately. Customer repays Affirm per their loan terms.
• Story 1.C.9 (Multiple Payment Methods): Customers can split payment across multiple credit cards or combine cash + card(s). System tracks each card’s token separately for individual refund processing.

Epic 1.D: Post-Sale & Data

• Story 1.D.1 (Voiding): Voiding is only allowed same business day with drawer open. Voiding reverses inventory, loyalty, and commissions (full reversal). Record is flagged VOIDED, not deleted.
• Story 1.D.2 (Returns): Returns require staff to scan the receipt for system validation before processing. Commission is reversed proportionally based on returned value. Refunds use stored payment tokens or manual terminal processing (staff chooses).
• Story 1.D.3 (Receipts): Staff can choose between Thermal (standard), A4 (invoice), or Gift Receipts (hidden price) at print time.
• Story 1.D.4 (Receipt Reprint): Staff can reprint any historical receipt or email to a different address.
• Story 1.D.5 (History & Export): Managers can filter history by Date/User/Status and export to CSV (limit 1,000 rows for performance).
• Story 1.D.6 (Return Policy Engine): System enforces return and exchange policies that are manually configured in the application’s Settings/Setup module. Policies are per-tenant, per-store, and per-channel (online vs in-store). Example defaults: 30 days full refund with receipt, 31-90 days store credit, no receipt = store credit at current price with manager approval.
• Story 1.D.7 (Dedicated Exchanges): Staff can process exchanges as a single transaction showing item out, item in, and price difference. Exchange records link the original and new items. Commission adjusts for price difference.

Epic 1.E: Special Orders & Transfers

• Story 1.E.1 (Special Orders): Staff can create special orders for out-of-stock items. Customer pays deposit (minimum 50% or configurable). System tracks order status and notifies customer on arrival.
• Story 1.E.2 (Multi-Store Inventory): Staff can view inventory at all store locations (eventually consistent, max 5 min stale). Can request transfers or reserve items at other stores for customer pickup.
• Story 1.E.3 (Transfer/Reserve Payment): Transfers and reservations require customer to pay in full before the request is submitted to the system. This prevents unpaid phantom requests.
• Story 1.E.4 (Hold for Pickup): Fully paid orders can be held for customer pickup with a configurable time limit (default 7 days). System alerts staff when holds expire.
• Story 1.E.5 (Ship to Customer): Staff can ship items from other store locations directly to the customer’s address. System integrates with carrier APIs to calculate real-time shipping costs based on origin store and destination address. Customer pays item price + shipping in full before shipment is initiated. Tracking number is shared with customer via email.

Epic 1.F: Tracking & Commissions

• Story 1.F.1 (Serial Numbers): Designated products require serial number capture at sale. System validates serial hasn’t been previously sold. Serial numbers are searchable for warranty/return lookup.
• Story 1.F.2 (Sales Commissions): Each transaction records the employee ID. Commission amounts are calculated based on sale total and stored for reporting.
• Story 1.F.3 (Commission Reversal): Voided sales reverse commission fully. Returns reverse commission proportionally (returned value / original sale value).
• Story 1.F.4 (Commission Reports): Managers can view commission reports by date range and employee, showing total sales, returns, and net commission earned.

Epic 1.G: Loyalty Programs

• Story 1.G.1 (Points Program): Customers earn points per dollar spent. Points can be redeemed for discounts at configurable rates (e.g., 100 points = $1).
• Story 1.G.2 (Punch Cards): Digital punch cards track qualifying purchases (e.g., 10 coffees = 1 free). Punches are automatically applied based on product categories.
• Story 1.G.3 (Spend Thresholds): Customers earn rewards when spending thresholds are met (e.g., spend $100/month, get $10 off). Rewards can be auto-applied or saved.
• Story 1.G.4 (Loyalty Tiers): Customers automatically upgrade tiers (Bronze → Silver → Gold) based on spend. Higher tiers earn more points or get better rewards.

Epic 1.H: Offline & Resilience

• Story 1.H.1 (Offline Detection): System automatically detects network loss and switches to offline mode with clear visual indicator.
• Story 1.H.2 (Offline Sales): Staff can process sales, returns with receipt, and price checks while offline. Transactions queue locally (max 100).
• Story 1.H.3 (Blocked Offline): System blocks risky operations offline: new customer creation, credit checks, gift card activation/reload, multi-store operations.
• Story 1.H.4 (Auto Sync): When network restores, system automatically syncs queued transactions. Conflicts are flagged for manager review.
• Story 1.H.5 (Conflict Resolution): Manager can review sync conflicts (out of stock, price changes) and approve, modify, or cancel affected transactions.

Epic 1.I: Tax Calculation

• Story 1.I.1 (Jurisdiction Taxes): System calculates tax based on store physical address, applying state + county + city + district rates as applicable.
• Story 1.I.2 (Tax Hierarchy): Product-level tax overrides take priority over customer exemptions, which take priority over default store rates.
• Story 1.I.3 (Tax Exemptions): Customers with valid exemption certificates (resale, non-profit, diplomatic) can be flagged for tax-exempt purchases.
• Story 1.I.4 (Tax Display): Receipt shows tax breakdown by jurisdiction (State Tax: $X, Local Tax: $Y).

1.20 Sales Acceptance Criteria (Gherkin)

Feature: Gift Card Operations

Feature: Gift Card Management
  As a retail staff member
  I need to sell, reload, and redeem gift cards
  So that customers can purchase and use store credit

  Background:
    Given I am logged into the POS system
    And the cash drawer is open

  Scenario: Sell a new gift card
    Given I have a physical gift card with number "GC-000000001234"
    And the gift card status is "INACTIVE"
    When I scan the gift card
    And I enter load amount "$50.00"
    And the customer pays "$50.00"
    Then the gift card status should be "ACTIVE"
    And the gift card balance should be "$50.00"
    And a receipt should print showing "Gift Card Activated: $50.00"

  Scenario: Check gift card balance
    Given a gift card "GC-000000001234" with balance "$35.50"
    When I click "Gift Card Balance"
    And I scan the gift card
    Then the display should show "Balance: $35.50"
    And the display should show expiry info based on jurisdiction

  Scenario: Partial redemption
    Given a gift card "GC-000000001234" with balance "$50.00"
    And a cart total of "$30.00"
    When I apply the gift card as payment
    Then the gift card balance should become "$20.00"
    And the order should be marked "PAID"
    And the gift card status should remain "ACTIVE"

  Scenario: Full redemption depletes card
    Given a gift card "GC-000000001234" with balance "$25.00"
    And a cart total of "$25.00"
    When I apply the gift card as payment
    Then the gift card balance should become "$0.00"
    And the gift card status should be "DEPLETED"

  Scenario: Insufficient balance prompts partial
    Given a gift card "GC-000000001234" with balance "$20.00"
    And a cart total of "$50.00"
    When I apply the gift card as payment
    Then the system should display "Card Balance: $20.00. Apply partial?"
    When I confirm partial application
    Then "$20.00" should be applied from the gift card
    And remaining balance should show "$30.00"

  Scenario: Reload existing gift card
    Given a gift card "GC-000000001234" with balance "$10.00"
    When I scan the gift card
    And I select "Reload"
    And I enter reload amount "$25.00"
    And the customer pays "$25.00"
    Then the gift card balance should be "$35.00"

  Scenario: Cash out in California
    Given the store is located in California
    And a gift card "GC-000000001234" with balance "$8.50"
    When I scan the gift card
    Then the system should show "Eligible for Cash Out: $8.50"
    When I process cash out
    Then the gift card balance should be "$0.00"
    And "$8.50" cash should be given to customer

Feature: Exchange Transactions

Feature: Dedicated Exchange Flow
  As a retail staff member
  I need to process exchanges efficiently
  So that customers can swap items in a single transaction

  Background:
    Given I am logged into the POS system
    And order "ORD-001" exists with item "Blue Shirt" at "$40.00"
    And the original sale had commission "$2.00"

  Scenario: Even exchange - same price items
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" to exchange OUT
    And I scan "Red Shirt" priced at "$40.00" to exchange IN
    Then the price difference should show "$0.00"
    And I should see "Even Exchange - No Payment Required"
    When I complete the exchange
    Then a new exchange record should link "ORD-001" to the new order
    And inventory for "Blue Shirt" should INCREMENT by 1
    And inventory for "Red Shirt" should DECREMENT by 1
    And commission should remain unchanged

  Scenario: Customer owes money - upgrade
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" ($40.00) to exchange OUT
    And I scan "Premium Jacket" priced at "$80.00" to exchange IN
    Then the price difference should show "Customer Owes: $40.00"
    When the customer pays "$40.00"
    And I complete the exchange
    Then the exchange should be recorded successfully
    And additional commission should be recorded for the $40.00 difference

  Scenario: Store owes refund - downgrade
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" ($40.00) to exchange OUT
    And I scan "Basic Tee" priced at "$25.00" to exchange IN
    Then the price difference should show "Refund to Customer: $15.00"
    When I process the refund
    And I complete the exchange
    Then "$15.00" should be refunded to original payment method
    And commission should be reduced proportionally

Feature: Multi-Store Transfer (Full Payment Required)

Feature: Multi-Store Inventory Transfer
  As a retail staff member
  I need to request transfers from other stores
  So that customers can get items not available locally

  Background:
    Given I am logged into POS at "Store A"
    And "Store B" has 5 units of "SKU-12345"
    And "Store A" has 0 units of "SKU-12345"

  Scenario: Transfer request requires full payment
    Given a customer wants "SKU-12345" priced at "$75.00"
    When I search for "SKU-12345"
    And I click "Check Other Stores"
    Then I should see "Store B: 5 units"
    And I should see "Last updated: X minutes ago"
    When I click "Request Transfer" from "Store B"
    Then I should see "Customer must pay in full to process"
    When the customer pays "$75.00"
    Then a transfer record should be created with status "PAID"
    And "Store B" should receive a transfer notification
    And I should print a transfer receipt for the customer

  Scenario: Transfer blocked without payment
    Given a customer wants "SKU-12345" priced at "$75.00"
    When I click "Request Transfer" from "Store B"
    And the customer declines to pay
    Then no transfer record should be created
    And "Store B" inventory should remain unchanged

  Scenario: Reservation at other store requires full payment
    Given a customer wants to pick up "SKU-12345" at "Store B"
    When I click "Reserve at Store B"
    Then I should see "Customer must pay in full to reserve"
    When the customer pays "$75.00"
    Then a reservation should be created at "Store B"
    And the customer should receive a pickup voucher
    And the reservation should expire in 7 days

Feature: Return Policy Engine

Feature: Return Policy Enforcement
  As a retail staff member
  I need the system to enforce return policies
  So that returns are handled consistently

  Scenario: Full refund within 30 days with receipt
    Given order "ORD-001" was placed 15 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Full Refund Eligible"
    And the refund should go to the original payment method
    And commission should be reversed proportionally

  Scenario: Store credit for 31-90 days
    Given order "ORD-001" was placed 45 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Store Credit Only"
    And I should issue store credit for the return amount

  Scenario: Manager override required beyond 90 days
    Given order "ORD-001" was placed 120 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Manager Approval Required"
    When a manager enters their PIN
    And selects exception reason "Customer Goodwill"
    Then the return should proceed

  Scenario: No receipt - store credit at current price
    Given a customer wants to return "Blue Shirt"
    And the customer has no receipt
    And "Blue Shirt" current price is "$35.00"
    When I scan the item barcode
    Then the system should show "No Receipt - Store Credit at Current Price"
    And the system should show "Manager Approval Required"
    When a manager approves
    Then store credit for "$35.00" should be issued

  Scenario: Final sale items blocked
    Given order "ORD-001" contains item "Clearance Item" marked as "Final Sale"
    When I attempt to return "Clearance Item"
    Then the system should show "BLOCKED: Final Sale - No Returns"
    And the return should not proceed

  Scenario: Restocking fee for opened electronics
    Given order "ORD-001" contains "Headphones" in category "Electronics"
    And the item has been opened
    When I process the return
    Then the system should show "Restocking Fee: 15%"
    And the refund should be reduced by 15%

Feature: Void vs Return Distinction

Feature: Void vs Return Rules
  As a retail staff member
  I need clear rules for when to void vs return
  So that corrections are handled properly

  Scenario: Void allowed same day with drawer open
    Given order "ORD-001" was completed today
    And the cash drawer is still open
    When I select order "ORD-001"
    And I click "Void"
    Then the void should be allowed
    And inventory should be reversed immediately
    And commission should be fully reversed
    And the order status should be "VOIDED"

  Scenario: Void blocked after drawer close
    Given order "ORD-001" was completed today
    And the cash drawer has been closed
    When I select order "ORD-001"
    And I click "Void"
    Then the system should show "Cannot void - drawer closed. Use Return instead."

  Scenario: Void blocked next day
    Given order "ORD-001" was completed yesterday
    When I select order "ORD-001"
    And I click "Void"
    Then the system should show "Cannot void - different business day. Use Return instead."

  Scenario: Return uses proportional commission reversal
    Given order "ORD-001" has 3 items totaling "$120.00"
    And commission was "$6.00" (5%)
    When I return 1 item worth "$40.00"
    Then commission should be reduced by "$2.00" (40/120 × $6)
    And net commission should be "$4.00"

Feature: Special Orders

Feature: Special Order Management
  As a retail staff member
  I need to create special orders for out-of-stock items
  So that customers can order items not currently available

  Scenario: Create special order with deposit
    Given "SKU-99999" is out of stock
    And it is available for special order at "$100.00"
    When I create a special order for customer "John Doe"
    And I enter quantity "1"
    Then the system should calculate deposit as "$50.00" (50%)
    When the customer pays "$50.00" deposit
    Then special order "SO-12345" should be created
    And the status should be "DEPOSIT_PAID"
    And the purchasing team should be notified

  Scenario: Complete special order on arrival
    Given special order "SO-12345" exists with deposit "$50.00"
    And the remaining balance is "$50.00"
    When the item arrives and status becomes "READY_FOR_PICKUP"
    Then customer "John Doe" should receive a notification
    When the customer arrives and pays "$50.00"
    Then the special order status should be "COMPLETED"

Feature: Cash Drawer Management

Feature: Cash Drawer Operations
  As a retail staff member
  I need to manage the cash drawer
  So that cash is tracked accurately

  Scenario: Open drawer with float
    Given the cash drawer is closed
    When a manager opens the drawer
    And enters opening float "$200.00"
    Then the drawer session should start
    And the drawer status should be "OPEN"

  Scenario: Close drawer with balanced count
    Given the drawer is open with float "$200.00"
    And cash sales today total "$350.00"
    And cash refunds today total "$50.00"
    When I click "Close Drawer"
    And I perform blind count entering "$500.00"
    Then expected amount should be "$500.00"
    And variance should be "$0.00"
    And the system should show "Drawer Balanced"
    And a Z-report should print

  Scenario: Variance requires manager approval
    Given the drawer is open with float "$200.00"
    And expected cash is "$500.00"
    When I perform blind count entering "$493.00"
    Then variance should be "-$7.00"
    And the system should show "Variance: -$7.00 - Manager Approval Required"
    When a manager enters PIN and reason "Counting Error"
    Then the drawer should close
    And the variance should be logged

  Scenario: Variance within tolerance auto-approves
    Given variance tolerance is set to "$5.00"
    And expected cash is "$500.00"
    When I perform blind count entering "$497.00"
    Then variance should be "-$3.00"
    And the system should show "Drawer Balanced" (within tolerance)

  Scenario: Run X-Report mid-shift
    Given the drawer is open with float "$200.00"
    And cash sales so far total "$150.00"
    And cash refunds so far total "$20.00"
    When I click "X-Report"
    Then the X-Report should show opening float "$200.00"
    And the X-Report should show cash sales "$150.00"
    And the X-Report should show cash refunds "$20.00"
    And the X-Report should show expected cash "$330.00"
    And the drawer should remain OPEN
    And I should be able to continue processing transactions

  Scenario: Run multiple X-Reports in one shift
    Given the drawer is open
    When I run an X-Report at 10:00 AM
    And I process more sales
    And I run another X-Report at 2:00 PM
    Then both X-Reports should complete successfully
    And the second X-Report should reflect updated totals
    And the drawer should remain OPEN

Feature: Coupon System

Feature: Coupon Redemption
  As a retail staff member
  I need to apply coupons to transactions
  So that customers receive their discounts

  Scenario: Apply single-use birthday coupon
    Given coupon "BDAY-JOHN-2026" exists
    And it is a single-use coupon for "$10 off"
    And it has not been redeemed
    When I scan the coupon
    Then "$10.00" discount should apply
    When I complete the sale
    Then the coupon status should be "REDEEMED"

  Scenario: Reject already-used single-use coupon
    Given coupon "BDAY-JOHN-2026" has been redeemed
    When I scan the coupon
    Then the system should show "Coupon Already Redeemed"
    And no discount should apply

  Scenario: Apply multi-use promotional coupon
    Given coupon "SAVE10" exists
    And it is a multi-use coupon for "10% off"
    And it has been used 50 times (limit 1000)
    When I scan the coupon
    Then "10% off" discount should apply
    When I complete the sale
    Then the coupon usage count should be 51

  Scenario: Reject expired coupon
    Given coupon "SUMMER2025" expired on "2025-08-31"
    When I scan the coupon
    Then the system should show "Coupon Expired"
    And no discount should apply

Feature: Loyalty Programs

Feature: Flexible Loyalty Programs
  As a retail staff member
  I need to manage customer loyalty
  So that customers are rewarded for purchases

  Scenario: Earn points per dollar
    Given customer "Jane Doe" is attached to the sale
    And the loyalty program awards 1 point per $1
    And the cart total is "$45.00"
    When I complete the sale
    Then "Jane Doe" should earn 45 points
    And the receipt should show "Points Earned: 45"

  Scenario: Redeem points for discount
    Given customer "Jane Doe" has 500 points
    And redemption rate is 100 points = $1
    When I click "Redeem Points"
    And I redeem 500 points
    Then "$5.00" discount should apply
    And "Jane Doe" points should become 0

  Scenario: Punch card completion
    Given customer "Jane Doe" has a coffee punch card
    And she has 9 of 10 punches
    And the cart contains 1 coffee
    When I complete the sale
    Then the punch card should show "FREE ITEM EARNED!"
    And the 10th coffee should be free
    And a new punch card should start

  Scenario: Tier upgrade on spend threshold
    Given customer "Jane Doe" is "BRONZE" tier
    And she has spent "$950" this year
    And the cart total is "$100"
    When I complete the sale
    Then "Jane Doe" should be upgraded to "SILVER"
    And the system should show "Customer upgraded to Silver!"
    And she should now earn 1.5x points

Feature: Offline Operations

Feature: Offline Mode Operations
  As a retail staff member
  I need to continue serving customers when network is down
  So that business is not interrupted

  Background:
    Given I am logged into the POS system
    And the cash drawer is open

  Scenario: Detect offline and show indicator
    Given the network connection is lost
    Then the UI should show "OFFLINE MODE" indicator
    And the indicator should be prominently visible

  Scenario: Process sale while offline
    Given I am in offline mode
    When I scan items and complete a sale
    Then the transaction should be queued locally
    And the receipt should print with "OFFLINE" watermark
    And I should see "1 transaction pending sync"

  Scenario: Block risky operations offline
    Given I am in offline mode
    When I try to create a new customer
    Then the system should show "Not available offline"
    When I try to activate a gift card
    Then the system should show "Not available offline"
    When I try to check multi-store inventory
    Then the system should show "Not available offline"

  Scenario: Auto-sync when network restores
    Given I am in offline mode
    And I have 3 queued transactions
    When the network connection is restored
    Then the UI should show "SYNCING..."
    And transactions should sync automatically
    When sync completes
    Then the UI should show "All transactions synced"

  Scenario: Handle sync conflict
    Given I am in offline mode
    And I sold the last unit of "SKU-123"
    When the network restores
    And another store also sold the last unit
    Then the system should show "Conflict: SKU-123 out of stock"
    And I should be prompted for manager review
    When the manager approves backorder
    Then the transaction should complete with backorder status

Feature: Payment Integration

Feature: SAQ-A Payment Processing
  As a retail staff member
  I need to process card payments securely
  So that customer card data is protected

  Scenario: Successful card payment
    Given a cart total of "$45.00"
    When I click "Pay by Card"
    Then the terminal should display "$45.00"
    When the customer taps their card
    And the payment is approved
    Then I should see "Approved - $45.00"
    And the receipt should show "VISA ****1234"
    And no full card number should be stored

  Scenario: Card declined - insufficient funds
    Given a cart total of "$200.00"
    When I click "Pay by Card"
    And the customer's card is declined for insufficient funds
    Then I should see "Card Declined: Insufficient Funds"
    And I should have options: "Try Another Card" | "Cash" | "Cancel"

  Scenario: Terminal timeout
    Given a cart total of "$45.00"
    When I click "Pay by Card"
    And the terminal does not respond within 60 seconds
    Then I should see "Terminal not responding"
    And I should have options: "Retry" | "Different Terminal" | "Cash" | "Cancel"

  Scenario: Refund using stored token
    Given order "ORD-001" was paid by card
    And the payment token is stored
    When I process a refund for "ORD-001"
    Then the refund should use the stored token
    And I should not need to re-enter card details
    And the receipt should show "Refund to VISA ****1234"

  Scenario: Pay with Affirm financing
    Given a cart total of "$500.00"
    When I click "Pay with Affirm"
    Then a QR code or redirect should display for the customer
    When the customer completes Affirm application on their device
    And Affirm approves the loan
    Then I should see "Payment Approved (Affirm)"
    And the full $500.00 should be received from Affirm
    And no card data should be stored
    And an Affirm charge_id should be stored

  Scenario: Split payment across two credit cards
    Given a cart total of "$200.00"
    When I click "Pay by Card"
    And the customer pays "$100.00" with first card
    Then remaining balance should show "$100.00"
    When I click "Pay by Card" again
    And the customer pays "$100.00" with second card
    Then the order should be marked "PAID"
    And two separate payment tokens should be stored

  Scenario: Combine cash and card payment
    Given a cart total of "$150.00"
    When I accept "$50.00" cash
    Then remaining balance should show "$100.00"
    When the customer pays "$100.00" by card
    Then the order should be marked "PAID"

Feature: Tax Calculation

Feature: Tax Calculation Engine
  As a retail staff member
  I need accurate tax calculation
  So that the correct tax is collected

  Scenario: Standard Virginia tax
    Given the store is located in Richmond, Virginia
    And the cart contains taxable items totaling "$100.00"
    When I calculate tax
    Then state tax should be "$4.30" (4.3%)
    And local tax should be "$1.00" (1.0%)
    And total tax should be "$5.30"

  Scenario: Northern Virginia regional tax
    Given the store is located in Fairfax, Virginia
    And the cart contains taxable items totaling "$100.00"
    When I calculate tax
    Then state tax should be "$4.30" (4.3%)
    And local tax should be "$1.00" (1.0%)
    And regional tax should be "$0.70" (0.7%)
    And total tax should be "$6.00"

  Scenario: Product-level tax override
    Given the cart contains "Grocery Item" in tax category "grocery_food"
    And "Grocery Item" price is "$20.00"
    When I calculate tax
    Then tax on "Grocery Item" should be "$0.30" (1.5% reduced rate)

  Scenario: Customer tax exemption
    Given customer "ABC Nonprofit" has tax exemption status "NONPROFIT"
    And the cart contains taxable items totaling "$100.00"
    When I attach customer "ABC Nonprofit" to the sale
    And I calculate tax
    Then total tax should be "$0.00"
    And the receipt should show "Tax Exempt: 501(c)(3)"

  Scenario: Tax hierarchy - product override takes priority
    Given customer "ABC Nonprofit" has tax exemption status
    And the cart contains "Prepared Food" (10% tax rate)
    When I calculate tax
    Then the product-level 10% rate should apply
    Because product-level overrides take priority over customer exemption

2. Customers Module

2.1 Customer Management Workflow

Scope: Creating Profiles, Merging Duplicates, Tax Logic, Groups, and Deletion Guards.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 1: Creation & Maintenance

    U->>UI: Search Customer (Name / Phone / Email)
    UI->>API: GET /customers/search

    alt Customer Found
        API-->>UI: Return Profile
        UI-->>U: Display Customer Details + Group + Price Tier
    else Create New
        U->>UI: Enter Details (Name, Phone, Email)
        U->>UI: Enter Physical Address (Shipping)
        U->>UI: Enter Billing Address (if different)

        opt Customer Group Assignment
            U->>UI: Select Group (Retail/Wholesale/VIP/Staff)
            Note right of UI: Group determines Price Tier
        end

        opt Tax Assignment
            U->>UI: Select Custom Tax Rate (e.g., "Tax Exempt")
            Note right of UI: Overrides Default Store Tax
        end

        opt Communication Preferences
            U->>UI: Set Email Opt-In (Y/N)
            U->>UI: Set SMS Opt-In (Y/N)
            U->>UI: Set Preferred Contact Method
        end

        opt Customer Notes
            U->>UI: Enter Size Preferences
            U->>UI: Enter Free-Form Notes
        end

        UI->>API: POST /customers/create
        API->>DB: Insert Record
    end

2.2 Customer Groups & Tiers

Scope: Automatic and manual group assignment with price tier implications.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Customer Group Management

    alt Manual Group Assignment
        U->>UI: Open Customer Profile
        U->>UI: Click "Change Group"
        U->>UI: Select Group (Retail/Wholesale/VIP/Staff)
        UI->>API: PATCH /customers/{id}/group
        API->>DB: Update Customer Group
        API->>DB: Update Price Tier (Based on Group)
        API-->>UI: Group Updated
    end

    Note over API, DB: Automatic Tier Upgrades (Background Job)

    API->>DB: Check Customer Spend Totals

    alt Spend >= Gold Threshold ($5,000/year)
        API->>DB: Upgrade to Gold Tier
        API-->>UI: Notify: "Customer upgraded to Gold!"
    else Spend >= Silver Threshold ($1,000/year)
        API->>DB: Upgrade to Silver Tier
    end

    Note right of DB: Tier Benefits:
    Note right of DB: Bronze: 1x points
    Note right of DB: Silver: 1.5x points + 5% discount
    Note right of DB: Gold: 2x points + 10% discount

2.3 Customer Notes & Preferences

Scope: Structured fields and free-form notes for customer preferences.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    U->>UI: Open Customer Profile
    U->>UI: Click "Notes & Preferences"

    Note over UI, DB: Structured Preferences

    U->>UI: Enter Clothing Size (S/M/L/XL)
    U->>UI: Enter Shoe Size
    U->>UI: Select Color Preferences
    U->>UI: Enter Brand Preferences

    Note over UI, DB: Free-Form Notes

    U->>UI: Enter Notes (e.g., "Prefers classic styles, allergic to wool")

    UI->>API: PATCH /customers/{id}/preferences
    API->>DB: Update Preference Fields
    API-->>UI: Saved

    Note over U, UI: Notes Display at POS

    U->>UI: Attach Customer to Sale
    UI->>API: GET /customers/{id}
    API-->>UI: Return Profile with Notes
    UI-->>U: Display: "Notes: Prefers classic styles, Size M"

2.4 Communication Preferences

Scope: Marketing consent, contact preferences, and opt-out management.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Communication Preference Management

    U->>UI: Open Customer Profile -> Communications

    UI-->>U: Display Current Settings:
    Note right of UI: Email Marketing: [ON/OFF]
    Note right of UI: SMS Marketing: [ON/OFF]
    Note right of UI: Preferred Contact: [Email/Phone/SMS]
    Note right of UI: Do Not Contact: [Y/N]

    U->>UI: Toggle Email Marketing ON
    U->>UI: Toggle SMS Marketing OFF
    U->>UI: Set Preferred: Email

    UI->>API: PATCH /customers/{id}/communication-prefs
    API->>DB: Update Communication Preferences
    API->>DB: Log Consent Change (Audit Trail)
    API-->>UI: Preferences Saved

    Note over API, DB: Privacy Compliance
    Note right of DB: All consent changes logged with timestamp
    Note right of DB: Customer can request full data export
    Note right of DB: "Do Not Contact" blocks all outreach

2.5 Advanced Customer Actions

Scope: Merge duplicates, safe deletion, data export, and privacy compliance.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 2: Advanced Actions (Merge & Delete)

    alt Action: Merge Duplicates
        U->>UI: Select "Source" (Duplicate) & "Target" (Primary)
        U->>UI: Click "Merge Customers"
        UI->>API: POST /customers/merge

        par Data Transfer
            API->>DB: Move History, Loyalty, Balance to Target
            API->>DB: Merge Notes (Append Source to Target)
            API->>DB: Keep Higher Tier
            API->>DB: Soft-Delete "Source" Profile
        end

        API-->>UI: Merge Success
    end

    alt Action: Delete Customer
        U->>UI: Click "Delete Customer"
        UI->>API: GET /customers/{id}/balance-check

        alt Has Debt or Open Layaway
            API-->>UI: Error: "Cannot Delete - Outstanding Balance"
            UI-->>U: Alert: "Settle Balance First"
        else Safe to Delete
            UI->>API: DELETE /customers/{id}
            API->>DB: Anonymize Personal Data
            API->>DB: Retain Sales History (Linked to "Anonymous")
            API-->>UI: Deletion Success
        end
    end

    alt Action: Export Data
        U->>UI: Filter List -> Click "Export CSV"
        UI->>API: POST /customers/export
        Note right of UI: Limit 1000 rows
        API-->>UI: Download CSV File
    end

    alt Action: Data Subject Request (Privacy)
        U->>UI: Click "Privacy Request"
        U->>UI: Select Type: Export / Delete / Restrict
        UI->>API: POST /customers/{id}/privacy-request
        API->>DB: Log Request with Timestamp
        API-->>UI: Request ID Generated
        Note right of API: Must complete within 30 days
    end

2.6 Customer Self-Service

Scope: Customer-facing loyalty balance and preference management.

sequenceDiagram
    autonumber
    participant C as Customer
    participant UI as Self-Service Kiosk / App
    participant API as Backend
    participant DB as DB

    Note over C, DB: Customer Self-Service Options

    alt Check Loyalty Balance
        C->>UI: Enter Phone Number or Scan Card
        UI->>API: GET /customers/lookup?phone={phone}
        API->>DB: Find Customer
        API-->>UI: Return Loyalty Summary
        UI-->>C: Display: "Points: 450 | Tier: Silver | $4.50 available"
    end

    alt Update Preferences
        C->>UI: Login (Phone + PIN)
        UI->>API: GET /customers/{id}/preferences
        API-->>UI: Return Current Preferences
        C->>UI: Update Email / SMS Opt-In
        UI->>API: PATCH /customers/{id}/communication-prefs
        API->>DB: Update & Log Consent Change
        API-->>UI: Saved
    end

    alt Request Data Export
        C->>UI: Click "Download My Data"
        UI->>API: POST /customers/{id}/data-export
        API->>DB: Queue Export Job
        API-->>UI: "Export will be emailed within 24 hours"
    end

2.6.1 Reports: Customer Module

Email Template: TMPL-WELCOME

Email Template: TMPL-TIER-UPGRADE

2.7 Customer User Stories (Epics)

Epic 2.A: Profile & Data Management

• Story 2.A.1 (Detailed Profile): Staff can store distinct “Shipping” (Physical) and “Billing” addresses for a customer to support delivery and invoicing.
• Story 2.A.2 (Duplicate Handling / Merge): Managers can merge two customer profiles. The system must transfer all Sales History, Loyalty Points, Account Balances, and Notes to the “Primary” profile and archive the “Duplicate”.
• Story 2.A.3 (Safe Deletion): The system must block deletion if the customer has an active “On Account” debt or an open “Layaway”. If deleted, their historical sales must remain but be anonymized.
• Story 2.A.4 (Export): Staff can export the customer list to CSV for marketing, limited to 1,000 rows per batch for system stability.
• Story 2.A.5 (Customer Notes): Staff can record structured preferences (size, color, brand) and free-form notes on customer profiles. Notes are displayed when customer is attached to a sale.

Epic 2.B: Financial & Tax Settings

• Story 2.B.1 (Custom Tax Rates): Managers can assign a specific tax exemption status (e.g., “Reseller”, “Non-Profit”) to a customer profile. This status overrides the Store Default Tax when the hierarchy allows.
• Story 2.B.2 (Credit Limits): Managers can set a hard “Credit Limit”. The POS must block any “On Account” sale that pushes (Current Debt + Pending Layaways + Cart) over this limit.
• Story 2.B.3 (Loyalty Adjustments): Managers can manually adjust loyalty points (e.g., +50 “Sorry for wait”). A mandatory reason note is required for audit trails.

Epic 2.C: Customer Groups & Tiers

• Story 2.C.1 (Customer Groups): Customers can be assigned to groups (Retail, Wholesale, VIP, Staff). Each group maps to a price tier that determines base pricing.
• Story 2.C.2 (Automatic Tier Upgrades): Customers automatically upgrade tiers (Bronze → Silver → Gold) when spend thresholds are met. Upgrades can also be manually assigned by managers.
• Story 2.C.3 (Tier Benefits): Each tier has configurable benefits: point multipliers, automatic discounts, and early access to sales.
• Story 2.C.4 (Price Tiers): Different customer groups see different base prices (not just discounts). Wholesale customers may see cost+markup pricing while retail sees standard pricing.

Epic 2.D: Communication & Preferences

• Story 2.D.1 (Communication Consent): Customers can opt-in or opt-out of email and SMS marketing. All consent changes are logged for compliance.
• Story 2.D.2 (Preferred Contact): Customers can specify their preferred contact method (Email, Phone, SMS). Staff can see this preference when reaching out.
• Story 2.D.3 (Do Not Contact): Customers can be flagged as “Do Not Contact” which blocks all marketing outreach while preserving transaction notifications.

Epic 2.E: Privacy & Compliance

• Story 2.E.1 (Data Export): Customers can request a full export of their personal data. Export must be provided within 30 days.
• Story 2.E.2 (Right to Deletion): Customers can request deletion of their personal data. System anonymizes records while preserving transaction history for accounting.
• Story 2.E.3 (Consent Audit Trail): All marketing consent changes are logged with timestamp and source for regulatory compliance.
• Story 2.E.4 (Data Retention): Customer data is retained according to configurable retention policies. Inactive customers can be auto-anonymized after retention period.

Epic 2.F: Self-Service

• Story 2.F.1 (Loyalty Balance Check): Customers can check their loyalty points balance via kiosk, app, or website using phone number lookup.
• Story 2.F.2 (Preference Update): Customers can update their communication preferences (opt-in/opt-out) via self-service channels.
• Story 2.F.3 (Data Request): Customers can submit data export or deletion requests via self-service, which are queued for staff processing.

2.8 Customer Acceptance Criteria (Gherkin)

Feature: Customer Groups and Tiers

Feature: Customer Group Management
  As a retail manager
  I need to assign customers to groups
  So that they receive appropriate pricing and benefits

  Scenario: Assign customer to wholesale group
    Given customer "ABC Corp" exists
    When I open the customer profile
    And I click "Change Group"
    And I select "Wholesale"
    Then the customer group should be "Wholesale"
    And the price tier should update to "Wholesale Pricing"

  Scenario: Automatic tier upgrade on spend
    Given customer "Jane Doe" is "BRONZE" tier
    And she has spent "$4,900" this year
    And annual spend threshold for Silver is "$1,000"
    And annual spend threshold for Gold is "$5,000"
    When she makes a purchase of "$150"
    Then her annual spend becomes "$5,050"
    And she should be upgraded to "GOLD" tier
    And she should now earn 2x points
    And she should receive 10% automatic discount

Feature: Customer Merge

Feature: Merge Duplicate Customers
  As a retail manager
  I need to merge duplicate customer profiles
  So that customer data is consolidated

  Scenario: Merge two customer profiles
    Given customer "John Doe" (ID: 100) has:
      | Loyalty Points | 500 |
      | Account Balance | $50.00 |
      | Tier | Silver |
    And customer "J. Doe" (ID: 101) has:
      | Loyalty Points | 200 |
      | Account Balance | $25.00 |
      | Tier | Bronze |
    When I select "J. Doe" as source and "John Doe" as target
    And I click "Merge Customers"
    Then "John Doe" should have:
      | Loyalty Points | 700 |
      | Account Balance | $75.00 |
      | Tier | Silver |
    And "J. Doe" profile should be archived
    And sales history from both should be under "John Doe"

Feature: Safe Customer Deletion

Feature: Customer Deletion Guards
  As a retail manager
  I need deletion to be blocked when unsafe
  So that we don't lose important data

  Scenario: Block deletion with outstanding debt
    Given customer "John Doe" has account balance "$150.00"
    When I click "Delete Customer"
    Then the system should show "Cannot Delete - Outstanding Balance"
    And the deletion should be blocked

  Scenario: Block deletion with open layaway
    Given customer "John Doe" has an active layaway order
    When I click "Delete Customer"
    Then the system should show "Cannot Delete - Open Layaway"
    And the deletion should be blocked

  Scenario: Safe deletion anonymizes data
    Given customer "John Doe" has no debt or layaway
    And "John Doe" has 5 historical orders
    When I click "Delete Customer"
    And I confirm the deletion
    Then personal data should be anonymized
    And the 5 orders should remain linked to "Anonymous Customer"

Feature: Communication Preferences

Feature: Communication Preference Management
  As a retail staff member
  I need to manage customer communication preferences
  So that we comply with privacy regulations

  Scenario: Update email opt-in
    Given customer "Jane Doe" has email marketing OFF
    When I open communications preferences
    And I toggle email marketing ON
    Then email marketing should be ON
    And a consent change should be logged with timestamp

  Scenario: Do Not Contact blocks outreach
    Given customer "John Doe" is flagged "Do Not Contact"
    When the marketing system attempts to send email
    Then the email should be blocked
    And no marketing should be sent

  Scenario: Transaction notifications still sent
    Given customer "John Doe" is flagged "Do Not Contact"
    When he makes a purchase
    Then a receipt email should still be sent
    Because transaction notifications are not marketing

Feature: Privacy Compliance

Feature: Customer Privacy Rights
  As a customer
  I need to exercise my privacy rights
  So that my data is protected

  Scenario: Request data export
    Given I am customer "Jane Doe"
    When I request a data export
    Then a request should be logged
    And I should receive confirmation
    And my data should be emailed within 30 days

  Scenario: Request data deletion
    Given I am customer "Jane Doe"
    And I have no outstanding balance or layaway
    When I request data deletion
    Then my personal data should be anonymized
    And my transaction history should be preserved (anonymized)
    And I should receive confirmation

  Scenario: Deletion blocked with balance
    Given I am customer "Jane Doe"
    And I have account balance "$50.00"
    When I request data deletion
    Then the system should show "Please settle outstanding balance first"
    And my data should not be deleted

Feature: Customer Self-Service

Feature: Customer Self-Service
  As a customer
  I want to check my loyalty status
  So that I know my rewards

  Scenario: Check loyalty balance
    Given I am customer with phone "555-1234"
    And I have 450 loyalty points
    And I am Silver tier
    When I enter my phone number at the kiosk
    Then I should see "Points: 450"
    And I should see "Tier: Silver"
    And I should see "$4.50 available for redemption"

  Scenario: Update marketing preferences
    Given I am logged into self-service
    And email marketing is ON
    When I toggle email marketing OFF
    Then email marketing should be OFF
    And a consent change should be logged

3. Catalog Module

3.1 Product Types & Data Model

Scope: Core POS Catalog – all product entries, types, data fields, and the relationships between them. Every item sold, bundled, or serviced flows through the catalog. The data model supports four distinct product types that cover the full range of retail merchandise: individually tracked goods, multi-dimension variants, composite bundles, and non-inventory services. Beyond the standard field set, the model supports tenant-defined custom attributes, product templates for rapid creation, and a matrix management interface for efficient variant operations.

Cross-Reference: See Module 5, Section 5.10 for UoM configuration and Section 5.12 for custom fields.

3.1.1 Product Types

3.1.2 Product Class Diagram

classDiagram
    class Product {
        +UUID id
        +String sku
        +String name
        +String product_type
        +Decimal base_price
        +Decimal cost
        +String lifecycle_status
        +Boolean shippable
        +UUID package_type_id
        +Enum selling_uom
        +Enum purchasing_uom
        +Decimal uom_conversion_factor
        +UUID season_id
        +UUID brand_id
        +DateTime created_at
        +DateTime updated_at
    }

    class StandardProduct {
        +String barcode
        +String[] alternate_barcodes
        +Boolean track_inventory
        +Integer low_stock_threshold
    }

    class VariantParent {
        +String[] dimension_names
        +Integer dimension_count
        +String style_number
        +String[] demographics_age_group
        +String[] demographics_gender
        +String origin
        +String fabric
        +UUID season_id
    }

    class VariantChild {
        +UUID parent_id
        +String dimension_1_value
        +String dimension_2_value
        +String dimension_3_value
        +String barcode
        +Decimal price_override
        +Decimal msrp
        +Boolean track_inventory
        +Boolean deletion_protected
    }

    class CompositeProduct {
        +Decimal bundle_price
        +Boolean allow_component_substitution
    }

    class BundleComponent {
        +UUID composite_id
        +UUID component_product_id
        +Integer quantity
        +Decimal component_cost_allocation
    }

    class ServiceProduct {
        +Integer estimated_minutes
        +Boolean requires_appointment
        +String service_category
    }

    class CustomAttributeDefinition {
        +UUID id
        +String name
        +Enum type
        +Boolean required
        +UUID tenant_id
    }

    class ProductCustomAttribute {
        +UUID product_id
        +UUID definition_id
        +String value
    }

    class PackageType {
        +UUID id
        +String name
        +Decimal length
        +Decimal width
        +Decimal height
        +Decimal empty_weight
        +UUID tenant_id
    }

    Product <|-- StandardProduct
    Product <|-- VariantParent
    Product <|-- CompositeProduct
    Product <|-- ServiceProduct
    VariantParent "1" --> "*" VariantChild : has children
    CompositeProduct "1" --> "*" BundleComponent : contains
    BundleComponent "*" --> "1" Product : references component
    Product "0..*" --> "0..*" ProductCustomAttribute : has custom values
    ProductCustomAttribute "*" --> "1" CustomAttributeDefinition : defined by
    Product "*" --> "0..1" PackageType : ships in

3.1.3 Full Product Data Model

Business Rules – Shipping:

• IF shippable = true THEN weight, length, width, and height are all mandatory. The system rejects save attempts where shippable is enabled but physical dimensions are missing.
• IF package_type_id is set, the package dimensions auto-populate from the PackageType record but can be overridden at the product level.

Business Rules – Unit of Measure:

• IF purchasing_uom differs from selling_uom, then uom_conversion_factor is mandatory.
• Receiving inventory via Purchase Order uses purchasing_uom; inventory levels and POS transactions use selling_uom. The system automatically converts quantities using the conversion factor.

3.1.4 Custom Attributes

Scope: Tenant-defined key/value custom fields that extend the standard product data model. Custom attributes allow each tenant to capture business-specific data (e.g., “Certification Level”, “Country of Origin Detail”, “Season Year”) without schema changes.

Custom Attribute Definition Table

ProductCustomAttribute Junction Table

Business Rules:

• Limit: Up to 50 custom attribute definitions per tenant. Attempting to create a 51st returns an error with guidance to archive unused attributes.
• Indexing: All attributes marked searchable = true are indexed via a GIN index on a materialized JSONB representation for fast full-text search.
• Filtering: Attributes marked filterable = true appear as sidebar filters in the Admin Portal product list and can be used in smart collection rules.
• Validation: When type = LIST, the system rejects any value not present in list_values[]. When type = NUMBER, the system validates numeric format. When required = true, product save is blocked until a value is provided.
• Inheritance: Custom attributes are set at the parent product level. Variant children inherit parent custom attributes and cannot override them individually.

3.1.5 Product Templates & Cloning

Scope: Accelerating product creation by cloning existing products and by applying category-based templates with pre-filled default values. Templates reduce repetitive data entry for categories with consistent attributes (e.g., all t-shirts share the same weight range, tax code, and fabric type).

Product Cloning

• Clone any product to create a new DRAFT with a new auto-generated SKU. All fields are copied except identity fields (id, sku, barcode), timestamps (created_at, updated_at, published_at), and audit fields (created_by is set to the cloning user).
• Cloned products always start in DRAFT status regardless of the source product’s status.
• For variant products, cloning copies the parent AND all child variants. Each child receives a new auto-generated SKU. Inventory levels are NOT copied (all set to zero).
• Cloned products receive a default name of “{Original Name} (Copy)” which staff must rename before publishing.

Category-Based Templates

Templates save pre-filled default values per category so that new products created in that category start with sensible defaults already populated.

Template Data Model

Example default_values JSON:

{
  "fabric": "100% Cotton",
  "weight": 0.35,
  "weight_unit": "lb",
  "tax_code": "clothing_exempt",
  "selling_uom": "EACH",
  "shippable": true,
  "track_inventory": true,
  "low_stock_threshold": 5,
  "demographics_gender": ["Men"],
  "demographics_age_group": ["Adult"],
  "origin": "Imported",
  "custom_attributes": {
    "Certification": "None",
    "Care Instructions": "Machine wash cold"
  }
}

Business Rules:

• One template per category per tenant. If a template already exists for a category, staff must edit the existing template rather than create a duplicate.
• When a product is created and assigned to a category that has a template, the system auto-fills all fields from default_values. Staff can override any auto-filled value before saving.
• Templates do not retroactively update existing products. They apply only at creation time.
• Template fields that conflict with required product fields are ignored (e.g., a template cannot set name or sku).

3.1.6 Product Matrix Management

Scope: A grid-based interface for managing variant products efficiently. The matrix view presents all variant combinations in a spreadsheet-like layout, enabling rapid price/cost/stock editing and bulk variant creation.

Matrix Grid View

For variant products with two dimensions, the matrix displays:

• Rows = Dimension 1 values (e.g., sizes: S, M, L, XL, XXL)
• Columns = Dimension 2 values (e.g., colors: Red, Blue, Navy, Black)
• Each cell shows: price, cost, and current stock level for that combination

              | Red        | Blue       | Navy       | Black      |
---------------------------------------------------------------------------
  S           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 14  | Stock: 11  | Stock: 9   | Stock: 7   |
---------------------------------------------------------------------------
  M           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 22  | Stock: 18  | Stock: 15  | Stock: 13  |
---------------------------------------------------------------------------
  L           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 19  | Stock: 16  | Stock: 12  | Stock: 10  |
---------------------------------------------------------------------------
  XL          | $32 / $13  | $32 / $13  | $32 / $13  | $32 / $13  |
              | Stock: 8   | Stock: 6   | Stock: 5   | Stock: 4   |

Inline Editing:

• Click any cell to edit price, cost, or stock level directly in the grid.
• Tab key moves to the next cell. Enter confirms the edit.
• Changed cells are highlighted until saved. A single “Save All Changes” action persists all edits in one batch.

Bulk-Create Variants:

• Select dimension value combinations via checkboxes (e.g., check “XXL” row and all color columns) to generate all child SKUs in one operation.
• The system auto-generates SKUs using the configured SKU pattern, assigns the parent’s base price and cost as defaults, and sets initial inventory to zero.
• Staff can review generated variants before confirming creation.

Matrix Import via CSV:

• Upload a CSV file with columns matching dimension values and data fields.
• CSV format: dimension_1_value, dimension_2_value, price, cost, barcode
• The system validates all rows, reports errors (duplicate barcodes, invalid dimension values, non-numeric prices), and applies valid rows in batch.
• Supports both CREATE (new variants) and UPDATE (existing variants matched by dimension values) modes.

Business Rules:

• Matrix view is available only for products with exactly 2 variant dimensions. Products with 1 or 3 dimensions use the standard list editor.
• Cells for non-existent variant combinations display as empty with a “+” icon to create that specific variant on demand.
• Deleting a variant from the matrix is only permitted when the variant has zero inventory across all locations and no open orders referencing it.

3.2 Product Lifecycle

Scope: Managing products from initial creation through active selling, discontinuation, archival, and potential re-creation from archived templates. The lifecycle enforces data completeness before publishing and protects against premature archival while stock remains on hand.

3.2.1 Product Lifecycle State Machine

stateDiagram-v2
    [*] --> DRAFT: Product Created
    DRAFT --> ACTIVE: Publish
    ACTIVE --> DISCONTINUED: Discontinue
    DISCONTINUED --> ACTIVE: Reactivate
    DISCONTINUED --> ARCHIVED: Archive (stock = 0 all locations)
    ARCHIVED --> DRAFT: Clone as New (new SKU)

    note right of DRAFT
        Incomplete product
        Not visible at POS
        No sales allowed
    end note

    note right of ACTIVE
        Fully configured
        Available for sale
        Visible at POS
    end note

    note right of DISCONTINUED
        Sell-through mode
        No restock / no new POs
        Still sellable until stock = 0
    end note

    note right of ARCHIVED
        Read-only historical record
        Not visible at POS
        Can clone to create new product
    end note

3.2.2 Lifecycle Transition Rules

Business Rules:

• A product cannot be archived while any location holds stock. The system checks qty_on_hand across all locations before allowing the transition.
• Cloning an archived product does NOT restore the original. It creates a new, separate product that can be edited independently.
• Discontinued products continue to appear in POS barcode lookup and search so that remaining stock can be sold.

3.3 Pricing Engine

Scope: Managing product pricing across channels, customer groups, and promotional periods. The engine supports centralized pricing with cascading overrides, named price books, four promotion types, formal markdown workflows, and best-price conflict resolution. Every price determination is auditable – the system logs which rules were evaluated, which rule won, and the final price applied.

3.3.1 Price Hierarchy

Centralized pricing with cascading override resolution. When determining the price for a product at checkout, the system evaluates five priority levels and applies the highest-priority match:

flowchart TD
    A[Start: Determine Price] --> B{Manual Override?}
    B -->|Yes| C[Use Manual Override Price]
    B -->|No| D{Active Promotion?}
    D -->|Yes| E[Use Promotion Price]
    D -->|No| F{Price Book Match?}
    F -->|Yes| G[Use Price Book Price]
    F -->|No| H{Channel Price Set?}
    H -->|Yes| I[Use Channel Price]
    H -->|No| J[Use base_price from Product]
    C --> K[Log Price Resolution to Audit Trail]
    E --> K
    G --> K
    I --> K
    J --> K
    K --> L[Return Final Price]

3.3.2 Price Books

Scope: Named price lists that override global pricing for specific customer groups, channels, or date ranges. Price books enable scenarios such as wholesale pricing for B2B customers, employee discount pricing, and seasonal price adjustments without modifying the base product price.

Price Book Data Model

Price Book Entry Table

Business Rules:

• Exclusivity: Only one price book can be active per customer group per channel at any given time. If a new price book overlaps with an existing active book for the same group/channel combination, the system rejects creation and prompts the user to deactivate the conflicting book first.
• No stacking: Price books do not stack. When multiple price books match (e.g., one by customer group and one by channel), only the book with the highest priority value applies.
• Audit: Every price book activation, deactivation, and entry modification is logged with the acting user and timestamp.
• Bulk entry: Staff can import price book entries via CSV with columns: sku, override_price, override_cost. The system validates SKU existence and numeric formats before applying.

3.3.3 Promotions

Scope: Four promotion types that cover the most common retail discount scenarios. Promotions can be automatic (applied when conditions are met) or code-based (requiring manual entry at POS).

Promotion Types

Tiered / Volume Example:

BOGO / Cross-Item Example:

• Buy 2 Shirts (buy_product_id = shirts category, buy_qty = 2), Get 1 Belt 50% off (get_product_id = belts category, get_qty = 1, get_discount_type = PERCENT, get_discount_value = 50)

Scheduled / Automatic Example:

• Happy Hour: schedule_type = RECURRING, recurrence_pattern = “MON-FRI 15:00-17:00” – 15% off all drinks every weekday from 3 PM to 5 PM

Promotion Data Model

Promotion Lifecycle

stateDiagram-v2
    [*] --> DRAFT : Create Promotion
    DRAFT --> SCHEDULED : Set dates & activate
    DRAFT --> CANCELLED : Cancel before scheduling
    SCHEDULED --> ACTIVE : Start date reached
    SCHEDULED --> CANCELLED : Cancel before start
    ACTIVE --> EXPIRED : End date passed
    ACTIVE --> CANCELLED : Manually deactivate
    CANCELLED --> [*]
    EXPIRED --> [*]

Lifecycle Transition Rules:

• DRAFT: Promotion is being configured. Not visible to POS. Can be edited freely.
• SCHEDULED: Promotion is locked for editing (except cancellation). Awaiting start date.
• ACTIVE: Promotion is live. Applied automatically or via code at POS. Only the is_active toggle and end_date can be modified.
• EXPIRED: Terminal state. Promotion has passed its end date. Preserved for reporting. Cannot be reactivated – must be cloned to create a new promotion.
• CANCELLED: Terminal state. Promotion was manually stopped. Preserved for reporting.

3.3.4 Markdown & Clearance Management

Scope: Formal workflows for reducing prices, tracking clearance merchandise, and handling end-of-life write-offs. Every price reduction is accountable – the system enforces approval workflows and logs all changes for audit.

Markdown Request Workflow

sequenceDiagram
    autonumber
    participant S as Staff
    participant UI as Admin Portal
    participant API as Backend
    participant M as Manager
    participant DB as DB
    participant POS as POS Client

    Note over S, POS: Markdown Request Workflow

    S->>UI: Create Markdown Request
    Note right of UI: Product, new_price, effective_date, reason

    UI->>API: POST /markdowns
    API->>DB: Save request (status: PENDING)
    API-->>UI: Request #MD-001 created

    API->>M: Notification: Markdown request pending
    M->>UI: Review request details
    Note right of M: Current price, proposed price,<br/>margin impact, reason

    alt Approved
        M->>API: PATCH /markdowns/MD-001 {status: APPROVED}
        API->>DB: Update status, schedule price change
        Note right of DB: effective_date triggers price update

        DB-->>API: Price updated on effective_date
        API->>POS: Push updated price to all terminals
        API->>DB: Log to price_audit_trail
        Note right of DB: who, when, old_price,<br/>new_price, reason, approval_id
    else Rejected
        M->>API: PATCH /markdowns/MD-001 {status: REJECTED, reject_reason: "..."}
        API-->>S: Notification: Markdown rejected
    end

Manual Price Changes:

• Staff with appropriate permissions can change a product’s price directly without the formal markdown workflow.
• Every manual change requires selecting a reason from a configurable list: Damaged, Price Match, Manager Discretion, Competitive Adjustment, Cost Change, Seasonal Reduction, Error Correction.
• All manual changes are logged to the price audit trail: user_id, timestamp, product_id, old_price, new_price, reason, location_id.

Automatic Markdown Rules:

• Configurable rules engine that evaluates nightly and flags or automatically applies markdowns:

• Automatic rules can be configured to either flag for review (creates a pending markdown request) or apply immediately (executes the price change and logs it as auto-rule).

Liquidation / Write-Off:

• When a product cannot sell at any price (damaged beyond sale, expired, recalled), staff create a write-off record.

Clearance Rack Tracking:

• Each product can be flagged as clearance on a per-location basis.
• Clearance fields: is_clearance (Boolean), clearance_price (Decimal), clearance_started_at (DateTime).
• Products flagged as clearance appear in a dedicated “Clearance” collection on the POS browse screen and can be filtered in reports.
• Clearance pricing takes precedence over the product’s base_price but is overridden by active promotions and manual overrides per the standard price hierarchy.

3.3.5 Conflict Resolution

Scope: Determining the final price when multiple pricing rules match the same product at checkout. The resolution algorithm ensures predictability, transparency, and customer-friendly outcomes.

Resolution Algorithm:

1. Check exclusivity: If any matched promotion has exclusive = true, use ONLY that promotion. If multiple exclusive promotions match, the one with the highest priority wins. All other pricing rules are ignored.

2. If no exclusive promotion: Apply the best price for the customer (lowest final price) from among:

   • The winning price book entry (if any)
   • The winning non-exclusive promotion (if any)
   • The channel price (if set)
   • The base price

3. Stackable promotions: Stackable promotions combine ONLY when both are marked stackable = true. The combined discount must not exceed the tenant’s max_discount_percent setting (default: 75%). If stacking would exceed the cap, the system applies the single best promotion instead.

4. Manual override: A manual override entered by staff at the POS always wins regardless of all other rules. It bypasses the algorithm entirely.

Conflict Resolution Flowchart:

flowchart TD
    A[Checkout: Evaluate Price] --> B[Gather all matching rules]
    B --> C{Any exclusive promotion?}
    C -->|Yes| D[Use highest-priority exclusive promo]
    C -->|No| E{Multiple stackable promos?}
    E -->|Yes| F{Combined discount <= max_discount_percent?}
    F -->|Yes| G[Apply stacked promotions]
    F -->|No| H[Apply single best promotion]
    E -->|No| I[Compare: Promo vs Price Book vs Channel vs Base]
    I --> J[Use lowest final price for customer]
    D --> K[Log: rules evaluated, winner, reason]
    G --> K
    H --> K
    J --> K

Audit: Every price resolution is logged with the following data:

• sale_id, line_item_id, product_id
• rules_evaluated[] – list of all pricing rules that were considered
• winning_rule_id and winning_rule_type (MANUAL / PROMOTION / PRICE_BOOK / CHANNEL / BASE)
• original_price (base_price) and final_price
• total_discount_amount and total_discount_percent
• timestamp

3.3.6 Reports: Pricing

3.4 Barcode Management

Scope: Supporting multiple barcode formats per product, auto-generating internal barcodes when no manufacturer code exists, enforcing uniqueness per tenant, and enabling fast barcode-to-product lookup from any scanner or manual entry.

3.4.1 Barcode Types

3.4.2 Barcode Features

• Multiple barcodes per product: Each product has one primary barcode and unlimited alternate barcodes. Scanning ANY barcode (primary or alternate) resolves to the same product.
• Auto-generate internal barcode: When a product is created without a manufacturer barcode, the system auto-generates an internal barcode using the tenant’s configured prefix and the next available sequence number.
• Uniqueness enforced per tenant: No two products within the same tenant can share a barcode (primary or alternate). The system rejects duplicates at creation and import time.
• Universal scan resolution: POS barcode lookup checks the primary barcode first, then searches alternate barcodes. The lookup returns the same product regardless of which barcode was scanned.
• Bulk barcode import via CSV: Staff can upload a CSV file mapping barcodes to existing SKUs. The system validates uniqueness, reports conflicts, and applies valid mappings in batch.

3.4.3 Barcode Lookup Flow

sequenceDiagram
    autonumber
    participant U as Staff
    participant SC as Scanner
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Barcode Scan to Product Lookup

    alt Barcode Scanner
        U->>SC: Scan Item Barcode
        SC->>UI: Barcode Value (e.g., "012345678901")
    else Manual Entry
        U->>UI: Type Barcode / SKU
    end

    UI->>API: POST /products/barcode-lookup
    Note right of API: {barcode: "012345678901", tenant_id: "..."}

    API->>DB: SELECT * FROM products WHERE barcode = ?
    Note right of DB: Check primary barcode first

    alt Primary Barcode Match
        DB-->>API: Product Found
    else No Primary Match
        API->>DB: SELECT * FROM alternate_barcodes WHERE barcode = ?
        Note right of DB: Search alternate barcodes

        alt Alternate Barcode Match
            DB-->>API: Product Found (via alternate)
        else No Match Found
            DB-->>API: No Results
            API-->>UI: "Product Not Found"
            UI-->>U: "No product matches this barcode"
            Note right of UI: Option: Create new product or re-scan
        end
    end

    API-->>UI: Return Product Data
    UI-->>U: Display: Name, SKU, Price, Stock Level
    Note right of UI: Product ready to add to cart

3.4.4 Reports: Barcode Management

3.5 Categories, Seasons & Collections

Scope: Organizing products into a navigable hierarchy for POS browsing, reporting, and rule application (tax defaults, commission rates). The system supports up to four levels of nesting, freeform tags, named collections, auto-tagging rules, formal buying seasons with lifecycle management, and multi-dimensional reporting hierarchies for financial analysis.

3.5.1 Category Hierarchy

The catalog supports a 4-level hierarchy. Products are assigned to the most specific level applicable.

Level 1: Department
|-- Level 2: Category
    |-- Level 3: Subcategory
        |-- Level 4: Sub-subcategory (max depth)

Example:
Men's Apparel                          (Department)
|-- Tops                               (Category)
|   |-- T-Shirts                       (Subcategory)
|   |   |-- Graphic Tees               (Sub-subcategory)
|   |   |-- Plain Tees                 (Sub-subcategory)
|   |-- Dress Shirts                   (Subcategory)
|   |-- Polos                          (Subcategory)
|-- Bottoms                            (Category)
|   |-- Jeans                          (Subcategory)
|   |-- Chinos                         (Subcategory)
|-- Outerwear                          (Category)
    |-- Jackets                        (Subcategory)
    |-- Coats                          (Subcategory)

Accessories                            (Department)
|-- Bags                               (Category)
|-- Hats                               (Category)
|-- Jewelry                            (Category)

Services                               (Department)
|-- Alterations                        (Category)
|-- Gift Services                      (Category)

3.5.2 Tags & Collections

Tags: Unlimited freeform tags can be applied to any product. Tags are tenant-scoped and support search filtering.

3.5.3 Category Features

• Drag-and-drop reordering: Staff can reorder categories and products within categories via drag-and-drop in the catalog management UI.
• Category-level default tax code: Each category can specify a default tax code (e.g., “clothing_exempt”, “grocery_food”). Products inherit the category tax code unless overridden at the product level.
• Category-level default commission rate: Each category can specify a default commission percentage. Used for commission calculation unless overridden at the product level.
• Bulk move products: Staff can select multiple products and move them to a different category in a single action.
• Category image/icon: Each category can have an assigned image or icon for display in POS browse mode and kiosk interfaces.

3.5.4 Reports: Category Management

3.5.5 Formal Seasons

Scope: Named buying seasons with lifecycle dates that track merchandise from initial buy planning through active selling, clearance, and close-out. Seasons provide a temporal dimension to inventory analysis – enabling sell-through tracking, carryover identification, and season-over-season comparison.

Season Data Model

Example Seasons:

Season Lifecycle State Machine

stateDiagram-v2
    [*] --> PLANNING : Create Season
    PLANNING --> ACTIVE : Season start date reached
    ACTIVE --> CLEARANCE : Triggered by staff or auto-rule
    CLEARANCE --> CLOSED : Season end date passed
    PLANNING --> CLOSED : Cancel season (no products received)
    CLOSED --> [*]

Lifecycle Transition Rules:

• PLANNING: Season is being prepared. Products can be assigned to this season. Purchase orders can reference this season. No products are expected on the sales floor yet.
• ACTIVE: Season merchandise is on the sales floor and selling. Transition occurs automatically when start_date is reached, or manually by staff. Products assigned to this season appear in season-filtered reports.
• CLEARANCE: Triggered manually by a buyer/manager OR by an automatic rule (e.g., “30 days before end_date, move to CLEARANCE”). Products in this season become eligible for automatic markdown rules. The clearance collection auto-populates with this season’s products.
• CLOSED: Terminal state. Season has ended. Remaining inventory is flagged as carryover. No further price changes tied to this season. Season data is preserved for historical reporting.

Product-Season Assignment:

• Products are assigned to seasons via the season_id FK on the product record.
• A product can belong to at most ONE season. Products with season_id = NULL are year-round core items not tied to any season.
• When a season transitions to CLOSED, products still assigned to it can be reassigned to a new season (carryover) or have their season_id set to NULL (promoted to core).

3.5.6 Reporting Dimensions

Scope: Structured classification hierarchies used exclusively for financial reporting and buying analysis. Reporting dimensions are separate from display categories – a product’s display category determines where it appears in the POS browse screen, while reporting dimensions determine how it appears in financial reports, open-to-buy analysis, and margin summaries.

Brand

• Products are assigned to brands via the brand_id FK on the product record.
• Brand is distinct from Vendor. Nike the brand (what the customer sees on the label) is different from Nike Direct the vendor (the company you send purchase orders to). A single brand may be sourced from multiple vendors. A single vendor may supply multiple brands.

Merchandise Hierarchy

A 3-level reporting hierarchy independent of display categories:

Department (Level 1)
|-- Class (Level 2)
    |-- Subclass (Level 3)

Example:
Footwear                               (Department)
|-- Athletic Shoes                     (Class)
|   |-- Running                        (Subclass)
|   |-- Basketball                     (Subclass)
|   |-- Training                       (Subclass)
|-- Casual Shoes                       (Class)
|   |-- Sneakers                       (Subclass)
|   |-- Loafers                        (Subclass)
|-- Dress Shoes                        (Class)
    |-- Oxfords                        (Subclass)
    |-- Derby                          (Subclass)

Merchandise Hierarchy Fields on Product:

• The merchandise hierarchy enables financial reporting by buying category rather than display category. A “Galaxy V-Neck Tee” might display under “Men’s > Casual > T-Shirts” but report under “Apparel > Knit Tops > V-Necks” for buying analysis.
• Merchandise hierarchy assignment is optional. Products without a merchandise hierarchy assignment are grouped under “Unclassified” in financial reports.

Custom Dimensions

Tenant-defined reporting dimensions for analysis needs beyond brand and merchandise hierarchy.

Product-Dimension Junction Table:

Example Custom Dimensions:

3.5.7 Reports: Seasons & Dimensions

3.6 Multi-Channel Management

Scope: Managing product visibility, inventory allocation, and pricing across multiple sales channels (In-Store POS, Online/Shopify, Wholesale). Each product can be configured independently per channel, enabling retailers to control where products appear, how much stock each channel can sell, and at what price.

Cross-Reference: See Module 4, Section 4.2 for inventory allocation across channels.

3.6.1 Channel Definition

The system ships with three built-in channels. Tenants can define additional custom channels to match their sales operations.

Channel Data Model

3.6.2 Channel Visibility Controls

Each product is independently toggled for visibility on each channel. Visibility can be immediate or scheduled with date windows.

Channel Visibility Data Model

Business Rules:

• A product must be visible on at least one channel to remain in ACTIVE lifecycle status. If a product is removed from all channels, the system warns: “Product will be hidden from all sales channels. Consider setting to DISCONTINUED.”
• Scheduled visibility windows are evaluated in real time. A product with available_from in the future does not appear on the channel until that timestamp.
• Bulk operations: staff can select multiple products and toggle channel visibility in batch via the catalog management UI.

Channel Visibility Sequence

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as Catalog UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Single Product Channel Toggle

    U->>UI: Open Product Detail
    UI->>API: GET /products/{id}/channels
    API-->>UI: Return Channel Visibility Settings

    U->>UI: Toggle "Online" Channel ON
    U->>UI: Set available_from "2026-03-01"
    U->>UI: Click "Save"

    UI->>API: PATCH /products/{id}/channels
    API->>DB: Upsert Channel Visibility Record
    API-->>UI: Channel Updated

    Note over U, DB: Bulk Channel Toggle

    U->>UI: Select 25 Products (Checkbox)
    U->>UI: Click "Bulk Actions" -> "Channel Visibility"
    UI-->>U: Show Channel Toggle Panel
    U->>UI: Toggle "Wholesale" ON for All Selected
    U->>UI: Click "Apply"

    UI->>API: POST /products/bulk-channel-update
    Note right of API: {product_ids: [...], channel_id: "...", is_visible: true}
    API->>DB: Upsert 25 Channel Visibility Records
    API-->>UI: "25 products updated"

3.6.3 Channel Inventory Allocation

Each tenant selects one of two inventory allocation modes. The mode applies globally per tenant.

Dedicated Allocation Data Model

Business Rules:

• Sum of allocated_qty across all channels at a location cannot exceed total physical inventory at that location.
• When one channel sells out (available_qty = 0), the system flags the product as “Channel Stockout” in the dashboard. Staff can manually release allocation from another channel to replenish.
• Auto-reallocation is not automatic by default. Staff must approve reallocation to prevent unintended stock shifts.
• In Shared Pool mode, the dedicated allocation table is not used. All channels reference the location’s total qty_on_hand.

3.6.4 Channel Pricing

Each product can carry a different price per channel. Channel pricing ties into the Price Tier hierarchy defined in the pricing engine.

Channel Pricing Data Model

Business Rules:

• If no channel_price is set for a product-channel combination, the system falls through to the product’s global base_price.
• Channel pricing is evaluated BEFORE customer price tiers. The resolution order is: Channel Price -> Base Price -> Price Tier Override.
• Wholesale channel pricing typically represents a cost-plus markup and may be lower than in-store pricing.

3.6.5 Reports: Multi-Channel

3.7 Shopify Integration

MOVED TO MODULE 6: This section has been consolidated into Module 6: Integrations & External Systems, Section 6.3 (Shopify Integration). The full Shopify integration specification – including sync modes, field-level ownership, conflict resolution, sync constraints, GraphQL API preference, @idempotent directive, Bulk Operations API, third-party POS integration rules, omnichannel/BOPIS requirements, and hardware compatibility – is now maintained in Section 6.3.

See: Module 6, Section 6.3 for the complete Shopify integration specification.

3.8 Vendor Management

Scope: Tracking supplier information, payment terms, and the many-to-many relationship between vendors and products. A single product can be sourced from multiple vendors, each with vendor-specific cost, SKU, and lead time.

Cross-Reference: See Module 4, Section 4.3 for purchase orders and Section 4.9 for vendor RMA.

Cross-Reference: See Module 5, Section 5.19 for supplier payment terms and lead time configuration.

3.8.1 Vendor Data Model

3.8.2 Vendor-Product Relationship

Vendors and products share a many-to-many relationship through the vendor_product junction table. Each link carries vendor-specific pricing, SKU mapping, and lead time overrides.

3.8.3 Vendor-Product Entity Relationship

erDiagram
    VENDOR {
        UUID id PK
        String name
        String code
        String tax_id
        String email
        String phone
        String payment_terms
        String currency
        Decimal minimum_order
        Integer default_lead_time_days
        String status
    }

    PRODUCT {
        UUID id PK
        String sku
        String name
        String product_type
        Decimal base_price
        Decimal cost
        String lifecycle_status
    }

    VENDOR_PRODUCT {
        UUID vendor_id FK
        UUID product_id FK
        String vendor_sku
        Decimal vendor_cost
        String vendor_barcode
        Boolean is_primary_vendor
        Integer lead_time_override_days
        Integer minimum_order_qty
    }

    VENDOR ||--o{ VENDOR_PRODUCT : "supplies"
    PRODUCT ||--o{ VENDOR_PRODUCT : "sourced from"

3.8.4 Reports: Vendor Management

3.9 Product Search & Discovery

Scope: Enabling fast product lookup at the POS terminal through multiple search methods: full-text search, category browsing, advanced filters, favorites, and product recommendations. Search must return results in under 200ms for responsive POS operation.

3.9.1 Full-Text Search

The POS search engine indexes the following fields for fast retrieval:

Relevance Ranking Order:

1. Exact SKU match
2. Exact barcode match (primary or alternate)
3. Name starts with search term
4. Name contains search term
5. Brand name match
6. Vendor name match
7. Tag exact match
8. Description contains search term
9. Custom attribute value match

Fuzzy Matching:

• Handles typos using Levenshtein distance (edit distance <= 2 for words >= 5 characters)
• Examples: “oxfrd” matches “Oxford”, “clasic” matches “Classic”, “niike” matches “Nike”
• Fuzzy results ranked below exact matches
• Disabled for SKU and barcode fields (exact match only)

Auto-Complete:

• Suggestions appear after 2 characters typed
• Returns top 8 suggestions combining product names, SKUs, and recent searches
• Debounced at 150ms to prevent excessive API calls
• Keyboard navigation supported (arrow keys + Enter to select)

Recent Searches:

• Last 10 searches stored per user, displayed in a dropdown when the search field is focused
• Tapping a recent search re-executes the query
• Clear individual or all recent searches

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant IDX as Search Index
    participant DB as DB

    U->>UI: Type "oxfrd" in search bar
    Note right of UI: Debounce 150ms

    UI->>API: GET /products/search?q=oxfrd&limit=20
    API->>IDX: Full-text query with fuzzy matching

    par Search Execution
        IDX->>IDX: Exact SKU/barcode check (no match)
        IDX->>IDX: Full-text name search (fuzzy: "oxfrd" → "Oxford")
        IDX->>IDX: Brand/vendor/tag search
        IDX->>IDX: Description search
    end

    IDX-->>API: Ranked results (Oxford Button-Down first)
    API->>DB: Fetch stock levels for results
    API-->>UI: Return products with price, stock, images

    UI-->>U: Display results grid (name, SKU, price, stock, image)
    U->>UI: Tap "Oxford Button-Down Shirt"
    UI->>UI: Add to cart

    par Background
        UI->>API: POST /search-history
        API->>DB: Save recent search "oxfrd" for user
    end

3.9.2 Category Browsing

Staff can browse the catalog visually through the 4-level category hierarchy defined in Section 3.4.

Visual Grid View:

• Categories displayed as image tiles (using category_image from Section 3.4.3)
• Each tile shows: category name, product count badge, category image (or placeholder icon)
• Grid layout: configurable 3x3, 4x4, or 5x5 per screen (setting per terminal)

Drill-Down Navigation:

Department → Category → Subcategory → Products

Example:
Men's Apparel [42 items] →
  Tops [28 items] →
    T-Shirts [15 items] →
      [Product Grid: Classic Tee, Graphic Tee, V-Neck, ...]

Breadcrumb Navigation:

Always visible at the top of the browse screen:

Home > Men's Apparel > Tops > T-Shirts

Tapping any breadcrumb segment navigates back to that level.

Sort Within Category:

3.9.3 Advanced Filters

Filters are combinable using AND logic. Each active filter narrows the result set.

Saved Filters:

• Staff can save current filter combination as a named view
• Maximum 20 saved filters per user, 50 shared filters per tenant
• Shared filters visible to all staff in the tenant

3.9.4 Quick-Add & Favorites

Favorites:

• Each staff member can pin up to 50 products
• One-tap add to cart from favorites panel
• Drag-drop reordering of favorites
• Favorites persist across terminals (tied to user, not device)

Quick-Add Buttons:

• Configurable grid of up to 20 high-velocity items on POS home screen
• Each button displays: product image thumbnail, product name (truncated), price
• Configurable per location (e.g., store-specific quick items)
• Manager or Admin role required to configure quick-add buttons

Recent Products:

• Last 20 products viewed or added to cart, displayed in a “Recents” side panel
• Per-user, per-session (resets on logout)
• One-tap to add to cart
• Stored in local state (not persisted to database)

Department Quick-Keys:

• Configurable shortcut buttons for top-level categories (departments)
• Up to 8 department quick-keys displayed in a horizontal bar above the search field
• Tapping a quick-key navigates directly to that department’s category browse view
• Configurable per location by Manager or Admin

3.9.5 Product Substitutions & Recommendations

Out-of-Stock Alternatives:

When a scanned or searched product has zero available stock at the current location, the system presents alternatives in priority order:

Cross-Sell / Upsell Configuration:

Manual Relationships:

• Staff defines “related products” per product via the admin product detail page
• Relationship types: SUBSTITUTE (alternative), CROSS_SELL (complementary), UPSELL (upgrade), ACCESSORY (add-on)
• Maximum 10 manual relationships per product per type

Auto-Generated Relationships:

• Background job analyzes completed order history (rolling 90 days)
• Identifies products frequently purchased together (co-purchase frequency >= 3 occurrences)
• Generates CROSS_SELL relationships with confidence score based on frequency
• Auto-generated relationships are refreshed weekly
• Staff can promote an auto-generated relationship to manual (persists beyond refresh)

POS Display:

• “Customers Also Bought” panel shown during checkout when cart contains products with cross-sell relationships
• Maximum 4 suggestions displayed, ordered by priority then confidence score
• Staff can dismiss suggestions or tap to add to cart

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    U->>UI: Scan barcode for "Classic Tee"
    UI->>API: POST /products/barcode-lookup
    API->>DB: Fetch product + inventory
    DB-->>API: Product found, qty_available = 0

    API-->>UI: Product data (OUT OF STOCK)
    UI-->>U: "Classic Tee is out of stock at this location"

    par Fetch Alternatives
        API->>DB: Same product at other locations
        DB-->>API: Store B: 12 units, Store C: 5 units
    and
        API->>DB: Similar products (same category, ±20% price)
        DB-->>API: "V-Neck Tee" $27.99 (8 in stock), "Crew Neck" $31.99 (15 in stock)
    and
        API->>DB: Same brand alternatives
        DB-->>API: "Classic Tee V2" $29.99 (20 in stock)
    end

    UI-->>U: Display alternatives panel
    Note right of UI: 1. Same item at Store B (12) / Store C (5)
    Note right of UI: 2. V-Neck Tee $27.99 (8) / Crew Neck $31.99 (15)
    Note right of UI: 3. Classic Tee V2 $29.99 (20)

    alt Staff selects alternative
        U->>UI: Tap "V-Neck Tee"
        UI->>UI: Add to cart
    else Staff initiates transfer
        U->>UI: Tap "Request from Store B"
        UI->>API: POST /transfers/request
    end

3.9.6 Reports: Search & Discovery

3.10 Label & Price Tag Printing

Scope: Generating and printing barcode labels, shelf price tags, and clearance stickers from the catalog. Supports multiple label formats, batch printing, and integration with standard label printers (Zebra, DYMO, Brother).

3.10.1 Label Types

3.10.2 Label Templates

Layout Definition JSON Structure:

{
  "fields": [
    { "name": "product_name", "x": 2, "y": 2, "font_size": 10, "max_width": 46, "bold": true },
    { "name": "barcode", "x": 2, "y": 10, "height": 8, "format": "CODE128" },
    { "name": "sku", "x": 2, "y": 20, "font_size": 7, "bold": false },
    { "name": "price", "x": 35, "y": 2, "font_size": 12, "bold": true, "prefix": "$" }
  ],
  "margins": { "top": 1, "right": 1, "bottom": 1, "left": 1 }
}

Supported Printers:

3.10.3 Batch Printing Workflow

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI / Admin
    participant API as Backend
    participant PS as Print Service
    participant PR as Label Printer

    Note over U, PR: Batch Label Printing Workflow

    U->>UI: Select products (search, category, or bulk select)
    UI-->>U: Display selected products (count, names)

    U->>UI: Click "Print Labels"
    UI-->>U: Show template selection dialog

    U->>UI: Choose label template (e.g., "Standard Barcode 50x25")
    UI-->>U: Show quantity options

    U->>UI: Set quantity per product
    Note right of UI: Default: 1 per product
    Note right of UI: Option: "Match stock qty" auto-fills

    U->>UI: Click "Preview"
    UI->>API: POST /labels/preview
    API-->>UI: Return rendered label previews (first 5)
    UI-->>U: Display label preview grid

    U->>UI: Select target printer from configured list
    U->>UI: Click "Print"
    UI->>API: POST /labels/print

    API->>API: Generate label data for all products
    API->>PS: Send print job (template + product data)

    PS->>PS: Render labels in printer language (ZPL/DYMO/ESC)
    PS->>PR: Send to printer

    PR-->>PS: Print confirmation
    PS-->>API: Job complete (labels_printed count)
    API->>API: Log print job to print_log

    API-->>UI: "Printed 45 labels on Zebra-Stockroom"
    UI-->>U: Success confirmation

Print Job Data Model:

3.10.4 Print Triggers

Business Rules:

• Print triggers are configurable per tenant (enable/disable each trigger)
• Staff can dismiss any auto-prompt without printing
• All print events are logged regardless of trigger type
• Print triggers fire only at the location where the event occurred

3.10.5 Reports: Label Printing

3.11 Product Media

Scope: Managing product images and video content for POS display, catalog browsing, and Shopify synchronization. Each product supports multiple images with one designated primary, plus optional video links. Images are optimized for fast POS terminal rendering.

3.11.1 Image Management

Product Image Data Model:

Image Rules:

Thumbnail Generation:

On upload, the system auto-generates three thumbnail sizes:

Thumbnails are generated asynchronously via a background job. Original image is stored as-is; thumbnails are derived copies.

3.11.2 Video Support

Product Video Data Model:

Video Rules:

• URL-based video links only (no direct video file upload)
• Use cases: product demos, styling guides, assembly instructions, care guides
• Display: video tab on product detail page in admin portal
• Not displayed at POS terminal (bandwidth and performance consideration)
• Maximum 5 videos per product

3.11.3 Media Sync

Shopify Integration:

Image Optimization Pipeline:

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as Admin UI
    participant API as Backend
    participant IMG as Image Service
    participant CDN as CDN
    participant DB as DB

    U->>UI: Upload product image (drag-drop or file select)
    UI->>UI: Client-side validation (format, size < 5MB)
    UI->>API: POST /products/{id}/images (multipart upload)

    API->>IMG: Process image
    IMG->>IMG: Validate dimensions (min 256x256)
    IMG->>IMG: Auto-resize if > 4096x4096
    IMG->>IMG: Compress (quality 85%, strip EXIF metadata)
    IMG->>IMG: Convert to WebP (if not already)

    par Thumbnail Generation
        IMG->>IMG: Generate 64x64 thumbnail (sm)
        IMG->>IMG: Generate 128x128 thumbnail (md)
        IMG->>IMG: Generate 256x256 thumbnail (lg)
    end

    IMG->>CDN: Upload original + 3 thumbnails
    CDN-->>IMG: Return CDN URLs

    IMG-->>API: Return URLs (original + thumbnails)
    API->>DB: Save image record with URLs
    API-->>UI: Image uploaded successfully
    UI-->>U: Display new image in gallery

CDN Delivery:

• All images served via CDN URL for fast display across all locations
• CDN cache TTL: 30 days (images are immutable; new upload = new URL)
• Fallback: if CDN is unavailable, images served from origin storage

3.12 Product Notes & Attachments

Scope: Supporting structured internal notes and file attachments on products for buying decisions, vendor communication, quality tracking, and staff communication. Notes and attachments are visible only in the admin portal, not at the POS terminal.

3.12.1 Structured Note Types

Product Note Data Model:

Business Rules:

• Only the note creator or an Admin can edit or delete a note
• Pinned notes always sort to the top, regardless of date
• Maximum 1 pinned note per note type per product (pinning a new note of the same type unpins the previous)
• Notes are never hard-deleted; they are soft-deleted with a deleted_at timestamp for audit

3.12.2 File Attachments

Attachment Rules:

3.12.3 Display

Admin Product Detail Page – Notes Tab:

┌─────────────────────────────────────────────────────────┐
│  Notes (7)                          [+ Add Note ▼]      │
│  ─────────────────────────────────────────────────────── │
│  Filter: [All Types ▼]  [Show Pinned Only ☐]            │
│                                                          │
│  📌 BUYING NOTE — Jan 15, 2026 by Sarah (Buyer)         │
│  ┌──────────────────────────────────────────────────┐    │
│  │ Reorder 200 units for Spring. Vendor confirmed   │    │
│  │ lead time of 21 days. Negotiate 5% volume disc.  │    │
│  └──────────────────────────────────────────────────┘    │
│                                                          │
│  QUALITY NOTE — Jan 12, 2026 by Mike (Manager)          │
│  ┌──────────────────────────────────────────────────┐    │
│  │ Customer complaint: stitching loose on collar.    │    │
│  │ Inspected 5 units from last batch - 2 defective. │    │
│  └──────────────────────────────────────────────────┘    │
│                                                          │
│  STAFF NOTE — Jan 10, 2026 by Jane (Staff)              │
│  ┌──────────────────────────────────────────────────┐    │
│  │ This item sells best when displayed near the      │    │
│  │ front entrance. Move to endcap for weekends.      │    │
│  └──────────────────────────────────────────────────┘    │
│                                                          │
│  ─────────────────────────────────────────────────────── │
│  Attachments (3)                    [+ Upload File]      │
│                                                          │
│  📎 Nike-SS26-Spec-Sheet.pdf (1.2 MB)    [Download]     │
│  📎 Care-Instructions-EN.pdf (340 KB)     [Download]     │
│  📎 Vendor-Quote-Jan2026.xlsx (85 KB)     [Download]     │
└─────────────────────────────────────────────────────────┘

Product List View:

• Note count badge displayed on product rows (e.g., “3 notes”) as a small indicator
• Badge color: grey for staff notes only, yellow if any buying/vendor notes exist, red if any quality notes exist

3.13 Catalog Permissions & Approvals

Scope: Controlling access to catalog features through role-based permissions, field-level edit restrictions, and approval workflows for sensitive changes (pricing, cost, lifecycle transitions). All permission-governed actions are logged to the audit trail defined in Section 3.13.4.

3.13.1 Role-Based Catalog Access

Role Assignment:

• Roles are assigned per user per tenant (a user can have different roles in different tenants)
• A user can hold exactly one catalog role per tenant
• Role assignment requires Admin permission
• Role changes take effect on the user’s next login (or session refresh)

3.13.2 Field-Level Permissions

Configurable per role per tenant. The tenant Admin can customize which fields each role can edit versus view as read-only.

Default Field-Level Restrictions:

Field Permission Data Model:

Constraint: Unique on (role_id, field_name, tenant_id).

3.13.3 Approval Workflows

Configurable approval rules determine which catalog changes require manager or admin sign-off before taking effect.

Default Approval Rules:

Approval Rule Data Model:

Approval Request Data Model:

Approval Workflow:

sequenceDiagram
    autonumber
    participant U as Staff / Buyer
    participant UI as Admin UI
    participant API as Backend
    participant DB as DB
    participant N as Notification Service
    participant A as Approver (Manager/Admin)

    U->>UI: Edit product field (e.g., reduce price by 25%)
    UI->>API: PUT /products/{id}
    API->>API: Check approval rules for this change

    alt Approval Required
        API->>DB: Create approval_request (status: PENDING)
        API->>DB: Store proposed change (do NOT apply yet)
        API->>N: Send notification to eligible approvers
        N-->>A: "Price change requires your approval"
        API-->>UI: "Change submitted for approval"
        UI-->>U: "Pending manager approval. Price unchanged until approved."

        Note over A, DB: Approver Reviews

        A->>UI: Open "Pending Approvals" queue
        UI->>API: GET /approvals?status=PENDING
        API-->>UI: List of pending approval requests

        A->>UI: Review change details
        Note right of UI: Shows: product, field, old value, new value, who requested, reason

        alt Approve
            A->>UI: Click "Approve"
            UI->>API: POST /approvals/{id}/approve
            API->>DB: Update approval_request (status: APPROVED, approved_by, resolved_at)
            API->>DB: Apply the change to the product
            API->>DB: Log to audit_trail (with approval_id reference)
            API->>N: Notify requester "Your change was approved"
            API-->>UI: "Change approved and applied"
        else Reject
            A->>UI: Click "Reject" + enter reason
            UI->>API: POST /approvals/{id}/reject
            API->>DB: Update approval_request (status: REJECTED, rejection_reason, resolved_at)
            API->>N: Notify requester "Your change was rejected: [reason]"
            API-->>UI: "Change rejected"
        end

    else No Approval Required
        API->>DB: Apply change directly
        API->>DB: Log to audit_trail
        API-->>UI: "Change saved"
    end

Business Rules:

• Pending approval requests expire after 7 days (configurable per tenant) and auto-set to EXPIRED
• A requester cannot approve their own change request
• If the product is edited again while a pending approval exists for the same field, the older request is auto-cancelled
• Admin can bypass approval requirements (self-approving)
• Approval rules can be enabled or disabled per tenant without deleting the rule definition

3.13.4 Audit Trail

Every field-level change to any catalog product is logged to an immutable audit trail.

Audit Trail Data Model:

Audit Trail Rules:

Audit Trail View (Admin Product Detail Page):

┌─────────────────────────────────────────────────────────────────┐
│  Change History (42 changes)         [Export CSV] [Filter ▼]    │
│  ───────────────────────────────────────────────────────────── │
│                                                                  │
│  ⚠ Jan 20, 2026 14:32 — Mike (Manager) — APPROVAL              │
│    base_price: $29.99 → $22.99 (approved by Sarah)             │
│                                                                  │
│  Jan 18, 2026 09:15 — Jane (Buyer) — MANUAL                    │
│    tags: ["summer"] → ["summer", "clearance"]                   │
│                                                                  │
│  ⚠ Jan 15, 2026 11:00 — SYSTEM — SYNC                          │
│    lifecycle_status: ACTIVE → DISCONTINUED                      │
│                                                                  │
│  Jan 10, 2026 16:45 — Import Bot — IMPORT                      │
│    cost: $12.50 → $13.00                                        │
│                                                                  │
│  [Load More...]                                                  │
└─────────────────────────────────────────────────────────────────┘

3.13.5 Reports: Permissions & Audit

3.14 Product Performance Analytics

Scope: Providing real-time product performance metrics embedded on the product detail page and a dedicated catalog analytics dashboard. These metrics drive inventory optimization, markdown decisions, and merchandising strategy.

3.14.1 Embedded Product Metrics

Displayed on each product’s detail page in the admin portal:

Metric Display Layout (Admin Product Detail):

┌─────────────────────────────────────────────────────────────┐
│  Performance Metrics               Period: [Last 30 Days ▼] │
│  ───────────────────────────────────────────────────────── │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Sell-Thru │  │ Days of  │  │  Margin  │  │ Velocity │   │
│  │  72% ▲    │  │ Supply   │  │  54.2%   │  │ 8.3/wk   │   │
│  │  (Green)  │  │  18 days │  │  (Green) │  │ ~~~~~~~~ │   │
│  │           │  │ (Yellow) │  │          │  │ sparkline│   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Aging   │  │   ABC    │  │  Turns   │  │ Revenue  │   │
│  │  45 days │  │   [A]    │  │ 6.2/yr   │  │ $12,450  │   │
│  │  (Green) │  │  (Green) │  │  (Green) │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘

3.14.2 ABC Classification

Calculation Method: Revenue-based Pareto analysis, calculated monthly via background job.

ABC Classification Data Model:

Business Rules:

• Recalculated on the 1st of each month using the trailing 12-month sales period
• Products with fewer than 60 days since published_at are classified as NEW
• Classification stored on the product record as abc_classification field for fast query
• Classification is tenant-scoped (each tenant’s products are ranked independently)
• ABC drives: reorder priority (A items reordered first), count scheduling (A items counted more frequently), display prominence in analytics

ABC Classification Impact on Operations:

3.14.3 Catalog Analytics Dashboard

A dedicated dashboard accessible from the admin portal navigation.

Summary Cards (Top Row):

Charts:

Dashboard Filters:

3.14.4 Reports: Analytics

3.15 Catalog User Stories & Acceptance Criteria (EXPANDED)

Note: Epics 3.A through 3.E and their existing Gherkin scenarios remain unchanged. The following adds new Epics 3.F through 3.S and new Gherkin acceptance criteria for key features.

Epic 3.F: Pricing Engine

• Story 3.F.1 (Price Hierarchy): System resolves product price using cascading hierarchy: Manual Override > Promotion > Price Book > Channel Price > Global Default. The customer always receives the best applicable price.
• Story 3.F.2 (Price Books): Admin can create named price books restricted by customer group, channel, and date range. Price book entries override base price for matched products.
• Story 3.F.3 (Promotions): Staff can create four promotion types: Basic (% or $ off), Tiered (volume pricing), BOGO (cross-item), and Scheduled (time-based). Promotions follow a Draft > Scheduled > Active > Expired lifecycle.
• Story 3.F.4 (Markdown Workflow): Price reductions follow a formal workflow: request > manager approval > scheduled price change. All price changes logged with who/when/why for accountability.
• Story 3.F.5 (Conflict Resolution): When multiple pricing rules match, system applies best-price-for-customer logic. Exclusive promotions override all other pricing. Stackable promotions combine up to configurable max discount.

Epic 3.G: Multi-Channel

• Story 3.G.1 (Channel Visibility): Staff can toggle product visibility per channel (In-Store, Online, Wholesale). Products must be visible on at least one channel to be Active.
• Story 3.G.2 (Channel Inventory): Admin can choose shared pool (default) or dedicated allocation per channel. Dedicated mode reserves specific quantities per channel.
• Story 3.G.3 (Channel Pricing): Products can have different prices per channel. Channel price overrides base price per the price hierarchy.

Epic 3.H: Shopify Integration

• Story 3.H.1 (POS-Master Sync): Product changes in POS automatically push to Shopify for POS-owned fields. Shopify-only fields (SEO, metafields) are preserved.
• Story 3.H.2 (Bidirectional Mode): Admin can enable bidirectional sync per tenant. POS-priority conflict resolution applies to shared fields.
• Story 3.H.3 (Sync Monitoring): Admin dashboard shows sync status, pending changes, failed syncs, and conflict log.

Epic 3.I: Search & Discovery

• Story 3.I.1 (Full-Text Search): POS search supports name, SKU, barcode, tags, vendor, brand, and custom attributes with fuzzy matching and auto-complete. Results return in under 200ms.
• Story 3.I.2 (Favorites & Quick-Add): Staff can pin up to 50 favorite products for one-tap access and configure up to 20 quick-add buttons on the POS home screen.
• Story 3.I.3 (Substitutions): When a product is out of stock, system suggests alternatives: same product at other locations, similar products in same category, and related products from cross-sell configuration.

Epic 3.J: Labels & Printing

• Story 3.J.1 (Label Printing): Staff can select products and print barcode labels, shelf tags, or clearance stickers using configurable templates. Supports Zebra, DYMO, Brother, and receipt printer output.
• Story 3.J.2 (Auto-Print Triggers): System prompts label printing on PO receive, transfer receive, price change, and markdown events. Triggers are configurable per tenant.

Epic 3.K: Media Management

• Story 3.K.1 (Product Images): Products support one primary image plus a gallery of up to 20 images. Per-variant images are supported. Drag-drop reorder. Auto-generated thumbnails (64px, 128px, 256px).
• Story 3.K.2 (Video): Products can link to video URLs (YouTube, Vimeo, self-hosted) for demos and styling guides. Videos displayed on admin product detail page only (not POS terminal).

Epic 3.L: Permissions & Approvals

• Story 3.L.1 (Role-Based Access): Four catalog roles (Admin, Buyer, Manager, Staff) with configurable field-level permissions. Staff is view-only. Admin has full access.
• Story 3.L.2 (Approval Workflows): Price decreases > 10% require Manager approval. Price decreases > 30% require Admin approval. Cost changes require Buyer/Admin approval. Rules are configurable per tenant.
• Story 3.L.3 (Audit Trail): Every field change logged with who, when, old value, new value, and change source. Searchable per product. Minimum 7-year retention. Exportable as CSV.

Epic 3.M: Analytics

• Story 3.M.1 (Product Metrics): Product detail page shows sell-through rate, days of supply, gross margin, sales velocity (sparkline), inventory aging, ABC classification, stock turn rate, and period revenue.
• Story 3.M.2 (ABC Classification): Monthly Pareto analysis classifies products as A (top 20% by revenue), B (next 30%), C (bottom 50%). New products exempt until 60 days of data.
• Story 3.M.3 (Analytics Dashboard): Dedicated catalog dashboard with summary cards, top/bottom performers, ABC distribution chart, aging histogram, category margin comparison, and seasonal sell-through trends.

Catalog Acceptance Criteria: New Gherkin Scenarios

Feature: Price Hierarchy Resolution

Feature: Price Hierarchy Resolution
  As a POS system
  I need to resolve the correct price using the pricing hierarchy
  So that customers always receive the best applicable price

  Background:
    Given product "Classic Tee" has base_price "$29.99"
    And product "Classic Tee" is in "ACTIVE" lifecycle status

  Scenario: Base price used when no overrides exist
    Given no channel price, price book, or promotion applies to "Classic Tee"
    When any customer adds "Classic Tee" to cart
    Then the price should be "$29.99"

  Scenario: Channel price overrides base price
    Given channel "WHOLESALE" has price "$19.99" for "Classic Tee"
    When a wholesale customer adds "Classic Tee" to cart
    Then the price should be "$19.99"

  Scenario: Price book overrides channel price
    Given price book "Employee Discount" is active for customer group "Employees"
    And "Employee Discount" has "Classic Tee" at "$14.99"
    And channel "IN_STORE" has price "$29.99" for "Classic Tee"
    When employee "John" adds "Classic Tee" to cart
    Then the price should be "$14.99"

  Scenario: Promotion overrides price book when better for customer
    Given promotion "Summer Sale" is active with 30% off "Classic Tee"
    And price book "Employee Discount" has "Classic Tee" at "$14.99"
    When employee "John" adds "Classic Tee" to cart
    Then the price should be "$14.99"
    And the system should apply best-price-for-customer logic
    And the applied pricing source should be "PRICE_BOOK"

  Scenario: Promotion wins when it gives the lower price
    Given promotion "Flash Sale" is active with 60% off "Classic Tee"
    And price book "Employee Discount" has "Classic Tee" at "$14.99"
    When employee "John" adds "Classic Tee" to cart
    Then the price should be "$12.00"
    And the applied pricing source should be "PROMOTION"

  Scenario: Manual override beats all other pricing
    Given promotion "Summer Sale" is active with 30% off "Classic Tee"
    And price book "Employee Discount" has "Classic Tee" at "$14.99"
    When manager "Mike" applies manual override price "$10.00" to "Classic Tee"
    Then the price should be "$10.00"
    And the applied pricing source should be "MANUAL_OVERRIDE"
    And the override should be logged to the audit trail

  Scenario: Exclusive promotion overrides stackable promotions
    Given exclusive promotion "VIP Members Only" is active with 40% off "Classic Tee"
    And stackable promotion "Summer Sale" is active with 10% off "Classic Tee"
    When a VIP customer adds "Classic Tee" to cart
    Then only the exclusive promotion should apply
    And the price should be "$17.99"

  Scenario: Stackable promotions combine up to max discount
    Given stackable promotion "Summer Sale" is active with 10% off "Classic Tee"
    And stackable promotion "Newsletter Signup" is active with 5% off "Classic Tee"
    And tenant max discount is configured at 50%
    When a qualifying customer adds "Classic Tee" to cart
    Then both promotions should apply
    And the combined discount should be 15%
    And the price should be "$25.49"

Feature: Markdown Workflow with Approval

Feature: Markdown Workflow with Approval
  As a catalog manager
  I need price reductions to follow an approval workflow
  So that markdowns are controlled and accountable

  Background:
    Given product "Slow Seller" has base_price "$49.99"
    And approval rule exists: price decrease > 10% requires Manager approval
    And approval rule exists: price decrease > 30% requires Admin approval

  Scenario: Small price decrease requires no approval
    When staff "Jane" changes price to "$47.99" (4% decrease)
    Then the price should change immediately to "$47.99"
    And the change should be logged to the audit trail
    And no approval request should be created

  Scenario: Moderate price decrease requires manager approval
    When staff "Jane" requests markdown to "$39.99" (20% decrease) with reason "Low sell-through"
    Then an approval request should be created with status "PENDING"
    And the product price should remain "$49.99" until approved
    And manager "Mike" should receive a notification

  Scenario: Manager approves the markdown
    Given a pending approval exists for "Slow Seller" price change to "$39.99"
    When manager "Mike" approves the markdown
    Then the product price should change to "$39.99"
    And the approval status should be "APPROVED"
    And the audit log should record the change with requester "Jane", approver "Mike", and reason "Low sell-through"
    And staff "Jane" should receive a notification "Your markdown was approved"

  Scenario: Manager rejects the markdown
    Given a pending approval exists for "Slow Seller" price change to "$39.99"
    When manager "Mike" rejects the markdown with reason "Wait for end-of-season clearance"
    Then the product price should remain "$49.99"
    And the approval status should be "REJECTED"
    And staff "Jane" should receive a notification with the rejection reason

  Scenario: Large price decrease escalates to admin
    When staff "Jane" requests markdown to "$29.99" (40% decrease) with reason "Clearance"
    Then an approval request should be created requiring Admin approval
    And manager approval should NOT be sufficient

  Scenario: Approval request expires after 7 days
    Given a pending approval was created 8 days ago for "Slow Seller"
    When the expiration job runs
    Then the approval status should change to "EXPIRED"
    And the product price should remain unchanged
    And the requester should be notified of expiration

  Scenario: Requester cannot approve their own change
    When staff "Jane" requests markdown to "$39.99"
    And "Jane" also has Manager role
    Then "Jane" should not be able to approve her own request
    And the system should show "Cannot approve your own change request"

Feature: POS-Shopify Catalog Sync

Feature: POS-Shopify Catalog Sync
  As a multi-channel retailer
  I need product changes to sync between POS and Shopify
  So that online and in-store catalogs stay consistent

  Background:
    Given product "Classic Tee" exists in POS with SKU "BLK-TEE-001"
    And product "Classic Tee" is synced with Shopify product ID "shop_12345"

  Scenario: POS price change pushes to Shopify in POS-Master mode
    Given sync mode is "POS-Master"
    When staff changes price from "$29.99" to "$24.99" in POS
    Then the price should update in Shopify within the sync interval
    And Shopify SEO title should remain unchanged
    And Shopify metafields should remain unchanged
    And sync log should record: field "price", direction "POS_TO_SHOPIFY", status "SUCCESS"

  Scenario: POS-owned fields are protected from Shopify overwrite
    Given sync mode is "POS-Master"
    When someone edits the price to "$27.99" directly in Shopify
    Then the next sync cycle should overwrite Shopify price back to "$24.99"
    And a conflict entry should be logged with source "SHOPIFY", rejected value "$27.99"

  Scenario: Shopify description change syncs in bidirectional mode
    Given sync mode is "Bidirectional with POS Priority"
    And "long_description" is configured with sync direction "Configurable"
    And "long_description" is set to "Shopify-to-POS" direction
    When an SEO agency updates the description in Shopify
    Then the new description should sync to POS on the next cycle
    And POS-owned fields (price, SKU, variants) should not be affected
    And sync log should record: field "long_description", direction "SHOPIFY_TO_POS", status "SUCCESS"

  Scenario: Conflict resolution when both sides change the same field
    Given sync mode is "Bidirectional with POS Priority"
    And "base_price" is a POS-priority field
    When POS changes price to "$24.99" between sync cycles
    And Shopify changes price to "$27.99" between the same sync cycles
    Then the POS price "$24.99" should win
    And Shopify should be updated to "$24.99"
    And a conflict audit entry should be created
    And the conflict log should show: POS value "$24.99" (applied), Shopify value "$27.99" (rejected)

  Scenario: New product publish creates Shopify listing
    Given product "New Arrival Shirt" is in "DRAFT" status in POS
    And the product has a primary image
    When staff publishes the product (Draft to Active)
    And channel "Online" is enabled for this product
    Then a new Shopify product should be created
    And the primary image should be pushed to Shopify
    And Shopify product status should be set to "active"
    And the Shopify product ID should be stored in the sync mapping table

  Scenario: Sync failure is logged and retried
    Given sync mode is "POS-Master"
    When staff changes price in POS
    And the Shopify API returns a 500 error
    Then the sync should be marked as "FAILED" in the sync log
    And the change should be queued for retry
    And after 3 failed retries, the sync should be flagged for manual review
    And the admin sync dashboard should show the failure

Feature: Label Printing

Feature: Label Printing
  As a retail staff member
  I need to print barcode labels and price tags
  So that products are properly tagged for sale

  Scenario: Print barcode labels for received PO items
    Given PO "PO-2026-00042" has just been received with 48 units of "Air Max 90"
    When the receive is confirmed
    Then the system should prompt "Print labels for 48 received items?"
    When staff clicks "Print Labels"
    And selects template "Standard Barcode 50x25"
    And sets quantity to 48
    And selects printer "Zebra-Stockroom"
    And clicks "Print"
    Then 48 labels should be sent to "Zebra-Stockroom"
    And the print log should record the job

  Scenario: Auto-prompt on price change
    Given product "Classic Tee" has a printed shelf tag at "$29.99"
    When manager changes price to "$24.99"
    Then the system should prompt "Price changed. Print new shelf tags?"
    And the "Reprint Needed" report should include "Classic Tee"

  Scenario: Batch print clearance stickers
    Given 12 products have been marked down for clearance
    When staff selects all 12 products from the clearance collection
    And clicks "Print Labels"
    And selects template "Clearance Sticker 40x30"
    Then each label should show markdown price, original price (strikethrough), discount %, and "CLEARANCE" badge
    And 12 labels should be printed

  Scenario: Print labels on receipt printer fallback
    Given no dedicated label printer is configured at "Store C"
    When staff attempts to print labels
    Then the system should offer the receipt printer as fallback
    And labels should be formatted for 80mm receipt paper width

Feature: Product Search at POS

Feature: Product Search at POS
  As a POS operator
  I need to find products quickly using multiple search methods
  So that checkout is fast and efficient

  Scenario: Fuzzy search handles typos
    Given product "Oxford Button-Down Shirt" exists
    When staff types "oxfrd" in the search bar
    Then "Oxford Button-Down Shirt" should appear in search results
    And results should return within 200ms

  Scenario: SKU exact match ranks highest
    Given product "Classic Tee" has SKU "BLK-TEE-001"
    And product "Black Tee Dress" has name containing "Tee"
    When staff searches "BLK-TEE-001"
    Then "Classic Tee" should be the first result (exact SKU match)

  Scenario: Auto-complete shows suggestions after 2 characters
    When staff types "Cl" in the search bar
    Then auto-complete should show suggestions including "Classic Tee", "Classic Oxford", "Clearance Items"
    And suggestions should appear within 150ms

  Scenario: Out-of-stock product shows substitution suggestions
    Given product "Classic Tee" has 0 units available at current location
    And "Store B" has 12 units of "Classic Tee"
    And "V-Neck Tee" is in the same category at "$27.99"
    When staff searches and selects "Classic Tee"
    Then the system should show "Out of stock at this location"
    And suggest: "Available at Store B (12 units)"
    And suggest: "Similar: V-Neck Tee $27.99 (8 in stock)"

  Scenario: Quick-add button adds product to cart in one tap
    Given "Classic Tee" is configured as quick-add button at position 1
    When staff taps the quick-add button
    Then "Classic Tee" should be added to cart with qty 1
    And no search or product detail view should be required

  Scenario: Saved filter retrieves matching products
    Given staff saved a filter named "Nike Low Stock" with brand "Nike" and stock status "Low Stock"
    When staff selects "Nike Low Stock" from saved filters
    Then only Nike products with stock below low_stock_threshold should be displayed

Feature: Catalog Permissions

Feature: Catalog Role-Based Permissions
  As a tenant admin
  I need to control who can edit catalog fields
  So that sensitive data is protected from unauthorized changes

  Scenario: Staff role is view-only
    Given user "Tom" has role "Staff"
    When "Tom" opens product "Classic Tee" detail page
    Then all fields should be displayed as read-only
    And no "Edit" or "Save" buttons should be visible
    And "Tom" should not see "Create Product" option in navigation

  Scenario: Buyer cannot change price
    Given user "Sarah" has role "Buyer"
    When "Sarah" edits product "Classic Tee"
    Then the "base_price" field should be read-only
    And the "compare_at_price" field should be read-only
    But the "cost" field should be editable
    And the "vendor_cost" field should be editable

  Scenario: Manager cannot change cost
    Given user "Mike" has role "Manager"
    When "Mike" edits product "Classic Tee"
    Then the "cost" field should be read-only
    And the "vendor_cost" field should be read-only
    But the "base_price" field should be editable
    And the "lifecycle_status" field should be editable

  Scenario: Unauthorized action is blocked and logged
    Given user "Tom" has role "Staff"
    When "Tom" attempts to call PUT /products/{id} via API
    Then the request should return 403 Forbidden
    And a permission violation should be logged with user, role, and attempted action
    And the violation should appear in the "Permission Violations" report

Feature: Product Analytics

Feature: Product Performance Analytics
  As a merchandising manager
  I need to see product performance metrics
  So that I can make data-driven inventory and pricing decisions

  Scenario: Product detail shows embedded metrics
    Given product "Classic Tee" has been active for 90 days
    And has sold 450 units out of 600 received
    And current stock is 150 units across all locations
    And avg daily sales is 5 units
    When manager opens the product detail page
    Then sell-through rate should show "75%"
    And days of supply should show "30 days"
    And sales velocity should show "35.0/wk" with sparkline
    And ABC classification badge should be displayed

  Scenario: ABC classification calculated monthly
    Given it is the 1st of the month
    And the monthly ABC job runs
    Then the top 20% of products by trailing 12-month revenue should be classified "A"
    And the next 30% should be classified "B"
    And the bottom 50% should be classified "C"
    And products active less than 60 days should be classified "NEW"

  Scenario: Dead stock report identifies zero-sale products
    Given product "Forgotten Widget" has had zero sales for 95 days
    And product "Forgotten Widget" has 30 units on hand
    And the dead stock threshold is configured at 90 days
    When manager runs the "Dead Stock" report
    Then "Forgotten Widget" should appear with last_sale_date, stock_qty 30, and days_without_sale 95
    And recommended action should be "Review for markdown or discontinuation"

  Scenario: Overstock alert fires for excess inventory
    Given product "Winter Coat" has target days of supply of 30
    And "Store A" has 200 units and sells 1/day (200 days of supply)
    When the overstock alert report runs
    Then "Winter Coat" at "Store A" should be flagged
    And excess units should show 170 (200 - 30 days x 1/day)
    And excess value should show the cost of 170 units

4. Inventory Module

Module 4: Inventory Management (Sections 4.1 – 4.7)

4.1 Overview & Scope

The Inventory Management module governs the complete lifecycle of physical stock within the multi-tenant POS system – from procurement through vendor purchase orders, to warehouse and store receiving, through internal logistics and transfers, and into auditing via physical counts and manual adjustments. It is the operational backbone that ensures every unit of merchandise is tracked, accounted for, and available for sale at the right location at the right time.

4.1.1 Executive Summary

Retail clothing operations across five stores and one HQ warehouse demand real-time, accurate inventory visibility. A single garment may be ordered from a vendor, received at the warehouse, transferred to a retail store, reserved for a customer’s online order, counted during a cycle count, adjusted after discovery of damage, and ultimately sold at the point of sale. Each of these events must be captured, validated, and reflected in the system’s inventory balances within seconds.

Module 4 provides the business rules, workflows, data models, and integration points that make this possible. It covers seven functional domains:

1. Procurement – Creating, approving, submitting, and tracking purchase orders to vendors (Section 4.3).
2. Receiving – Inspecting and accepting inbound inventory from any source – PO shipments, transfers, customer returns, and vendor RMA replacements (Section 4.4).
3. Logistics – Inter-store and warehouse-to-store transfers are documented in Module 5 (Transfers & Logistics). Module 4 provides the inventory status and reservation primitives that Module 5 depends on.
4. Auditing – Physical stock counts and manual adjustments that reconcile system quantities with reality (Sections 4.6 and 4.7).
5. Costing – Inventory valuation via weighted average cost is applied at receiving time and propagated through the system. Cost data feeds into Module 1 (Sales) for margin calculation.
6. Integration – Inventory events trigger real-time updates to the POS terminals (Module 1), the catalog (Module 3), and the movement history audit trail.
7. Operations – Reorder management, dead stock detection, and minimum display quantity monitoring ensure proactive inventory health (Section 4.5).

4.1.2 Module Dependencies

Module 4 does not operate in isolation. It depends on and is depended upon by multiple other modules in the system.

flowchart LR
    M1["Module 1\nSales & POS"]
    M3["Module 3\nCatalog"]
    M4["Module 4\nInventory"]
    M5["Module 5\nTransfers & Logistics"]
    M6["Module 6\nReporting"]

    M3 -->|Product data, variants,\nvendor links, barcodes| M4
    M4 -->|Available qty per location,\nreservation status| M1
    M1 -->|Sale committed → decrement,\nVoid → release reservation| M4
    M4 -->|Inventory status,\nreservation holds| M5
    M5 -->|Transfer receive → increment,\nTransfer ship → decrement| M4
    M4 -->|Stock levels, velocity,\ncost data| M6
    M1 -->|Sales velocity data| M4

    style M4 fill:#2d6a4f,stroke:#1b4332,color:#fff
    style M1 fill:#264653,stroke:#1d3557,color:#fff
    style M3 fill:#264653,stroke:#1d3557,color:#fff
    style M5 fill:#264653,stroke:#1d3557,color:#fff
    style M6 fill:#264653,stroke:#1d3557,color:#fff

Upstream dependencies (Module 4 consumes):

Downstream consumers (Module 4 provides):

4.1.3 Functional Scope

The following table enumerates the functional areas covered by Module 4 and their section references.

4.1.4 Key Business Rules Summary

The following rules apply across all Module 4 operations:

• Only AVAILABLE stock can be sold at POS. Inventory in any other status (QUARANTINE, DAMAGED, RESERVED, IN_TRANSIT, PENDING_INSPECTION) is excluded from the sellable quantity displayed to cashiers.
• Only AVAILABLE stock can be transferred between locations. Transfer requests that would reduce available stock below zero are rejected.
• Every inventory change is logged. All status transitions, quantity changes, and cost updates create movement records in the audit trail (see Module 3, Section 3.16 – Movement History).
• Inventory is tracked per product, per variant, per location, per status. A single product may have quantities spread across multiple statuses at a single location simultaneously.
• All monetary values use the tenant’s configured currency. Multi-currency is not supported in v1.
• Tenant isolation is enforced at the data layer. Every inventory record carries a tenant_id foreign key. Cross-tenant queries are impossible by design.

4.1.5 Inventory Balance Equation

The system maintains the following balance equation at all times for each product-variant-location combination:

Available = On-Hand - Reserved - In-Transit - Quarantine - Damaged

Where:

The system does not store Available as a separate field. It is always computed from the status-based quantity fields. This ensures the balance equation is always consistent and cannot drift due to bugs in update logic.

4.2 Inventory Status Model

4.2.1 Inventory Status State Machine

Each unit of inventory at each location carries a status that controls whether it can be sold, transferred, or must be held for inspection. The system supports six statuses organized into a state machine with well-defined transitions.

stateDiagram-v2
    [*] --> AVAILABLE: Stock Received & Inspected
    AVAILABLE --> QUARANTINE: Quality Concern Flagged
    AVAILABLE --> RESERVED: Allocated to Order/Transfer
    AVAILABLE --> DAMAGED: Damage Identified
    QUARANTINE --> AVAILABLE: Inspection Passed
    QUARANTINE --> DAMAGED: Inspection Failed
    PENDING_INSPECTION --> AVAILABLE: Inspection Passed
    PENDING_INSPECTION --> QUARANTINE: Needs Further Review
    PENDING_INSPECTION --> DAMAGED: Inspection Failed
    DAMAGED --> WRITE_OFF: Unrepairable
    DAMAGED --> VENDOR_RMA: Return to Vendor
    IN_TRANSIT --> AVAILABLE: Transfer Received & OK
    IN_TRANSIT --> PENDING_INSPECTION: Received - Needs Inspection
    RESERVED --> AVAILABLE: Reservation Released

    note right of AVAILABLE
        Sellable at POS
        Transferable between locations
    end note

    note right of QUARANTINE
        Blocked from sale
        Blocked from transfer
        Awaiting inspection
    end note

    note right of DAMAGED
        Blocked from sale
        Can be written off or returned to vendor
    end note

    note right of RESERVED
        Allocated but not yet shipped/sold
        Decremented from available count
    end note

    note right of IN_TRANSIT
        Moving between locations
        Not available at source or destination
    end note

Status Definitions:

Business Rules:

• Only AVAILABLE stock can be sold at POS. The POS terminal displays only the AVAILABLE quantity as the sellable count.
• Only AVAILABLE stock can be transferred between locations. Transfer requests that would reduce AVAILABLE stock below zero at the source location are rejected.
• QUARANTINE and DAMAGED stock is blocked from sale and transfer. It must be inspected and resolved before it can re-enter the sellable pool.
• RESERVED stock is decremented from the available count but not yet physically moved. If the reservation is released (e.g., cart abandoned, parked transaction voided), the stock returns to AVAILABLE.
• All status changes require a reason code and are logged to the movement history audit trail.
• Status changes can only follow the transitions defined in the state machine above. Any attempt to make an invalid transition (e.g., QUARANTINE directly to RESERVED) is rejected by the API.

Inventory Status Data Model

4.2.2 Reservation Model

Reservations temporarily hold inventory for a specific purpose, preventing it from being sold or transferred to another customer or location. The reservation model is central to ensuring that the POS system does not oversell stock in a multi-terminal, multi-channel environment.

When a reservation is created, the specified quantity is moved from AVAILABLE status to RESERVED status. When the reservation is committed (sale completed, transfer shipped), the reserved quantity is decremented from inventory. When the reservation is released (cart abandoned, transaction voided), the reserved quantity returns to AVAILABLE.

Reservation Types

The system supports five distinct reservation types, each with its own lifecycle and rules:

Reservation Data Model

Reservation Lifecycle State Machine

stateDiagram-v2
    [*] --> ACTIVE: Reserve Created
    ACTIVE --> COMMITTED: Sale Paid / Transfer Shipped / Pickup Completed
    ACTIVE --> RELEASED: Void / Cancel / Manual Release
    ACTIVE --> EXPIRED: Expiry Timer Elapsed

    COMMITTED --> [*]
    RELEASED --> [*]
    EXPIRED --> [*]

    note right of ACTIVE
        Qty moved from AVAILABLE to RESERVED
        Other terminals see reduced available qty
    end note

    note right of COMMITTED
        Qty decremented from inventory
        Reservation fulfilled
    end note

    note right of RELEASED
        Qty moved from RESERVED back to AVAILABLE
        Stock returned to sellable pool
    end note

    note right of EXPIRED
        Auto-triggered by background job
        Qty returned to AVAILABLE
        Notification sent to staff
    end note

Business Rules:

• When a reservation is created, the system atomically decrements the AVAILABLE status qty and increments the RESERVED status qty for the product-variant-location combination.
• When a reservation is committed, the RESERVED qty is decremented (stock leaves inventory via sale, or moves to IN_TRANSIT for transfer).
• When a reservation is released or expired, the RESERVED qty is decremented and the AVAILABLE qty is incremented (stock returns to sellable pool).
• Reservations are checked by a background job every 5 minutes for expiry. Expired reservations are auto-released and a notification is sent to the staff member who created the reservation.
• Parked transaction override: If a staff member at another terminal attempts to sell a product that has units reserved by a parked transaction, the system shows a warning: “2 of 5 units reserved by parked sale P-0045 at Terminal 2. Proceed anyway?” If the staff member confirms, the system sells through the available stock and the parked transaction’s reserved quantity is reduced when it is recalled (the system reconciles at recall time).
• Concurrent reservation conflict: If two terminals attempt to reserve the last available unit simultaneously, the first transaction to commit the database write wins. The second terminal receives an error: “Insufficient available stock. 0 units available.” This is enforced by database-level row locking on the inventory status record.

4.2.4 Minimum Display Quantity

Retail clothing stores rely on visual merchandising – an empty rack or sparse display reduces sales. The minimum display quantity feature provides an advisory warning system that alerts store staff when the available inventory at a location drops below a configured floor display minimum.

Key Behaviors:

• Minimum display quantity is configured per product (or variant) per location. Not all products require a minimum display – the field is optional and defaults to null (no warning).
• The warning is advisory only. It does not block sales, transfers, or any other operation. It is a soft alert that appears on the store dashboard and in the inventory list view.
• When available qty at a location drops below the configured minimum display qty, the system creates a dashboard alert: “Product XYZ at Store A has 1 unit remaining (minimum display: 3). Consider replenishment.”
• The alert clears automatically when stock is replenished above the minimum display qty (via receiving, transfer, or adjustment).
• Minimum display qty is distinct from the reorder point (Section 4.5). The reorder point triggers purchase order generation. The minimum display qty triggers a store-level visual merchandising alert.

Minimum Display Quantity Data Model

Business Rules:

• Minimum display quantity alerts appear on the store dashboard under a “Low Display Stock” section.
• Alerts are generated when AVAILABLE qty < min_display_qty at a location. The check runs whenever inventory changes at the location (sale, transfer, adjustment, receive).
• Alerts include a suggested action: “Request transfer from [location with highest available qty]” with a one-click “Request Transfer” button.
• Minimum display quantity does NOT factor into the reorder point calculation (Section 4.5). They are independent systems.
• Setting a minimum display quantity of 0 is equivalent to disabling the alert for that product-location combination.

4.3 Purchase Orders & Procurement

Scope: Creating, approving, submitting, receiving, and closing purchase orders to replenish inventory from vendors. The PO workflow supports approval routing for high-value orders, partial receives, variance tracking, inspection steps, overdue alerts, and auto-generation from low-stock alerts.

4.3.1 Purchase Order State Machine

stateDiagram-v2
    [*] --> DRAFT: PO Created
    DRAFT --> PENDING_APPROVAL: Submit for Approval (above threshold)
    DRAFT --> SUBMITTED: Submit to Vendor (below threshold / auto-approved)
    PENDING_APPROVAL --> SUBMITTED: Manager Approves
    PENDING_APPROVAL --> REJECTED: Manager Rejects
    REJECTED --> DRAFT: Revise and Resubmit
    SUBMITTED --> PARTIALLY_RECEIVED: Partial Shipment Arrived
    PARTIALLY_RECEIVED --> PARTIALLY_RECEIVED: Additional Shipment
    PARTIALLY_RECEIVED --> FULLY_RECEIVED: All Items Received
    SUBMITTED --> FULLY_RECEIVED: Full Shipment Arrived
    FULLY_RECEIVED --> CLOSED: PO Closed

    DRAFT --> CANCELLED: Cancel Before Submit
    SUBMITTED --> CANCELLED: Cancel After Submit

    CANCELLED --> [*]
    CLOSED --> [*]

    note right of DRAFT
        Editable line items
        No inventory impact
        Not sent to vendor
    end note

    note right of PENDING_APPROVAL
        PO total exceeds approval threshold
        Awaiting manager/owner approval
        Line items locked for review
    end note

    note right of SUBMITTED
        Sent to vendor (email/EDI/manual)
        Awaiting shipment
        Line items locked
    end note

    note right of PARTIALLY_RECEIVED
        Some items received
        Inventory incremented for received qty
        Remaining items still expected
    end note

    note right of FULLY_RECEIVED
        All line items received
        Pending final review
        Ready to close
    end note

4.3.2 PO Approval Workflow

Purchase orders above a configurable dollar threshold require manager or owner approval before submission to the vendor. This prevents unauthorized large purchases while allowing routine restocking to flow without friction.

Approval Threshold Configuration:

Approval Rules:

• When a staff member clicks “Submit” on a PO whose total value (SUM of line_total) is at or below the po_auto_approve_threshold, the PO moves directly from DRAFT to SUBMITTED. No approval step is needed.
• When a staff member clicks “Submit” on a PO whose total value exceeds the po_auto_approve_threshold, the PO moves from DRAFT to PENDING_APPROVAL. A notification is sent to all users with the configured approval role at the PO’s destination location.
• The approver can APPROVE (moves to SUBMITTED), REJECT with a reason (moves to REJECTED), or request modifications (the PO creator is notified to revise).
• A REJECTED PO can be revised (returns to DRAFT status with editable line items) and resubmitted.
• The approval threshold is configurable per tenant in tenant settings. Different tenants may have different spending limits.
• Auto-generated draft POs from the reorder engine (Section 4.5) follow the same approval rules – they are not exempt from the threshold check.

Approval Workflow Sequence

sequenceDiagram
    autonumber
    participant S as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant NOTIF as Notification Service
    participant M as Manager/Owner

    S->>UI: Click "Submit PO"
    UI->>API: POST /purchase-orders/{id}/submit

    API->>DB: Calculate PO Total (SUM of line_total)
    API->>DB: Lookup Tenant's po_auto_approve_threshold

    alt PO Total <= Threshold (Auto-Approve)
        API->>DB: Update Status: SUBMITTED
        API->>DB: Lock Line Items
        API-->>UI: "PO Submitted to Vendor"
        Note right of API: PO proceeds to vendor submission
    else PO Total > Threshold (Requires Approval)
        API->>DB: Update Status: PENDING_APPROVAL
        API->>DB: Lock Line Items for Review
        API->>NOTIF: Send Approval Request to Manager(s)
        API-->>UI: "PO Sent for Manager Approval"
        NOTIF-->>M: "PO #PO-2026-00042 ($4,500) awaiting your approval"

        alt Manager Approves
            M->>UI: Review PO -> Click "Approve"
            UI->>API: POST /purchase-orders/{id}/approve
            API->>DB: Update Status: SUBMITTED
            API->>DB: Record approved_by, approved_at
            API->>NOTIF: Notify Creator: "PO Approved"
            NOTIF-->>S: "Your PO #PO-2026-00042 was approved"
        else Manager Rejects
            M->>UI: Review PO -> Click "Reject"
            M->>UI: Enter Rejection Reason
            UI->>API: POST /purchase-orders/{id}/reject
            API->>DB: Update Status: REJECTED
            API->>DB: Record rejection_reason
            API->>NOTIF: Notify Creator: "PO Rejected"
            NOTIF-->>S: "Your PO #PO-2026-00042 was rejected: reason"
        end
    end

4.3.3 Purchase Order Lifecycle

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant V as Vendor

    Note over U, V: Step 1: Create Purchase Order

    U->>UI: Click "New Purchase Order"
    UI->>UI: Select Vendor from List
    UI->>API: GET /vendors/{id}/products
    API-->>UI: Return Vendor's Product Catalog with Vendor Costs

    loop Add Line Items
        U->>UI: Select Product
        UI->>UI: Auto-Fill Vendor SKU, Vendor Cost
        U->>UI: Enter Quantity Ordered
        U->>UI: Set Expected Delivery Date
        UI->>UI: Calculate Line Total (qty x unit_cost)
    end

    UI->>UI: Display PO Summary (line count, total cost)
    U->>UI: Add Notes (optional)
    U->>UI: Click "Save Draft"
    UI->>API: POST /purchase-orders
    API->>DB: Create PO Record (Status: DRAFT)
    Note right of DB: Auto-generated PO Number: PO-2026-00042

    API-->>UI: PO #PO-2026-00042 Created

    Note over U, V: Step 2: Submit to Vendor

    U->>UI: Review PO -> Click "Submit"
    UI->>API: POST /purchase-orders/{id}/submit

    Note over API: Approval check runs here (see Section 4.3.2)

    alt Email Submission
        API->>V: Send PO via Email (PDF attachment)
        Note right of V: Vendor receives PO email
    else EDI Submission
        API->>V: Transmit PO via EDI
    else Manual Submission
        API-->>UI: "PO marked Submitted - send manually"
        Note right of UI: Staff prints PO and calls/faxes vendor
    end

    API->>DB: Update Status: SUBMITTED
    API->>DB: Lock Line Items (no edits)
    API-->>UI: PO Submitted Successfully

    Note over U, V: Step 3: Receive Inventory

    V-->>U: Shipment Arrives at Store/Warehouse
    U->>UI: Open PO #PO-2026-00042 -> Click "Receive"

    loop Receive Line Items
        U->>UI: Enter Qty Received per Line Item
        opt Variance Detected
            UI-->>U: "Ordered: 50, Received: 48 - Enter Variance Note"
            U->>UI: Enter Note: "2 units damaged in transit"
        end
    end

    U->>UI: Click "Confirm Receive"
    UI->>API: POST /purchase-orders/{id}/receive

    par Inventory Updates
        API->>DB: Increment Inventory (received qty per location)
        API->>DB: Update PO Line Items (qty_received)
        API->>DB: Record Variance Notes
    end

    alt All Items Received
        API->>DB: Update Status: FULLY_RECEIVED
        API-->>UI: "All items received"
    else Partial Receive
        API->>DB: Update Status: PARTIALLY_RECEIVED
        API-->>UI: "Partial receive recorded - awaiting remaining"
    end

    Note over U, DB: Step 4 (Optional): Inspect Received Goods

    opt Quality Inspection
        U->>UI: Open Received Items -> Click "Inspect"
        U->>UI: Mark Items as Passed / Failed
        Note right of UI: Failed items logged for vendor claim
        UI->>API: POST /purchase-orders/{id}/inspection
        API->>DB: Record Inspection Results
    end

    Note over U, DB: Step 5: Close PO

    U->>UI: Click "Close PO"
    UI->>API: POST /purchase-orders/{id}/close
    API->>DB: Update Status: CLOSED
    API->>DB: Finalize Cost Records
    API-->>UI: PO Closed

4.3.4 PO Header Data Model

4.3.5 PO Line Item Data Model

4.3.6 Expected Delivery Date & Overdue Alerts

Each purchase order has an expected_delivery_date field representing when the vendor is expected to deliver the goods. The system uses this date, combined with a configurable buffer period, to generate overdue alerts when a PO has not been received within the expected timeframe.

Overdue Alert Logic:

overdue_trigger_date = expected_delivery_date + overdue_alert_buffer_days

• If the current date exceeds overdue_trigger_date and the PO status is still SUBMITTED (nothing received), the system generates an overdue alert.
• If the PO status is PARTIALLY_RECEIVED and the current date exceeds overdue_trigger_date, the system generates a different alert: “PO partially received but remaining items overdue.”
• Overdue alerts appear on the purchasing dashboard and are sent as push notifications to the PO creator and the destination location’s manager.
• The overdue_alert_buffer_days defaults to 3 days but can be overridden per PO when the expected delivery date is uncertain (e.g., international shipments).
• Overdue alerts auto-clear when the PO reaches FULLY_RECEIVED or CLOSED status.

Business Rules:

• If expected_delivery_date is not set on the PO, the system falls back to the vendor’s default lead_time_days (from the vendor record) plus overdue_alert_buffer_days.
• Overdue POs appear in the Open PO Report with a visual indicator (red highlight) and are sorted to the top by default.
• The background job that checks for overdue POs runs daily at a configurable time (default: 8:00 AM local time per tenant timezone).

4.3.7 Purchase Order Features

• Auto-generate PO from low-stock alerts: When inventory drops below reorder_point at any location, the system generates a suggested draft PO with the primary vendor and recommended quantities based on sales velocity (see Section 4.5 for reorder management details).
• PO templates: Staff can save frequently ordered product sets as templates (e.g., “Weekly Nike Restock”) and generate new POs from templates with one click. Templates store vendor, product list, and default quantities but not dates or notes.
• Partial receives: Each receive operation records the quantity received per line item. Multiple receives accumulate until all items arrive. Each partial receive increments inventory at the destination location immediately.
• Variance tracking: When received quantity differs from ordered quantity, staff must enter a variance note. Variances are tracked for vendor performance reporting (see Section 4.3.8).
• Auto-increment PO number per tenant: PO numbers follow the format PO-{YEAR}-{SEQUENCE} and auto-increment per tenant. Example: PO-2026-00001, PO-2026-00002. Sequence resets annually.
• Receive to specific location: When receiving, staff selects the destination location (store or warehouse). Inventory increments at that location. The destination is pre-filled from the PO header’s destination_location_id but can be overridden during receiving.
• PO duplication: Staff can duplicate an existing PO (any status) to create a new DRAFT with the same vendor and line items. Useful for recurring orders.
• Approval threshold: POs above a configurable dollar threshold require manager approval before vendor submission (see Section 4.3.2).

4.3.8 Reports: Purchase Orders

4.4 Receiving & Inspection

Scope: A single unified receiving workflow handles all inbound inventory regardless of source type – PO shipments, inter-store transfers, customer returns, vendor RMA replacements, and non-PO receives. This section documents the open receive mode, discrepancy handling, non-PO receiving, over-shipment handling, return-to-stock processing, and scanner-primary receiving operations.

4.4.1 Receiving Source Types

4.4.2 Receiving Data Model – Header

4.4.3 Receiving Data Model – Line Items