MTR002 — Movimentação MTR002

Fonte

Source: source/MTR002/
Package: source/MTR002/MTR002.dpk
Form: source/MTR002/UMTR002.pas / UMTR002.dfm
DataModule: source/MTR002/UdmMTR002.pas / UdmMTR002.dfm

Objetivo

Lancar adiantamentos financeiros para motoristas vinculados a uma Viagem em aberto. A tela registra o documento de adiantamento (data, viagem, motorista, valor) via procedure GRAVA_ADIANTVIAGEM e, em seguida, gera o lancamento correspondente no caixa (módulo jCaixa.AbreCaixa), integrando o adiantamento ao fluxo financeiro do transporte.

A tela pode ser aberta como módulo autonomo ou ser disparada por outra tela passando CD_VIAGEM em programa.params — neste modo embutido, ao concluir o adiantamento a janela e fechada automaticamente.

Funcionalidades

Lancamento de novo adiantamento de viagem vinculado a motorista + viagem.
Validacao automatica de situacao da Viagem (impede adiantamento para viagem fechada, ST_VIAGEM = 'F').
Validacao automatica de vinculo Motorista x Viagem via VIAGEMROTA/JUNCAO (so motoristas associados a rota da viagem).
Pesquisa (F9) de motoristas elegiveis pela viagem informada.
Geracao automatica do lancamento de caixa (saida tipo 'R') apos gravar o adiantamento.
Suporte a modo embutido (CD_VIAGEM via programa.params): abre ja amarrado a viagem, grava e fecha.
Controle de acesso tpAcesso = 2 (leitura) oculta Novo/Salvar/Excluir.

Estrutura da Tela

Janela: Dados do Adiantamento (GroupBox principal, MDI child, tamanho fixo 593x316)

Botao	Atalho	Acao
Novo Registro	F5	Rollback + StartTransaction + insere registro em branco na CDS
Salvar Alteracoes	F6	Post + chama `GRAVA_ADIANTVIAGEM` + `AbreCaixa` + Commit
Excluir Registro	F7	(botao presente, sem handler — operacao nao aplicavel)
Cancelar Registro	F4	(botao presente, sem handler)
Consultar	F3	(botao presente, sem handler)
Atualizar Registros	F2	(botao presente, sem handler)
Imprimir	F8	(botao presente, sem handler)
Sair	F12	Fecha o form

Campos do Grupo "Dados do Adiantamento"

Label	Componente	DataField	Tipo	Required	Observacoes
Data	TwwDBDateTimePicker	`DT_LANCAMENTO`	TSQLTimeStamp	Sim	Default = `Date` (AfterInsert); formato `dd/mm/yyyy`.
Nº Viagem	TDBEdit	`NR_VIAGEM`	Integer	Sim	Validado contra `VIAGEM`; bloqueado se `ST_VIAGEM = 'F'`.
Motorista	TDBEdit	`CD_MOTORISTA`	Integer	Sim	F9 = Lista de Motoristas da viagem; valida vinculo via `VIAGEMROTA`/`JUNCAO`.
Nome Motorista	TDBEdit (ReadOnly)	`NM_MOTORISTA`	String(60)	Nao	Preenchido automaticamente no validate do motorista ou via F9.
Valor	TDBEdit	`VL_DOCUMENTO`	Float	Sim	Formato `#,0.00`.

Parametros que Influenciam

Nenhum parametro de sistema (PARM*/PARAM*/CONFIG*) e consultado diretamente pelo codigo desta tela. A tela depende exclusivamente dos dados da Viagem e dos vinculos com Motorista.

O unico "parametro externo" e o argumento CD_VIAGEM recebido via programa.params.Values['CD_VIAGEM'], que, quando presente, pre-carrega o numero da viagem no registro e forca o fechamento automatico da janela apos salvar (modo embutido, usado por telas chamadoras como MTR001/MTR005).

Regras de Negocio

Validacoes

