Documentacao UX - Wizard de Lancamento CIOT

Objetivo do documento

Este documento descreve o fluxo proposto para o wizard de lancamento de CIOT, incluindo os campos exibidos em cada etapa, a logica de experiencia do usuario e os pontos discutidos em reuniao sobre comprovante, PDF, WhatsApp, e-mail e data de liberacao.

A ideia principal e manter a emissao simples, direta e segura. O usuario deve conseguir emitir o CIOT sem ser interrompido por acoes extras. Depois da emissao, as acoes complementares ficam disponiveis no grid, no menu de acoes do lancamento.

Principio principal de UX

A emissao deve ser simples. Acoes extras devem ficar disponiveis, mas nao atrapalhar o fluxo principal.

Na pratica:

Momento	Experiencia esperada
Antes da emissao	Usuario preenche o wizard com dados obrigatorios e revisa antes de emitir.
Durante a emissao	Sistema mostra estado de carregamento e evita duplo envio.
Logo apos emitir	Sistema confirma sucesso e retorna para o grid/listagem.
Depois da emissao	Usuario pode baixar PDF, enviar por WhatsApp ou enviar por e-mail pelo menu de acoes.

Visao geral do fluxo

O wizard e dividido em 6 etapas:

Ordem	Etapa	Objetivo UX
1	Produto	Informar dados basicos da operacao e documentos fiscais.
2	Pessoas	Identificar contratado, motorista e partes envolvidas.
3	Veiculo	Informar veiculo, carretas, mercadoria e indicadores operacionais.
4	Rota	Informar origem, destino e distancia dos trechos.
5	Pagamento	Configurar forma de pagamento, valores, quebra e parcelas.
6	Revisao	Conferir os principais dados antes de emitir o CIOT.

Visualmente, o wizard deve comunicar progresso. A pessoa precisa entender onde esta, o que ja foi preenchido e quanto falta para emitir.

Acao de entrada no wizard

Na tela de listagem de lancamentos da transportadora, o usuario acessa o wizard pelo botao:

Novo lancamento CIOT

Local sugerido:

Area da tela	Comportamento
Toolbar/filtros da listagem	Botao primario ou destacado ao lado das acoes de pesquisa, limpar, filtros avancados e atualizar.

Motivo UX:

O usuario inicia a emissao a partir do contexto da listagem. Isso reduz troca de tela, mantem orientacao e facilita o retorno ao grid depois da emissao.

Etapa 1 - Produto

Objetivo: registrar a operacao, periodo e documentos fiscais vinculados ao CIOT.

Bloco: Dados da operacao

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ emitente	cpf_cnpj_emitente	Sim	Texto com mascara CPF/CNPJ	Deve deixar claro quem esta emitindo a operacao.
Data inicio	data_inicio	Sim	Data	Preencher automaticamente com a data atual, permitindo alteracao.
Data fim	data_fim	Sim	Data	Preencher automaticamente com a data atual, permitindo alteracao.

Bloco: Documento fiscal

Este bloco e repetivel. O usuario pode adicionar um ou mais documentos vinculados a operacao.

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Tipo documento	documento[index].tipo	Sim	Selecao	Opcoes: CTE, CIOT, MDF-e, Nota Fiscal.
Numero	documento[index].numero	Sim	Texto numerico	Deve aceitar apenas digitos.
Serie	documento[index].serie	Sim	Texto	Campo curto.

Acao do bloco:

Acao	Comportamento
Adicionar documento	Adiciona uma nova linha de documento fiscal.
Remover documento	Disponivel quando houver mais de um documento.

Bloco: Observacao

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Observacao	obs	Nao	Area de texto	Usar para informacoes complementares da operacao.

Etapa 2 - Pessoas

Objetivo: identificar todos os envolvidos na operacao. Esta etapa concentra informacoes cadastrais e documentais.

Bloco: Contratado

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ	contratado.cpf_cnpj	Sim	Texto com mascara CPF/CNPJ	Documento do contratado.
Nome	contratado.nome	Sim	Texto	Nome completo ou razao social.
RNTRC	contratado.rntrc	Sim	Texto numerico	Aceita 8 ou 9 digitos.
Categoria	contratado.categoria	Sim	Selecao	Opcoes: TAC, ETC, CTC.
Celular	contratado.celular	Sim	Texto com mascara telefone	Contato do contratado.
E-mail	contratado.email	Nao	E-mail	Pode ser usado futuramente para envio de comprovante.

