@fayz-ai/plugin-inventory 0.1.1

package/src/InventoryPage.tsx

@@ -0,0 +1,170 @@
+import React, { useState, useMemo } from 'react'
+import type { StoreApi } from 'zustand/vanilla'
+import { ModulePage, PageTransition, type ModuleNavItem } from '@fayz-ai/ui'
+import { InventoryContextProvider, type ResolvedInventoryConfig } from './InventoryContext'
+import type { InventoryDataProvider } from './data/types'
+import type { InventoryUIState } from './store'
+import type { PluginRegistryDef, PluginQuickAction } from '@fayz-ai/core'
+import { useModuleNavigation, ModuleActionBar, createViewRouter } from '@fayz-ai/saas'
+import { useTranslation } from '@fayz-ai/core'
+import { DashboardView } from './views/DashboardView'
+import { ProductListView } from './views/ProductListView'
+import { ProductFormView } from './views/ProductFormView'
+import { StockMovementView } from './views/StockMovementView'
+import { MovementHistoryView } from './views/MovementHistoryView'
+import { RecipesView } from './views/RecipesView'
+import { RecipeFormView } from './views/RecipeFormView'
+import { RecipeDetailView } from './views/RecipeDetailView'
+import { InventoryGeneralSettings } from './components/InventoryGeneralSettings'
+import { InventoryOnboarding } from './components/InventoryOnboarding'
+
+function buildNav(config: ResolvedInventoryConfig, view: string, navigate: (v: string) => void, t: (key: string) => string): ModuleNavItem[] {
+  const items: ModuleNavItem[] = [
+    { id: 'dashboard', label: t('inventory.nav.dashboard'), icon: 'BarChart3', active: view === 'dashboard', onClick: () => navigate('dashboard') },
+    {
+      id: 'products', label: t('inventory.nav.products'), icon: 'Package', active: view.startsWith('products'),
+      children: [
+        { id: 'products-new', label: t('inventory.nav.new'), active: view === 'products-new', onClick: () => navigate('products-new') },
+        { id: 'products-list', label: t('inventory.nav.list'), active: view === 'products-list', onClick: () => navigate('products-list') },
+      ],
+    },
+    {
+      id: 'stock', label: t('inventory.nav.stock'), icon: 'ArrowUpCircle',
+      children: [
+        { id: 'stock-entry', label: t('inventory.nav.entry'), active: view === 'stock-entry', onClick: () => navigate('stock-entry') },
+        { id: 'stock-exit', label: t('inventory.nav.exit'), active: view === 'stock-exit', onClick: () => navigate('stock-exit') },
+        { id: 'stock-history', label: t('inventory.nav.history'), active: view === 'stock-history', onClick: () => navigate('stock-history') },
+      ],
+    },
+  ]
+
+  if (config.modules.recipes) {
+    items.push({
+      id: 'recipes', label: config.labels.recipes, icon: 'BookOpen',
+      children: [
+        { id: 'recipes-list', label: config.labels.recipesList, active: view === 'recipes-list' || view.startsWith('recipes-detail:'), onClick: () => navigate('recipes-list') },
+        { id: 'recipes-new', label: config.labels.recipesNew, active: view === 'recipes-new', onClick: () => navigate('recipes-new') },
+      ],
+    })
+  }
+
+  return items
+}
+
+export function InventoryPage({ config, provider, store, registries }: {
+  config: ResolvedInventoryConfig
+  provider: InventoryDataProvider
+  store: StoreApi<InventoryUIState>
+  registries?: PluginRegistryDef[]
+}) {
+  const t = useTranslation()
+  const { view, direction, navigate } = useModuleNavigation('/inventory', {
+    dashboard: 0,
+    'products-list': 0, 'products-new': 1,
+    'stock-entry': 1, 'stock-exit': 1, 'stock-history': 0,
+    'recipes-list': 0, 'recipes-new': 1, 'recipes-detail': 1,
+    settings: 1,
+  }, 'dashboard')
+
+  const [onboardingComplete, setOnboardingComplete] = useState(() => {
+    try { return localStorage.getItem('saas-core:inventory-onboarded') === 'true' } catch { return false }
+  })
+
+  const isSettings = view === 'settings'
+  const isSummary = view === 'dashboard' || view === ''
+  const nav = buildNav(config, view, navigate, t)
+
+  const quickActions = useMemo<PluginQuickAction[]>(() => {
+    const actions: PluginQuickAction[] = [
+      {
+        id: 'new-product',
+        label: t('inventory.quickActions.newProduct'),
+        icon: 'Package',
+        description: t('inventory.quickActions.newProductDesc'),
+        action: () => navigate('products-new'),
+      },
+      {
+        id: 'stock-entry',
+        label: t('inventory.quickActions.stockEntry'),
+        icon: 'ArrowUpRight',
+        description: t('inventory.quickActions.stockEntryDesc'),
+        action: () => navigate('stock-entry'),
+      },
+      {
+        id: 'stock-exit',
+        label: t('inventory.quickActions.stockExit'),
+        icon: 'ArrowDownRight',
+        description: t('inventory.quickActions.stockExitDesc'),
+        action: () => navigate('stock-exit'),
+      },
+    ]
+    return actions
+  }, [])
+
+  if (!onboardingComplete) {
+    return (
+      <InventoryContextProvider config={config} provider={provider} store={store}>
+        <InventoryOnboarding onComplete={() => { setOnboardingComplete(true); try { localStorage.setItem('saas-core:inventory-onboarded', 'true') } catch {} }} />
+      </InventoryContextProvider>
+    )
+  }
+
+  if (isSettings && registries && registries.length > 0) {
+    return (
+      <InventoryContextProvider config={config} provider={provider} store={store}>
+        <PageTransition transitionKey="settings" direction={direction}>
+          <div style={{ padding: '24px' }}>
+            <div style={{ marginBottom: '16px' }}>
+              <h1 style={{ fontSize: '20px', fontWeight: 600, margin: 0 }}>{t('inventory.settingsPage.title')}</h1>
+              <p style={{ color: 'var(--muted-foreground, #6b7280)', margin: '4px 0 0', fontSize: '14px' }}>
+                {t('inventory.settingsPage.subtitle')}
+              </p>
+            </div>
+            <InventoryGeneralSettings />
+          </div>
+        </PageTransition>
+      </InventoryContextProvider>
+    )
+  }
+
+  const renderView = createViewRouter([
+    { id: 'products-list', render: () => <ProductListView onNew={() => navigate('products-new')} onEdit={(id) => navigate(`products-edit:${id}`)} /> },
+    { id: 'products-new', render: () => <ProductFormView onSaved={() => navigate('products-list')} /> },
+    { id: 'products-edit', render: ({ id }) => <ProductFormView editId={id!} onSaved={() => navigate('products-list')} /> },
+    { id: 'stock-entry', render: () => <StockMovementView defaultType="entry" onSaved={() => navigate('stock-history')} /> },
+    { id: 'stock-exit', render: () => <StockMovementView defaultType="exit" onSaved={() => navigate('stock-history')} /> },
+    { id: 'stock-history', render: () => <MovementHistoryView onViewDetail={(id) => navigate(`stock-detail:${id}`)} /> },
+    { id: 'stock-detail', render: ({ id }) => {
+      const movement = store.getState().movements.find((m) => m.id === id)
+      return movement
+        ? <StockMovementView defaultType={movement.movementType} viewMovement={movement} onSaved={() => navigate('stock-history')} />
+        : <MovementHistoryView onViewDetail={(mid) => navigate(`stock-detail:${mid}`)} />
+    } },
+    { id: 'recipes-list', render: () => <RecipesView onNew={() => navigate('recipes-new')} onView={(id) => navigate(`recipes-detail:${id}`)} /> },
+    { id: 'recipes-new', render: () => <RecipeFormView onSaved={(id) => id ? navigate(`recipes-detail:${id}`) : navigate('recipes-list')} /> },
+    { id: 'recipes-detail', render: ({ id }) => <RecipeDetailView recipeId={id!} onBack={() => navigate('recipes-list')} /> },
+    { id: 'dashboard', render: () => <DashboardView /> },
+  ], 'dashboard')
+
+  return (
+    <InventoryContextProvider config={config} provider={provider} store={store}>
+      <ModulePage
+        title={config.labels.pageTitle}
+        subtitle={config.labels.pageSubtitle}
+        nav={nav}
+        showHeader={isSummary}
+        viewKey={view}
+        direction={direction}
+        headerAction={
+          <ModuleActionBar
+            quickActions={quickActions}
+            settingsPath={registries && registries.length > 0 ? '/settings/inventory' : undefined}
+            settingsLabel="Inventory Settings"
+          />
+        }
+      >
+        {renderView(view)}
+      </ModulePage>
+    </InventoryContextProvider>
+  )
+}

