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
|
||||
@@ -0,0 +1,173 @@
|
||||
Add a dashboard progress widget for post-onboarding activation.
|
||||
|
||||
Context:
|
||||
This is a powder coating shop management app. We recently shortened the setup wizard and added a guided activation flow. Some setup items are intentionally deferred so users can evaluate the system quickly before fully configuring everything.
|
||||
|
||||
Goal:
|
||||
Create a dashboard widget that helps users “get the most out of their shop” without making it feel like unfinished homework.
|
||||
|
||||
Do NOT call it “Complete setup.”
|
||||
|
||||
Recommended title:
|
||||
“Get the most out of your shop”
|
||||
|
||||
Purpose:
|
||||
Show progress based on real usage/configuration milestones and give users clear next actions.
|
||||
|
||||
Requirements:
|
||||
|
||||
1. Inspect existing dashboard structure
|
||||
|
||||
* Locate the dashboard controller/view/components.
|
||||
* Reuse existing card, alert, progress bar, and button styles.
|
||||
* Follow existing UI conventions.
|
||||
|
||||
2. Widget visibility
|
||||
Show the widget for companies that:
|
||||
|
||||
* Have completed the setup wizard
|
||||
* Are not yet meaningfully activated OR still have recommended setup tasks incomplete
|
||||
|
||||
It is okay to keep showing it until all tasks are complete.
|
||||
|
||||
3. Progress calculation
|
||||
Create a checklist of 5–6 items max.
|
||||
|
||||
Suggested items:
|
||||
|
||||
A. Create your first quote or job
|
||||
Complete when:
|
||||
|
||||
* company has at least one quote OR at least one job
|
||||
|
||||
CTA:
|
||||
|
||||
* “Create quote/job” or “Start workflow”
|
||||
|
||||
B. Move a job through your workflow
|
||||
Complete when:
|
||||
|
||||
* at least one job has had a status/stage change
|
||||
* If there is no existing way to detect this, use the closest available activity/history/status timestamp
|
||||
|
||||
CTA:
|
||||
|
||||
* “Open daily board”
|
||||
|
||||
C. Create your first invoice
|
||||
Complete when:
|
||||
|
||||
* company has at least one invoice
|
||||
|
||||
CTA:
|
||||
|
||||
* “Create invoice”
|
||||
|
||||
D. Invite your team
|
||||
Complete when:
|
||||
|
||||
* company has more than one active user/team member
|
||||
|
||||
CTA:
|
||||
|
||||
* “Invite team”
|
||||
|
||||
E. Customize pricing
|
||||
Complete when:
|
||||
|
||||
* company has configured pricing tiers/custom pricing settings beyond defaults
|
||||
* If this is hard to detect reliably, make this optional or use a simple existing flag/count
|
||||
|
||||
CTA:
|
||||
|
||||
* “Customize pricing”
|
||||
|
||||
F. Review payment terms
|
||||
Complete when:
|
||||
|
||||
* company has customized payment terms from default
|
||||
* If this is hard to detect reliably, make this optional or use a simple existing flag/value comparison
|
||||
|
||||
CTA:
|
||||
|
||||
* “Review terms”
|
||||
|
||||
4. UX copy
|
||||
Use friendly, value-focused language.
|
||||
|
||||
Widget title:
|
||||
“Get the most out of your shop”
|
||||
|
||||
Subtitle:
|
||||
“Complete a few quick steps to unlock the full workflow.”
|
||||
|
||||
Progress text:
|
||||
“X of Y complete”
|
||||
|
||||
Avoid wording like:
|
||||
|
||||
* “Incomplete setup”
|
||||
* “Missing configuration”
|
||||
* “Required steps”
|
||||
|
||||
5. Visual design
|
||||
|
||||
* Use a card-style widget near the top of the dashboard.
|
||||
* Include a progress bar.
|
||||
* Show checklist rows with completed and incomplete states.
|
||||
* Completed items should feel rewarding.
|
||||
* Incomplete items should have one clear CTA.
|
||||
* Keep it compact and non-annoying.
|
||||
|
||||
6. Behavior
|
||||
|
||||
* Each checklist item should link to the most relevant existing page or action.
|
||||
* Do not build new duplicate workflows.
|
||||
* Reuse existing guided activation route for “Create your first quote or job” if available.
|
||||
* If a task cannot be detected reliably yet, implement it conservatively or leave a TODO comment explaining why.
|
||||
|
||||
7. Data/query logic
|
||||
|
||||
* Prefer calculating progress server-side in the dashboard view model.
|
||||
* Avoid expensive queries.
|
||||
* Reuse existing repositories/services if available.
|
||||
* Keep the logic readable and testable.
|
||||
|
||||
8. Dismissal behavior
|
||||
Add optional dismissal if easy:
|
||||
|
||||
* Let user collapse or dismiss the widget.
|
||||
* If dismissed, do not permanently hide it forever unless all tasks are complete.
|
||||
* Prefer “collapse” over full dismissal.
|
||||
* Store dismissal/collapse state only if there is already a simple place to store dashboard preferences.
|
||||
|
||||
9. Important product guidance
|
||||
This widget should guide users from evaluation into real adoption.
|
||||
|
||||
The emotional framing should be:
|
||||
“You’re already making progress — here are the next valuable things to try.”
|
||||
|
||||
Not:
|
||||
“You failed to finish setup.”
|
||||
|
||||
10. Implementation style
|
||||
Before coding:
|
||||
|
||||
* Inspect relevant dashboard, setup wizard, guided activation, company preference, quote, job, invoice, user/team, pricing, and payment term structures.
|
||||
* Propose a concise implementation plan.
|
||||
* Then implement incrementally.
|
||||
|
||||
After coding:
|
||||
|
||||
* Summarize changed files.
|
||||
* Explain how progress is calculated.
|
||||
* Provide manual QA steps.
|
||||
|
||||
Manual QA scenarios:
|
||||
|
||||
* Brand new company after setup wizard
|
||||
* Company with first quote/job created
|
||||
* Company with moved job/status change
|
||||
* Company with invoice created
|
||||
* Company with invited team member
|
||||
* Company with all tasks complete
|
||||
Reference in New Issue
Block a user