# Product Requirements Document

## Validation Checklist

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

---

## Product Overview

### Vision

Enable store managers to fully configure all event integrations during the event creation wizard and receive clear, actionable feedback on integration setup success, eliminating the current workflow of creating events with incomplete integrations that require manual follow-up.

### Problem Statement

**Current State:** When creating events with integrations in the Event Management system, users face two critical problems:

1. **Incomplete Configuration UI:** The integration configuration panels in Step 3 of the create wizard only offer basic toggles and minimal options. For example:
   - Comeback Cash requires 15+ configuration fields (earning type, tiers, coupon values, redemption windows), but users can only select an existing event or choose "Create New"
   - SMS requires message template selection, send times, and segment targeting, but users only see two checkboxes
   - Tasks require names, phases, assignments, and priorities, but users only see generic "create prep/follow-up tasks" checkboxes

2. **No Visibility into Results:** After clicking "Create Event," users see only a generic success message ("Event created!") and are redirected to the detail page. There is no confirmation showing:
   - Which integrations were actually created vs. failed
   - What configuration was applied to each integration
   - Whether any integrations need additional setup

**Consequences:**
- Users must navigate to each integration's separate management page to complete setup
- Failed integration creation goes unnoticed until users discover missing functionality
- Store events launch with incomplete promotional coordination
- Support tickets increase as users report "missing" integrations

### Value Proposition

This solution provides a complete, self-contained event creation experience where users can:
- Configure all integration details in one unified wizard without leaving the page
- See immediate, actionable feedback on what was created and what needs attention
- Trust that their promotional event is fully set up and ready to activate

---

## User Personas

### Primary Persona: Store Manager

- **Demographics:** 28-55 years old, manages retail store operations, moderate technical expertise (comfortable with web apps but not developers)
- **Goals:**
  - Set up seasonal promotions efficiently without missing any components
  - Coordinate all promotional systems (signage, SMS, coupons) from one place
  - Know exactly what's configured before an event goes live
- **Pain Points:**
  - Currently must visit 4-5 different pages to fully configure an event
  - Forgets which integrations were enabled after creating an event
  - Discovers missing integrations when customers or staff report issues

### Secondary Personas

**Regional Manager**
- Oversees multiple stores, creates template-based events
- Needs confidence that events are fully configured before deployment
- Values the confirmation modal to verify setup without drilling into details

**Store Staff (View Only)**
- Views event details but doesn't create events
- Benefits from clear integration status indicators on detail page
- Needs to know if an event's integrations are "ready" vs. "pending setup"

---

## User Journey Maps

### Primary User Journey: Complete Event Creation with Integrations

1. **Awareness:** Manager knows an upcoming sale/season requires coordinated promotions across Comeback Cash, signage, and SMS
2. **Consideration:** Manager opens event create wizard, sees Step 3 offers full integration configuration (not just toggles)
3. **Adoption:** Manager enables integrations and configures each one's specific settings inline
4. **Usage:**
   - Completes wizard steps 1-4
   - Clicks "Create Event"
   - Sees confirmation modal with per-integration results
   - Reviews any failures or warnings
   - Clicks "View Event" to see fully-configured event detail page
5. **Retention:** Manager trusts the system because it shows exactly what was created

### Secondary User Journeys

**Journey: Handling Partial Failures**
1. Manager creates event with 4 integrations enabled
2. System shows confirmation: "3 integrations created, 1 failed"
3. Failed integration shows error reason and "Retry" option
4. Manager retries or clicks "Configure Later" to proceed
5. Event detail page shows integration with "Setup Required" badge

**Journey: Template-Based Creation**
1. Manager selects a template with pre-configured integrations
2. Template fills in integration configurations with defaults
3. Manager reviews/modifies configurations as needed
4. Creation proceeds with confidence that all settings are complete

---

## Feature Requirements

### Must Have Features

#### Feature 1: Complete Integration Configuration Forms (Hub and Spoke UI)

