258 lines
4.6 KiB
Markdown
258 lines
4.6 KiB
Markdown
# 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 |