# 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 a professional-grade designer that transforms static floor space into a dynamic, performance-optimized retail environment powered by SyncFusion's industry-leading diagram technology.

### 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 (60%+ annual retail turnover rate)

2. **Understand which floor areas drive the most sales** - without spatial sales data, owners can't optimize high-traffic vs low-traffic placement, leaving potential revenue on the table

3. **Plan and execute floor layout changes** - seasonal transitions (4x/year minimum), 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 degrade faster and need frequent tidying, but there's no visibility into which racks are overdue for maintenance

5. **Create professional floor plans** - existing paper diagrams and mental models don't scale, can't be shared, and provide no analytics

**Evidence:**
- User research shows event preparation is a major pain point with missed items and confusion
- Staff turnover creates continuous knowledge gaps about merchandise placement
- Stores average 2,000-5,000 sq ft with 20-50 rack/display fixtures to manage
- No existing solution combines visual floor planning + POS sales heatmapping + maintenance tracking for resale retail

**Consequences of not solving:**
- Suboptimal merchandise placement reduces sales per square foot
- 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
The SyncFusion Floor Plan Designer provides the **only integrated solution** for resale retail that combines:

1. **Professional floor planning** - industry-grade diagram tools with drag-drop rack placement, snap-to-grid precision, and visual category assignments

2. **Sales performance heatmaps** - instantly identify hot and cold zones based on actual POS data to optimize merchandise placement

3. **Layout versioning & scheduling** - plan future layouts for events/seasons with auto-generated move tasks and scheduled activations

4. **Maintenance tracking** - prioritized rack maintenance with accountability and audit trails

5. **Symbol palette with retail fixtures** - purpose-built rack templates (round racks, straight racks, shoe displays, etc.) that match real store fixtures

Unlike generic floor plan tools, this is purpose-built for resale retail with direct integration to existing BuyerKiosk 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 for business operations
- **Goals:**
  - Maximize sales per square foot through strategic merchandise placement
  - Reduce time spent on floor change coordination from hours to minutes
  - Maintain consistent store presentation across all staff shifts
  - Make data-driven merchandising decisions backed by actual sales data
- **Pain Points:**
  - No visibility into which floor areas perform best - decisions are gut-feel
  - Event prep is chaotic - things get missed, confusion about what goes where
  - Staff turnover means losing institutional knowledge of "where things go"
  - Can't easily communicate layout expectations to staff without walking the floor

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

### 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 without asking manager
  - Understand where merchandise categories belong quickly
  - Complete rack maintenance efficiently
  - Avoid getting blamed for incomplete work
- **Pain Points:**
  - Unclear priorities - what should I do first when starting my shift?
  - Don't know where things are supposed to go, especially as a newer employee
  - No record of completed work to prove I did my tasks
  - Can't easily communicate completion status to manager

## 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 despite having good inventory
2. **Consideration:** Owner evaluates options - spreadsheets, paper diagrams, generic CAD tools, or this integrated solution
3. **Adoption:** Owner sees the Floor Plan module in admin sidebar, clicks to explore, and sees "Create Your First Floor Plan" with an intuitive starting point
4. **Usage:**
   - Selects canvas size preset matching approximate store dimensions (Small/Medium/Large)
   - Uses polygon wall tool to draw store perimeter (click corners, system connects)
   - Opens symbol palette showing rack templates (Round Rack, Straight Rack, Shoe Display, etc.)
   - Drags rack templates onto canvas, positions with snap-to-grid
   - Names sockets on each rack (e.g., "Women's Tops", "Clearance")
   - Assigns current category placements from dropdown showing POS subcategories
   - Views first sales heatmap overlay to see performance by zone
5. **Retention:** Weekly heatmap reviews reveal optimization opportunities; event planning becomes streamlined with layout versioning; new employees onboard faster with visual reference

### Secondary User Journey: Planning a Seasonal Layout Change (Owner/Manager)
1. **Trigger:** Upcoming season change (Spring → Summer) or promotional event requires moving categories around
2. **Planning:** Owner opens current layout and clicks "Create New Layout Version" - names it "Summer 2025"
3. **Editing:** Owner drags categories to their target positions for summer merchandise mix
4. **Scheduling:** Owner sets activation date (e.g., May 1st) and optionally links to an event
5. **Task Generation:** System computes diff between current and wanted layouts, generates per-category move tasks with clear "From: Rack 3 → To: Rack 7" instructions
6. **Execution:** Manager and employees see tasks in Rack Maintenance panel, mark items as moved during their shifts
7. **Completion:** Layout auto-activates on scheduled date; audit log captures all actions; current layout archives for historical reference

