# TMS010 - OPERAÇÃO DE TRANSPORTE
## Arquitetura e Fluxo de Negócio

---

## 1. VISÃO GERAL DO MÓDULO

### Objetivo
Módulo integrado que gerencia operações de transporte desde a **contratação comercial de fretes** até a **conclusão com documentação fiscal e prova de entrega**.

### Integração com Outros Módulos
- **Comercial**: Contratação de fretes e cotações
- **Programação**: Veículos, motoristas e agendamentos
- **Fiscal**: CTE, Manifesto, NF-e
- **Rastreamento**: Geolocalização em tempo real
- **Financeiro**: Custos e margens

---

## 2. ESTRUTURA DE TABELAS

### 2.1 TABELA PRINCIPAL: `tms010_operacao`
**Responsabilidade**: Registra a operação de transporte e coordena todos os dados relacionados

#### Campos Principais:
- `numero_operacao`: Identificador único da operação
- `data_operacao`: Data de registro da operação
- `tipo_operacao`: 
  - FRETE_CONTRATADO (inicial, cotação aceita)
  - FRETE_AGENDADO (veículo/motorista designado)
  - FRETE_EXECUTADO (em andamento)
- `status_operacao`: 
  - RASCUNHO → COTADA → CONTRATADA → AGENDADA → EM_TRANSPORTE → ENTREGUE
- `valor_total`: Valor final (frete + impostos + adicionais - descontos)
- `status_documentacao`: Controla geração de CTE, Manifesto, NF-e

#### Datas Importantes:
- `data_prevista_coleta` e `data_prevista_entrega`: Prazos comerciais
- `data_real_coleta` e `data_real_entrega`: Execução real

---

### 2.2 `tms010_operacao_itens`
**Responsabilidade**: Detalhes de cada carga/volume na operação

#### Características:
- Uma operação pode ter **múltiplos itens** (multiplos volumes)
- Cada item tem: quantidade, peso, volume, valor
- Rastreia peso e volume por item
- Status individual: ABERTO, COLHIDO, ENTREGUE, DANIFICADO

#### Fórmula de Cálculo:
```
peso_total = quantidade × peso_unitario
volume_total = quantidade × volume_unitario
valor_item = valor_peso + valor_volume
```

---

### 2.3 `tms010_operacao_cotacoes`
**Responsabilidade**: Histórico de propostas/cotações de fretes

#### Fluxo:
1. **Cliente solicita frete** → Múltiplas cotações de fornecedores
2. **Cotações abertas** → Validação de prazos, valores
3. **Cotação aceita** → Status muda para ACEITA
4. **Cotação rejeitada/expirada** → Status REJEITADA/EXPIRADA

#### Campos:
- `status_cotacao`: ABERTA, ACEITA, REJEITADA, EXPIRADA
- Termo de pagamento (prazo, forma)
- Validade da cotação

---

### 2.4 `tms010_operacao_programacao`
**Responsabilidade**: Detalhes de execução da viagem (veículo, motorista, rotas)

#### Conceito de "Pernas":
- Uma operação pode ter **múltiplas pernas** (transbordo, paradas intermediárias)
- Exemplo: São Paulo → Campinas (Perna 1) → Rio de Janeiro (Perna 2)
- Cada perna pode ter **motorista diferente**

#### Campos:
- `numero_perna`: Sequência (1ª perna, 2ª perna, etc.)
- `id_veiculo`, `id_motorista`, `id_motorista_aux`: Recursos alocados
- `data_saida_prevista` / `data_saida_real`: Tracking de horários
- `distancia_percorrida`: KM real percorrido
- `temperatura_minima/maxima`: Para carga refrigerada

---

### 2.5 `tms010_operacao_documentos`
**Responsabilidade**: Registro de documentos emitidos (CTE, Manifesto, NF-e)

#### Tipos de Documentos:
- **CTE**: Conhecimento de Transporte Eletrônico
- **MANIFESTO**: Manifesto de Carga
- **NFE**: Nota Fiscal Eletrônica (importação/vinculação)
- **AVERBACAO**: Averiguação de valores
- **COMPROVANTE_ENTREGA**: Prova de entrega

#### Status:
- GERADO → EMITIDO → TRANSMITIDO → AUTORIZADO (SEFAZ)
- Rastreia protocolos SEFAZ e chaves de acesso

---

### 2.6 `tms010_operacao_nfe`
**Responsabilidade**: Importação e vinculação de NF-e à operação

#### Fluxo:
1. **Importação de NF-e**: Usuário fornece chave ou arquivo XML
2. **Validação**: Emitente, destinatário, valores
3. **Vinculação**: Associação com a operação de transporte
4. **Rastreamento**: Peso e volume da carga

---

### 2.7 `tms010_operacao_rastreamento`
**Responsabilidade**: Histórico de eventos e posicionamento GPS

#### Tipos de Evento:
- SAIDA, CHEGADA, PARADA, ALERTA, DESVIO, ENTREGA
- Cada evento registra: lat/long, hora, velocidade, temperatura

#### Dados Capturados:
- Posicionamento GPS
- Velocidade e condições do motor
- Temperatura ambiental e de carga (se refrigerado)
- Nível de combustível

