# 🌌 Sistema CD9 - Inteligência do Projeto

Este documento serve como a **"fonte da verdade"** para o sistema **CD9 (Centro de Destroca)**. Ele detalha a arquitetura, as regras de negócio críticas, a estrutura de dados e os padrões de interface que regem o desenvolvimento deste ecossistema logístico e financeiro.

---

## 🚀 1. Visão Geral e Módulos do Sistema

O CD9 é uma solução completa para gestão logística de centros de distribuição, com foco em rastreabilidade de veículos, controle rigoroso de estoque físico/fiscal e automação financeira integrada com emissão de NFS-e.

### Módulos Core:

| Módulo | Descrição |
|---|---|
| **CIV** | Controle de Identificação de Veículo — coração do sistema. Gerencia toda a jornada de caminhões, motoristas e transportadoras. |
| **AMV** | Autorização de Movimento de Veículo — vincula itens de estoque a um CIV de saída. |
| **CD Estoque** | Controle granular de lotes por marca (revenda), tipo de movimentação e estados (Físico vs Reservado). |
| **Conferência** | Módulo de conferência física de carga com abertura/fechamento de registros e geração de PDF. |
| **Validação XML** | Upload de arquivos XML de NF-e para conferência fiscal automática via chave de acesso. |
| **Contratos** | Gestão de vigência contratual, alíquotas de ISS, código de serviço e pulmão de armazenagem. |
| **Diárias** | Cálculo e faturamento de armazenagem baseado em saldo médio acima do pulmão contratual. |
| **Contas a Receber** | Geração de cobranças a partir de movimentações e diárias, com ciclo completo de recebimento. |
| **NFS-e (Digisan)** | Emissão, cancelamento e sincronização de Notas Fiscais de Serviços Eletrônicas via API Digisan. |
| **Contas a Pagar** | Controle de despesas e pagamentos operacionais. |
| **Fluxo de Caixa** | Visão consolidada de entradas e saídas financeiras. |
| **Relatórios** | Relatório CIV-AMV com visão cruzada de operações. |
| **AI Assistant** | Assistente CD9 integrado ao Google Gemini 2.5 Flash — botão flutuante em todas as telas. |

---

## ⚖️ 2. Regras de Negócio (Core Logic)

### 2.1. O Fluxo do CIV

Toda operação logística nasce ou morre em um CIV:

1. **Entrada:** Um CIV de entrada gera **Lotes** (`cd_civ_lote`) que criam registros de **Estoque** (`cd_estoque`) e **Movimentações** (`fin_movimentacoes`).
2. **Saída:** Um processo de saída requer uma **AMV** (Autorização de Movimento) que vincula itens de estoque disponível ao CIV de saída.
3. **Estados do CIV:**
   - `Aguardando` → entrada criada, aguardando início da operação.
   - `Em Operação` → carga em processo na doca. Edições de lote bloqueadas.
   - `Concluído` → Gate Out realizado. Dispara a baixa definitiva no estoque.

### 2.2. Lógica de Saldo Disponível (Stock Math)

> **Disponível** = `qtd_original` - `qtd_saida` - `qtd_reservada`

- **Reservado:** Unidades em um CIV de saída que ainda não concluíram o "Gate Out".
- **Baixa definitiva:** Ocorre APENAS quando o CIV atinge o status "Concluído".

### 2.3. Validação de XML (NF-e Fiscal)

Para evitar erros humanos na doca:
- O sistema lê o nó `<refNFe>` (ou a chave da própria nota) no XML carregado.
- Compara com o campo `chave` registrado no lote do CIV (`cd_civ_lote.chave`).
- **Status 1 (Sucesso):** Chaves idênticas — XML válido.
- **Status 2 (Divergente):** Alerta visual imediato no Dashboard e na listagem do CIV.

### 2.4. Faturamento de Diárias (Pulmão de Armazenagem)

> **Cobrança** = `(Saldo Histórico Médio - Pulmão) * Valor da Diária`

- Cada contrato possui um **Pulmão** (quantidade isenta de diária, ex: 500 unidades).
- O sistema calcula o saldo médio diário histórico via job de cálculo.
- A cobrança só incide sobre o que **excede** o pulmão contratual.
- As diárias ficam em `fin_diarias` e alimentam a geração de Contas a Receber.

### 2.5. Fluxo Financeiro Completo

```
Movimentações (CIV/AMV) + Diárias
        ↓
Contas a Receber (fin_contas_receber)
        ↓ [status: recebido]
Fluxo de Caixa (fin_caixa) — entrada automática
        ↓ [emitir NFS-e]
Nota Fiscal (fin_notas_fiscais) via Digisan API
```

### 2.6. Emissão de NFS-e (Nota Fiscal de Serviços Eletrônica)

O fluxo de emissão integra o CD9 com a API **Digisan** (homologada na Sefaz/MA):