Obrigatoriedade de campos (tabADIANTAMENTOBeforePost) — varre Fields e, para todo campo com Required = True vazio, foca o campo e levanta JException('E-0000', ['O Campo "<DisplayLabel>" deve ser Informado!']).
Validacao da Viagem (tabADIANTAMENTONR_VIAGEMValidate):
- SELECT DT_INICIO, ST_VIAGEM FROM VIAGEM WHERE CD_EMPRESA = :empresa AND CD_VIAGEM = :nrViagem.
- Se nao encontrada: JException('E-0000', ['Viagem nao encontrada! [MTR001]']).
- Se ST_VIAGEM = 'F': JException('E-0000', ['A Viagem ja esta fechada! [MTR001]']).
Validacao do Motorista (tabADIANTAMENTOCD_MOTORISTAValidate):
- Exige Viagem informada previamente (JException('E-0000', ['A Viagem deve ser informada primeiro!'])).
- Consulta JOIN MOTORISTA + PESSOA + VIAGEMROTA + JUNCAO para garantir que o motorista esta associado a rota da viagem.
- Se motorista nao cadastrado: JException('E-0000', ['Motorista nao cadastrado! [TTR005]']).
- Se nao vinculado: JException('E-0000', ['Este Motorista nao esta associado a viagem! [MTR001]']).
- Preenche NM_MOTORISTA automaticamente.
Defaults (tabADIANTAMENTOAfterInsert): DT_LANCAMENTO := Date.

Fluxo de Salvamento (`btnSalvarClick`)

Post da CDS em dsInsert/dsEdit.
Rollback + StartTransaction (garante transacao limpa).
Chama procedure GRAVA_ADIANTVIAGEM(empresa, NR_VIAGEM, CD_MOTORISTA, DT_LANCAMENTO, VL_DOCUMENTO) via ExecutaConsulta, retornando O_NR_LANCAMENTO, O_NR_PROCESSO, O_DS_MENSAGEM.
Se O_DS_MENSAGEM retornar erro: Rollback + JException('E-0000', [mensagem]).
Monta ParmCaixa (8 posicoes) e chama AbreCaixa(transaction, ParmCaixa) do shared jCaixa:
- [0] = empresa; [1] = empresa; [2] = NR_PROCESSO; [3] = 'R' (saida);
- [4] = DT_LANCAMENTO; [5] = VL_DOCUMENTO; [6] = CD_MOTORISTA.
Se AbreCaixa retornar False: Rollback + JException('E-0000', ['Execucao do Adiantamento Cancelada!']).
Commit e MessageBox com O_NR_LANCAMENTO e O_NR_PROCESSO.
btnNovo.Click para proximo lancamento; se em modo embutido (vNR_VIAGEM <> ''), fecha a tela.

Pesquisa F9 (motorista — `edtCD_MOTORISTAKeyDown`)

Abre dialog Pesquisa (jPesquisa) com SQL JOIN em MOTORISTA + PESSOA + VIAGEMROTA + JUNCAO filtrado pela viagem corrente, retornando NM_PESSOA (col 0) e CD_PESSOA (col 1), que sao gravados em NM_MOTORISTA/CD_MOTORISTA.

Acesso

Se programa.tpAcesso = 2 (somente consulta): btnNovo, btnSalvar, btnExcluir, Separador1 ficam invisiveis.

Datasets e SQL

Dataset principal

Dataset	Tipo	Descricao
`tabADIANTAMENTO`	TClientDataSet	CDS em memoria (nao persiste direto); usa campos persistentes `DT_LANCAMENTO`, `NR_VIAGEM`, `CD_MOTORISTA`, `NM_MOTORISTA`, `VL_DOCUMENTO`.
`dsADIANTAMENTO`	TDataSource	Binding visual do CDS.

Persistencia e feita via GRAVA_ADIANTVIAGEM (nao pelo dataset).

SQL embutidas

-- Valida Viagem (tabADIANTAMENTONR_VIAGEMValidate)
SELECT DT_INICIO, ST_VIAGEM
  FROM VIAGEM
 WHERE VIAGEM.CD_EMPRESA = :empresa
   AND VIAGEM.CD_VIAGEM  = :nrViagem;

