@fayz-ai/plugin-financial 0.1.1

package/src/FinancialPage.tsx

@@ -0,0 +1,261 @@
+import React, { useState, useCallback, useMemo } from 'react'
+import type { StoreApi } from 'zustand/vanilla'
+import { useTranslation } from '@fayz-ai/core'
+import { ModulePage, PageTransition, type ModuleNavItem } from '@fayz-ai/ui'
+import { FinancialContextProvider, type ResolvedFinancialConfig } from './FinancialContext'
+import type { FinancialDataProvider } from './data/types'
+import type { FinancialUIState } from './store'
+import type { PluginRegistryDef, PluginQuickAction } from '@fayz-ai/core'
+import { useModuleNavigation, ModuleActionBar, parseViewId } from '@fayz-ai/saas'
+import { SummaryView } from './views/SummaryView'
+import { PayablesView } from './views/PayablesView'
+import { ReceivablesView } from './views/ReceivablesView'
+import { CashRegistersView } from './views/CashRegistersView'
+import { StatementsView } from './views/StatementsView'
+import { CommissionsView } from './views/CommissionsView'
+import { CardsView } from './views/CardsView'
+import { FinancialGeneralSettings } from './components/FinancialGeneralSettings'
+import { FinancialOnboarding } from './components/FinancialOnboarding'
+
+// ---------------------------------------------------------------------------
+// View intent — what subpage + mode to show
+// ---------------------------------------------------------------------------
+
+export interface ViewIntent {
+  view: string
+  mode?: 'list' | 'new' | 'edit' | 'detail'
+  editId?: string
+}
+
+function parseIntent(activeView: string): ViewIntent {
+  // `base` collapses 'payables-detail' / 'payables-edit' etc; `id` is the canonical :id param.
+  const { base, id } = parseViewId(activeView)
+  const m = base.match(/^(payables|receivables)-(new|list|detail|edit)$/)
+  if (m) return { view: m[1], mode: m[2] as ViewIntent['mode'], editId: id }
+  return { view: activeView }
+}
+
+// ---------------------------------------------------------------------------
+// Nav builder
+// ---------------------------------------------------------------------------
+
+function buildNav(
+  config: ResolvedFinancialConfig,
+  activeView: string,
+  navigate: (view: string, hash?: string) => void,
+  t: (key: string, params?: Record<string, string | number>) => string,
+): ModuleNavItem[] {
+  const items: ModuleNavItem[] = [
+    {
+      id: 'summary',
+      label: t('financial.nav.summary'),
+      icon: 'BarChart3',
+      active: activeView === 'summary',
+      onClick: () => navigate('summary'),
+    },
+  ]
+
+  if (config.modules.payables) {
+    items.push({
+      id: 'payables',
+      label: t('financial.nav.payables'),
+      icon: 'ArrowUpCircle',
+      active: activeView.startsWith('payables'),
+      children: [
+        { id: 'payables-new', label: t('financial.nav.new'), active: activeView === 'payables-new', onClick: () => navigate('payables-new') },
+        { id: 'payables-list', label: t('financial.nav.list'), active: activeView === 'payables-list', onClick: () => navigate('payables-list') },
+        { id: 'payables-recurring', label: t('financial.nav.recurringExpenses'), active: activeView === 'payables-recurring', onClick: () => navigate('payables-recurring') },
+      ],
+    })
+  }
+
+  if (config.modules.receivables) {
+    items.push({
+      id: 'receivables',
+      label: t('financial.nav.receivables'),
+      icon: 'ArrowDownCircle',
+      active: activeView.startsWith('receivables'),
+      children: [
+        { id: 'receivables-new', label: t('financial.nav.new'), active: activeView === 'receivables-new', onClick: () => navigate('receivables-new') },
+        { id: 'receivables-list', label: t('financial.nav.list'), active: activeView === 'receivables-list', onClick: () => navigate('receivables-list') },
+      ],
+    })
+  }
+
+  if (config.modules.cashRegisters) {
+    items.push({
+      id: 'cash-registers',
+      label: t('financial.nav.cashRegisters'),
+      icon: 'Landmark',
+      active: activeView === 'cash-registers',
+      onClick: () => navigate('cash-registers'),
+    })
+  }
+
+  if (config.modules.statements) {
+    items.push({
+      id: 'statements',
+      label: t('financial.nav.statements'),
+      icon: 'Receipt',
+      active: activeView === 'statements',
+      onClick: () => navigate('statements'),
+    })
+  }
+
+  if (config.modules.commissions) {
+    items.push({
+      id: 'commissions',
+      label: t('financial.nav.commissions'),
+      icon: 'Users',
+      children: [
+        { id: 'commissions-overview', label: t('financial.nav.overview'), active: activeView === 'commissions', onClick: () => navigate('commissions') },
+        { id: 'commissions-rules', label: t('financial.nav.rules'), active: activeView === 'commissions', onClick: () => navigate('commissions') },
+      ],
+    })
+  }
+
+  if (config.modules.cards) {
+    items.push({
+      id: 'cards',
+      label: t('financial.nav.cards'),
+      icon: 'CreditCard',
+      children: [
+        { id: 'cards-overview', label: t('financial.nav.overview'), active: activeView === 'cards', onClick: () => navigate('cards') },
+        { id: 'cards-reconciliation', label: t('financial.nav.reconciliation'), active: activeView === 'cards', onClick: () => navigate('cards') },
+      ],
+    })
+  }
+
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// Main page component
+// ---------------------------------------------------------------------------
+
+export function FinancialPage({ config, provider, store, registries }: {
+  config: ResolvedFinancialConfig
+  provider: FinancialDataProvider
+  store: StoreApi<FinancialUIState>
+  registries?: PluginRegistryDef[]
+}) {
+  const { view, direction, navigate } = useModuleNavigation('/financial', {
+    summary: 0,
+    'payables-list': 0, 'payables-new': 1, 'receivables-list': 0, 'receivables-new': 1,
+    'cash-registers': 0, statements: 0, commissions: 0, cards: 0,
+    settings: 1,
+  })
+
+  const [onboardingComplete, setOnboardingComplete] = useState(() => {
+    try { return localStorage.getItem('saas-core:financial-onboarded') === 'true' } catch { return false }
+  })
+
+  const t = useTranslation()
+  const intent = parseIntent(view)
+  const isSettings = view === 'settings'
+  const nav = buildNav(config, view, navigate, t)
+
+  const quickActions = useMemo<PluginQuickAction[]>(() => {
+    const actions: PluginQuickAction[] = []
+    if (config.modules.payables) {
+      actions.push({
+        id: 'new-payable',
+        label: t('financial.quickActions.newPayable'),
+        icon: 'ArrowUpCircle',
+        description: t('financial.quickActions.newPayableDesc'),
+        action: () => navigate('payables-new'),
+      })
+    }
+    if (config.modules.receivables) {
+      actions.push({
+        id: 'new-receivable',
+        label: t('financial.quickActions.newReceivable'),
+        icon: 'ArrowDownCircle',
+        description: t('financial.quickActions.newReceivableDesc'),
+        action: () => navigate('receivables-new'),
+      })
+    }
+    if (config.modules.cashRegisters) {
+      actions.push({
+        id: 'open-cash',
+        label: t('financial.quickActions.openCashRegister'),
+        icon: 'Landmark',
+        description: t('financial.quickActions.openCashRegisterDesc'),
+        action: () => navigate('cash-registers'),
+      })
+    }
+    return actions
+  }, [config.modules])
+
+  function handleOnboardingComplete() {
+    setOnboardingComplete(true)
+    try { localStorage.setItem('saas-core:financial-onboarded', 'true') } catch {}
+  }
+
+  // Show onboarding on first visit
+  if (!onboardingComplete) {
+    return (
+      <FinancialContextProvider config={config} provider={provider} store={store}>
+        <FinancialOnboarding onComplete={handleOnboardingComplete} />
+      </FinancialContextProvider>
+    )
+  }
+
+  // Settings view
+  if (isSettings && registries && registries.length > 0) {
+    return (
+      <FinancialContextProvider 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('financial.settingsPage.title')}</h1>
+              <p style={{ color: 'var(--muted-foreground, #6b7280)', margin: '4px 0 0', fontSize: '14px' }}>{t('financial.settingsPage.subtitle')}</p>
+            </div>
+            <FinancialGeneralSettings />
+          </div>
+        </PageTransition>
+      </FinancialContextProvider>
+    )
+  }
+
+  function renderView() {
+    switch (intent.view) {
+      case 'payables':
+        return <PayablesView intent={intent} onNavigate={navigate} />
+      case 'receivables':
+        return <ReceivablesView intent={intent} onNavigate={navigate} />
+      case 'cash-registers':
+        return <CashRegistersView />
+      case 'statements':
+        return <StatementsView />
+      case 'commissions':
+        return <CommissionsView />
+      case 'cards':
+        return <CardsView />
+      default:
+        return <SummaryView />
+    }
+  }
+
+  return (
+    <FinancialContextProvider config={config} provider={provider} store={store}>
+      <ModulePage
+        title={config.labels.pageTitle}
+        subtitle={config.labels.pageSubtitle}
+        nav={nav}
+        showHeader={intent.view === 'summary' || view === 'summary'}
+        viewKey={view}
+        direction={direction}
+        headerAction={
+          <ModuleActionBar
+            quickActions={quickActions}
+            settingsPath={registries && registries.length > 0 ? '/settings/financial' : undefined}
+            settingsLabel={t('financial.settingsPage.title')}
+          />
+        }
+      >
+        {renderView()}
+      </ModulePage>
+    </FinancialContextProvider>
+  )
+}

