# Product Requirements Document
# 035 - Premium Scheduling Module

## 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
Establish a sustainable premium revenue stream by packaging BuyerKiosk's native scheduling engine, team chat, and AI scheduling features as a $30/month add-on, while keeping basic team management free for all stores.

### Problem Statement
BuyerKiosk has invested significant development effort into a full-featured scheduling engine, team chat system, and AI-powered schedule generation. However, all of these features are currently bundled with the base product at no additional charge. This creates two problems:

1. **No revenue differentiation** — Stores using advanced scheduling, chat, and AI features generate the same revenue as stores that only need basic employee management. The cost to build and maintain these features is not offset.
2. **No clear upgrade path** — New stores see all features at once with no guided onboarding. There is no "aha moment" that demonstrates the value of premium capabilities before the user commits.
3. **Feature sprawl confusion** — Stores that don't need scheduling still see scheduling-related UI, creating clutter and confusion in the interface.

### Value Proposition
By segmenting premium features behind a clear paywall with a compelling marketing page and 1-month free trial:

- **For BuyerKiosk**: Creates a recurring $30/mo revenue stream per store that opts in, with zero customer acquisition cost (existing users).
- **For Store Owners**: Provides a clean, focused experience — basic stores get a decluttered UI, while stores that need advanced scheduling get a dedicated, well-marketed premium package with a risk-free trial.
- **For Team Members**: Eliminates confusion about features they don't have access to — either the tools are available or they're not shown.

## User Personas

### Primary Persona: Store Owner (Decision Maker)
- **Demographics:** Small business owner or franchise operator, age 30-55, manages 1-5 store locations, moderate tech comfort, uses BuyerKiosk daily for buy operations
- **Goals:** Minimize operational costs while keeping team organized, only pay for features they actually use, maintain control over store expenses
- **Pain Points:** Overwhelmed by features they don't need, unclear what they're paying for vs. what's included, wants to try before committing money

### Secondary Persona: Store Manager (Daily User)
- **Demographics:** Age 22-40, manages day-to-day operations including scheduling, comfortable with web apps, spends 2-4 hours/day in BuyerKiosk
- **Goals:** Efficiently schedule shifts, communicate with team, reduce scheduling conflicts, minimize time spent on admin tasks
- **Pain Points:** When scheduling is disabled, no clear path to request it be enabled; when enabled, needs it to "just work" without friction

### Tertiary Persona: Team Member (End User)
- **Demographics:** Age 18-35, hourly employee, primarily uses mobile app (BuyerKiosk Team), checks schedule and chats with team
- **Goals:** Know when they work, swap shifts easily, communicate with managers and peers
- **Pain Points:** Confusion when scheduling features appear/disappear, no context for why certain features are unavailable

## User Journey Maps

### Primary User Journey: Store Owner Discovers and Enables Premium

