# Specification: 035-premium-scheduling-module

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-02-09 |
| **Current Phase** | Implementation Complete - All 7 Phases DONE |
| **Last Updated** | 2026-02-09 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Reviewed by Codex. 8 Must Have, 2 Should Have, 2 Could Have features. All blockers resolved. |
| solution-design.md | completed | All 6 ADRs confirmed. Codex reviewed: 3 blockers resolved, 5 important items fixed, 1 enhancement. |
| implementation-plan.md | completed | 7 phases, ~120 tasks. ALL PHASES COMPLETED. 151 tests, 591 assertions, 0 PHPStan errors. |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-09 | WIW/Homebase are separate from premium | External integrations don't require premium; premium only gates native BK scheduling + chat |
| 2026-02-09 | Premium gates: Scheduling + Chat + AI | All native scheduling, team chat, and AI features are premium. Basic employee CRUD stays free |
| 2026-02-09 | Manual flag only (MVP billing) | No Stripe integration; premium added to existing BK billing via database flag |
| 2026-02-09 | Marketing page replaces schedule view | Non-premium users see upsell page when clicking "Schedule" in nav |
| 2026-02-09 | Premium replaces external provider | Enabling premium switches schedulingProvider to 'buyerkiosk', replacing WIW/Homebase |
| 2026-02-09 | 1 calendar month trial, owner only | Store owners can activate one free trial; tracked with trial end date |
| 2026-02-09 | Landing page with screenshots (MVP) | Feature showcase + CTA with static screenshots, not live demo |
| 2026-02-09 | Chat hidden when not premium | Chat panel/tab completely removed from UI, not shown as locked |
| 2026-02-09 | Data preserved on expiry | All schedule/chat data kept in DB; access locked until reactivation |
| 2026-02-09 | Web + Mobile gating | Both web and mobile apps respect premium flag via API |
| 2026-02-09 | No grandfathering needed | Native scheduling not yet live on production; premium gating launches with the feature |
| 2026-02-09 | Expired = completely inaccessible | No read-only mode; marketing page replaces scheduling view on expiry |
| 2026-02-09 | Store timezone, end of day | Trial expires at 11:59 PM in the store's configured timezone |
| 2026-02-09 | PRD reviewed by Codex | 3 blockers resolved, 5 important items fixed, 3 enhancements added |
| 2026-02-09 | SDD draft completed | 4 parallel codebase research agents, 6 ADRs, full architecture designed |
| 2026-02-09 | SDD Codex review completed | 3 blockers, 5 important, 1 enhancement found. All resolved. |
| 2026-02-09 | Runtime trial expiration enforcement added | PremiumService checks timezone-aware expiration at read-time, not just daily job |
| 2026-02-09 | Billing integration path documented | MVP uses event log + email notification to ops; manual billing line-item |
| 2026-02-09 | Admin API expanded | Full admin endpoints: start trial, extend trial, activate, deactivate (not just set status) |
| 2026-02-09 | 7-day trial warning banner specified | Standard vs urgent banner variants with color escalation |
| 2026-02-09 | Chat/AI UI gating points enumerated | Explicit list of template elements to gate per component |
| 2026-02-09 | Marketing page content structure defined | Hero, feature grid, pricing, CTA sections with content requirements |
| 2026-02-09 | Event property mapping documented | Each PRD tracking event mapped to JSON properties in premiumEventLog |
| 2026-02-09 | Trial usage stats service added | TrialUsageService computes shifts/chats/AI counts from store DB |
| 2026-02-09 | PremiumRepository added to directory map | Resolves diagram-to-directory consistency |
| 2026-02-09 | Implementation plan completed | 7 phases: Foundation → Services → API → Job → UI → Marketing → Integration |
| 2026-02-09 | Phases 1-6 implemented + Codex reviewed | 115 tests, 331 assertions. 5 critical fixes, 3 medium fixes applied. |
| 2026-02-09 | Phase 7 completed | 36 new tests (+260 assertions). TrialUsageService tested, CSRF resolved, PRD coverage verified. |
| 2026-02-09 | Full implementation DONE | 151 tests, 591 assertions, PHPStan 0 errors. All 10 Must/Should features covered. |

## Context

We have a native BuyerKiosk Team Management and Scheduling engine that needs to be segmented as a premium add-on ($30/mo). The system also supports When I Work integration as an alternative. Basic team management (CRUD for employees) must remain in the base package. When premium scheduling is not enabled, users should see a marketing landing page showcasing features with a flow to enable the module.

### Related Specifications
- `010-employee-schedule-panel` - done
- `013-employee-scheduling` - done
- `014-manage-employees-unified` - done
- `024-staff-chat-backend`
- `025-schedule-templates-overlays`
- `026-ai-smart-scheduling`

### Key Components
- **Base Package**: Basic team management (create/edit/activate/deactivate/delete employees)
- **Premium Add-on**: Scheduling engine, team chat, advanced features ($30/mo unlimited employees)
- **Alternative Integration**: When I Work (external scheduling platform)
- **Marketing/Upsell**: Landing page for non-premium users with feature showcase and enable flow

---
*This file is managed by the specification-management skill.*