# Documentação técnica — Seeders e dados iniciais

Este documento lista **todas as classes em `database/seeders/`**, se estão **ligadas** ao fluxo normal da aplicação, **quando executam** e o que populam. Também cita **migrations que inserem dados** (não são seeders, mas cumprem papel semelhante).

**Índice geral:** **`Doc_INDICE.md`**.

---

## 1. Visão rápida

| Classe | “Ativo” no fluxo? | Quando roda |
|--------|-------------------|-------------|
| **`DatabaseSeeder`** | Sim, como orquestrador | `php artisan db:seed` ou `migrate:fresh --seed` / `migrate:refresh --seed` (classe padrão) |
| **`EstruturaContabilSeeder`** | Sim | Chamado por `DatabaseSeeder`; também `php artisan db:seed --class=EstruturaContabilSeeder` |
| **`FluxoStatusSeeder`** | Sim | Novo **tenant** (`TenantObserver`); criação de **fluxo** novo no admin; ação **“recriar fluxos”** no índice de fluxos; `db:seed --class=FluxoStatusSeeder` (todos os tenants + backfill) |
| **`FormapagamentoFluxoSeeder`** | Manual | **Somente** módulo `formapagamento` (ATIVO ↔ INATIVO) + backfill `idfluxostatus`; `db:seed --class=FormapagamentoFluxoSeeder` |
| **`FinalidadeFiscalSeeder`** | Sim | Novo **tenant** (`TenantObserver`); `run()` para todos os tenants; `runForTenant($id)` isolado |
| **`PaletaCorPadraoSeeder`** | Opcional / manutenção | **Não** é chamado pelo `TenantObserver` (cores são criadas **inline** no observer). Útil para tenants antigos sem paleta: `db:seed --class=PaletaCorPadraoSeeder` |
| **`CodigoTributacaoNacionalSeeder`** | Manual | **Só** se alguém rodar `php artisan db:seed --class=CodigoTributacaoNacionalSeeder` |
| **`LinhaDreSeeder`** | Manual (via Classificacao) | Chamado por **`ClassificacaoContabilPadraoSeeder`**; catálogo global **`linhadre`** |
| **`ClassificacaoContabilPadraoSeeder`** | Manual | `db:seed --class=ClassificacaoContabilPadraoSeeder` — parâmetros DRE/DFC em **`classificacao_contabil_padrao`** |
| **`TipoPessoaSeed`** | **Não** (órfão) | **Não** referenciado em `DatabaseSeeder` nem em observers; implementação de `insert` é **inválida** para dois registros (ver § 9) |

---

## 2. `DatabaseSeeder`

**Arquivo:** `database/seeders/DatabaseSeeder.php`

**`run()`:**

1. Resolve **`idtenant`**: primeiro tenant sem escopo global, ou **`1`** se vazio.
2. Cria **um usuário** via `User::factory()` (`name` Admin, `email` admin@material.com, `password` — valor literal no código; em produção deve ser trocado / uso apenas em dev).
3. Chama **`$this->call([EstruturaContabilSeeder::class])`**.

**Não chama:** `FluxoStatusSeeder`, `FinalidadeFiscalSeeder`, `PaletaCorPadraoSeeder`, `CodigoTributacaoNacionalSeeder`, `TipoPessoaSeed`.

**Implicação:** em ambiente novo com **`db:seed`**, a **estrutura contábil** é criada **desde que** existam tenant e empresa (ver § 3). **Fluxos e finalidades fiscais** por tenant vêm do **`TenantObserver`** ao **criar tenant pela aplicação**, não deste seeder global.

---

## 3. `EstruturaContabilSeeder`

**Arquivo:** `database/seeders/EstruturaContabilSeeder.php`

**Função:** sincroniza a árvore **DRE em 4 níveis** (`GrupoConta` → `GrupoItem` → `Item` → `TipoProdutoServico`) a partir da lista canônica em `getLinhas()` (centenas de linhas de negócio).

**`run()`:**

- Resolve tenant e empresa: variáveis de ambiente **`TENANT_ID`** ou **`ESTRUTURA_CONTABIL_TENANT_ID`**, senão **primeiro** tenant e **primeira** empresa com escopo padrão.
- Se faltar tenant ou empresa, emite **warning** e encerra.
- Faz `firstOrCreate` em massa; opção interna **`$cleanup`** (padrão `false`) pode remover níveis fora da lista (subcategoria só se não usada por `prodserv`).