---

### 2.8 `tms010_operacao_alertas`
**Responsabilidade**: Incidências e problemas durante o transporte

#### Tipos de Alerta:
- DESVIO_ROTA
- PARADA_NAOPLANEJADA
- EXCESSO_VELOCIDADE
- TEMPERATURA_FORA_LIMITES
- COMBUSTIVEL_BAIXO
- FALHA_EQUIPAMENTO

#### Severidade:
- CRITICA, ALTA, MEDIA, BAIXA
- Status: ABERTO → INVESTIGANDO → RESOLVIDO

---

### 2.9 `tms010_operacao_custos`
**Responsabilidade**: Detalhamento financeiro da operação

#### Tipos de Custo:
- FRETE_BASE
- COMBUSTIVEL
- PEDAGIO
- TAXAS (ICMS, PIS, COFINS)
- IMPOSTOS
- EXTRAS (serviços adicionais)

#### Cálculo:
```
Valor Total = Frete Base + Combustível + Pedagio + Impostos + Extras - Desconto
Margem Lucro = Frete Contratado - Custos Totais
```

---

### 2.10 `tms010_operacao_entrega`
**Responsabilidade**: Prova de entrega (comprovante de recebimento)

#### Fluxo:
1. Veículo chega ao destino
2. Conferência de itens
3. Assinatura do recebedor
4. Fotos de comprovação
5. Registro de danos/avarias

#### Campos:
- `condicao_entrega`: INTEGRA, DANIFICADA, FALTANTE, PARCIAL
- `quantidade_entregue`, `quantidade_devolucao`, `quantidade_faltante`
- Assinatura digital e fotos

---

### 2.11 `tms010_operacao_auditoria`
**Responsabilidade**: Rastreamento de quem alterou o quê

#### Campos:
- Usuário que fez a alteração
- Campo alterado
- Valor anterior vs. valor novo
- Motivo da alteração

---

## 3. FLUXO DE NEGÓCIO COMPLETO

```
┌─────────────────────────────────────────────────────────────────────────┐
│                     FLUXO DE OPERAÇÃO DE TRANSPORTE                     │
└─────────────────────────────────────────────────────────────────────────┘

[1] COMERCIAL - CONTRATAÇÃO DE FRETE
    ├─ Cliente solicita frete
    ├─ Sistema cria operação em status RASCUNHO
    ├─ Solicitação de cotações a fornecedores
    ├─ Múltiplas cotações registradas em tms010_operacao_cotacoes
    ├─ Análise de proposta
    └─ Cotação aceita → Status = COTADA

[2] PROGRAMAÇÃO
    ├─ Aloca veículo e motorista
    ├─ Define datas/horários de saída e entrega
    ├─ Registra em tms010_operacao_programacao
    ├─ Confirma disponibilidade
    └─ Status = AGENDADA

[3] PRÉ-COLETA
    ├─ Recebe itens de carga
    ├─ Registra pesos, volumes, quantidades em tms010_operacao_itens
    ├─ Valida documentação (NF-e se aplicável)
    └─ Status = RASCUNHO → COTADA → CONTRATADA

[4] COLETA
    ├─ Motorista coleta a carga
    ├─ Registra data/hora real de coleta
    ├─ Captura posicionamento GPS inicial
    ├─ Evento de rastreamento: SAIDA
    └─ Status = EM_TRANSPORTE

[5] EMISSÃO DE DOCUMENTOS (PARALELO)
    ├─ Gera/Emite CTE (Conhecimento de Transporte)
    ├─ Gera Manifesto de Carga
    ├─ Importa/Valida NF-e (se aplicável)
    ├─ Transmite ao SEFAZ
    ├─ Registra em tms010_operacao_documentos
    └─ Status_documentacao = COMPLETO/TRANSMITIDO

[6] TRANSPORTE (EM TEMPO REAL)
    ├─ Rastreamento contínuo via GPS
    ├─ Eventos registrados em tms010_operacao_rastreamento
    ├─ Monitoramento de temperatura (se refrigerado)
    ├─ Detecção de desvios/alertas
    │   └─ Registra em tms010_operacao_alertas
    ├─ Paradas intermediárias registradas
    └─ Gerenciamento de múltiplas pernas (se houver transbordo)

[7] CHEGADA AO DESTINO
    ├─ Evento de rastreamento: CHEGADA
    ├─ Conferência de itens
    ├─ Registro de danos/avarias
    ├─ Assinatura do recebedor
    ├─ Fotos de comprovação
    ├─ Registra em tms010_operacao_entrega
    └─ Status = ENTREGUE

[8] PÓS-ENTREGA
    ├─ Encerramento de custos
    ├─ Cálculo de margem de lucro
    ├─ Finalização de documentação fiscal
    ├─ Arquivamento de provas de entrega
    └─ Status = ENTREGUE (Final)

[9] AUDITORIA
    └─ Todas as alterações registradas em tms010_operacao_auditoria

```

---

## 4. INTEGRAÇÕES COM OUTROS MÓDULOS

### 4.1 COM COMERCIAL
- Busca clientes, expedidores, destinatários
- Registra cotações de fornecedores
- Controla contratação de fretes