1. O usuário seleciona uma Conta a Receber e clica em "Emitir NFS-e".
2. O sistema valida os dados do **Prestador** (tabela `cd_destrocas`: CNPJ + Inscrição Municipal).
3. Valida os dados do **Tomador** (empresa cliente: CNPJ, endereço completo, CEP, código IBGE da cidade).
4. Busca as **Regras de Imposto** por prioridade: `Contrato > Empresa > Default(5%)`.
5. Monta o payload Digisan e envia para a API.
6. Registra **auditoria** em `fin_nfse_logs` (request + response, sempre).
7. Persiste a nota em `fin_notas_fiscais` com `status_sefaz = PROCESSANDO`.
8. O frontend faz **polling** do status até AUTORIZADA ou ERRO.

**Estados da NFS-e:**
- `PROCESSANDO` — aguardando retorno da Sefaz.
- `AUTORIZADA` — nota emitida com sucesso, PDF e XML disponíveis.
- `CANCELADA` — cancelada com justificativa (mínimo 15 caracteres).
- `ERRO` — rejeição da Sefaz, verificar `mensagem_sefaz`.

**Campos importantes do payload Digisan:**
- `idExterno` → ID do CD9 (conta a receber).
- `prestador.cnpj` + `prestador.inscricaoMunicipal` → dados do CD (cd_destrocas).
- `tomador.cpfCnpj` + endereço completo com `municipio.codigoIbge`.
- `servico.itemListaServicoLC116` → código de serviço (padrão: `110401`).
- `servico.valorServicos` → valor total da conta.
- Observação: `aliquotaIss` e `valorIss` **não** são enviados (a Sefaz/MA calcula automaticamente para evitar erro E0617).

### 2.7. Contas a Receber — Status

| Código | Status | Descrição |
|---|---|---|
| 1 | `pendente` | Aguardando pagamento. |
| 2 | `vencido` | Vencida sem recebimento. |
| 3 | `recebido` | Pago — gera entrada automática no Caixa. |
| 4 | `cancelado` | Cancelada manualmente. |

---

## 🛠️ 3. Arquitetura e Stack Tecnológica

O sistema utiliza uma arquitetura **Decoupled (Client-Server)**:

### Frontend (`cd_front`)

| Item | Detalhe |
|---|---|
| Framework | Next.js 13+ (Pages Router) |
| UI Library | Material UI (MUI v5) |
| Estilização | TailwindCSS (utilitários) |
| Estado Global | Redux |
| Comunicação | `fetch` nativo via `src/services/api.js` (Bearer Token) |
| Toasts | Notyf (`src/layouts/components/interacao`) |
| Ícones | Iconify (`src/@core/components/icon`) |
| Wrapper de Página | `ApexChartWrapper` |

### Backend (`cd_back`)

| Item | Detalhe |
|---|---|
| Framework | PHP 8.2+ / Laravel 10+ |
| ORM | Eloquent |
| Auth | Laravel Sanctum (Bearer Token) |
| PDF | DomPDF (`barryvdh/laravel-dompdf`) |
| HTTP Client | Laravel Http Facade (`Illuminate\Support\Facades\Http`) |
| NFS-e | API Digisan (via `DigisanService`) |
| AI Assistant | Google Gemini 2.5 Flash (via `GeminiService`) |
| Jobs/Cron | Artisan Commands (`nfse:sync-all`, cálculo de diárias) |
| Banco | MySQL (produção em `cd9.com.br`) |

### Serviços Externos

| Serviço | Variável de Ambiente | Função |
|---|---|---|
| Digisan API | `DIGISAN_API_KEY`, `DIGISAN_BASE_URL` | Emissão de NFS-e |
| Google Gemini | `GEMINI_API_KEY` | Assistente de IA CD9 |

---

## 🗄️ 4. Estrutura do Banco de Dados

### Tabelas Core — Operacional

| Tabela | Função |
|---|---|
| `cd_civ` | Registro macro de veículos, motoristas, transportadora e status de operação. |
| `cd_civ_lote` | Vínculo entre CIV e Notas Fiscais/Produtos (contém `chave` para validação XML). |
| `cd_estoque` | Controle de saldos físicos (`qtd_original`, `qtd_saida`, `qtd_reservada`). |
| `cd_amv` | Autorização de Movimento de Veículo — relaciona CIV de saída ao estoque. |
| `cd_itensamv` | Itens detalhados de cada AMV (produto, quantidade). |
| `cd_conferencia` | Registros de conferência física de carga na doca. |
| `cd_anexos` | Paths de arquivos (XML, PDF) e logs de validação fiscal. |
| `cd_destrocas` | Dados do Centro de Destroca (Prestador para NFS-e: CNPJ, Inscrição Municipal). |

### Tabelas Core — Cadastros

| Tabela | Função |
|---|---|
| `cd_empresas` | Cadastro central: Marcas, Revendas, Transportadoras. Contém dados fiscais para NFS-e. |
| `cd_filiais` | Filiais das empresas (cidade, CNPJ por filial). |
| `cd_motoristas` | Cadastro de motoristas e seus documentos/anexos. |
| `cd_veiculos` | Frota cadastrada por transportadora. |
| `cd_produtos` | Catálogo de produtos movimentados no CD. |
| `cd_docas` | Docas disponíveis para operação. |
| `cd_contratos` | Regras comerciais: pulmão, valor da diária, alíquota ISS, código de serviço. |

### Tabelas Core — Financeiro

