# 📊 MODELO DE BANCO DE DADOS - NOTAS FISCAIS

## 🎯 Objetivo

Armazenar e gerenciar notas fiscais importadas de XMLs, com suporte a:
- ✅ Múltiplas notas por viagem
- ✅ Múltiplas notas por CTe (futura geração)
- ✅ Itens detalhados
- ✅ Integração com clientes/fornecedores
- ✅ Clientes criados dinamicamente
- ✅ Auditoria completa

---

## 📋 TABELAS PRINCIPAIS

### 1️⃣ **tms001_notafiscal** (PRINCIPAL)

Armazena dados principais da Nota Fiscal importada do XML.

```sql
CAMPOS PRINCIPAIS:
├── Identificação
│   ├── id (PRIMARY KEY)
│   ├── empresa (FK)
│   ├── numero_nf (NF-123456)
│   ├── serie_nf (1)
│   └── chave_acesso (UNIQUE)
│
├── Datas
│   ├── data_emissao (2025-12-01)
│   ├── data_criacao (TIMESTAMP)
│   └── data_atualizacao (TIMESTAMP)
│
├── Emitente (Remetente)
│   ├── idemitente (FK -> dim_cliente)
│   ├── cnpj_emitente (12.345.678/0001-57)
│   ├── razaosocial_emitente
│   ├── nomefantasia_emitente
│   └── endereco_emitente
│
├── Destinatário (Cliente)
│   ├── iddestinatario (FK -> dim_cliente)
│   ├── cnpj_destinatario
│   ├── cpf_destinatario
│   ├── razaosocial_destinatario
│   └── endereco_destinatario
│
├── Valores
│   ├── valor_total (3000.00)
│   ├── valor_frete (100.00)
│   ├── valor_seguro (50.00)
│   ├── valor_desconto (0.00)
│   ├── valor_baseicms (3000.00)
│   ├── valor_icms (540.00)
│   ├── valor_ipi (77.50)
│   ├── valor_pis (229.51)
│   └── valor_cofins (228.00)
│
├── Transporte
│   ├── modo_frete (0-9)
│   └── modo_frete_desc (Descrição)
│
├── Localização
│   ├── latitude_origem (-23.5505)
│   ├── longitude_origem (-46.6333)
│   ├── latitude_destino (-22.9068)
│   ├── longitude_destino (-43.1729)
│   ├── cidade_origem (São Paulo)
│   ├── uf_origem (SP)
│   ├── cidade_destino (Rio de Janeiro)
│   └── uf_destino (RJ)
│
├── Peso & Volume
│   ├── peso_total (350.000 kg)
│   ├── peso_liquido (350.000 kg)
│   ├── peso_bruto (355.000 kg)
│   ├── qtd_itens (2)
│   └── volume_total (0.0000 m³)
│
├── Status & Controle
│   ├── status (0=Importada, 1=Vinculada, 2=Entregue, 9=Cancelada)
│   ├── idviagem (FK -> tms010_operacao) [NULLABLE]
│   ├── id_cte (ABC-2025-001) [NULLABLE]
│   └── observacoes
│
└── Auditoria
    ├── idusuario_criacao
    ├── idusuario_alteracao
```

**Índices:**
- PK: `(id, empresa)` - Particionado por empresa
- UNIQUE: `chave_acesso` - Evita duplicatas
- `numero_nf, serie_nf, empresa` - Busca rápida por número
- `cnpj_emitente` - Busca por remetente
- `cnpj_destinatario` - Busca por cliente
- `idviagem` - Busca por viagem
- `status` - Filtro por status
- `data_emissao` - Filtro por data

---

### 2️⃣ **tms001_notafiscal_itens** (ITENS)

Armazena cada item da nota fiscal (produtos).

```sql
CAMPOS:
├── id (PRIMARY KEY)
├── id_notafiscal (FK)
├── numero_item (Sequência 1, 2, 3...)
│
├── Produto
│   ├── codigo_produto (001234)
│   ├── descricao_produto (PRODUTO A - TIPO ESPECIAL)
│   ├── ncm (12345678)
│   └── cfop (5102)
│
├── Quantidade
│   ├── quantidade (100.0000)
│   └── unidade_medida (UN, KG, L, M3)
│
├── Valores
│   ├── valor_unitario (15.50)
│   ├── valor_total (1550.00)
│   └── valor_desconto (0.00)
│
├── Peso
│   ├── peso_liquido (50.000)
│   └── peso_bruto (55.000)
│
└── Status
    ├── status (0=Importado, 1=OK, 2=Divergência)
    └── observacoes
```

**Relacionamento:**
- Um-para-Muitos com `tms001_notafiscal`
- Quando deleta NF, deleta itens automaticamente (CASCADE)

---

### 3️⃣ **tms001_nf_viagem** (ASSOCIAÇÃO)

Relaciona múltiplas notas a uma viagem.

