# Arquitetura do Sistema CD9

Este documento descreve as decisões arquiteturais globais, o stack de tecnologia e como as peças do sistema interagem entre si.

## Visão Geral

O CD9 é um sistema web logístico construído com uma arquitetura **Client-Server Separada** (Decoupled Frontend e Backend).

```mermaid
graph TD
    User([Usuário Web]) --> |React/Next.js| Frontend(CD Front)
    Frontend --> |REST / JSON APIs| Backend(CD Back)
    Backend --> |SQL| Database[(Banco de Dados Relacional)]
    Backend -.-> |Geração de Arquivos| Storage([Storage/PDF/XML])
```

## Stack Tecnológico

### Frontend (`cd_front`)
- **Framework Core:** Next.js (com base em ReactJS).
- **Estilização:** TailwindCSS / Componentes Customs de UI.
- **Requisições HTTP:** Consumo das APIs pelo lado do cliente.
- **Responsividade:** Focado primariamente na usabilidade de painéis gerenciais (Desktop/Tablets), adaptável a mobile.

### Backend (`cd_back`)
- **Framework Core:** PHP (Laravel 10/11+).
- **Controladores (Controllers):** Padrão MVC para controlar entradas e requisições HTTP REST.
- **Banco de Dados:** Banco relacional (tipicamente MySQL ou MariaDB). Toda regra de armazenamento é mapeada usando Models via Eloquent do Laravel.
- **Autenticação:** Baseado em **JWT (JSON Web Tokens)** provido pelo Laravel Sanctum.
- **Funcionalidades Críticas:**
  - `CDCivController` e `CDEstoqueController`: Coração da logística de entrada e saída.
  - `DiariaService` e `GerarDiariasEstoque`: Lógica de faturamento baseada em saldo de estoque histórico.
  - Geração de PDFs On-the-fly (`/pdf/pedido/{id}`).
  - Manipulação e Upload de XMLs para validações de nota (`uploadXmlLote`).

---

## Fluxos de Operação Principais

### 1. Entrada e Saída (O papel do CIV)
O CIV (Controle de Identificação de Veículos) dita as regras do jogo. 
- Quando um Caminhão/Módulo chega na doca para **Entrada**, o sistema gera um CIV de entrada e atrela produtos (lotes) que injetam `Estoque`.
- Quando um processo é de **Saída**, o sistema de estoque no backend varre e filtra as unidades exatas baseando-se no que foi liberado no CIV de saída.

### 2. Validação da NFe via XML
Para checar veracidade em trânsito de docas e estoque:
1. O Front envia o arquivo `.xml` via FormData (`CDMotoristaAnexoController` ou equivalente).
2. O Laravel faz conversão/parse do arquivo.
3. Extrai o conteúdo no nó `<refNFe>`.
4. Compara com a `chave` já mapeada no banco (`cd_civ_lote`). Se coincidir: Status Validação = 1 (Sucesso). Caso discorde: Status 2 (Alerta).
5. Frontend exibe os badges de feedback baseados nesse status.

### 3. Proteção e Estado de Máquina em Contratos
Certos módulos, como os Contratos, operam com regras de estado engessadas ("Vigente", "Encerrado").
A arquitetura prevê intervenção manual por supervisão (botão "Reabrir"). O front dispara para o back a senha inserida e, ocorrendo match, a API executa um override no banco permitindo que o frontend volte ao estado de formulário preenchível.

### 4. Ciclo Financeiro de Diárias e Movimentações
O sistema fecha o ciclo logístico com o financeiro:
- **Diárias**: Calculadas diariamente via Cron Job (`GerarDiariasEstoque`) ou trigger de conferência. O cálculo utiliza o saldo histórico (Entradas - Saídas até a data) subtraindo o "pulmão" do item de contrato.
- **Movimentações**: Cada entrada/saída gera um registro financeiro que pode ser faturado em lote para o Contas a Receber.
- **Integração**: Ambos os módulos alimentam o `Contas a Receber`, fechando a gestão de fluxo de caixa.

---

## Estrutura de Diretórios 

`e:\WORK\CLUBT-TI\PROJECTS\CD9`
- `/cd_back/`: Toda a responsabilidade de servidor e conexão com o banco.
- `/cd_front/`: Toda SPA (Single Page Application) do cliente.
- `/docs/`: Ponto central de registro e guidelines.
- `/.agent/`: Ferramental de automação local (Antigravity Scripts/Skills).