# Análise do schema do módulo de viagens

As regras de negócio abaixo marcadas como **[Proposta]** foram adotadas no módulo inicial. A origem das demais observações é o DDL de `tursaas.sql`. O anexo contém definições de tabelas e índices, sem instruções de carga de dados.

| Referência | Observação no anexo | Implementação |
| --- | --- | --- |
| RF-01 · Empresa e acesso | `app_travels.company_id` identifica a empresa. `app_company_users` contém papel, vínculo ativo e empresa padrão. O dump referencia `app_users.id` como `INT UNSIGNED`. A conta da aplicação atual usa `users.id` como `BIGINT UNSIGNED` no MySQL. | A autenticação existente é a fonte dos usuários. As migrações usam FKs compatíveis para vínculo e autoria. Existe uma chave única para `(user_id, company_id)`. A empresa ativa é selecionada entre os vínculos ativos da sessão. |
| RF-02 · Viagens | `app_travels` reúne classificação, itinerário, ocupação, valores e exclusão lógica. | Mantive `app_travels` para preservar o vocabulário físico do schema. `Trip` seria um nome idiomático em inglês para a entidade. Uma renomeação agora exigiria coordenar índices, FKs e integrações. Listagem paginada, filtros, detalhes, edição, arquivo e restauração. |
| RF-03 · Catálogo de cidades | `app_cities` é compartilhada. As origens e destinos apontam para `id` e o registro da viagem também tem nome e UF. | Consulta somente leitura por prefixo do nome, com limite de 15 resultados por requisição. O backend valida novos IDs e copia nome e UF a partir do catálogo. A viagem conserva esse snapshot ao manter o mesmo vínculo. A migração do módulo não declara FKs para a tabela externa, o que permite instalar e usar rascunhos enquanto o catálogo é provisionado pela aplicação responsável. |
| RF-04 · Itinerário | `destination_arrival_time` tem horário e o anexo não define a data correspondente. `return_date` acompanha a partida do destino. | Adicionei `destination_arrival_date` para representar chegadas em outro dia. O formulário apresenta `return_date` como data da saída do destino. A validação compara as etapas preenchidas. |
| RF-05 · Cadastros | Cliente, veículo e dois motoristas são vínculos opcionais. Uma FK simples valida o ID e não valida a empresa proprietária do cadastro. | Clientes, motoristas e veículos têm listagem, criação, edição e situação ativo/inativo. A viagem valida a empresa e a disponibilidade de novos vínculos. Cadastros inativados continuam aparecendo nas viagens que já os referenciam. |
| RF-06 · Ocupação e valores | O preço por passagem, pagantes, cortesias e total manual são campos distintos. O comentário de `total_value_calculated` especifica preço × pagantes. | Prévia no formulário e recálculo em centavos inteiros no servidor. Cortesias ocupam assentos. Valor manual tem precedência, inclusive `0,00`. O total calculado respeita o limite de `DECIMAL(12,2)`. |
| RNF-01 · Consulta | O anexo indexa a data de saída isoladamente e possui outro índice para empresa e status. | A listagem filtra primeiro pela empresa e por exclusão lógica. Os índices da migração começam por essas colunas e seguem por data ou status. O filtro textual por cidade usa correspondência parcial no snapshot. O custo desse filtro deve ser medido com `EXPLAIN` e com o volume da operação. |
| RNF-02 · Exclusão | O DDL usa cascata em vários vínculos de empresa e autoria, e `SET NULL` em alguns vínculos operacionais. | Viagens arquivam com `deleted_at`. As relações operacionais essenciais usam restrição de exclusão física nas tabelas próprias do módulo, para conservar o histórico. |

## Regras adotadas nesta versão

- **[Proposta] RN-01** A empresa é a unidade de compartilhamento. `admin` e `operator` podem criar, editar, arquivar e restaurar. Outros vínculos ativos têm acesso de leitura. O usuário que cria a empresa recebe o papel `admin` nela. A aplicação oferece seleção da empresa e cadastro inicial. Convites e gestão de papéis ficam para uma etapa própria.
- **[Proposta] RN-02** Uma viagem pode começar como rascunho. Origem, destino e data da saída são obrigatórios nos estados pendente, em andamento e concluída. A situação é editável e mantém os códigos do anexo. A validação de um fluxo fechado de transições depende da política operacional do cliente.
- **[Proposta] RN-03** Pagantes + cortesias devem caber no total de assentos informado na viagem. A capacidade do cadastro do veículo continua um dado de referência. Ainda é preciso definir se a capacidade de frota e conflitos de agenda devem bloquear o cadastro.
- **[Proposta] RN-04** Se outra edição alterar uma viagem entre a abertura e o envio do formulário, o operador recebe uma mensagem para reabrir o registro. O arquivamento é reversível e listado à parte.

## Implantação

As migrações instalam o subconjunto operacional do schema no projeto Laravel. Campos estendidos de empresa e contatos, documentos pessoais, fotos de veículos, cobrança e contadores de uso persistidos ficam fora do módulo entregue. O plano atual fica em `app_companies.plan_code` e o consumo é consultado nas tabelas operacionais. As categorias são globais como no anexo. O seeder opcional oferece três exemplos que podem ser substituídos pelas categorias reais.

O dump original contém comandos `DROP TABLE IF EXISTS`, inclusive para `app_cities`. Em um banco que já recebeu esse dump ou tem tabelas do módulo em uso, faça a conciliação das colunas, dos usuários e das FKs em homologação antes de executar a migração. Na base Laravel da versão anterior, com apenas a estrutura inicial de autenticação, execute a migração normalmente. O [README](../README.md) cobre a instalação e o provisionamento separado do catálogo.
