# 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
Empower resale store owners to visualize, optimize, and manage their sales floor layout with data-driven insights, transforming static floor space into a dynamic, performance-optimized retail environment.

### Problem Statement
Resale store owners currently have no systematic way to:
1. **Track what merchandise categories are located where** on the sales floor - this knowledge exists only in employees' heads and is lost with staff turnover
2. **Understand which floor areas drive the most sales** - without spatial sales data, owners can't optimize high-traffic vs low-traffic placement
3. **Plan and execute floor layout changes** - seasonal transitions, events, and promotions require moving categories around, but there's no coordinated system to plan moves, assign tasks, and track completion
4. **Maintain rack presentation quality** - high-traffic racks need frequent tidying, but there's no visibility into which racks are overdue for maintenance

**Consequences of not solving:**
- Suboptimal merchandise placement reduces sales potential
- Layout changes are chaotic, incomplete, or forgotten
- Rack presentation degrades in high-traffic areas, hurting customer experience
- New employees have no reference for where things belong
- Event preparations are stressful and error-prone

### Value Proposition
Floor Plan Management provides the **only integrated solution** that combines:
1. **Visual floor planning** - see your store layout with rack positions and category assignments
2. **Sales performance heatmaps** - instantly identify hot and cold zones based on actual POS data
3. **Layout versioning** - plan future layouts for events/seasons and auto-generate move tasks
4. **Maintenance tracking** - prioritized rack maintenance with accountability and audit trails

Unlike generic floor plan tools, this is purpose-built for resale retail with direct integration to your existing category and sales data.

## User Personas

### Primary Persona: Store Owner (Sarah)
- **Demographics:** 35-55 years old, owns 1-3 resale clothing stores, moderate technical proficiency, uses the admin panel daily
- **Goals:**
  - Maximize sales per square foot
  - Reduce time spent on floor change coordination
  - Maintain consistent store presentation
  - Make data-driven merchandising decisions
- **Pain Points:**
  - No visibility into which floor areas perform best
  - Event prep is chaotic - things get missed
  - Staff turnover means losing institutional knowledge of "where things go"
  - Can't easily communicate layout expectations to staff

### Secondary Persona: Store Manager (Mike)
- **Demographics:** 25-45 years old, manages day-to-day operations, comfortable with technology, uses admin panel and workbook
- **Goals:**
  - Execute layout changes efficiently
  - Keep racks looking presentable
  - Delegate and track maintenance tasks
  - Prepare store for events and promotions
- **Pain Points:**
  - No clear task list for floor changes
  - Difficult to know which racks need attention
  - Hard to verify employees completed assigned moves
  - Layout instructions are verbal or on paper, easily lost

### Secondary Persona: Sales Floor Employee (Jordan)
- **Demographics:** 18-35 years old, part-time or full-time, uses workbook on shared tablet/computer, limited system access
- **Goals:**
  - Know what tasks to complete during shift
  - Understand where merchandise categories belong
  - Complete rack maintenance efficiently
  - Avoid getting blamed for incomplete work
- **Pain Points:**
  - Unclear priorities - what should I do first?
  - Don't know where things are supposed to go
  - No record of completed work
  - Can't easily communicate completion status

## User Journey Maps

### Primary User Journey: Initial Floor Plan Setup (Owner)
1. **Awareness:** Owner realizes they need better floor organization after a chaotic seasonal transition or noticing sales decline in certain areas
2. **Consideration:** Owner evaluates whether to use spreadsheets, paper diagrams, or this integrated solution
3. **Adoption:** Owner sees the Floor Plan module in admin panel, tries creating their first floor plan with the intuitive drag-drop designer
4. **Usage:**
   - Creates store shape using polygon wall tool
   - Places rack templates from library (or creates custom)
   - Names sockets on each rack
   - Assigns current category placements
   - Views first sales heatmap
5. **Retention:** Weekly heatmap reviews reveal optimization opportunities; event planning becomes streamlined