| Tabela | Função |
|---|---|
| `fin_movimentacoes` | Movimentações financeiras geradas por CIVs (entradas/saídas). Campo `gerado` indica se já virou Conta a Receber. |
| `fin_diarias` | Diárias de armazenagem calculadas por produto/período. |
| `fin_contas_receber` | Contas a receber com status, vencimento e vínculo à empresa. |
| `fin_notas_fiscais` | Notas Fiscais de Serviços emitidas via Digisan. Contém `numero_nfse`, `status_sefaz`, `url_pdf`, `url_xml`, `api_referencia`. |
| `fin_nfse_logs` | Log de auditoria de todas as operações de emissão/cancelamento de NFS-e (request + response). |
| `fin_contas_pagar` | Despesas e pagamentos operacionais. |
| `fin_caixa` | Entradas e saídas efetivadas no caixa (alimentado automaticamente pelo recebimento). |
| `fin_plano_contas` | Plano de contas contábil para classificação de receitas/despesas. |

### Tabelas Core — Sistema/ACL

| Tabela | Função |
|---|---|
| `usuario` | Usuários do sistema (tabela principal de auth — **não** `users`). |
| `roles` / `permissions` | Controle de acesso (ACL). |
| `admin_rotas` | Rotas do sistema cadastradas para controle de permissão. |
| `categorias` | Categorias para agrupamento de rotas/permissões. |

---

## 🎨 5. Design System & UX Standards

### 5.1. Identidade Visual

| Token | Valor | Uso |
|---|---|---|
| Primária / Ações | `#ff6b00` | Botões principais, header, FAB do AI Assistant |
| Hover Primária | `#e66000` | Estado hover de botões primários |
| Sidebar / Nav | `#4a4357` | Background da sidebar e navegação lateral |
| Background | `bg-gray-100` | Fundo geral das páginas |
| Texto Primário | `text-slate-800` | Textos principais |
| Texto Secundário | `text-gray-500` | Labels, captions |

### 5.2. Status de NFS-e (Cores)

| Status | Cor |
|---|---|
| AUTORIZADA | Verde `#2e7d32` |
| PROCESSANDO | Laranja `#e65100` |
| CANCELADA | Vermelho `#c62828` |
| ERRO | Vermelho escuro `#b71c1c` |

### 5.3. Padrões de Interface (MUI + Tailwind)

- **Modais:** Componente `ModalCentral` (`src/pages/forms_components/ModalCentral`) — drawer lateral de 50% ou 85%.
- **Tabelas:** Componente `Tabela` de `forms_components` — consistência em filtros e paginação server-side.
- **Feedback:** Toasts via `Notyf` (Sucesso: Verde, Erro: Vermelho).
- **UX de Edição:** Campos de "Senha Administrativa" para reabertura de contratos e CIVs concluídos.
- **AI Assistant:** Botão FAB laranja fixo (`position: fixed, bottom: 28, right: 28`) em todas as páginas autenticadas.

---

## 📄 6. Mapa de Páginas (Frontend Routes)

### Operacional (CD)

| Rota | Descrição |
|---|---|
| `/dashboard` | Painel analítico de estoque e CIVs pendentes. |
| `/cd/operacao/civ` | Listagem e gestão completa de CIVs (entradas/saídas). |
| `/cd/operacao/amv` | Listagem e gestão de AMVs (Autorizações de Movimento). |
| `/cd/estoque` | Visão granular de lotes, saldos disponíveis e upload de XML. |

### Financeiro

| Rota | Descrição |
|---|---|
| `/financeiro/contas-a-receber` | Listagem de cobranças com emissão de NFS-e integrada. |
| `/financeiro/contas-a-pagar` | Gestão de despesas e pagamentos. |
| `/financeiro/diarias` | Cálculo, preview e geração de faturamento de diárias. |
| `/financeiro/movimentacoes` | Movimentações financeiras brutas por CIV. |
| `/financeiro/plano-de-contas` | Cadastro do plano de contas contábil. |
| `/financeiro/fluxo-de-caixa` | Visão de caixa consolidada (entradas/saídas efetivadas). |

### Cadastros

| Rota | Descrição |
|---|---|
| `/cadastros/empresas` | Cadastro de empresas (marcas, revendas, transportadoras). |
| `/cadastros/motoristas` | Cadastro e controle de acesso de condutores. |
| `/cadastros/veiculos` | Frota por transportadora. |
| `/cadastros/contratos` | Contratos comerciais com regras de pulmão e ISS. |
| `/cadastros/docas` | Cadastro de docas operacionais. |
| `/cadastros/filiais` | Filiais das empresas (busca por CNPJ). |
| `/cadastros/destrocas` | Dados do Prestador (Centro de Destroca) para NFS-e. |
| `/cadastros/transportadoras` | Cadastro de transportadoras. |
| `/cadastros/companhias` | Companhias/Marcas. |

### Relatórios & Sistema

| Rota | Descrição |
|---|---|
| `/relatorios/civ-amv` | Relatório cruzado de CIVs e AMVs com filtros de período. |
| `/perfil` | Configurações de usuário e permissões (ACL). |
| `/permissoes` | Gestão de roles e permissões por rota. |

---

## 🔌 7. API Endpoints (Backend)