Bloco: Motorista

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF	motorista.cpf	Sim	Texto com mascara CPF/CNPJ	Deve ter 11 digitos.
Nome	motorista.nome	Sim	Texto	Nome completo do motorista.
Celular	motorista.celular	Sim	Texto com mascara telefone	Pode apoiar envio por WhatsApp futuramente.

Bloco: Remetente

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ	remetente.cpf_cnpj	Sim	Texto com mascara CPF/CNPJ	Documento do remetente.
Nome	remetente.nome	Sim	Texto	Nome ou razao social.

Bloco: Destinatario

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ	destinatario.cpf_cnpj	Sim	Texto com mascara CPF/CNPJ	Documento do destinatario.
Nome	destinatario.nome	Sim	Texto	Nome ou razao social.

Bloco: Consignatario expedidor

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ	consignatario_expedidor.cpf_cnpj	Sim	Texto com mascara CPF/CNPJ	Documento do consignatario expedidor.
Nome	consignatario_expedidor.nome	Sim	Texto	Nome ou razao social.

Bloco: Consignatario recebedor

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
CPF/CNPJ	consignatario_recebedor.cpf_cnpj	Sim	Texto com mascara CPF/CNPJ	Documento do consignatario recebedor.
Nome	consignatario_recebedor.nome	Sim	Texto	Nome ou razao social.

Etapa 3 - Veiculo

Objetivo: informar a composicao veicular, a mercadoria transportada e os indicadores operacionais.

Bloco: Veiculo principal

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Placa	veiculo.placa	Sim	Texto com mascara placa	Deve aceitar padrao ABC1234 ou ABC1D23.
RNTRC	veiculo.rntrc	Sim	Texto numerico	Aceita 8 ou 9 digitos.
Eixos	veiculo.numero_eixos	Sim	Numero	Valor entre 2 e 4.

Bloco: Carretas

Este bloco e opcional e repetivel. O limite atual e de ate 3 carretas.

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Placa	veiculo.carretas[index].placa	Sim quando adicionar carreta	Texto com mascara placa	Nao pode repetir a placa do veiculo nem de outra carreta.
RNTRC	veiculo.carretas[index].rntrc	Nao	Texto numerico	Aceita 8 ou 9 digitos quando preenchido.
Eixos	veiculo.carretas[index].numero_eixos	Sim quando adicionar carreta	Numero	Valor entre 0 e 4.

Acao do bloco:

Acao	Comportamento
Adicionar carreta	Inclui uma carreta, ate o limite de 3.
Remover carreta	Remove a carreta adicionada.

Bloco: Mercadoria

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
NCM	mercadoria.ncm	Sim	Texto numerico	Deve ter 8 digitos.
Tipo carga	mercadoria.codigo_tipo_carga	Sim	Combobox com busca	Deve permitir busca por tipo de carga.
Peso carga	mercadoria.peso_carga	Sim	Numero com mascara de peso	Deve ser maior que zero.
Valor mercadoria	mercadoria.valor	Sim	Moeda	Valor monetario da mercadoria.

Bloco: Indicadores operacionais

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Alto desempenho	indicadores_operacionais.alto_desempenho	Nao	Checkbox	Marcacao simples.
Retorno vazio	indicadores_operacionais.retorno_vazio	Nao	Checkbox	Marcacao simples.
Composicao veicular	indicadores_operacionais.composicao_veicular	Nao	Checkbox	Marcacao simples.

Etapa 4 - Rota

Objetivo: informar origem, destino e distancia. A etapa aceita um ou mais trechos.

Cada trecho possui 3 areas visuais: Origem, Distancia e Destino.

Bloco: Origem

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Cidade	origem_destino[index].origem.cidade_uuid	Condicional	Combobox	O usuario deve informar cidade, CEP ou latitude/longitude.
CEP	origem_destino[index].origem.cep	Condicional	Texto com mascara CEP	Alternativa para localizar origem.
Latitude	origem_destino[index].origem.latitude	Condicional	Numero decimal	Deve ser usada junto com longitude.
Longitude	origem_destino[index].origem.longitude	Condicional	Numero decimal	Deve ser usada junto com latitude.