### 4.2 COM FROTA (PROGRAMAÇÃO)
- Aloca veículos (dim_veiculostelemetria)
- Aloca motoristas (dim_motorista)
- Registra disponibilidade de recursos

### 4.3 COM FISCAL (NF-e)
- Importa dados de NF-e
- Vincula NF-e à operação
- Gera CTE eletrônico
- Gera Manifesto

### 4.4 COM RASTREAMENTO
- Recebe dados de GPS em tempo real
- Registra eventos de viagem
- Detecta desvios e alertas
- Monitora condições de carga

### 4.5 COM FINANCEIRO
- Registra custos da operação
- Calcula margens
- Registra faturamento

---

## 5. STATUS E TRANSIÇÕES

### Status Principal (tms010_operacao)
```
RASCUNHO
   ↓
COTADA (cotação aceita)
   ↓
CONTRATADA (frete contratado)
   ↓
AGENDADA (veículo/motorista alocados)
   ↓
EM_TRANSPORTE (em viagem)
   ↓
ENTREGUE (destino alcançado)

Alternativas:
CANCELADA (qualquer momento)
```

### Status de Cotação (tms010_operacao_cotacoes)
```
ABERTA → ACEITA (selecionada)
ABERTA → REJEITADA (não aceita)
ABERTA → EXPIRADA (vencimento)
```

### Status de Documentação (tms010_operacao)
```
NAO_INICIADO
   ↓
PARCIAL (alguns documentos)
   ↓
COMPLETO (todos gerados)
   ↓
ENVIADO (transmitido ao SEFAZ)
```

---

## 6. RELATÓRIOS E DASHBOARDS

### Relatórios Estratégicos
1. **Resumo de Operações** (v_tms010_operacao_resumo)
   - Filtrar por período, cliente, status
   - Exibir peso, volume, valor

2. **Operações Pendentes** (v_tms010_operacoes_pendentes)
   - Operações não entregues
   - Dias de atraso
   - Responsáveis

3. **Análise de Custos** (v_tms010_analise_custos)
   - Margem de lucro por operação
   - Custos vs. Frete contratado
   - Rentabilidade

4. **Documentação Pendente** (v_tms010_documentacao_pendente)
   - CTE não gerado
   - Manifesto não gerado
   - NF-e não importada

### Dashboard de Rastreamento
- Posição em tempo real de cada veículo
- Status de cada operação
- Alertas ativos
- ETA vs. prazo

---

## 7. SEGURANÇA E AUDITORIA

### Auditoria Completa
- Todas as alterações registradas em `tms010_operacao_auditoria`
- Rastreamento de quem, o quê, quando e por quê
- Histórico de mudanças de status

### Permissões Sugeridas
- **Visualizar**: Todos
- **Criar Operação**: Gestor Comercial
- **Programar Recursos**: Programador
- **Encerrar Operação**: Supervisor de Transporte
- **Gerar Documentos**: Departamento Fiscal

---

## 8. INDICADORES-CHAVE (KPIs)

### Operacional
- Taxa de pontualidade (entrega dentro do prazo)
- Tempo médio de entrega
- Taxa de devolução (danos/avarias)
- Ocupação de veículos (peso/volume vs. capacidade)

### Financeiro
- Margem média por operação
- Custo por KM
- Receita por cliente
- Rentabilidade por rota

### Qualidade
- Taxa de alertas por operação
- Desvios de rota
- Paradas não planejadas
- Problemas de temperatura

---

## 9. MIGRATIONS E DEPLOY

### Pré-requisitos:
1. Verificar tabelas de dimensão existem:
   - `dim_cliente`
   - `dim_fornecedor`
   - `dim_veiculostelemetria`
   - `dim_motorista`
   - `sis003_usuario`

### Execução:
```sql
-- 1. Executar DDL completo
\i TMS010_OPERACAO_DDL.sql

-- 2. Validar tabelas criadas
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public' AND table_name LIKE 'tms010%';

-- 3. Verificar índices
SELECT indexname FROM pg_indexes 
WHERE tablename LIKE 'tms010%';
```

---

## 10. PRÓXIMAS FASES

### Fase 2: TELAS E FORMULÁRIOS
- [ ] Cadastro de Operação (cad.php)
- [ ] Listagem (index.php)
- [ ] Programação de Recursos (tms010_programacao.php)
- [ ] Emissão de Documentos (tms010_documentos.php)
- [ ] Rastreamento em Tempo Real (painel_rastreamento.php)
- [ ] Prova de Entrega (tms010_entrega.php)
- [ ] Relatórios (relatorio_operacoes.php)

### Fase 3: INTEGRAÇÕES
- [ ] Integração com API de Rastreamento
- [ ] Integração com SEFAZ (CTE/Manifesto)
- [ ] Integração com NF-e
- [ ] Notificações (SMS, Email, Push)
- [ ] Exportação de dados (Excel, PDF)

### Fase 4: DASHBOARDS
- [ ] Dashboard em tempo real
- [ ] KPIs por período
- [ ] Análise de custos
- [ ] Heatmap de rotas

