Assist_Design/docs/_archive/planning/PUBLIC-CATALOG-TASKS.md

Public Catalog & Unified Checkout - Task Checklist

Related: See 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	-