- **User Story:** As a store manager, I want to configure all integration settings within the create wizard so that I don't have to visit separate pages to complete setup.
- **Acceptance Criteria:**

  **Hub and Spoke Navigation:**
  - [ ] Step 3 displays a "hub" view showing all 7 integration types as cards
  - [ ] Each card shows: integration name, icon, toggle switch, and configuration status (Not Configured / Configured / Incomplete)
  - [ ] Clicking an enabled integration card opens a configuration "spoke" (sub-screen or modal)
  - [ ] User can configure integrations in any order
  - [ ] "Back to Integrations" button returns to hub from any spoke
  - [ ] Hub shows visual indicator (checkmark) for fully configured integrations

  **Progressive Disclosure in Config Panels:**
  - [ ] Each integration config panel shows required fields first (marked with asterisks)
  - [ ] "Advanced Options" expandable section contains optional fields (collapsed by default)
  - [ ] Sensible defaults pre-filled for optional fields

  **Integration-Specific Config Fields:**
  - [ ] Comeback Cash: side (buy/sales), earning type, earning value/tiers/percentage, coupon value, earning period (relative days), redemption period (relative days), minimum purchase requirements, max coupons, double-up setting, SMS notification toggle
  - [ ] Signage: slide selection (from store/corporate library), tag filtering, display order, duration override
  - [ ] SMS Blast: message template selector, send time picker, customer segment selector, relative days from event
  - [ ] SMS Trigger: trigger type selector, message template, active period (relative days)
  - [ ] Tasks: task name input, phase selector (prep/active/cleanup), relative days, assignment target, priority level
  - [ ] Notes: title input, content textarea, visibility toggle (manager-only), pinned toggle
  - [ ] Backstock: event name, category multi-select, markup adjustment, priority boost toggle

  **Validation Behavior:**
  - [ ] All configuration forms validate inputs on blur and show inline errors
  - [ ] Invalid configurations show inline error messages
  - [ ] Config status updates in real-time as user fills fields

  **Draft vs Schedule Validation:**
  - [ ] When saving as DRAFT: Integrations can be enabled but unconfigured (partial setup allowed)
  - [ ] When SCHEDULING or ACTIVATING: All enabled integrations MUST be fully configured
  - [ ] If scheduling with incomplete integrations, show validation error listing which integrations need configuration
  - [ ] "Configure Now" links in validation error jump directly to incomplete integration's config panel

#### Feature 2: Enhanced API Response with Per-Integration Results

- **User Story:** As a store manager, I want the system to tell me exactly what happened with each integration so that I know what succeeded and what needs attention.
- **Acceptance Criteria:**
  - [ ] API response includes `integrationResults` array with entry per enabled integration
  - [ ] Each integration result includes: type, status (created/failed/skipped), foreignId (if created), error message (if failed)
  - [ ] Overall event creation succeeds even if some integrations fail (partial success)
  - [ ] Response includes summary counts: total enabled, created, failed

#### Feature 3: Post-Creation Confirmation Modal

- **User Story:** As a store manager, I want to see a confirmation summary after creating an event so that I know exactly what was set up.
- **Acceptance Criteria:**
  - [ ] Modal appears after successful event creation (before redirect)
  - [ ] Modal header shows event name and overall status (success/partial success)
  - [ ] Modal body shows list of integrations with individual status indicators
  - [ ] Success items show green checkmark and type name
  - [ ] Failed items show red X, type name, and error message
  - [ ] Modal footer has primary "View Event" button and secondary "Create Another" button
  - [ ] User can dismiss modal to proceed to event detail page
  - [ ] Modal is non-blocking (X button to close)
  - [ ] Modal persists until user takes an action (no auto-close timeout)
  - [ ] If no integrations were enabled, modal shows simple success message without integration list
  - [ ] Modal supports keyboard navigation (Tab, Enter, Escape to close)

#### Feature 4: Integration Status Indicators on Detail Page

- **User Story:** As a store manager, I want to see which integrations need attention on the event detail page so that I can complete any remaining setup.
- **Acceptance Criteria:**
  - [ ] Newly created integrations (< 24 hours) show "New" badge in addition to status badge
  - [ ] Failed integrations show "Setup Required" badge with error context (takes precedence over "New")
  - [ ] Pending integrations show "Pending" badge (awaiting event activation)
  - [ ] Active integrations show "Active" badge (green, currently running)
  - [ ] Completed integrations show "Completed" badge (event has ended)
  - [ ] Integration cards are clickable/expandable to show configuration summary
  - [ ] Each integration card has "Configure" action that opens inline edit panel (not separate page)

#### Feature 5: Edit Mode Integration Configuration

- **User Story:** As a store manager, I want to edit integration configurations on existing events using the same interface as creation so that I have a consistent experience.
- **Acceptance Criteria:**

  **Consistent UI:**
  - [ ] Edit page uses the same hub and spoke UI pattern as create wizard Step 3
  - [ ] Same integration configuration modals/panels used in both create and edit contexts
  - [ ] Same progressive disclosure (required fields + Advanced Options) in both contexts
  - [ ] Same validation rules and inline error display in both contexts

  **Edit-Specific Behavior:**
  - [ ] Edit page shows current integration configurations pre-populated
  - [ ] Can add new integrations to existing event
  - [ ] Can remove/disable existing integrations (with confirmation if integration has data)
  - [ ] Can modify configuration of existing integrations
  - [ ] Changes are saved individually per integration OR all at once (user choice via "Save" vs "Save All")

  **Draft vs Scheduled Edit Validation:**
  - [ ] Editing a DRAFT event: Can leave integrations unconfigured
  - [ ] Editing a SCHEDULED/ACTIVE event: Cannot save if enabled integrations are incomplete
  - [ ] Warning shown if disabling an integration that has already created records (e.g., coupons issued)
  - [ ] Cannot remove integrations from ACTIVE events that are currently in use

