# 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
Transform the Survey Results page into a modern, data-driven dashboard that empowers store managers to quickly identify service quality trends and take action to improve customer experience.

### Problem Statement
The current Survey Results page suffers from multiple UX/UI issues that hinder effective decision-making:

1. **Visual Inconsistency**: The page uses outdated Bootstrap panel styles that don't match the modernized backstock pages, creating a fragmented brand experience
2. **Poor Data Visualization**: Charts are embedded in gray "well" containers with inconsistent sizing, making it difficult to compare metrics at a glance
3. **Information Overload**: The data table displays 11 columns on a single horizontal row, forcing users to scroll horizontally and lose context
4. **Mobile Unfriendly**: The page is nearly unusable on mobile devices - charts overflow, tables require extensive horizontal scrolling, and the date picker is awkward to use
5. **Buried Insights**: Key metrics like "Average Satisfaction Rating" are buried in a small box rather than prominently displayed as a key performance indicator
6. **Poor Action Hierarchy**: The AI Analysis section has equal visual weight despite being a powerful feature, and lacks clear visual affordance

### Value Proposition
By redesigning the Survey Results page to match the modern backstock design system, store managers will be able to:
- Instantly understand customer satisfaction trends with prominent KPI cards
- Quickly identify service issues through improved data visualization
- Access and act on survey data from any device (mobile-first)
- Generate AI insights with clear visual feedback and results
- Navigate survey results efficiently with improved table UX

## User Personas

### Primary Persona: Store Manager (Sarah)
- **Demographics:** 28-45 years old, retail management experience, moderate technical expertise, uses desktop and mobile devices throughout the day
- **Goals:**
  - Monitor overall customer satisfaction scores
  - Identify employees who need additional training
  - Track how customers discover the store (marketing attribution)
  - Generate reports for ownership/stakeholders
- **Pain Points:**
  - Currently spends too much time scrolling through tables to find patterns
  - Can't quickly check survey results on her phone between tasks
  - Has to export data to Excel to create presentable reports
  - Struggles to explain data to team members due to poor visualization

### Secondary Personas

#### Store Owner (Mike)
- **Demographics:** 45-60 years old, business owner, limited time for detailed analysis
- **Goals:** Quick health check on customer satisfaction across stores, ROI on marketing channels
- **Pain Points:** Wants high-level KPIs without diving into details, needs mobile access

#### Regional Manager (Jessica)
- **Demographics:** 35-50 years old, oversees multiple stores, data-driven decision maker
- **Goals:** Compare survey performance across stores, identify training opportunities
- **Pain Points:** No easy way to compare stores, has to look at each store individually

## User Journey Maps

### Primary User Journey: Daily Survey Review

1. **Awareness:** Manager notices a customer complaint or wants to do their daily check-in on service quality
2. **Consideration:** Opens the Survey Results page from the admin sidebar
3. **Adoption:** Scans the KPI cards for overall satisfaction and response counts
4. **Usage:**
   - Reviews chart visualizations for trends in greeting, process explanation, and pass explanation
   - Checks the "Where did you hear about us?" chart for marketing insights
   - Optionally generates AI analysis for deeper insights
   - Drills into specific survey responses in the data table
5. **Retention:** Bookmarks the page, uses date range picker to compare periods, shares AI insights with team

### Secondary User Journeys

#### Journey: Mobile Quick Check
1. Manager is on the sales floor and wants to quickly check today's satisfaction score
2. Opens Survey Results on mobile phone
3. Instantly sees KPI cards with current satisfaction rating
4. Can tap to expand charts if needed
5. Returns to work with confidence in service levels

#### Journey: Employee Performance Review
1. Manager preparing for employee review meeting
2. Filters survey results by date range around employee's shifts
3. Reviews buyer/sorter columns for specific employee feedback
4. Uses AI analysis to identify patterns
5. Documents findings for the review

## Feature Requirements

### Must Have Features

#### Feature 1: Modern Page Header with Quick Stats
- **User Story:** As a store manager, I want to see key metrics immediately when I load the page so that I can quickly assess customer satisfaction levels
- **Acceptance Criteria:**
  - [ ] Page header follows backstock design pattern with icon, title "Post-Buy Survey Results", and subtitle
  - [ ] Quick search input in header for filtering surveys (matches backstock pattern)
  - [ ] Date range picker button styled consistently with backstock action buttons
  - [ ] Responsive layout that stacks appropriately on mobile

#### Feature 2: KPI Stats Grid
- **User Story:** As a store manager, I want to see key performance indicators in prominent stat cards so that I can instantly understand our service quality
- **Acceptance Criteria:**
  - [ ] Stats grid displays 4-6 stat cards in responsive grid (matches backstock pattern)
  - [ ] Cards show: Total Responses, Avg Satisfaction, Greeted Immediately %, Process Explained %, Top Marketing Source, Response Rate
  - [ ] Each card has appropriate color coding (success for good metrics, warning/danger for concerning metrics)
  - [ ] Cards are clickable to filter related data
  - [ ] Grid responsive: 6-col on desktop, 3-col on tablet, 2-col on mobile