**Quando roda:** via `DatabaseSeeder` ou comando isolado com `--class`.

---

## 4. `FluxoStatusSeeder`

**Arquivo:** `database/seeders/FluxoStatusSeeder.php`

**Função:** cria registros em **`status`** (`StatusFluxo`) e **`fluxo`** / **`fluxostatus`** / transições para os **módulos** definidos em `MODULOS` (parcelas crédito/débito, compras, vendas, pedido, nf, evento, contratos, campanhas, empresas, veículos, tags, cadastros de pessoas, etc.).

**Métodos principais:**

- **`run()`** — para **cada** tenant existente (ou `[1]` se vazio), chama `runForTenant`; em seguida **`backfillNfparcelaIdfluxostatus()`** (alinhamento de parcelas).
- **`runForTenant(int $idtenant)`** — `seedStatus` + `seedFluxo` para cada módulo.
- **`seedFluxostatusForFluxo(Fluxo $fluxo)`** — usado quando um **fluxo novo** é criado pelo admin e estava “recently created”.

**Gatilhos automáticos / UI:**

| Gatilho | Onde |
|---------|------|
| Novo tenant | `TenantObserver::created` → `runForTenant($idtenant)` |
| Novo fluxo manual | `FluxoController` (store) → `seedFluxostatusForFluxo` se o fluxo foi criado agora |
| Recriar fluxos do tenant | `POST admin/fluxo/seed-tenant` → `FluxoController::seedForTenant` → `runForTenant` |

**Comando manual:** `php artisan db:seed --class=FluxoStatusSeeder` (processa **todos** os tenants + backfill).

### 4.1 `FormapagamentoFluxoSeeder` (somente forma de pagamento)

**Arquivo:** `database/seeders/FormapagamentoFluxoSeeder.php`

**Função:** para cada tenant, garante status **ATIVO** / **INATIVO**, recria o fluxo **`formapagamento`** (transições Ativar ↔ Inativar) e executa backfill de **`formapagamento.idfluxostatus`**. Não altera outros módulos.

**Comando:** `php artisan db:seed --class=FormapagamentoFluxoSeeder`

**Um tenant:** `(new \Database\Seeders\FormapagamentoFluxoSeeder)->runForTenant($idtenant);`

---

## 5. `FinalidadeFiscalSeeder`

**Arquivo:** `database/seeders/FinalidadeFiscalSeeder.php`

**Função:** `updateOrCreate` em **`FinalidadeFiscal`** por tenant, com códigos numéricos e descrições (uso contábil / NF-e).

**`run()`** — todos os tenants (ou `[1]` se nenhum).

**`runForTenant(int $idtenant)`** — um tenant.

**Gatilho:** `TenantObserver::created` chama `runForTenant` para o tenant recém-criado.

---

## 6. `PaletaCorPadraoSeeder`

**Arquivo:** `database/seeders/PaletaCorPadraoSeeder.php`

**Função:** para cada tenant **sem** nenhuma linha em **`paleta_cor`**, insere as cores de **`config('paleta_cores.padrao')`**.

**Não** é invocado pelo `TenantObserver` — no **`TenantObserver`** as cores são criadas **diretamente** com o mesmo `config`, linha a linha, para o novo tenant.

**Uso:** rodar **manualmente** após deploy ou para corrigir tenants antigos:  
`php artisan db:seed --class=PaletaCorPadraoSeeder`

---

## 7. `CodigoTributacaoNacionalSeeder`

**Arquivo:** `database/seeders/CodigoTributacaoNacionalSeeder.php`

**Função:** parseia o texto embutido (lista anexa LC 116/2003, referência Gov.br no comentário do arquivo) e insere/atualiza **`codigo_tributacao_nacional`** (`CodigoTributacaoNacional`).

**Escopo:** dados **globais** na tabela (sem `idtenant` no trecho analisado).

**Quando roda:** **somente** se executado explicitamente:  
`php artisan db:seed --class=CodigoTributacaoNacionalSeeder`

---

## 8. `LinhaDreSeeder` e `ClassificacaoContabilPadraoSeeder`

### 8.1 `LinhaDreSeeder`

