# Implementation Plan # 035 - Premium Scheduling Module ## Validation Checklist - [x] All specification file paths are correct and exist - [x] Context priming section is complete - [x] All implementation phases are defined - [x] Each phase follows TDD: Prime → Test → Implement → Validate - [x] Dependencies between phases are clear (no circular dependencies) - [x] Parallel work is properly tagged with `[parallel: true]` - [x] Activity hints provided for specialist selection `[activity: type]` - [x] Every phase references relevant SDD sections - [x] Every test references PRD acceptance criteria - [x] Integration & E2E tests defined in final phase - [x] Project commands match actual project setup - [x] A developer could follow this plan independently --- ## Specification Compliance Guidelines ### How to Ensure Specification Adherence 1. **Before Each Phase**: Complete the Pre-Implementation Specification Gate 2. **During Implementation**: Reference specific SDD sections in each task 3. **After Each Task**: Run Specification Compliance checks 4. **Phase Completion**: Verify all specification requirements are met ### Deviation Protocol If implementation cannot follow specification exactly: 1. Document the deviation and reason 2. Get approval before proceeding 3. Update SDD if the deviation is an improvement 4. Never deviate without documentation ## Metadata Reference - `[parallel: true]` - Tasks that can run concurrently - `[component: component-name]` - For multi-component features - `[ref: document/section; lines: 1, 2-3]` - Links to specifications, patterns, or interfaces and (if applicable) line(s) - `[activity: type]` - Activity hint for specialist agent selection --- ## Context Priming *GATE: You MUST fully read all files mentioned in this section before starting any implementation.* **Specification**: - `docs/specs/035-premium-scheduling-module/product-requirements.md` - Product Requirements (8 Must Have, 2 Should Have, 2 Could Have features) - `docs/specs/035-premium-scheduling-module/solution-design.md` - Solution Design (6 confirmed ADRs, Codex-reviewed) **Key Design Decisions**: - ADR-1: Premium status stored directly on `kiosk_buykiosk.stores` table (not a separate table) - ADR-2: Redis cache with 60s TTL + active invalidation for premium status checks - ADR-3: Middleware for API gating + controller-level check for page rendering (dual approach) - ADR-4: Twig extension `isPremiumActive()` for template-level sidebar/nav gating - ADR-5: TaskEngine daily job for trial expiration + runtime read-time enforcement for "on the day" accuracy - ADR-6: Marketing page as server-rendered Twig template (not SPA) **Implementation Context**: - Commands to run: ```bash ./test.sh --testsuite unit # All unit tests cd userfrosting && ./vendor/bin/phpunit --filter "Premium" # Premium-specific tests php userfrosting/conductor run # Run pending migrations php userfrosting/conductor build-css --minify # Build CSS php userfrosting/bin/task job:list # Verify job registered cd userfrosting && ./vendor/bin/phpstan analyse src/BuyerKiosk/Premium/ # Static analysis ``` - Patterns to follow: - Job registration: `TaskCommandFactory::registerJobs()` (lines 220-264) — add class to `$registry->registerAll()` array - BaseJob subclass: `AiScheduleCleanupJob.php` — static config methods + handle() returning JobResult - Twig extension: extends `\Twig_Extension`, `getFunctions()` returns `\Twig_SimpleFunction` array - Twig registration: `config-userfrosting.php` line 137 — `$app->view()->parserExtensions[] = ...` - Migration JSON: `type`, `description`, `database`, `check_query`, `sql` fields - Route groups: Slim 2.6.2 `$app->group()` with inline auth checks - Interfaces to implement: `[ref: SDD/Interface Specifications; lines: 407-625]` - Gotchas: `[ref: SDD/Implementation Gotchas; lines: 1361-1367]` **Critical Files to Read Before Starting**: | File | Why | SDD Reference | |------|-----|---------------| | `userfrosting/src/BuyerKiosk/Core/Store.php` | Store entity to modify | ICO-2 | | `userfrosting/routes/admin/scheduling.php` | Route pattern to follow | ICO-3 | | `userfrosting/src/BuyerKiosk/Scheduling/Controllers/SchedulingPageController.php` | Controller to intercept | ICO-3 | | `userfrosting/templates/themes/default/menus/sidebar.html` (lines 231-262) | Sidebar to gate | ICO-4 | | `userfrosting/src/BuyerKiosk/MobileApi/Controllers/MobileApiController.php` | Mobile API to extend | ICO-5 | | `userfrosting/src/BuyerKiosk/TaskEngine/Domain/Jobs/BaseJob.php` | Job base class | ICO-6 | | `userfrosting/src/BuyerKiosk/TaskEngine/Commands/TaskCommandFactory.php` (lines 220-264) | Job registration point | ICO-6 | | `userfrosting/src/BuyerKiosk/Vite/ViteTwigExtension.php` | Twig extension pattern | ICO-9 | | `userfrosting/config-userfrosting.php` (line 137) | Extension registration point | ICO-9 | | `userfrosting/migrations/input/20251220_013_009_store_scheduling_config.json` | Migration format reference | ICO-8 | --- ## Implementation Phases ### Phase 1: Foundation — Database, Value Objects, Repository **COMPLETED** *Delivers: Database schema, PremiumStatus value object, PremiumRepository, Store model extensions. No business logic yet — just the data layer.* - [x] T1 Phase 1: Data Foundation `[component: data-layer]` - [ ] T1.1 Prime Context - [ ] T1.1.1 Read SDD Data Storage Changes `[ref: SDD/Interface Specifications/Data Storage Changes; lines: 407-472]` - [ ] T1.1.2 Read existing scheduling migration for format reference `[ref: userfrosting/migrations/input/20251220_013_009_store_scheduling_config.json]` - [ ] T1.1.3 Read Store.php scheduling properties `[ref: userfrosting/src/BuyerKiosk/Core/Store.php; lines: 93-103, 2365-2401]` - [ ] T1.1.4 Read SDD Application Data Models `[ref: SDD/Application Data Models; lines: 627-720]` - [ ] T1.2 Write Tests `[activity: backend-test]` - [ ] T1.2.1 Test PremiumStatus value object: isActive() returns true for TRIAL and ACTIVE, false for NONE and EXPIRED `[ref: PRD/Feature 1/AC1; lines: 95]` - [ ] T1.2.2 Test PremiumStatus::canStartTrial() returns true only when trialUsed=false `[ref: PRD/Feature 3/AC5; lines: 120]` - [ ] T1.2.3 Test PremiumStatus::label() returns human-readable labels for all statuses - [ ] T1.2.4 Test PremiumRepository::getPremiumInfo() returns correct fields from stores table `[ref: SDD/Data Storage Changes; lines: 412-429]` - [ ] T1.2.5 Test PremiumRepository::updatePremiumStatus() correctly updates stores columns - [ ] T1.2.6 Test Store::getPremiumStatus() returns PremiumStatus value object `[ref: SDD/Application Data Models/Store MODIFIED; lines: 643-656]` - [ ] T1.2.7 Test Store::isPremiumActive() returns boolean for trial/active vs none/expired - [ ] T1.3 Implement Database Migrations `[activity: backend-db]` - [ ] T1.3.1 Create migration `20260209_035_001_premium_columns.json` — Add 7 premium columns + 2 indexes to `kiosk_buykiosk.stores` table `[ref: SDD/Data Storage Changes; lines: 412-429]` - [ ] T1.3.2 Create migration `20260209_035_002_premium_event_log.json` — Create `premiumEventLog` table in `kiosk_buykiosk` `[ref: SDD/Data Storage Changes; lines: 436-472]` - [ ] T1.3.3 Run migrations: `php userfrosting/conductor run` `[activity: run-command]` - [ ] T1.4 Implement Value Objects & Repository `[activity: backend-api]` - [ ] T1.4.1 Create `PremiumStatus.php` — Enum-like value object with NONE/TRIAL/ACTIVE/EXPIRED constants and isActive()/isTrial()/canStartTrial()/label() methods `[ref: SDD/Application Data Models; lines: 630-641]` - [ ] T1.4.2 Create `PremiumRepository.php` — PDO queries for premium status CRUD on stores table (getPremiumInfo, updatePremiumStatus, getTrialStores, etc.) `[ref: SDD/Directory Map; lines: 355]` - [ ] T1.4.3 Modify `Store.php` — Add premium properties ($premiumStatus, $premiumTrialStartDate, $premiumTrialEndDate, $premiumTrialUsed, $premiumActivatedAt, $premiumActivatedByUserId), load from DB row in createStoreFromRowArray(), add getter methods `[ref: SDD/Application Data Models/Store MODIFIED; lines: 643-656]` - [ ] T1.5 Validate - [ ] T1.5.1 Run unit tests: `cd userfrosting && ./vendor/bin/phpunit --filter "PremiumStatus"` `[activity: run-tests]` - [ ] T1.5.2 Run unit tests: `cd userfrosting && ./vendor/bin/phpunit --filter "PremiumRepository"` `[activity: run-tests]` - [ ] T1.5.3 Run PHPStan: `cd userfrosting && ./vendor/bin/phpstan analyse src/BuyerKiosk/Premium/` `[activity: lint-code]` - [ ] T1.5.4 Verify migrations ran: check that `premiumStatus` column exists on stores table `[activity: run-command]` - [ ] T1.5.5 Verify PRD Feature 1 AC7: Premium status is stored per-store in the central database `[ref: PRD/Feature 1/AC7; lines: 101]` `[activity: business-acceptance]` --- ### Phase 2: Core Services — PremiumService, TrialService, EventLogger **COMPLETED** *Delivers: The business logic layer. PremiumService with Redis caching and runtime trial enforcement, TrialService for trial/activation flows, PremiumEventLogger for tracking.* *Depends on: Phase 1 (PremiumStatus, PremiumRepository, Store model)* - [x] T2 Phase 2: Core Business Services - [ ] T2.1 PremiumService (Cached Status Checks) `[parallel: true]` `[component: premium-service]` - [ ] T2.1.1 Prime Context `[ref: SDD/PremiumService example; lines: 846-919]` `[ref: SDD/ADR-2; lines: 1296-1299]` `[ref: SDD/ADR-5; lines: 1311-1314]` - [ ] T2.1.2 Write Tests `[activity: backend-test]` - [ ] T2.1.2a Test isPremiumActive() returns true for 'trial' and 'active' statuses `[ref: PRD/Feature 1/AC4; lines: 98]` - [ ] T2.1.2b Test isPremiumActive() returns false for 'none' and 'expired' statuses - [ ] T2.1.2c Test Redis cache hit: getPremiumInfo() returns cached data without DB query `[ref: SDD/ADR-2; lines: 1296-1299]` - [ ] T2.1.2d Test Redis cache miss: getPremiumInfo() queries DB and caches result with 60s TTL `[ref: PRD/Feature 1/AC6; lines: 100]` - [ ] T2.1.2e Test invalidateCache() deletes Redis key `[ref: SDD/Cache key; lines: 1061]` - [ ] T2.1.2f Test Redis failure fallback: isPremiumActive() queries DB directly when Redis unavailable `[ref: SDD/Error Handling; lines: 1163]` - [ ] T2.1.2g **Test runtime trial expiration**: isPremiumActive() returns false for trial where trialEndDate has passed in store timezone, even if DB still shows 'trial' `[ref: SDD/ADR-5 runtime enforcement; lines: 1311-1314]` - [ ] T2.1.2h Test isTrialExpiredInStoreTimezone() with various timezone edge cases (UTC, EST, PST, mid-day vs end-of-day) - [ ] T2.1.2i Test getDaysRemaining() returns correct count using store timezone - [ ] T2.1.3 Implement `PremiumService.php` `[activity: backend-api]` - [ ] T2.1.3a Constructor accepting PDO and optional Redis - [ ] T2.1.3b isPremiumActive() with runtime trial expiration check - [ ] T2.1.3c getPremiumInfo() with Redis cache (60s TTL) and DB fallback - [ ] T2.1.3d isTrialExpiredInStoreTimezone() — private timezone-aware check - [ ] T2.1.3e invalidateCache() — delete Redis key - [ ] T2.1.3f getDaysRemaining() — calculate days remaining in store timezone - [ ] T2.1.4 Validate: Run tests, verify cache behavior `[activity: run-tests]` - [ ] T2.2 PremiumEventLogger `[parallel: true]` `[component: event-logger]` - [ ] T2.2.1 Prime Context `[ref: SDD/Event Property Mapping; lines: 447-472]` `[ref: SDD/Billing Integration; lines: 234-246]` - [ ] T2.2.2 Write Tests `[activity: backend-test]` - [ ] T2.2.2a Test log() inserts correct event name and JSON properties to premiumEventLog table `[ref: PRD/Tracking Requirements; lines: 283-294]` - [ ] T2.2.2b Test log() includes userId and platform fields - [ ] T2.2.2c Test billing notification is triggered for premium_activated and premium_deactivated events `[ref: SDD/Billing Integration; lines: 244]` - [ ] T2.2.2d Test event properties match PRD tracking requirements for each event type - [ ] T2.2.3 Implement `PremiumEventLogger.php` `[activity: backend-api]` - [ ] T2.2.3a Constructor accepting PDO - [ ] T2.2.3b log(typeNum, event, properties, userId, platform) — inserts to premiumEventLog - [ ] T2.2.3c Internal notification method for billing-relevant events (email to ops) - [ ] T2.2.4 Validate: Run tests `[activity: run-tests]` - [ ] T2.3 TrialService (Trial & Activation Logic) `[component: trial-service]` *Depends on: T2.1, T2.2* - [ ] T2.3.1 Prime Context `[ref: SDD/TrialService entity; lines: 671-679]` `[ref: PRD/Feature 3,4,5 specifications; lines: 113-141]` - [ ] T2.3.2 Write Tests `[activity: backend-test]` - [ ] T2.3.2a **Test startTrial()**: Sets premiumStatus='trial', calculates trialEndDate as +1 calendar month, sets trialUsed=1, sets schedulingProvider='buyerkiosk', invalidates cache, logs event `[ref: PRD/Feature 3/AC3; lines: 118]` `[ref: SDD/Test Scenario 2; lines: 1384-1396]` - [ ] T2.3.2b **Test startTrial() month-end edge case**: Jan 31 → Feb 28 using DateTime::modify('+1 month') `[ref: PRD/Trial Edge Cases/Scenario 1; lines: 265]` `[ref: SDD/Gotcha; lines: 1363]` - [ ] T2.3.2c **Test startTrial() rejects repeat trial**: Returns error when trialUsed=1 `[ref: PRD/Feature 3/AC5; lines: 120]` `[ref: SDD/Test Scenario 3; lines: 1398-1405]` - [ ] T2.3.2d **Test activatePremium()**: Sets premiumStatus='active', premiumActivatedAt=NOW(), logs event `[ref: PRD/Feature 5/AC3; lines: 138]` - [ ] T2.3.2e **Test deactivatePremium()**: Sets premiumStatus='expired', schedulingProvider='none', premiumDeactivatedAt=NOW(), logs event `[ref: PRD/Trial Business Rules/Rule 6; lines: 253]` - [ ] T2.3.2f **Test processExpiredTrials()**: Finds trial stores past expiration in their timezone, transitions each to expired, logs event with usage stats `[ref: SDD/Test Scenario 4; lines: 1407-1415]` - [ ] T2.3.2g **Test concurrent trial activation**: Second concurrent call returns error (DB-level check) `[ref: PRD/Trial Edge Cases/Scenario 2; lines: 266]` - [ ] T2.3.2h **Test trial start sets schedulingProvider**: If previously 'wiw' or 'homebase', changes to 'buyerkiosk' `[ref: PRD/Feature 3/AC6; lines: 121]` - [ ] T2.3.3 Implement `TrialService.php` `[activity: backend-api]` - [ ] T2.3.3a Constructor with PremiumRepository, PremiumService, PremiumEventLogger, TrialUsageService - [ ] T2.3.3b startTrial(typeNum, userId, storeTimezone) — validate trialUsed, calculate dates, update DB, invalidate cache, log event - [ ] T2.3.3c activatePremium(typeNum, userId) — update status, set schedulingProvider, invalidate cache, log event - [ ] T2.3.3d deactivatePremium(typeNum, userId) — update status, revert schedulingProvider to 'none', invalidate cache, log event - [ ] T2.3.3e expireTrial(typeNum) — called by job/admin, sets expired status, reverts provider, logs event - [ ] T2.3.3f processExpiredTrials() — batch process all expired trials with timezone logic - [ ] T2.3.4 Validate: Run all TrialService tests `[activity: run-tests]` - [ ] T2.4 TrialUsageService `[parallel: true]` `[component: trial-usage]` - [ ] T2.4.1 Prime Context `[ref: SDD/TrialUsageService entity; lines: 681-708]` `[ref: PRD/Feature 9; lines: 168-173]` - [ ] T2.4.2 Write Tests `[activity: backend-test]` - [ ] T2.4.2a Test getTrialUsageSummary() returns correct counts for shifts, chats, AI schedules created after trialStartDate - [ ] T2.4.2b Test getTrialUsageSummary() returns zeros when no usage exists - [ ] T2.4.3 Implement `TrialUsageService.php` — COUNT queries on scheduleShifts, chatMessages, aiScheduleJobs `[activity: backend-api]` - [ ] T2.4.4 Validate: Run tests `[activity: run-tests]` - [ ] T2.5 Phase 2 Validation - [ ] T2.5.1 Run all Phase 2 unit tests: `cd userfrosting && ./vendor/bin/phpunit --filter "Premium"` `[activity: run-tests]` - [ ] T2.5.2 Run PHPStan on all new code `[activity: lint-code]` - [ ] T2.5.3 Verify PRD Feature 1 AC4: Status is checked on every request (service exists) `[activity: business-acceptance]` - [ ] T2.5.4 Verify PRD Feature 1 AC6: Status propagation <60s (cache TTL = 60s) `[activity: business-acceptance]` --- ### Phase 3: API Layer — Middleware, Controllers, Routes **COMPLETED** *Delivers: Premium API endpoints (trial start, activate, status), PremiumGateMiddleware, admin API endpoints, route modifications.* *Depends on: Phase 2 (PremiumService, TrialService, PremiumEventLogger)* - [x] T3 Phase 3: API Layer - [ ] T3.1 PremiumGateMiddleware `[parallel: true]` `[component: middleware]` - [ ] T3.1.1 Prime Context `[ref: SDD/PremiumGateMiddleware example; lines: 802-840]` `[ref: SDD/ADR-3; lines: 1301-1304]` `[ref: userfrosting/src/BuyerKiosk/MobileApi/Middleware/HybridAuthMiddleware.php]` - [ ] T3.1.2 Write Tests `[activity: backend-test]` - [ ] T3.1.2a Test middleware returns 403 JSON with error='premium_required' and feature name when not premium `[ref: SDD/Test Scenario 1; lines: 1373-1381]` `[ref: PRD/Feature 6/AC3; lines: 147]` - [ ] T3.1.2b Test middleware passes through when premium is active `[ref: SDD/Test Scenario 8; lines: 1447-1454]` - [ ] T3.1.2c Test middleware handles missing typeNum gracefully (does not crash) - [ ] T3.1.2d Test middleware returns correct feature label: 'scheduling', 'chat', 'ai_scheduling' `[ref: PRD/Feature 7/AC2; lines: 154]` - [ ] T3.1.2e Test middleware logs premium_feature_gated event `[ref: PRD/Tracking Requirements; lines: 292]` - [ ] T3.1.3 Implement `PremiumGateMiddleware.php` — static requirePremium(feature) returns callable `[activity: backend-api]` - [ ] T3.1.4 Validate `[activity: run-tests]` - [ ] T3.2 PremiumApiController (User-Facing API) `[parallel: true]` `[component: premium-api]` - [ ] T3.2.1 Prime Context `[ref: SDD/Internal API Changes; lines: 475-525]` - [ ] T3.2.2 Write Tests `[activity: backend-test]` - [ ] T3.2.2a Test POST /api/:typeNum/premium/trial/start — happy path with owner permission `[ref: SDD/Test Scenario 2; lines: 1384-1396]` - [ ] T3.2.2b Test POST /api/:typeNum/premium/trial/start — rejects non-owner `[ref: SDD/Test Scenario 7; lines: 1438-1445]` - [ ] T3.2.2c Test POST /api/:typeNum/premium/trial/start — rejects repeat trial `[ref: SDD/Test Scenario 3; lines: 1398-1405]` - [ ] T3.2.2d Test POST /api/:typeNum/premium/activate — happy path `[ref: PRD/Feature 5; lines: 133-140]` - [ ] T3.2.2e Test GET /api/:typeNum/premium/status — returns full status info including daysRemaining `[ref: SDD/Get Premium Status endpoint; lines: 513-524]` - [ ] T3.2.3 Implement `PremiumApiController.php` `[activity: backend-api]` - [ ] T3.2.3a Constructor with $app, $store pattern - [ ] T3.2.3b startTrial() — permission check (owner), delegate to TrialService - [ ] T3.2.3c activatePremium() — permission check (owner), delegate to TrialService - [ ] T3.2.3d getStatus() — returns premiumStatus, trialEndDate, trialUsed, daysRemaining, isOwner - [ ] T3.2.4 Validate `[activity: run-tests]` - [ ] T3.3 Admin PremiumApiController `[parallel: true]` `[component: admin-api]` - [ ] T3.3.1 Prime Context `[ref: SDD/Admin Premium Management API; lines: 535-612]` - [ ] T3.3.2 Write Tests `[activity: backend-test]` - [ ] T3.3.2a Test PUT /admin/api/premium/:typeNum/status — sets status with admin permission `[ref: PRD/Permission Matrix; lines: 256-262]` - [ ] T3.3.2b Test POST /admin/api/premium/:typeNum/trial/start — admin can override trialUsed `[ref: SDD/Admin Start Trial notes; lines: 562-566]` - [ ] T3.3.2c Test PUT /admin/api/premium/:typeNum/trial/extend — only works for trial status - [ ] T3.3.2d Test POST /admin/api/premium/:typeNum/activate — activates with admin source - [ ] T3.3.2e Test POST /admin/api/premium/:typeNum/deactivate — deactivates and reverts schedulingProvider - [ ] T3.3.2f Test all admin endpoints reject non-admin users (missing uri_store_settings) - [ ] T3.3.3 Implement admin controller methods `[activity: backend-api]` - [ ] T3.3.4 Validate `[activity: run-tests]` - [ ] T3.4 Route Files `[component: routes]` *Depends on: T3.1, T3.2, T3.3* - [ ] T3.4.1 Prime Context `[ref: SDD/Directory Map routes section; lines: 376-383]` `[ref: userfrosting/routes/admin/scheduling.php]` `[ref: userfrosting/routes/scheduling.php]` - [ ] T3.4.2 Create `routes/premium.php` — Premium user-facing API routes (trial/start, activate, status) `[activity: backend-api]` - [ ] T3.4.3 Create `routes/admin/premium-admin.php` — Admin premium management routes `[activity: backend-api]` - [ ] T3.4.4 Modify `routes/scheduling.php` — Add `PremiumGateMiddleware::requirePremium('scheduling')` to scheduling API route group `[ref: SDD/Integration Points; lines: 777-781]` `[activity: backend-api]` - [ ] T3.4.5 Modify `routes/groups/ai-scheduling.php` — Add `PremiumGateMiddleware::requirePremium('ai_scheduling')` `[activity: backend-api]` - [ ] T3.4.6 Modify `routes/groups/staff-chat-api.php` — Add `PremiumGateMiddleware::requirePremium('chat')` `[ref: PRD/Feature 6/AC3; lines: 147]` `[activity: backend-api]` - [ ] T3.5 Mobile API Integration `[component: mobile-api]` *Depends on: T3.1* - [ ] T3.5.1 Prime Context `[ref: SDD/Mobile API Additions; lines: 614-624]` `[ref: userfrosting/src/BuyerKiosk/MobileApi/Controllers/MobileApiController.php]` - [ ] T3.5.2 Write Tests `[activity: backend-test]` - [ ] T3.5.2a Test /api/mobile/verify response includes premiumScheduling object per store `[ref: SDD/Test Scenario 6; lines: 1427-1435]` - [ ] T3.5.2b Test premiumScheduling.features correctly reflects active vs inactive status `[ref: PRD/Feature 8; lines: 157-164]` - [ ] T3.5.3 Modify `MobileApiController.php` — Add premiumScheduling object to store info response `[activity: backend-api]` - [ ] T3.5.4 Update mobile API docs: `docs/api/mobile-agent-requests.md` and `../buyerkiosk-team/docs/backend-api-updates.md` `[activity: documentation]` - [ ] T3.5.5 Validate `[activity: run-tests]` - [ ] T3.6 Phase 3 Validation - [ ] T3.6.1 Run all unit tests: `./test.sh --testsuite unit` `[activity: run-tests]` - [ ] T3.6.2 Run PHPStan on all Premium code `[activity: lint-code]` - [ ] T3.6.3 Verify PRD Feature 6 AC3: Chat API returns 403 when not premium `[activity: business-acceptance]` - [ ] T3.6.4 Verify PRD Feature 7 AC2: AI API returns 403 when not premium `[activity: business-acceptance]` - [ ] T3.6.5 Verify PRD Feature 8: Mobile API includes premium status `[activity: business-acceptance]` --- ### Phase 4: Background Job — TrialExpirationJob **COMPLETED** *Delivers: TaskEngine job for daily trial expiration processing.* *Depends on: Phase 2 (TrialService)* - [x] T4 Phase 4: Trial Expiration Job `[component: taskengine-job]` - [ ] T4.1 Prime Context - [ ] T4.1.1 Read SDD TrialExpirationJob specification `[ref: SDD/TrialExpirationJob entity; lines: 710-719]` - [ ] T4.1.2 Read SDD job example `[ref: SDD/Trial Expiration Job example; lines: 922-971]` - [ ] T4.1.3 Read BaseJob pattern `[ref: userfrosting/src/BuyerKiosk/TaskEngine/Domain/Jobs/BaseJob.php]` - [ ] T4.1.4 Read TaskCommandFactory registration `[ref: userfrosting/src/BuyerKiosk/TaskEngine/Commands/TaskCommandFactory.php; lines: 220-264]` - [ ] T4.2 Write Tests `[activity: backend-test]` - [ ] T4.2.1 Test job static config: getName()='trial-expiration', getScope()='global', getQueue()='default', getTimeout()=300 `[ref: SDD/TrialExpirationJob entity; lines: 711-714]` - [ ] T4.2.2 Test handle() finds and expires correct trials (store with yesterday's endDate and matching timezone) `[ref: SDD/Test Scenario 4; lines: 1407-1415]` - [ ] T4.2.3 Test handle() respects store timezone (trial not expired yet in PST but past midnight UTC) `[ref: PRD/Trial Business Rules/Rule 7; lines: 254]` - [ ] T4.2.4 Test handle() is idempotent — running twice doesn't cause errors - [ ] T4.2.5 Test handle() returns JobResult::success with expired_count - [ ] T4.2.6 Test handle() handles empty result (no trials to expire) gracefully - [ ] T4.2.7 Test handle() includes usage stats in premium_trial_expired event `[ref: PRD/Tracking Requirements/premium_trial_expired; lines: 289]` - [ ] T4.3 Implement `[activity: backend-api]` - [ ] T4.3.1 Create `Jobs/TrialExpirationJob.php` extending BaseJob with global scope - [ ] T4.3.2 Implement handle() — query trial stores, check timezone-aware expiration, call TrialService::expireTrial() - [ ] T4.3.3 Register job in `TaskCommandFactory::registerJobs()` — add `\BuyerKiosk\Premium\Jobs\TrialExpirationJob::class` to registry array - [ ] T4.4 Validate - [ ] T4.4.1 Run tests: `cd userfrosting && ./vendor/bin/phpunit --filter "TrialExpiration"` `[activity: run-tests]` - [ ] T4.4.2 Verify job registered: `php userfrosting/bin/task job:list` should show trial-expiration `[activity: run-command]` - [ ] T4.4.3 Manual dispatch test: `php userfrosting/bin/task job:dispatch trial-expiration` `[activity: run-command]` - [ ] T4.4.4 Verify PRD Feature 4 AC1: System checks trial expiration dates daily `[ref: PRD/Feature 4/AC1; lines: 126]` `[activity: business-acceptance]` --- ### Phase 5: UI Layer — Twig Extension, Sidebar Gating, Page Controller Intercept **COMPLETED** *Delivers: PremiumTwigExtension, sidebar nav gating, SchedulingPageController marketing page intercept, chat/AI UI gating, trial banner.* *Depends on: Phase 2 (PremiumService), Phase 3 (routes active)* - [x] T5 Phase 5: UI Gating & Template Integration - [ ] T5.1 PremiumTwigExtension `[component: twig-extension]` - [ ] T5.1.1 Prime Context `[ref: SDD/ADR-4; lines: 1306-1309]` `[ref: userfrosting/src/BuyerKiosk/Vite/ViteTwigExtension.php]` `[ref: userfrosting/config-userfrosting.php; lines: 137]` - [ ] T5.1.2 Write Tests `[activity: backend-test]` - [ ] T5.1.2a Test isPremiumActive() Twig function calls PremiumService and returns boolean - [ ] T5.1.2b Test getPremiumStatus() Twig function returns status string - [ ] T5.1.2c Test getPremiumDaysRemaining() Twig function returns int or null - [ ] T5.1.3 Implement `Twig/PremiumTwigExtension.php` — extends `\Twig_Extension`, registers isPremiumActive/getPremiumStatus/getPremiumDaysRemaining as Twig functions `[activity: backend-api]` - [ ] T5.1.4 Register extension in `config-userfrosting.php` — `$app->view()->parserExtensions[] = ...` `[activity: backend-api]` - [ ] T5.1.5 Validate `[activity: run-tests]` - [ ] T5.2 Sidebar Navigation Gating `[component: sidebar]` *Depends on: T5.1* - [ ] T5.2.1 Prime Context `[ref: SDD/Chat & AI UI Gating Points; lines: 722-760]` `[ref: userfrosting/templates/themes/default/menus/sidebar.html; lines: 231-262]` - [ ] T5.2.2 Modify `sidebar.html` — Wrap scheduling nav section (lines 231-262) with `{% if isPremiumActive(store.typeNum) %}` conditional `[ref: SDD/Integration Points; lines: 772-775]` `[activity: frontend]` - [ ] T5.2.3 Wrap chat nav item with `{% if isPremiumActive(store.typeNum) %}` `[ref: SDD/Chat UI Gating; lines: 729-732]` `[activity: frontend]` - [ ] T5.2.4 Validate: Visually confirm sidebar hides scheduling/chat when premium inactive `[activity: business-acceptance]` - [ ] T5.3 SchedulingPageController Intercept `[component: page-controller]` *Depends on: T5.1* - [ ] T5.3.1 Prime Context `[ref: SDD/Primary Flow; lines: 975-1007]` `[ref: userfrosting/src/BuyerKiosk/Scheduling/Controllers/SchedulingPageController.php; lines: 86-117]` - [ ] T5.3.2 Modify `SchedulingPageController.php` — Add premium check before rendering calendar. If not premium, render `premium/marketing.html` instead `[ref: SDD/ADR-3; lines: 1301-1304]` `[activity: backend-api]` - [ ] T5.3.3 Add trial banner include: When premium is trial, pass daysRemaining to template and include appropriate banner partial `[ref: SDD/Trial Banner Display Logic; lines: 1121-1148]` `[activity: backend-api]` - [ ] T5.3.4 Log `premium_marketing_page_viewed` event when rendering marketing page `[ref: PRD/Tracking Requirements; lines: 287]` `[activity: backend-api]` - [ ] T5.4 Chat & AI UI Gating `[component: template-gating]` *Depends on: T5.1* - [ ] T5.4.1 Prime Context `[ref: SDD/Chat & AI UI Gating Points; lines: 722-760]` - [ ] T5.4.2 Modify `scheduling/calendar.html` — Wrap chat panel/tab include with premium conditional `[ref: SDD/Chat Gating; lines: 735-737]` `[activity: frontend]` - [ ] T5.4.3 Modify `scheduling/calendar.html` — Wrap AI Schedule Generate button with premium conditional `[ref: SDD/AI Gating; lines: 747-749]` `[activity: frontend]` - [ ] T5.4.4 Modify `scheduling/settings.html` — Wrap AI settings section with premium conditional `[ref: SDD/AI Gating; lines: 751-753]` `[activity: frontend]` - [ ] T5.4.5 Modify `scheduling/partials/ai-panel.html` — Wrap entire partial with premium conditional `[ref: SDD/AI Gating; lines: 755-758]` `[activity: frontend]` - [ ] T5.5 PremiumPageController (Marketing Page Rendering) `[component: marketing-page-controller]` - [ ] T5.5.1 Prime Context `[ref: SDD/Marketing Page Content Structure; lines: 1057-1119]` `[ref: SDD/Directory Map; lines: 359]` - [ ] T5.5.2 Implement `PremiumPageController.php` — Renders marketing.html with premium status context (trialUsed, isOwner, currentProvider, premiumStatus) `[activity: backend-api]` - [ ] T5.5.3 Validate: Controller renders correctly for all status variants `[activity: run-tests]` - [ ] T5.6 Phase 5 Validation - [ ] T5.6.1 Run all tests: `./test.sh --testsuite unit` `[activity: run-tests]` - [ ] T5.6.2 Run PHPStan `[activity: lint-code]` - [ ] T5.6.3 Verify PRD Feature 2 AC1: Non-premium user sees marketing page `[ref: PRD/Feature 2/AC1; lines: 106]` `[activity: business-acceptance]` - [ ] T5.6.4 Verify PRD Feature 4 AC2: 7-day warning banner appears `[ref: PRD/Feature 4/AC2; lines: 127]` `[activity: business-acceptance]` - [ ] T5.6.5 Verify PRD Feature 6 AC1-2: Chat hidden from web UI `[ref: PRD/Feature 6/AC1-2; lines: 145-146]` `[activity: business-acceptance]` - [ ] T5.6.6 Verify PRD Feature 7 AC1: AI buttons hidden `[ref: PRD/Feature 7/AC1; lines: 153]` `[activity: business-acceptance]` --- ### Phase 6: Marketing Page — Templates & CSS **COMPLETED** *Delivers: Marketing/upsell landing page with hero, feature grid, pricing, CTA. Trial banner templates.* *Depends on: Phase 5 (PremiumPageController, PremiumTwigExtension)* - [x] T6 Phase 6: Marketing Page & Trial Banners `[component: frontend-templates]` - [ ] T6.1 Prime Context - [ ] T6.1.1 Read SDD marketing page content structure `[ref: SDD/Marketing Page Content Structure; lines: 1057-1119]` - [ ] T6.1.2 Read SDD trial banner display logic `[ref: SDD/Trial Banner Display Logic; lines: 1121-1148]` - [ ] T6.1.3 Read existing landing page for design patterns `[ref: userfrosting/templates/themes/default/demo/landing.html]` - [ ] T6.1.4 Read design token definitions `[ref: public_html/css/admin/tokens.css]` - [ ] T6.2 Create Marketing Page Templates `[activity: frontend]` - [ ] T6.2.1 Create `premium/marketing.html` — Main layout including all partials, extending admin layout `[ref: SDD/Marketing Page Sections; lines: 1061-1117]` - [ ] T6.2.2 Create `premium/partials/hero-section.html` — Headline, subheadline, gradient background `[ref: PRD/Feature 2/AC2; lines: 107]` - [ ] T6.2.3 Create `premium/partials/feature-grid.html` — 3-column grid with 4 feature cards (scheduling, chat, AI, mobile) with screenshot placeholders `[ref: PRD/Feature 2/AC3; lines: 108]` - [ ] T6.2.4 Create `premium/partials/pricing-section.html` — $30/mo card with unlimited employees tagline `[ref: SDD/Pricing section; lines: 1092-1104]` - [ ] T6.2.5 Create `premium/partials/cta-section.html` — Role-based CTA (owner: trial/activate, non-owner: "ask your owner") with confirmation dialog JS `[ref: SDD/CTA section; lines: 1106-1116]` `[ref: PRD/Feature 2 Business Rules; lines: 221-225]` - [ ] T6.2.6 Create `premium/partials/comparison-table.html` — Base vs Premium feature comparison (Could Have Feature 12) `[ref: PRD/Feature 12; lines: 191-195]` - [ ] T6.2.7 Wrap any Handlebars syntax in `{% raw %}{% endraw %}` blocks per template conventions - [ ] T6.3 Create Trial Banner Templates `[activity: frontend]` - [ ] T6.3.1 Create `premium/partials/trial-banner.html` — Standard info banner (>7 days remaining, dismissible) `[ref: SDD/Trial Banner standard; lines: 1127-1131]` - [ ] T6.3.2 Create `premium/partials/trial-banner-urgent.html` — Warning/danger banner (<=7 days, not dismissible, with CTA) `[ref: SDD/Trial Banner urgent; lines: 1133-1145]` `[ref: PRD/Feature 4/AC2; lines: 127]` - [ ] T6.4 Create CSS `[activity: frontend]` - [ ] T6.4.1 Create `public_html/css/admin/modules/premium.css` — Marketing page styles using design tokens (hero gradient, feature cards, pricing card, CTA styling) `[ref: SDD/Directory Map; lines: 404]` - [ ] T6.4.2 Build CSS: `php userfrosting/conductor build-css --minify` `[activity: run-command]` - [ ] T6.5 Create Screenshot Placeholders `[activity: frontend]` - [ ] T6.5.1 Create `public_html/img/premium/screenshots/` directory - [ ] T6.5.2 Add placeholder images for: schedule-calendar.png, team-chat.png, ai-scheduling.png, mobile-app.png (to be replaced with real screenshots from staging) `[ref: SDD/Screenshot assets; lines: 1119]` - [ ] T6.6 CTA JavaScript `[activity: frontend]` - [ ] T6.6.1 Implement confirmation dialog for "Start Free Trial" — AJAX POST to /api/:typeNum/premium/trial/start, page reload on success `[ref: SDD/Secondary Flow; lines: 1009-1047]` - [ ] T6.6.2 Implement confirmation dialog for "Enable Premium" — AJAX POST to /api/:typeNum/premium/activate, page reload on success - [ ] T6.6.3 Log `premium_cta_clicked` event on button click `[ref: PRD/Tracking Requirements; lines: 294]` - [ ] T6.7 Phase 6 Validation - [ ] T6.7.1 Verify PRD Feature 2 AC2: Page includes hero, feature grid, pricing, CTA `[ref: PRD/Feature 2/AC2; lines: 107]` `[activity: business-acceptance]` - [ ] T6.7.2 Verify PRD Feature 2 AC4: Design consistent with BuyerKiosk design system `[ref: PRD/Feature 2/AC4; lines: 109]` `[activity: business-acceptance]` - [ ] T6.7.3 Verify PRD Feature 2 AC6: Responsive on tablet (768px+) and desktop (1024px+) `[ref: PRD/Feature 2/AC6; lines: 111]` `[activity: business-acceptance]` - [ ] T6.7.4 Verify PRD Feature 3 AC2: Confirmation dialog shows correct trial details `[ref: PRD/Feature 3/AC2; lines: 117]` `[activity: business-acceptance]` - [ ] T6.7.5 Visual review in browser at dev2.buyerkiosk.com `[activity: review-code]` --- ### Phase 7: Integration Testing & End-to-End Validation **COMPLETED** *Delivers: Full integration test suite, end-to-end flow validation, security verification, performance checks.* *Depends on: All previous phases (1-6)* - [x] T7 Phase 7: Integration & End-to-End Validation - [x] T7.1 Integration Tests `[activity: backend-test]` - [x] T7.1.1 Test full trial activation flow: marketing page → CTA click → API call → status change → page reload → calendar view `[ref: PRD/User Journey 1; lines: 60-66]` - [x] T7.1.2 Test full premium activation flow: marketing page → "Enable Premium" → status change → calendar view `[ref: PRD/User Journey 1/Step 5; lines: 66]` - [x] T7.1.3 Test full expiration flow: trial active → job runs → status expired → marketing page with "Reactivate" `[ref: PRD/Feature 4/AC3-4; lines: 128-129]` - [x] T7.1.4 Test reactivation flow: expired → activate → calendar with existing data preserved `[ref: PRD/Feature 5/AC4; lines: 139]` - [x] T7.1.5 Test middleware + permission layering: checkStoreGroup → checkAccess → isPremiumActive `[ref: SDD/Solution Strategy; lines: 283-288]` - [x] T7.1.6 Test mobile API flow: verify → get premium status → gated endpoint returns 403 `[ref: PRD/Feature 8; lines: 157-164]` - [x] T7.2 Cross-Component Tests `[activity: backend-test]` - [x] T7.2.1 Test cache invalidation end-to-end: TrialService changes status → Redis key deleted → next isPremiumActive() reads new status `[ref: PRD/Feature 1/AC6; lines: 100]` - [x] T7.2.2 Test PremiumEventLogger logs correct events throughout full trial lifecycle - [x] T7.2.3 Test TrialExpirationJob + TrialUsageService integration: expiration event includes usage stats - [x] T7.3 Security Tests `[activity: backend-test]` - [x] T7.3.1 Verify non-owner cannot start trial or activate premium `[ref: SDD/Quality Requirements/Security; lines: 1335-1341]` - [x] T7.3.2 Verify premium middleware cannot be bypassed by direct URL access - [x] T7.3.3 Verify no schedule/chat data leaks in 403 responses - [x] T7.3.4 Verify admin endpoints reject non-admin users (via AdminPremiumApiControllerTest) - [x] T7.3.5 Verify trial activation is idempotent (double-click safe) - [x] T7.4 Codex Deferred Items `[activity: backend-test]` - [x] T7.4.1 TrialUsageService unit tests (Codex deferred #10) — 10 tests, 23 assertions - [x] T7.4.2 CSRF token investigation (Codex deferred #11) — resolved: app-wide JSON API pattern uses session auth without CSRF; consistent with scheduling, chat, AI endpoints - [x] T7.5 Full Test Suite `[activity: run-tests]` - [x] T7.5.1 Run Premium tests: 151 tests, 591 assertions — ALL PASSING - [x] T7.5.2 Run PHPStan on Premium module: 0 errors - [x] T7.5.3 Full unit test suite: premature PHP process termination in unrelated test (~test 3150 of 7030) — pre-existing issue, not Premium-related - [x] T7.6 PRD Feature Coverage Verification `[activity: business-acceptance]` - [x] T7.6.1 Feature 1 (Premium Flag): All ACs met — PremiumStatus value object, Redis cache, mobile API, 60s TTL - [x] T7.6.2 Feature 2 (Marketing Page): All ACs met — hero, feature grid, pricing, CTA, Bootstrap 5 responsive - [x] T7.6.3 Feature 3 (Trial Activation): All ACs met — owner only, 1 calendar month, trialUsed flag, provider switch - [x] T7.6.4 Feature 4 (Trial Expiration): All ACs met — daily TaskEngine job, trial banner, expired status, data preserved - [x] T7.6.5 Feature 5 (Premium Activation): All ACs met — activate from marketing, reactivation restores data - [x] T7.6.6 Feature 6 (Chat Gating): All ACs met — sidebar hidden via isPremiumActive(), 403 API via middleware - [x] T7.6.7 Feature 7 (AI Gating): All ACs met — hidden via isPremiumActive() in calendar.html, 403 API - [x] T7.6.8 Feature 8 (Mobile API): All ACs met — premiumScheduling in store info, 403 on gated endpoints - [x] T7.6.9 Feature 9 (Trial Dashboard): All ACs met — trial-banner.html, days remaining, usage via TrialUsageService - [x] T7.6.10 Feature 10 (Admin Dashboard): All ACs met — admin API endpoints, status management, trial extension - [x] T7.7 Deployment Readiness `[activity: review-code]` - [x] T7.7.1 Deployment sequence verified: 2 migration JSONs → PHP classes → CSS → job in TaskCommandFactory - [x] T7.7.2 Rollback strategy: revert migrations (columns nullable/droppable), no data loss risk - [x] T7.7.3 Mobile API contract: premiumScheduling object in store info documented in routes/premium.php - [x] T7.7.4 All Premium tests passing (151/151), PHPStan clean (0 errors) --- ## Phase 1-6 Review Summary **Review Date**: 2026-02-09 **Reviewer**: Codex (o3 model, read-only sandbox) **Scope**: All code from Phases 1-6 ### Codex Review Findings #### Critical (Fixed) | # | Finding | Fix Applied | |---|---------|-------------| | 1 | `getTrialStores()` missing `premiumTrialStartDate` in SELECT — usage stats always zero | Added column to SELECT in `PremiumRepository.php:89` | | 2 | Trial banner "Subscribe Now" uses `` GET on POST-only endpoint → 404 in production | Changed to `