### Secondary User Journey: Planning a Seasonal Layout Change (Owner/Manager)
1. **Trigger:** Upcoming season change or promotional event requires moving categories
2. **Planning:** Owner creates a new "wanted" layout, dragging categories to their target positions
3. **Scheduling:** Owner links the layout to an event date or manually schedules activation
4. **Task Generation:** System computes diff between current and wanted layouts, generates per-category move tasks
5. **Execution:** Employees see tasks in Rack Maintenance panel, mark items as moved
6. **Completion:** Layout auto-activates on scheduled date; audit log captures all actions

### Secondary User Journey: Daily Rack Maintenance (Employee)
1. **Shift Start:** Employee opens Workbook, sees Rack Maintenance panel
2. **Prioritization:** Views combined-score ranked list showing most urgent racks (overdue + high-traffic)
3. **Execution:** Works through list, tidying each rack
4. **Completion:** Marks each rack as "Done" in the system
5. **Verification (Optional):** Manager or senior employee marks "Double Checked" for quality assurance
6. **Tracking:** System logs all actions with timestamps and user attribution

### Secondary User Journey: Viewing Floor Layout (Employee)
1. **Need:** Employee needs to know where a category belongs
2. **Access:** Opens "Floor" panel in Workbook (read-only)
3. **View:** Sees current floor plan with category assignments clearly labeled
4. **Reference:** Uses view to locate correct rack for restocking or customer questions

## Feature Requirements

### Must Have Features

#### Feature 1: Floor Plan Designer
- **User Story:** As a store owner, I want to create a visual representation of my store layout so that I can track and communicate where merchandise categories are located
- **Acceptance Criteria:**
  - [ ] User can select canvas shape (Rectangle or Square) and size (Small=40x30ft/~1200sqft, Medium=60x50ft/~3000sqft, Large=80x70ft/~5600sqft)
  - [ ] User can draw walls using simple polygon tool (click corners to place, system connects them)
  - [ ] User can place rack templates from a predefined library onto the canvas via drag-drop
  - [ ] User can create custom rack types with configurable socket count and names
  - [ ] User can name each socket on a rack (e.g., "Top Shelf", "Middle Rack", "Shoe Display")
  - [ ] User can save floor plan; saved plans persist across sessions
  - [ ] User can edit existing floor plan (move/delete racks, modify walls)
  - [ ] System warns (soft warning) if floor plan complexity may impact performance
  - [ ] Floor plan renders correctly for printing (print-friendly view)

#### Feature 2: Category Assignment to Rack Sockets
- **User Story:** As a store owner, I want to assign merchandise categories to specific rack locations so that everyone knows where each category belongs
- **Acceptance Criteria:**
  - [ ] User can assign one or more subcategories to any rack socket (many-to-many)
  - [ ] User can group multiple subcategories into a single socket assignment
  - [ ] Subcategory list is sourced from existing POS category data (~80 subcategories)
  - [ ] Same subcategory can be assigned to multiple sockets (e.g., Shoes on two racks)
  - [ ] User can remove category assignments
  - [ ] Current assignments are visually displayed on the floor plan
  - [ ] Category labels are readable at default zoom level

#### Feature 3: Layout Management (Current + Scheduled)
- **User Story:** As a store owner, I want to create multiple layout versions so that I can plan future floor arrangements and schedule them for events
- **Acceptance Criteria:**
  - [ ] System maintains one "current" active layout representing today's floor
  - [ ] User can create multiple named "wanted" layouts (e.g., "Holiday 2025", "Summer Sale")
  - [ ] Each wanted layout can be scheduled for a specific activation date
  - [ ] Only one layout can be active per day
  - [ ] User can view any saved layout (current or wanted) in the designer
  - [ ] User can edit wanted layouts before their activation date
  - [ ] User can delete wanted layouts that are no longer needed

#### Feature 4: Layout Diff and Task Generation
- **User Story:** As a store owner, I want the system to compute what needs to move when transitioning between layouts so that I don't have to manually track every change
- **Acceptance Criteria:**
  - [ ] User can request a "diff" between current layout and any wanted layout
  - [ ] System identifies all category-socket changes (additions, removals, moves)
  - [ ] System generates one task per category that needs to move
  - [ ] Task includes: category name, source location (rack/socket), destination location
  - [ ] Tasks appear in the Rack Maintenance panel for execution
  - [ ] Completed move tasks are tracked in the audit log

