UAT Overview

User Acceptance Testing (UAT) is the final quality gate before production release. This section covers everything testers need to validate the SONAN DIGITAL CRM in the staging environment.

---

What Exists in This Release

v1.0.0 is the first full production release of the SONAN DIGITAL CRM platform. It is a multi-tenant, edge-runtime SaaS application built on Next.js 15, Supabase, and Vercel. The following modules are fully implemented and in scope for UAT:

Module	Description
Authentication & MFA	Email/password login with TOTP multi-factor authentication for all user roles
Lead Management	Lead capture, pipeline status, conversion to client
Client Management	Client records, contact management, portal access provisioning
Proposal Builder	Line-item proposals, subtotal calculation, email delivery, client e-approval
Contract Management	Contract creation, e-signature workflow, client signing portal
Invoice Management	Invoice generation, Stripe Checkout integration, auto-paid status on webhook
Recurring Invoices	Cron-based recurring invoice generation
Project Management	Projects linked to clients, task assignment and tracking
Time Logging	Employee time entry against tasks
Support Tickets	Client ticket submission, employee reply, ticket closure
Document Sharing	Admin upload, signed URL delivery, client download portal
Deployment Tracking	Artifact tracking per project/client
Client Cost Ledger	Internal cost tracking for client engagements
Reports	Revenue report with CSV export, time log report by employee
In-App Wiki	Contextual help articles for users
Notification System	In-app bell notifications and email notifications
Employee Portal	Tasks, time logs, project view, ticket handling
Client Portal	Dashboard, proposals, contracts, invoices, documents, support tickets

---

What's New in This UAT Cycle

This is the v1.0 initial UAT cycle. There is no prior production baseline — the entire platform is being validated for the first time.

Security fixes applied prior to this UAT cycle:

• CRIT-4 — Tenant isolation enforcement on all admin API routes
• CRIT-7 — RLS policy gaps on the documents and contracts tables
• H8 — Client portal access token validation strengthened

---

UAT Objectives

The following objectives must be satisfied before sign-off is granted:

• [ ] Validate all CRM modules function correctly in the staging environment
• [ ] Confirm all three security fixes (CRIT-4, CRIT-7, H8) are effective and cannot be bypassed
• [ ] Verify the complete client portal flow end-to-end: invitation → login → MFA → proposal approval → contract signing → invoice payment → document download
• [ ] Validate the Stripe payment flow using test cards in the staging environment
• [ ] Confirm email delivery for all transactional emails (proposals, invoices, contracts, support replies)
• [ ] Confirm cron jobs execute correctly (recurring invoices, overdue detection)
• [ ] Verify report generation and CSV export accuracy

---

UAT Scope

In Scope

• All modules listed in the feature table above
• Admin, Employee, and Client portal roles
• Stripe Checkout payment flow (test mode)
• Email notifications via Resend
• TOTP MFA for all user types
• RLS and tenant isolation security checks

Out of Scope

• Production environment (do NOT test on production)
• Load/performance testing
• Penetration testing (covered separately)
• PDF generation (known issue HIGH-2, deferred to v1.1)
• Audit logging (known issue HIGH-3, deferred to v1.2)

---

UAT Documents

Document	Purpose
Execution Guide	Step-by-step test sequence for all five phases
Test Data	Required seed data, test accounts, Stripe test cards
Defect Log	Track and manage defects found during testing
Sign-Off	Acceptance criteria and sign-off form
Retest Process	How to retest resolved defects and run regression

---

UAT Timeline

Milestone	Target Date
Staging environment ready	2026-07-01
Test data seeded	2026-07-01
UAT execution begins	2026-07-02
UAT execution complete	2026-07-09
Defect resolution window	2026-07-10 – 2026-07-14
Retest complete	2026-07-15
Sign-off target	2026-07-16
Production release	2026-07-17

---

UAT Execution Guide

This guide defines the exact test sequence for UAT v1.0. Tests are organized into five phases. Execute phases in order — later phases depend on data created in earlier phases.

---

Before You Start

Environment Setup