#### Feature 3: Redesigned Chart Section
- **User Story:** As a store manager, I want to view survey data in clean, modern charts so that I can quickly identify trends and issues
- **Acceptance Criteria:**
  - [ ] Charts contained in modern card containers (white background, subtle border, rounded corners)
  - [ ] Chart titles are clear and descriptive
  - [ ] Horizontal bar charts replaced with more readable donut/pie charts for categorical data
  - [ ] Charts maintain aspect ratio and don't overflow on mobile
  - [ ] Average satisfaction rating prominently displayed with large emoji and rating
  - [ ] Charts use brand color palette (purple primary, semantic colors for good/bad responses)

#### Feature 4: AI Analysis Section Redesign
- **User Story:** As a store manager, I want the AI Analysis feature to be visually prominent and easy to use so that I can quickly generate insights
- **Acceptance Criteria:**
  - [ ] AI Analysis section uses modern card styling
  - [ ] Generate button uses primary gradient style with clear call-to-action
  - [ ] Loading state shows progress indicator with helpful message
  - [ ] Results tabs redesigned to match backstock tab styling
  - [ ] Each analysis section clearly labeled with helpful context
  - [ ] Mobile-friendly tab navigation (scrollable or collapsible)

#### Feature 5: Modern Data Table
- **User Story:** As a store manager, I want to browse survey responses in a clean, scannable table so that I can review individual customer feedback
- **Acceptance Criteria:**
  - [ ] Table wrapped in modern card container matching backstock style
  - [ ] Reduced visual noise - cleaner borders, proper spacing
  - [ ] Star ratings displayed as visual stars (not just numbers)
  - [ ] Customer names and Buy IDs are clickable links (styled in brand purple)
  - [ ] Expandable row detail for comments and additional info
  - [ ] Column visibility toggle to show/hide columns
  - [ ] Export buttons (Excel, PDF, Print) match backstock styling
  - [ ] Pagination styled to match backstock pattern
  - [ ] Table horizontally scrollable on mobile with sticky first column

#### Feature 6: Mobile-First Responsive Layout
- **User Story:** As a store manager, I want to access survey results on my mobile device so that I can check data while on the sales floor
- **Acceptance Criteria:**
  - [ ] All content readable without horizontal scrolling on mobile
  - [ ] Stat cards stack appropriately on small screens
  - [ ] Charts resize and remain readable on mobile
  - [ ] Table shows essential columns on mobile, hides secondary columns
  - [ ] Touch-friendly tap targets (minimum 44px)
  - [ ] Date picker optimized for mobile interaction

### Should Have Features

#### Feature 7: Quick Filters
- **User Story:** As a store manager, I want quick filter buttons so that I can segment data without navigating complex controls
- **Acceptance Criteria:**
  - [ ] Filter chips for: Low Ratings (1-2), Medium (3), High (4-5)
  - [ ] Filter by marketing source with dropdown
  - [ ] Filter by employee (buyer/sorter)
  - [ ] Active filters shown as dismissible badges
  - [ ] Clear all filters button

#### Feature 8: Trend Indicators
- **User Story:** As a store manager, I want to see trend indicators on KPI cards so that I know if metrics are improving or declining
- **Acceptance Criteria:**
  - [ ] Each stat card shows trend arrow (up/down/flat) comparing to previous period
  - [ ] Percentage change displayed
  - [ ] Green for improvement, red for decline, gray for flat
  - [ ] Tooltip explains comparison period

### Could Have Features

#### Feature 9: Survey Response Quick Actions
- **User Story:** As a store manager, I want to take quick actions on survey responses so that I can follow up efficiently
- **Acceptance Criteria:**
  - [ ] Flag for follow-up button on each row
  - [ ] Quick note/tag functionality
  - [ ] Link to send follow-up message to customer

#### Feature 10: Customizable Dashboard
- **User Story:** As a store manager, I want to customize which metrics are shown so that I can focus on what matters most to my store
- **Acceptance Criteria:**
  - [ ] Drag-and-drop reordering of stat cards
  - [ ] Show/hide specific charts
  - [ ] Save preferences per user

### Won't Have (This Phase)

- **Multi-store comparison view** - Requires additional API work and is better suited for a dedicated reporting module
- **Real-time survey notifications** - Would require WebSocket integration, out of scope for this redesign
- **Survey question customization** - This is a settings feature, not a results viewing feature
- **PDF report generation** - Complex feature that deserves its own specification
- **Historical trend charts** - Requires significant data aggregation work, planned for future phase

## Detailed Feature Specifications

### Feature: KPI Stats Grid
**Description:** A responsive grid of stat cards that displays key performance indicators at a glance. Each card shows a metric with an icon, value, label, and optional trend indicator. Cards use semantic colors to indicate positive/negative performance.

**User Flow:**
1. User loads Survey Results page
2. System calculates KPIs from survey data within selected date range
3. Stats grid displays with 6 cards
4. User can click a card to filter the table by that metric
5. User changes date range
6. System recalculates and updates all stat cards