Bloco: Distancia

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Distancia km	origem_destino[index].distancia_km	Sim	Numero decimal	Deve ser maior ou igual a 0,01 km.

Bloco: Destino

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Cidade	origem_destino[index].destino.cidade_uuid	Condicional	Combobox	O usuario deve informar cidade, CEP ou latitude/longitude.
CEP	origem_destino[index].destino.cep	Condicional	Texto com mascara CEP	Alternativa para localizar destino.
Latitude	origem_destino[index].destino.latitude	Condicional	Numero decimal	Deve ser usada junto com longitude.
Longitude	origem_destino[index].destino.longitude	Condicional	Numero decimal	Deve ser usada junto com latitude.

Acao do bloco:

Acao	Comportamento
Adicionar trecho	Inclui novo trecho de origem/destino.
Remover trecho	Disponivel quando houver mais de um trecho.

Regra UX importante:

Em origem e destino, o usuario nao precisa preencher todos os localizadores. Basta informar uma forma valida de localizacao: cidade, CEP ou latitude/longitude completa.

Etapa 5 - Pagamento

Objetivo: definir como o frete sera pago, quais valores compoem o pagamento e quando cada parcela sera liberada.

Bloco: Dados principais

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Tipo pagamento ANTT	pagamento.tipo_pagamento_antt	Sim	Selecao	Opcoes: IP, Conta Corrente, Conta Poupanca, Conta Pagamento, Outros, Pix, IP APROMS.
Beneficiado	pagamento.beneficiado	Sim	Selecao	Opcoes: Motorista ou Contratado.
Valor frete	pagamento.valor_frete	Sim	Moeda	Valor total do frete.

Bloco condicional: Dados bancarios

Este bloco aparece conforme o tipo de pagamento ANTT selecionado.

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Quando aparece
Instituicao financeira	pagamento.codigo_instituicao_financeira	Sim em tipos aplicaveis	Combobox com busca remota	IP, Conta Corrente, Conta Poupanca, Conta Pagamento, IP APROMS.
Agencia	pagamento.numero_agencia	Sim em tipos aplicaveis	Texto	Conta Corrente, Conta Poupanca, Conta Pagamento, IP APROMS.
Conta	pagamento.numero_conta	Sim em tipos aplicaveis	Texto	IP, Conta Corrente, Conta Poupanca, Conta Pagamento, IP APROMS.

Bloco condicional: Dados Pix

Este bloco aparece quando o tipo de pagamento ANTT for Pix.

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Chave Pix	pagamento.chave_pix	Sim para Pix	Texto	Maximo de 77 caracteres.
Tipo da chave Pix	pagamento.identificador_pix	Sim para Pix	Selecao	Opcoes: Telefone, E-mail, CPF/CNPJ, Chave aleatoria.

Bloco: Quebra e calculo

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Aplicar quebra	pagamento.aplicar_quebra	Nao	Checkbox	Define se havera aplicacao de quebra.
Recalcular frete	pagamento.recalcular_frete	Nao	Checkbox	Define se o frete sera recalculado.
Tolerancia	pagamento.tolerancia	Nao	Percentual ou peso	O formato muda conforme o tipo de quebra.
Tipo quebra	pagamento.tipo_quebra	Sim	Selecao	Opcoes: Percentual ou Tonelada.

Bloco: Valores complementares

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Frete empresa	pagamento.frete_empresa	Nao	Moeda	Valor complementar.
PPT motorista	pagamento.ppt_motorista	Sim	Moeda	Campo obrigatorio.
Acrescimo	pagamento.valor_acrescimo	Nao	Moeda	Valor complementar.
GRIS	pagamento.gris	Nao	Moeda	Valor complementar.
IRRF	pagamento.irrf	Nao	Moeda	Valor complementar.
INSS	pagamento.inss	Nao	Moeda	Valor complementar.
SEST	pagamento.sest	Nao	Moeda	Valor complementar.
Taxa	pagamento.taxa	Nao	Moeda	Valor complementar.
Outros	pagamento.outros	Nao	Moeda	Entra na validacao da soma.
ICMS	pagamento.icms	Nao	Moeda	Valor complementar.
Pedagio	pagamento.valor_pedagio	Nao	Moeda	Valor complementar.
Estadia	pagamento.valor_estadia	Nao	Moeda	Valor complementar.
CPF/CNPJ creditado	pagamento.cpf_cnpj_creditado	Nao	Texto com mascara CPF/CNPJ	Se nao informado, pode ser derivado do beneficiado.