### Should Have Features

#### Feature 6: Inline Integration Retry

- **User Story:** As a store manager, I want to retry failed integrations from the confirmation modal so that I don't have to start over.
- **Acceptance Criteria:**
  - [ ] "Retry" button on failed integration items in confirmation modal
  - [ ] Retry attempts creation with same configuration
  - [ ] Modal updates to show new status after retry
  - [ ] Maximum 3 retry attempts before showing "Configure Manually" option

#### Feature 7: Configuration Preview in Review Step

- **User Story:** As a store manager, I want to see a summary of all integration configurations before creating so that I can verify everything is correct.
- **Acceptance Criteria:**
  - [ ] Step 4 (Review) shows expandable section per enabled integration
  - [ ] Each section shows key configuration values in readable format
  - [ ] "Edit" link on each section to jump back to Step 3 hub

### Could Have Features

#### Feature 8: Integration Configuration Templates

- **User Story:** As a store manager, I want to save my integration configurations as templates so that I can reuse them for similar events.
- **Acceptance Criteria:**
  - [ ] "Save as Template" option in integration configuration panels
  - [ ] Template name and description input
  - [ ] Templates appear in dropdown when configuring future events

#### Feature 9: Bulk Integration Actions

- **User Story:** As a store manager, I want to enable/disable all integrations at once so that I can quickly set up common configurations.
- **Acceptance Criteria:**
  - [ ] "Enable All" / "Disable All" toggle at top of integrations hub
  - [ ] Keyboard shortcut for quick toggle

### Won't Have (This Phase)

- **Real-time integration sync status:** Showing live connection status to external systems
- **Integration dependency warnings:** Alerting when integrations conflict (e.g., overlapping Comeback Cash periods)
- **Multi-event integration sharing:** Linking one integration to multiple events
- **Integration analytics in wizard:** Showing historical performance data when configuring

---

## Detailed Feature Specifications

### Feature: Hub and Spoke Integration Configuration

**Description:** Replace the current minimal toggle/checkbox panels in Step 3 with a hub and spoke navigation pattern. The hub displays all 7 integration types as cards with toggle switches. Clicking an enabled card opens a configuration spoke (modal or sub-screen) with the full configuration form using progressive disclosure.

**User Flow (Create):**
1. User navigates to Step 3 (Integrations) - sees hub with 7 integration cards
2. User toggles an integration card to "enabled" - card highlights, shows "Not Configured" status
3. User clicks the enabled card to open configuration spoke
4. Spoke displays required fields prominently, "Advanced Options" collapsed
5. User fills in required fields; system validates on blur
6. User optionally expands "Advanced Options" for additional settings
7. User clicks "Save & Return" to go back to hub - card now shows "Configured" with checkmark
8. User repeats for other integrations as needed (any order)
9. User clicks "Next" to proceed to Step 4 (Review)
10. If saving as Draft: proceeds even with unconfigured integrations
11. If Scheduling: system validates all enabled integrations are configured; blocks with error if not

**User Flow (Edit):**
1. User opens event detail page, clicks "Edit Integrations" button
2. Same hub view appears with current integrations pre-populated
3. Enabled integrations show current config status (Configured/Incomplete)
4. User can toggle new integrations on, configure, or modify existing
5. User clicks "Save Changes" - same draft vs scheduled validation applies
6. Confirmation shows what changed (added/modified/removed integrations)

**Business Rules:**

**Comeback Cash:**
- Rule 1: If earning type is "tiered", tier configuration section becomes required
- Rule 2: If earning type is "percentage", percentage field becomes required
- Rule 3: Buy-side events can only use "flat" earning type
- Rule 4: Earning period must end before or when redemption period starts
- Rule 5: Coupon value must be positive
- Rule 6: All "relative days" are calculated from event start date (negative = before start, positive = after start)
- Rule 7: Redemption relative days are calculated from event end date

**Signage:**
- Rule 1: At least one slide or one tag must be selected
- Rule 2: Duration must be positive if specified
- Rule 3: Display order must be non-negative if specified

**SMS:**
- Rule 1: Message template is required for both blast and trigger types
- Rule 2: Send time must be in HH:MM format for blasts
- Rule 3: Relative days must be between -365 and 365

**Tasks:**
- Rule 1: Task name is required and max 255 characters
- Rule 2: Phase must be prep, active, or cleanup
- Rule 3: Priority must be high, normal, or low

