# 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] Implementation details deferred to SDD (product-level semantics only)
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
A centralized store configuration hub in the admin panel that empowers store managers to manage store hours, operational settings, and other store-level configurations - eliminating guesswork and enabling consistent scheduling decisions system-wide.

### Problem Statement
**Currently**, store hours are stored in browser localStorage within the scheduling calendar, meaning:
1. **No persistence**: Store hours are lost when browsers clear cache or users change devices
2. **No system-wide availability**: Other parts of the system cannot reliably reference store hours
3. **Manual entry required every time**: Users must re-enter open/close times repeatedly
4. **No audit trail**: Changes to store hours aren't tracked or logged
5. **Scheduling conflicts**: Shifts can be created outside store operating hours with no visibility/warnings
6. **Scattered configuration**: Store-level settings are spread across multiple pages with no unified access point

**Evidence**: The recent Spec 013 (Employee Scheduling) implementation stores store hours in localStorage (scheduling/calendar.html, lines 48-75), highlighting the gap in persistent store hours management.

### Value Proposition
Store Configuration provides store administrators with:
- **Single source of truth**: One place to manage all store-level settings
- **Persistent store hours**: Database-stored hours available system-wide
- **Scheduling integration**: Display operating hours in the scheduler and enable future validation against store hours
- **Consistent operations**: Reduce manual re-entry and improve data accuracy
- **Future extensibility**: Foundation for additional store-level configuration features

## Key Definitions & Non-Obvious Requirements

- **Canonical timezone:** The store's configured timezone is the single source of truth. UI and APIs must treat all date-only values (e.g., `YYYY-MM-DD`) as dates in the store timezone, regardless of the user's browser timezone.
- **Hours are wall-clock times:** Store hours represent local "open" and "close" times, not full timestamps. They are interpreted relative to the store timezone and a specific calendar date when used in scheduling contexts.
- **This PRD does not enforce shift blocking:** This phase focuses on persistent configuration + display/availability. Hard enforcement ("prevent creating shifts outside hours") is explicitly deferred.
- **Migration from localStorage:** Existing calendar localStorage values must not silently override persisted configuration. If the database has no stored hours yet and localStorage does, the UI should guide the user to save/import (or discard) rather than creating dual sources of truth.

## User Personas

### Primary Persona: Store Manager
- **Demographics:** Age 28-45, retail management background, moderate technical expertise
- **Role:** Oversees daily store operations, staff scheduling, and administrative tasks
- **Goals:**
  - Quickly configure store hours when they change (seasonal, holiday adjustments)
  - Ensure scheduling system reflects accurate operating hours
  - Minimize time spent on administrative configuration
  - Have reliable settings that persist across sessions
- **Pain Points:**
  - Having to re-enter store hours in the scheduling calendar repeatedly
  - No central place to view/edit store operational settings
  - Uncertainty about whether current settings match actual operations
  - No visibility into when settings were last changed

### Secondary Personas

#### Assistant Manager / Shift Lead
- **Demographics:** Age 22-35, retail experience, lower admin access
- **Role:** Assists with scheduling, may not have full configuration access
- **Goals:** View current store hours when planning shifts, understand operational constraints
- **Pain Points:** Needs to ask manager for store hours information, no self-service access to view configuration

#### Regional/District Manager
- **Demographics:** Age 35-55, multi-store oversight, high technical proficiency
- **Role:** Oversees multiple stores, reviews configurations across locations
- **Goals:** Ensure consistency across stores, audit store configurations, quick access across typeNums
- **Pain Points:** No way to see store hours at a glance across stores in their group

## User Journey Maps

### Primary User Journey: Setting Store Hours