**Business Rules:**
- Rule 1: Satisfaction rating below 3.5 shows in orange (warning), below 3.0 shows in red (danger)
- Rule 2: "Greeted Immediately" percentage below 70% shows warning color
- Rule 3: Stats calculate based on currently selected date range
- Rule 4: If no surveys in date range, cards show "N/A" with muted styling
- Rule 5: Clicking a stat card applies a filter to the data table

**Edge Cases:**
- Scenario 1: No surveys in selected date range → Expected: Cards show "N/A" or "0" with empty state styling
- Scenario 2: Date range spans multiple years → Expected: System handles large datasets gracefully, potentially with loading state
- Scenario 3: User has no permission to view certain data → Expected: Cards show only permitted data

### Feature: Modern Data Table
**Description:** A redesigned DataTables implementation that matches the backstock styling, with improved mobile responsiveness and clearer information hierarchy.

**User Flow:**
1. User scrolls to Survey Results table
2. Table loads with default 50 entries per page
3. User can search across all columns
4. User clicks row expand button to see full comments
5. User can sort by clicking column headers
6. User can paginate through results

**Business Rules:**
- Rule 1: Default sort is by date descending (newest first)
- Rule 2: Star ratings display as visual stars, not numbers
- Rule 3: Empty comments don't show expand button
- Rule 4: Customer names link to customer profile
- Rule 5: Buy IDs link to buy transaction
- Rule 6: Mobile view prioritizes: Date, Customer, Satisfaction, Source

**Edge Cases:**
- Scenario 1: Very long customer names → Expected: Truncate with ellipsis, full name in tooltip
- Scenario 2: Missing employee data → Expected: Show "N/A" in buyer/sorter columns
- Scenario 3: Survey with no rating → Expected: Show "NR" in satisfaction column

## Success Metrics

### Key Performance Indicators

- **Adoption:** 80% of existing Survey Results page users continue using the redesigned page within 2 weeks of launch
- **Engagement:** Average time on page decreases by 20% (indicates users finding information faster)
- **Quality:** Mobile bounce rate decreases by 30% (indicates improved mobile experience)
- **Business Impact:** AI Analysis feature usage increases by 50% due to improved visibility

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| survey_results_page_view | typeNum, date_range, device_type | Track page visits and device distribution |
| stat_card_click | card_type, filter_applied | Understand which KPIs users care about |
| chart_interaction | chart_type, action | Track engagement with visualizations |
| ai_analysis_generated | typeNum, survey_count, duration | Track AI feature adoption |
| table_filter_applied | filter_type, filter_value | Understand common filtering patterns |
| table_row_expanded | has_comments | Track engagement with detailed feedback |
| date_range_changed | from_date, to_date, preset_used | Understand common analysis periods |
| survey_export | format_type | Track export usage |

---

## Constraints and Assumptions

### Constraints
- Must maintain backward compatibility with existing survey data structure
- Must use existing BuyerKiosk CSS framework (backstock-home.css patterns)
- Must work within current PHP/Slim/Twig architecture
- Cannot change survey submission process (only viewing)
- Should not require database schema changes

### Assumptions
- Users have access to modern browsers (Chrome 90+, Safari 14+, Firefox 88+, Edge 90+)
- Existing Chart.js library is adequate for new visualizations
- DataTables library can be styled to match new design
- Mobile users accept some reduced functionality (e.g., fewer visible columns)
- Existing API endpoints provide sufficient data for all planned features

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Users resist change to familiar interface | Medium | Medium | Provide toggle to switch between old/new views during transition period |
| Performance degradation with large datasets | High | Low | Implement pagination, lazy loading of charts, server-side processing for tables |
| Mobile experience still inadequate | High | Medium | Extensive mobile testing, prioritize core metrics over feature parity |
| CSS conflicts with existing styles | Medium | Medium | Scope all new styles under `.survey-results-page` class |
| Chart.js customization limitations | Low | Low | Consider alternative charting library if needed (ApexCharts) |

## Open Questions

- [x] Should we maintain the current horizontal bar chart style or switch to donut/pie charts? → **Decision: Use horizontal bar charts for consistency with backstock, but with updated styling**
- [x] What date range presets are most useful? → **Decision: Yesterday, Last 7 Days, Last 30 Days, Last 90 Days, This Month, Last Month, Year to Date**
- [x] Should AI Analysis be collapsed by default? → **Decision: No, keep visible but below the fold**
- [x] Which columns should be visible on mobile? → **Decision: Date, Customer, Satisfaction, Source (4 columns)**

---

## Supporting Research

### Competitive Analysis
- **Typeform Analytics**: Clean dashboard with prominent KPIs, excellent mobile experience, inspired our stat card approach
- **SurveyMonkey**: Strong data visualization, but can be overwhelming; we'll focus on simplicity
- **Google Forms**: Minimal but effective, inspired our clean chart styling

### User Research
- Feedback from store managers indicates frustration with current mobile experience
- Request for "at-a-glance" metrics without scrolling
- AI Analysis feature underutilized due to poor visibility
- Export functionality used frequently for reports

### Market Data
- 73% of store managers access admin tools from mobile devices at least weekly (industry benchmark)
- Survey response rates correlate with quick feedback loops - faster access to results encourages action
- Mobile-first design has become standard expectation for business dashboards