# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Enable retail store staff to manage backstock bins directly from the mobile app with the same capabilities they have on the website, eliminating the need to walk to a computer to create, update, or act on bins.

### Problem Statement
Store employees currently must leave the sales floor and walk to a back-office computer to create new backstock bins or record actions (removing items, restocking, moving bins between locations). This disrupts workflow, delays inventory updates, and leads to:
- **Stale data**: Actions are recorded later or forgotten entirely
- **Time waste**: Multiple trips to back-office terminals during shifts
- **Friction**: Employees skip recording actions because it's inconvenient
- **Duplicate bins**: Unable to quickly check if a bin name exists, employees create duplicates

The mobile app currently has **read-only** bin viewing (search, filter, detail view) but lacks CRUD and action capabilities.

### Value Proposition
By adding bin creation, editing, and action recording to the mobile app, employees can:
- **Create bins on the spot** while in the backstock area, storage unit, or on the floor
- **Record actions instantly** as they happen (pulling items, restocking, moving bins)
- **Scan bin barcodes** to quickly look up and act on specific bins
- **Manage the full bin lifecycle** without leaving the floor—matching website parity

This reduces inventory lag time from hours/days to seconds and ensures accurate, real-time backstock data.

## User Personas

### Primary Persona: Floor Associate
- **Demographics:** Ages 18-35, entry-level retail position, comfortable with smartphones
- **Goals:** Process backstock efficiently, find items quickly for customers, keep the floor stocked
- **Pain Points:**
  - Must leave the floor to use the website for bin management
  - Forgets to record actions later; data gets stale
  - Unsure if a bin name already exists before creating
  - Can't quickly see what actions are valid for a bin

### Secondary Persona: Shift Manager
- **Demographics:** Ages 25-45, supervisory role, moderate technical proficiency
- **Goals:** Ensure backstock is organized, bins are rotated (oldest first), and inventory is accurate
- **Pain Points:**
  - Difficult to monitor bin activity across the store
  - Hidden bins are forgotten and never reactivated
  - Unable to delegate bin creation tasks to associates without website access

## User Journey Maps