**Notes:**
- Rule 1: Title is required and max 255 characters
- Rule 2: Content is required

**Backstock:**
- Rule 1: Event name is required and max 100 characters
- Rule 2: Markup adjustment must be between -100 and 100

**Edge Cases:**
- Scenario 1: User enables integration but doesn't configure it, then clicks "Save as Draft" → Allowed; integration saved with "unconfigured" status
- Scenario 2: User enables integration but doesn't configure it, then clicks "Schedule" → Blocked; error message with "Configure Now" link
- Scenario 3: User enables integration, fills fields, then disables it → Configuration is preserved in case they re-enable
- Scenario 4: Template pre-fills integration with invalid data → System shows validation errors when spoke is opened
- Scenario 5: Network error loading slide/template options → Show "Retry loading" button with fallback to manual ID entry
- Scenario 6: All 7 integrations enabled simultaneously → System handles all; no maximum limit
- Scenario 7: Session timeout during wizard → Show "Session expired" message with option to save draft locally
- Scenario 8: Browser back button pressed in spoke → Return to hub; preserve entered data
- Scenario 9: User tries to navigate away from spoke with unsaved changes → Prompt "You have unsaved changes. Discard?"
- Scenario 10: Edit mode - user disables integration with existing data (e.g., issued coupons) → Warning: "This integration has X records. Disabling will not delete them but will stop future actions."
- Scenario 11: Edit mode - user tries to remove integration from ACTIVE event → Blocked if integration is currently in use; allowed if event is still in build-up phase

---

## Success Metrics

### Key Performance Indicators

- **Adoption:** 80% of events created with integrations use the full configuration UI (vs. requiring post-creation setup)
- **Engagement:** Average time in Step 3 increases by 30% (indicates users are configuring, not skipping)
- **Quality:** Integration creation success rate > 95% (vs. current unknown failure rate)
- **Business Impact:** Support tickets for "missing integrations" decrease by 50%

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `event_wizard_step_completed` | step_number, integrations_enabled[], time_on_step | Measure engagement with Step 3 |
| `integration_config_opened` | integration_type, is_template_prefilled | Track which integrations are configured |
| `integration_config_validated` | integration_type, validation_passed, error_fields[] | Identify common configuration mistakes |
| `event_created` | event_id, integrations_attempted, integrations_succeeded, integrations_failed | Measure overall success rate |
| `confirmation_modal_action` | action (view_event, create_another, retry, dismiss), failed_count | Understand user behavior after creation |
| `integration_retry_attempted` | integration_type, retry_number, success | Track retry feature effectiveness |

---

## Constraints and Assumptions

### Constraints

- Must work within existing Slim 2.6.2 / Twig 1.x framework
- Must maintain mobile-responsive design for tablet use
- Integration adapters already exist and define validation rules (we expose their requirements in UI)
- SweetAlert 1.x is the notification library (no migration to SweetAlert2)

### Assumptions

- Users have basic familiarity with each integration type from using standalone pages
- Existing adapter validation logic is correct and complete
- Event creation can succeed with partial integration failures (already supported by IntegrationService)
- Users prefer inline configuration over navigating to separate setup pages

---

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Configuration forms overwhelm users | Medium | Medium | Progressive disclosure: show "Quick Setup" with essential fields, "Advanced" expandable for optional fields |
| Slow page load with all integration forms | Medium | Low | Lazy-load integration config panels when expanded; cache slide/template lists |
| Validation rule changes in adapters break UI | High | Low | UI validation mirrors adapter rules; add adapter version checking |
| Users skip reading confirmation modal | Medium | Medium | Use visual hierarchy: red badges for failures, require acknowledgment for failed items |

---

## Open Questions

All questions resolved through research and user input:

- [x] Scope decision: Full integration configuration UI (resolved: user selected this option)
- [x] Integration configuration requirements: Documented from adapter analysis
- [x] Confirmation modal UX patterns: Researched and documented
- [x] Existing detail page patterns: Analyzed and documented

---

## Supporting Research

### Competitive Analysis

Event management platforms (Eventbrite, Splash, Bizzabo) all provide:
- Single-page event creation with integrated settings
- Real-time validation during form completion
- Post-creation summary with actionable next steps
- Status indicators for connected integrations

Our current implementation lacks the inline configuration and confirmation feedback that users expect from modern event management tools.

### User Research

Analysis of current workflow reveals:
- Current create.html has only basic toggles in Step 3 (checkboxes, single dropdown)
- Adapters require 5-15 configuration fields each
- No error handling or feedback for failed integration creation
- Users must visit separate pages to complete integration setup

### Market Data

- 73% of users expect real-time form validation (Baymard Institute)
- Post-action confirmation modals increase user confidence by 40% (NNGroup)
- Multi-step wizards with progress indication reduce abandonment by 25%