Commit misc scripts, feature specs, SQL deploy scripts, and settings updates
This commit is contained in:
@@ -0,0 +1,258 @@
|
||||
# Guided Activation Flow Feature Spec
|
||||
|
||||
## Overview
|
||||
|
||||
This feature introduces a **post-setup guided activation flow** for new companies.
|
||||
|
||||
After completing the setup wizard, users should be guided through their **first real workflow** so they understand how to use the system immediately.
|
||||
|
||||
This is NOT a tooltip tour.
|
||||
|
||||
This is a **guided outcome flow using real system actions** (quotes, jobs, invoices).
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
Current behavior:
|
||||
- Users complete setup wizard
|
||||
- Land on dashboard
|
||||
- Do not create quotes, jobs, or invoices
|
||||
- Drop off
|
||||
|
||||
Goal:
|
||||
- Ensure users complete at least ONE real workflow
|
||||
- Create an "aha moment" within first session
|
||||
|
||||
---
|
||||
|
||||
## Business Workflows
|
||||
|
||||
### 1. Quote-First Workflow
|
||||
- Create Quote
|
||||
- Send to customer
|
||||
- Convert Quote → Job
|
||||
- Process Job
|
||||
- Create Invoice
|
||||
- Customer Pays
|
||||
|
||||
### 2. Job-First Workflow (Walk-in)
|
||||
- Create Job directly
|
||||
- Process Job
|
||||
- Create Invoice
|
||||
- Customer Pays
|
||||
|
||||
---
|
||||
|
||||
## Feature Behavior
|
||||
|
||||
### Trigger Condition
|
||||
|
||||
IF:
|
||||
- setup wizard is completed
|
||||
- AND firstWorkflowCompleted == false
|
||||
|
||||
THEN:
|
||||
→ redirect user to guided activation flow
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Workflow Selection
|
||||
|
||||
Display full-screen page:
|
||||
|
||||
### Title:
|
||||
"Your shop is set up. Let’s run your first workflow."
|
||||
|
||||
### Subtitle:
|
||||
"Choose how jobs usually start for your shop and we’ll guide you through it."
|
||||
|
||||
### Question:
|
||||
"How do jobs usually start for your shop?"
|
||||
|
||||
### Options:
|
||||
|
||||
#### Option A:
|
||||
Title: "I send a quote first"
|
||||
Description: "Create a quote, convert it to a job, then invoice when work is complete."
|
||||
|
||||
#### Option B:
|
||||
Title: "I start with a job"
|
||||
Description: "For walk-ins or approved work where you start immediately."
|
||||
|
||||
---
|
||||
|
||||
### On Selection:
|
||||
Save:
|
||||
- onboardingPath = "quote_first" | "job_first"
|
||||
|
||||
Then continue into guided flow
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Guided Flow
|
||||
|
||||
### Path A — Quote First
|
||||
|
||||
#### Step A1: Create Quote
|
||||
- Use existing quote creation logic
|
||||
- Pre-fill fields:
|
||||
- Customer: "Sample Customer"
|
||||
- Item: "Wheel Set"
|
||||
- Quantity: 4
|
||||
- Notes: "Sample onboarding quote"
|
||||
- Allow editing before submit
|
||||
|
||||
#### Step A2: Show Quote Created
|
||||
Message:
|
||||
"This is the quote you would send to your customer."
|
||||
|
||||
CTA:
|
||||
"Convert to Job"
|
||||
|
||||
#### Step A3: Convert Quote → Job
|
||||
- Use existing conversion logic
|
||||
|
||||
#### Step A4: Show Job
|
||||
Message:
|
||||
"This job is now tracked in your workflow."
|
||||
|
||||
CTA:
|
||||
"Create Invoice" (if supported)
|
||||
|
||||
#### Step A5: Create Invoice (optional)
|
||||
- Use existing invoice logic
|
||||
|
||||
#### Completion:
|
||||
Set:
|
||||
- firstWorkflowCompleted = true
|
||||
|
||||
---
|
||||
|
||||
### Path B — Job First
|
||||
|
||||
#### Step B1: Create Job
|
||||
- Use existing job creation logic
|
||||
- Pre-fill:
|
||||
- Customer: "Walk-in Customer"
|
||||
- Item: "Wheel Set"
|
||||
- Quantity: 4
|
||||
- Notes: "Sample onboarding job"
|
||||
|
||||
#### Step B2: Show Job
|
||||
Message:
|
||||
"This job is now in your workflow."
|
||||
|
||||
CTA:
|
||||
"Create Invoice" (optional)
|
||||
|
||||
#### Step B3: Create Invoice (optional)
|
||||
|
||||
#### Completion:
|
||||
Set:
|
||||
- firstWorkflowCompleted = true
|
||||
|
||||
---
|
||||
|
||||
## Skipping
|
||||
|
||||
Provide "Skip for now" option.
|
||||
|
||||
If skipped:
|
||||
- DO NOT set firstWorkflowCompleted
|
||||
- Redirect to dashboard
|
||||
- Continue showing activation banner
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Behavior
|
||||
|
||||
If:
|
||||
- setup complete
|
||||
- AND firstWorkflowCompleted == false
|
||||
|
||||
Show persistent banner:
|
||||
|
||||
Title:
|
||||
"Create your first job or quote"
|
||||
|
||||
Text:
|
||||
"Run a quick 2-minute workflow to see how the system works."
|
||||
|
||||
CTA:
|
||||
"Start first workflow"
|
||||
|
||||
---
|
||||
|
||||
## Data Model Changes
|
||||
|
||||
Add to Company or User:
|
||||
|
||||
- onboardingPath: string | null
|
||||
- firstWorkflowCompleted: boolean
|
||||
|
||||
Optional:
|
||||
- firstQuoteCreatedAt: datetime
|
||||
- firstJobCreatedAt: datetime
|
||||
- firstInvoiceCreatedAt: datetime
|
||||
|
||||
---
|
||||
|
||||
## Events / Tracking (if system exists)
|
||||
|
||||
Track:
|
||||
- onboarding_path_selected
|
||||
- first_quote_created
|
||||
- first_job_created
|
||||
- first_invoice_created
|
||||
- first_workflow_completed
|
||||
- first_workflow_skipped
|
||||
|
||||
---
|
||||
|
||||
## Implementation Constraints
|
||||
|
||||
- MUST reuse existing quote/job/invoice logic
|
||||
- DO NOT duplicate business logic
|
||||
- DO NOT create separate fake systems
|
||||
- Use existing forms and APIs where possible
|
||||
- Keep UI minimal and fast
|
||||
- Pre-fill as much as possible
|
||||
|
||||
---
|
||||
|
||||
## UX Requirements
|
||||
|
||||
- No tooltip tours
|
||||
- Linear guided flow only
|
||||
- One action at a time
|
||||
- Minimize user effort
|
||||
- Show immediate visual feedback
|
||||
|
||||
---
|
||||
|
||||
## Developer Instructions
|
||||
|
||||
Before coding:
|
||||
1. Inspect setup wizard completion logic
|
||||
2. Identify routing after setup
|
||||
3. Identify quote/job/invoice creation flows
|
||||
4. Identify data model structure
|
||||
|
||||
Then:
|
||||
5. Propose implementation plan
|
||||
6. Wait for approval
|
||||
7. Implement incrementally
|
||||
8. Summarize changes
|
||||
9. Provide manual QA steps
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- % of users creating first job increases significantly
|
||||
- Users complete at least one workflow during onboarding
|
||||
- Reduced drop-off after setup wizard
|
||||
|
||||
Target:
|
||||
≥ 30% of new users create at least one job or quote
|
||||
Reference in New Issue
Block a user