package/src/README.md

@@ -0,0 +1,177 @@
+# Inventory Plugin
+
+Product catalog, stock management, movement tracking, and recipe/production formulas for any SaaS vertical.
+
+## Quick Start
+
+```typescript
+import { createInventoryPlugin } from '@fayz-ai/saas-core/plugins/inventory'
+
+// In your createSaasApp config:
+plugins: [
+  createInventoryPlugin({
+    currency: { code: 'BRL', locale: 'pt-BR', symbol: 'R$' },
+  }),
+]
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `modules.recipes` | boolean | true | Production recipes/technical specs |
+| `modules.stockLocations` | boolean | true | Multi-location stock |
+| `modules.batchTracking` | boolean | false | Batch numbers + expiry dates |
+| `productTypes` | array | ingredient, sale, intermediate, asset | Available product classifications |
+| `currency` | object | BRL/pt-BR | Currency code, locale, symbol |
+| `locations` | array | [] | Business units (shows unit picker when 1+) |
+| `dataProvider` | InventoryDataProvider | mock | Custom data provider |
+| `navPosition` | number | 4 | Navigation order |
+
+## Architecture
+
+```
+src/plugins/inventory/
+  index.ts                    # createInventoryPlugin() factory
+  types.ts                    # Pure TS domain types (zero deps)
+  registries.ts               # CRUD entities: units, categories, locations
+  store.ts                    # Zustand UI state + provider actions
+  InventoryContext.tsx         # React contexts: config, provider, store
+  InventoryPage.tsx            # Main page with ModulePage layout
+  data/
+    types.ts                  # InventoryDataProvider interface
+    mock.ts                   # In-memory mock provider
+  views/                      # Dashboard, Products, Stock, Recipes
+  components/                 # Settings, onboarding
+  migrations/                 # SQL migration files
+```
+
+### Data Flow
+
+Same pattern as the Financial plugin:
+
+```
+createInventoryPlugin(options)
+  → resolves config
+  → creates provider (mock or custom)
+  → creates zustand store
+  → returns PluginManifest
+
+InventoryPage
+  → InventoryContextProvider wraps all views
+  → useModuleNavigation for view switching + animations
+  → views call useInventoryStore(selector) for data
+```
+
+## Type System
+
+### Product Types
+
+Products are classified by type — a product can be one type at a time:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `ingredient` | Raw material consumed in production | Hair dye, flour |
+| `sale` | Sold directly to customers | Shampoo bottle, menu item |
+| `intermediate` | Produced internally from ingredients | Pre-mixed color, dough |
+| `asset` | Fixed asset for patrimony tracking | Equipment, furniture |
+
+The `productTypes` option lets verticals customize available types:
+
+```typescript
+// Restaurant — simplified types
+createInventoryPlugin({
+  productTypes: [
+    { value: 'ingredient', label: 'Ingredient' },
+    { value: 'sale', label: 'Menu Item' },
+  ],
+})
+```
+
+### Stock Movements
+
+| Movement Type | Direction | Description |
+|--------------|-----------|-------------|
+| `entry` | +quantity | Receiving goods from supplier |
+| `exit` | -quantity | Using/selling goods |
+| `adjustment` | +/- | Quantity correction after audit |
+| `transfer` | neutral | Between stock locations |
+| `loss` | -quantity | Waste, damage, or expiry |
+
+### Core Entities
+
+| Entity | Purpose |
+|--------|---------|
+| `Product` | Master product with type, pricing, stock levels |
+| `StockMovement` | Transaction log: entries, exits, adjustments |
+| `StockPosition` | Physical inventory by location + batch + expiry |
+| `StockLocation` | Warehouses, storage areas |
+| `Recipe` | Production formula for intermediate/final products |
+| `RecipeIngredient` | What goes into a recipe |
+| `MeasurementUnit` | Units of measure (kg, L, unit, box) |
+| `ProductCategory` | Hierarchical product organization |
+
+## Registries (Plugin Settings)
+
+Accessible via gear icon or global Settings > Inventory tab:
+
+| Registry | Seed Data |
+|----------|-----------|
+| Measurement Units | Unit, Box, Kg, g, L, mL |
+| Product Categories | — |
+| Stock Locations | — |
+
+## Database Migrations
+
+Run in order:
+
+1. `001_inventory_base.sql` — product_categories, stock_locations, products, stock_movements, stock_positions
+2. `002_recipes.sql` — recipes, recipe_ingredients
+3. `003_measurement_units.sql` — measurement_units
+
+All tables use `tenant_id` for multi-tenant isolation.
+
+## Views
+
+| View | Route suffix | Description |
+|------|-------------|-------------|
+| Dashboard | `/inventory` | KPIs: total products, low stock, stock value |
+| Products List | `/inventory/products/list` | Filterable by type |
+| Products New | `/inventory/products/new` | Create product |
+| Stock Entry | `/inventory/stock/entry` | Record goods received |
+| Stock Exit | `/inventory/stock/exit` | Record goods consumed |
+| Stock History | `/inventory/stock/history` | Movement log |
+| Recipes | `/inventory/recipes/list` | Production formulas |
+| Settings | `/inventory/settings/*` | Registry management |
+
+## Extending
+
+### Custom Data Provider
+
+```typescript
+import type { InventoryDataProvider } from '@fayz-ai/saas-core/plugins/inventory'
+
+const supabaseProvider: InventoryDataProvider = {
+  async getProducts(query) { /* Supabase query */ },
+  async createMovement(input) { /* Supabase insert + trigger */ },
+  // ... implement all methods
+}
+
+createInventoryPlugin({ dataProvider: supabaseProvider })
+```
+
+### Future: Unit Conversion System
+
+The types support multi-unit products (base unit, content unit, purchase unit) following the beautyplace pattern. Example:
+
+```
+Shampoo bottle (base: UNIT)
+  - Content: 300mL per unit
+  - Purchase: BOX of 12 units
+```
+
+This will be implemented when the Supabase provider is built.
+
+### Future: DANFE/NF-e Import
+
+Invoice XML import for automatic stock entry — will be added as a sub-module.

package/src/components/InventoryGeneralSettings.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+import { SettingsGroup, ToggleRow } from '@fayz-ai/saas'
+import { useTranslation } from '@fayz-ai/core'
+
+export function InventoryGeneralSettings() {
+  const t = useTranslation()
+  return (
+    <div className="space-y-4">
+      <SettingsGroup title={t('inventory.settings.stockManagement')} description={t('inventory.settings.stockManagementDesc')}>
+        <ToggleRow label={t('inventory.settings.lowStockAlerts')} description={t('inventory.settings.lowStockAlertsDesc')} checked={true} onChange={() => {}} />
+        <ToggleRow label={t('inventory.settings.requireReason')} description={t('inventory.settings.requireReasonDesc')} checked={true} onChange={() => {}} />
+        <ToggleRow label={t('inventory.settings.autoDeduct')} description={t('inventory.settings.autoDeductDesc')} checked={false} onChange={() => {}} />
+      </SettingsGroup>
+
+      <SettingsGroup title={t('inventory.settings.products')} description={t('inventory.settings.productsDesc')}>
+        <ToggleRow label={t('inventory.settings.requireSku')} description={t('inventory.settings.requireSkuDesc')} checked={false} onChange={() => {}} />
+        <ToggleRow label={t('inventory.settings.allowNegative')} description={t('inventory.settings.allowNegativeDesc')} checked={false} onChange={() => {}} />
+      </SettingsGroup>
+
+      <SettingsGroup title={t('inventory.settings.notifications')} description={t('inventory.settings.notificationsDesc')}>
+        <ToggleRow label={t('inventory.settings.lowStockEmail')} description={t('inventory.settings.lowStockEmailDesc')} checked={false} onChange={() => {}} />
+        <ToggleRow label={t('inventory.settings.expiryWarnings')} description={t('inventory.settings.expiryWarningsDesc')} checked={true} onChange={() => {}} />
+      </SettingsGroup>
+    </div>
+  )
+}

package/src/components/InventoryOnboarding.tsx

@@ -0,0 +1,60 @@
+import React, { useState } from 'react'
+import { Package, Ruler, MapPin, ChevronRight, Check } from 'lucide-react'
+import { useTranslation } from '@fayz-ai/core'
+import { Button } from '@fayz-ai/ui'
+
+const STEPS = [
+  { id: 'welcome', icon: Package, titleKey: 'inventory.onboarding.welcome', descKey: 'inventory.onboarding.description' },
+  { id: 'units', icon: Ruler, titleKey: 'inventory.onboarding.units.title', descKey: 'inventory.onboarding.units.description' },
+  { id: 'locations', icon: MapPin, titleKey: 'inventory.onboarding.locations.title', descKey: 'inventory.onboarding.locations.description' },
+]
+
+export function InventoryOnboarding({ onComplete }: { onComplete: () => void }) {
+  const t = useTranslation()
+  const [step, setStep] = useState(0)
+  const current = STEPS[step]
+  const isLast = step === STEPS.length - 1
+  const Icon = current.icon
+
+  return (
+    <div className="flex items-center justify-center py-12">
+      <div className="w-full max-w-lg">
+        <div className="flex items-center gap-1 mb-8">
+          {STEPS.map((_, i) => (
+            <div key={i} className={`h-1 flex-1 rounded-full transition-colors ${i <= step ? 'bg-primary' : 'bg-muted'}`} />
+          ))}
+        </div>
+        <div className="rounded-card border bg-card p-8 text-center space-y-6 shadow-sm">
+          <div className="flex justify-center">
+            <div className="flex h-16 w-16 items-center justify-center rounded-2xl bg-primary/10">
+              <Icon className="h-8 w-8 text-primary" />
+            </div>
+          </div>
+          <div>
+            <h2 className="text-xl font-bold">{t(current.titleKey)}</h2>
+            <p className="text-sm text-muted-foreground mt-2 max-w-sm mx-auto">{t(current.descKey)}</p>
+          </div>
+          <div className="flex items-center justify-center gap-3 pt-2">
+            {step > 0 && (
+              <Button variant="outline" size="lg" onClick={() => setStep(step - 1)}>{t('common.back')}</Button>
+            )}
+            {isLast ? (
+              <Button variant="default" size="lg" onClick={onComplete}>
+                <Check className="h-4 w-4" /> {t('inventory.onboarding.start')}
+              </Button>
+            ) : (
+              <Button variant="default" size="lg" onClick={() => setStep(step + 1)}>
+                {step === 0 ? t('inventory.onboarding.getStarted') : t('common.continue')} <ChevronRight className="h-4 w-4" />
+              </Button>
+            )}
+          </div>
+          {step === 0 && (
+            <button onClick={onComplete} className="text-xs text-muted-foreground hover:text-foreground transition-colors">
+              {t('inventory.onboarding.skip')}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/InventorySettings.tsx

@@ -0,0 +1,27 @@
+import React from 'react'
+import { ChevronLeft } from 'lucide-react'
+import { PluginRegistryManager } from '@fayz-ai/saas'
+import type { PluginRegistryDef } from '@fayz-ai/core'
+import { useTranslation } from '@fayz-ai/core'
+
+export function InventorySettings({ registries, routeBase, onClose }: {
+  registries: PluginRegistryDef[]
+  routeBase: string
+  onClose: () => void
+}) {
+  const t = useTranslation()
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-3">
+        <button onClick={onClose} className="flex h-8 w-8 items-center justify-center rounded-lg border hover:bg-muted bg-card shadow-button active:shadow-button-inset transition-colors">
+          <ChevronLeft className="h-4 w-4" />
+        </button>
+        <div>
+          <h2 className="text-lg font-bold">{t('inventory.settingsPage.title')}</h2>
+          <p className="text-xs text-muted-foreground">{t('inventory.settingsPage.subtitle')}</p>
+        </div>
+      </div>
+      <PluginRegistryManager registries={registries} routeBase={routeBase} />
+    </div>
+  )
+}

package/src/data/index.ts

@@ -0,0 +1,2 @@
+export type { InventoryDataProvider } from './types'
+export { createMockInventoryProvider } from './mock'