1. **Awareness:** Store manager realizes operating hours need to change (seasonal, holiday, policy update)
2. **Navigation:** Manager navigates to Admin Panel → Store Settings → Store Hours
3. **Review:** Manager views current hours configuration (open time, close time, timezone)
4. **Modification:** Manager updates store open/close times using time picker controls
5. **Confirmation:** System validates input and shows preview of changes
6. **Save:** Manager saves changes; success message confirms update
7. **Verification:** Manager sees updated hours reflected in scheduling calendar immediately
8. **Audit:** Changes are logged for future reference

### Secondary User Journey: Holiday Hours Configuration

1. **Awareness:** Upcoming holiday requires modified hours
2. **Navigation:** Manager accesses Store Hours configuration page
3. **Holiday Selection:** Manager identifies specific dates for modified hours
4. **Override Entry:** Manager enters opening/closing times for holiday dates
5. **System Integration:** Holiday hours automatically apply in scheduling
6. **Staff Communication:** Manager can reference configured hours when communicating with team

### Tertiary User Journey: Viewing Store Configuration (Read-Only)

1. **Need:** Assistant manager needs to verify store operating hours for scheduling
2. **Access:** User navigates to Store Configuration (view permission)
3. **Information:** User sees current store hours, timezone, and any special dates
4. **Usage:** User applies this information when creating or reviewing schedules

## Feature Requirements

### Must Have Features

#### Feature 1: Store Hours Configuration
- **User Story:** As a store manager, I want to set my store's opening and closing times so that the scheduling system knows when my store operates.
- **Acceptance Criteria:**
  - [ ] User can set store opening time (time picker, 24-hour or 12-hour format)
  - [ ] User can set store closing time (time picker, 24-hour or 12-hour format)
  - [ ] System validates closing time is after opening time
  - [ ] Changes persist to database (not localStorage)
  - [ ] Scheduling calendar reflects updated hours immediately after save
  - [ ] Current hours display clearly on page load
  - [ ] If database hours are not set yet but localStorage hours exist, user is prompted to save/import them (or discard) to avoid dual sources of truth

#### Feature 2: Store Timezone Display
- **User Story:** As a store manager, I want to see and confirm my store's timezone so that all time-based settings use the correct local time.
- **Acceptance Criteria:**
  - [ ] Current store timezone displays prominently (e.g., "America/Los_Angeles")
  - [ ] Timezone is read from existing store configuration
  - [ ] All time inputs clearly indicate they are in store's local time
  - [ ] Times are stored and displayed in store's timezone context
  - [ ] If user/browser timezone differs from store timezone, the UI still displays the same store hours (no "day drift" or offset confusion)

#### Feature 3: Store Configuration Admin Page
- **User Story:** As a store manager, I want a dedicated configuration page so that I have one place to manage store-level settings.
- **Acceptance Criteria:**
  - [ ] Page accessible via Admin sidebar navigation
  - [ ] Page requires appropriate permission (`uri_store_settings`)
  - [ ] Page displays store identity (name, typeNum, address)
  - [ ] Layout follows existing admin page patterns (card-based, Bootstrap 5)
  - [ ] Page is mobile-responsive

#### Feature 4: Save and Reset Functionality
- **User Story:** As a store manager, I want to save my changes and reset to previous values so that I can confidently make and undo configuration changes.
- **Acceptance Criteria:**
  - [ ] Save button persists all changes to database
  - [ ] Reset button restores form to last-saved state
  - [ ] Success toast notification on successful save
  - [ ] Error notification with clear message on failure
  - [ ] Unsaved changes warning if navigating away
  - [ ] After a successful save, any other open scheduling/config screens reflect the new hours without requiring manual data entry

### Should Have Features

#### Feature 5: Daily Hours by Day of Week
- **User Story:** As a store manager, I want to set different hours for different days so that weekend or weekday variations are captured.
- **Acceptance Criteria:**
  - [ ] Individual open/close times per day of week (Sun-Sat)
  - [ ] Option to "copy to all days" for quick setup
  - [ ] Visual indication of days with non-standard hours
  - [ ] Ability to mark specific days as "closed"

