# Implementation Plan ## 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/003-comeback-cash/product-requirements.md` - Product Requirements (complete) - `docs/specs/003-comeback-cash/solution-design.md` - Solution Design (complete) **Key Design Decisions**: - **ADR-1**: Separate system from existing Loyalty (new `BuyerKiosk\ComebackCash` namespace) - **ADR-2**: Bearer instrument model (coupons redeemable by anyone with code) - **ADR-3**: POS-only coupon issuance (no manual creation in workspace) - **ADR-4**: Store-level database (all data in `kiosk_{typeNum}` databases) - **ADR-5**: Ably for real-time sync with `/settings` API polling fallback - **ADR-6**: Pre-tax thresholds for all calculations - **Buy-side vs Sales-side**: Buy-side has NO earning thresholds (any transaction = coupon); Sales-side supports tiered/percentage earning **Implementation Context**: - Commands to run: - `cd userfrosting && composer install` - Install dependencies - `./test.sh` - Run tests - `php userfrosting/conductor migrate` - Run database migrations - `./deploy.sh` - Test + deploy - Patterns to follow: - `userfrosting/src/BuyerKiosk/Workbook/Controllers/TasksApiController.php` - API controller pattern - `userfrosting/src/BuyerKiosk/Workbook/WorkbookAbly.php` - Ably event publishing - `userfrosting/migrations/input/20251202_003_backstock_events_tables.json` - Migration JSON format - Interfaces to implement: - POS API: GET `/api/{typeNum}/comeback-cash/settings`, POST `/api/{typeNum}/comeback-cash/coupons`, POST `/api/{typeNum}/comeback-cash/redeem` - Workspace API: CRUD events, coupon lookup, redemption - Ably events: `comeback_cash.settings_updated`, `comeback_cash.event_started`, `comeback_cash.event_ended` --- ## Implementation Phases ### Phase 1: Database Foundation - [x] T1 Phase 1 - Database Schema and Migration `[component: database]` - [x] T1.1 Prime Context - [x] T1.1.1 Read existing migration patterns `[ref: userfrosting/migrations/input/20251202_003_backstock_events_tables.json]` - [x] T1.1.2 Read database schema from SDD `[ref: solution-design.md; lines: 471-570]` - [x] T1.1.3 Understand multi-store migration execution `[ref: userfrosting/migrations/methods/storeMigration.php]` - [x] T1.2 Write Tests - [x] T1.2.1 Create migration test: verify tables created with correct columns `[activity: write-test]` - [x] T1.2.2 Create migration test: verify indexes exist for performance `[activity: write-test]` - [x] T1.2.3 Create migration test: verify foreign key constraints `[activity: write-test]` - [x] T1.3 Implement Migration - [x] T1.3.1 Create `userfrosting/migrations/input/20251205_001_comeback_cash_tables.json` `[activity: database-migration]` - ccEvents table (event configuration) - ccCoupons table (issued coupons) - ccRedemptions table (audit log) - [x] T1.3.2 Include proper check_query for idempotent execution `[activity: database-migration]` - [x] T1.3.3 Use `"database": "{{store}}"` for multi-store deployment `[activity: database-migration]` - [x] T1.4 Validate - [x] T1.4.1 Run migration on dev database: `php userfrosting/conductor migrate` `[activity: run-migration]` - [x] T1.4.2 Verify table structure matches SDD specification `[activity: verify-schema]` - [x] T1.4.3 Verify indexes are created for query patterns `[activity: verify-schema]` --- ### Phase 2: Core Domain Models - [x] T2 Phase 2 - Domain Models and Services `[component: backend]` - [x] T2.1 Event Model and Service `[parallel: true]` `[component: event-model]` - [x] T2.1.1 Prime Context - [x] T2.1.1.1 Read Event data model from SDD `[ref: solution-design.md; lines: 726-757]` - [x] T2.1.1.2 Read existing model patterns `[ref: userfrosting/src/BuyerKiosk/Core/Loyalty/LoyaltyCoupon.php]` - [x] T2.1.2 Write Tests - [x] T2.1.2.1 Test Event::isActive() returns correct status based on dates `[activity: write-test]` - [x] T2.1.2.2 Test Event::isInRedemptionPeriod() validates redemption window `[activity: write-test]` - [x] T2.1.2.3 Test Event::calculateReward() for buy-side (always returns flat amount) `[activity: write-test]` - [x] T2.1.2.4 Test Event::calculateReward() for sales-side tiered earning `[activity: write-test]` - [x] T2.1.2.5 Test Event::calculateReward() for sales-side percentage earning `[activity: write-test]` - [x] T2.1.2.6 Test Event::toSettingsArray() produces correct POS format `[activity: write-test]` - [x] T2.1.3 Implement - [x] T2.1.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Models/Event.php` `[activity: implement-model]` - [x] T2.1.3.2 Implement all properties matching ccEvents table `[activity: implement-model]` - [x] T2.1.3.3 Implement calculateReward() with buy-side vs sales-side logic `[activity: implement-business-logic]` - [x] T2.1.3.4 Implement lifecycle methods (isActive, isInRedemptionPeriod) `[activity: implement-business-logic]` - [x] T2.1.4 Validate - [x] T2.1.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T2.1.4.2 Verify buy-side always returns flat amount regardless of transaction `[activity: business-acceptance]` - [x] T2.2 Coupon Model and Service `[parallel: true]` `[component: coupon-model]` - [x] T2.2.1 Prime Context - [x] T2.2.1.1 Read Coupon data model from SDD `[ref: solution-design.md; lines: 762-788]` - [x] T2.2.1.2 Read code generation example `[ref: solution-design.md; lines: 925-938]` - [x] T2.2.2 Write Tests - [x] T2.2.2.1 Test Coupon::generateCode() produces 8-char alphanumeric codes `[activity: write-test]` - [x] T2.2.2.2 Test Coupon::generateCode() excludes ambiguous characters `[activity: write-test]` - [x] T2.2.2.3 Test Coupon::isRedeemable() validates status and expiration `[activity: write-test]` - [x] T2.2.2.4 Test Coupon::canRedeemForAmount() checks minimum purchase `[activity: write-test]` - [x] T2.2.2.5 Test Coupon::markRedeemed() updates status correctly `[activity: write-test]` - [x] T2.2.3 Implement - [x] T2.2.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Models/Coupon.php` `[activity: implement-model]` - [x] T2.2.3.2 Implement static generateCode() with cryptographically secure random bytes `[activity: implement-model]` - [x] T2.2.3.3 Implement validation methods (isRedeemable, canRedeemForAmount) `[activity: implement-business-logic]` - [x] T2.2.3.4 Implement status transition methods (markRedeemed, markExpired, reinstate) `[activity: implement-business-logic]` - [x] T2.2.4 Validate - [x] T2.2.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T2.3 Redemption Model `[parallel: true]` `[component: redemption-model]` - [x] T2.3.1 Prime Context - [x] T2.3.1.1 Read Redemption data model from SDD `[ref: solution-design.md; lines: 793-807]` - [x] T2.3.2 Write Tests - [x] T2.3.2.1 Test Redemption entity stores all audit fields `[activity: write-test]` - [x] T2.3.2.2 Test Redemption::getCoupon() returns associated coupon `[activity: write-test]` - [x] T2.3.3 Implement - [x] T2.3.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Models/Redemption.php` `[activity: implement-model]` - [x] T2.3.4 Validate - [x] T2.3.4.1 Run tests: `./test.sh` `[activity: run-tests]` --- ### Phase 3: Business Services - [x] T3 Phase 3 - Business Logic Services `[component: backend]` - [x] T3.1 EventService `[component: event-service]` - [x] T3.1.1 Prime Context - [x] T3.1.1.1 Read event lifecycle algorithm `[ref: solution-design.md; lines: 1098-1139]` - [x] T3.1.1.2 Read business rules from PRD `[ref: product-requirements.md; lines: 306-324]` - [x] T3.1.2 Write Tests - [x] T3.1.2.1 Test createEvent() validates only one active per side `[ref: PRD Rule 1,2]` `[activity: write-test]` - [x] T3.1.2.2 Test createEvent() validates earning before redemption period `[ref: PRD Rule 3]` `[activity: write-test]` - [x] T3.1.2.3 Test activateEvent() deactivates conflicting event on same side `[activity: write-test]` - [x] T3.1.2.4 Test getActiveEvent() returns correct event by side `[activity: write-test]` - [x] T3.1.2.5 Test deleteEvent() only allows draft events `[activity: write-test]` - [x] T3.1.2.6 Test buy-side event creation enforces flat earning type only `[activity: write-test]` - [x] T3.1.3 Implement - [x] T3.1.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Services/EventService.php` `[activity: implement-service]` - [x] T3.1.3.2 Implement CRUD operations with validation `[activity: implement-service]` - [x] T3.1.3.3 Implement lifecycle transitions (draft→scheduled→active→ended) `[activity: implement-business-logic]` - [x] T3.1.3.4 Implement conflict detection and resolution `[activity: implement-business-logic]` - [x] T3.1.4 Validate - [x] T3.1.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T3.1.4.2 Verify all PRD business rules enforced `[activity: business-acceptance]` - [x] T3.2 CouponService `[component: coupon-service]` - [x] T3.2.1 Prime Context - [x] T3.2.1.1 Read coupon issuance flow `[ref: solution-design.md; lines: 969-998]` - [x] T3.2.1.2 Read API response format `[ref: solution-design.md; lines: 609-632]` - [x] T3.2.2 Write Tests - [x] T3.2.2.1 Test issueCoupon() for buy-side: any transaction earns coupon `[activity: write-test]` - [x] T3.2.2.2 Test issueCoupon() for sales-side: threshold must be met `[activity: write-test]` - [x] T3.2.2.3 Test issueCoupon() handles duplicate transaction_id (idempotent) `[activity: write-test]` - [x] T3.2.2.4 Test issueCoupon() queues SMS when phone provided `[activity: write-test]` - [x] T3.2.2.5 Test validateCoupon() returns correct status for all states `[activity: write-test]` - [x] T3.2.3 Implement - [x] T3.2.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Services/CouponService.php` `[activity: implement-service]` - [x] T3.2.3.2 Implement issueCoupon() with buy-side/sales-side logic `[activity: implement-business-logic]` - [x] T3.2.3.3 Implement validateCoupon() with all validation checks `[activity: implement-business-logic]` - [x] T3.2.3.4 Implement SMS notification queueing `[activity: implement-integration]` - [x] T3.2.4 Validate - [x] T3.2.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T3.3 RedemptionService `[component: redemption-service]` - [x] T3.3.1 Prime Context - [x] T3.3.1.1 Read redemption flow `[ref: solution-design.md; lines: 1001-1037]` - [x] T3.3.1.2 Read error handling requirements `[ref: solution-design.md; lines: 1068-1092]` - [x] T3.3.2 Write Tests - [x] T3.3.2.1 Test redeemCoupon() validates coupon status `[activity: write-test]` - [x] T3.3.2.2 Test redeemCoupon() validates minimum purchase `[activity: write-test]` - [x] T3.3.2.3 Test redeemCoupon() creates audit record `[activity: write-test]` - [x] T3.3.2.4 Test redeemCoupon() updates coupon status to redeemed `[activity: write-test]` - [x] T3.3.2.5 Test redeemCoupon() in transaction (atomic) `[activity: write-test]` - [x] T3.3.3 Implement - [x] T3.3.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Services/RedemptionService.php` `[activity: implement-service]` - [x] T3.3.3.2 Implement redeemCoupon() with database transaction `[activity: implement-business-logic]` - [x] T3.3.3.3 Implement all validation checks with specific error codes `[activity: implement-business-logic]` - [x] T3.3.4 Validate - [x] T3.3.4.1 Run tests: `./test.sh` `[activity: run-tests]` --- ### Phase 4: Real-Time Integration - [x] T4 Phase 4 - Ably Integration `[component: ably]` - [x] T4.1 Prime Context - [x] T4.1.1 Read existing Ably pattern `[ref: userfrosting/src/BuyerKiosk/Workbook/WorkbookAbly.php]` - [x] T4.1.2 Read Ably event specification `[ref: solution-design.md; lines: 939-958]` - [x] T4.1.3 Read integration points `[ref: solution-design.md; lines: 809-844]` - [x] T4.2 Write Tests - [x] T4.2.1 Test ComebackCashAbly::broadcastSettingsUpdate() publishes correct payload `[activity: write-test]` - [x] T4.2.2 Test ComebackCashAbly handles Ably failures gracefully `[activity: write-test]` - [x] T4.2.3 Test payload excludes PII (no phone numbers in broadcast) `[activity: write-test]` - [x] T4.3 Implement - [x] T4.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Services/ComebackCashAbly.php` `[activity: implement-service]` - [x] T4.3.2 Implement broadcastSettingsUpdate() method `[activity: implement-integration]` - [x] T4.3.3 Implement event-specific broadcast methods (eventStarted, eventEnded) `[activity: implement-integration]` - [x] T4.3.4 Add graceful error handling (log but don't throw) `[activity: implement-error-handling]` - [x] T4.4 Validate - [x] T4.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T4.4.2 Verify no PII in Ably payloads `[activity: security-review]` --- ### Phase 5: Factory and Dependency Injection - [x] T5 Phase 5 - Service Factory `[component: backend]` - [x] T5.1 Prime Context - [x] T5.1.1 Read factory pattern example `[ref: solution-design.md; lines: 1237-1249]` - [x] T5.2 Implement - [x] T5.2.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/ComebackCashFactory.php` `[activity: implement-service]` - [x] T5.2.2 Implement createEventService() with proper dependencies `[activity: implement-service]` - [x] T5.2.3 Implement createCouponService() with proper dependencies `[activity: implement-service]` - [x] T5.2.4 Implement createRedemptionService() with proper dependencies `[activity: implement-service]` - [x] T5.3 Validate - [x] T5.3.1 Run tests: `./test.sh` `[activity: run-tests]` --- ### Phase 6: POS API Layer - [x] T6 Phase 6 - POS API Endpoints `[component: pos-api]` - [x] T6.1 Prime Context - [x] T6.1.1 Read POS API specification `[ref: solution-design.md; lines: 575-672]` - [x] T6.1.2 Read existing API route patterns `[ref: userfrosting/routes/api.php]` - [x] T6.1.3 Read API controller pattern `[ref: solution-design.md; lines: 1256-1280]` - [x] T6.2 Write Tests - [x] T6.2.1 Test GET /settings returns active events for both sides `[activity: write-test]` - [x] T6.2.2 Test GET /settings requires API key authentication `[activity: write-test]` - [x] T6.2.3 Test POST /coupons issues coupon for qualifying transaction `[activity: write-test]` - [x] T6.2.4 Test POST /coupons returns null for below-threshold sales-side `[activity: write-test]` - [x] T6.2.5 Test POST /coupons always issues for buy-side (no threshold) `[activity: write-test]` - [x] T6.2.6 Test POST /coupons handles duplicate transaction (idempotent) `[activity: write-test]` - [x] T6.2.7 Test GET /coupons/{code} validates coupon `[activity: write-test]` - [x] T6.2.8 Test POST /redeem processes redemption `[activity: write-test]` - [x] T6.2.9 Test all endpoints return proper error codes `[activity: write-test]` - [x] T6.3 Implement - [x] T6.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Controllers/ComebackCashPosApiController.php` `[activity: implement-api]` - [x] T6.3.2 Implement getSettings() endpoint `[activity: implement-api]` - [x] T6.3.3 Implement issueCoupon() endpoint `[activity: implement-api]` - [x] T6.3.4 Implement validateCoupon() endpoint `[activity: implement-api]` - [x] T6.3.5 Implement redeemCoupon() endpoint `[activity: implement-api]` - [x] T6.3.6 Add API key authentication middleware `[activity: implement-security]` - [x] T6.3.7 Create route file `userfrosting/routes/groups/comeback-cash-pos.php` `[activity: implement-routing]` - [x] T6.3.8 Register routes in `userfrosting/routes/api.php` `[activity: implement-routing]` - [x] T6.4 Validate - [x] T6.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T6.4.2 Test API manually with curl commands `[activity: manual-test]` - [x] T6.4.3 Verify API response times <500ms `[activity: performance-test]` --- ### Phase 7: Workspace API Layer - [x] T7 Phase 7 - Workspace API Endpoints `[component: workspace-api]` - [x] T7.1 Prime Context - [x] T7.1.1 Read Workspace API specification `[ref: solution-design.md; lines: 677-721]` - [x] T7.1.2 Read existing workspace controller pattern `[ref: userfrosting/src/BuyerKiosk/Workbook/Controllers/TasksApiController.php]` - [x] T7.2 Write Tests - [x] T7.2.1 Test GET /events lists events with filtering `[activity: write-test]` - [x] T7.2.2 Test POST /events creates event with validation `[activity: write-test]` - [x] T7.2.3 Test PUT /events/{id} updates event and triggers Ably `[activity: write-test]` - [x] T7.2.4 Test DELETE /events/{id} only allows draft events `[activity: write-test]` - [x] T7.2.5 Test GET /lookup validates coupon code `[activity: write-test]` - [x] T7.2.6 Test POST /redeem processes workspace redemption `[activity: write-test]` - [x] T7.2.7 Test GET /events/{id}/report returns statistics `[activity: write-test]` - [x] T7.2.8 Test all endpoints require session auth and permission `[activity: write-test]` - [x] T7.3 Implement - [x] T7.3.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Controllers/ComebackCashApiController.php` `[activity: implement-api]` - [x] T7.3.2 Implement event CRUD endpoints `[activity: implement-api]` - [x] T7.3.3 Implement coupon lookup endpoint `[activity: implement-api]` - [x] T7.3.4 Implement redemption endpoint `[activity: implement-api]` - [x] T7.3.5 Implement reporting endpoint `[activity: implement-api]` - [x] T7.3.6 Add session auth and permission checks `[activity: implement-security]` - [x] T7.3.7 Create route file `userfrosting/routes/comeback-cash/api.php` `[activity: implement-routing]` - [x] T7.4 Validate - [x] T7.4.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T7.4.2 Verify permission checks work correctly `[activity: security-review]` --- ### Phase 8: Workspace Page Controller - [x] T8 Phase 8 - Workspace Page Controller `[component: workspace-pages]` - [x] T8.1 Prime Context - [x] T8.1.1 Read workspace page patterns `[ref: userfrosting/src/BuyerKiosk/Workbook/Controllers/WorkbookPageController.php]` - [x] T8.1.2 Read workspace routing `[ref: userfrosting/routes/workbook/pages.php]` - [x] T8.2 Implement - [x] T8.2.1 Create `userfrosting/src/BuyerKiosk/ComebackCash/Controllers/ComebackCashPageController.php` `[activity: implement-controller]` - [x] T8.2.2 Implement main() page render method `[activity: implement-controller]` - [x] T8.2.3 Create route file `userfrosting/routes/comeback-cash/pages.php` `[activity: implement-routing]` - [x] T8.3 Validate - [x] T8.3.1 Run tests: `./test.sh` `[activity: run-tests]` - [x] T8.3.2 Verify page loads without errors `[activity: manual-test]` --- ### Phase 9: Workspace UI - [x] T9 Phase 9 - Frontend Templates and JavaScript `[component: frontend]` - [x] T9.1 Templates `[parallel: true]` `[component: templates]` - [x] T9.1.1 Prime Context - [x] T9.1.1.1 Read SPA view container pattern `[ref: userfrosting/templates/themes/default/workspace/workspace.html]` - [x] T9.1.1.2 Read sidebar navigation pattern `[ref: userfrosting/templates/themes/default/workspace/partials/sidebar-nav.html]` - [x] T9.1.1.3 Read modal form pattern `[ref: userfrosting/templates/themes/default/workbook/modals/add-note-modal.html]` - [x] T9.1.2 Implement - [x] T9.1.2.1 Create `userfrosting/templates/themes/default/workspace/partials/comeback-cash/main.html` `[activity: implement-ui]` - [x] T9.1.2.2 Create `userfrosting/templates/themes/default/workspace/partials/comeback-cash/events-list.html` `[activity: implement-ui]` - [x] T9.1.2.3 Create `userfrosting/templates/themes/default/workspace/partials/comeback-cash/event-form.html` `[activity: implement-ui]` - [x] T9.1.2.4 Create `userfrosting/templates/themes/default/workspace/partials/comeback-cash/redemption-panel.html` `[activity: implement-ui]` - [x] T9.1.2.5 Create `userfrosting/templates/themes/default/workspace/partials/comeback-cash/reports.html` `[activity: implement-ui]` - [x] T9.1.2.6 Create `userfrosting/templates/themes/default/modals/comeback-cash-redeem-modal.html` `[activity: implement-ui]` - [x] T9.1.2.7 Update `sidebar-nav.html` to add navigation item `[activity: implement-ui]` - [x] T9.1.2.8 Update `workspace.html` to include new view container `[activity: implement-ui]` - [x] T9.1.3 Validate - [x] T9.1.3.1 Verify templates render without Twig errors `[activity: manual-test]` - [x] T9.2 JavaScript `[parallel: true]` `[component: javascript]` - [x] T9.2.1 Prime Context - [x] T9.2.1.1 Read existing JS module patterns `[ref: public_html/js/workspace/modules/]` - [x] T9.2.1.2 Read Ably sync pattern `[ref: public_html/js/workspace/modules/workbook/ably-sync.js]` - [x] T9.2.2 Implement - [x] T9.2.2.1 Create `public_html/js/workspace/modules/comeback-cash/comeback-cash.js` - Main module init `[activity: implement-js]` - [x] T9.2.2.2 Create `public_html/js/workspace/modules/comeback-cash/events-controller.js` - Event management `[activity: implement-js]` - [x] T9.2.2.3 Create `public_html/js/workspace/modules/comeback-cash/redemption-controller.js` - Redemption flow with barcode scanner support `[activity: implement-js]` - [x] T9.2.2.4 Create `public_html/js/workspace/modules/comeback-cash/ably-sync.js` - Real-time settings sync `[activity: implement-js]` - [x] T9.2.2.5 Register view with WorkspaceApp `[activity: implement-js]` - [x] T9.2.3 Validate - [x] T9.2.3.1 Verify no JavaScript console errors `[activity: manual-test]` - [x] T9.2.3.2 Test barcode scanner input handling `[activity: manual-test]` - [x] T9.3 Styles `[parallel: true]` `[component: css]` - [x] T9.3.1 Implement - [x] T9.3.1.1 Create `public_html/css/workspace/comeback-cash.css` `[activity: implement-css]` - [x] T9.3.1.2 Style event cards and forms `[activity: implement-css]` - [x] T9.3.1.3 Style redemption modal with clear success/error states `[activity: implement-css]` - [x] T9.3.1.4 Ensure tablet-friendly responsive design `[activity: implement-css]` - [x] T9.3.2 Validate - [x] T9.3.2.1 Test on desktop and tablet viewports `[activity: manual-test]` --- ### Phase 10: Integration & End-to-End Validation - [x] T10 Integration & End-to-End Validation - [x] T10.1 All unit tests passing `[activity: run-tests]` - [x] T10.1.1 Run full test suite: `./test.sh` - [x] T10.1.2 Verify all Event model tests pass - [x] T10.1.3 Verify all Coupon model tests pass - [x] T10.1.4 Verify all service tests pass - [x] T10.1.5 Verify all API tests pass - [x] T10.2 Integration tests for component interactions `[activity: write-test]` - [x] T10.2.1 Test full coupon lifecycle: Event creation → Coupon issuance → Redemption - [x] T10.2.2 Test Ably broadcasts trigger on event status changes - [x] T10.2.3 Test SMS queue integration - [x] T10.3 End-to-end tests for complete user flows `[activity: e2e-test]` - [x] T10.3.1 E2E: Store owner creates sales-side event with tiered earning - [x] T10.3.2 E2E: Store owner creates buy-side event (flat, no threshold) - [x] T10.3.3 E2E: POS fetches settings and issues coupon - [x] T10.3.4 E2E: Employee redeems coupon via workspace - [x] T10.3.5 E2E: View redemption report - [x] T10.4 Performance tests meet requirements `[ref: solution-design.md; lines: 1339-1345]` `[activity: performance-test]` - [x] T10.4.1 POS API response time <500ms (95th percentile) - [x] T10.4.2 Coupon lookup <200ms - [x] T10.4.3 Ably sync latency <2 seconds - [x] T10.4.4 Database query performance <100ms - [x] T10.5 Security validation passes `[ref: solution-design.md; lines: 1356-1361]` `[activity: security-review]` - [x] T10.5.1 API key validation on all POS endpoints - [x] T10.5.2 Session + permission validation on workspace endpoints - [x] T10.5.3 No PII in Ably payloads - [x] T10.5.4 CSRF protection on workspace POST/PUT/DELETE - [x] T10.5.5 Audit log contains all redemptions with employee ID - [x] T10.6 Acceptance criteria verified against PRD `[ref: product-requirements.md; lines: 150-266]` `[activity: business-acceptance]` - [x] T10.6.1 Feature 1: Sales-side event configuration complete - [x] T10.6.2 Feature 2: Buy-side event configuration complete (no threshold) - [x] T10.6.3 Feature 3: Coupon generation API working - [x] T10.6.4 Feature 4: Settings retrieval API working - [x] T10.6.5 Feature 5: Real-time settings sync via Ably working - [x] T10.6.6 Feature 6: Workspace redemption interface complete - [x] T10.6.7 Feature 7: Coupon database at store level working - [x] T10.7 Test coverage meets standards `[activity: coverage-report]` - [x] T10.7.1 Generate coverage report - [x] T10.7.2 Verify critical paths have >80% coverage - [x] T10.8 Documentation updated `[activity: documentation]` - [x] T10.8.1 Update CLAUDE.md if new patterns established - [x] T10.8.2 Document API endpoints for POS team - [x] T10.9 Build and deployment verification `[activity: deploy]` - [x] T10.9.1 Run `./deploy.sh` on staging - [x] T10.9.2 Verify migration runs successfully - [x] T10.9.3 Verify all endpoints accessible - [x] T10.10 Final PRD requirements checklist `[activity: business-acceptance]` - [x] T10.10.1 All "Must Have" features implemented and working - [x] T10.10.2 No critical bugs or blockers - [x] T10.10.3 Ready for pilot store deployment - [x] T10.11 Implementation follows SDD design `[activity: architecture-review]` - [x] T10.11.1 Verify namespace structure matches SDD - [x] T10.11.2 Verify API contracts match SDD - [x] T10.11.3 Verify database schema matches SDD - [x] T10.11.4 Verify Ably event format matches SDD --- ## Dependency Graph ``` Phase 1 (Database) ↓ Phase 2 (Models) [parallel: Event, Coupon, Redemption] ↓ Phase 3 (Services) [depends on: Phase 2] ↓ Phase 4 (Ably) [depends on: Phase 3] ↓ Phase 5 (Factory) [depends on: Phase 3, 4] ↓ Phase 6 (POS API) [depends on: Phase 5] ←→ Phase 7 (Workspace API) [parallel possible] ↓ ↓ Phase 8 (Page Controller) [depends on: Phase 7] ↓ Phase 9 (UI) [depends on: Phase 8] [parallel: Templates, JS, CSS] ↓ Phase 10 (Integration) [depends on: All phases] ``` ## Quick Reference ### File Locations (New) ``` userfrosting/src/BuyerKiosk/ComebackCash/ ├── Controllers/ │ ├── ComebackCashPageController.php │ ├── ComebackCashApiController.php │ └── ComebackCashPosApiController.php ├── Models/ │ ├── Event.php │ ├── Coupon.php │ └── Redemption.php ├── Services/ │ ├── EventService.php │ ├── CouponService.php │ ├── RedemptionService.php │ └── ComebackCashAbly.php └── ComebackCashFactory.php userfrosting/routes/ ├── comeback-cash/ │ ├── pages.php │ └── api.php └── groups/ └── comeback-cash-pos.php userfrosting/migrations/input/ └── 20251205_001_comeback_cash_tables.json userfrosting/templates/themes/default/ ├── workspace/partials/comeback-cash/ │ ├── main.html │ ├── events-list.html │ ├── event-form.html │ ├── redemption-panel.html │ └── reports.html └── modals/ └── comeback-cash-redeem-modal.html public_html/ ├── js/workspace/modules/comeback-cash/ │ ├── comeback-cash.js │ ├── events-controller.js │ ├── redemption-controller.js │ └── ably-sync.js └── css/workspace/ └── comeback-cash.css ``` ### Key Commands ```bash # Development cd userfrosting && composer install # Install dependencies ./test.sh # Run tests php userfrosting/conductor migrate # Run migrations # Deployment ./deploy.sh # Test + deploy # Verification curl -X GET "https://dev2.buyerkiosk.com/api/{typeNum}/comeback-cash/settings" -H "X-API-Key: {key}" ```