### Auth

| Método | Rota | Descrição |
|---|---|---|
| POST | `/api/auth/login` | Login — retorna Bearer Token. |
| GET | `/api/auth/me` | Dados do usuário autenticado. |
| GET | `/api/auth/logout` | Logout. |

### CD Operacional (prefixo `/api/cadastros/cd`)

| Método | Rota | Descrição |
|---|---|---|
| CRUD | `/civ` | CIVs — inclui geração de PDF assinado. |
| POST | `/civ/{id}/analyze` | Análise de CIV específico. |
| CRUD | `/amv` | AMVs com geração de PDF. |
| CRUD | `/itensamv` | Itens detalhados da AMV. |
| GET | `/estoque` | Saldos de estoque com filtros. |
| POST | `/estoque/baixa-civ/{id}` | Baixa manual de CIV no estoque. |
| POST | `/estoque/upload-xml/{loteId}` | Upload de XML para validação fiscal. |
| GET | `/conferencia/grouped` | Conferências agrupadas. |
| POST | `/conferencia/{id}/close` | Fecha conferência e gera PDF. |

### Financeiro (prefixo `/api/financeiro`)

| Método | Rota | Descrição |
|---|---|---|
| GET | `/contas-a-receber` | Lista contas com resumo financeiro. |
| PUT | `/contas-a-receber/{id}` | Atualiza status/vencimento/observações. |
| DELETE | `/contas-a-receber/{id}` | Remove conta e libera movimentações. |
| POST | `/contas-a-receber/{id}/emitir-nfse` | Emite NFS-e via Digisan. |
| GET | `/contas-a-receber/{id}/sincronizar-nfse` | Sincroniza status com Sefaz. |
| GET | `/contas-a-receber/{id}/status-nfse` | Polling de status da NFS-e. |
| POST | `/contas-a-receber/{id}/cancelar-nfse` | Cancela NFS-e com justificativa. |
| GET | `/contas-a-receber/{id}/gerar-link-doc` | Gera link assinado para download (PDF/XML). |
| GET | `/diarias/preview` | Preview de diárias antes da geração. |
| POST | `/diarias/gerar` | Gera faturamento de diárias. |
| GET | `/preview-contas-receber` | Preview de movimentações não faturadas. |
| POST | `/gerar-contas-receber` | Gera contas a receber a partir de movimentações selecionadas. |

### AI Assistant (prefixo `/api/ai`)

| Método | Rota | Descrição |
|---|---|---|
| POST | `/ai/chat` | Envia mensagem e recebe resposta do Gemini. |
| GET | `/ai/status` | Verifica se o assistente está ativo (`enabled: true/false`). |

---

## 🤖 8. AI Assistant (Módulo Removível)

O assistente usa o modelo **Gemini 2.5 Flash** e conhece as regras de negócio do CD9 via System Prompt.

### Como remover sem afetar o sistema:

**Backend:**
1. Apagar `app/Services/AI/GeminiService.php`
2. Apagar `app/Http/Controllers/AI/AiAssistantController.php`
3. Remover o bloco `// AI ASSISTANT` em `routes/api.php`
4. Remover a chave `gemini` de `config/services.php`

**Frontend:**
1. Apagar `src/components/AIAssistant/` (pasta inteira)
2. Remover as 2 linhas marcadas em `src/layouts/UserLayout.js`

### Histórico de conversa:
Armazenado apenas em `localStorage` (chave: `cd9_ai_chat_history`). Sem banco de dados. Máximo de 20 mensagens por sessão.

---

---

## 🧭 9. Guia Operacional Completo — Todos os Módulos

Esta seção documenta todos os módulos do sistema CD9 do ponto de vista do operador, com fluxos detalhados, regras e alertas importantes.

---

## 📋 MÓDULO 1 — CADASTROS BÁSICOS

### 1.1. Cadastro de Empresas
As empresas são o cadastro central do sistema. Uma mesma empresa pode ter papéis diferentes:
- **Companhia (Marca):** dono do produto armazenado (ex: Nacional, Ultragaz, Copagaz).
- **Transportadora:** responsável pelo transporte dos veículos.
- **Revenda:** distribuidor vinculado a uma companhia.

**Como cadastrar uma empresa:**
1. Acesse **Cadastros → Empresas**.
2. Clique em **Nova Empresa**.
3. Preencha CNPJ, Razão Social, Nome Fantasia e Tipo (Companhia, Transportadora ou Revenda).
4. Para empresas que emitem NFS-e, preencha também: endereço completo, CEP e cidade com código IBGE.
5. Salve. A empresa fica disponível para uso em CIVs, contratos e faturamentos.

> ⚠️ O cadastro de CNPJ, endereço e cidade é **obrigatório** para emissão de NFS-e.

---

### 1.2. Cadastro de Filiais
Filiais são unidades físicas de uma empresa (por cidade ou CNPJ específico).

**Como cadastrar:**
1. Acesse **Cadastros → Filiais**.
2. Selecione a empresa pai e informe cidade, CNPJ da filial e endereço.
3. Salve. A filial ficará vinculada à empresa e disponível nos CIVs.

---

### 1.3. Cadastro de Motoristas
Os motoristas são os condutores dos veículos registrados nos CIVs.