#### Feature 5: Scheduled Layout Activation
- **User Story:** As a store owner, I want layouts to automatically become "current" on their scheduled date so that floor changes happen on time without manual intervention
- **Acceptance Criteria:**
  - [ ] When activation date arrives, wanted layout becomes the new current layout
  - [ ] System auto-generates move tasks if not already generated
  - [ ] Layout activates regardless of whether all move tasks are complete
  - [ ] If rack sockets were deleted from floor plan, orphaned assignments are auto-removed
  - [ ] Activation is logged in audit trail

#### Feature 6: Sales Heatmap Report
- **User Story:** As a store owner, I want to see which floor areas generate the most sales so that I can optimize merchandise placement
- **Acceptance Criteria:**
  - [ ] Heatmap overlays on floor plan view showing sales performance by rack
  - [ ] Color scale indicates relative performance (cold=blue/gray to hot=red/orange)
  - [ ] User can select date range for analysis (default: last 30 days)
  - [ ] Aggregate sales shown for all categories assigned to each socket
  - [ ] Hover/click on rack shows breakdown by individual subcategory
  - [ ] Distinct visual state for: no sales (cold), not on floor plan (grayed/hatched), no data yet (hidden)
  - [ ] Heatmap is hidden entirely if store has insufficient sales data

#### Feature 7: Rack Maintenance Tracking
- **User Story:** As a store manager, I want to track which racks need maintenance and who completed it so that the sales floor stays presentable
- **Acceptance Criteria:**
  - [ ] Each rack type has a configurable maintenance interval (e.g., every 3 days)
  - [ ] System calculates maintenance urgency using combined score (time overdue + sales volume)
  - [ ] Rack Maintenance panel in Workbook shows prioritized list of racks needing attention
  - [ ] Employees can mark a rack as "Done" with one click
  - [ ] Optional "Double Checked" status can be applied by another user
  - [ ] Store owner can configure whether Double Check is required (store setting)
  - [ ] All maintenance actions are logged with timestamp and user

#### Feature 8: Maintenance Heatmap Report
- **User Story:** As a store owner, I want to see which racks are overdue for maintenance so that I can ensure consistent store presentation
- **Acceptance Criteria:**
  - [ ] Heatmap overlays on floor plan showing maintenance urgency by rack
  - [ ] Color indicates days since last maintenance (green=recent, red=overdue)
  - [ ] Hover shows last maintenance date and who completed it
  - [ ] Rack Maintenance heatmap is separate from Sales heatmap (different report views)

#### Feature 9: Workbook Floor Panel (Read-Only)
- **User Story:** As an employee, I want to view the current floor layout so that I know where merchandise categories belong
- **Acceptance Criteria:**
  - [ ] Floor panel displays current active layout
  - [ ] All category assignments are visible and readable
  - [ ] Panel is read-only for all workbook users (including managers)
  - [ ] Managers must use Admin Panel to make layout changes
  - [ ] View renders well on desktop and tablet screens

#### Feature 10: Workbook Rack Maintenance Panel
- **User Story:** As an employee, I want to see which racks need maintenance so that I can keep the floor presentable during my shift
- **Acceptance Criteria:**
  - [ ] Panel shows prioritized list of racks needing maintenance
  - [ ] Combined score (time + traffic) determines sort order
  - [ ] Each item shows: rack name/location, days since last maintenance, priority indicator
  - [ ] Employee can mark items as "Done"
  - [ ] Manager/senior can mark items as "Double Checked" (if enabled)
  - [ ] Move tasks from layout transitions appear in this panel

### Should Have Features

#### Feature 11: Event System Integration
- **User Story:** As a store owner, I want to link floor layouts to calendar events so that layout changes are automatically prepared for promotions
- **Acceptance Criteria:**
  - [ ] When creating/editing a wanted layout, user can link it to an existing event
  - [ ] Linked layouts auto-activate on event start date
  - [ ] Event details display on the layout for context
  - [ ] Unlinking an event does not delete the layout