package/src/README.md

@@ -0,0 +1,155 @@
+# Financial Plugin
+
+Accounts payable/receivable, cash registers, bank statements, and financial reporting for any SaaS vertical.
+
+## Quick Start
+
+```typescript
+import { createFinancialPlugin } from '@fayz-ai/saas-core/plugins/financial'
+
+// In your createSaasApp config:
+plugins: [
+  createFinancialPlugin({
+    currency: { code: 'BRL', locale: 'pt-BR', symbol: 'R$' },
+  }),
+]
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `modules.payables` | boolean | true | Accounts payable |
+| `modules.receivables` | boolean | true | Accounts receivable |
+| `modules.cashRegisters` | boolean | true | Cash register sessions |
+| `modules.statements` | boolean | true | Bank statements |
+| `modules.commissions` | boolean | true | Staff commissions |
+| `modules.cards` | boolean | true | Card transactions |
+| `currency` | object | BRL/pt-BR | Currency code, locale, symbol |
+| `itemTypes` | array | service, product, other | Invoice line item types |
+| `enableServiceExecution` | boolean | false | Track service execution on items |
+| `contactEntity` | object | client | Person archetype kind for contacts |
+| `locations` | array | [] | Business units (shows unit picker when 1+) |
+| `dataProvider` | FinancialDataProvider | mock | Custom data provider |
+| `navPosition` | number | 6 | Navigation order |
+
+## Architecture
+
+```
+src/plugins/financial/
+  index.ts                    # createFinancialPlugin() factory
+  types.ts                    # Pure TS domain types (zero deps)
+  registries.ts               # CRUD entities: payment methods, chart of accounts, etc.
+  store.ts                    # Zustand UI state + provider actions
+  FinancialContext.tsx         # React contexts: config, provider, store
+  FinancialPage.tsx            # Main page with ModulePage layout
+  data/
+    types.ts                  # FinancialDataProvider interface
+    mock.ts                   # In-memory mock provider
+  views/                      # All sub-views (Summary, Invoices, Cash, etc.)
+  components/                 # Settings, onboarding
+  migrations/                 # SQL migration files
+```
+
+### Data Flow
+
+```
+createFinancialPlugin(options)
+  → resolves config (labels, currency, modules, itemTypes)
+  → creates provider (mock or custom)
+  → creates zustand store (bound to provider)
+  → returns PluginManifest with route, navigation, registries, settings tab
+
+FinancialPage (rendered by plugin route)
+  → wraps children in FinancialContextProvider (config + provider + store)
+  → useModuleNavigation handles view switching + hash routing + animations
+  → each view calls useFinancialStore(selector) to read/write data
+```
+
+## Type System
+
+Core entities (in `types.ts`):
+
+| Entity | Purpose |
+|--------|---------|
+| `Invoice` | Header: direction (debit/credit), date, contact, total, status |
+| `InvoiceItem` | Line item: kind, description, qty, price, discount |
+| `FinancialMovement` | Installments & payments: amount, due date, status |
+| `BankAccount` | Bank, cash register, credit card, digital wallet |
+| `CashSession` | Open/close sessions with balance reconciliation |
+| `PaymentMethod` | Configured methods with discount/interest rules |
+| `ChartOfAccountsNode` | Hierarchical ledger accounts |
+| `CardTransaction` | Credit card installment tracking |
+
+Status enums: `InvoiceStatus`, `MovementStatus`, `TransactionDirection`, `MovementKind`
+
+## Registries (Plugin Settings)
+
+Accessible via gear icon in Financial module or in global Settings > Financial tab:
+
+| Registry | Editable | Seed Data |
+|----------|----------|-----------|
+| Payment Method | Yes | — |
+| Ledger Account | Yes | Default chart of accounts |
+| Cost Center | Yes | "General" |
+| Bank Account | Yes | — |
+| Payment Type | Read-only | Cash, PIX, Credit Card, Debit Card, Transfer, Check |
+| Card Brand | Read-only | Visa, Mastercard, Amex, Elo, etc. |
+
+## Database Migrations
+
+Run in order:
+
+1. `001_financial_base.sql` — Core tables: payment_method_types, payment_methods, bank_accounts, cash_register_sessions, invoices, invoice_items, financial_movements
+2. `002_chart_of_accounts.sql` — chart_of_accounts (self-referencing tree), cost_centers
+3. `003_card_brands.sql` — card_brands
+
+All tables use `tenant_id` referencing `saas_core.tenants(id)` for multi-tenant isolation.
+
+## Views
+
+| View | Route suffix | Description |
+|------|-------------|-------------|
+| Summary | `/financial` | Dashboard with KPIs, cash flow, overdue alerts |
+| Payables List | `/financial/payables/list` | Filterable invoice list (debit) |
+| Payables New | `/financial/payables/new` | Create payable invoice |
+| Receivables List | `/financial/receivables/list` | Filterable invoice list (credit) |
+| Cash Registers | `/financial/cash/registers` | Open/close sessions |
+| Statements | `/financial/statements` | Bank account statement viewer |
+| Cards | `/financial/cards` | Card transaction reconciliation |
+| Settings | `/financial/settings/*` | Registry CRUD management |
+
+## Extending
+
+### Custom Data Provider
+
+```typescript
+import type { FinancialDataProvider } from '@fayz-ai/saas-core/plugins/financial'
+
+const supabaseProvider: FinancialDataProvider = {
+  async getInvoices(query) { /* Supabase query */ },
+  async createInvoice(input) { /* Supabase insert */ },
+  // ... implement all methods
+}
+
+createFinancialPlugin({ dataProvider: supabaseProvider })
+```
+
+### Vertical Customization
+
+```typescript
+// Restaurant — no commissions, custom item types
+createFinancialPlugin({
+  modules: { commissions: false },
+  itemTypes: [
+    { value: 'menu_item', label: 'Menu Item' },
+    { value: 'beverage', label: 'Beverage' },
+  ],
+})
+
+// Beauty salon — with service execution tracking
+createFinancialPlugin({
+  enableServiceExecution: true,
+  contactEntity: { archetypeKind: 'client', label: 'Client' },
+})
+```

package/src/components/FinancialGeneralSettings.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+import { SettingsGroup, ToggleRow } from '@fayz-ai/saas'
+import { useTranslation } from '@fayz-ai/core'
+
+export function FinancialGeneralSettings() {
+  const t = useTranslation()
+  return (
+    <div className="space-y-4">
+      <SettingsGroup title={t('financial.settings.invoices')} description={t('financial.settings.invoicesDesc')}>
+        <ToggleRow label={t('financial.settings.autoInstallments')} description={t('financial.settings.autoInstallmentsDesc')} checked={true} onChange={() => {}} />
+        <ToggleRow label={t('financial.settings.requireDoc')} description={t('financial.settings.requireDocDesc')} checked={false} onChange={() => {}} />
+        <ToggleRow label={t('financial.settings.allowPartial')} description={t('financial.settings.allowPartialDesc')} checked={true} onChange={() => {}} />
+      </SettingsGroup>
+
+      <SettingsGroup title={t('financial.settings.cashRegister')} description={t('financial.settings.cashRegisterDesc')}>
+        <ToggleRow label={t('financial.settings.requireOpening')} description={t('financial.settings.requireOpeningDesc')} checked={true} onChange={() => {}} />
+        <ToggleRow label={t('financial.settings.autoClose')} description={t('financial.settings.autoCloseDesc')} checked={false} onChange={() => {}} />
+      </SettingsGroup>
+
+      <SettingsGroup title={t('financial.settings.notifications')} description={t('financial.settings.notificationsDesc')}>
+        <ToggleRow label={t('financial.settings.overdueAlerts')} description={t('financial.settings.overdueAlertsDesc')} checked={true} onChange={() => {}} />
+        <ToggleRow label={t('financial.settings.dailySummary')} description={t('financial.settings.dailySummaryDesc')} checked={false} onChange={() => {}} />
+      </SettingsGroup>
+    </div>
+  )
+}

package/src/components/FinancialOnboarding.tsx

@@ -0,0 +1,87 @@
+import React, { useState } from 'react'
+import { DollarSign, Landmark, CreditCard, BookOpen, ChevronRight, Check } from 'lucide-react'
+import { useTranslation } from '@fayz-ai/core'
+import { Button } from '@fayz-ai/ui'
+
+const STEPS = [
+  { id: 'welcome', icon: DollarSign, titleKey: 'financial.onboarding.welcome', descKey: 'financial.onboarding.description' },
+  { id: 'accounts', icon: Landmark, titleKey: 'financial.onboarding.accounts.title', descKey: 'financial.onboarding.accounts.description' },
+  { id: 'payments', icon: CreditCard, titleKey: 'financial.onboarding.payments.title', descKey: 'financial.onboarding.payments.description' },
+  { id: 'chart', icon: BookOpen, titleKey: 'financial.onboarding.chart.title', descKey: 'financial.onboarding.chart.description' },
+]
+
+export function FinancialOnboarding({ 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">
+        {/* Progress */}
+        <div className="flex items-center gap-1 mb-8">
+          {STEPS.map((s, i) => (
+            <div
+              key={s.id}
+              className={`h-1 flex-1 rounded-full transition-colors ${
+                i <= step ? 'bg-primary' : 'bg-muted'
+              }`}
+            />
+          ))}
+        </div>
+
+        {/* Card */}
+        <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>
+
+          {/* Step-specific hint */}
+          {step > 0 && step < STEPS.length - 1 && (
+            <div className="rounded-lg bg-muted/30 px-4 py-3 text-xs text-muted-foreground">
+              {t('financial.onboarding.configureHint')}
+            </div>
+          )}
+
+          {/* Actions */}
+          <div className="flex items-center justify-center gap-3 pt-2">
+            {step > 0 && (
+              <Button variant="outline" size="lg" onClick={() => setStep(step - 1)}>
+                {t('financial.onboarding.back')}
+              </Button>
+            )}
+            {isLast ? (
+              <Button variant="default" size="lg" onClick={onComplete}>
+                <Check className="h-4 w-4" /> {t('financial.onboarding.startUsing')}
+              </Button>
+            ) : (
+              <Button variant="default" size="lg" onClick={() => setStep(step + 1)}>
+                {step === 0 ? t('financial.onboarding.getStarted') : t('financial.onboarding.next')}
+                <ChevronRight className="h-4 w-4" />
+              </Button>
+            )}
+          </div>
+
+          {/* Skip */}
+          {!isLast && step === 0 && (
+            <button
+              onClick={onComplete}
+              className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+            >
+              {t('financial.onboarding.skip')}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/FinancialSettings.tsx

@@ -0,0 +1,31 @@
+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 FinancialSettings({ 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('financial.settingsPage.title')}</h2>
+          <p className="text-xs text-muted-foreground">{t('financial.settingsPage.subtitle')}</p>
+        </div>
+      </div>
+
+      <PluginRegistryManager registries={registries} routeBase={routeBase} />
+    </div>
+  )
+}