**Como cadastrar:**
1. Acesse **Cadastros → Motoristas**.
2. Preencha nome, CPF, CNH e validade da CNH.
3. Você pode anexar documentos (CNH, foto) ao cadastro.
4. Salve. O motorista ficará disponível para seleção nos CIVs.

> ⚠️ Motoristas com CNH vencida são sinalizados no sistema.

---

### 1.4. Cadastro de Veículos
Veículos são vinculados a uma transportadora.

**Como cadastrar:**
1. Acesse **Cadastros → Veículos**.
2. Selecione a transportadora proprietária.
3. Informe placa, tipo de veículo e capacidade.
4. Salve. O veículo estará disponível nos CIVs daquela transportadora.

---

### 1.5. Cadastro de Docas
Docas são os pontos de carregamento e descarregamento do CD.

**Como cadastrar:**
1. Acesse **Cadastros → Docas**.
2. Informe o nome/número da doca e sua capacidade.
3. Salve. A doca ficará disponível para seleção nos CIVs em operação.

---

### 1.6. Cadastro de Transportadoras
Transportadoras são empresas que operam o transporte dos veículos.

**Como cadastrar:**
1. Acesse **Cadastros → Transportadoras**.
2. Preencha CNPJ, Razão Social e Fantasia.
3. Salve. A transportadora ficará disponível nos CIVs.

---

### 1.7. Cadastro de Companhias (Marcas)
Companhias são as marcas donas do produto (ex: Ultragaz, Nacional).

1. Acesse **Cadastros → Companhias**.
2. Preencha os dados da marca e salve.
3. A companhia é usada para segmentar estoque, contratos e faturamentos.

---

### 1.8. Cadastro de Contratos

Contratos definem as regras comerciais de cada companhia com o CD.

**Campos obrigatórios:**
- **Empresa:** a companhia dona do produto.
- **Pulmão por Produto:** quantidade de unidades isentas de diária por tipo de produto.
- **Valor da Diária:** valor cobrado por unidade acima do pulmão.
- **Alíquota ISS:** percentual de imposto de serviço para NFS-e.
- **Código de Serviço LC116:** código fiscal da atividade (padrão: 110401).
- **Vigência:** data de início e fim do contrato.

**Como cadastrar:**
1. Acesse **Cadastros → Contratos**.
2. Selecione a empresa e clique em **Novo Contrato**.
3. Preencha todos os campos acima.
4. Salve — o sistema ativa o contrato e usa suas regras nos cálculos de diária e emissão de NFS-e.

> ⚠️ Só pode haver **um contrato ativo por empresa** ao mesmo tempo.
> ⚠️ Para reativar um contrato encerrado, é necessária **Senha Administrativa**.

---

### 1.9. Cadastro do Centro de Destroca (Destrocas)
Estes são os dados do **Prestador** — o próprio CD9 — usados na emissão de NFS-e.

**Como atualizar:**
1. Acesse **Cadastros → Destrocas**.
2. Preencha CNPJ e Inscrição Municipal do Centro de Destroca.
3. Salve — estes dados serão enviados automaticamente na emissão de todas as notas fiscais.

> ⚠️ Sem estes dados corretos, a emissão de NFS-e será bloqueada.

---

## 🚛 MÓDULO 2 — CIV (Controle de Identificação de Veículo)

O CIV é o coração do sistema. Todo veículo que entra ou sai do CD passa por um CIV.

### 2.1. O que é um CIV?
Um CIV representa a **jornada completa de um veículo** no CD: da chegada ao Gate Out. Ele vincula:
- O veículo e motorista
- A transportadora
- A companhia dona da carga
- Os lotes (produtos, quantidades, notas fiscais)
- O tipo de movimentação (Entrada, Saída ou Normal)

### 2.2. Estados do CIV

| Status | Significado | O que é permitido |
|---|---|---|
| **Aguardando** | Veículo registrado, aguardando doca | Editar dados e lotes |
| **Em Operação** | Veículo na doca, carga em andamento | Acompanhar, mas **lotes bloqueados** |
| **Concluído** | Gate Out realizado | Apenas visualizar — **baixa no estoque automática** |

### 2.3. Como registrar um CIV de Entrada

1. Acesse **Operação → CIV** e clique em **Novo CIV**.
2. Selecione o tipo: **Entrada**.
3. Preencha:
   - Data, Companhia (marca), Transportadora, Veículo e Motorista.
   - Doca onde a operação ocorrerá.
4. Adicione os **Lotes** da carga:
   - Produto (P05, P08, P13, P20 ou P45)
   - Quantidade conferida
   - Número da Nota Fiscal e Série
   - Chave de Acesso da NF-e (44 dígitos) — usada na validação de XML
   - Revenda (marca distribuidora, se aplicável)
5. Salve — o CIV fica com status **Aguardando**.
6. Quando o veículo entrar na doca, atualize para **Em Operação**.
7. Ao finalizar o descarregamento, mude para **Concluído** — o estoque é atualizado automaticamente.

> ⚠️ A baixa no estoque ocorre **somente** ao concluir o CIV.

### 2.4. Como registrar um CIV de Saída

