# Documentação técnica — Status, fluxo configurável e cores

Este documento descreve o **motor de fluxo** (`Fluxo`, `fluxostatus`, tabela **`status`** / model **`StatusFluxo`**, transições e histórico), o serviço **`FluxoService`**, como isso se conecta às **parcelas** de NF e onde entram **cores** na UI (badges dinâmicos, Bootstrap fixo, cor de pessoa, paleta). Para regras de negócio de NF e parcelas sem o editor de fluxo, ver **`Doc_Modulo_Financeiro.md`**. Definições de **tenant**, `TenantScope` e `selectedTenant`: **`Doc_Modulo_Tenant.md`**.

---

## 1. Dois “níveis” de status no sistema

### 1.1 Campo textual `status` (domínio)

Muitas entidades guardam um **string** em `status` (ex.: `PENDENTE`, `CONCLUÍDO`, `ATIVO`, `QUITADO`). O código dos controllers e services **compara** esses valores diretamente (geração de parcelas, filtros de listagem, eventos, pedidos, etc.). Esses textos precisam permanecer **alinhados** aos **`tipo`** definidos no cadastro de status de fluxo quando a entidade também usa `idfluxostatus`.

### 1.2 Fluxo configurável (tenant)

Paralelamente, existe um grafo **por tenant** e **por módulo**:

| Tabela / model | Papel |
|----------------|--------|
| **`fluxo`** (`Fluxo`) | Um registro por módulo (ex.: `nfparcela_credito`), opcionalmente com **`tipo_coluna`** / **`tipo_valor`** para variação (ex.: evento por `ideventotipo` — ver `config/fluxo.php`). |
| **`status`** (`StatusFluxo`) | Catálogo de status: **`tipo`** (chave lógica), **`rotulo_usuario`**, **`rotulo_botao`**, **`cor`**, **`cor_texto`**, flags **`eh_inicio`** / **`eh_fim`**, **`padrao`** (marca tipos “do sistema”). |
| **`fluxostatus`** (`FluxoStatus`) | Liga um **fluxo** a um **status** do catálogo, com **`ordem`**, **`eh_inicial`**, **`eh_final`**. |
| **`fluxostatustransicao`** | Arestas dirigidas: origem → destino (**transição permitida**). |
| **`fluxostatushist`** (`FluxoStatusHist`) | Auditoria: módulo, id do registro, `idfluxostatus`, usuário, observação. |

O **`FluxoService`** usa esse grafo para validar transições, atualizar `idfluxostatus` + `status` no model e disparar **regras** (ex.: saldo da agência na parcela).

---

## 2. `FluxoService` (`App\Services\FluxoService`)

| Método | Função |
|--------|--------|
| **`getFluxoPorModulo($modulo, $tipoColuna, $tipoValor)`** | Fluxo **ATIVO**; se não achar fluxo específico por tipo, alguns fluxos fazem *fallback* para o fluxo “genérico” do módulo (sem `tipo_coluna`/`tipo_valor`). |
| **`getRotuloECorPorModuloETipo($modulo, $tipo)`** | Para **exibição** (badge da NF na tela de parcela): busca `StatusFluxo` via fluxo + `tipo`; se não achar, usa **fallback** fixo para `CONCLUÍDO`, `ATIVO`, `INATIVO`, `PENDENTE`. |
| **`aplicarFluxoInicial($model)`** | No **creating**: se o model implementa `getModuloFluxo()` e ainda não tem `idfluxostatus`, preenche com o **`fluxostatus` marcado `eh_inicial`** e copia `status` = `tipo` do status. |
| **`ensureIdfluxostatusFromStatus($modulo, $model)`** | Se há `status` mas falta `idfluxostatus`, sincroniza olhando o fluxo do módulo (útil para dados legados). |
| **`getBotoesPermitidos` / `getStatusAtualEBotoes`** | Lista transições a partir do `idfluxostatus` atual, com **cores e rótulos** dos botões. |
| **`transicionar($modulo, $model, $idfluxostatus_destino, $observacao)`** | Valida aresta, chama **`aplicarRegrasPorModulo`**, persiste novo `idfluxostatus` e `status`, grava histórico. |
| **`aplicarRegrasPorModulo`** | Para **`nfparcela_debito`** / **`nfparcela_credito`**: ao entrar/sair de **`QUITADO`** com `idagencia`, chama **`NfParcelaService::concluirParcela`** / **`estornarParcela`** (igual à documentação financeira). Sem agência, **não** altera saldo. |

