# plugin-crm

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

Every business that sells anything needs a way to track who's interested, what's in motion, and what's about to close. Most verticals end up rebuilding the same CRM badly. plugin-crm is the one sales engine — leads, a drag-style pipeline, deals, quotes, and activities — that snaps into a defineSaas app and adapts to the vertical underneath it.

## Visão geral

CRM enxuto para negócios de serviço: leads viram negócios, negócios andam por um pipeline visual, e atividades e orçamentos registram o histórico. O plugin monta a página `/sales` (rota e navegação), widgets de dashboard e uma aba de Configurações. Os módulos `quotes`, `activities` e `pipeline` são ligáveis e desligáveis por config.

Sobre dados, o CRM segue o padrão de arquétipos do Fayz: **leads são pessoas** (`saas_core.persons`, `kind='lead'`) e **negócios e orçamentos são orders** (`saas_core.orders`, `kind='deal'`/`quote`). O plugin acrescenta tabelas de extensão em `public` — `pipelines`, `pipeline_stages`, `lead_sources`, `crm_tags`, `crm_activities` e `deal_extensions` — em cinco migrations que cobrem base, atividades, views + RLS e o seed de um pipeline padrão. Provider Supabase com fallback mock.

Quando um lead é aprovado, o CRM pode promover a pessoa (`persons.kind`) e criar o registro na tabela de extensão configurada (`clientConversion`). Para IA, expõe `countCustomers` e `listLeads`. Status **beta / capability parcial**: pronto para dogfood, ainda evoluindo.

## Quando usar

- Acompanhar leads e negócios num funil visual.
- Emitir orçamentos e registrar atividades de contato.
- Converter um lead aprovado em cliente sem sair do fluxo.

## Ficha técnica

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

## Modelo de dados

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

- `plg_crm_pipelines` — name, is_default, is_active
- `plg_crm_pipeline_stages` — pipeline_id, name, order, color, probability, is_won
- `plg_crm_lead_sources` — name, is_active
- `plg_crm_tags` — name, color, is_active
- `plg_crm_deal_extensions` — order_id, pipeline_id, stage_id, probability, expected_close_date, lead_id
- `plg_crm_activity_types` — name, is_active
- `plg_crm_activities` — deal_id, lead_id, contact_id, contact_name, activity_type, title

## Tools de IA

| id | modo | descrição |
| --- | --- | --- |
| `crm.count-customers` | read | Returns the number of active customers/clients. |
| `crm.list-leads` | read | Lists leads with optional filters. |

## 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": "crm", "enabled": true } ] } } }
```

```bash
npx fayz doctor
```