Diferente da entrada, o CIV de Saída foca no carregamento de itens que já estão no estoque.

1. Acesse **Operação → CIV** e clique em **Novo CIV**.
2. Selecione o tipo: **Saída**.
3. Preencha os dados do veículo, motorista e transportadora.
4. No campo de **Itens para Saída (AMV)**, adicione os produtos e quantidades que o veículo irá carregar.
   - O sistema valida automaticamente se há saldo disponível em estoque para essa empresa.
5. Salve o CIV — o sistema gera automaticamente a **AMV vinculada** e reserva o estoque.
6. Evolua o CIV para **Em Operação** e, após o Gate Out, mude para **Concluído**.
7. O sistema realiza a baixa definitiva do estoque e processa as movimentações financeiras.

### 2.5. Anexos no CIV

Cada CIV pode ter **um único anexo** (PDF ou imagem). Regras:
- Ao enviar um novo arquivo, o anterior é substituído automaticamente.
- O anexo pode ser removido enquanto o CIV não estiver Concluído.
- O sistema gera um **PDF assinado do CIV** com link temporário de 30 minutos.

---

## 📦 MÓDULO 3 — AMV (Autorização de Movimento de Veículo)

### 3.1. O que é uma AMV?
A AMV (Autorização de Movimento de Veículo) é o documento que formaliza a saída de produtos. No CD9, ela funciona de forma integrada: ao registrar os itens de saída em um CIV, o sistema gera a AMV automaticamente para controle de estoque e faturamento.

### 3.2. Como a AMV é gerada?

O operador **não cria a AMV manualmente** em uma tela separada. O fluxo é:
1. Durante a criação ou edição de um **CIV de Saída**, o operador informa os itens e quantidades.
2. Ao salvar o CIV, o sistema cria a AMV em background e a vincula ao veículo.
3. As unidades informadas passam para o estado **Reservado** (não podem ser usadas em outra saída).
4. O sistema impede a reserva se a quantidade solicitada for maior que o saldo disponível em estoque.

### 3.3. O que acontece depois da AMV?

- As unidades ficam **Reservadas** — não aparecem como disponíveis para outras AMVs.
- Ao concluir o CIV de saída vinculado, as unidades são **baixadas definitivamente** do estoque.
- O sistema gera automaticamente **Movimentações Financeiras** com base nos valores do contrato.
- O PDF da AMV pode ser gerado com link assinado de 30 minutos.

---

## 📊 MÓDULO 4 — ESTOQUE

### 4.1. Como o estoque funciona?

O estoque é controlado por **lotes**, vinculados a CIVs de entrada. Cada lote representa uma nota fiscal com um produto e quantidade.

**Fórmula do Saldo Disponível:**
> **Disponível** = Quantidade Entrada − Quantidade Saída − Quantidade Reservada

| Campo | Significado |
|---|---|
| Quantidade Entrada | Total recebido naquele lote |
| Quantidade Saída | Já baixado definitivamente (CIVs Concluídos) |
| Quantidade Reservada | Em AMV ativa, ainda não concluída |

### 4.2. Visão do Estoque

A tela de estoque agrupa por **Produto + Companhia** e exibe:
- Saldo atual disponível
- Quantidade reservada
- Quantidade já saída
- Histórico de movimentações por lote

### 4.3. Baixa Manual de Estoque

Em casos especiais, é possível realizar a baixa de estoque de um CIV manualmente sem esperar a conclusão pelo fluxo normal. Esta ação deve ser usada com cautela.

---

## 📋 MÓDULO 5 — VALIDAÇÃO DE XML (NF-e Fiscal)

### 5.1. Para que serve?

Garante que o arquivo XML da Nota Fiscal enviada pelo fornecedor corresponde exatamente à nota cadastrada no lote do CIV.

### 5.2. Como validar

1. Acesse **Estoque** e localize o lote desejado.
2. Clique em **Upload de XML** e selecione o arquivo `.xml` da NF-e.
3. O sistema lê automaticamente a chave de acesso dentro do XML.
4. Compara com a chave cadastrada no lote.

| Resultado | Significado | Ação |
|---|---|---|
| ✅ **Válido** | Chaves idênticas | Nenhuma — lote confirmado |
| ⚠️ **Divergente** | Chaves diferentes | Verificar a nota com o fornecedor |

> ⚠️ Um lote com status **Divergente** gera alerta visual no Dashboard e na listagem do CIV.

### 5.3. Regras adicionais

- Apenas arquivos `.xml` são aceitos (máximo 10MB).
- O XML pode ser removido e substituído enquanto o CIV não estiver Concluído.
- O alerta de divergência é visual — o sistema não bloqueia automaticamente a operação.

---

## 📅 MÓDULO 6 — CONFERÊNCIA DIÁRIA

### 6.1. O que é a Conferência?

A Conferência é o processo de **contagem física diária** do estoque no CD. Ao final do dia, o operador registra quantas unidades contou fisicamente de cada produto, e o sistema compara com o estoque lógico.

### 6.2. Regras Importantes

- Só existe **uma conferência por dia** (conferência geral do CD, não por empresa).
- Não é possível abrir uma nova conferência se houver uma conferência de dia anterior ainda aberta.
- A sequência é: Aberta → Em Avaliação → Fechada.