#### Feature 6: Holiday Hours Override
- **User Story:** As a store manager, I want to set special hours for specific dates so that holidays and special events have correct operating times.
- **Acceptance Criteria:**
  - [ ] Add holiday date with custom open/close times
  - [ ] Mark holiday as "closed" (store not operating)
  - [ ] View list of configured holiday overrides
  - [ ] Remove/edit existing holiday overrides
  - [ ] Holiday overrides take precedence over regular hours

### Could Have Features

#### Feature 7: Hours Change Audit Log
- **User Story:** As a store manager, I want to see who changed store hours and when so that I can track configuration history.
- **Acceptance Criteria:**
  - [ ] Log entry for each configuration change
  - [ ] Timestamp of change
  - [ ] User who made the change
  - [ ] Before/after values for changed fields
  - [ ] View last 10-20 changes on configuration page

#### Feature 8: Bulk Configuration (Multi-Store)
- **User Story:** As a regional manager, I want to view store hours across my stores so that I can ensure consistency.
- **Acceptance Criteria:**
  - [ ] Dashboard showing hours for all stores in group
  - [ ] Quick navigation to individual store configuration
  - [ ] Highlight stores with unusual hours

### Won't Have (This Phase)

- **Timezone Editing**: Timezone is set at store creation, not configurable here (requires system-wide impact assessment)
- **Operating Schedule Templates**: Predefined templates (mall hours, standalone hours) - deferred to future phase
- **Integration Settings**: QuickBooks, WhenIWork, etc. configuration - separate existing pages
- **SMS/Communication Settings**: Already managed elsewhere in system
- **Employee/Team Member Configuration**: Managed via Team Members page (Spec 014)
- **Shift Validation Enforcement**: Backend scheduling validation against store hours (separate implementation)

## Detailed Feature Specifications

### Feature: Store Hours Configuration

**Description:** A form section allowing store managers to define when their store opens and closes on a typical day. These hours serve as the default operating schedule and integrate with the scheduling system.

**User Flow:**
1. User navigates to Store Configuration page
2. System loads current store hours from database (or shows defaults)
3. User views current open/close times displayed in time input fields
4. User clicks on opening time field - time picker appears
5. User selects new opening time
6. User clicks on closing time field - time picker appears
7. User selects new closing time (must be after opening)
8. User clicks "Save" button
9. System validates times (close > open)
10. System saves to database via API call
11. System displays success toast notification
12. System updates scheduling calendar if open in another tab

**Business Rules:**
- Rule 1: Store closing time must be after store opening time
- Rule 2: Times are always stored and displayed in the store's configured timezone
- Rule 3: Default hours for new stores: 9:00 AM - 9:00 PM local time
- Rule 4: Hours are stored as time-of-day values (not full timestamps) and are interpreted as store-local wall-clock times
- Rule 5: Changes take effect immediately after save (no delayed activation)
- Rule 6: Only users with `uri_store_settings` permission can modify hours
 - Rule 7: Date-only values used by the UI/API (e.g., "weekStart") are interpreted in the store timezone, not the user's browser timezone

**Edge Cases:**
- Scenario 1: User enters closing time before opening time → Expected: Validation error message, save prevented
- Scenario 2: User navigates away with unsaved changes → Expected: Browser confirmation dialog
- Scenario 3: Network error during save → Expected: Error toast with retry option, form state preserved
- Scenario 4: Two admins edit simultaneously → Expected: Last save wins, consider optimistic locking in future
- Scenario 5: Store operates past midnight (opens 8PM, closes 2AM) → Expected: Not supported; validation error shown. Stores must have same-day operating hours (open and close within same calendar day).
- Scenario 6: Store operates 24 hours → Expected: Supported via an explicit configuration pattern (define whether this is `00:00–23:59` or a dedicated "open 24 hours" toggle in future phases)

## Success Metrics

### Key Performance Indicators