```sql
CAMPOS:
├── id (PRIMARY KEY)
├── id_notafiscal (FK)
├── id_viagem (FK -> tms010_operacao)
├── empresa (FK)
│
├── sequencia (Ordem na viagem: 1, 2, 3...)
├── percentual_viagem (100.00 ou 50.00 se compartilhada)
│
├── Totalizadores
│   ├── peso_total (Peso desta NF)
│   ├── valor_total (Valor desta NF)
│   └── quantidade_itens
│
├── Status
│   ├── status (0=Planejada, 1=Embalada, 2=Carregada, 3=Entregue)
│   ├── data_inclusao (TIMESTAMP)
│   └── observacoes
│
└── UNIQUE: (id_notafiscal, id_viagem) → Uma NF só uma vez por viagem
```

**Uso:**
```sql
-- Uma viagem pode ter VÁRIAS notas
Viagem 1 ──┬─→ NF 001
           ├─→ NF 002
           └─→ NF 003

-- Uma NF pode estar em várias viagens (viagens compartilhadas)
-- Exemplo: NF com 100 unidades, 50 na Viagem A (50%), 50 na Viagem B (50%)
```

---

### 4️⃣ **tms001_nf_importacao** (AUDITORIA)

Registra histórico de todas as importações de XML.

```sql
CAMPOS:
├── id (PRIMARY KEY)
├── empresa (FK)
├── id_notafiscal (FK - pode ser NULL se erro)
│
├── Arquivo
│   ├── nome_arquivo (documento.xml)
│   ├── tamanho_arquivo (bytes)
│   └── hash_arquivo (SHA256 - evita duplicatas)
│
├── Status
│   ├── status (sucesso, erro_xml, erro_validacao, duplicada)
│   └── mensagem_erro
│
├── Dados
│   ├── numero_nf
│   ├── chave_acesso
│   └── cnpj_emitente
│
└── Auditoria
    ├── data_importacao (TIMESTAMP)
    └── idusuario
```

**Benefícios:**
- ✅ Histórico completo de tentativas
- ✅ Previne duplicatas (via hash)
- ✅ Permite rastrear problemas

---

### 5️⃣ **tms001_cliente_temporario** (CLIENTES NOVOS)

Armazena clientes/fornecedores extraídos do XML mas não encontrados no cadastro.

```sql
CAMPOS:
├── id (PRIMARY KEY)
├── empresa (FK)
│
├── Dados
│   ├── cnpj (UNIQUE)
│   ├── cpf
│   ├── razao_social (OBRIGATÓRIO)
│   ├── nome_fantasia
│
├── Endereço Completo
│   ├── logradouro
│   ├── numero
│   ├── complemento
│   ├── bairro
│   ├── cidade
│   ├── estado
│   ├── cep
│   └── pais
│
├── Contato
│   ├── telefone
│   └── email
│
├── Controle
│   ├── tipo (emitente, destinatario)
│   ├── origem (xml_importacao)
│   ├── id_notafiscal_origem (qual NF gerou)
│   ├── status (0=Pendente, 1=Confirmado, 2=Integrado)
│   └── id_cliente_integrado (quando integrado ao dim_cliente)
│
└── Auditoria
    ├── data_criacao
    ├── data_aprovacao
    ├── idusuario_criacao
    ├── idusuario_aprovacao
    └── observacoes
```

**Fluxo:**
```
XML com CNPJ não encontrado
        ↓
Cria registro em tms001_cliente_temporario (status=0)
        ↓
Usuário revisa dados (tela com lista de pendentes)
        ↓
[Opção A] Confirma e cria cliente no dim_cliente (status=2)
[Opção B] Edita dados e salva (status=1)
[Opção C] Rejeita (status=9)
```

---

## 📈 RELACIONAMENTOS

```
dim_cliente (Emitentes/Clientes já cadastrados)
    ↑
    └─── tms001_notafiscal (emitente)
         ├─ tms001_notafiscal_itens (1:N)
         ├─ tms001_nf_viagem (1:N)
         └─ tms001_nf_importacao (1:N)

tms010_operacao (Viagens)
    ↑
    └─── tms001_nf_viagem (N:M com NF)

tms001_cliente_temporario (Clientes não encontrados)
    ↑
    └─── tms001_notafiscal (quando integrado)

FLUXO COMPLETO:
┌─────────────┐
│  XML Upload │
└──────┬──────┘
       │
       ▼
┌──────────────────────┐
│  Parse (nfe_parser)  │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  Buscar CNPJ em dim_cliente?         │
└──────┬──────────────────────────────┘
       │
   ┌───┴───┐
   │       │
   ▼       ▼
 SIM      NÃO
  │        │
  │        └──→ Criar em tms001_cliente_temporario
  │
  ▼
Inserir em tms001_notafiscal
Inserir em tms001_notafiscal_itens
Registrar em tms001_nf_importacao
```

---

## 🔄 FLUXO DE IMPORTAÇÃO