### 6.3. Estados da Conferência

| Status | Significado |
|---|---|
| 1 — Aberta | Conferência do dia em andamento, itens podem ser adicionados |
| 2 — Em Avaliação | Enviada para aprovação, edição bloqueada |
| 4 — Fechada | Encerrada — **gera diárias automaticamente** |

### 6.4. Como abrir e fechar uma Conferência

**Abertura:**
1. Acesse **Operação → Conferência**.
2. Clique em **Abrir Conferência do Dia**.
3. O sistema registra automaticamente o snapshot do estoque lógico atual.
4. Adicione as contagens físicas por produto para cada empresa.

**Fechamento:**
1. Após finalizar as contagens, clique em **Fechar Conferência**.
2. O sistema grava os dados como snapshot definitivo.
3. **Gera automaticamente as diárias** de armazenagem para empresas com saldo acima do pulmão.
4. Gera o PDF da conferência para arquivo.

> ⚠️ O fechamento da conferência **dispara o cálculo de diárias** — esta é a origem das cobranças de armazenagem.

---

## 💰 MÓDULO 7 — DIÁRIAS (Armazenagem)

### 7.1. O que são diárias?

Diárias são cobranças de armazenagem para empresas que mantêm estoque **acima do limite contratual (Pulmão)**.

**Fórmula:**
> **Cobrança do dia** = (Saldo Médio − Pulmão) × Valor da Diária

### 7.2. Como as diárias são geradas?

As diárias são geradas **automaticamente** ao fechar a conferência diária. O sistema:
1. Calcula o saldo atual de cada empresa por produto.
2. Compara com o pulmão definido no contrato ativo.
3. Se o saldo exceder o pulmão, gera uma linha de diária para aquela empresa/produto.

### 7.3. Como gerar o faturamento das diárias

As diárias geradas ficam **pendentes** até serem faturadas manualmente:

1. Acesse **Financeiro → Diárias**.
2. Clique em **Preview** para ver quais empresas possuem diárias pendentes.
3. Revise o período, o saldo médio e o valor a cobrar.
4. Selecione as empresas a faturar.
5. Clique em **Gerar Faturamento** — o sistema cria automaticamente as **Contas a Receber** correspondentes.

> ⚠️ Só são faturadas diárias de empresas com saldo **acima do pulmão** no contrato.
> ⚠️ A data de vencimento padrão é **15 dias após o fim do período**.

---

## 🧾 MÓDULO 8 — MOVIMENTAÇÕES FINANCEIRAS

### 8.1. O que são movimentações?

Movimentações são registros financeiros gerados automaticamente quando um CIV é concluído ou uma AMV é processada. Elas representam os **eventos financeiros brutos** da operação.

**Tipos:**
- **Entrada:** gerada quando um CIV de entrada é concluído.
- **Saída:** gerada quando um CIV de saída com AMV é concluído.

### 8.2. Como ver as movimentações

1. Acesse **Financeiro → Movimentações**.
2. Filtre por empresa, período ou tipo.
3. Movimentações com status **não faturado** podem ser agrupadas em Contas a Receber.

### 8.3. Como gerar Contas a Receber a partir de movimentações

1. Acesse **Financeiro → Contas a Receber**.
2. Clique em **Gerar Contas**.
3. Selecione o período e as empresas.
4. O sistema agrupa todas as movimentações não faturadas por empresa e cria uma cobrança consolidada.
5. Confirme — as movimentações ficam marcadas como faturadas.

---

## 📑 MÓDULO 9 — CONTAS A RECEBER

### 9.1. O que são?

Contas a Receber são as cobranças geradas a partir de movimentações operacionais e diárias de armazenagem.

### 9.2. Status das Contas

| Status | Descrição | Efeito |
|---|---|---|
| **Pendente** | Aguardando pagamento | Nenhum |
| **Vencido** | Prazo expirado sem pagamento | Alerta visual |
| **Recebido** | Pagamento confirmado | Gera entrada automática no Fluxo de Caixa |
| **Cancelado** | Cancelada manualmente | Libera as movimentações vinculadas |

### 9.3. Como registrar um recebimento

1. Acesse **Financeiro → Contas a Receber**.
2. Localize a cobrança e clique em **Editar**.
3. Altere o status para **Recebido** e informe a data de pagamento.
4. Salve — o sistema registra automaticamente a entrada no **Fluxo de Caixa**.

### 9.4. Como cancelar uma conta

1. Localize a cobrança e clique em **Editar**.
2. Altere o status para **Cancelado**.
3. As movimentações vinculadas ficam disponíveis para novo faturamento.

---

## 🏦 MÓDULO 10 — NFS-e (Nota Fiscal de Serviços Eletrônica)

### 10.1. O que é a NFS-e?

A NFS-e é a Nota Fiscal de Serviços emitida pelo CD9 para as empresas clientes. A emissão é integrada com a **Sefaz/MA via API Digisan**.

### 10.2. Pré-requisitos para emissão