Bloco: Parcelas

Este bloco e repetivel. A soma das parcelas mais o campo Outros deve fechar com o valor do frete.

Campo visivel	Nome tecnico	Obrigatorio	Tipo de entrada	Observacao UX
Tipo	pagamento.valores[index].tipo	Sim	Selecao	Opcoes: Adiantamento, Adiantamento 1 a 5, Saldo, Complemento, Recebimento, Estadia.
Valor	pagamento.valores[index].valor	Sim	Moeda	Deve ser maior que zero.
Data liberacao	pagamento.valores[index].data_liberacao	Sim	Data	Preencher com data atual por padrao, mas permitir alteracao.

Resumo exibido no final do bloco:

Indicador	Objetivo
Valor do frete	Mostra o valor total informado.
Parcelas + outros	Mostra a soma das parcelas mais outros.
Diferenca	Mostra se o fechamento bate ou se ainda existe divergencia.

Regras atuais importantes:

Regra	Comportamento esperado
Pelo menos uma parcela	O formulario deve ter no minimo uma parcela.
Saldo obrigatorio	Deve existir pelo menos uma parcela do tipo Saldo.
Tipo duplicado	Nao permitir repetir o mesmo tipo de parcela.
Fechamento de valores	Parcelas + Outros deve ser igual ao Valor do frete.

Etapa 6 - Revisao

Objetivo: permitir que o usuario confira os principais dados antes de emitir.

A revisao nao deve repetir todos os campos do formulario. Ela deve funcionar como uma tela de confirmacao executiva, agrupada por blocos editaveis.

Blocos exibidos na revisao

Bloco	Dados mostrados	Acao
Operacao	Emitente, periodo e documentos fiscais.	Editar Produto.
Pessoas	Contratado, motorista, remetente e destinatario.	Editar Pessoas.
Veiculo e mercadoria	Placa, RNTRC, NCM e quantidade de carretas.	Editar Veiculo.
Rota	Quantidade de trechos e distancia total.	Editar Rota.
Pagamento	Valor do frete, total de parcelas, diferenca e quantidade de parcelas.	Editar Pagamento.

Acao final:

Botao	Comportamento
Emitir CIOT	Envia a operacao para emissao.

Recomendacao para data de liberacao

Foi discutido que o sistema deve preencher automaticamente com a data do dia, mas permitir alteracao antes de salvar.

Regra de UX recomendada:

Default inteligente, mas editavel quando o negocio permite.

Como aplicar

Caso	Data sugerida automaticamente	Usuario pode alterar?	Motivo
Adiantamento	Data atual	Sim	Normalmente pode ser liberado no momento da emissao.
Saldo	Data atual ou data futura sugerida, conforme regra do negocio	Sim	Pode depender de entrega, documento ou conferencia.
Complemento	Data atual	Sim	Mantem rapidez, mas permite ajuste.
Recebimento	Data atual	Sim	Mantem rapidez, mas permite ajuste.
Estadia	Data atual	Sim	Mantem rapidez, mas permite ajuste.

Sugestao pratica para o wizard

Elemento	Proposta
Campo Data liberacao	Sempre visivel em cada parcela.
Valor padrao	Data atual.
Edicao	Permitida antes de emitir.
Ajuda visual	Texto curto abaixo do campo ou tooltip: "A data vem preenchida automaticamente, mas pode ser alterada antes da emissao."
Saldo	Permitir escolher data futura sem atrapalhar o preenchimento do adiantamento.

Fluxo apos emissao

Foi discutido que, logo depois de emitir, o sistema deve voltar para o grid e permitir acoes sobre o comprovante.

Fluxo recomendado

Passo	Comportamento
1	Usuario clica em Emitir CIOT na etapa Revisao.
2	Sistema mostra carregamento enquanto envia.
3	Em caso de sucesso, sistema fecha o modal.
4	Sistema retorna para o grid/listagem.
5	Grid atualiza os dados do lancamento emitido.
6	No menu de acoes do lancamento, ficam disponiveis as acoes extras.