```
1. UPLOAD (múltiplos XMLs)
   ├─ Validar tipo arquivo
   ├─ Validar tamanho
   └─ Validar hash (não duplicado)

2. PARSE
   ├─ Ler XML
   ├─ Extrair dados
   └─ Validar estrutura

3. BUSCAR REFERENCIAS
   ├─ Buscar emitente em dim_cliente (por CNPJ)
   ├─ Buscar destinatário em dim_cliente
   └─ Buscar viagem (se conhecida)

4. CRIAR REGISTROS
   ├─ Inserir em tms001_notafiscal
   ├─ Inserir itens em tms001_notafiscal_itens
   ├─ Se CNPJ não encontrado: criar em tms001_cliente_temporario
   └─ Registrar em tms001_nf_importacao

5. TELA DE VALIDAÇÃO
   ├─ Mostrar notas importadas
   ├─ Mostrar clientes temporários pendentes
   ├─ Permitir vincular a viagem
   ├─ Permitir crear clientes
   └─ Permitir editar dados

6. VINCULAÇÃO
   ├─ Inserir em tms001_nf_viagem
   └─ Atualizar status = 1 (Vinculada)
```

---

## 📊 VIEWS ÚTEIS

### 1. **vw_nf_por_viagem**
Resumo de notas por viagem:
```sql
SELECT 
    viagem_id,
    qtd_notas,
    valor_total,
    peso_total,
    quantidade_itens
FROM vw_nf_por_viagem
WHERE viagem_id = 123;
```

### 2. **vw_nf_pendentes**
Notas aguardando vinculação:
```sql
SELECT 
    id,
    numero_nf,
    razaosocial_emitente,
    razaosocial_destinatario,
    valor_total
FROM vw_nf_pendentes;
```

### 3. **vw_clientes_temp_pendentes**
Clientes pendentes de aprovação:
```sql
SELECT 
    id,
    razao_social,
    cnpj,
    tipo,
    data_criacao
FROM vw_clientes_temp_pendentes;
```

---

## 🔑 CAMPOS OBRIGATÓRIOS

| Tabela | Campo | Obrigatoriedade |
|--------|-------|-----------------|
| **tms001_notafiscal** | numero_nf | ✅ SIM |
| | data_emissao | ✅ SIM |
| | cnpj_emitente | ✅ SIM |
| | valor_total | ✅ SIM |
| | status | ✅ SIM (default=0) |
| **tms001_notafiscal_itens** | descricao_produto | ✅ SIM |
| | quantidade | ✅ SIM |
| **tms001_cliente_temporario** | razao_social | ✅ SIM |
| | tipo | ✅ SIM |

---

## 🔒 CONSTRAINTS

- UNIQUE `chave_acesso` - Evita importação duplicada da mesma NF
- UNIQUE `cnpj` em cliente_temporario - Um CNPJ por cliente novo
- UNIQUE `(id_notafiscal, id_viagem)` - Uma NF só uma vez por viagem
- FK com CASCADE delete - Itens deletam com NF
- FK com SET NULL - Registros históricos não deletam NF

---

## 📈 ÍNDICES DE PERFORMANCE

- Busca por NF: `(numero_nf, serie_nf, empresa)`
- Busca por viagem: `idviagem`
- Busca por status: `status`
- Busca por data: `data_emissao`
- Busca por CNPJ: `cnpj_emitente`, `cnpj_destinatario`
- Busca por hash: `hash_arquivo` (auditoria)

---

## 💡 CASOS DE USO

### Caso 1: NF com Emitente não cadastrado
```
1. XML importado
2. CNPJ emitente não encontrado em dim_cliente
3. Criar em tms001_cliente_temporario (status=0)
4. Usuário vê na tela de validação
5. Confirma dados e cria cliente no dim_cliente
6. Atualizar tms001_cliente_temporario (status=2, id_cliente_integrado=...)
```

### Caso 2: Múltiplas NFs em uma Viagem
```
1. Viagem TMS010 criada (Origem SP, Destino RJ)
2. Usuário importa 3 XMLs
3. Na tela de validação, seleciona as 3 NFs
4. Clica "Vincular à Viagem"
5. Insere 3 registros em tms001_nf_viagem
6. Status das NFs muda para 1 (Vinculada)
```

### Caso 3: Viagem Compartilhada
```
1. NF com 100 unidades
2. 50 unidades na Viagem A (percentual=50%)
3. 50 unidades na Viagem B (percentual=50%)
4. Cria 2 registros em tms001_nf_viagem com percentuais
```

---

## 🚀 PRÓXIMAS FUNCIONALIDADES

1. **Geração automática de CTe**
   - Agrupar NFs por origem/destino
   - Gerar documento CTe
   - Atualizar id_cte em tms001_notafiscal

2. **Integração com Rastreamento**
   - Atualizar coordenadas de origem/destino
   - Integrar com mapa da tela TMS010

3. **Validação de Divergências**
   - Comparar peso/volume do XML com peso real
   - Alertar diferenças

4. **Contagem de Itens**
   - Permitir confirmar quantidade de itens
   - Gerar relatório de conformidade

---

**Versão:** 1.0  
**Data:** Dezembro 2025  
**Status:** ✅ Modelo Aprovado