**Tenant:** `getIdTenant()` usa `session('selectedTenant')` ou `auth()->user()->idtenant`.

---

## 3. Trait `HasFluxo` e quem usa

- **`App\Traits\HasFluxo`** registra no **`creating`** a chamada a **`FluxoService::aplicarFluxoInicial`** e define **`fluxoStatus()`** → `belongsTo(FluxoStatus)`.
- No código analisado, **`NfParcela`** é o model que **usa** `HasFluxo` e sobrescreve **`getModuloFluxo()`**: retorna **`nfparcela_debito`** se `tipo === 'D'`, senão **`nfparcela_credito`**.

Outras entidades podem ter coluna `status` **sem** passar pelo motor de fluxo na prática (ex.: NF, evento, contrato), embora o **seeder** crie definições de fluxo para vários módulos “para frente”.

---

## 4. Seed e módulos pré-definidos (`FluxoStatusSeeder`)

O seeder **`Database\Seeders\FluxoStatusSeeder`** (também invocado ao criar fluxo novo no admin via **`FluxoController`**) define:

- **Catálogo `STATUS_POR_TIPO`:** para cada `tipo` (ex.: `PENDENTE`, `PROGRAMADO`, `QUITADO`, `CONCLUÍDO`, `EM_ANDAMENTO`, `CANCELADO`, `INATIVO`) grava **`cor`** e **`cor_texto`** em hex (ex.: quitado/concluído `#198754`, programado/em andamento `#0d6efd`, pendente `#6c757d`, inativo/cancelado tons de vermelho).
- **Módulos** com lista de tipos permitidos naquele fluxo: `nfparcela_debito`, `nfparcela_credito`, `compras`, `vendas`, `pedido`, `nf`, `evento`, `contratos`, `campanhas`, `empresas`, `veiculos`, `tagsretira`, `fornecedores`, `clientes`, `funcionarios`, `representantes`, `pessoas`.
- **Transições padrão:**
  - **Parcelas:** `PENDENTE` ↔ `PROGRAMADO` ↔ `QUITADO` / `CANCELADO`, estorno `QUITADO` → `PENDENTE`, etc. (ver comentários no seeder).
  - **Demais módulos do seeder:** malha típica `PENDENTE` → `EM_ANDAMENTO` → `CONCLUÍDO` e ramos para `CANCELADO`, com opcional `CONCLUÍDO` → `PENDENTE`.
- **`backfillNfparcelaIdfluxostatus`:** SQL que preenche `nfparcela.idfluxostatus` a partir de `nfparcela.status` + empresa/tenant.

**Tipos “do sistema”** (`TIPOS_SISTEMA`): não devem ser removidos da convenção — o código compara literais como **`QUITADO`**.

**Atenção:** o tipo **`CONCLUÍDO`** no seeder usa **acento** (`CONCLUÍDO`). Qualquer divergência com dados antigos (`CONCLUIDO`) quebra alinhamento com o fluxo.

---

## 5. Configuração administrativa

### 5.1 `FluxoController` (rotas `admin.fluxo.*`)

- Lista/cria/edita **fluxos**, adiciona ou remove **fluxostatus**, define **inicial** / **final**, salva **matriz de transições** (POST `fluxo.save-transicoes`, toggle de aresta, reorder).
- Criação de fluxo: pode disparar **`seedFluxostatusForFluxo`** para povoar status do módulo.
- **`fluxo.seed-tenant`:** replica padrões de fluxo/status para o tenant (cenário de provisionamento).

### 5.2 `StatusFluxoController` (`admin.status-fluxo.*`)