#### Feature 12: Rack Template Library
- **User Story:** As a store owner, I want pre-built rack templates so that I can quickly populate my floor plan without defining every fixture from scratch
- **Acceptance Criteria:**
  - [ ] System provides predefined rack templates (types TBD pending store research)
  - [ ] Each template has default socket count and suggested names
  - [ ] User can customize any template after placing
  - [ ] Templates include visual icons/shapes for easy identification

#### Feature 13: Print-Optimized Floor Plan
- **User Story:** As a store manager, I want to print the floor plan so that employees have a physical reference while working the floor
- **Acceptance Criteria:**
  - [ ] Print view removes UI chrome, maximizes floor plan visibility
  - [ ] Category labels remain readable when printed
  - [ ] Option to print with or without heatmap overlay
  - [ ] Prints on standard letter/A4 paper

### Could Have Features

#### Feature 14: Floor Zones/Sections
- **User Story:** As a store owner with a large store, I want to group racks into named zones so that I can manage areas independently
- **Acceptance Criteria:**
  - [ ] User can define named zones (e.g., "Front", "Back", "Fitting Room Area")
  - [ ] Racks can be assigned to zones
  - [ ] Reports can be filtered by zone
  - [ ] Tasks can be assigned by zone

#### Feature 15: Mobile View-Only API
- **User Story:** As an employee, I want to view the floor plan on my phone so that I can reference it while on the floor
- **Acceptance Criteria:**
  - [ ] Mobile API endpoint serves floor plan data
  - [ ] Read-only access to current layout
  - [ ] View-only - no editing capabilities on mobile

### Won't Have (This Phase)

1. **Layout Version History** - Ability to view/restore historical layouts (deferred to future phase)
2. **Multi-Floor Support** - Support for stores with multiple levels (handle as separate floor plans)
3. **Real-Time Collaboration** - Multiple users editing floor plan simultaneously
4. **POS Location Tracking** - Tracking which rack a sale came from (requires POS integration beyond current scope)
5. **Automated Rack Recommendations** - AI-suggested category placements based on sales data
6. **Mobile Editing** - Creating/editing floor plans on mobile devices
7. **3D Visualization** - Three-dimensional store views
8. **Inventory Integration** - Showing current inventory levels on floor plan

## Detailed Feature Specifications

### Feature: Layout Diff and Task Generation
**Description:** When a store owner wants to transition from the current floor layout to a planned "wanted" layout, the system analyzes both layouts, identifies all differences in category-to-socket assignments, and generates actionable tasks for employees to execute the transition.

**User Flow:**
1. User navigates to Layout Management in Admin Panel
2. User selects a wanted layout from the list
3. User clicks "Compare to Current" or "Generate Move Tasks"
4. System displays side-by-side comparison showing:
   - Categories being added to new locations
   - Categories being removed from current locations
   - Categories moving from one rack to another
5. User reviews the diff and confirms task generation
6. System creates individual tasks for each category move
7. Tasks appear in Workbook Rack Maintenance panel
8. Employees execute moves and mark tasks complete
9. On scheduled date, layout activates regardless of task status

**Business Rules:**
- Rule 1: One task is generated per category that changes location (not per socket)
- Rule 2: If a category is on multiple sockets and only one changes, only one task is generated for that move
- Rule 3: Tasks include both "from" and "to" locations for clarity
- Rule 4: If floor plan structure changed (rack deleted), affected category assignments in wanted layout are auto-removed before diff
- Rule 5: Re-generating tasks for the same layout transition overwrites previous incomplete tasks
- Rule 6: Completed tasks are preserved in audit log even if layout is edited

**Edge Cases:**
- Scenario 1: Wanted layout has category on a rack that was deleted → Expected: Auto-remove that assignment, log warning, proceed with remaining diff
- Scenario 2: User generates tasks, then edits the wanted layout → Expected: User can regenerate tasks; old incomplete tasks are replaced
- Scenario 3: Activation date passes with incomplete tasks → Expected: Layout activates anyway; incomplete tasks remain for completion tracking
- Scenario 4: Category appears on 3 sockets currently, wanted layout has it on 2 different sockets → Expected: Generate tasks for "Remove from Socket A", "Add to Socket D", etc.
- Scenario 5: No differences between current and wanted layout → Expected: Show "No changes needed" message, generate no tasks

