# Public Catalog & Unified Checkout - Task Checklist > **Related**: See [PUBLIC-CATALOG-UNIFIED-CHECKOUT.md](./PUBLIC-CATALOG-UNIFIED-CHECKOUT.md) for full design document. ## Implementation Notes (Current Codebase) - Public catalog routes are implemented under `/shop` (directory: `apps/portal/src/app/(public)/(catalog)/shop`). - Unified checkout is implemented under `/order` (directory: `apps/portal/src/app/(public)/order`). ## Quick Reference - **Total Effort**: ~7 weeks - **Priority**: P0 (Critical), P1 (Important), P2 (Nice to have) - **Status Legend**: ⬜ Todo, 🟡 In Progress, ✅ Done, ❌ Blocked - **Branch**: `Homepage` ### Current Progress ``` ✅ Phase 0 (SF Permissions) → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Launch ↑ START HERE ``` ### Critical Path Phase 4 (Salesforce Account Creation) remains the most complex phase, but **SF permissions are now verified** ✅ --- ## Phase 0: Preparation (4 days) | # | Task | Priority | Effort | Status | Notes | | --- | ---------------------------------------- | -------- | ------ | ------ | --------------------------- | | 0.1 | Create feature branch `feature/homepage` | P0 | 1h | ✅ | Done - on Homepage branch | | 0.2 | Document current catalog user flow | P0 | 2h | ⬜ | Screenshots + notes | | 0.3 | Document current checkout user flow | P0 | 2h | ⬜ | Screenshots + notes | | 0.4 | Set up feature flags infrastructure | P0 | 4h | ⬜ | Use env vars initially | | 0.5 | Verify SF integration user permissions | P0 | 3h | ✅ | Done - permissions verified | | 0.6 | Add "Portal Checkout" to SF picklist | P0 | 1h | ✅ | Done - picklist updated | | 0.7 | Create test Salesforce sandbox accounts | P0 | 2h | ⬜ | For testing order flow | | 0.8 | Create test WHMCS accounts | P0 | 2h | ⬜ | For payment testing | | 0.9 | Document rollback/cleanup procedures | P0 | 2h | ⬜ | For orphaned records | ### ✅ Salesforce Permissions - VERIFIED The following permissions have been confirmed: | Object | Permission | Status | | ------------------------------- | ---------- | ------------------------------ | | Account | CREATE | ✅ Verified | | Account | UPDATE | ✅ Verified | | Contact | CREATE | ✅ Verified | | SF_Account_No\_\_c | READ/WRITE | ✅ Verified | | WH_Account\_\_c | READ/WRITE | ✅ Verified | | Portal_Status\_\_c | WRITE | ✅ Verified | | Portal_Registration_Source\_\_c | WRITE | ✅ Verified (picklist updated) | --- ## Phase 1: Public Catalog (5 days) ### 1.1 Frontend - Routes & Layout | # | Task | Priority | Effort | Status | Notes | | ------ | ----------------------------------------------------- | -------- | ------ | ------ | ----------------------------- | | 1.1.1 | Create `CatalogLayout` component | P0 | 4h | ⬜ | Hybrid header (public + auth) | | 1.1.2 | Create `CatalogHeader` component | P0 | 2h | ⬜ | Logo, nav, sign-in button | | 1.1.3 | Create `(public)/catalog/layout.tsx` | P0 | 1h | ⬜ | Use CatalogLayout | | 1.1.4 | Create `(public)/catalog/page.tsx` | P0 | 2h | ⬜ | Copy from authenticated | | 1.1.5 | Create `(public)/catalog/internet/page.tsx` | P0 | 2h | ⬜ | Copy from authenticated | | 1.1.6 | Create `(public)/catalog/internet/configure/page.tsx` | P0 | 2h | ⬜ | Copy from authenticated | | 1.1.7 | Create `(public)/catalog/sim/page.tsx` | P0 | 2h | ⬜ | Copy from authenticated | | 1.1.8 | Create `(public)/catalog/sim/configure/page.tsx` | P0 | 2h | ⬜ | Copy from authenticated | | 1.1.9 | Create `(public)/catalog/vpn/page.tsx` | P0 | 1h | ⬜ | Copy from authenticated | | 1.1.10 | Update internal links in catalog components | P0 | 2h | ⬜ | Ensure relative paths work | ### 1.2 Backend - Public API | # | Task | Priority | Effort | Status | Notes | | ----- | --------------------------------------------- | -------- | ------ | ------ | ----------------------- | | 1.2.1 | Add `@Public()` to `CatalogController` | P0 | 0.5h | ⬜ | `catalog.controller.ts` | | 1.2.2 | Update catalog services to handle null userId | P0 | 1h | ⬜ | Defensive coding | | 1.2.3 | Add rate limiting to public catalog endpoints | P0 | 1h | ⬜ | Prevent abuse | | 1.2.4 | Test catalog API without auth token | P0 | 1h | ⬜ | Manual + automated | ### 1.3 Integration | # | Task | Priority | Effort | Status | Notes | | ----- | -------------------------------------------- | -------- | ------ | ------ | ---------------------- | | 1.3.1 | Update `catalogService` to work without auth | P0 | 1h | ⬜ | Frontend service | | 1.3.2 | Test full catalog flow without login | P0 | 2h | ⬜ | All product types | | 1.3.3 | Add "Proceed to Checkout" CTA | P0 | 2h | ⬜ | Redirects to /checkout | --- ## Phase 2: Checkout Store (3 days) | # | Task | Priority | Effort | Status | Notes | | --- | --------------------------------------- | -------- | ------ | ------ | ----------------------- | | 2.1 | Define `CartItem` TypeScript interface | P0 | 1h | ⬜ | In domain package | | 2.2 | Define `GuestInfo` TypeScript interface | P0 | 1h | ⬜ | In domain package | | 2.3 | Create `checkout.store.ts` with Zustand | P0 | 2h | ⬜ | With persist middleware | | 2.4 | Implement cart item serialization | P0 | 2h | ⬜ | Handle complex objects | | 2.5 | Implement cart validation utilities | P0 | 2h | ⬜ | Zod schemas | | 2.6 | Create `useCartRecovery` hook | P1 | 2h | ⬜ | Detect stale carts | | 2.7 | Write unit tests for checkout store | P0 | 4h | ⬜ | Full coverage | | 2.8 | Test localStorage persistence | P0 | 1h | ⬜ | Refresh, close browser | --- ## Phase 3: Unified Checkout UI (8 days) ### 3.1 Checkout Shell | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------------ | -------- | ------ | ------ | --------------- | | 3.1.1 | Create `(public)/checkout/page.tsx` | P0 | 1h | ⬜ | Shell page | | 3.1.2 | Create `CheckoutLayout` component | P0 | 2h | ⬜ | Minimal header | | 3.1.3 | Create `CheckoutProgress` component | P0 | 2h | ⬜ | Step indicator | | 3.1.4 | Create `CheckoutWizard` component | P0 | 3h | ⬜ | Step management | | 3.1.5 | Create `OrderSummaryCard` component | P0 | 2h | ⬜ | Sidebar summary | | 3.1.6 | Create `EmptyCartRedirect` component | P0 | 1h | ⬜ | Handle no cart | ### 3.2 Account Step | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------------- | -------- | ------ | ------ | -------------------- | | 3.2.1 | Create `AccountStep` component | P0 | 3h | ⬜ | Parent component | | 3.2.2 | Create `GuestInfoForm` component | P0 | 3h | ⬜ | New customer form | | 3.2.3 | Create `SignInForm` embedded variant | P0 | 2h | ⬜ | Reuse existing | | 3.2.4 | Implement mode switching (new/signin) | P0 | 1h | ⬜ | Toggle between forms | | 3.2.5 | Add form validation | P0 | 2h | ⬜ | Zod + useZodForm | ### 3.3 Address Step | # | Task | Priority | Effort | Status | Notes | | ----- | -------------------------------- | -------- | ------ | ------ | --------------- | | 3.3.1 | Create `AddressStep` component | P0 | 2h | ⬜ | Wrapper | | 3.3.2 | Integrate existing `AddressForm` | P0 | 2h | ⬜ | Reuse component | | 3.3.3 | Add postal code auto-fill (JP) | P1 | 3h | ⬜ | External API | | 3.3.4 | Add address validation | P0 | 2h | ⬜ | Required fields | ### 3.4 Payment Step | # | Task | Priority | Effort | Status | Notes | | ----- | --------------------------------------- | -------- | ------ | ------ | --------------- | | 3.4.1 | Create `PaymentStep` component | P0 | 3h | ⬜ | Main component | | 3.4.2 | Implement WHMCS SSO link opening | P0 | 2h | ⬜ | New tab | | 3.4.3 | Create `usePaymentPolling` hook | P0 | 2h | ⬜ | Poll for method | | 3.4.4 | Add focus listener for return detection | P0 | 1h | ⬜ | Window focus | | 3.4.5 | Create `PaymentMethodDisplay` component | P0 | 1h | ⬜ | Show added card | | 3.4.6 | Add loading/waiting states | P0 | 1h | ⬜ | UX polish | ### 3.5 Review Step | # | Task | Priority | Effort | Status | Notes | | ----- | ----------------------------------- | -------- | ------ | ------ | ------------ | | 3.5.1 | Create `ReviewStep` component | P0 | 3h | ⬜ | Summary view | | 3.5.2 | Create `OrderItemsReview` component | P0 | 2h | ⬜ | Cart items | | 3.5.3 | Create `AddressReview` component | P0 | 1h | ⬜ | Show address | | 3.5.4 | Create `PaymentReview` component | P0 | 1h | ⬜ | Show payment | | 3.5.5 | Add terms acceptance checkbox | P0 | 0.5h | ⬜ | Required | | 3.5.6 | Create submit order handler | P0 | 2h | ⬜ | API call | | 3.5.7 | Add loading state during submission | P0 | 1h | ⬜ | UX | ### 3.6 Confirmation | # | Task | Priority | Effort | Status | Notes | | ----- | -------------------------------------------- | -------- | ------ | ------ | ------------- | | 3.6.1 | Create `(public)/checkout/complete/page.tsx` | P0 | 2h | ⬜ | Success page | | 3.6.2 | Create `OrderConfirmation` component | P0 | 2h | ⬜ | Order details | | 3.6.3 | Add "Go to Dashboard" CTA | P0 | 0.5h | ⬜ | Navigation | | 3.6.4 | Clear checkout store on completion | P0 | 0.5h | ⬜ | Cleanup | --- ## Phase 4: Backend - Checkout Registration (7 days) > **CRITICAL**: Salesforce Account creation is SYNCHRONOUS and REQUIRED. > Every new customer MUST have a Salesforce Account for business tracking. ### 4.1 Domain Schema Changes | # | Task | Priority | Effort | Status | Notes | | ----- | -------------------------------------------- | -------- | ------ | ------ | ---------------------- | | 4.1.1 | Make `sfNumber` optional in signup schema | P0 | 1h | ⬜ | `packages/domain/auth` | | 4.1.2 | Create `checkoutRegisterSchema` | P0 | 1h | ⬜ | New schema | | 4.1.3 | Create `checkoutSubmitSchema` | P0 | 1h | ⬜ | Order from cart | | 4.1.4 | Create `CreateSalesforceAccountRequest` type | P0 | 0.5h | ⬜ | SF Account payload | | 4.1.5 | Create `CreateSalesforceContactRequest` type | P0 | 0.5h | ⬜ | SF Contact payload | | 4.1.6 | Update type exports | P0 | 0.5h | ⬜ | Index files | | 4.1.7 | Build domain package | P0 | 0.5h | ⬜ | Verify compilation | ### 4.2 Salesforce Account Service Updates | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------------ | -------- | ------ | ------ | ---------------------- | | 4.2.1 | Add `createAccount()` method | P0 | 3h | ⬜ | Creates SF Account | | 4.2.2 | Add `createContact()` method | P0 | 2h | ⬜ | Creates SF Contact | | 4.2.3 | Add `generateAccountNumber()` method | P0 | 2h | ⬜ | Auto-gen PNNNNNNN | | 4.2.4 | Add `findByEmail()` method | P0 | 1h | ⬜ | Check for duplicates | | 4.2.5 | Test SF Account creation in sandbox | P0 | 2h | ⬜ | Verify permissions | | 4.2.6 | Test SF Contact creation in sandbox | P0 | 1h | ⬜ | Verify link to Account | | 4.2.7 | Verify WH_Account\_\_c update works | P0 | 1h | ⬜ | Link SF → WHMCS | ### 4.3 Checkout Service | # | Task | Priority | Effort | Status | Notes | | ------ | ------------------------------------------ | -------- | ------ | ------ | ------------------- | | 4.3.1 | Create `CheckoutService` class | P0 | 1h | ⬜ | Business logic | | 4.3.2 | Implement `registerForCheckout()` - Step 1 | P0 | 1h | ⬜ | Create SF Account | | 4.3.3 | Implement `registerForCheckout()` - Step 2 | P0 | 1h | ⬜ | Create SF Contact | | 4.3.4 | Implement `registerForCheckout()` - Step 3 | P0 | 1h | ⬜ | Create WHMCS Client | | 4.3.5 | Implement `registerForCheckout()` - Step 4 | P0 | 0.5h | ⬜ | Link SF to WHMCS | | 4.3.6 | Implement `registerForCheckout()` - Step 5 | P0 | 1h | ⬜ | Create Portal User | | 4.3.7 | Implement `registerForCheckout()` - Step 6 | P0 | 0.5h | ⬜ | Create ID Mapping | | 4.3.8 | Implement `registerForCheckout()` - Step 7 | P0 | 0.5h | ⬜ | Generate tokens | | 4.3.9 | Implement `rollbackRegistration()` method | P0 | 2h | ⬜ | Compensating txns | | 4.3.10 | Implement `getPaymentStatus()` method | P0 | 1h | ⬜ | Check WHMCS | | 4.3.11 | Add comprehensive logging | P0 | 1h | ⬜ | Debug each step | ### 4.4 Checkout Controller | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------------------- | -------- | ------ | ------ | -------------- | | 4.4.1 | Create `CheckoutController` class | P0 | 1h | ⬜ | New controller | | 4.4.2 | Add `POST /checkout/register` endpoint | P0 | 1h | ⬜ | Public | | 4.4.3 | Add `GET /checkout/payment-status` endpoint | P0 | 0.5h | ⬜ | Authenticated | | 4.4.4 | Add `POST /checkout/submit` endpoint | P0 | 0.5h | ⬜ | Authenticated | | 4.4.5 | Add rate limiting (5/min) | P0 | 0.5h | ⬜ | Prevent abuse | | 4.4.6 | Create `CheckoutModule` | P0 | 0.5h | ⬜ | Nest module | | 4.4.7 | Register in `AppModule` | P0 | 0.5h | ⬜ | Wire up | ### 4.5 Testing | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------------ | -------- | ------ | ------ | -------------------- | | 4.5.1 | Unit test: SF Account creation | P0 | 1h | ⬜ | Mock SF API | | 4.5.2 | Unit test: SF Contact creation | P0 | 1h | ⬜ | Mock SF API | | 4.5.3 | Unit test: Account number generation | P0 | 1h | ⬜ | Sequence logic | | 4.5.4 | Unit test: Full registration flow | P0 | 2h | ⬜ | Happy path | | 4.5.5 | Unit test: Rollback scenarios | P0 | 2h | ⬜ | Failure at each step | | 4.5.6 | Integration test: SF sandbox | P0 | 2h | ⬜ | Real SF calls | | 4.5.7 | Integration test: Full flow | P0 | 2h | ⬜ | SF + WHMCS + Portal | --- ## Phase 5: Integration Testing (5 days) | # | Task | Priority | Effort | Status | Notes | | ---- | ---------------------------------------- | -------- | ------ | ------ | ------------------- | | 5.1 | Wire up checkout UI to register endpoint | P0 | 2h | ⬜ | API integration | | 5.2 | Implement auto-login after registration | P0 | 2h | ⬜ | Token handling | | 5.3 | Wire up order submission | P0 | 2h | ⬜ | API integration | | 5.4 | E2E test: New customer full flow | P0 | 4h | ⬜ | Playwright | | 5.5 | E2E test: Existing customer flow | P0 | 2h | ⬜ | Sign-in path | | 5.6 | E2E test: Cart recovery | P1 | 2h | ⬜ | Abandon + resume | | 5.7 | E2E test: Error scenarios | P0 | 3h | ⬜ | Network, validation | | 5.8 | Performance test checkout | P1 | 2h | ⬜ | Load testing | | 5.9 | Security review | P0 | 4h | ⬜ | Auth, CSRF, etc. | | 5.10 | Fix bugs from testing | P0 | 8h | ⬜ | Buffer time | --- ## Phase 6: Public Support (3 days) | # | Task | Priority | Effort | Status | Notes | | --- | ------------------------------------------ | -------- | ------ | ------ | ------------ | | 6.1 | Create `(public)/support/page.tsx` | P1 | 2h | ⬜ | FAQ landing | | 6.2 | Create `PublicSupportView` component | P1 | 3h | ⬜ | Content | | 6.3 | Create `(public)/support/contact/page.tsx` | P1 | 1h | ⬜ | Form page | | 6.4 | Create `PublicContactForm` component | P1 | 3h | ⬜ | Form UI | | 6.5 | Create `publicContactSchema` | P1 | 0.5h | ⬜ | Validation | | 6.6 | Add `POST /support/contact` endpoint | P1 | 2h | ⬜ | Public API | | 6.7 | Implement Salesforce Lead creation | P1 | 3h | ⬜ | Integration | | 6.8 | Add rate limiting to contact endpoint | P1 | 0.5h | ⬜ | Prevent spam | | 6.9 | Test public contact flow | P1 | 1h | ⬜ | Full flow | --- ## Phase 7: Polish & Launch (4 days) ### 7.1 Error Handling | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------- | -------- | ------ | ------ | -------------------- | | 7.1.1 | Review all error messages | P0 | 2h | ⬜ | User-friendly | | 7.1.2 | Add error boundaries | P0 | 1h | ⬜ | React boundaries | | 7.1.3 | Add retry mechanisms | P1 | 2h | ⬜ | Network errors | | 7.1.4 | Add fallback UI states | P0 | 2h | ⬜ | Graceful degradation | ### 7.2 UX Polish | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------- | -------- | ------ | ------ | ----------------------- | | 7.2.1 | Add loading skeletons | P0 | 2h | ⬜ | All async states | | 7.2.2 | Add transition animations | P2 | 2h | ⬜ | Step transitions | | 7.2.3 | Mobile responsive testing | P0 | 2h | ⬜ | All breakpoints | | 7.2.4 | Accessibility audit | P1 | 2h | ⬜ | Screen reader, keyboard | ### 7.3 Analytics & Monitoring | # | Task | Priority | Effort | Status | Notes | | ----- | --------------------------- | -------- | ------ | ------ | ----------------- | | 7.3.1 | Add funnel tracking events | P1 | 2h | ⬜ | Google Analytics | | 7.3.2 | Add error tracking | P1 | 1h | ⬜ | Sentry or similar | | 7.3.3 | Create conversion dashboard | P1 | 2h | ⬜ | Metrics | ### 7.4 Documentation | # | Task | Priority | Effort | Status | Notes | | ----- | ------------------------------ | -------- | ------ | ------ | ---------- | | 7.4.1 | Update STRUCTURE.md | P1 | 1h | ⬜ | New routes | | 7.4.2 | Update catalog-and-checkout.md | P1 | 2h | ⬜ | New flow | | 7.4.3 | Create feature announcement | P1 | 1h | ⬜ | For users | ### 7.5 Launch Prep | # | Task | Priority | Effort | Status | Notes | | ----- | -------------------------------- | -------- | ------ | ------ | ---------------- | | 7.5.1 | Configure feature flags for prod | P0 | 1h | ⬜ | Gradual rollout | | 7.5.2 | Update production env vars | P0 | 0.5h | ⬜ | If needed | | 7.5.3 | Create rollback procedure | P0 | 1h | ⬜ | Document steps | | 7.5.4 | Prepare monitoring alerts | P0 | 1h | ⬜ | Error rate, etc. | | 7.5.5 | Schedule launch window | P0 | 0.5h | ⬜ | With team | --- ## Definition of Done Each task is considered **Done** when: - [ ] Code is written and follows project conventions - [ ] Unit tests pass (if applicable) - [ ] Code is reviewed and approved - [ ] Feature works in staging environment - [ ] No TypeScript errors - [ ] No ESLint warnings - [ ] Responsive design verified (if UI) --- ## Dependencies Graph ``` Phase 0 ✅ (SF Permissions verified, branch created) │ ↓ Phase 1 ──→ Phase 2 ──→ Phase 3 │ ↓ Phase 4 (SF Account Creation) │ ↓ Phase 5 (Integration Testing) │ ├──────────┬──────────┐ ↓ │ ↓ Phase 6 │ Phase 7 │ │ │ └──────────┴──────────┘ ↓ LAUNCH ``` ### Phase Dependencies Detail | Phase | Depends On | Blocks | | ------- | ------------------ | -------------------------------- | | Phase 0 | - | All phases | | Phase 1 | Phase 0 | Phase 3 (checkout needs catalog) | | Phase 2 | Phase 0 | Phase 3 (checkout needs cart) | | Phase 3 | Phase 1, 2 | Phase 5 | | Phase 4 | Phase 0 (SF perms) | Phase 5 | | Phase 5 | Phase 3, 4 | Phase 7 | | Phase 6 | Phase 0 | Launch | | Phase 7 | Phase 5 | Launch | --- ## Risk Register | Risk | Likelihood | Impact | Mitigation | Status | | ------------------------------------------- | ---------- | ------------ | ------------------------------------- | ------------ | | **SF Account creation fails** | Medium | **Critical** | Retry logic, clear errors, monitoring | Open | | ~~SF permission issues~~ | ~~Medium~~ | ~~Critical~~ | ~~Verify in Phase 0~~ | ✅ Mitigated | | **Partial registration (orphaned records)** | Medium | High | Rollback logic, cleanup procedures | Open | | SF API rate limits | Low | High | Monitor usage, batch if needed | Open | | WHMCS SSO reliability | Medium | High | Add retry logic, clear error messages | Open | | Performance regression | Low | Medium | Load test before launch | Open | | Security vulnerability | Low | Critical | Security review, pen test | Open | | Duplicate SF Accounts created | Low | Medium | Check by email before creating | Open | | User confusion with new flow | Medium | Low | Clear UX, help text | Open | ### Salesforce-Specific Risks | Risk | Mitigation | Status | | -------------------------------------------- | ------------------------------------- | ----------- | | ~~Integration user lacks CREATE on Account~~ | ~~Test in Phase 0~~ | ✅ Verified | | Required fields missing in SF org | Document all fields, validate payload | Open | | Customer number collision | Use SF auto-number or query for max | Open | | SF sandbox differs from production | Test in production-like sandbox | Open | | SF API timeout during registration | Add timeout handling, retry logic | Open | --- ## Contacts | Role | Name | Responsibility | | ------------ | ---- | ------------------------ | | Tech Lead | TBD | Architecture decisions | | Frontend Dev | TBD | UI implementation | | Backend Dev | TBD | API implementation | | QA | TBD | Testing | | Product | TBD | Requirements, acceptance | --- ## Changelog | Date | Change | Author | | ---------- | ------------------------- | ------ | | 2024-12-17 | Initial task list created | - |