1. Obtain the staging Vercel URL from the Technical Lead (format: https://sonan-digital-git-staging-<hash>.vercel.app or a named preview alias).
2. Open the URL in an incognito/private browser window to avoid session conflicts.
3. Confirm you can reach the login page before beginning any test phase.
4. Have a second browser profile or device ready for client portal tests — you will need to be logged in as admin and client simultaneously in some phases.
5. Keep the Defect Log open in a separate tab throughout testing.

Tools Required

• A modern browser (Chrome or Firefox recommended)
• An authenticator app (Google Authenticator, Authy, or 1Password) for MFA setup
• Access to the test email inboxes (see Test Data for email accounts)
• A Stripe test card (details in Test Data)

---

Phase 1 — Admin Core

These tests validate the fundamental admin experience: authentication, lead management, and client setup.

TC-1.1 Admin Login & MFA

Precondition: Admin test account exists in staging DB (see Test Data).

1. Navigate to the staging URL.
2. Enter the admin test email and password. Click Sign In.
3. Expected: MFA prompt appears requesting a TOTP code.
4. Open your authenticator app. Enter the current 6-digit code for the admin account.
5. Expected: Login succeeds. Admin dashboard loads. In-app notification bell is visible in the header.
6. Expected: URL is /admin/dashboard or /admin.

Pass criteria: Admin dashboard loads after valid TOTP code. Invalid TOTP code is rejected.

---

TC-1.2 Create a Lead & Verify Notification

1. In the admin sidebar, navigate to Leads.
2. Click New Lead (or equivalent action button).
3. Fill in the lead form:
4. Name: UAT Test Lead
5. Email: uat-lead@example.com
6. Phone: +1 555 000 0001
7. Source: Website
8. Status: New
9. Submit the form.
10. Expected: Lead appears in the leads list with status New.
11. Check the notification bell in the header.
12. Expected: A new_lead notification is present: "New lead received — UAT Test Lead".

Pass criteria: Lead created successfully. Notification generated and visible in-app.

---

TC-1.3 Convert Lead to Client

1. Open the UAT Test Lead lead record created in TC-1.2.
2. Find and click the Convert to Client action.
3. Expected: A confirmation prompt or conversion form appears.
4. Confirm the conversion.
5. Expected: Lead status updates to Converted. A new client record UAT Test Lead appears in the Clients list.
6. Navigate to Clients and confirm the record exists.

Pass criteria: Lead is converted. Client record created. Lead marked converted.

---

TC-1.4 Add Contacts to Client

1. Navigate to Clients and open the UAT Test Lead client record.
2. Find the Contacts section and click Add Contact.
3. Fill in:
4. Name: Jane UAT
5. Email: jane.uat@example.com
6. Phone: +1 555 000 0002
7. Title: Project Manager
8. Is Primary: checked
9. Save the contact.
10. Expected: Contact appears in the client's contacts list with a "Primary" indicator.
11. Add a second contact (non-primary) with different details.
12. Expected: Both contacts are listed. Only the first is marked primary.

Pass criteria: Multiple contacts can be added to a client. Primary flag works correctly.

---

Phase 2 — Proposals & Contracts

These tests validate the proposal-to-contract workflow. Requires the client created in Phase 1.

TC-2.1 Create Proposal with Line Items

1. Navigate to Proposals (or access via the client record). Click New Proposal.
2. Associate the proposal with the UAT Test Lead client.
3. Add three line items:

Description	Quantity	Unit Price
Website Design	1	$1,000.00
SEO Setup	3	$250.00
Monthly Retainer	2	$500.00

1. Expected: Subtotal calculates to $2,750.00 automatically.
2. Add a title: UAT Proposal v1.
3. Add an optional note: This is a UAT test proposal.
4. Save the proposal as a draft.
5. Expected: Proposal saved with status Draft. Subtotal shown is $2,750.00.

Pass criteria: Three line items accepted. Subtotal calculated correctly. Draft saved.

---

TC-2.2 Send Proposal — Verify Client Email

1. Open the UAT Proposal v1 draft.
2. Click Send to Client.
3. Expected: Proposal status changes to Sent. A confirmation message indicates the email was dispatched.
4. Open the client test email inbox (see Test Data).
5. Expected: An email from the system arrives within 2 minutes with subject referencing the proposal. The email contains a link to view/approve the proposal.

Pass criteria: Proposal status updated to Sent. Email received in client inbox with correct content and link.

---

TC-2.3 Client Approves Proposal

1. Switch to the client browser session (incognito window).
2. Log in as the client portal test account (see Test Data).
3. Navigate to Proposals in the client portal.
4. Open UAT Proposal v1.
5. Expected: Proposal details displayed with all three line items and the $2,750.00 subtotal.
6. Click Approve.
7. Expected: Proposal status updates to Approved. A success message is shown.
8. Switch back to admin session.
9. Open UAT Proposal v1 in admin.
10. Expected: Status is Approved. Timestamp of approval is recorded.

Pass criteria: Client can view and approve proposal. Admin sees updated status.

---

TC-2.4 Convert Proposal to Invoice

1. Open the approved UAT Proposal v1 in admin.
2. Click Convert to Invoice.
3. Expected: An invoice is created pre-populated with the proposal line items and $2,750.00 subtotal. Invoice status is Draft.
4. Confirm the invoice record is visible under Invoices.

Pass criteria: Invoice created from proposal with correct amounts. No data loss during conversion.

---

TC-2.5 Create & Send Contract

1. Navigate to Contracts. Click New Contract.
2. Associate with UAT Test Lead client.
3. Enter a contract title: UAT Service Agreement v1.
4. Enter contract body text (a few paragraphs of placeholder terms).
5. Save and click Send for Signature.
6. Expected: Contract status changes to Pending Signature. Email sent to client.
7. Check the client test inbox.
8. Expected: Email received with a link to review and sign the contract.

Pass criteria: Contract created and sent. Status reflects pending. Email delivered.

---

TC-2.6 Client Signs Contract

1. Switch to client browser session.
2. Navigate to Contracts in the client portal, or follow the link from the email.
3. Open UAT Service Agreement v1.
4. Expected: Contract text displayed in full.
5. Click Sign Contract (or equivalent action — may require typing name or clicking signature area).
6. Expected: Contract status updates to Signed. Confirmation shown to client.
7. Switch back to admin session.
8. Open the contract in admin.
9. Expected: Status is Signed. Signature timestamp recorded.
10. Expected: A contract_signed notification appears in the admin notification bell.

Pass criteria: Client can sign contract. Admin sees signed status and receives notification.

---

Phase 3 — Invoices & Payments

These tests validate the full invoice-to-payment flow including Stripe Checkout.

TC-3.1 Send Invoice — Verify Email

1. In admin, navigate to Invoices and open the invoice created in TC-2.4.
2. Review the invoice details. Set a due date if not pre-populated.
3. Click Send Invoice.
4. Expected: Invoice status changes to Sent. Confirmation message shown.
5. Open the client test email inbox.
6. Expected: Invoice email received with the amount ($2,750.00) and a Pay Now link.

Pass criteria: Invoice email received. Pay Now link present in email.

---

TC-3.2 Client Pays Invoice via Stripe

1. Switch to client browser session.
2. Navigate to Invoices in the client portal. Open the invoice.
3. Expected: Invoice shows amount due $2,750.00 and a Pay Now button.
4. Click Pay Now.
5. Expected: Redirected to Stripe Checkout page. Amount shown matches invoice.
6. Enter the Stripe test card:
7. Card Number: 4242 4242 4242 4242
8. Expiry: Any future date (e.g., 12/28)
9. CVC: Any 3 digits (e.g., 123)
10. Name: Any name
11. Click Pay.
12. Expected: Stripe Checkout shows payment success. Redirected back to the client portal.

Pass criteria: Stripe Checkout loads with correct amount. Test card payment accepted.

---

TC-3.3 Invoice Auto-Marked Paid After Webhook

1. After TC-3.2, wait up to 60 seconds for the Stripe webhook to process.
2. Switch to admin session. Navigate to Invoices.
3. Open the invoice.
4. Expected: Invoice status is Paid. Payment date recorded. Amount paid matches.
5. Expected: A invoice_paid notification appears in the admin notification bell.
6. Switch to client session. Open the invoice.
7. Expected: Invoice shows "Paid" status to the client as well.

Pass criteria: Invoice auto-marked paid via Stripe webhook. Both admin and client see paid status.

---

Phase 4 — Operations

These tests validate day-to-day operational features: time logging, support tickets, and related workflows.

TC-4.1 Log Time Against a Task

1. Ensure a project with at least one task exists (created during test data seeding — see Test Data).
2. Log in as the employee test account in a separate session.
3. Navigate to My Tasks or Time Logs in the employee portal.
4. Click Log Time.
5. Select the project and task.
6. Enter:
7. Hours: 3.5
8. Date: Today
9. Note: UAT time log entry
10. Save.
11. Expected: Time log entry appears in the employee's time log list.
12. Switch to admin session. Navigate to Reports → Time Logs.
13. Expected: The 3.5-hour entry for the employee is visible.

Pass criteria: Time log created by employee. Visible in admin reports.

---

TC-4.2 Create Support Ticket as Client

1. Switch to client session.
2. Navigate to Support in the client portal. Click New Ticket.
3. Fill in:
4. Subject: UAT Test Ticket
5. Message: This is a UAT test support request. Please acknowledge.
6. Priority: Normal (if available)
7. Submit the ticket.
8. Expected: Ticket created with status Open. Confirmation shown to client.

Pass criteria: Support ticket created from client portal.

---

TC-4.3 Employee Replies to Ticket

1. Switch to employee session (or admin session — whichever has ticket management access).
2. Navigate to Support Tickets.
3. Open UAT Test Ticket.
4. Expected: Ticket details and original message displayed.
5. Enter a reply: Thank you for your message. We have received your request and will follow up shortly.
6. Click Reply (or Send).
7. Expected: Reply is appended to the ticket thread.
8. Switch to client session. Open the ticket.
9. Expected: Employee reply visible in the ticket thread.
10. Expected: A support_reply notification visible to the client (in-app and/or email).

Pass criteria: Employee can reply. Client sees reply. Notification delivered.

---

TC-4.4 Close Support Ticket

1. In the employee/admin session, open UAT Test Ticket.
2. Click Close Ticket (or change status to Closed).
3. Expected: Ticket status updates to Closed.
4. Switch to client session. Open the ticket.
5. Expected: Ticket shows as Closed. Client cannot submit additional replies (if that is the intended behavior — note if not enforced).

Pass criteria: Ticket can be closed by employee/admin. Closed status visible to client.

---

Phase 5 — Documents & Reports

TC-5.1 Upload Document for Client

1. In admin session, navigate to Documents (or open the UAT Test Lead client and go to the Documents tab).
2. Click Upload Document.
3. Select a small PDF or text file from your local machine (< 2 MB).
4. Set the document name: UAT Test Document.
5. Associate with UAT Test Lead client.
6. Click Upload.
7. Expected: Document appears in the client's document list with name, upload date, and file size.

Pass criteria: Document uploads successfully. Listed in admin view.

---

TC-5.2 Client Downloads Document

1. Switch to client session.
2. Navigate to Documents in the client portal.
3. Expected: UAT Test Document is listed.
4. Click Download (or the document link).
5. Expected: File downloads successfully. File is not corrupted.

Pass criteria: Client can see and download the document uploaded by admin.

---

TC-5.3 Revenue Report & CSV Export

1. In admin session, navigate to Reports → Revenue.
2. Set the date range to cover the current month.
3. Expected: Revenue report loads. The invoice paid in TC-3.3 ($2,750.00) is included.
4. Click Export CSV.
5. Expected: A CSV file downloads containing at least one row with the invoice data.
6. Open the CSV and verify:
7. Client name matches
8. Amount matches ($2,750.00)
9. Date matches

Pass criteria: Revenue report is accurate. CSV export includes correct data.

---

TC-5.4 Time Logs Report

1. Navigate to Reports → Time Logs.
2. Filter by the employee used in TC-4.1.
3. Expected: The 3.5-hour log entry is listed with the correct date, task, and note.
4. Verify the total hours sum is correct if multiple entries exist.

Pass criteria: Time log report returns accurate data for the selected employee.

---

Defect Logging

When a test step fails:

1. Open Defect Log.
2. Add a new row to the defect table.
3. Include:
4. A unique ID (DEF-XXX, next in sequence)
5. The exact test case that failed (e.g., TC-3.3)
6. Steps to reproduce (copy the failing steps from this guide)
7. Expected vs. actual result
8. Severity (see defect log severity table)
9. Screenshot or screen recording filename
10. Notify the assigned engineer in the team channel.
11. Do NOT continue testing dependent steps until Critical defects are resolved.

---

Exit Criteria

UAT execution is complete when ALL of the following are true:

• [ ] All test cases TC-1.1 through TC-5.4 have been executed
• [ ] All Critical (P1) test cases have a PASS result
• [ ] All High (P2) test cases have a PASS result or a documented accepted risk
• [ ] Open defects: zero Critical, zero High (or formally accepted in defect log)
• [ ] Sign-off form in sign-off.md is completed and approved

Proceed to Sign-Off when exit criteria are met.

---

UAT Test Data

This page documents all test data required for the v1.0 UAT cycle, including required seed records, test accounts, Stripe test cards, and data reset procedures.

---

Required Seed Data

The following records must exist in the staging Supabase database before UAT execution begins. The Technical Lead is responsible for seeding this data.

Tenant Record

Field	Value
Name	SONAN DIGITAL Test Tenant
Slug	sonan-uat
Plan	Pro (or highest available tier)
Status	Active

User Accounts

Role	Full Name	Email	Notes
Admin	UAT Admin	uat-admin@sonandigital.test	Primary tester account, MFA enabled
Employee	UAT Employee	uat-employee@sonandigital.test	Used for time logs, ticket replies
Client	UAT Client	uat-client@sonandigital.test	Portal access provisioned

Client Records

Two client records must be pre-seeded:

Client Name	Status	Portal Access	Notes
Pre-Seeded Client A	Active	Yes — uat-client@sonandigital.test	Used for portal flow tests
Pre-Seeded Client B	Active	No	Used for admin-only flows

Lead Record

Field	Value
Name	Pre-Seeded Lead
Email	preseed-lead@sonandigital.test
Status	New
Source	Referral

This pre-seeded lead is used to verify the leads list loads correctly. The test execution creates its own lead (TC-1.2).

Project & Tasks

Field	Value
Project Name	UAT Test Project
Client	Pre-Seeded Client A
Status	Active
Task 1	UAT Task Alpha (assigned to UAT Employee)
Task 2	UAT Task Beta (assigned to UAT Employee)

These tasks are referenced in TC-4.1 (time logging).

---

Test Accounts

Role	Email	Password	MFA TOTP Seed	Portal URL
Admin	uat-admin@sonandigital.test	[SET BY TECH LEAD]	[TOTP SEED — scan QR or enter in authenticator]	/auth/login → admin dashboard
Employee	uat-employee@sonandigital.test	[SET BY TECH LEAD]	[TOTP SEED]	/auth/login → employee portal
Client	uat-client@sonandigital.test	[SET BY TECH LEAD]	[TOTP SEED]	/portal/login or invite link

Setting Up MFA for Test Accounts

1. The Technical Lead provisions the accounts and generates TOTP secrets.
2. Scan the provided QR code (or manually enter the seed) into your authenticator app (Google Authenticator, Authy, 1Password).
3. Verify the code is working before starting UAT by logging in once to confirm the TOTP is accepted.
4. If you need the TOTP seed reset, contact the Technical Lead — do not attempt to reset it yourself.

Email Inboxes for Test Accounts

Emails sent to @sonandigital.test addresses during UAT need to be checked. The staging Resend configuration should route to a test inbox or use the Resend test mode where emails are captured in the Resend dashboard rather than delivered.

To view test emails during UAT:

1. Log into the Resend dashboard at https://resend.com.
2. Navigate to Emails in the sidebar.
3. Filter by the staging API key domain.
4. All outbound emails from the staging environment will appear here.

Alternatively, if the Technical Lead has configured email routing to a real test inbox (e.g., a shared team inbox), use those credentials to access email during UAT.

---

Stripe Test Cards

All Stripe interactions during UAT use Stripe's test mode. The following cards can be used:

Primary Test Cards

Scenario	Card Number	Expiry	CVC	Expected Result
Success	4242 4242 4242 4242	Any future date	Any 3 digits	Payment succeeds immediately
Declined	4000 0000 0000 0002	Any future date	Any 3 digits	Card declined — use to test error handling
3D Secure Required	4000 0025 0000 3155	Any future date	Any 3 digits	3DS authentication challenge appears
Insufficient Funds	4000 0000 0000 9995	Any future date	Any 3 digits	Payment fails with insufficient funds

Stripe Test Mode Verification

Before running payment tests (TC-3.2), confirm the staging environment is in Stripe test mode:

1. The Stripe Checkout page should show a banner: "Test mode" in the top-left.
2. In the Vercel staging environment variables, STRIPE_SECRET_KEY must begin with sk_test_.
3. If you see no test mode banner, stop and notify the Technical Lead immediately — you may be connected to live mode.

---

Recommended Test Invoice Amounts

Use these amounts during UAT to make verification straightforward:

Use Case	Proposed Amount	Why
Simple single-line invoice	$100.00	Easy to verify in Stripe dashboard
Multi-line proposal (TC-2.1)	$2,750.00	Three line items, round numbers
Medium invoice	$250.00	Tests two-digit dollar, three-digit cent-free
Large invoice	$1,000.00	Tests four-digit amounts in reports

---

Data Reset Between UAT Runs

If UAT needs to be run more than once (e.g., after a major defect fix that requires full re-execution), test data should be reset before the second run. This prevents stale records from corrupting test expectations.

Reset Procedure

The Technical Lead runs the following SQL in the Supabase SQL editor against the staging project:

-- SONAN DIGITAL UAT Data Reset Script
-- Run ONLY against staging. Confirm tenant_id before executing.

DO $$
DECLARE
  v_tenant_id UUID := '[UAT TENANT ID]'; -- Replace with staging UAT tenant UUID
BEGIN

  -- Remove notifications
  DELETE FROM notifications WHERE tenant_id = v_tenant_id;

  -- Remove time logs (via tasks → projects → clients → tenant)
  DELETE FROM time_logs
  WHERE task_id IN (
    SELECT t.id FROM tasks t
    JOIN projects p ON p.id = t.project_id
    WHERE p.tenant_id = v_tenant_id
  );

  -- Remove tasks
  DELETE FROM tasks
  WHERE project_id IN (
    SELECT id FROM projects WHERE tenant_id = v_tenant_id
  );

  -- Remove support tickets
  DELETE FROM support_tickets WHERE tenant_id = v_tenant_id;

  -- Remove documents
  DELETE FROM documents WHERE tenant_id = v_tenant_id;

  -- Remove invoices
  DELETE FROM invoices WHERE tenant_id = v_tenant_id;

  -- Remove contracts
  DELETE FROM contracts WHERE tenant_id = v_tenant_id;

  -- Remove proposals
  DELETE FROM proposals WHERE tenant_id = v_tenant_id;

  -- Remove projects
  DELETE FROM projects WHERE tenant_id = v_tenant_id;

  -- Remove contacts
  DELETE FROM contacts
  WHERE client_id IN (
    SELECT id FROM clients WHERE tenant_id = v_tenant_id
  );

  -- Remove clients created during UAT (keep pre-seeded ones if needed)
  -- To remove only the test-converted client:
  DELETE FROM clients WHERE tenant_id = v_tenant_id AND name = 'UAT Test Lead';

  -- Remove leads created during UAT
  DELETE FROM leads WHERE tenant_id = v_tenant_id AND name = 'UAT Test Lead';

  RAISE NOTICE 'UAT data reset complete for tenant %', v_tenant_id;
END $$;

After running the script:

1. Verify the staging dashboard shows only the pre-seeded records.
2. Re-run the seed script (maintained by the Technical Lead) to restore the required baseline.
3. Confirm test accounts still have valid MFA secrets (they should be unaffected by the data reset).
4. Notify all testers that the environment has been reset and UAT can restart from TC-1.1.

---

UAT Defect Log

This page is the authoritative record of all defects found during UAT v1.0. Every issue, regardless of severity, must be logged here before being communicated to engineering.

---

Severity Classification

Severity	Label	Definition	Examples
Critical	P1	System crash, data loss, security breach, payment processing failure, or complete feature breakdown with no workaround	Webhook not marking invoice paid; tenant data visible to wrong tenant; payment charged but not recorded
High	P2	Major feature broken; prevents completion of a core user journey; no acceptable workaround	Proposal subtotal calculates incorrectly; client cannot log into portal; contract signing page throws error
Medium	P3	Feature partially broken; a workaround exists; user experience significantly degraded	Email notification delayed by >10 minutes; report missing one record; date picker does not work on Firefox
Low	P4	Cosmetic issue, minor UX friction, typo, or non-functional visual defect	Button alignment off on mobile; spelling error in notification body; icon missing in sidebar

---

Defect Status Values

Status	Meaning
Open	Defect reported, not yet assigned or investigated
In Progress	Engineering is actively working on the fix
Resolved	Fix deployed to staging, pending retest
Deferred	Accepted as known issue, not fixing before v1.0 go-live
Won't Fix	Engineering reviewed and determined not to fix (with documented rationale)

---

Defect Log Table

ID	Date	Tester	Module	Summary	Steps to Reproduce	Expected	Actual	Severity	Status	Assigned To	Resolution Date
DEF-001	2026-06-30	A. Hassan	Invoices / Stripe	Invoice not marked paid after successful Stripe Checkout payment	1. Create and send invoice. 2. Log in as client. 3. Click Pay Now. 4. Complete payment with card 4242... 5. Wait 2 minutes. 6. Check invoice status in admin.	Invoice status changes to Paid within 60 seconds of payment via Stripe webhook	Invoice status remains Sent. No invoice_paid notification generated. Stripe dashboard shows payment succeeded.	Critical	Resolved	Dev Team	2026-07-01
DEF-002	2026-06-30	A. Hassan	Proposals	Proposal subtotal calculation produces incorrect result when line item quantity is a decimal (e.g., 1.5 hours)	1. Create new proposal. 2. Add line item: Description = "Consulting", Qty = 1.5, Unit Price = $200.00. 3. Observe subtotal field.	Subtotal = $300.00 (1.5 × $200)	Subtotal shows $200.00 — decimal quantity appears to be floored to integer before multiplication	High	Open	Dev Team	—
DEF-003	2026-07-01	S. Reyes	Client Portal	Mobile navigation menu overlaps main content on iOS Safari (iPhone 13, iOS 16)	1. Log in as client on iPhone 13 with iOS 16 Safari. 2. Tap the hamburger menu icon. 3. Observe menu panel position.	Navigation menu slides in as overlay above content; background content is not interactable	Menu opens but overlaps and partially obscures the main content area; some content behind menu remains clickable	Low	Deferred	—	Post-v1.0

---

How to Submit a Defect

Follow this process for every defect found during UAT:

Step 1 — Reproduce the Defect

Before logging, confirm you can reproduce the defect at least twice using the exact steps from the test case. If you cannot reproduce it consistently, mark it as "Intermittent" in the summary.

Step 2 — Capture Evidence

Capture one or more of the following before logging:

• Screenshot — name it DEF-XXX-screenshot-1.png and attach to the shared UAT evidence folder
• Screen recording — name it DEF-XXX-recording.mp4
• Browser console output — copy and paste relevant errors into the notes column or a separate text file DEF-XXX-console.txt
• Network request — if the defect involves API failures, capture the failing request from DevTools Network tab

Step 3 — Add Row to the Defect Table

Copy the row format from the examples above. Fill in every column:

• ID — use the next sequential DEF number
• Date — today's date (YYYY-MM-DD)
• Tester — your name or initials
• Module — the CRM module where the defect was found (e.g., Proposals, Invoices, Client Portal)
• Summary — one concise sentence describing what is wrong
• Steps to Reproduce — numbered, exact steps starting from a known state
• Expected — what should happen according to the spec or reasonable expectation
• Actual — what actually happened
• Severity — use the severity table above
• Status — set to Open on initial submission
• Assigned To — leave blank; engineering will self-assign
• Resolution Date — leave blank until resolved

Step 4 — Notify Engineering

After adding the row to this log:

1. Post a message in the team engineering channel (Slack/Discord/Teams — whichever the team uses).
2. Include the defect ID, severity, and one-line summary.
3. Link to this defect log page.
4. For Critical defects, also send a direct message to the Technical Lead.

Step 5 — Track Resolution

Engineering will update the Status and Assigned To columns as work progresses. When status changes to Resolved, the tester who logged the defect must run the retest procedure in Retest Process.

---

Defect Metrics Summary

Update this table at the end of each UAT day.

Date	New Defects	Critical	High	Medium	Low	Total Open	Total Resolved
2026-06-30	2	1	1	0	0	1	1
2026-07-01	1	0	0	0	1	1	1

---

UAT Sign-Off

This page defines the acceptance criteria for UAT completion and provides the sign-off form template that must be completed before production release is authorized.

---

UAT Acceptance Criteria

All of the following conditions must be satisfied for UAT to receive a PASS decision:

Test Execution

• [ ] All Phase 1 test cases (TC-1.1 through TC-1.4) executed and passed
• [ ] All Phase 2 test cases (TC-2.1 through TC-2.6) executed and passed
• [ ] All Phase 3 test cases (TC-3.1 through TC-3.3) executed and passed
• [ ] All Phase 4 test cases (TC-4.1 through TC-4.4) executed and passed
• [ ] All Phase 5 test cases (TC-5.1 through TC-5.4) executed and passed

Defect Status

• [ ] Zero open Critical (P1) defects
• [ ] Zero open High (P2) defects, OR all open High defects have been formally accepted with documented rationale in the defect log
• [ ] All resolved defects have been retested per the Retest Process and confirmed fixed

Critical Flows

• [ ] Stripe payment flow verified end-to-end in staging (Checkout → Webhook → Invoice marked paid)
• [ ] Client portal invitation flow verified: invite sent → account created → MFA enrolled → login succeeds
• [ ] E-signature flow verified: contract sent → client signs → admin notified → status updated
• [ ] Client portal proposal approval flow verified end-to-end

Security Verification

• [ ] CRIT-4 — Tenant isolation: verified that admin API routes reject requests for resources belonging to a different tenant
• [ ] CRIT-7 — RLS gaps: verified that documents and contracts records are not accessible to users outside the owning tenant (test with a second test tenant if available, or review Supabase RLS policies directly)
• [ ] H8 — Client portal access token: verified that client portal rejects expired or tampered session tokens

Email Delivery

• [ ] Proposal email received by client (TC-2.2)
• [ ] Contract email received by client (TC-2.5)
• [ ] Invoice email received by client (TC-3.1)
• [ ] Support reply notification received by client (TC-4.3)

---

Decision Options

Decision	Meaning
PASS	All acceptance criteria met. Production release authorized.
CONDITIONAL PASS	All Critical criteria met. One or more High defects deferred with documented acceptance. Production release authorized subject to stated conditions.
FAIL	One or more Critical criteria not met, or unresolved Critical defects exist. Production release is blocked. Retest required after fixes.

---

Sign-Off Form Template

Complete this form and return it to the Technical Lead. Both signatories must complete their own copy.

---

SONAN DIGITAL CRM — UAT SIGN-OFF FORM
Version: v1.0 Initial Release

──────────────────────────────────────────────
UAT CYCLE DETAILS
──────────────────────────────────────────────
UAT Cycle:            v1.0 Initial
Testing Period:       [Start Date: YYYY-MM-DD] – [End Date: YYYY-MM-DD]
Test Environment URL: [Staging Vercel URL]
Git Commit / Branch:  [Staging deployment commit SHA or branch name]

──────────────────────────────────────────────
TESTER DETAILS
──────────────────────────────────────────────
Tester Name:    ________________________________
Role:           ________________________________  (Technical Lead / Business Owner)
Organization:   SONAN DIGITAL
Date:           ________________________________

──────────────────────────────────────────────
ACCEPTANCE CRITERIA CHECKLIST
──────────────────────────────────────────────
[ ] All P1 (Critical) test cases passed
[ ] All P2 (High) test cases passed or formally deferred
[ ] Zero open Critical defects
[ ] Zero open High defects (or all accepted with rationale)
[ ] Stripe payment flow verified
[ ] Client portal invitation and MFA flow verified
[ ] E-signature (contract sign) flow verified
[ ] Security fixes CRIT-4, CRIT-7, H8 verified
[ ] All resolved defects retested and confirmed

──────────────────────────────────────────────
SIGN-OFF DECISION
──────────────────────────────────────────────
Decision:   [ ] PASS   [ ] CONDITIONAL PASS   [ ] FAIL

Conditions (required if CONDITIONAL PASS):
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________

Notes / Observations:
__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________

──────────────────────────────────────────────
SIGNATURE
──────────────────────────────────────────────
Signed: ________________________________   Date: ________________
Print:  ________________________________
Role:   ________________________________

---

Who Signs

Two signatories are required:

Signatory	Role	Responsibility
Technical Lead	Engineering / QA	Confirms all technical test cases passed, security fixes verified, no outstanding critical bugs
Business Owner	Product / Management	Confirms the product meets business requirements, client portal experience is acceptable, ready for client-facing release

Both forms must be signed before the production release checklist (releases/v1.0/release-checklist.md) can proceed.

---

After Sign-Off

Once both signatories have signed:

1. Technical Lead updates the defect log to mark UAT as complete.
2. Technical Lead proceeds through the production release checklist at Release Checklist.
3. The signed forms are archived (scan to PDF and store in the project shared drive under UAT/Sign-offs/v1.0/).
4. Engineering schedules the production deployment.
5. Stakeholders are notified of the impending go-live date.

---

UAT Retest Process

This page describes how to retest defects once engineering marks them as Resolved, and how to determine the regression scope for each type of fix.

---

When to Retest

A retest is triggered when a defect in the Defect Log has its status changed from In Progress to Resolved by engineering. This means a fix has been deployed to the staging environment and is ready for verification.

Do not retest against the same staging build that contained the original defect. Always confirm a new deployment is in place.

---

Retest Scope

Retest scope depends on defect severity:

Critical (P1) Defects

• Re-execute the exact steps from the original defect report.
• Re-execute all test cases in the Phase that contained the defect.
• Example: DEF-001 (invoice not marked paid) is in Phase 3 → re-run TC-3.1, TC-3.2, and TC-3.3.
• Verify that the fix did not introduce a regression in adjacent Phases.

High (P2) Defects

• Re-execute the exact steps from the original defect report.
• Re-execute all test cases in the affected module.
• Example: DEF-002 (proposal subtotal with decimal qty) is in the Proposals module → re-run TC-2.1 through TC-2.4.

Medium (P3) Defects

• Re-execute the exact steps from the original defect report only.
• Spot-check one adjacent test case if the fix touched shared code (e.g., a shared component or utility function).

Low (P4) Defects

• Re-execute the exact steps from the original defect report only.
• Visual/cosmetic issues: confirm the visual is correct in the affected browser and one other browser.

---

Retest Procedure

Follow these steps for every retest:

1. Confirm the staging build is updated. Check with engineering or verify the Vercel deployment timestamp.

2. Re-execute the failing steps exactly as documented in the defect log. Do not skip steps or alter the order.

3. Observe the result:

4. If the defect is fixed → continue to step 4.
5. If the defect is still present → the fix did not work. Update the defect status back to Open and add a comment in the Notes column: RETEST FAILED YYYY-MM-DD by [Tester]. Notify engineering.

6. If the fix introduced a new issue → log a new defect (new DEF-XXX ID) and link it to the original defect in the summary: Introduced by fix for DEF-XXX.

7. Run regression scope per the severity table above.

8. Update the defect log:

9. Change Status from Resolved to confirmed Resolved (add retest date/tester if the table has columns for it, or add a note in the Resolution Date column: Resolved + Retested YYYY-MM-DD by [Tester]).

10. Notify the team that the defect has been retested and confirmed fixed.

---

Regression Test Matrix

Use this matrix to determine which test cases to re-run for a given type of fix:

Fix Type	Affected Area	Regression Scope
Stripe webhook handler	Payment processing	TC-3.2, TC-3.3; verify invoice status updates
Proposal calculation logic	Proposal builder	TC-2.1 (all line item combinations); check invoice conversion amount TC-2.4
RLS policy change	Database security	All cross-tenant operations; verify tenant A cannot see tenant B data
Auth / session handling	Login, MFA, portal access	TC-1.1 (admin login), TC-2.3 (client login), TC-3.2 (client payment)
Email delivery (Resend integration)	Notifications	TC-2.2, TC-2.5, TC-3.1, TC-4.3
Client portal routing / access control	Client portal	TC-2.3, TC-2.6, TC-3.2, TC-5.2
Supabase query / FK join fix	Any data-fetch endpoint	Re-run all test cases in the module that was fixed
CSS / layout change	Visual presentation	Re-run affected TC on Chrome, Firefox, and mobile (if Low severity fix)
Cron job logic	Recurring invoices, overdue detection	Cannot be fully tested in manual UAT — verify by checking cron job logs or simulating a cron trigger
Document upload / storage	Document sharing	TC-5.1, TC-5.2
Report generation / CSV export	Reports	TC-5.3, TC-5.4

---

Re-Sign-Off Requirement

When Re-Sign-Off is NOT Required

• A Low or Medium defect is fixed and retested successfully.
• A High defect is fixed, retested, and no regression is found.
• The fix is limited to a cosmetic or non-functional area.

When Re-Sign-Off IS Required

Re-sign-off is required if any of the following occur during retest:

• A new Critical defect is found (regardless of whether it was introduced by the fix or pre-existing).
• A fix for a Critical defect fails the retest.
• Regression testing reveals a previously passing Phase now fails.
• The scope of retesting was broader than a single module and multiple new issues were found.

Re-Sign-Off Procedure

1. Reset the UAT sign-off status — the previous signed form is void.
2. Notify the Business Owner and Technical Lead immediately.
3. Engineering addresses the new or regressed defects.
4. Run a targeted retest covering the newly identified issues.
5. If all issues are resolved, complete a new sign-off form (see Sign-Off).
6. Archive both the original (failed) and new (passed) sign-off forms in the project shared drive.

---

Retest Log

Track all retest activity in this table:

DEF ID	Retest Date	Tester	Staging Build / Commit	Result	Notes
DEF-001	2026-07-01	A. Hassan	abc1234	PASS	Invoice marked paid within 30s of payment. Webhook confirmed in Vercel logs.
DEF-002	—	—	—	Pending	Awaiting engineering fix
DEF-003	—	—	—	Deferred	Accepted for v1.0, will fix in v1.1