### Feature: Sales Heatmap Calculation
**Description:** The sales heatmap visualizes revenue performance across the store floor by aggregating POS sales data by category and mapping it to the rack sockets where those categories are assigned.

**User Flow:**
1. User opens Sales Heatmap Report in Admin Panel
2. User selects date range (default: last 30 days)
3. System queries sales data grouped by subcategory
4. System maps each subcategory to its assigned rack socket(s)
5. System calculates total revenue per socket (sum of all assigned subcategories)
6. System renders floor plan with color overlay based on relative performance
7. User hovers over a rack to see breakdown by subcategory
8. User can adjust date range to analyze different periods

**Business Rules:**
- Rule 1: Sales data comes from `kiosk_sales.sales` table, grouped by `catID` (maps to subcategory codes)
- Rule 2: If a subcategory is assigned to multiple sockets, the SAME total appears on each socket (not divided)
- Rule 3: Heatmap colors are relative within the store (highest performer = hottest, lowest = coldest)
- Rule 4: Sockets with no assigned categories show as "not applicable" (distinct from zero sales)
- Rule 5: Categories with zero sales in period show as cold/blue
- Rule 6: If store has no sales data in selected period, heatmap is hidden with explanatory message
- Rule 7: Subcategory breakdown on hover shows individual contribution to socket total

**Edge Cases:**
- Scenario 1: New store with no sales data → Expected: Hide heatmap, show "Collecting data..." message
- Scenario 2: Category sold but not assigned to any socket → Expected: Show alert/indicator that sales exist for unplaced category
- Scenario 3: Date range has partial data (store opened mid-period) → Expected: Calculate based on available data, note limited data in UI
- Scenario 4: All sockets have same sales value → Expected: All show as neutral/middle color

### Feature: Maintenance Priority Scoring
**Description:** Rack maintenance priority is calculated using a combined score that weighs both time since last maintenance and sales volume, ensuring high-traffic areas get more frequent attention.

**Business Rules:**
- Rule 1: Base score = Days since last maintenance / Maintenance interval for rack type
- Rule 2: Traffic multiplier = Socket's sales volume / Average socket sales volume (normalized)
- Rule 3: Combined score = Base score × (1 + Traffic multiplier × Weight factor)
- Rule 4: Weight factor is configurable per store (default: 0.5)
- Rule 5: Racks with no assigned categories use base score only (no traffic multiplier)
- Rule 6: New racks start with "never maintained" status and appear at top of list
- Rule 7: Manual priority override by managers takes precedence over calculated score

**Edge Cases:**
- Scenario 1: Rack has no maintenance history → Expected: Treat as maximally overdue
- Scenario 2: Rack was just maintained, but traffic spike happened → Expected: Traffic multiplier applies but base score is low, so it won't jump to top
- Scenario 3: Rack type has no defined maintenance interval → Expected: Use store default interval (configurable)

## Success Metrics

### Key Performance Indicators

- **Adoption:** 60% of active stores create a floor plan within 90 days of feature launch
- **Engagement:** Active stores view heatmap reports at least 2x per month
- **Task Completion:** 80% of generated move tasks marked complete within 7 days of activation date
- **Maintenance Coverage:** Average rack maintenance compliance rate of 75% (maintained within interval)
- **Business Impact:** Stores using floor plan optimization show 5% improvement in sales per square foot (6-month measurement)

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| floor_plan_created | store_id, canvas_size, rack_count | Track adoption and floor plan complexity |
| floor_plan_edited | store_id, edit_type (rack/wall/socket) | Understand iteration patterns |
| layout_created | store_id, layout_name, is_scheduled | Track layout planning behavior |
| layout_activated | store_id, layout_id, tasks_complete_pct | Measure transition completion |
| heatmap_viewed | store_id, heatmap_type (sales/maintenance), date_range | Track report engagement |
| task_generated | store_id, task_count, trigger (manual/scheduled) | Measure task generation volume |
| task_completed | store_id, task_id, user_id, task_type (move/maintenance) | Track employee engagement |
| maintenance_marked_done | store_id, rack_id, user_id | Track maintenance activity |
| maintenance_double_checked | store_id, rack_id, user_id | Track verification usage |
| category_assigned | store_id, socket_id, subcategory_count | Track category management |
| print_floor_plan | store_id, include_heatmap | Measure print feature usage |

