bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a0679d48d7b99c9d9b97f194efc10c05e78c7eb
bakery-ia/docs/wizard-flow-specification.md

2145 lines
103 KiB
Markdown
Raw Normal View History

Add comprehensive wizard flow specification for bakery inventory setup UI Created a detailed design specification for the post-onboarding setup wizard that guides users through adding suppliers, inventory, recipes, quality checks, and team members. Key features of the specification: **Wizard Structure (7 Steps)**: - Step 5: Welcome & Setup Overview - Step 6: Add Suppliers (≥1 required) - Step 7: Set Up Inventory Items (≥3 required) - Step 8: Create Recipes (≥1 required) - Step 9: Define Quality Standards (≥2 required) - Step 10: Add Team Members (optional) - Step 11: Review & Launch **Design Principles**: - Guide, don't block (flexible but directed) - Explain, don't assume (plain language, contextual help) - Validate early, fail friendly (real-time validation) - Progress over perfection (good enough to move forward) - Show value early (unlock features as you progress) **Smart Features**: 1. Intelligent templates (starter inventory, recipe templates, quality checks) 2. Auto-suggestions & smart defaults (ML-powered category detection) 3. Bulk import & export (CSV/Excel support) 4. Contextual help system (tooltips, video tutorials, inline examples) 5. Progress celebrations & motivation (milestone animations) 6. Intelligent validation warnings (non-blocking soft warnings) **Technical Implementation**: - Component architecture and file structure - Reusing OnboardingWizard and AddModal patterns - Backend API requirements (bulk endpoints, templates, smart suggestions) - State management approach - Performance considerations (lazy loading, caching, optimistic updates) - Accessibility and internationalization support **Progress Tracking**: - Weighted progress calculation (by step complexity) - Save & resume functionality - Mobile and desktop navigation patterns - Auto-save behavior **Validation & Error Handling**: - Field-level, cross-field, and step-level validation - Helpful error messages (not technical jargon) - Dependency enforcement (suppliers → inventory → recipes) - Error recovery strategies **Success Metrics**: - Leading: Completion rate (≥80%), time to complete (15-25 min), data quality (≥90%) - Lagging: Feature adoption (≥70%), NPS (≥40), time to first value (≤3 days) - Business impact: Waste reduction (15-20%), cost visibility (100%), quality compliance (≥80%) **Implementation Roadmap**: - Phase 1: Foundation (Week 1-2) - Phase 2: Core Steps (Week 3-5) - Phase 3: Advanced Features (Week 6-7) - Phase 4: Polish & Smart Features (Week 8) - Phase 5: Testing & Iteration (Week 9-10) - Phase 6: Launch & Monitor (Week 11+) Estimated completion time: 15-20 minutes for users Target completion rate: ≥80% Based on JTBD analysis in docs/jtbd-analysis-inventory-setup.md
2025-11-06 10:51:59 +00:00
# Bakery Setup Wizard - Complete Flow Specification
**Version**: 1.0
**Date**: 2025-11-06
**Status**: Design Specification
**Related**: `jtbd-analysis-inventory-setup.md`
---
## 📋 Table of Contents
1. [Executive Summary](#executive-summary)
2. [Design Principles](#design-principles)
3. [Wizard Architecture](#wizard-architecture)
4. [Complete Step Sequence](#complete-step-sequence)
5. [Step Specifications (Detailed)](#step-specifications-detailed)
6. [Progress Tracking & Navigation](#progress-tracking--navigation)
7. [Validation & Error Handling](#validation--error-handling)
8. [Smart Features](#smart-features)
9. [Technical Implementation Notes](#technical-implementation-notes)
10. [Success Metrics](#success-metrics)
---
## Executive Summary
### Problem Statement
After completing the initial onboarding wizard (Register Bakery → Upload Sales Data → ML Training → Completion), users are dropped onto a dashboard with no guidance on how to set up the foundational data needed for daily operations. This creates:
- High abandonment rates (users don't complete setup)
- Data quality issues (incomplete or incorrect entries)
- Delayed time-to-value (can't use the system effectively)
### Solution Overview
**Guided Bakery Setup Journey**: A continuation of the onboarding wizard that walks users through setting up suppliers, inventory, recipes, quality standards, and team in a logical, dependency-aware sequence.
### Key Innovations
1. **Continuous Journey**: Extends onboarding wizard (Step 5+) instead of separate flow
2. **Dependency Awareness**: Enforces order (suppliers before inventory before recipes)
3. **Progressive Disclosure**: Shows complex options only when needed
4. **Flexible Pacing**: Save progress, skip optional steps, resume later
5. **Contextual Guidance**: Every step explains why it matters and what comes next
6. **Celebration Moments**: Recognizes milestones to maintain motivation
---
## Design Principles
### 1. Guide, Don't Block
**Principle**: Provide clear direction while allowing flexibility
- ✅ Suggest optimal path but allow users to skip optional steps
- ✅ Show what's incomplete without preventing progress
- ❌ Don't force users into rigid workflows
- ❌ Don't hide advanced options from experienced users
### 2. Explain, Don't Assume
**Principle**: Use plain language and provide context
- ✅ Explain why each step matters to bakery operations
- ✅ Use bakery terminology, not software jargon
- ✅ Provide examples and common values
- ❌ Don't assume users understand database concepts
- ❌ Don't use technical terms without explanation
### 3. Validate Early, Fail Friendly
**Principle**: Catch errors before they happen, provide helpful guidance
- ✅ Real-time validation as users type
- ✅ Helpful error messages with suggestions
- ✅ Prevent invalid states (dependencies, cross-field validation)
- ❌ Don't wait until submit to show errors
- ❌ Don't show technical error messages
### 4. Progress Over Perfection
**Principle**: Help users make progress, even if data isn't perfect
- ✅ Allow "good enough" data to move forward
- ✅ Clearly mark what's required vs. optional
- ✅ Allow editing later without redoing the entire wizard
- ❌ Don't demand perfection that prevents progress
- ❌ Don't make optional fields feel required
### 5. Show Value Early
**Principle**: Unlock features as users progress
- ✅ Show what becomes possible after each step
- ✅ Preview features before they're available
- ✅ Celebrate completion milestones
- ❌ Don't wait until the end to show value
- ❌ Don't make setup feel like busywork
---
## Wizard Architecture
### Overall Flow Structure
```
┌─────────────────────────────────────────────────────────────┐
│ EXISTING ONBOARDING WIZARD (Steps 1-4) │
│ ──────────────────────────────────────────────────────── │
│ 1. Register Tenant (setup) │
│ 2. Configure Inventory (smart-inventory-setup) │
│ 3. Train AI (ml-training) │
│ 4. Completion │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ NEW: BAKERY SETUP WIZARD (Steps 5-11) │
│ ──────────────────────────────────────────────────────── │
│ PHASE 1: ORIENTATION & PLANNING │
│ 5. Welcome & Setup Overview (setup-welcome) │
│ │
│ PHASE 2: CORE DEPENDENCIES (Critical Path) │
│ 6. Add Suppliers (suppliers-setup) │
│ 7. Set Up Inventory Items (inventory-items-setup) │
│ │
│ PHASE 3: OPERATIONAL DATA (Required for Production) │
│ 8. Create Recipes (recipes-setup) │
│ 9. Define Quality Standards (quality-setup) │
│ │
│ PHASE 4: TEAM & FINALIZATION (Optional but Recommended) │
│ 10. Add Team Members (team-setup) [OPTIONAL] │
│ 11. Review & Launch (setup-completion) │
└─────────────────────────────────────────────────────────────┘
```
### Integration Point
- **Trigger**: When user completes existing Step 4 (Completion)
- **Transition**: Instead of navigating to dashboard, show "One more thing..." modal
- **Modal Content**: "Great start! Now let's set up your daily operations. This will take about 10-15 minutes and unlock powerful features like recipe costing, inventory tracking, and quality monitoring."
- **User Choice**:
- **"Set Up Now"** (recommended) → Enter wizard at Step 5
- **"I'll Do This Later"** → Go to dashboard with persistent "Complete Setup" banner
### Step Categories
| Category | Steps | Required? | Can Skip? | Estimated Time |
|----------|-------|-----------|-----------|----------------|
| **Orientation** | Step 5 (Welcome) | No | Yes | 2 min |
| **Critical Path** | Steps 6-7 (Suppliers, Inventory) | Yes | No | 5-8 min |
| **Production Setup** | Steps 8-9 (Recipes, Quality) | Yes | No | 5-10 min |
| **Team Setup** | Step 10 (Team) | No | Yes | 2-5 min |
| **Completion** | Step 11 (Review) | No | Yes | 1-2 min |
**Total Estimated Time**: 15-27 minutes (depending on data complexity)
---
## Complete Step Sequence
### PHASE 1: ORIENTATION & PLANNING
#### **Step 5: Welcome & Setup Overview** (`setup-welcome`)
**Purpose**: Orient user to what's ahead, reduce anxiety, set expectations
**User Job**: *"Help me understand what I need to set up and why"*
**Content**:
- Welcome message: "You've trained your AI. Now let's set up your daily operations."
- Visual roadmap showing all steps ahead
- Time estimate: "This takes about 15-20 minutes"
- What you'll need: "Have ready: supplier info, ingredient list, common recipes"
- What you'll gain: Feature preview cards showing value
**UI Components**:
```
┌──────────────────────────────────────────────────────┐
│ 🎉 Excellent! Your AI is Ready │
│ │
│ Now let's set up your bakery's daily operations │
│ so the system can help you manage: │
│ │
│ ✓ Inventory tracking & reorder alerts │
│ ✓ Recipe costing & profitability analysis │
│ ✓ Quality standards & production monitoring │
│ ✓ Team coordination & task assignment │
│ │
│ ⏱️ Takes about 15-20 minutes │
│ │
│ 📋 What You'll Set Up: │
│ ──────────────────────────────────────────────── │
│ [CARD] Suppliers | 2-3 min | Required │
│ [CARD] Inventory Items | 5-8 min | Required │
│ [CARD] Recipes | 5-10 min | Required │
│ [CARD] Quality Checks | 3-5 min | Required │
│ [CARD] Team Members | 2-5 min | Optional │
│ │
│ 💡 You can save progress and resume anytime │
│ │
│ [Skip for Now] [Let's Get Started! →] │
└──────────────────────────────────────────────────────┘
```
**Validation**: None (informational step)
**Navigation**:
- **Next**: Step 6 (Suppliers Setup)
- **Skip**: Go to dashboard with "Resume Setup" banner
**Backend**: Mark `setup-welcome` as completed
---
### PHASE 2: CORE DEPENDENCIES (Critical Path)
#### **Step 6: Add Suppliers** (`suppliers-setup`)
**Purpose**: Set up supplier relationships as foundation for inventory
**User Job**: *"Add my suppliers so I can track where ingredients come from and manage orders"*
**Why This Step**:
> "Suppliers are the source of your ingredients. Setting them up now lets you track costs, manage orders, and analyze supplier performance."
**What Users Need to Add**: Minimum 1 supplier (recommended 2-3)
**Form Type**: **Wizard-Enhanced List Entry**
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 2 of 7: Add Your Suppliers │
│ ════════════════════════════════════════════════════ │
│ │
│ 💼 Suppliers │
│ Your ingredient and material providers │
│ │
│ [==========>------------------] 29% Complete │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Why This Matters │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Tracking suppliers helps you: │ │
│ │ • Compare ingredient costs │ │
│ │ • Manage purchase orders │ │
│ │ • Analyze delivery performance │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📝 Your Suppliers (1 required, 2-3 ideal) │ │
│ │ │ │
│ │ [+ Add Your First Supplier] │ │
│ │ │ │
│ │ Empty state illustration │ │
│ │ "Add at least one supplier to continue" │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 💡 Tip: Start with your most frequently used │
│ supplier. You can add more later. │
│ │
│ [← Back] [Skip] [Continue →] │
│ (disabled until 1 supplier added) │
└──────────────────────────────────────────────────────┘
```
**When "Add Supplier" clicked** → Opens inline wizard modal:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Supplier │
│ ════════════════════════════════════════════════════ │
│ │
│ Basic Information │
│ ──────────────────────────────────────────────── │
│ Supplier Name * │
│ [_____________________________________________] │
│ e.g., "Molinos del Norte", "Ingredientes García" │
│ │
│ Supplier Type * │
│ [▼ Select type___________________________] │
│ ├─ Ingredients (flour, sugar, yeast...) │
│ ├─ Packaging (boxes, bags, labels...) │
│ └─ Equipment (mixers, ovens...) │
│ │
│ Contact Information (Optional) │
│ ──────────────────────────────────────────────── │
│ ▼ Show optional fields │
│ │
│ [Add Another Supplier] [Cancel] [Add →] │
└──────────────────────────────────────────────────────┘
```
**Fields**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars | "The business name of your supplier" |
| `supplier_type` | select | Yes | Must select | "Ingredients, Packaging, or Equipment" |
| `contact_name` | text | No | - | "Main contact person at this supplier" |
| `email` | email | No | Valid email | "For sending purchase orders" |
| `phone` | tel | No | Valid phone | "For quick inquiries" |
| `payment_terms` | select | No | - | "Net 30, Net 60, Prepaid, COD..." |
| `status` | select | No | Default: Active | "Active, Inactive, Preferred" |
**After Adding Suppliers**:
```
┌──────────────────────────────────────────────────────┐
│ 📝 Your Suppliers (2 added) ✓ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 💼 Molinos del Norte │ [⋮] │
│ │ Type: Ingredients │ Status: Active │ │
│ │ Contact: Juan García │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 📦 Empaques Premium │ [⋮] │
│ │ Type: Packaging │ Status: Active │ │
│ │ Contact: María López │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [+ Add Another Supplier] │
│ │
│ ✅ Great! You've added 2 suppliers │
│ │
│ [← Back] [Continue to Inventory →] │
└──────────────────────────────────────────────────────┘
```
**Validation**:
- **Minimum**: 1 supplier required to continue
- **Real-time**: Check for duplicate names
- **Business Rule**: At least one "Ingredients" type supplier recommended (show warning if none)
**Navigation**:
- **Continue**: Only enabled when ≥1 supplier added
- **Skip**: Allowed, but shows warning: "You'll need suppliers later for purchase orders"
**Backend**:
- Save each supplier via `POST /api/v1/suppliers/`
- Mark step `suppliers-setup` as completed
- Store count in step data: `{suppliers_added: 2}`
**Smart Features**:
- **Template Suppliers**: "Use common supplier template" button → Pre-fills with typical Spanish bakery suppliers
- **Bulk Import**: "Import from spreadsheet" (CSV with name, type, contact)
---
#### **Step 7: Set Up Inventory Items** (`inventory-items-setup`)
**Purpose**: Add the ingredients and materials used in bakery operations
**User Job**: *"Add my ingredients so the system can track inventory levels and costs"*
**Why This Step**:
> "Inventory items are the building blocks of your recipes. Once set up, the system will track quantities, alert you when stock is low, and help you calculate recipe costs."
**What Users Need to Add**: Minimum 3 inventory items (recommended 10-15 for starter set)
**Dependency**: Requires ≥1 supplier from Step 6
**Form Type**: **Wizard-Enhanced List Entry with Bulk Options**
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 3 of 7: Set Up Inventory Items │
│ ════════════════════════════════════════════════════ │
│ │
│ 📦 Inventory Items │
│ Ingredients and materials you use │
│ │
│ [====================>--------] 57% Complete │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Why This Matters │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Inventory tracking enables: │ │
│ │ • Low stock alerts (never run out!) │ │
│ │ • Automatic reorder suggestions │ │
│ │ • Accurate recipe costing │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📝 Your Inventory (3 min required, 10 ideal)│ │
│ │ │ │
│ │ [+ Add Item] [📥 Import Spreadsheet] │ │
│ │ [📋 Use Starter Template] │ │
│ │ │ │
│ │ (Empty state) │ │
│ │ "Add your most common ingredients first" │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 💡 Quick Start: Use our starter template with │
│ common bakery ingredients (flour, sugar, eggs, │
│ butter...). You can customize them after. │
│ │
│ [← Back to Suppliers] [Skip] [Continue →] │
│ (disabled until 3 items added) │
└──────────────────────────────────────────────────────┘
```
**Starter Template Feature**:
When user clicks "Use Starter Template":
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Starter Ingredients │
│ ════════════════════════════════════════════════════ │
│ │
│ We'll add common bakery ingredients to get you │
│ started. You can edit or remove any items. │
│ │
│ ☑️ Flour (White Bread Flour) - kg │
│ ☑️ Flour (Whole Wheat) - kg │
│ ☑️ Sugar (White Granulated) - kg │
│ ☑️ Butter (Unsalted) - kg │
│ ☑️ Eggs (Large) - units │
│ ☑️ Milk (Whole) - liters │
│ ☑️ Yeast (Active Dry) - kg │
│ ☑️ Salt (Fine) - kg │
│ ☑️ Water - liters │
│ ☑️ Chocolate Chips - kg │
│ │
│ Assign Supplier (Optional): │
│ [▼ Molinos del Norte________________] │
│ (will be set as supplier for flour & sugar) │
│ │
│ [Cancel] [Add Selected Items (10) →] │
└──────────────────────────────────────────────────────┘
```
**Manual Add Item Modal**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Inventory Item [Step 1 of 2] │
│ ════════════════════════════════════════════════════ │
│ │
│ ▼ Basic Information │
│ ──────────────────────────────────────────────── │
│ Item Name * │
│ [_____________________________________________] │
│ e.g., "Harina de trigo 000", "Azúcar blanca" │
│ │
│ Category * │
│ [▼ Select category_______________________] │
│ ├─ Flour & Grains │
│ ├─ Dairy & Eggs │
│ ├─ Sweeteners │
│ ├─ Fats & Oils │
│ ├─ Leavening Agents │
│ ├─ Flavorings & Additives │
│ └─ Packaging Materials │
│ │
│ Unit of Measure * │
│ [▼ Kilograms________________________] │
│ ├─ Kilograms (kg) │
│ ├─ Grams (g) │
│ ├─ Liters (L) │
│ ├─ Milliliters (ml) │
│ └─ Units (pieces) │
│ │
│ ▼ Supplier & Pricing (Optional - can add later) │
│ ──────────────────────────────────────────────── │
│ ▶ Show optional fields │
│ │
│ [Cancel] [Continue to Stock Levels →] │
└──────────────────────────────────────────────────────┘
```
**Step 2 of Add Item (Stock & Reorder Levels)**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Inventory Item [Step 2 of 2] │
│ ════════════════════════════════════════════════════ │
│ │
│ ✓ Harina de trigo 000 │ Flour & Grains │ kg │
│ │
│ ▼ Stock Levels & Alerts │
│ ──────────────────────────────────────────────── │
│ Current Stock (Optional) │
│ [________] kg │
│ How much do you have right now? │
│ │
│ Low Stock Alert At │
│ [________] kg (Recommended: 10-20 kg) │
│ You'll get notified when stock falls below this │
│ │
│ Reorder Point │
│ [________] kg (Recommended: 5 kg) │
│ System will suggest reordering at this level │
│ │
│ ▼ Advanced Options (Optional) │
│ ──────────────────────────────────────────────── │
│ ▶ Pricing, Shelf Life, SKU/Barcode │
│ │
│ 💡 Don't worry if you don't know exact numbers. │
│ You can adjust these anytime based on usage. │
│ │
│ [← Back] [Add Another Item] [Save & Done] │
└──────────────────────────────────────────────────────┘
```
**Fields (Complete List)**:
**Step 1 - Required**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars, unique | "The name you use for this item" |
| `category` | select | Yes | Must select | "Helps organize your inventory" |
| `unit_of_measure` | select | Yes | Must select | "How this item is measured" |
**Step 2 - Stock Levels**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `current_quantity` | number | No | ≥0 | "Current stock on hand" |
| `low_stock_threshold` | number | No | ≥0 | "Alert me when below this level" |
| `reorder_point` | number | No | ≥0, ≤ low_stock | "Suggest reorder at this level" |
**Advanced - Optional**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `supplier_id` | select | No | Must exist | "Primary supplier for this item" |
| `standard_cost` | currency | No | ≥0 | "Typical cost per unit" |
| `sku` | text | No | Unique | "Stock keeping unit code" |
| `barcode` | text | No | Valid barcode | "For scanning" |
| `shelf_life_days` | number | No | >0 | "Days until expires" |
**After Adding Items**:
```
┌──────────────────────────────────────────────────────┐
│ 📝 Your Inventory Items (12 added) ✓ │
│ │
│ Filter by: [All▼] [Search: _______________] [⚙️] │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 🌾 Harina de trigo 000 │ [⋮] │
│ │ Flour & Grains │ 50 kg │ Low: 20 kg │ │
│ │ Supplier: Molinos del Norte │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 🥚 Eggs (Large) │ [⋮] │
│ │ Dairy & Eggs │ 200 units │ Low: 50 │ │
│ │ No supplier set │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [... 10 more items ...] │
│ │
│ [+ Add Item] [Import] [Use Template] │
│ │
│ ✅ Excellent! You've set up 12 inventory items │
│ │
│ [← Back to Suppliers] [Continue to Recipes →]│
└──────────────────────────────────────────────────────┘
```
**Validation**:
- **Minimum**: 3 items required to continue
- **Real-time**: Check for duplicate names within category
- **Business Rules**:
- Warn if no flour items (common for bakeries)
- Warn if reorder_point > low_stock_threshold
- Suggest supplier if none set for "Ingredients" type items
**Navigation**:
- **Continue**: Enabled when ≥3 items added
- **Skip**: Allowed with warning: "Recipes require ingredients. Sure you want to skip?"
**Backend**:
- Save each item via `POST /api/v1/inventory/ingredients/`
- For starter template: Bulk create via `POST /api/v1/inventory/ingredients/bulk/`
- Mark step `inventory-items-setup` as completed
- Store count: `{inventory_items_added: 12, used_template: true}`
**Smart Features**:
- **Smart Categories**: Auto-suggest category based on item name (ML)
- **Unit Conversion**: "Convert between units" helper
- **Supplier Recommendation**: Based on item category, suggest relevant suppliers from Step 6
- **Bulk Edit**: "Edit multiple items" for updating low stock thresholds
**Progress Indicator Within Step**:
```
┌──────────────────────────────────────┐
│ Progress: 12 items added │
│ ▰▰▰▱▱ Minimum met (3+) ✓ │
│ ▰▰▰▰▰ Recommended (10+) ✓ │
└──────────────────────────────────────┘
```
---
### PHASE 3: OPERATIONAL DATA (Required for Production)
#### **Step 8: Create Recipes** (`recipes-setup`)
**Purpose**: Define production recipes using inventory items
**User Job**: *"Add my recipes so the system can calculate costs, track production, and manage ingredient usage"*
**Why This Step**:
> "Recipes connect your inventory to production. The system will calculate exact costs per item, track ingredient consumption, and help you optimize your menu profitability."
**What Users Need to Add**: Minimum 1 recipe (recommended 3-5 core products)
**Dependency**: Requires ≥3 inventory items from Step 7
**Form Type**: **Multi-Step Recipe Builder**
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 4 of 7: Create Your Recipes │
│ ════════════════════════════════════════════════════ │
│ │
│ 👨‍🍳 Recipes │
│ Your bakery's production formulas │
│ │
│ [=============================>---] 71% Complete │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Why This Matters │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Recipes unlock powerful features: │ │
│ │ • Automatic ingredient cost calculation │ │
│ │ • Production planning & scheduling │ │
│ │ • Inventory consumption tracking │ │
│ │ • Profitability analysis per product │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📝 Your Recipes (1 min required, 3-5 ideal) │ │
│ │ │ │
│ │ [+ Create Recipe] [📋 Use Recipe Template] │ │
│ │ │ │
│ │ (Empty state) │ │
│ │ "Create recipes for your core products" │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 💡 Quick Start: Use recipe templates for common │
│ baked goods. Adjust quantities to match yours. │
│ │
│ [← Back to Inventory] [Skip] [Continue →]│
│ (disabled until 1 recipe added) │
└──────────────────────────────────────────────────────┘
```
**Recipe Template Gallery**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Choose Recipe Template │
│ ════════════════════════════════════════════════════ │
│ │
│ Select a template to customize, or create from │
│ scratch: │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 🥖 │ │ 🍞 │ │ 🥐 │ │
│ │ Baguette │ │ White │ │ Croissant│ │
│ │ Francesa │ │ Bread │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 🍰 │ │ 🧁 │ │ ➕ │ │
│ │ Cake │ │ Muffins │ │ Create │ │
│ │ Sponge │ │ Blueberry│ │ Blank │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ [Cancel] │
└──────────────────────────────────────────────────────┘
```
**Create Recipe - Step 1 (Basic Info)**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Create Recipe [Step 1 of 3] │
│ ════════════════════════════════════════════════════ │
│ │
│ Recipe Information │
│ ──────────────────────────────────────────────── │
│ Recipe Name * │
│ [_____________________________________________] │
│ e.g., "Baguette Francesa", "Pan de Molde" │
│ │
│ Category * │
│ [▼ Select category_______________________] │
│ ├─ Bread │
│ ├─ Pastry │
│ ├─ Cake │
│ ├─ Cookie │
│ └─ Specialty │
│ │
│ Batch Yield * │
│ [_____] units │
│ How many items does this recipe make? │
│ │
│ Preparation Time (Optional) │
│ [_____] minutes │
│ │
│ Description (Optional) │
│ [_____________________________________________] │
│ [_____________________________________________] │
│ Brief description or notes about this recipe │
│ │
│ [Cancel] [Continue to Ingredients →]│
└──────────────────────────────────────────────────────┘
```
**Create Recipe - Step 2 (Add Ingredients)**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Create Recipe [Step 2 of 3] │
│ ════════════════════════════════════════════════════ │
│ │
│ ✓ Baguette Francesa │ Bread │ Yield: 10 units │
│ │
│ Recipe Ingredients (1 minimum) │
│ ──────────────────────────────────────────────── │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Ingredient #1 │ [🗑️] │
│ │ ────────────────────────────────────── │ │
│ │ Ingredient * │ │
│ │ [▼ Harina de trigo 000______________] │ │
│ │ │ │
│ │ Quantity * Unit * │ │
│ │ [_____] kg [▼ Kilograms_______] │ │
│ │ │ │
│ │ ☐ Optional ingredient (e.g., optional │ │
│ │ decoration or variation) │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [+ Add Another Ingredient] │
│ │
│ 💡 Tip: Add ingredients in the order you use them │
│ during production for easier reference. │
│ │
│ Estimated Cost: Calculating... │
│ (Cost per unit will be calculated automatically │
│ based on ingredient prices) │
│ │
│ [← Back] [Skip to Review] [Add Instructions →]│
└──────────────────────────────────────────────────────┘
```
**After Adding Ingredient**:
```
│ ┌────────────────────────────────────────────┐ │
│ │ ✓ Ingredient #1 │ [⋮] │
│ │ ────────────────────────────────────── │ │
│ │ 🌾 Harina de trigo 000 │ │
│ │ 1.5 kg │ €0.75/kg │ Cost: €1.13 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Ingredient #2 │ [🗑️] │
│ │ [Empty - Click to add] │ │
│ └────────────────────────────────────────────┘ │
```
**Create Recipe - Step 3 (Instructions - Optional)**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Create Recipe [Step 3 of 3] │
│ ════════════════════════════════════════════════════ │
│ │
│ ✓ Baguette Francesa │ 4 ingredients │ €2.45/batch │
│ │
│ Production Instructions (Optional) │
│ ──────────────────────────────────────────────── │
│ Add step-by-step instructions to help your team │
│ produce this recipe consistently. │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Step 1: Mixing │ [⋮] │
│ │ [________________________________] │ │
│ │ Duration: [___] min │ Temp: [___]°C │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [+ Add Step] │
│ │
│ 💡 You can skip this for now and add instructions │
│ later. The recipe will still work for costing. │
│ │
│ ▼ Advanced Options (Optional) │
│ ──────────────────────────────────────────────── │
│ ▶ Add process stages, equipment, yield notes │
│ │
│ [← Back to Ingredients] [Skip] [Create Recipe →] │
└──────────────────────────────────────────────────────┘
```
**Fields (Complete List)**:
**Step 1 - Recipe Info**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars, unique | "The name of this recipe/product" |
| `category` | select | Yes | Must select | "Type of baked good" |
| `yield_quantity` | number | Yes | >0 | "Number of units this recipe makes" |
| `yield_unit` | select | No | Default: "units" | "What does this recipe produce?" |
| `prep_time_minutes` | number | No | >0 | "Preparation time" |
| `description` | textarea | No | Max 500 chars | "Notes about this recipe" |
**Step 2 - Ingredients (List)**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `ingredient_id` | select | Yes | Must exist in inventory | "Select from your inventory" |
| `quantity` | number | Yes | >0 | "Amount needed for this recipe" |
| `unit` | select | Yes | Must match ingredient unit or convertible | "Measurement unit" |
| `is_optional` | boolean | No | Default: false | "Optional or decoration ingredient" |
| `ingredient_order` | number | Auto | Auto-assigned | "Order in list" |
**Step 3 - Instructions (Optional)**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `process_stages` | list | No | - | "Mixing, Proofing, Baking, etc." |
| `equipment_needed` | list | No | - | "Required equipment" |
**After Creating Recipes**:
```
┌──────────────────────────────────────────────────────┐
│ 📝 Your Recipes (3 created) ✓ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 🥖 Baguette Francesa │ [⋮] │
│ │ Bread │ Yield: 10 units │ │
│ │ Cost: €2.45/batch (€0.25/unit) │ │
│ │ Ingredients: 4 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 🍞 Pan de Molde │ [⋮] │
│ │ Bread │ Yield: 2 loaves │ │
│ │ Cost: €3.20/batch (€1.60/loaf) │ │
│ │ Ingredients: 7 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [+ Create Recipe] [Use Template] │
│ │
│ ✅ Awesome! You've created 3 recipes │
│ Total recipe value: €8.15 │
│ │
│ [← Back to Inventory] [Continue to Quality →] │
└──────────────────────────────────────────────────────┘
```
**Validation**:
- **Minimum**: 1 recipe required
- **Real-time**:
- Check ingredient availability (must be in inventory from Step 7)
- Calculate cost as ingredients are added
- Warn if unit mismatch (e.g., selecting grams when ingredient is in kg)
- **Business Rules**:
- Must have ≥1 non-optional ingredient
- Show warning if recipe uses >50% of current inventory stock
**Navigation**:
- **Continue**: Enabled when ≥1 recipe created
- **Skip**: Allowed with strong warning: "Recipes are essential for production planning. Skip anyway?"
**Backend**:
- Save recipe via `POST /api/v1/recipes/`
- For each ingredient: Save via recipe ingredients endpoint
- Mark step `recipes-setup` as completed
- Store count: `{recipes_added: 3, total_cost_value: 8.15}`
**Smart Features**:
- **Auto-Cost Calculation**: Real-time cost per batch and per unit
- **Unit Converter**: "Convert quantity" button for different units
- **Duplicate Recipe**: "Copy and modify" for variations
- **Ingredient Substitutions**: "Add substitution" for alternative ingredients
---
#### **Step 9: Define Quality Standards** (`quality-setup`)
**Purpose**: Set up quality checks for production monitoring
**User Job**: *"Define quality standards so my team knows what checks to perform and the system can track quality metrics"*
**Why This Step**:
> "Quality checks ensure consistent output and help you identify issues early. Define what 'good' looks like for each stage of production."
**What Users Need to Add**: Minimum 2 quality checks (recommended 5-8 across stages)
**Form Type**: **Wizard-Enhanced List with Stage Selection**
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 5 of 7: Define Quality Standards │
│ ════════════════════════════════════════════════════ │
│ │
│ ✅ Quality Checks │
│ Standards for consistent production │
│ │
│ [===================================>] 86% Complete │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Why This Matters │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Quality tracking helps you: │ │
│ │ • Maintain consistent product standards │ │
│ │ • Train new team members │ │
│ │ • Identify production issues early │ │
│ │ • Track quality metrics over time │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📝 Quality Checks (2 min required, 5 ideal) │ │
│ │ │ │
│ │ [+ Add Quality Check] [Use Template Set] │ │
│ │ │ │
│ │ (Empty state) │ │
│ │ "Define checks for key production stages" │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 💡 Quick Start: Use our template set of common │
│ quality checks for bakeries. Customize after. │
│ │
│ [← Back to Recipes] [Skip] [Continue →]│
│ (disabled until 2 checks added) │
└──────────────────────────────────────────────────────┘
```
**Quality Template Set**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Quality Check Template Set │
│ ════════════════════════════════════════════════════ │
│ │
│ We'll add common quality checks for each production │
│ stage. You can edit or remove any check. │
│ │
│ Mixing Stage: │
│ ☑️ Dough temperature (18-24°C) │
│ ☑️ Dough consistency (smooth, elastic) │
│ │
│ Proofing Stage: │
│ ☑️ Dough volume (doubled in size) │
│ ☑️ Proofing time (60-90 min) │
│ │
│ Baking Stage: │
│ ☑️ Internal temperature (95-98°C for bread) │
│ ☑️ Crust color (golden brown) │
│ │
│ Cooling Stage: │
│ ☑️ Cooling time (30-45 min before packaging) │
│ │
│ Final Product: │
│ ☑️ Weight (within 5% of target) │
│ ☑️ Visual inspection (no defects) │
│ │
│ [Deselect All] [Cancel] [Add Selected (9) →] │
└──────────────────────────────────────────────────────┘
```
**Manual Add Quality Check**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Add Quality Check │
│ ════════════════════════════════════════════════════ │
│ │
│ Check Information │
│ ──────────────────────────────────────────────── │
│ Check Name * │
│ [_____________________________________________] │
│ e.g., "Dough temperature", "Crust color" │
│ │
│ Description │
│ [_____________________________________________] │
│ What to check and why │
│ │
│ Production Stage * │
│ [☑️ Mixing] [☑️ Proofing] [☑️ Baking] [☑️ Cooling] │
│ (Select all stages where this check applies) │
│ │
│ Check Type * │
│ [▼ Select type_______________________] │
│ ├─ Visual Inspection │
│ ├─ Temperature Measurement │
│ ├─ Weight Measurement │
│ ├─ Time Tracking │
│ ├─ Yes/No Check │
│ └─ Numeric Range │
│ │
│ ▼ Pass Criteria (appears based on check type) │
│ ──────────────────────────────────────────────── │
│ [For Temperature: Min/Max range fields] │
│ [For Visual: Description of acceptable appearance] │
│ [For Weight: Target weight ± tolerance] │
│ │
│ Priority │
│ ( ) Critical ( ) Important (•) Standard │
│ │
│ [Cancel] [Add Another] [Save & Done →] │
└──────────────────────────────────────────────────────┘
```
**Fields**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 3 chars | "Short name for this check" |
| `description` | textarea | No | Max 500 chars | "What to check and why it matters" |
| `production_stages` | multi-select | Yes | ≥1 stage | "When to perform this check" |
| `check_type` | select | Yes | Must select | "How to measure this quality aspect" |
| `pass_criteria` | varies | Conditional | Depends on type | "What defines a pass" |
| `priority` | select | No | Default: Standard | "Critical, Important, or Standard" |
**After Adding Quality Checks**:
```
┌──────────────────────────────────────────────────────┐
│ 📝 Your Quality Checks (7 added) ✓ │
│ │
│ Group by: [Stage ▼] │
│ │
│ 🔧 Mixing (2 checks) │
│ ┌────────────────────────────────────────────┐ │
│ │ 🌡️ Dough Temperature │ [⋮] │
│ │ Range: 18-24°C │ Priority: Critical │ │
│ └────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────┐ │
│ │ ✋ Dough Consistency │ [⋮] │
│ │ Visual check │ Priority: Important │ │
│ └────────────────────────────────────────────┘ │
│ │
│ 🍞 Baking (3 checks) │
│ [... more checks ...] │
│ │
│ [+ Add Check] [Use Template] │
│ │
│ ✅ Great! You've defined 7 quality standards │
│ │
│ [← Back to Recipes] [Continue to Team →] │
└──────────────────────────────────────────────────────┘
```
**Validation**:
- **Minimum**: 2 checks required
- **Business Rules**:
- Recommend at least one "Critical" check
- Warn if no checks for "Baking" stage (common oversight)
**Navigation**:
- **Continue**: Enabled when ≥2 checks added
- **Skip**: Allowed (quality is important but not blocking for basic operations)
**Backend**:
- Save via `POST /api/v1/quality-templates/`
- Mark step `quality-setup` as completed
- Store count: `{quality_checks_added: 7, critical_checks: 2}`
---
### PHASE 4: TEAM & FINALIZATION (Optional but Recommended)
#### **Step 10: Add Team Members** (`team-setup`)
**Purpose**: Set up user accounts for bakery staff
**User Job**: *"Add my team so they can access the system and we can coordinate work"*
**Why This Step**:
> "Adding team members allows you to assign tasks, track who does what, and give everyone the tools they need to work efficiently."
**What Users Need to Add**: Optional (0-10 team members)
**Form Type**: **Simple List Entry (Invite-Based)**
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 6 of 7: Add Team Members (Optional) │
│ ════════════════════════════════════════════════════ │
│ │
│ 👥 Team │
│ Your bakery staff │
│ │
│ [========================================] 93% Complete│
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Why This Matters │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Team access enables: │ │
│ │ • Task assignment & coordination │ │
│ │ • Production tracking by person │ │
│ │ • Quality check accountability │ │
│ │ • Permission-based access control │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📝 Team Members (Optional) │ │
│ │ │ │
│ │ [+ Invite Team Member] │ │
│ │ │ │
│ │ (Empty state) │ │
│ │ "Invite your staff to collaborate" │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 💡 You can add team members later from Settings. │
│ Skip this step if you're the only user for now. │
│ │
│ [← Back to Quality] [Skip This Step] [Continue →]│
│ (always enabled - this step is optional) │
└──────────────────────────────────────────────────────┘
```
**Invite Team Member Modal**:
```
┌──────────────────────────────────────────────────────┐
│ ✕ Invite Team Member │
│ ════════════════════════════════════════════════════ │
│ │
│ Member Information │
│ ──────────────────────────────────────────────── │
│ Name * │
│ [_____________________________________________] │
│ │
│ Email * │
│ [_____________________________________________] │
│ They'll receive an invitation to join │
│ │
│ Role * │
│ [▼ Select role_______________________] │
│ ├─ Baker (can view & record production) │
│ ├─ Manager (can edit recipes & inventory) │
│ └─ Admin (full access) │
│ │
│ [Cancel] [Send Invitation →] │
└──────────────────────────────────────────────────────┘
```
**After Adding Team**:
```
│ 📝 Team Members (3 invited) ✓ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 👤 María García │ [⋮] │
│ │ maria@bakery.com │ Role: Manager │ │
│ │ Status: Invitation sent │ │
│ └────────────────────────────────────────────┘ │
│ │
│ [... more team members ...] │
```
**Validation**: None (optional step)
**Navigation**:
- **Continue**: Always enabled
- **Skip**: Always allowed
**Backend**:
- Send invitation via `POST /api/v1/team/invitations/`
- Mark step `team-setup` as completed
- Store count: `{team_invitations_sent: 3}`
---
#### **Step 11: Review & Launch** (`setup-completion`)
**Purpose**: Celebrate completion and show what's now possible
**User Job**: *"Verify I've set everything up correctly and start using the system"*
**Why This Step**:
> "You're ready to go! Let's review what you've set up and show you what's now available."
**UI Flow**:
```
┌──────────────────────────────────────────────────────┐
│ Step 7 of 7: You're All Set! 🎉 │
│ ════════════════════════════════════════════════════ │
│ │
│ ✅ Setup Complete │
│ Your bakery system is ready │
│ │
│ [=========================================>] 100% │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 🎊 Congratulations! │ │
│ │ ─────────────────────────────────────────── │ │
│ │ Your bakery management system is fully │ │
│ │ configured and ready to help you run your │ │
│ │ operations more efficiently. │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 📊 Setup Summary │
│ ──────────────────────────────────────────────── │
│ ✅ 2 Suppliers added │
│ ✅ 12 Inventory items set up │
│ ✅ 3 Recipes created (Total value: €8.15) │
│ ✅ 7 Quality checks defined │
│ ✅ 3 Team members invited │
│ │
│ 🎯 What You Can Do Now │
│ ──────────────────────────────────────────────── │
│ ┌──────────────────────────────────────────┐ │
│ │ 📦 Track Inventory │ [→] │
│ │ Real-time stock levels & alerts │ │
│ └──────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────┐ │
│ │ 👨‍🍳 Create Production Orders │ [→] │
│ │ Plan daily baking with your recipes │ │
│ └──────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────┐ │
│ │ 💰 Analyze Costs & Profitability │ [→] │
│ │ See exact costs per recipe │ │
│ └──────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────┐ │
│ │ 📈 View AI Forecasts │ [→] │
│ │ Demand predictions for your products │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 💡 Quick Start Guide │
│ ──────────────────────────────────────────────── │
│ [📘 View Tutorial] [❓ Watch Demo Video] │
│ │
│ [← Back to Team] [Go to Dashboard →] │
└──────────────────────────────────────────────────────┘
```
**Validation**: None (review step)
**Navigation**:
- **Continue**: Go to dashboard (system fully operational)
**Backend**:
- Mark step `setup-completion` as completed
- Set overall onboarding status to "completed"
- Trigger: Send welcome email with quick start guide
---
## Progress Tracking & Navigation
### Overall Progress Indicator
**Visual Design** (appears at top of every step):
```
[====================>----------] 57% Complete
Step 3 of 7: Set Up Inventory Items
```
**Progress Calculation**:
```typescript
// Weight steps by estimated complexity/time
const STEP_WEIGHTS = {
'setup-welcome': 5, // 2 min (light)
'suppliers-setup': 10, // 5 min (moderate)
'inventory-items-setup': 20, // 10 min (heavy)
'recipes-setup': 20, // 10 min (heavy)
'quality-setup': 15, // 7 min (moderate)
'team-setup': 10, // 5 min (optional)
'setup-completion': 5 // 2 min (light)
};
const totalWeight = Object.values(STEP_WEIGHTS).reduce((a, b) => a + b);
function calculateProgress(currentStepIndex: number, completedSteps: string[]): number {
let completedWeight = 0;
// Add weight of fully completed steps
completedSteps.forEach(stepId => {
completedWeight += STEP_WEIGHTS[stepId] || 0;
});
// Add 50% of current step weight (user is midway through)
const currentStepId = STEPS[currentStepIndex].id;
completedWeight += (STEP_WEIGHTS[currentStepId] || 0) * 0.5;
return Math.round((completedWeight / totalWeight) * 100);
}
```
### Step Navigation States
**Continue Button States**:
| Step | Enable Condition | Button Text | Behavior |
|------|------------------|-------------|----------|
| Welcome | Always | "Let's Get Started →" | Navigate to Step 6 |
| Suppliers | ≥1 supplier added | "Continue to Inventory →" | Navigate to Step 7 |
| Inventory | ≥3 items added | "Continue to Recipes →" | Navigate to Step 8 |
| Recipes | ≥1 recipe created | "Continue to Quality →" | Navigate to Step 9 |
| Quality | ≥2 checks added | "Continue to Team →" | Navigate to Step 10 |
| Team | Always (optional) | "Continue to Review →" | Navigate to Step 11 |
| Completion | Always | "Go to Dashboard →" | Exit wizard → Dashboard |
**Back Button Behavior**:
- Always visible (except on Step 5)
- Goes to previous step WITHOUT losing data (data is saved on each step completion)
- Disabled during save operations
**Skip Button**:
- Visible on Steps 5, 9, 10, 11 (optional/skippable steps)
- Shows confirmation dialog: "Are you sure you want to skip [Step Name]? You can set this up later from Settings."
- On confirm: Marks step as "skipped" (not "completed") and advances
### Mobile Navigation Patterns
**Small Screens (<640px)**:
- Progress bar: Full width, height: 8px
- Step title: Larger font (18px)
- Buttons: Stacked vertically
- Step indicators: Horizontal scroll
```
[========>------] 43%
📦 Inventory Items
Step 3 of 7
[Main content...]
[← Back ]
[Skip This Step]
[Continue → ]
```
**Desktop (≥640px)**:
- Progress bar: Full width, height: 12px
- Buttons: Horizontal layout
- Step indicators: All visible
### Save Progress & Resume Later
**Auto-Save Behavior**:
- Each entity added is immediately saved to backend
- Step is marked "completed" when user clicks Continue
- If user closes browser mid-step, data is preserved but step not marked complete
**Resume Behavior**:
```typescript
function determineResumeStep(userProgress: UserProgress): number {
// Find first incomplete step
for (let i = 0; i < SETUP_STEPS.length; i++) {
const step = SETUP_STEPS[i];
const stepProgress = userProgress.steps.find(s => s.step_name === step.id);
if (!stepProgress?.completed && stepProgress?.status !== 'skipped') {
return i; // Resume here
}
}
// All steps complete → go to last step (completion)
return SETUP_STEPS.length - 1;
}
```
**Resume Entry Point**:
- Dashboard shows "Complete Setup" banner if wizard not finished
- Banner shows: "You're 57% done! Continue setting up →"
- Click banner → Resume at first incomplete step
### Exit Points & Persistence
**User Can Exit At Any Time**:
1. Click browser back button
2. Click dashboard link in sidebar
3. Close browser tab
**On Exit (Not Completed)**:
- All data entered so far is saved
- Progress tracked in backend (`user_progress` table)
- Dashboard shows persistent banner: "Complete your setup to unlock all features"
**Re-Entry**:
- User clicks "Complete Setup" from dashboard
- System loads user progress and resumes at correct step
- Previously entered data is loaded (suppliers, inventory, recipes, etc.)
---
## Validation & Error Handling
### Real-Time Validation Strategy
**Field-Level Validation**:
- Trigger: `onChange` (debounced 300ms for text inputs)
- Display: Inline error message below field
- State: Field border turns red, error icon appears
**Example**:
```typescript
// Supplier name field
const [nameError, setNameError] = useState<string | null>(null);
const validateName = debounce((value: string) => {
if (value.length < 2) {
setNameError("Supplier name must be at least 2 characters");
return false;
}
// Check for duplicates (async)
checkDuplicateSupplier(value).then(isDuplicate => {
if (isDuplicate) {
setNameError("A supplier with this name already exists");
} else {
setNameError(null);
}
});
return true;
}, 300);
```
**Cross-Field Validation**:
- Trigger: When dependent field changes
- Example: `reorder_point` must be ≤ `low_stock_threshold`
```typescript
function validateInventoryItem(item: InventoryItemForm): ValidationErrors {
const errors: ValidationErrors = {};
if (item.reorder_point && item.low_stock_threshold) {
if (item.reorder_point > item.low_stock_threshold) {
errors.reorder_point = "Reorder point must be less than or equal to low stock threshold";
}
}
return errors;
}
```
**Step-Level Validation**:
- Trigger: When user clicks "Continue"
- Validates all requirements for current step
- If validation fails: Show error summary, scroll to first error
### Error Message Patterns
**Tone**: Helpful, not judgmental
| Error Type | Bad Message | Good Message |
|------------|-------------|--------------|
| Required field | "This field is required" | "Please enter a supplier name to continue" |
| Format error | "Invalid email" | "Please enter a valid email address (e.g., name@bakery.com)" |
| Duplicate | "Duplicate entry" | "You already have a supplier named 'Molinos'. Try a different name." |
| Dependency | "Dependency not met" | "Please add at least 3 inventory items before creating recipes" |
**Visual Pattern**:
```
┌────────────────────────────────────────┐
│ ⚠️ Please fix these issues: │
│ ──────────────────────────────────── │
│ • Supplier name is required │
│ • Email format is invalid │
│ │
│ [Fix Issues] │
└────────────────────────────────────────┘
```
### Preventing Invalid States
**Dependency Enforcement**:
1. **Suppliers before Inventory**: Can't assign supplier to inventory item if no suppliers exist
- Solution: Show "Add supplier" link inline in inventory form
2. **Inventory before Recipes**: Can't select ingredients if no inventory items exist
- Solution: Wizard step order enforces this naturally
3. **No Empty Steps**: Can't mark step complete if minimum requirements not met
- Solution: Disable "Continue" button until requirements met
**Business Rule Validation**:
```typescript
// Inventory item validation
function validateInventorySetup(items: InventoryItem[]): ValidationWarning[] {
const warnings: ValidationWarning[] = [];
// Warn if no flour (common for bakeries)
const hasFlour = items.some(item =>
item.category === 'flour_grains' ||
item.name.toLowerCase().includes('flour')
);
if (!hasFlour) {
warnings.push({
severity: 'warning',
message: "Most bakeries use flour. Did you mean to skip it?",
action: "Add flour items",
onAction: () => openAddItemModal({ category: 'flour_grains' })
});
}
return warnings;
}
```
### Error Recovery Strategies
**Network Errors**:
- Retry failed requests automatically (max 3 attempts)
- Show toast: "Connection lost. Retrying..."
- If all retries fail: Show error with "Try Again" button
**Validation Errors**:
- Highlight all invalid fields
- Show summary of errors at top of form
- Scroll to first error
- Provide "Fix for me" suggestions where possible
**Example Recovery UI**:
```
┌────────────────────────────────────────┐
│ ❌ Couldn't save supplier │
│ │
│ Network connection lost. Your data │
│ is safe - we'll try again. │
│ │
│ [Try Again] [Continue Offline] │
└────────────────────────────────────────┘
```
---
## Smart Features
### 1. Intelligent Templates
**Starter Template for Inventory**:
- Pre-populated with 25 common bakery ingredients
- Categorized (Flour & Grains, Dairy, Sweeteners, etc.)
- Suggested units and typical low stock thresholds
- User can select which to import
**Recipe Templates**:
- Library of 15+ common recipes (baguette, white bread, croissant, muffins, etc.)
- User selects template → System maps template ingredients to user's inventory
- If ingredient missing: Prompt to add it or substitute
**Quality Check Templates**:
- Pre-configured checks for each production stage
- Based on industry best practices
- User can enable/disable individual checks
### 2. Auto-Suggestions & Smart Defaults
**Category Auto-Detection** (ML-powered):
```typescript
function suggestCategory(itemName: string): string {
// ML model trained on bakery inventory data
const prediction = categoryModel.predict(itemName);
// Examples:
// "harina" → "flour_grains"
// "azúcar" → "sweeteners"
// "leche" → "dairy_eggs"
return prediction.category;
}
```
**Supplier Recommendations**:
- When adding inventory item, suggest supplier based on item category
- "Flour items usually come from: [Molinos del Norte ▼]"
**Unit Conversion Helper**:
```
Adding: Harina de trigo (1000g)
💡 Tip: 1000g = 1kg. Switch to kilograms? [Yes] [No]
```
**Cost Estimation**:
- If user doesn't know ingredient cost, suggest typical market price
- "Average cost for flour in Spain: €0.60-0.80/kg"
### 3. Bulk Import & Export
**CSV/Excel Import**:
- Upload spreadsheet → Map columns → Import in bulk
- Template downloadable: "Download sample spreadsheet"
- Validation before import: "Found 12 items, 2 have errors. Fix them?"
**Supported Entities**:
- Suppliers (name, type, contact, email, phone)
- Inventory Items (name, category, unit, supplier, cost, stock levels)
- Recipes (name, category, yield + separate ingredient list)
### 4. Contextual Help System
**Help Tooltips**:
- (?) icon next to complex fields
- Hover/click to see explanation
```
Low Stock Threshold (?)
────────────────────────
When inventory falls below this level,
you'll receive an alert to reorder.
Recommended: 2-3 weeks of typical usage
Example: If you use 50kg flour per week,
set threshold to 100-150kg
```
**Video Tutorials**:
- Embedded 30-60 second videos for complex steps
- "Watch how to create a recipe (45 sec)"
**Inline Examples**:
- Every field shows example value
- "e.g., Molinos del Norte" for supplier name
- "e.g., 1.5" for recipe ingredient quantity
### 5. Progress Celebrations & Motivation
**Milestone Animations**:
- When reaching 25%, 50%, 75% completion: Brief confetti animation
- "Great progress! You're halfway there! 🎉"
**Step Completion Feedback**:
- After each step: Success message with positive reinforcement
- "✅ Excellent! You've added 3 recipes. Your bakery is taking shape!"
**Comparison to Others** (Optional):
- "Most bakeries add 10-15 inventory items. You've added 12 - right on track!"
### 6. Intelligent Validation Warnings (Non-Blocking)
**Soft Warnings** (shown but don't prevent progress):
```
⚠️ Heads up!
You haven't set a cost for "Harina de trigo".
Recipe costing won't be accurate until you add it.
[Add Cost Now] [I'll Do It Later]
```
**Proactive Suggestions**:
```
💡 Suggestion
You've added "Baguette" recipe. Want to add a
"Whole Wheat Baguette" variation? We can copy
the recipe and you just adjust the flour.
[Create Variation] [No Thanks]
```
---
## Technical Implementation Notes
### Component Architecture
**Proposed Structure**:
```
frontend/src/components/domain/setup-wizard/
├── SetupWizard.tsx # Main wizard component (similar to OnboardingWizard)
├── steps/
│ ├── WelcomeStep.tsx
│ ├── SuppliersSetupStep.tsx
│ ├── InventorySetupStep.tsx
│ ├── RecipesSetupStep.tsx
│ ├── QualitySetupStep.tsx
│ ├── TeamSetupStep.tsx
│ └── CompletionStep.tsx
├── components/
│ ├── StepProgress.tsx # Progress bar & indicators
│ ├── StepNavigation.tsx # Back/Skip/Continue buttons
│ ├── AddEntityModal.tsx # Generic modal for adding items
│ ├── TemplateSelector.tsx # Template gallery
│ └── EntityList.tsx # List view for added items
└── hooks/
├── useSetupProgress.ts
├── useStepValidation.ts
└── useAutoSave.ts
```
### Reusing Existing Patterns
**From OnboardingWizard**:
- Step configuration structure (`StepConfig` interface)
- Progress tracking (`useUserProgress` hook)
- Step completion (`useMarkStepCompleted` mutation)
- Step navigation logic
- Mobile/desktop responsive design
- Progress percentage calculation
**From AddModal**:
- Field configuration (`AddModalField` interface)
- Section-based organization
- ListFieldRenderer for managing collections
- Validation infrastructure
- Loading states & success animations
**Integration Strategy**:
```typescript
// Extend existing StepConfig to support setup wizard steps
interface SetupStepConfig extends StepConfig {
id: string;
title: string;
description: string;
component: React.ComponentType<SetupStepProps>;
minRequired?: number; // Minimum items to proceed
isOptional?: boolean; // Can be skipped
estimatedMinutes?: number; // For progress calculation
dependencies?: string[]; // Step IDs that must be complete first
}
```
### Backend API Requirements
**New Endpoints Needed**:
```typescript
// Setup-specific progress tracking
GET /api/v1/onboarding/progress/:userId?type=setup
POST /api/v1/onboarding/steps/:stepName/complete
// Bulk operations
POST /api/v1/inventory/ingredients/bulk // Bulk create from template
POST /api/v1/quality-templates/bulk // Bulk create checks
POST /api/v1/inventory/ingredients/import // CSV import
// Templates
GET /api/v1/templates/inventory-starter // Get starter inventory
GET /api/v1/templates/recipes/:category // Get recipe templates
GET /api/v1/templates/quality-checks // Get quality check templates
// Smart suggestions
POST /api/v1/ml/suggest-category // ML category suggestion
GET /api/v1/market-data/average-prices // Average ingredient prices
```
**Existing Endpoints to Use**:
```typescript
// Already available
POST /api/v1/suppliers/
POST /api/v1/inventory/ingredients/
POST /api/v1/recipes/
POST /api/v1/quality-templates/
POST /api/v1/team/invitations/
```
### State Management
**Setup Wizard State**:
```typescript
interface SetupWizardState {
currentStepIndex: number;
completedSteps: string[];
skippedSteps: string[];
stepData: {
[stepId: string]: {
itemsAdded: number;
totalValue?: number;
completedAt?: string;
// Step-specific data
};
};
isInitialized: boolean;
progressPercentage: number;
}
```
**Persisted State** (in backend):
```sql
-- user_progress table (already exists)
user_id: UUID
current_step: VARCHAR -- e.g., "inventory-items-setup"
completion_percentage: INTEGER
steps: JSONB -- Array of step progress objects
completed_at: TIMESTAMP (nullable)
-- step progress object structure
{
"step_name": "suppliers-setup",
"completed": true,
"skipped": false,
"completed_at": "2025-11-06T10:30:00Z",
"data": {
"suppliers_added": 2,
"used_template": false
}
}
```
### Performance Considerations
**Lazy Loading**:
- Load step components on-demand (React.lazy)
- Preload next step component in background
**Optimistic Updates**:
- Show success immediately, sync in background
- If sync fails, rollback with notification
**Caching**:
- Cache supplier/inventory lists in React Query
- Invalidate on mutations
**Debouncing**:
- Search/filter operations: 300ms debounce
- Validation: 300ms debounce for text inputs
- Auto-save draft: 1000ms debounce
### Accessibility (a11y)
**Keyboard Navigation**:
- Tab order: Top to bottom, left to right
- Enter: Submit form/Continue
- Esc: Close modal
- Arrow keys: Navigate step indicators
**Screen Reader Support**:
```tsx
<div role="progressbar" aria-valuenow={57} aria-valuemin={0} aria-valuemax={100}>
Step 3 of 7: Set Up Inventory Items (57% complete)
</div>
<button
aria-label="Continue to Recipes step"
disabled={!canContinue}
aria-disabled={!canContinue}
>
Continue →
</button>
```
**Focus Management**:
- When step changes: Focus on step title
- When modal opens: Focus on first input
- When error: Focus on first invalid field
### Internationalization (i18n)
**Translation Keys**:
```json
{
"setup_wizard": {
"steps": {
"welcome": {
"title": "Welcome & Setup Overview",
"description": "Let's set up your bakery operations",
...
},
"suppliers": {
"title": "Add Suppliers",
"description": "Your ingredient and material providers",
"min_required": "Add at least {{count}} supplier to continue",
...
}
},
"navigation": {
"back": "Back",
"skip": "Skip This Step",
"continue": "Continue",
...
}
}
}
```
---
## Success Metrics
### Leading Indicators (During Wizard)
**Completion Rate**:
- **Metric**: % of users who complete all 7 steps
- **Target**: ≥80% completion rate
- **Measurement**: `(users_completed / users_started) * 100`
**Drop-Off Points**:
- **Metric**: Where users abandon the wizard
- **Target**: No single step has >15% drop-off
- **Measurement**: Track step entry vs. step completion
**Time to Complete**:
- **Metric**: Average time from Step 5 to Step 11
- **Target**: 15-25 minutes (matches estimate)
- **Measurement**: `completion_timestamp - start_timestamp`
**Data Quality Score**:
- **Metric**: % of records with complete, valid data
- **Target**: ≥90% of entities have all required + recommended fields
- **Calculation**:
```typescript
function calculateDataQuality(entity: any): number {
const requiredFields = entity.requiredFields.filter(f => !!entity[f]);
const optionalFields = entity.optionalFields.filter(f => !!entity[f]);
return (requiredFields.length + (optionalFields.length * 0.5)) /
(entity.requiredFields.length + entity.optionalFields.length);
}
```
**Template Usage Rate**:
- **Metric**: % of users who use starter templates
- **Target**: ≥60% use at least one template
- **Hypothesis**: Templates speed up setup and improve data quality
### Lagging Indicators (Post-Wizard)
**Feature Adoption Rate**:
- **Metric**: % of completed users actively using core features within 7 days
- **Features**: Inventory tracking, recipe costing, production planning, quality checks
- **Target**: ≥70% use ≥2 features weekly
**System Reliance**:
- **Metric**: Daily active usage frequency
- **Target**: ≥5 days per week for production-focused users
- **Measurement**: DAU/MAU ratio
**User Satisfaction** (NPS):
- **Metric**: Net Promoter Score for setup experience
- **Survey**: "How likely are you to recommend this setup process?" (0-10)
- **Target**: NPS ≥40
**Time to First Value**:
- **Metric**: Days from registration to first meaningful action (e.g., create production order, record sale)
- **Target**: ≤3 days (with wizard) vs. 7-10 days (without)
**Support Ticket Reduction**:
- **Metric**: "How do I..." support tickets related to setup
- **Target**: 50% reduction vs. previous un-guided experience
### Business Impact (Long-term)
**Operational Efficiency**:
- **Metric**: Waste reduction (% decrease in spoilage/overstock)
- **Target**: 15-20% reduction in first 3 months
- **Attribution**: Users with complete setup vs. incomplete
**Cost Visibility**:
- **Metric**: % of users who can accurately report per-recipe costs
- **Target**: 100% of users with recipes can see cost breakdowns
- **Value**: Enables pricing decisions, profitability analysis
**Quality Consistency**:
- **Metric**: Quality check compliance rate
- **Target**: ≥80% of production runs have quality checks recorded
- **Attribution**: Users who defined quality standards in wizard
### A/B Testing Opportunities
**Test Variations**:
1. **Template vs. Manual Entry**
- A: Show templates prominently (current design)
- B: Manual entry default, templates as optional
- Hypothesis: Templates increase completion rate & speed
2. **Step Granularity**
- A: 7 steps (current design)
- B: 4 steps (combine some steps)
- Hypothesis: Fewer steps reduce cognitive load, increase completion
3. **Progress Celebration**
- A: Milestone animations + messages (current design)
- B: No celebrations, just progress bar
- Hypothesis: Celebrations increase motivation & completion
4. **Skip vs. No-Skip for Optional Steps**
- A: Allow skipping Team & Quality steps
- B: Encourage completion ("3 more minutes to 100%")
- Hypothesis: Encouraging completion increases feature adoption
### Tracking Implementation
**Analytics Events**:
```typescript
// Track key events
analytics.track('setup_wizard_started', {
user_id, timestamp
});
analytics.track('setup_step_completed', {
user_id, step_id, items_added, duration_seconds, used_template
});
analytics.track('setup_step_skipped', {
user_id, step_id, reason
});
analytics.track('setup_wizard_completed', {
user_id, total_duration, suppliers_count, inventory_count, recipes_count,
quality_checks_count, team_count, used_templates_count
});
analytics.track('setup_wizard_abandoned', {
user_id, last_step_id, completion_percentage, duration
});
```
**Dashboard Metrics**:
```
Setup Wizard Performance
─────────────────────────
Completion Rate: 82% ✓ (target: 80%)
Avg. Time: 18 min ✓ (target: 15-25 min)
Drop-off Points: Step 7 (Inventory): 12% ✓
Data Quality Score: 91% ✓ (target: 90%)
Template Usage: 68% ✓ (target: 60%)
- Inventory starter: 55%
- Recipe templates: 42%
- Quality checks: 71%
Feature Adoption (7 days post-setup):
- Inventory tracking: 78%
- Recipe costing: 65%
- Production planning: 52%
- Quality monitoring: 48%
```
---
## Implementation Roadmap
### Phase 1: Foundation (Week 1-2)
- [ ] Create SetupWizard component structure
- [ ] Implement step navigation & progress tracking
- [ ] Integrate with existing OnboardingWizard
- [ ] Build StepProgress and StepNavigation components
- [ ] Set up backend endpoints for step completion
### Phase 2: Core Steps (Week 3-5)
- [ ] Implement Welcome Step (Step 5)
- [ ] Implement Suppliers Setup Step (Step 6)
- [ ] Implement Inventory Setup Step (Step 7)
- [ ] Implement Recipes Setup Step (Step 8)
- [ ] Add real-time validation for each step
### Phase 3: Advanced Features (Week 6-7)
- [ ] Implement Quality Setup Step (Step 9)
- [ ] Implement Team Setup Step (Step 10)
- [ ] Implement Completion Step (Step 11)
- [ ] Add template systems (inventory, recipes, quality)
- [ ] Implement bulk import functionality
### Phase 4: Polish & Smart Features (Week 8)
- [ ] Add contextual help & tooltips
- [ ] Implement auto-suggestions (ML category detection)
- [ ] Add celebration animations & milestone feedback
- [ ] Optimize performance (lazy loading, caching)
- [ ] Complete i18n translations
### Phase 5: Testing & Iteration (Week 9-10)
- [ ] User testing with 10-15 bakery owners
- [ ] Fix issues identified in testing
- [ ] A/B test setup (template vs. manual entry)
- [ ] Set up analytics tracking
- [ ] Write documentation & tutorial content
### Phase 6: Launch & Monitor (Week 11+)
- [ ] Soft launch to 10% of new users
- [ ] Monitor metrics & gather feedback
- [ ] Iterate based on data
- [ ] Full rollout to all users
- [ ] Ongoing optimization
---
## Appendix: Open Questions & Decisions Needed
### Design Decisions
1. **Should we allow users to edit data from previous steps within the wizard?**
- Option A: Yes, "Edit" button on each step summary
- Option B: No, must exit wizard and use normal UI
- Recommendation: Option A (better UX, keeps users in flow)
2. **How do we handle users who want to skip the entire wizard?**
- Option A: Allow full skip, but show persistent "Incomplete Setup" banner
- Option B: Require minimum critical path (Steps 6-8)
- Recommendation: Option B (ensures system can function)
3. **Should recipe templates include quantities, or just ingredient lists?**
- Option A: Full recipes with quantities (more helpful, but may not match user's scale)
- Option B: Just ingredient lists (user fills in quantities)
- Recommendation: Option A with prominent "Adjust quantities to your batch size" notice
4. **What happens if a user creates an entity outside the wizard (e.g., manually adds a supplier)?**
- Option A: Wizard counts it toward requirements
- Option B: Wizard doesn't recognize it, asks user to add via wizard
- Recommendation: Option A (recognize all entities, wizard is just guided experience)
### Technical Questions
1. **Should we reuse existing modal components or create wizard-specific ones?**
- Recommendation: Reuse AddModal architecture, extend with wizard-specific features
2. **How do we handle wizard state if user switches tenants mid-wizard?**
- Recommendation: Save progress per tenant, allow resuming
3. **Should wizard data be saved in a separate table or use main entity tables?**
- Recommendation: Use main entity tables (suppliers, inventory, etc.) + track progress in user_progress
4. **How do we handle concurrent edits (user opens wizard, also opens suppliers page)?**
- Recommendation: Real-time sync via websockets or periodic polling
### Content & Messaging
1. **Tone: Professional vs. Friendly?**
- Recommendation: Friendly but professional ("Let's set up..." not "Time to configure your database!")
2. **Spanish vs. English default?**
- Recommendation: Detect from user's browser locale, allow language switch
3. **Should we use bakery-specific terminology throughout?**
- Recommendation: Yes (e.g., "recipes" not "production formulas", "ingredients" not "inventory items")
---
## Document Status
**Version**: 1.0 (Initial Draft)
**Date**: 2025-11-06
**Status**: Ready for Review
**Next Steps**:
1. Review with product team
2. Validate design with UX team
3. Review technical feasibility with engineering
4. Conduct user interviews to validate JTBD assumptions
5. Create detailed wireframes/mockups
6. Begin Phase 1 implementation
**Related Documents**:
- `jtbd-analysis-inventory-setup.md` - Jobs To Be Done analysis
- `OnboardingWizard.tsx` - Existing onboarding implementation
- `AddModal.tsx` - Existing modal component architecture
**Reviewers**:
- [ ] Product Manager
- [ ] UX Designer
- [ ] Tech Lead
- [ ] Backend Engineer
- [ ] QA Lead
**Approval**: Pending
---
*End of Specification*
Reference in New Issue Copy Permalink