### Secondary User Journey: Daily Rack Maintenance (Employee)
1. **Shift Start:** Employee opens Workbook on shared tablet, clicks Rack Maintenance panel
2. **Prioritization:** Views combined-score ranked list showing most urgent racks (overdue maintenance + high-traffic = higher priority)
3. **Visual Reference:** Can tap any rack to see its location on the floor plan thumbnail
4. **Execution:** Works through list from top priority down, tidying each rack
5. **Completion:** Marks each rack as "Done" with one tap
6. **Verification (Optional):** If store has Double Check enabled, manager marks "Verified" after inspecting
7. **Tracking:** System logs all actions with timestamps and user attribution for accountability

### Secondary User Journey: Viewing Floor Layout (Employee)
1. **Need:** Employee needs to know where a specific category belongs (customer asked, or restocking)
2. **Access:** Opens "Floor" panel in Workbook (read-only view)
3. **View:** Sees current floor plan with category assignments clearly labeled and color-coded
4. **Search (Optional):** Types category name to highlight which rack(s) it's assigned to
5. **Reference:** Uses view to locate correct rack for restocking or customer assistance
6. **Result:** Employee answers customer question or places merchandise correctly without asking manager

## Feature Requirements

### Must Have Features

#### Feature 1: Professional Floor Plan Designer
- **User Story:** As a store owner, I want to create a professional visual representation of my store layout so that I can track and communicate where merchandise categories are located
- **Acceptance Criteria:**
  - [ ] User can select canvas size preset: Small (~1,200 sqft), Medium (~3,000 sqft), Large (~5,600 sqft)
  - [ ] User can draw walls using polygon tool (click to place corners, system auto-connects)
  - [ ] User can access symbol palette with predefined rack templates
  - [ ] User can drag rack symbols from palette onto canvas
  - [ ] Racks snap to grid for precise alignment (configurable grid size)
  - [ ] User can rotate racks in 15° increments for angled placement
  - [ ] User can resize racks while maintaining aspect ratio
  - [ ] User can select, move, and delete placed racks
  - [ ] User can undo/redo any action (minimum 20 steps)
  - [ ] User can zoom in/out and pan across the canvas
  - [ ] User can save floor plan; saves persist across sessions
  - [ ] User can edit existing floor plan (move, delete, add racks)
  - [ ] Floor plan renders correctly for printing (print-friendly view)

#### Feature 2: Symbol Palette with Retail Rack Templates
- **User Story:** As a store owner, I want pre-built rack templates that match my actual store fixtures so that I can quickly populate my floor plan without designing from scratch
- **Acceptance Criteria:**
  - [ ] Symbol palette displays collapsible categories of rack types
  - [ ] System provides predefined rack templates organized by type:

    **Gondola Fixtures:**
    - Gondola – Shoe Deck (Double-Sided) (rectangular, 4-6 sockets for shoes/merchandise)
    - Gondola – Endcap (Grid End) (rectangular end cap, 2-3 sockets)

    **Endcap Fixtures:**
    - Endcap – Shoe Wing (Peg) (rectangular with peg display, 2-3 sockets)

    **Freestanding Fixtures:**
    - Rounder (circular rack, 1 socket - single category focus)
    - Spinner – Accessories (circular, 1 socket - small items)
    - Four-Way Rack (cross-shaped, 4 sockets - multi-directional)

    **Wall Fixtures:**
    - Wall Bay – Hangrail (optional Shoe Shelf) (long rectangular wall unit, 4-6 sockets)
    - Wall Unit – Standard (rectangular, 4-6 sockets)

    **Combination/Multi-Use:**
    - Combo Shoe + Apparel Rack (rectangular, 2-4 sockets for mixed display)

    **Service Areas:**
    - Cash Wrap / Checkout Counter (rectangular, 1 socket - impulse items)
    - Table Display (square, 1 socket - featured items)
    - Clearance Bin (square, 1 socket - sale items)

  - [ ] Each template has appropriate visual icon/shape matching the fixture type
  - [ ] Each template has default socket count and suggested socket names
  - [ ] User can create custom rack templates for unique fixtures
  - [ ] Custom templates appear in a "Custom" section of the palette
  - [ ] Drag-drop from palette to canvas with visual preview during drag