---

## Constraints and Assumptions

### Constraints
- **Data Dependency:** Sales heatmap requires populated `kiosk_sales.sales` table with valid `catID` values
- **Category Mapping:** Subcategory codes in POS data must map to known subcategories (~80 from DRS export)
- **Browser Support:** Floor plan designer requires modern browser with canvas/SVG support (Chrome, Firefox, Safari, Edge)
- **Single Floor:** MVP supports single-floor stores only; multi-floor requires separate floor plans
- **Existing Permissions:** Must use existing Owner/Manager/Employee role hierarchy
- **Per-Store Data:** All floor plan data stored in per-store database (follows existing architecture)

### Assumptions
- Store owners have basic computer proficiency for drag-drop interfaces
- Stores have relatively stable physical layouts (rack positions don't change frequently)
- POS category data is reasonably accurate and consistently used
- Employees have access to shared computers/tablets in the store
- Print capability exists at most stores for physical floor plan reference
- Event system integration is available and functional

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Floor plan designer too complex for non-technical users | High | Medium | Provide video tutorials, use familiar drag-drop patterns, offer preset templates |
| Sales data doesn't map cleanly to floor categories | High | Medium | Build category mapping admin tool, handle unmapped categories gracefully |
| Employees don't adopt maintenance tracking | Medium | Medium | Make UI simple, show immediate feedback, gamify with completion stats |
| Large floor plans cause performance issues | Medium | Low | Implement soft warnings, optimize rendering, lazy-load heatmap data |
| Rack template library doesn't match actual store fixtures | Medium | High | Support custom rack creation, gather research on common fixture types |
| Layout activation causes confusion if tasks incomplete | Medium | Medium | Clear UI messaging, notification before activation, incomplete task warnings |
| Print output not readable | Low | Low | Test print layouts early, allow zoom/scale options |

## Open Questions

- [x] What specific rack/fixture types should be in the initial template library? → **Research needed with store owners**
- [x] Should categories be assigned at category level or subcategory level? → **Subcategory level with grouping**
- [x] How should many-to-many category assignments display on heatmap? → **Same value shown on each socket**
- [x] What maintenance intervals are typical for different rack types? → **Configurable per rack type, store default**
- [x] What are the exact canvas dimensions for Small/Medium/Large presets? → **Grid units representing 1ft each: Small=40x30 (~1200sqft), Medium=60x50 (~3000sqft), Large=80x70 (~5600sqft)**
- [x] Should there be a maximum number of scheduled layouts per store? → **Unlimited - no cap on scheduled layouts**
- [x] What notification mechanism alerts managers about upcoming layout activations? → **Deferred to future phase - no notifications in MVP**

---

## Supporting Research

### Competitive Analysis
**Retail Floor Planning Tools:**
- **SmartDraw / Lucidchart:** General-purpose diagramming tools can create floor plans but lack retail-specific features, no POS integration, no maintenance tracking
- **Visual Retail Plus:** Enterprise retail planning, expensive, overkill for resale stores
- **CB4:** AI-driven retail analytics but focused on planogram compliance for large retailers

**Gap:** No existing solution combines visual floor planning + POS sales heatmapping + maintenance tracking specifically for resale/consignment retail at an accessible price point.

### User Research
Based on requirements gathering session:
- Store owners currently use paper diagrams or mental models for floor layout
- Seasonal transitions (4x/year) and events cause significant floor reorganization
- Rack maintenance is ad-hoc; high-traffic areas degrade faster
- Staff turnover creates knowledge gaps about merchandise placement
- Event preparation is a major pain point with missed items and confusion

### Market Data
- US secondhand apparel market: $43B in 2023, growing 11% annually (ThredUp)
- Average resale store: 2,000-5,000 sq ft sales floor
- Typical store has 20-50 rack/display fixtures
- Staff turnover in retail: 60%+ annually, creating continuous training needs