**Arquivo:** `database/seeders/LinhaDreSeeder.php`

**Função:** popula a tabela global **`linhadre`** (códigos como receita bruta, deduções, custos variáveis, despesas fixas, excluir do DRE). Idempotente.

**Quando:** automaticamente no início de **`ClassificacaoContabilPadraoSeeder::run()`**; isolado: `php artisan db:seed --class=LinhaDreSeeder`.

### 8.2 `ClassificacaoContabilPadraoSeeder`

**Arquivo:** `database/seeders/ClassificacaoContabilPadraoSeeder.php`

**Função:** define padrões em **`classificacao_contabil_padrao`** por **nome** de grupo conta (ex.: Receita Bruta → linha DRE + `FCO`) e exceções por subcategoria. Não substitui a árvore do **`EstruturaContabilSeeder`**.

**Comando:** `php artisan db:seed --class=ClassificacaoContabilPadraoSeeder`

**Propagação ao tenant:** após seed/migrations, rodar **`php artisan contabilidade:sincronizar-classificacao`** para atualizar `grupoconta.idlinhadre`, `grupoconta.tipo_fluxo` e `prodservtipo.idlinhadre` conforme nomes cadastrados.

**Documentação:** **`Doc_Modulo_Produto_Servico.md`** § 2.1.1; dashboards **`Doc_Modulo_Dashboards.md`**.

---

## 9. `TipoPessoaSeed`

**Arquivo:** `database/seeders/TipoPessoaSeed.php`

**Estado:** **não referenciado** em `DatabaseSeeder`, observers ou controllers.

**Código:** uso de `DB::table('tipopessoa')->insert([...], [...])` com **dois argumentos** não é a assinatura correta do Laravel para inserir duas linhas (o esperado seria um único array de arrays ou duas chamadas). Tratar como **legado / quebrado** até revisão.

---

## 10. Dados iniciais fora de `database/seeders/` (migrations)

Não são classes `Seeder`, mas **populam o banco** ao rodar `php artisan migrate`:

| Migration (exemplo) | Tabela / efeito |
|---------------------|-----------------|
| **`2025_02_06_000003_seed_pdv_motivos_cancelamento`** | Insere motivos padrão em **`pdv_motivo_cancelamento`** |
| **`2026_03_15_120000_nfparcela_status_quitado_programado_cancelado`** | Altera status de **`nfparcela`**, ajusta **`fluxostatus`**, pode inserir **`status`** (`PROGRAMADO`, etc.) — evolução do modelo de parcelas |

Outras migrations podem conter `insert` pontuais; buscar por `insert(` em `database/migrations` ao auditar.

---

## 11. Comandos úteis

```bash
# Roda DatabaseSeeder (usuário demo + EstruturaContabilSeeder)
php artisan db:seed

# Seeder específico
php artisan db:seed --class=FluxoStatusSeeder
php artisan db:seed --class=FinalidadeFiscalSeeder
php artisan db:seed --class=PaletaCorPadraoSeeder
php artisan db:seed --class=CodigoTributacaoNacionalSeeder
php artisan db:seed --class=EstruturaContabilSeeder
php artisan db:seed --class=ClassificacaoContabilPadraoSeeder

# Sincroniza classificação DRE/DFC nos cadastros do tenant
php artisan contabilidade:sincronizar-classificacao
php artisan contabilidade:sincronizar-classificacao --sem-sobrescrever

# Fresh + seed (apaga tudo e migra de novo + DatabaseSeeder)
php artisan migrate:fresh --seed
```

---

## 12. Referência cruzada

- **Tenant e provisionamento:** **`Doc_Modulo_Tenant.md`** (menciona `FinalidadeFiscalSeeder` no observer).
- **Fluxo / status:** **`Doc_Modulo_Status_Fluxo_Cores.md`**.
- **Produto / DRE / DFC / `TipoProdutoServico`:** **`Doc_Modulo_Produto_Servico.md`**.
- **Dashboards DRE e DFC:** **`Doc_Modulo_Dashboards.md`**.
- **PDV e motivos de cancelamento:** **`Doc_Modulo_PDV.md`** (tabela `pdv_*`).

---

*Documento baseado na leitura do código. Ao criar novo seeder, atualize a tabela da § 1 e o corpo correspondente.*