Workflow Playbook
Product Master Workflow
How the product record behaves from first save, including singleProduct and hasVariants behavior and field visibility after create.
Audience: Catalog admins, inventory leads, and implementation consultants.
Collections and Responsibilities
Products
product
Main catalog record for title, provider, descriptions, and base pricing/stock defaults.
Product Variants
productVariant
Execution-level inventory record. Sales and purchases update stock on variants, not on product master directly.
Suppliers
supplier
Provider relation used by purchasing and operational ownership.
Categories
categories
Classification layer for reporting, filtering, and navigation.
Workflow Timeline
Step 1
Step 1: Create base product record
Fill title, provider, and core attributes, then save once to create persistent product ID.
Step 2
Step 2: Product mode fields become available after create
singleProduct and hasVariants are update-time controls. They are intentionally not editable on the first create screen.
Step 3
Step 3: Choose one model
Use singleProduct for one operational stock record, or hasVariants for multi-option products.
Step 4
Step 4: Save and verify side effects
Simple mode auto-syncs a default variant. Variant mode enables options and generated real variants.
Step 5
Step 5: Control transitions carefully
Conflict resolution hook keeps singleProduct and hasVariants mutually exclusive during updates.
Field Guide (Required vs Optional)
| Field | Requirement | Behavior |
|---|---|---|
Product Title title | Required | Main product name shown across admin and sales forms. |
Provider provider | Required | Supplier relationship is mandatory on product. |
SKU Code sku | Required | Unique per tenant; auto-generated if empty and collision-safe. |
Slug slug | Auto / System | Auto-generated from title and kept read-only. |
Simple Product (No Variants) singleProduct | Conditional | Available only after create and only when hasVariants is not active. |
Has Variants hasVariants | Conditional | Available only after create and only when singleProduct is not active. |
Option Name productOptions[].name | Conditional | Required per option row when hasVariants=true. |
Pricing & Inventory price, costPrice, stock, inStock | Optional | Base values. Final operational values are held at variant level. |
Product Details & Media category, barcode, shortDescription, longDescription, media | Optional | Commercial and descriptive enrichment fields. |
Decision Scenarios
If this happens
You check singleProduct after create
System creates/updates an isDefault variant and syncs stock/price/cost from product to that variant.
Timing: Immediately after product save (afterChange).
If this happens
You check hasVariants
Variant options and variants tabs are enabled; you can generate and persist real variants.
Timing: At edit-time UI and on variant builder submission.
If this happens
Both singleProduct and hasVariants are true in update payload
Hook resolves conflict: hasVariants wins when productOptions exist; otherwise singleProduct wins.
Timing: beforeChange on product update.
If this happens
You move from singleProduct to real variants
Default placeholder variant is removed once hasVariants=true to avoid duplicate stock ownership.
Timing: afterChange on product update.
Automatic Side Effects
- Product SKU is auto-generated and uniqueness-checked when missing.
- Product slug is generated from title.
- Simple product mode keeps default variant and product fields synchronized.
Operational Controls
- Do not train users to set mode flags during first create; this is intentionally a post-create action.
- Reconcile inventory at variant level, not product master level.
- When migrating from simple to variants, define options first then generate variants in one controlled cycle.