Assist_Design/docs/plans/2026-02-24-uat-guidebook-design.md

UAT Guidebook Design

Date: 2026-02-24 Status: Approved

Goal

Create a UAT reference guidebook that explains each user journey in the Customer Portal, including what happens in WHMCS and Salesforce, so testers can verify end-to-end behavior.

Audience

QA testers who are familiar with WHMCS and Salesforce admin panels but do not have deep technical knowledge (no code, no API details).

Format

• Markdown files in docs/uat/
• Text descriptions only (no screenshots)
• Organized by user journey
• Reference guide style (not test scripts)

Structure

docs/uat/
├── README.md                              # Overview, how to use this guide
├── 01-signup-and-account-creation.md
├── 02-login-and-authentication.md
├── 03-dashboard-and-profile.md
├── 04-browsing-services.md
├── 05-ordering-a-service.md
├── 06-managing-sim-subscriptions.md
├── 07-managing-internet-subscriptions.md
├── 08-managing-vpn-subscriptions.md
├── 09-billing-and-invoices.md
├── 10-support-cases.md
├── 11-identity-verification.md
├── 12-notifications.md
├── 13-address-management.md
└── appendix-cross-reference.md            # Portal <-> WHMCS <-> Salesforce mapping

Journey File Template

Each journey file follows a consistent structure:

1. Overview - What this journey covers (2-3 sentences)
2. Portal Flow - Step-by-step what the user does, organized by sub-flows
3. What Happens in WHMCS - Records created/updated, where to find them
4. What Happens in Salesforce - Records created/updated, where to find them
5. Key Things to Verify - What testers should pay attention to

Approach

• Explore the actual codebase (portal pages, BFF services, domain mappers, integration docs) to understand real behavior
• Write from the tester's perspective: "When you do X, you should see Y"
• Use plain language, avoid code references or technical jargon
• Mention specific WHMCS/Salesforce object names and fields testers can look up