Para emitir uma NFS-e com sucesso, verifique:
- ✅ Empresa (Tomador) com CNPJ, endereço, CEP e código IBGE da cidade cadastrados.
- ✅ Dados do CD (Prestador) configurados em Cadastros → Destrocas.
- ✅ Contrato ativo com alíquota ISS e código de serviço LC116.
- ✅ Conta a Receber no status **Pendente** ou **Recebido**.

### 10.3. Como emitir uma NFS-e

1. Acesse **Financeiro → Contas a Receber**.
2. Localize a cobrança desejada.
3. Clique em **Emitir NFS-e**.
4. Revise no modal:
   - Dados do Tomador (empresa cliente)
   - Descrição do serviço e observação
   - Valor total
5. Confirme — o sistema envia automaticamente para a Sefaz.
6. A nota fica com status **Processando** enquanto aguarda retorno.

### 10.4. Status da NFS-e

| Status | Significado | Ação disponível |
|---|---|---|
| **Processando** | Aguardando aprovação da Sefaz | Aguardar ou sincronizar manualmente |
| **Autorizada** | Nota emitida com sucesso | Download do PDF e XML |
| **Cancelada** | Cancelada com justificativa | Nenhuma — nota inválida |
| **Erro** | Rejeitada pela Sefaz | Verificar o motivo e corrigir os dados |

### 10.5. Como sincronizar o status

Se a nota ficou parada em **Processando** por muito tempo:
1. Localize a cobrança e clique em **Sincronizar NFS-e**.
2. O sistema consulta a Sefaz e atualiza o status.

### 10.6. Como cancelar uma NFS-e

Só é possível cancelar notas com status **Autorizada**.

1. Localize a cobrança com NFS-e autorizada.
2. Clique em **Cancelar NFS-e**.
3. Informe a justificativa (mínimo **15 caracteres**).
4. Confirme — o cancelamento é enviado para a Sefaz.
5. Status muda para **Cancelada**.

> ⚠️ O cancelamento é **irreversível**. Uma nova nota precisará ser emitida se necessário.

### 10.7. Download do PDF e XML

1. Localize a cobrança com NFS-e **Autorizada**.
2. Clique em **Baixar PDF** ou **Baixar XML**.
3. O sistema gera um link assinado com validade temporária para download seguro.

---

## 💵 MÓDULO 11 — FLUXO DE CAIXA

### 11.1. Como funciona?

O Fluxo de Caixa consolida automaticamente todas as entradas e saídas financeiras do CD:

- **Entradas:** geradas automaticamente quando uma Conta a Receber é marcada como **Recebida**.
- **Saídas:** registradas manualmente em **Contas a Pagar**.

### 11.2. Como visualizar

1. Acesse **Financeiro → Fluxo de Caixa**.
2. Filtre por período para ver o consolidado de entradas e saídas.
3. O saldo exibido reflete apenas **valores efetivados** (não inclui pendentes).

---

## 💸 MÓDULO 12 — CONTAS A PAGAR

### 12.1. O que são?

Contas a Pagar registram as despesas e pagamentos operacionais do CD (fornecedores, manutenção, etc.).

### 12.2. Como registrar uma despesa

1. Acesse **Financeiro → Contas a Pagar**.
2. Clique em **Nova Conta**.
3. Preencha: descrição, valor, data de vencimento, fornecedor e plano de contas.
4. Salve — a conta fica como **Pendente**.
5. Ao realizar o pagamento, atualize o status para **Pago** — uma saída é registrada no Caixa.

---

## 📊 MÓDULO 13 — PLANO DE CONTAS

O plano de contas é a **classificação contábil** das receitas e despesas do CD.

### Como usar

1. Acesse **Financeiro → Plano de Contas**.
2. Adicione categorias como: "Armazenagem", "Diária de Botijão", "Manutenção", etc.
3. Ao criar Contas a Receber e Contas a Pagar, selecione o plano de contas correspondente para facilitar relatórios futuros.

---

## 📈 MÓDULO 14 — RELATÓRIOS

### Relatório CIV-AMV

O relatório CIV-AMV oferece uma **visão cruzada** de todas as operações de entrada e saída:

1. Acesse **Relatórios → CIV-AMV**.
2. Defina o período desejado.
3. Filtre por empresa, transportadora ou tipo de movimentação.
4. Visualize os dados ou exporte conforme necessário.

---

## 🤖 MÓDULO 15 — ASSISTENTE DE IA (CD9 AI)

### O que é?

O Assistente CD9 é um chatbot integrado ao sistema, disponível em **todas as telas** através do botão laranja flutuante no canto inferior direito.

### O que ele responde?

- Dúvidas sobre regras de negócio do CD9.
- Como usar qualquer funcionalidade do sistema.
- Explicações sobre status, fluxos e cálculos.

### O que ele **não** faz?

- Não acessa dados em tempo real do banco de dados.
- Não realiza operações no sistema.
- Não responde perguntas fora do escopo do CD9.

### Histórico de conversa

O histórico é salvo localmente no navegador (máximo 20 mensagens). Ao limpar os dados do navegador, o histórico é apagado.

---


> [!NOTE]
> Guia operacional completo. Atualizado em **maio de 2026**. Para adicionar novos fluxos, edite diretamente este arquivo — a Central de Ajuda lerá automaticamente as atualizações.