- **Adoption:** 80% of stores configure store hours within 30 days of feature launch
- **Engagement:** Average time to complete initial store hours setup < 2 minutes
- **Quality:** <1% error rate on save operations
- **Business Impact:** Reduction in scheduling conflicts due to unknown store hours (qualitative initially)

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `store_config_page_view` | typeNum, store_timezone, user_role | Track page adoption and usage frequency |
| `store_hours_saved` | typeNum, store_timezone, open_time, close_time, changed_fields[] | Track configuration changes |
| `store_hours_save_error` | typeNum, store_timezone, error_type, error_message | Track issues for debugging |
| `store_hours_reset` | typeNum, store_timezone | Track how often users use reset functionality |
| `store_config_navigation` | typeNum, source_page | Track how users find configuration page |

---

## Constraints and Assumptions

### Constraints
- **Permission system**: Must use existing permission framework (`uri_store_settings`)
- **Database architecture**: Store-level configuration is stored centrally (not in per-store operational databases)
- **Framework**: Bootstrap 5.3.3, PHP 8.x, Slim 2.6.2
- **Browser support**: Modern browsers (Chrome, Firefox, Safari, Edge - latest 2 versions)
- **No breaking changes**: Cannot modify existing scheduling behavior without coordination

### Assumptions
- Users will have `uri_store_settings` permission if they need to modify store hours
- Existing store timezone configuration is accurate and maintained
- Most stores operate with consistent daily hours (same open/close each day)
- Holiday hours are infrequent (typically < 15 dates per year)

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Cache invalidation failure | High - stale hours shown | Low | Clear/refresh cached store configuration after save; add refresh mechanism |
| Scheduling calendar localStorage conflict | Medium - dual sources of truth | Medium | Migration path to remove localStorage usage |
| Timezone confusion | Medium - incorrect schedule times | Low | Clear timezone display on all time inputs |
| Hours model too simple for real stores | Medium - cannot represent closed days/variable hours | Medium | Prioritize Feature 5 (per-day hours) quickly if adoption feedback indicates it's necessary |
| Permission misconfiguration | High - unauthorized access | Low | Follow existing permission patterns exactly |
| Browser compatibility issues | Low - form doesn't work | Low | Standard Bootstrap 5 components, tested browsers |

## Open Questions

- [x] Should store hours support overnight operation (opens evening, closes next morning)? → **RESOLVED: No.** Same-day only. Store hours must be within the same calendar day.
- [ ] Should the scheduling calendar automatically validate new shifts against store hours? → Deferred to separate feature
- [x] Should closed days (e.g., Sunday closed) be supported in the first release, given many stores vary hours by day? → **RESOLVED: Yes.** Supported via per-day `isClosed` flag in `storeOperatingHours` table.
- [x] What is the correct navigation placement/name in the admin sidebar (e.g., "Store Settings", "Store Configuration", or "Scheduling Settings") to match existing IA? → **RESOLVED:** Use existing "Store Configuration" page under "Store Settings" section. Overwrite the current placeholder page.
- [x] Is `uri_store_settings` the correct permission name, or should this align with existing scheduling config permissions? → **RESOLVED: Yes.** `uri_store_settings` permission exists and is correct.
- [ ] What's the rollout strategy - all stores at once or phased? → Typically immediate availability
- [ ] Are there stores with multiple operating zones (e.g., cafe inside store with different hours)? → Not in scope for this phase

---

## Supporting Research

### Competitive Analysis
- **WhenIWork**: Allows business hours configuration per location, displays in scheduler
- **Homebase**: Store hours are core configuration, warns when shifts exceed hours
- **Square Staff**: Simple open/close per day, integrated with POS hours

### User Research
- Scheduling implementation (Spec 013) revealed store hours stored in localStorage - user feedback indicated desire for persistent configuration
- Current pattern requires re-entry of hours on each session/device

### Market Data
- Standard retail POS and scheduling systems treat store hours as foundational configuration
- Multi-location retailers expect per-store hours configuration as baseline feature