# plugin-financial

`@fayz-ai/plugin-financial` · beta · Capability parcial

Most vertical SaaS bolts on finance as an afterthought: a "total" field, a spreadsheet export, and a prayer. plugin-financial makes money a first-class part of the app. It models the full order-to-cash loop — receivables, payables, cash registers, statements, card reconciliation, and commission rules — as composable modules you toggle per business.

## Visão geral

Núcleo financeiro: contas a pagar e a receber, caixas, extratos, comissões, cartões e conciliação bancária. Monta a página `/financial`, widgets de dashboard e um widget de extrato por pessoa (zona `person.detail.financial`). Os módulos `payables`, `receivables`, `cashRegisters`, `statements`, `commissions`, `cards` e `reconciliation` (opt-in, exige um conector bancário) são ligáveis por config.

Sobre dados, **as faturas são orders** (`saas_core.orders`, `kind='invoice_payable'`/`invoice_receivable'`), enquanto o razão financeiro vive em `financial_movements`. O plugin acrescenta em `public` tabelas como `payment_methods`, `payment_method_types`, `bank_accounts`, `cash_register_sessions`, `chart_of_accounts`, `card_brands` e `cost_centers` — onze migrations cobrindo plano de contas, bandeiras de cartão, order-to-cash, RLS, conciliação e split de pagamento. Provider Supabase com fallback mock.

Para IA, expõe `getRevenue`, `createInvoice` e `listPayables`. Status **beta / capability parcial**.

## Quando usar

- Controlar fluxo de caixa, contas a pagar e a receber.
- Emitir e acompanhar faturas ligadas a contatos.
- Conciliar extrato bancário com um conector — módulo opt-in.

## Ficha técnica

- **Pacote:** `@fayz-ai/plugin-financial`
- **Versão:** 0.2.0
- **Status:** beta
- **Capability:** Capability parcial
- **Tipo de produto:** Gestão (Admin/SaaS)
- **Canal stable:** `^0.2.0`
- **Migrations:** 11 migration(s)
- **Factory:** `createFinancialPlugin()`

## Modelo de dados

Tabelas instaladas (convenção `plg_` · `tenant_id` + RLS):

- `plg_financial_payment_method_types` — name, transaction_type, is_active, allowed_account_types
- `plg_financial_payment_methods` — name, payment_method_type_id, is_active, discount_mode, discount_value, interest_mode
- `plg_financial_bank_accounts` — name, account_type, bank_name, account_number, agency_number, current_balance
- `plg_financial_cash_register_sessions` — bank_account_id, status, opened_at, opened_by_user_id, opened_by_name, opening_balance
- `plg_financial_movements` — invoice_id, direction, movement_kind, amount, paid_amount, status
- `plg_financial_chart_of_accounts` — code, name, node_type, parent_id, is_active
- `plg_financial_cost_centers` — code, name, is_active
- `plg_financial_card_brands` — name, is_active
- `sequences` — kind, current_value

## Tools de IA

| id | modo | descrição |
| --- | --- | --- |
| `financial.get-revenue` | read | Returns revenue for the business in a given period. |
| `financial.create-invoice` | persist | Creates a new invoice/payable for a contact. |
| `financial.list-payables` | read | Lists outstanding payables/bills. |

## Integrações

Sem conector hospedado — provedores externos via spine de conectores (`@fayz-ai/core`).

## Integrar

Adicione o plugin em `surfaces.admin.plugins` do `app.manifest.json` e rode o doctor:

```json
{ "surfaces": { "admin": { "plugins": [ { "id": "financial", "enabled": true } ] } } }
```

```bash
npx fayz doctor
```