CRUD do catálogo **`StatusFluxo`** (tabela **`status`**): rótulos, **`cor`** / **`cor_texto`** (strings curtas, tipicamente hex), `tipo`, flags início/fim. Na criação, a view oferece **`PaletaCor`** (`paleta_cor`) como ajuda visual — valores ainda são gravados em `status.cor` / `status.cor_texto`.

### 5.3 `config/fluxo.php`

Chave **`modulos_com_tipo`:** hoje **`evento`** usa coluna **`ideventotipo`** para permitir **fluxos distintos por tipo de evento** (`Fluxo` com `tipo_coluna` / `tipo_valor`). Models que suportem isso devem expor **`getFluxoTipoColuna` / `getFluxoTipoValor`** (padrão no `FluxoService`).

---

## 6. UI: onde aparecem cores

### 6.1 Parcelas crédito/débito — fluxo dinâmico

- Views de edição chamam **`getStatusAtualEBotoes`** e incluem **`partials/fluxo-botoes`**: mostra **status atual** e **botões** por transição, com `style="background-color: …; color: …"` vindos do **`StatusFluxo`**.
- **`getRotuloECorPorModuloETipo('vendas'/'compras', $nf->status)`** alimenta badge da **NF** associada (rótulo + cor do módulo de compra/venda no catálogo).

**Rotas POST dedicadas:** `admin.nfparcelascredito.fluxo.transition`, `admin.nfparcelasdebito.fluxo.transition` (delegam validação e `transicionar`).

### 6.2 Barra de progresso — classes Bootstrap fixas

**`partials/status-progress`** não lê o banco: recebe **`$options`** com `status`, `percentage`, `class` (ex.: `bg-success`, `bg-warning`). O clique dispara AJAX (**`update-status-progress`**) que faz `PUT` no registro com `{ status, redirect }`. As cores são **convenção da view** que monta `$options`, não o `StatusFluxo`.

### 6.3 Switch ATIVO/INATIVO

**`partials/status-switch`:** checkbox genérico; o JS associado costuma alternar entre **ATIVO** e outro valor conforme o contexto da listagem.

### 6.4 `bg_status` nas telas de edição

Vários controllers definem **`$bg_status`** (`bg-success`, `bg-danger`, `bg-info`, `bg-warning`) com base em **comparações fixas** em PHP para o *badge* do cabeçalho — independente do fluxo configurável.

### 6.5 Cor da pessoa (`pessoa.cor`)

Campo **color picker** no formulário compartilhado de pessoas: usado para identificação visual (calendário/agenda), **não** confundir com **`status.cor`** do fluxo.

---

## 7. Histórico

**`FluxoService::registrarHistorico`** grava em **`fluxostatushist`** o módulo (string), PK do registro, `idfluxostatus` de destino, usuário autenticado e observação opcional (ex.: ao transicionar pela tela de parcela).

---

## 8. Referência rápida de arquivos

| Arquivo | Função |
|---------|--------|
| `app/Services/FluxoService.php` | Núcleo: transições, cores para UI, regras de parcela. |
| `app/Traits/HasFluxo.php` | Hook `creating` + relação `fluxoStatus`. |
| `app/Models/Fluxo.php`, `FluxoStatus.php`, `FluxoStatusTransicao.php`, `FluxoStatusHist.php` | Persistência do grafo. |
| `app/Models/StatusFluxo.php` | Catálogo (`table = status`): `tipo`, `cor`, `cor_texto`, rótulos. |
| `app/Http/Controllers/Admin/FluxoController.php` | Manutenção de fluxos e transições. |
| `app/Http/Controllers/Admin/StatusFluxoController.php` | CRUD de status + paleta. |
| `config/fluxo.php` | Módulos com fluxo por “subtipo”. |
| `database/seeders/FluxoStatusSeeder.php` | Padrão inicial por tenant e backfill de parcelas. |
| `resources/views/partials/fluxo-botoes.blade.php` | Botões de transição coloridos. |
| `resources/views/partials/status-progress.blade.php` | Barra de etapas Bootstrap. |

---

*Documento baseado na leitura do código. Após alterar `tipo` ou transições no admin, valide telas críticas (parcelas, NF) e integrações que comparam `status` como string literal.*