#### Feature 3: Rack Sockets and Category Assignment
- **User Story:** As a store owner, I want to assign merchandise categories to specific rack locations (sockets) so that everyone knows exactly where each category belongs
- **Acceptance Criteria:**
  - [ ] Each rack has configurable sockets (named locations within the rack)
  - [ ] User can name each socket (e.g., "Top Shelf", "Lower Bar", "Side Panel")
  - [ ] User can assign one or more subcategories to any socket (many-to-many)
  - [ ] Subcategory dropdown shows all store-specific POS subcategories with search (e.g., 113 for Plato's Closet)
  - [ ] Same subcategory can appear on multiple sockets (e.g., "Women's Dresses" on 3 racks)
  - [ ] Current assignments are visually displayed on the floor plan (category badges)
  - [ ] Category labels are readable at default zoom level
  - [ ] User can remove category assignments with one click
  - [ ] Changes auto-save or prompt for save on navigation away

#### Feature 4: Layout Versioning (Current + Wanted)
- **User Story:** As a store owner, I want to create multiple layout versions so that I can plan future floor arrangements for events and seasons
- **Acceptance Criteria:**
  - [ ] System maintains one "Current" layout representing today's actual floor
  - [ ] User can create new "Wanted" layouts from scratch or by copying existing
  - [ ] Each wanted layout has a name (e.g., "Holiday 2025", "Summer Sale")
  - [ ] Each wanted layout can have an optional activation date
  - [ ] Only one layout can be "Current" (active) at any time
  - [ ] User can view any saved layout in the designer (read-only for non-current)
  - [ ] User can edit wanted layouts before their activation
  - [ ] User can delete wanted layouts that are no longer needed
  - [ ] Cannot delete the current active layout

#### Feature 5: Layout Diff and Move Task Generation
- **User Story:** As a store owner, I want the system to automatically identify 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 "Compare" between current layout and any wanted layout
  - [ ] System displays visual diff: additions (green), removals (red), moves (yellow)
  - [ ] System generates summary: X additions, Y removals, Z moves
  - [ ] User can click "Generate Tasks" to create move tasks from diff
  - [ ] Tasks are **atomic** (socket-level): each task is either an **Add** (to a socket) or a **Remove** (from a socket)
  - [ ] Each task includes: category name, task type (add/remove), rack/socket context (from/to as applicable)
  - [ ] Tasks appear in Rack Maintenance panel for employees
  - [ ] If category is on multiple sockets and only some change, only changed sockets generate tasks
  - [ ] If a category is removed from the floor in the wanted layout (no destination), system prompts for a **resolution** before generating tasks:
    - [ ] Mark as "Gone" (optional reason: sold out/donated/other) → **creates audit entry only (no task)**
    - [ ] Move to Backstock (optional: select specific bin now; otherwise employee may choose an existing bin, create a new empty bin, or leave bin unspecified and resolve later)
  - [ ] Re-generating tasks replaces previous incomplete tasks (with warning)
  - [ ] Completed tasks are preserved in history/audit log

#### Feature 6: Scheduled Layout Activation
- **User Story:** As a store owner, I want layouts to automatically become active on their scheduled date so that floor changes happen on time without me having to remember
- **Acceptance Criteria:**
  - [ ] Wanted layout with activation date shows countdown in UI
  - [ ] On activation date, wanted layout becomes the new "Current" layout
  - [ ] Previous current layout is archived (not deleted)
  - [ ] System auto-generates move tasks if not already generated
  - [ ] Activation occurs regardless of task completion status
  - [ ] Activation is logged in audit trail with timestamp
  - [ ] If multiple layouts scheduled for same date, first created activates (with warning on save)

#### Feature 7: 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 for maximum revenue
- **Acceptance Criteria:**
  - [ ] Heatmap overlays on floor plan view as semi-transparent color layer
  - [ ] **Dual visualization modes** - user can toggle between:
    - **Socket Coloring**: Colors each rack/socket directly based on sales (discrete, clear per-element)
    - **Gradient Heatmap**: Continuous color gradient overlay showing "hot zones" (uses heatmap.js)
    - **Both**: Socket coloring + gradient overlay at reduced opacity
  - [ ] Color scale: cold (blue/gray) to hot (red/orange) based on relative sales
  - [ ] User can select date range (default: last 30 days)
  - [ ] Sales aggregated by subcategory and projected onto assigned sockets
  - [ ] If subcategory is on multiple sockets, same total appears on each socket
  - [ ] Hover/click on rack shows breakdown: subcategory names and individual sales
  - [ ] Distinct visual for: no data yet (gray hatched), zero sales (cold blue), not assigned (neutral)
  - [ ] Heatmap hidden with message if store has insufficient sales data (<7 days)
  - [ ] Toggle to show/hide heatmap overlay
  - [ ] User preference for visualization mode saved per store

#### Feature 8: Rack Maintenance Tracking
- **User Story:** As a store manager, I want to track which racks need tidying and who completed it so that the sales floor stays presentable
- **Acceptance Criteria:**
  - [ ] Each rack type has a configurable maintenance interval (default: 3 days)
  - [ ] System calculates priority score: time overdue + sales volume weighting
  - [ ] Rack Maintenance panel in Workbook shows prioritized list
  - [ ] List shows: rack name, location description, days since last maintenance, priority badge
  - [ ] Employee can mark rack as "Done" with one tap
  - [ ] Optional "Double Check" can be marked by different user (manager)
  - [ ] Store setting to require Double Check (on/off)
  - [ ] All maintenance actions logged with timestamp and user

#### Feature 9: 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:**
  - [ ] Maintenance heatmap overlays on floor plan (separate from sales heatmap)
  - [ ] Color indicates urgency: green (recent) → yellow (due soon) → red (overdue)
  - [ ] Hover shows: last maintained date, who completed it, days overdue
  - [ ] Toggle between Sales Heatmap and Maintenance Heatmap views
  - [ ] Can view both simultaneously with different opacity levels

#### Feature 10: Workbook Floor Panel (Employee View)
- **User Story:** As an employee, I want to view the current floor layout so that I know where merchandise categories belong without asking my manager
- **Acceptance Criteria:**
  - [ ] Floor panel displays current active layout
  - [ ] All category assignments visible with readable labels
  - [ ] Can search/filter by category name (highlights matching racks)
  - [ ] View is read-only (no editing from workbook)
  - [ ] Tap rack to see socket assignments in popup/sidebar
  - [ ] View renders well on tablet screens (minimum 768px width)
  - [ ] Basic zoom/pan controls for navigation

#### Feature 11: Workbook Rack Maintenance Panel (Employee View)
- **User Story:** As an employee, I want to see my rack maintenance tasks so that I can keep the floor presentable during my shift
- **Acceptance Criteria:**
  - [ ] Panel shows prioritized list of racks needing maintenance
  - [ ] Move tasks from layout transitions appear in this list
  - [ ] Each item shows: task type icon (maintenance vs move), rack name, priority
  - [ ] Tap "Done" to mark maintenance complete
  - [ ] Completed items move to "Done Today" section (collapsible)
  - [ ] Refresh button to update list
  - [ ] Shows count badge in workbook navigation

### Should Have Features

#### Feature 12: 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 wanted layout, can link to existing event
  - [ ] Linked layouts inherit activation date from event start
  - [ ] If event dates change, layout activation date updates automatically
  - [ ] Event name displays on layout for context
  - [ ] Unlinking event preserves layout (just removes auto-sync)
  - [ ] Move tasks can auto-generate X days before event

#### 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 button opens print preview
  - [ ] Print view removes UI controls, maximizes floor plan
  - [ ] Category labels remain readable when printed
  - [ ] Option to include/exclude heatmap overlay
  - [ ] Date and layout name printed as header
  - [ ] Fits on standard letter (8.5x11") or A4 paper

#### Feature 14: Audit Log Viewer
- **User Story:** As a store owner, I want to see a history of floor plan changes so that I can track who made what changes and when
- **Acceptance Criteria:**
  - [ ] Audit log shows: action, entity, user, timestamp
  - [ ] Actions include: created, updated, deleted, activated, assigned, maintained
  - [ ] Can filter by action type, date range, user
  - [ ] Export audit log to CSV

#### Feature 15: Background Image + Calibration
- **User Story:** As a store owner, I want to import a background image and calibrate scale so my floor plan matches the real store dimensions
- **Acceptance Criteria:**
  - [ ] User can upload a background image (optional) for a floor plan
  - [ ] User can adjust background opacity (to trace over it)
  - [ ] User can calibrate scale by drawing a measurement line and entering real-world distance (e.g., 20 ft)
  - [ ] System stores measurement unit (ft) and scale factor for the floor plan
  - [ ] Rulers/grid reflect calibrated scale (within reasonable tolerance)

#### Feature 16: Rack Identity + Find Rack
- **User Story:** As a store owner/manager, I want racks to have clear unique names and a “find rack” search so staff can follow tasks reliably
- **Acceptance Criteria:**
  - [ ] Newly created racks auto-receive a unique name/label (e.g., R1, R2, ...)
  - [ ] Rack names are unique within the store’s floor plan
  - [ ] User can rename a rack; system prevents duplicate names
  - [ ] “Find rack” search highlights/zooms to matching racks by name
  - [ ] Move/maintenance tasks reference rack names consistently

#### Feature 17: Draft vs Published Current Layout
- **User Story:** As a store owner/manager, I want a draft/publish workflow so I can safely edit without changing what employees see until I’m ready
- **Acceptance Criteria:**
  - [ ] Editing the current layout creates/uses a draft version
  - [ ] Employees (Workbook) see only the published current layout
  - [ ] User can publish draft to become the new current layout
  - [ ] User can discard draft changes
  - [ ] UI clearly indicates “Draft” vs “Published”

#### Feature 18: Export Floor Plan (JSON/PNG)
- **User Story:** As a store owner/manager, I want to export the floor plan as JSON and PNG for support/debugging and training
- **Acceptance Criteria:**
  - [ ] User can export floor plan as JSON (diagram + assignments)
  - [ ] User can export floor plan as PNG image
  - [ ] Exports include the layout name/date in metadata or filename
  - [ ] Export respects current published layout by default (optionally include draft)

### Could Have Features

#### Feature 19: 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 draw zone boundaries (polygon)
  - [ ] Zones have names (e.g., "Front", "Back", "Fitting Room Area")
  - [ ] Racks can be assigned to zones automatically (by position)
  - [ ] Reports can filter by zone
  - [ ] Maintenance tasks can be assigned by zone

#### Feature 20: Custom Rack Template Builder
- **User Story:** As a store owner, I want to create custom rack templates with specific shapes and socket configurations for my unique fixtures
- **Acceptance Criteria:**
  - [ ] Template builder UI for creating custom shapes
  - [ ] Define socket positions visually on the template
  - [ ] Set default maintenance interval for template
  - [ ] Templates saved to store's custom library
  - [ ] Can edit/delete custom templates

#### Feature 21: 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-responsive read-only floor view
  - [ ] Pinch-to-zoom and pan navigation
  - [ ] Category search with rack highlighting
  - [ ] No editing on mobile

### Won't Have (This Phase)

1. **Layout Version History** - Ability to view/restore specific historical layout states (beyond current/wanted/archived)
2. **Multi-Floor Support** - Stores with multiple levels (handle as separate floor plans per floor)
3. **Real-Time Collaboration** - Multiple users editing the same floor plan simultaneously
4. **POS Location Tracking** - Tracking which physical rack rang up a specific sale (requires POS hardware changes)
5. **Automated Rack Recommendations** - AI-suggested category placements based on sales patterns
6. **3D Visualization** - Three-dimensional store views
7. **Inventory Integration** - Showing current inventory levels on the floor plan
8. **Customer Traffic Heatmaps** - Foot traffic tracking (requires sensors)

## Detailed Feature Specifications

### Feature: Layout Diff and Move Task Generation
**Description:** When a store owner wants to transition from the current floor layout to a planned future 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" button
4. System displays side-by-side visual comparison showing:
   - Categories being added to new locations (green highlight)
   - Categories being removed from current locations (red highlight)
   - Categories moving from one rack to another (yellow highlight with arrow)
5. User reviews the diff summary showing counts
6. User clicks "Generate Move Tasks" to confirm
7. If the wanted layout **drops** categories (present in current, absent in wanted), system prompts user to resolve each dropped category (Gone vs Backstock, optional bin)
8. System creates individual **atomic** tasks for each socket-level change (Add or Remove)
8. Tasks appear in Workbook Rack Maintenance panel for employees
9. Employees execute moves and mark tasks complete
10. On scheduled date (or manual activation), layout activates regardless of task status

**Business Rules:**
- **Rule 1:** Tasks are generated at the socket level and are **atomic** operations:
  - **Add Task**: `toSocket` is set, `fromSocket` is empty
  - **Remove Task**: `fromSocket` is set, `toSocket` is empty (used for Backstock resolution only)
- **Rule 2:** UI may visualize a "move" as a combined change, but task execution remains atomic (remove then add)
- **Rule 3:** If a rack was deleted from the floor plan, any category assignments to that rack are automatically removed from the wanted layout before diff
- **Rule 4:** Re-generating tasks for the same layout overwrites previous incomplete tasks (warning shown to user)
- **Rule 5:** Completed tasks are preserved in audit log even if layout is later edited
- **Rule 6:** Task completion does not affect layout activation - layouts activate on schedule regardless
 - **Rule 7:** Dropped category resolution:
   - If a category exists in current layout but not in wanted layout, the system requires a resolution before task generation:
     - **Gone**: indicates the category will no longer be on the floor (optional reason captured)
       - Result: **audit entry only** (no task created)
     - **Backstock**: indicates the category is moving off-floor into backstock (optional bin selection now; if no bin selected, employee must choose existing bin or create a new empty bin when completing the task)

**Edge Cases:**
- **Scenario 1:** Wanted layout has category on a deleted rack → Expected: Auto-remove that assignment, log warning, show notification to user, proceed with remaining diff
- **Scenario 2:** User generates tasks, then edits the wanted layout → Expected: Prompt to regenerate tasks; old incomplete tasks replaced if user confirms
- **Scenario 3:** Activation date passes with incomplete tasks → Expected: Layout activates anyway; incomplete tasks remain visible for tracking but marked as "post-activation"
- **Scenario 4:** Category on 3 sockets currently, wanted has it on 2 different sockets → Expected: Generate specific socket-level tasks (remove from A, remove from B, add to C)
- **Scenario 5:** No differences between current and wanted layout → Expected: Show "Layouts are identical" message, disable task generation button
 - **Scenario 6:** Category is removed from the wanted layout (dropped) → Expected: Prompt user to mark as Gone or Backstock before generating tasks
 - **Scenario 7:** Dropped category marked Gone → Expected: Create audit entry with reason; no task generated
 - **Scenario 8:** Dropped category marked Backstock without bin → Expected: Task generated with "bin TBD"; employee may select existing bin, create new empty bin, or complete without bin and resolve later
 - **Scenario 9:** Employee completes Backstock task without bin → Expected: Task can be completed; bin remains unspecified and can be assigned later

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

**User Flow:**
1. User opens Sales Heatmap Report in Admin Panel
2. User selects date range picker (default: last 30 days)
3. System queries sales data grouped by subcategory
4. System looks up which sockets have each subcategory assigned in current layout
5. System calculates relative performance (min to max scale)
6. System renders floor plan with color overlay based on relative performance
7. User hovers over a rack to see tooltip with breakdown by subcategory
8. User can adjust date range to analyze different time periods

**Business Rules:**
- **Rule 1:** Sales data comes from POS system, grouped by subcategory code (catID)
- **Rule 2:** If a subcategory is assigned to multiple sockets, the SAME total sales appears on each socket (not divided) - this shows category performance, not rack-specific sales
- **Rule 3:** Heatmap colors are relative within the current view (highest = hottest, lowest = coldest)
- **Rule 4:** Sockets with no assigned categories show as "N/A" (neutral gray hatched) - distinct from zero sales
- **Rule 5:** Categories with zero sales in period show as cold (blue), not N/A
- **Rule 6:** If store has less than 7 days of sales data, heatmap is hidden with "Collecting data..." message
- **Rule 7:** Hover breakdown shows each subcategory's contribution to the socket total

**Edge Cases:**
- **Scenario 1:** New store with no sales data → Expected: Hide heatmap, show "Sales data not yet available" message with explanation
- **Scenario 2:** Category sold items but not assigned to any socket → Expected: Show alert indicator "Unassigned categories have sales" with list
- **Scenario 3:** Date range has partial data (store opened mid-period) → Expected: Calculate based on available data, show "Limited data" indicator
- **Scenario 4:** All sockets have identical sales → Expected: All show as neutral middle color (not misleading hot/cold)
- **Scenario 5:** Very high outlier socket skewing scale → Expected: Use percentile-based coloring (95th percentile = max) to prevent one outlier making everything else look cold

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

**Business Rules:**
- **Rule 1:** Base score = Days since last maintenance / Maintenance interval for that rack type
- **Rule 2:** Traffic multiplier = Socket's sales volume / Average socket sales volume (normalized 0-2 range)
- **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 (traffic multiplier = 1.0)
- **Rule 6:** New racks with no maintenance history treated as maximally overdue (appear at top)
- **Rule 7:** Manager can manually pin a rack to top priority (override calculated score)

**Edge Cases:**
- **Scenario 1:** Rack has never been maintained → Expected: Treat as maximum base score (e.g., 10.0), appears at top of list
- **Scenario 2:** Rack just maintained but has very high traffic → Expected: Low base score keeps it from top despite high multiplier
- **Scenario 3:** Rack type has no defined maintenance interval → Expected: Use store default interval setting
- **Scenario 4:** Zero average sales (new store) → Expected: All racks use base score only until sales data available

## 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/assignment) | Understand iteration patterns |
| `layout_created` | store_id, layout_name, is_scheduled, linked_event_id | Track layout planning behavior |
| `layout_diff_viewed` | store_id, layout_id, diff_summary (adds/removes/moves) | Measure planning engagement |
| `layout_activated` | store_id, layout_id, tasks_complete_pct, activation_type (manual/scheduled) | Measure transition completion |
| `tasks_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 |
| `heatmap_viewed` | store_id, heatmap_type (sales/maintenance), date_range_days | Track report engagement |
| `heatmap_date_range_changed` | store_id, old_range, new_range | Understand analysis patterns |
| `maintenance_marked_done` | store_id, rack_id, user_id, days_overdue | Track maintenance activity |
| `maintenance_double_checked` | store_id, rack_id, user_id | Track verification usage |
| `category_assigned` | store_id, socket_id, subcategory_codes, layout_id | Track category management |
| `category_unassigned` | store_id, socket_id, subcategory_code | Track category management |
| `print_floor_plan` | store_id, include_heatmap, layout_id | Measure print feature usage |
| `workbook_floor_viewed` | store_id, user_id, user_role | Track employee usage |
| `workbook_maintenance_viewed` | store_id, user_id, pending_task_count | Track task awareness |

---

## Constraints and Assumptions

### Constraints
- **Technology:** Must use SyncFusion JavaScript Diagram component (licensed library)
- **Data Source:** Sales heatmap relies on existing POS data - cannot track actual rack-level sales without POS changes (out of scope)
- **Browser Support:** Modern browsers only (Chrome, Firefox, Safari, Edge) with canvas/SVG support
- **Database:** Per-store database architecture - all floor plan data stored in store-specific database
- **Single Floor:** MVP supports single-floor stores; multi-floor handled as separate floor plans
- **Single Floor Plan per Store:** MVP supports one floor plan per store (future enhancement may allow multiple)
- **Permissions:** Must integrate with existing Owner/Manager/Employee role hierarchy
- **Timeline:** Must be deployable without requiring store owners to take action (no mandatory migration)

### Assumptions
- Store owners have basic computer proficiency for drag-drop interfaces
- Stores have relatively stable physical layouts (rack positions don't change weekly)
- POS category/subcategory data is reasonably accurate and consistently used by employees
- Employees have access to shared computers/tablets in the store for workbook access
- Most stores have print capability for physical floor plan reference
- SyncFusion license is available (community license or commercial)
- Event Management system is deployed and functional for event integration feature

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| SyncFusion learning curve for developers | Medium | Medium | Start with team training on SyncFusion docs; use showcase app as reference; allocate extra time for first feature |
| Floor plan designer too complex for store owners | High | Medium | Provide video tutorials, preset templates, guided first-time flow; user testing before launch |
| Sales data doesn't map cleanly to floor categories | High | Medium | Build category mapping validation tool; show warnings for unmapped categories; fallback to basic view without heatmap |
| Employees don't adopt maintenance tracking | Medium | Medium | Make marking "Done" trivially easy (one tap); show immediate visual feedback; optional gamification (completion stats) |
| Large floor plans cause performance issues | Medium | Low | Set soft limit on rack count with warning; optimize rendering; lazy-load heatmap data |
| Rack template library doesn't match actual store fixtures | Medium | High | Support custom rack creation from day 1; gather research on common fixture types pre-launch |
| Layout activation causes confusion if tasks incomplete | Medium | Medium | Clear UI messaging pre-activation; show incomplete task count; activation proceeds anyway per business rule |
| Print output not readable with category labels | Low | Low | Test print layouts early in development; allow zoom/scale options; optimize label sizing |
| SyncFusion licensing cost changes | Low | Low | Evaluate commercial license terms; document community license requirements |

## Open Questions

- [x] What specific rack/fixture types should be in the initial template library? → **Defined 12 fixture types across 6 categories: Gondola (2), Endcap (1), Freestanding (3), Wall (2), Combo (1), Service (3) - see Feature 2**
- [x] Should categories be assigned at category level or subcategory level? → **Subcategory level (store-specific list; e.g., 113 types for Plato's Closet) with multi-select grouping**
- [x] How should many-to-many category assignments display on heatmap? → **Same sales value shown on each socket (category performance, not rack sales)**
- [x] What maintenance intervals are typical for different rack types? → **Configurable per rack type, store default is 3 days**
- [x] What are the exact canvas dimensions for Small/Medium/Large presets? → **Grid units: Small=40x30 (~1200sqft), Medium=60x50 (~3000sqft), Large=80x70 (~5600sqft)**
- [x] Should there be a maximum number of scheduled layouts per store? → **No cap (unlimited wanted layouts)**
- [x] What notification mechanism for upcoming layout activations? → **Deferred to future phase - no notifications in MVP beyond UI indicators**
- [x] What happens to incomplete tasks after layout activation? → **Tasks remain visible as "post-activation" for tracking, layout activates anyway**

---

## Supporting Research

### Competitive Analysis
**Retail Floor Planning Tools:**
- **SmartDraw / Lucidchart:** General-purpose diagramming, can create floor plans but no retail-specific features, no POS integration, no maintenance tracking, $10-20/user/month
- **Visual Retail Plus:** Enterprise retail planning for large chains, $$$, overkill for resale stores, focused on planogram compliance
- **CB4:** AI-driven retail analytics for large retailers, focused on compliance not planning
- **Excel/Paper diagrams:** Free but no visualization, no integration, lost during staff turnover

**SyncFusion Advantages:**
- Purpose-built diagram component with floor planner showcase
- Symbol palette with drag-drop (matches retail workflow)
- Snap-to-grid, rulers, alignment tools (professional results)
- JSON serialization (easy to store/load)
- Licensed for commercial use with predictable pricing

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

### User Research
Based on requirements gathering sessions with store owners:
- Store owners currently use paper diagrams or mental models for floor layout
- Seasonal transitions (4x/year) and events cause significant floor reorganization stress
- Rack maintenance is ad-hoc; employees don't know which areas need attention
- Staff turnover (60%+ annually) creates constant knowledge gaps
- Event preparation is consistently cited as the most stressful operational task
- Owners want "something visual I can show employees"
- Mobile access is nice-to-have but tablet/desktop is primary use case

### Market Data
- US secondhand apparel market: $43B in 2023, growing 11% annually (ThredUp Resale Report)
- 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 (Bureau of Labor Statistics)
- Stores using visual merchandising see 10-20% sales lift (Retail Minded)
- 73% of retailers say floor layout optimization is a priority (NRF)

---

**Sources:**
- [Syncfusion Floor Planner Blog](https://www.syncfusion.com/blogs/post/floor-planner-diagrams-in-javascript)
- [Syncfusion Floor Planner Showcase](https://www.syncfusion.com/showcase-apps/javascript/floor-planner)
- [Syncfusion JavaScript Diagram Library](https://www.syncfusion.com/javascript-ui-controls/js-diagram)