Acoes extras no grid

Sugestao: colocar as acoes no menu de tres pontinhos do lancamento CIOT.

Acao	Local sugerido	Objetivo
Baixar PDF	Menu de acoes do grid	Baixar comprovante do CIOT.
Enviar por WhatsApp	Menu de acoes do grid	Compartilhar comprovante com motorista, contratado ou contato selecionado.
Enviar por e-mail	Menu de acoes do grid	Enviar comprovante para e-mail informado ou digitado.
Ver detalhes	Acao rapida ou menu	Consultar dados do CIOT emitido.
Cancelar	Menu de acoes	Cancelar CIOT quando regra permitir.
Encerrar	Menu de acoes	Encerrar CIOT quando regra permitir.

Por que nao mostrar essas acoes dentro do wizard?

Porque elas sao pos-emissao. Se ficarem dentro do wizard, o usuario pode entender que precisa escolher envio ou download antes de concluir. Isso aumenta carga cognitiva e pode deixar o fluxo principal mais lento.

Melhor experiencia:

Decisao UX	Beneficio
Emitir primeiro	Reduz friccao.
Voltar para o grid	Mantem o usuario no contexto da listagem.
Acoes extras no menu	Nao polui o wizard.
PDF/WhatsApp/E-mail como acoes posteriores	Permite executar somente quando necessario.

Sugestao visual para o grid apos emissao

Na listagem, o lancamento CIOT pode ter uma area de acoes com:

Elemento visual	Comportamento
Icone de olho	Ver detalhes do CIOT.
Menu de tres pontinhos	Abrir acoes secundarias.
Badge de status	Mostrar situacao do CIOT, como Emitido, Cancelado ou Encerrado.
Numero do CIOT	Mostrar quando disponivel, para facilitar identificacao.

Menu sugerido:

Ordem	Acao
1	Baixar comprovante PDF
2	Enviar por WhatsApp
3	Enviar por e-mail
4	Ver detalhes
5	Encerrar CIOT
6	Cancelar CIOT

Separacao visual recomendada:

Grupo	Acoes
Comprovante	Baixar PDF, WhatsApp, E-mail.
Consulta	Ver detalhes.
Operacional	Encerrar, Cancelar.

Estados de interface recomendados

Estado	Como deve aparecer
Inicial	Wizard abre na etapa Produto com datas preenchidas com o dia atual.
Preenchimento	Botao Proxima etapa avanca somente quando a etapa atual estiver valida.
Revisao	Cards resumidos com botao Editar por bloco.
Emitindo	Botao em loading, sem permitir clique duplicado.
Sucesso	Confirmar emissao e fechar/voltar para grid.
Erro	Mostrar mensagem clara e manter dados preenchidos para correcao.

Pontos de duvida para alinhar antes de implementar completo

Tema	Pergunta
PDF	O comprovante sera gerado pelo backend ou pelo frontend?
WhatsApp	O envio sera por integracao oficial, link wa.me ou compartilhamento manual?
E-mail	O e-mail deve usar o e-mail do contratado, do motorista, ambos ou permitir digitar outro?
Data do saldo	A data futura do saldo deve ser sugerida por alguma regra, ou apenas editavel manualmente?
Permissoes	Quem pode baixar, enviar, cancelar ou encerrar CIOT?
Auditoria	Envio de PDF, WhatsApp e e-mail precisa ficar registrado no historico?

Resumo executivo

O wizard deve focar em uma tarefa: emitir o CIOT com seguranca.

O usuario percorre as etapas Produto, Pessoas, Veiculo, Rota, Pagamento e Revisao. Ao emitir, o sistema retorna ao grid. A partir do grid, o usuario pode executar acoes complementares como baixar PDF, enviar por WhatsApp ou enviar por e-mail.

A data de liberacao deve seguir a regra de UX discutida: preencher automaticamente com a data atual, mas permitir alteracao antes de salvar. Para adiantamento, isso reduz trabalho manual. Para saldo, isso preserva flexibilidade quando a liberacao depende de entrega, documento ou conferencia.

Frase guia do produto:

Default inteligente, fluxo simples e acoes extras fora do caminho principal.