-- Valida Motorista + vinculo com Viagem (tabADIANTAMENTOCD_MOTORISTAValidate)
SELECT PESSOA.NM_PESSOA, VIAGEMROTA.NR_VIAGEM
  FROM MOTORISTA
 INNER JOIN PESSOA     ON (PESSOA.CD_PESSOA = MOTORISTA.CD_MOTORISTA)
  LEFT JOIN VIAGEMROTA ON (VIAGEMROTA.CD_EMPRESA = :empresa
                       AND VIAGEMROTA.NR_VIAGEM  = :nrViagem)
  LEFT JOIN JUNCAO     ON (JUNCAO.NR_JUNCAO = VIAGEMROTA.NR_JUNCAO
                       AND JUNCAO.CD_MOTORISTA = MOTORISTA.CD_MOTORISTA)
 WHERE MOTORISTA.CD_MOTORISTA = :cdMotorista;

-- Pesquisa F9 (motoristas da viagem)
SELECT DISTINCT PESSOA.NM_PESSOA, PESSOA.CD_PESSOA
  FROM MOTORISTA
 INNER JOIN PESSOA     ON (PESSOA.CD_PESSOA = MOTORISTA.CD_MOTORISTA)
  LEFT JOIN VIAGEMROTA ON (VIAGEMROTA.CD_EMPRESA = :empresa
                       AND VIAGEMROTA.NR_VIAGEM  = :nrViagem)
  LEFT JOIN JUNCAO     ON (JUNCAO.NR_JUNCAO = VIAGEMROTA.NR_JUNCAO
                       AND JUNCAO.CD_MOTORISTA = MOTORISTA.CD_MOTORISTA);

-- Efetiva o adiantamento (btnSalvarClick)
SELECT O_NR_LANCAMENTO, O_NR_PROCESSO, O_DS_MENSAGEM
  FROM GRAVA_ADIANTVIAGEM(:empresa, :viagem, :motorista, :data, :valor);

Perguntas Frequentes

Módulo MTR002 - Adiantamento de Viagem

Perguntas Gerais

P: Qual e a finalidade do módulo MTR002? R: O módulo MTR002 tem como finalidade o registro de Adiantamentos de Viagem. Nesta tela e possivel lancar adiantamentos financeiros destinados aos motoristas ou responsaveis pelas viagens de transporte. O adiantamento e vinculado a uma viagem especifica e, ao ser registrado com sucesso, gera um lancamento financeiro e um numero de processo no sistema.

P: Como registrar um novo Adiantamento de Viagem? R: Para registrar um novo Adiantamento de Viagem, acesse o módulo MTR002, selecione a viagem para a qual deseja lancar o adiantamento, preencha os campos obrigatorios com as informacoes do adiantamento (como valor e demais dados solicitados) e confirme a operacao. Ao salvar, o sistema ira gerar automaticamente o lancamento financeiro correspondente.

P: O que acontece quando um adiantamento e registrado com sucesso? R: Quando o adiantamento e registrado com sucesso, o sistema exibe a mensagem de confirmacao "Adiantamento lancado com sucesso!", acompanhada do numero do Lancamento e do numero do Processo gerados. Esses numeros servem como referencia para consulta e rastreamento do adiantamento nos módulos financeiros do sistema.

P: Como consultar um Adiantamento de Viagem ja registrado? R: Para consultar um adiantamento ja registrado, utilize os numeros de Lancamento e Processo informados na mensagem de sucesso. Esses numeros podem ser utilizados para localizar o registro nos módulos financeiros do sistema. Tambem e possivel consultar os adiantamentos vinculados a uma viagem especifica acessando os detalhes da viagem no módulo MTR001.

P: E possivel estornar ou cancelar um Adiantamento de Viagem? R: A gestao de estornos e cancelamentos de adiantamentos deve ser realizada por meio dos módulos financeiros do sistema, utilizando o numero do Lancamento e do Processo gerados no momento do registro. Consulte o administrador do sistema ou o responsavel financeiro para orientacoes sobre o procedimento adequado.

Mensagens Informativas