1. **Awareness:** Store owner clicks "Schedule" in the navigation. Instead of a scheduler (which they haven't enabled), they see a polished marketing page showcasing scheduling, team chat, and AI scheduling features with screenshots and feature descriptions.
2. **Consideration:** Owner reviews the feature list, sees the $30/mo price with "unlimited employees" messaging, and notices the "Try Free for 1 Month" call-to-action. They compare this mentally to When I Work ($4/user/mo) and see the flat-rate value.
3. **Adoption:** Owner clicks "Start Free Trial." A confirmation dialog explains what will be enabled and that no payment is required during the trial. Owner confirms. The scheduling provider is automatically set to "buyerkiosk," and the page refreshes to show the full scheduling interface.
4. **Usage:** Over the next month, owner and managers create schedules, team members check shifts on mobile, and the team chat becomes active. The system tracks trial usage.
5. **Retention:** Before trial ends, the owner receives a notification that their trial is expiring. They can choose to continue at $30/mo (added to their existing BuyerKiosk bill) or let it expire. If they let it expire, all data is preserved but access is locked — they see the marketing page again with a "Reactivate" option.

### Secondary User Journey: Store Owner with WIW Switches to Premium

1. **Current State:** Store is using When I Work integration for scheduling. They click "Schedule" and see their WIW-synced schedule.
2. **Discovery:** In store settings or via marketing communication, they learn about BuyerKiosk's native premium scheduling with team chat, AI scheduling, and no per-user fees.
3. **Decision:** Owner decides to switch. They enable premium, which automatically replaces WIW as the scheduling provider.
4. **Migration:** WIW data sync stops. Owner begins creating native schedules. Historical WIW data is not migrated (clean start).
5. **Ongoing:** Owner uses native scheduling going forward. If they disable premium later, scheduling provider reverts to "none" (not back to WIW).

### Tertiary User Journey: Manager Uses Premium Features Daily

1. **Access:** Manager logs in and sees "Schedule" tab in navigation (because store has premium enabled).
2. **Schedule:** Creates and publishes weekly schedules using templates and AI suggestions.
3. **Communicate:** Uses team chat to coordinate with team members about shift changes, announcements, and day-to-day operations.
4. **Monitor:** Reviews timesheet approvals, overtime alerts, and labor cost dashboards.

### Mobile User Journey: Team Member on BuyerKiosk Team App

1. **Premium Active:** Team member opens app, sees their upcoming shifts, can request time off, swap shifts, and chat with team.
2. **Premium Not Active:** Team member opens app. Scheduling and chat features are not available. App shows a clean interface focused on available features (clock-in/out, basic profile). No broken or confusing UI elements.

## Feature Requirements

### Must Have Features

#### Feature 1: Premium Feature Flag on Store
- **User Story:** As a store owner, I want my store to have a premium scheduling status so that the system can correctly gate access to scheduling, chat, and AI features across all platforms.
- **Acceptance Criteria:**
  - [ ] Each store has a premium scheduling status: `none`, `trial`, `active`, `expired`
  - [ ] Trial stores track both `trialStartDate` and `trialEndDate`
  - [ ] A `trialUsed` flag permanently records whether the store has ever used its trial (prevents repeat trials)
  - [ ] Status is checked on every request to scheduling, chat, or AI endpoints (web and mobile)
  - [ ] Mobile API responses include premium status so apps can adjust UI accordingly
  - [ ] Changing premium status takes effect within 60 seconds (maximum cache propagation delay)
  - [ ] Premium status is stored per-store in the central database (not environment-variable-based)

#### Feature 2: Marketing/Upsell Landing Page
- **User Story:** As a store owner without premium scheduling, I want to see a compelling overview of what premium scheduling offers so that I can make an informed decision about enabling it.
- **Acceptance Criteria:**
  - [ ] Page appears when non-premium user navigates to "Schedule" in main navigation
  - [ ] Page includes: hero section with value proposition, feature grid with screenshots, pricing section ($30/mo, unlimited employees), and "Start Free Trial" CTA
  - [ ] Screenshots/images showcase: weekly schedule view, team chat, AI scheduling, mobile app usage
  - [ ] Page is visually polished and consistent with BuyerKiosk's design system (Bootstrap 5, design tokens)
  - [ ] Page loads within 2 seconds on a standard broadband connection (desktop/tablet)
  - [ ] Responsive design works on tablet (768px+) and desktop (1024px+) viewports

#### Feature 3: Trial Activation Flow
- **User Story:** As a store owner, I want to start a 1-month free trial of premium scheduling so that I can evaluate the features before committing to a paid subscription.
- **Acceptance Criteria:**
  - [ ] Only users with store owner permissions can activate the trial
  - [ ] Clicking "Start Free Trial" shows a confirmation dialog explaining: features being enabled, trial duration (1 calendar month), no payment required during trial, and what happens when trial ends
  - [ ] Upon confirmation, premium status changes to `trial`, trial end date is set to 1 calendar month from today, and scheduling provider is set to `buyerkiosk`
  - [ ] The page immediately transitions from marketing page to the full scheduling interface
  - [ ] Each store can only activate one trial (no repeated trials)
  - [ ] If store previously had WIW/Homebase active, the external provider is replaced

#### Feature 4: Trial Expiration Handling
- **User Story:** As a store owner whose trial is ending, I want to be notified and given clear options so that I can decide whether to subscribe or let the trial lapse.
- **Acceptance Criteria:**
  - [ ] System checks trial expiration dates daily
  - [ ] 7 days before trial ends, a notification banner appears in the scheduling interface: "Your free trial ends on [date]. Subscribe to keep your scheduling features."
  - [ ] On the day the trial expires, premium status changes to `expired`
  - [ ] Expired stores see the marketing page again, but with messaging updated to "Reactivate Premium" instead of "Start Free Trial"
  - [ ] All scheduling, chat, and AI data is preserved (not deleted)
  - [ ] All premium features become completely inaccessible — the marketing/upsell page replaces the scheduling view (no read-only mode)

#### Feature 5: Premium Activation (Post-Trial)
- **User Story:** As a store owner, I want to activate premium scheduling (either after a trial or directly) so that I can access scheduling, chat, and AI features on an ongoing basis.
- **Acceptance Criteria:**
  - [ ] Store owner can click "Enable Premium" from the marketing page
  - [ ] A confirmation dialog explains the $30/mo charge will be added to their existing BuyerKiosk bill
  - [ ] Upon confirmation, premium status changes to `active`
  - [ ] If reactivating after expired trial, all previous data is immediately accessible again
  - [ ] No separate payment processor needed (added to existing billing)

#### Feature 6: Chat Feature Gating
- **User Story:** As a store user without premium scheduling, I should not see team chat UI elements so that my interface remains clean and focused on available features.
- **Acceptance Criteria:**
  - [ ] Team chat tab/panel is completely hidden from web UI when premium is not active
  - [ ] Chat-related navigation items do not appear in sidebar/menu
  - [ ] Chat API endpoints return HTTP 403 with `{ "error": "premium_required", "feature": "chat" }` when premium is not active
  - [ ] Mobile app hides chat features when premium is not active

#### Feature 7: AI Scheduling Feature Gating
- **User Story:** As a store user without premium scheduling, I should not see AI scheduling options so that premium features are properly segmented.
- **Acceptance Criteria:**
  - [ ] AI scheduling buttons/options are hidden when premium is not active
  - [ ] AI scheduling API endpoints return HTTP 403 with `{ "error": "premium_required", "feature": "ai_scheduling" }` when premium is not active
  - [ ] Mobile app hides AI scheduling features when premium is not active

#### Feature 8: Mobile API Premium Gating
- **User Story:** As a mobile app user, I want the app to know my store's premium status so that scheduling and chat features are shown or hidden appropriately.
- **Acceptance Criteria:**
  - [ ] Store info API response includes premium scheduling status (`none`, `trial`, `active`, `expired`)
  - [ ] If trial, response includes `trialEndDate`
  - [ ] Scheduling API endpoints return 403 with `{ "error": "premium_required", "feature": "scheduling" }` when premium is not active
  - [ ] Chat API endpoints return 403 with `{ "error": "premium_required", "feature": "chat" }` when premium is not active
  - [ ] Mobile app team receives updated API contract documentation

### Should Have Features

#### Feature 9: Trial Status Dashboard
- **User Story:** As a store owner on a trial, I want to see how many days remain and what features I've used so that I can evaluate whether premium is worth subscribing to.
- **Acceptance Criteria:**
  - [ ] A small banner or card shows on the scheduling page during trial: "X days remaining in your free trial"
  - [ ] Shows usage summary: shifts created, chats sent, AI schedules generated
  - [ ] Links to the subscribe flow

#### Feature 10: Premium Status in Admin Dashboard
- **User Story:** As a BuyerKiosk system administrator, I want to see which stores have premium enabled, are on trial, or have expired so that I can monitor adoption and revenue.
- **Acceptance Criteria:**
  - [ ] Admin store list shows premium status column
  - [ ] Can filter stores by premium status
  - [ ] Shows trial expiration dates for stores on trial

### Could Have Features

#### Feature 11: Email Notifications for Trial Events
- **User Story:** As a store owner, I want to receive email notifications about my trial status so that I don't miss the expiration date.
- **Acceptance Criteria:**
  - [ ] Email sent when trial starts (welcome + getting started tips)
  - [ ] Email sent 7 days before trial ends (reminder + value summary)
  - [ ] Email sent when trial expires (reactivation CTA)

#### Feature 12: Feature Comparison Table
- **User Story:** As a store owner evaluating premium, I want to see a clear comparison of base vs. premium features so that I understand exactly what I'm getting.
- **Acceptance Criteria:**
  - [ ] Marketing page includes a comparison table: Base (free) vs. Premium ($30/mo)
  - [ ] Clearly shows what's included in each tier

### Won't Have (This Phase)

- **Stripe/Payment Processing Integration** — Premium is added to existing BuyerKiosk billing. No separate payment processor integration for now.
- **Per-Feature Premium Tiers** — No "Scheduling Only" or "Chat Only" tiers. It's all-or-nothing premium.
- **Data Migration from WIW/Homebase** — When switching to premium from an external provider, users start fresh. No import of historical scheduling data.
- **Self-Service Cancellation** — For MVP, cancellation is handled by contacting BuyerKiosk support or toggling in admin. No automated cancellation flow with exit survey.
- **Annual Pricing Option** — Only monthly pricing for now. Annual plans may come later.
- **Proration** — If a store enables mid-month, they get charged the full $30 on next billing cycle. No pro-rated partial month charges.

## Detailed Feature Specifications

### Feature: Marketing/Upsell Landing Page

**Description:** A polished, conversion-focused landing page that replaces the scheduling view for stores without premium. It showcases the value of premium scheduling and drives trial activation.

**User Flow:**
1. User clicks "Schedule" in main navigation
2. System checks store's premium status
3. If `none` or `expired`: System renders the marketing landing page
4. User scrolls through feature showcase with screenshots
5. User clicks "Start Free Trial" (or "Reactivate Premium" if expired)
6. Confirmation dialog appears with details
7. User confirms → Premium activates → Page refreshes to full scheduling interface

**Business Rules:**
- Rule 1: Only store owners can see and click the activation CTA. Managers and team members see a message: "Ask your store owner to enable Premium Scheduling."
- Rule 2: If store has previously completed a trial, the CTA changes from "Start Free Trial" to "Enable Premium ($30/mo)". No second trial allowed.
- Rule 3: If store currently uses WIW/Homebase, the marketing page should mention that enabling premium will replace the external scheduling provider.
- Rule 4: The marketing page is the ONLY entry point for non-premium stores navigating to scheduling. There is no back-door access.

**Edge Cases:**
- Scenario 1: Store owner enables trial, then another owner-level user tries to cancel → Deactivation is not available through the UI; must contact BuyerKiosk support or BK system admin handles via admin panel
- Scenario 2: Trial expires on a weekend when no one is logged in → System automatically transitions to `expired` status on the expiration date regardless of login activity
- Scenario 3: Store has active published schedules when premium expires → Schedules remain in database but scheduling view is replaced by marketing page; team members lose mobile access to schedules immediately
- Scenario 4: Store owner enables premium, creates schedules, then disables → Data preserved, access locked, reactivation restores everything

### Feature: Trial Period Management

**Description:** A 1-calendar-month free trial that lets store owners evaluate premium features risk-free.

**User Flow:**
1. Store owner clicks "Start Free Trial" on marketing page
2. Confirmation dialog explains trial terms
3. Owner confirms
4. System sets premium status to `trial`, records trial start and end dates
5. Throughout trial, a subtle banner shows remaining days
6. At 7 days remaining, banner becomes more prominent
7. On expiration date, system transitions to `expired`
8. Owner sees marketing page with "Enable Premium" CTA

**Business Rules:**
- Rule 1: Trial duration is exactly 1 calendar month (e.g., Feb 9 → Mar 9). Trial ends at 11:59 PM in the store's configured timezone on the expiration date.
- Rule 2: Each store gets exactly one trial. The `trialUsed` flag is permanent — once set, it cannot be reset through the UI.
- Rule 3: A store can go directly to `active` (skip trial) if the owner chooses "Enable Premium" instead of "Start Free Trial"
- Rule 4: During trial, all premium features function identically to a paid subscription — no feature limitations
- Rule 5: Trial cannot be paused or extended
- Rule 6: When premium replaces WIW/Homebase, the external provider settings (tokens, API keys) are preserved in the database. If premium expires, the scheduling provider reverts to `none` (not back to WIW/Homebase). The store owner can manually re-enable WIW/Homebase via store settings if desired.
- Rule 7: Trial expiration is processed by a daily scheduled job (TaskEngine). The job runs once per day and transitions all stores whose `trialEndDate` has passed (in their local timezone) to `expired` status.

**Permission Matrix:**
| Action | Store Owner | Store Manager | Team Member | BK System Admin |
|--------|-------------|---------------|-------------|-----------------|
| View marketing page | Yes | Yes (no CTA) | Yes (no CTA) | Yes |
| Start trial | Yes | No | No | Yes (via admin) |
| Activate premium | Yes | No | No | Yes (via admin) |
| Deactivate premium | No (contact support) | No | No | Yes (via admin) |

**Edge Cases:**
- Scenario 1: Store starts trial on Jan 31 → Trial ends Feb 28 (or Feb 29 in leap year) — use PHP `DateTime::modify('+1 month')` date math, not "30 days"
- Scenario 2: Two owner-level users both try to start a trial simultaneously → First activation wins (database-level uniqueness), second sees "trial already active"
- Scenario 3: BK system admin manually changes premium status in database → System respects the manual override; no validation beyond valid status values
- Scenario 4: Store owner with multiple stores → Each store has independent premium status and independent trial eligibility
- Scenario 5: Store changes timezone mid-trial → Expiration date stays the same calendar date; only the timezone interpretation shifts (may gain or lose hours)
- Scenario 6: Mobile app is open when premium expires → Next API call returns 403 with `premium_required` error; app should handle gracefully and remove premium UI elements

## Success Metrics

### Key Performance Indicators

- **Trial Adoption:** 25% of non-premium stores start a free trial within 3 months of feature launch
- **Trial-to-Paid Conversion:** 40% of trial stores convert to paid premium within 1 month of trial end
- **Revenue:** $X incremental monthly recurring revenue within 6 months (dependent on store count)
- **Retention:** 90% of premium stores remain active after 3 months
- **Feature Engagement (Trial):** Average trial store creates at least 5 shifts and sends 10 chat messages during trial period
- **UX Quality:** Marketing page has < 5% bounce rate (users who navigate to schedule then leave the app)

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `premium_marketing_page_viewed` | `storeId`, `typeNum`, `userRole`, `previousStatus` | Measure awareness and page traffic |
| `premium_trial_started` | `storeId`, `typeNum`, `userId`, `trialEndDate`, `previousProvider` | Track trial adoption |
| `premium_trial_expired` | `storeId`, `typeNum`, `shiftsCreated`, `chatsSent`, `aiSchedulesGenerated` | Measure trial engagement at expiration |
| `premium_activated` | `storeId`, `typeNum`, `userId`, `fromTrial`, `previousProvider` | Track paid conversions |
| `premium_deactivated` | `storeId`, `typeNum`, `userId`, `reason`, `durationMonths` | Track churn |
| `premium_feature_gated` | `storeId`, `typeNum`, `feature`, `endpoint`, `platform` | Track how often gating blocks access |
| `premium_reactivated` | `storeId`, `typeNum`, `userId`, `gapDays` | Track win-back success |
| `premium_cta_clicked` | `storeId`, `typeNum`, `ctaType`, `pageLocation` | Track conversion funnel |

---

## Constraints and Assumptions

### Constraints
- **No new payment processor** — Premium billing is added to the existing BuyerKiosk billing system. No Stripe or external payment integration for MVP.
- **Existing feature flag system** — Currently environment-variable-based. This feature needs a database-driven per-store flag, which is a new pattern.
- **Mobile app coordination** — Both BuyerKiosk Team and BuyerKiosk Live apps need API changes to support premium gating. Mobile releases may lag behind web deployment.
- **No migration path from external providers** — Users switching from WIW/Homebase to premium start with a clean scheduling slate.
- **TaskEngine dependency** — Trial expiration requires a daily scheduled job. The existing TaskEngine scheduler infrastructure (spec 015) must be running and processing the `scheduler:run` cron for trial expiration to work automatically.
- **Billing line item** — The $30/mo premium charge is added as a line item to the store's existing BuyerKiosk invoice. No separate checkout flow, payment method collection, or billing UI changes are needed for MVP.

### Assumptions
- Store owners have sufficient permissions to make purchasing decisions for their store.
- The existing billing infrastructure can accommodate an additional $30/mo line item without significant rework.
- Mobile app teams can implement premium gating within a reasonable timeframe of the web release.
- The current scheduling, chat, and AI features are production-ready and do not need stabilization before being packaged as premium.
- Native scheduling is not yet live on production. Premium gating will be in place from the initial launch — no grandfathering needed.

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Users perceive $30/mo as too expensive for what's included | Medium | Medium | Emphasize unlimited employees value vs per-user competitors; trial removes risk; iterate pricing based on conversion data |
| Low trial-to-paid conversion rate | High | Medium | Ensure trial period demonstrates clear value; track engagement metrics to optimize onboarding |
| Mobile app update lag creates inconsistent experience | Medium | High | Gate at API level so even outdated apps get proper error responses; coordinate release timing |
| Marketing page doesn't convert (poor UX or messaging) | Medium | Medium | A/B test messaging; iterate on page design based on view-to-trial conversion rate |
| Store data loss perception when premium expires | Medium | Low | Clearly communicate that data is preserved; show "Reactivate" messaging that implies continuity |
| WIW/Homebase users feel forced to switch | Medium | Low | External integrations remain a separate, free path; premium is positioned as a native alternative, not a replacement for integrations |

## Open Questions

- [x] How should existing stores currently using native scheduling for free be handled? → **Not applicable — native scheduling is not yet live on production. Premium gating launches with the feature.**
- [x] Should the $30/mo price be configurable per store or globally fixed? → **Globally fixed for MVP**
- [x] What timezone should trial expiration use? → **Store's configured timezone, end of day (11:59 PM)**
- [x] Should expired stores have read-only access? → **No — completely inaccessible. Marketing page replaces scheduling view.**
- [ ] What is the rollout strategy? All stores at once, or phased by region/size?
- [ ] Should the marketing page content be static HTML or CMS-manageable for future updates?
- [ ] What analytics platform will be used for tracking events? (For MVP, events will be logged to the existing PHP error/event log. A dedicated analytics service can be added later.)

---

## Supporting Research

### Competitive Analysis

| Competitor | Pricing Model | Key Differentiator |
|-----------|--------------|-------------------|
| When I Work | $4/user/month (Essentials) to $8/user/month (Pro) | Per-user pricing; expensive at scale |
| Homebase | Free (basic) to $24.95/location/month (Plus) | Free tier attracts SMBs; feature gating by tier |
| 7shifts | $34.99/location/month (Entrée) | Restaurant-focused; similar flat-rate model |
| Deputy | $4.50/user/month to $6/user/month | Per-user; strong mobile experience |

**BuyerKiosk Advantage:** Flat $30/mo regardless of team size. For a store with 10+ employees, this is significantly cheaper than per-user competitors. "Unlimited employees" messaging is a strong differentiator.

### User Research
- Stores using WIW report frustration with per-user costs as they grow
- Store owners want a "try before you buy" option — the 1-month trial addresses this directly
- Team members care about mobile access to schedules — premium gating must work cleanly on mobile

### Market Data
- Employee scheduling software market is projected to grow at ~14% CAGR through 2028
- SMB segment (BuyerKiosk's core market) increasingly expects integrated scheduling within their primary business tools
- Flat-rate pricing models are gaining preference among SMBs over per-seat pricing due to predictability