### Primary User Journey: Creating a New Bin
1. **Trigger:** Associate has items to put in backstock but no available bin
2. **Action:** Opens mobile app → navigates to Backstock → taps "Create Bin"
3. **Flow:**
   - Enters bin name (or scans barcode)
   - Selects main category (searchable picker from store's categories)
   - Optionally selects sub-categories (up to 3)
   - Selects location (on-site or off-site storage)
   - Taps "Create"
4. **Outcome:** Bin is created immediately, action history shows "Created Bin"
5. **Retention:** Associate uses app for all future bin creations

### Secondary User Journey: Recording an Action on Existing Bin
1. **Trigger:** Associate removes items from a bin to restock the floor
2. **Action:** Opens bin detail screen (via search or scan)
3. **Flow:**
   - Taps "Actions" button
   - Selects action type ("Pulled for Replenishment")
   - Confirms action
4. **Outcome:** Action is recorded with timestamp and employee name
5. **Retention:** Associate records all bin actions in real-time

### Tertiary User Journey: Scanning a Bin Barcode
1. **Trigger:** Associate finds a bin with a printed barcode label
2. **Action:** Taps scan icon in bin search → scans barcode
3. **Flow:**
   - App calls lookup endpoint with bin name from barcode
   - If found: navigates directly to bin detail screen
   - If not found: prompts to create new bin with scanned name
4. **Outcome:** Quick access to bin without manual search
5. **Retention:** Associates prefer scanning over typing

## Feature Requirements

### Must Have Features

#### Feature 1: Create New Bin
- **User Story:** As a floor associate, I want to create a new backstock bin from my phone so that I can organize items immediately without going to a computer.
- **Acceptance Criteria:**
  - [ ] User can access "Create Bin" from bin search screen
  - [ ] User can enter a bin name (alphanumeric, 1-50 chars)
  - [ ] User can select main category from searchable list (sorted by bin count)
  - [ ] User can optionally select up to 3 sub-categories
  - [ ] User can select storage location from list
  - [ ] Created bin appears in search results immediately
  - [ ] Action history shows "Created Bin" entry with timestamp and user

#### Feature 2: Edit Existing Bin
- **User Story:** As a floor associate, I want to update a bin's details so that I can correct errors or update categories as inventory changes.
- **Acceptance Criteria:**
  - [ ] Edit button visible on bin detail screen
  - [ ] Can update bin name
  - [ ] Can change main category
  - [ ] Can add/remove sub-categories
  - [ ] Can change storage location
  - [ ] Can add/edit notes
  - [ ] Can reset age date (for age tracking purposes)
  - [ ] Save button disabled until changes are made

#### Feature 3: Perform Bin Actions
- **User Story:** As a floor associate, I want to record actions on a bin so that the store has accurate inventory history.
- **Acceptance Criteria:**
  - [ ] Action button visible on bin detail screen
  - [ ] Action picker shows all 6 action types:
    - Removed Everything (clears all categories)
    - Removed Some Items (requires category selection)
    - Restock from Floor
    - Moved Bin (requires destination location selection)
    - Pulled for Replenishment
  - [ ] "Created Bin" action is recorded automatically (not user-selectable)
  - [ ] Confirmation dialog shows before performing destructive actions
  - [ ] Action appears in history timeline immediately after recording
  - [ ] Move action automatically updates bin's location

#### Feature 4: Barcode Scanning for Bin Lookup
- **User Story:** As a floor associate, I want to scan a bin's barcode so that I can quickly find and act on it without typing.
- **Acceptance Criteria:**
  - [ ] Scan button visible on bin search screen
  - [ ] Camera permission requested if not granted
  - [ ] Successful scan navigates to bin detail if bin exists
  - [ ] Not-found scan prompts option to create new bin with scanned name
  - [ ] Flash toggle available for low-light scanning
  - [ ] Works with standard 1D and 2D barcodes (matching website printer format)

#### Feature 5: Delete/Hide Bin
- **User Story:** As a floor associate, I want to hide bins that are no longer in use so that the active bin list stays clean.
- **Acceptance Criteria:**
  - [ ] Hide option in bin detail action menu
  - [ ] Confirmation dialog before hiding
  - [ ] Hidden bins do not appear in normal search results
  - [ ] Delete option requires Manager+ access level
  - [ ] Deleted bins are soft-deleted (can be restored by admin)

### Should Have Features

#### Feature 6: Hidden Bins List
- **User Story:** As a shift manager, I want to see hidden bins so that I can reactivate ones that were hidden by mistake.
- **Acceptance Criteria:**
  - [ ] "Show Hidden" toggle or separate menu option in bin search
  - [ ] Hidden bins display with visual indicator (e.g., muted colors, "Hidden" badge)
  - [ ] Reactivate button on hidden bin detail
  - [ ] Reactivated bins appear in normal search immediately

#### Feature 7: Generate Descriptive Name
- **User Story:** As a floor associate, I want the app to suggest a descriptive bin name so that bins are consistently named.
- **Acceptance Criteria:**
  - [ ] "Generate Name" button on bin create/edit screen
  - [ ] Generated name includes category + sequential number (e.g., "Summer Boots #1500")
  - [ ] User can edit generated name before saving
  - [ ] Generation only available when main category is selected

### Could Have Features

#### Feature 8: Batch Actions
- **User Story:** As a shift manager, I want to perform actions on multiple bins at once so that seasonal transitions are faster.
- **Acceptance Criteria:**
  - [ ] Multi-select mode in bin search
  - [ ] Bulk action picker (Move, Hide, Removed Everything)
  - [ ] Progress indicator during batch operation
  - [ ] Summary of results after completion

#### Feature 9: Quick Action Swipe Gestures
- **User Story:** As a power user, I want to swipe on bins in the list to perform common actions without opening details.
- **Acceptance Criteria:**
  - [ ] Swipe right reveals "Edit" action
  - [ ] Swipe left reveals "Perform Action" option
  - [ ] Swipe actions match the gesture patterns used elsewhere in the app

### Won't Have (This Phase)

- **Bin auditing/inventory count** - Separate workflow, different endpoints
- **Barcode printing** - Requires integration with store printers; website-only
- **Bin value estimation AI** - Future ML feature
- **Photo attachment to bins** - Storage/bandwidth concerns; deferred
- **Real-time collaboration** - WebSocket-based updates; future enhancement

## Detailed Feature Specifications

### Feature: Perform Bin Actions

**Description:** The action system lets users record what they've done with bin contents. Each action type has specific behaviors and may require additional inputs.

**User Flow:**
1. User taps "Actions" button on bin detail screen
2. System displays action type picker (bottom sheet)
3. User selects an action type
4. If action requires input (category, location), system shows secondary picker
5. User confirms action
6. System records action and updates bin state if applicable
7. User sees success confirmation and updated action history

**Business Rules:**
- Rule 1: "Removed Everything" action automatically clears all categories from the bin
- Rule 2: "Removed Some Items" requires user to specify which category was removed
- Rule 3: "Moved Bin" requires destination location and automatically updates bin's location field
- Rule 4: Only one action can be recorded at a time (no batching within single bin)
- Rule 5: All actions are recorded with userId, timestamp, and optional category/location
- Rule 6: Action history is immutable (actions cannot be deleted)

**Edge Cases:**
- Scenario 1: User selects "Move" but cancels before selecting location → No action recorded
- Scenario 2: Network error during action submission → Retry dialog with option to save offline (deferred)
- Scenario 3: Bin is hidden while action modal is open → Action fails with "Bin not found" error
- Scenario 4: User tries action on a bin they don't have access to → Access denied error

### Feature: Create New Bin

**Description:** Bin creation captures all required fields upfront to ensure bins are properly categorized and located from the start.

**User Flow:**
1. User taps "+" FAB or "Create Bin" button on bin search screen
2. System displays full-screen create form
3. User enters required fields:
   - Bin name (text input, required)
   - Main category (searchable picker, required)
   - Location (list picker, required)
4. User optionally adds:
   - Sub-categories (multi-select, max 3)
   - Date created (defaults to today)
5. User taps "Create"
6. System validates and saves bin
7. User sees success state and navigates to new bin detail

**Business Rules:**
- Rule 1: Bin name must be unique within the store (checked via lookup endpoint)
- Rule 2: Main category comes from store's concept-specific category list
- Rule 3: Location defaults to first on-site location if only one exists
- Rule 4: "Created Bin" action is automatically recorded with creation

**Edge Cases:**
- Scenario 1: Duplicate bin name → Show inline error "Bin name already exists"
- Scenario 2: No categories available → Show error "No categories configured for this store"
- Scenario 3: Network error during save → Show retry option; do not lose entered data
- Scenario 4: User navigates away mid-form → Show "Discard changes?" confirmation

## Success Metrics

### Key Performance Indicators

- **Adoption:** 50% of bin creations happen via mobile app within 30 days of launch
- **Engagement:** Average 15+ bin actions recorded per store per day via mobile
- **Quality:** <2% error rate on bin creation/action submissions
- **Business Impact:** 30% reduction in stale bins (>90 days) within 60 days

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `bin_created` | binId, categoryId, locationId, hasSubCategories | Track bin creation usage and patterns |
| `bin_updated` | binId, fieldsChanged[] | Track which fields users update most |
| `bin_action_performed` | binId, actionId, actionName, categoryId?, locationId? | Track action usage by type |
| `bin_deleted` | binId, binAge, wasHidden | Track deletion patterns |
| `bin_hidden` | binId, binAge | Track hiding patterns |
| `bin_activated` | binId, daysHidden | Track reactivation patterns |
| `bin_barcode_scanned` | binName, found, createFlow | Track barcode adoption |
| `bin_name_generated` | binId, categoryId | Track name generation usage |
| `bin_create_abandoned` | step, fieldsEntered | Track where users drop off |
| `bin_action_abandoned` | binId, actionType, step | Track where action flow drops off |

---

## Constraints and Assumptions

### Constraints
- Backend API is complete and documented (10 endpoints ready)
- App must work on iOS 13+ and Android 8+
- Barcode scanning requires camera permission
- Delete action restricted to Manager+ access level (existing permission system)
- No offline support in initial release (requires network connectivity)

### Assumptions
- Users will have consistent network connectivity while using backstock features
- Existing category and location data is accurate in the backend
- Bin barcodes follow a consistent format that the camera can read
- Users are already familiar with the backstock workflow from website usage

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Users create duplicate bins despite name check | Medium | Medium | Real-time duplicate check as user types; fuzzy match warning |
| Barcode scanning fails in low-light storage areas | Medium | High | Provide flashlight toggle; fall back to manual lookup |
| Actions recorded on wrong bin after scan error | High | Low | Always show bin details before action confirmation |
| Category list too long to navigate efficiently | Medium | Medium | Searchable picker with most-used (by bin count) at top |
| Network errors cause lost actions | High | Medium | Queue failed actions for retry; show pending indicator |

## Open Questions

- [x] Which action types should be user-selectable vs automatic? → All except "Created Bin" are selectable
- [x] Should hidden bins be visible in search with a filter, or in a separate screen? → Filter toggle on search
- [x] What permission level is required for delete vs hide? → Hide: all users; Delete: Manager+
- [x] Should batch actions be MVP? → No, moved to "Could Have"

---

## Supporting Research

### Competitive Analysis
- **Lightspeed Retail**: Has mobile bin creation but limited to basic fields
- **Square for Retail**: No bin/backstock concept—just inventory counts
- **Clover**: Mobile backstock is view-only; actions require POS terminal
- **BuyerKiosk (website)**: Full CRUD + actions; this mobile feature achieves parity

### User Research
- Store managers report 20-30 minute time savings per shift if bin actions can be recorded immediately
- Associates often photograph bins and update records later, leading to errors
- Barcode scanning is the #1 requested feature from BuyerKiosk mobile users

### Market Data
- 80% of retail employees carry personal smartphones during shifts
- Mobile-first inventory management adoption is growing 15% YoY
- Real-time inventory accuracy correlates with 5-8% revenue improvement in resale retail