P: O que significa a mensagem "Adiantamento lancado com sucesso! Lancamento: X, Processo: Y"? R: Esta mensagem informativa confirma que o adiantamento de viagem foi registrado com sucesso no sistema. O valor "X" corresponde ao numero do Lancamento financeiro gerado e o valor "Y" corresponde ao numero do Processo associado. Guarde esses numeros para futuras consultas e rastreamento do adiantamento.

Tabelas de Escrita (INSERT/UPDATE/DELETE)

Nenhuma escrita direta a partir da tela — toda persistencia e delegada a procedure GRAVA_ADIANTVIAGEM e ao módulo jCaixa (AbreCaixa).

Tabelas de Leitura (SELECT)

Tabela	Operacoes	Uso
JUNCAO	SELECT	Vinculo juncao ↔ motorista via JOIN em validacoes e F9.
MOTORISTA	SELECT	Validacao de existencia e filtro dos motoristas elegiveis.
PESSOA	SELECT	Nome do motorista (`NM_PESSOA`).
VIAGEM	SELECT	Verifica existencia e status (`ST_VIAGEM`) da viagem.
VIAGEMROTA	SELECT	Vinculo viagem ↔ juncao usado para filtrar motoristas elegiveis.

Procedures Chamadas

Procedure	Quando	Retorno
`GRAVA_ADIANTVIAGEM(CD_EMPRESA, NR_VIAGEM, CD_MOTORISTA, DT_LANCAMENTO, VL_DOCUMENTO)`	btnSalvarClick	`O_NR_LANCAMENTO`, `O_NR_PROCESSO`, `O_DS_MENSAGEM` (se `<> ''` → erro).

Alem disso, a tela invoca AbreCaixa (funcao da shared unit jCaixa), que por sua vez executa as procedures/updates internos do dominio de caixa/financeiro (ver jCaixa).

Tabelas via Procedures

A procedure GRAVA_ADIANTVIAGEM e o fluxo AbreCaixa encapsulam a escrita real do adiantamento. Tabelas afetadas tipicamente incluem ADIANTVIAGEM/CONTAS/CAIXA/MOVIMENTACAO (ver corpo da procedure em Scripts/ e documentacao de jCaixa). A analise estatica (table_screen_map.json) nao lista tabelas_via_procs para MTR002 porque o corpo esta fora do escopo do módulo BPL.

Dependencias Aferentes

Telas que abrem MTR002 (passando CD_VIAGEM via programa.params) ou que o referenciam via menu/configuracao:

MTR001 — Cadastro/Manutencao de Viagens: chama MTR002 para lancar adiantamento da viagem selecionada.
MTR005 — Consulta / Fechamento de Viagem: chama MTR002 durante fechamento.
RTR008 — Relatório de Transporte que referencia adiantamentos.
RNF005 — Relatório fiscal relacionado ao contexto de viagens.
TTR015 — Tela de Transporte que referencia a operacao de adiantamento.

Dependencias Eferentes

Shared units / módulos consumidos em tempo de execucao:

jCommon — TSessao, TPrograma, JException, ExecutaConsulta, Nulo, traduzir.
jPesquisa — funcao Pesquisa (F9 de motoristas).
jCaixa — funcao AbreCaixa (gera lancamento de caixa para o adiantamento).

Fonte​

Objetivo​

Funcionalidades​

Estrutura da Tela​

Toolbar (lateral esquerda)​

Campos do Grupo "Dados do Adiantamento"​

Parametros que Influenciam​

Regras de Negocio​

Validacoes​

Fluxo de Salvamento (btnSalvarClick)​

Pesquisa F9 (motorista — edtCD_MOTORISTAKeyDown)​

Acesso​

Datasets e SQL​

Dataset principal​

SQL embutidas​

Perguntas Frequentes​

Módulo MTR002 - Adiantamento de Viagem​

Perguntas Gerais​

Mensagens Informativas​

Tabelas de Escrita (INSERT/UPDATE/DELETE)​

Tabelas de Leitura (SELECT)​

Procedures Chamadas​

Tabelas via Procedures​

Dependencias Aferentes​

Dependencias Eferentes​