QT_KMRETORNO — KM para Cálculo de Data de Retorno (Televendas/Pós-Vendas)

Tela de configuração: OFI001 — Parâmetros de Oficina
ABA: Garantia
Tabela: PARMOFICINA.QT_KMRETORNO
Tipo: NUMERIC(15,2) — campo editável (TDBEdit).
Valor padrão: Não informado (nullable).
Componente: edtQT_KMRETORNO (DFM: DataField = 'QT_KMRETORNO')

---

O que faz

Define a quantidade de quilômetros usada como referência para calcular automaticamente a data e hora de retorno de um veículo em operações de Tele-Vendas (MOF003) e Pós-Vendas (MOF005/MOF001).

O cálculo ocorre internamente na rotina MOF001: o sistema divide o valor de QT_KMRETORNO pela NR_MEDIAKM (quilometragem média diária do veículo, informada na Ordem de Serviço) e soma o resultado em dias à data de emissão da OS.

Para funcionar, ambos os valores precisam estar preenchidos:

• PARMOFICINA.QT_KMRETORNO (> vazio)
• ORDEMSERVICO.NR_MEDIAKM (> vazio)

Quando qualquer um está vazio, o cálculo não é executado.

Telas impactadas

Tela	Módulo	Impacto
OFI001	Parâmetros de Oficina	Tela de configuração do parâmetro
MOF001	Ordem de Serviço (execução)	Cálculo automático de DT_RETORNOTELEVENDAS e HR_RETORNOTELEVENDAS ao validar o vendedor
MOF003	Televendas	Herda comportamento de MOF001
MOF005	Pós-vendas	Herda comportamento de MOF001

Campos envolvidos

Campo	Tabela	Tipo	Descrição
QT_KMRETORNO	PARMOFICINA	NUMERIC(15,2)	KM de retorno — parâmetro configurado na OFI001
NR_MEDIAKM	ORDEMSERVICO	—	Quilometragem média diária informada na OS
DT_EMISSAO	ORDEMSERVICO	DATE/TIME	Data de emissão da OS
DT_RETORNOTELEVENDAS	ORDEMSERVICO	DATE/TIME	Data de retorno calculada
HR_RETORNOTELEVENDAS	ORDEMSERVICO	STRING	Hora de retorno (hora atual do sistema)

Formula do cálculo

Dias := Trunc(QT_KMRETORNO / NR_MEDIAKM)
DT_RETORNOTELEVENDAS := DT_EMISSAO + Dias
HR_RETORNOTELEVENDAS := Hora atual do sistema (TIME)

Exemplo numérico:

• QT_KMRETORNO = 300,00 (retorno esperado em 300 km)
• NR_MEDIAKM = 50,00 (o cliente roda média de 50 km/dia)
• DT_EMISSAO = 15/01/2025

Dias = Trunc(300 / 50) = Trunc(6) = 6
DT_RETORNO = 15/01/2025 + 6 = 21/01/2025
HR_RETORNO = 14:30:00 (hora do cálculo)

Opções disponíveis

Como campo numérico editável, QT_KMRETORNO não possui "opções" discretas, mas comportamentos conforme o valor informado:

Valor preenchido (QT_KMRETORNO > 0)

O que faz	Detalhe
Ativa cálculo	Quando NR_MEDIAKM também estiver preenchido na OS, calcula DT_RETORNOTELEVENDAS e HR_RETORNOTELEVENDAS automaticamente
Requer NR_MEDIAKM	Sem a km média, o cálculo é ignorado (if interno não executa)
Executado ao validar vendedor	Happens no CD_VENDTELEVENDASValidate, ou seja, no momento de selecionar o vendedor

Simulação passo a passo

1. Acesse OFI001 (Parâmetros de Oficina).
2. Abra a aba Garantia.
3. No campo "KM p/cálculo Data Retorno Tele Vendas/Pós Vendas", digite 300,00.
4. Salve o registro.
5. Abra MOF001 (Ordem de Serviço) e crie uma nova OS para um veículo de Televendas/Pós-Vendas.
6. Preencha a Quilometragem Média (NR_MEDIAKM) com 50,00.
7. Preencha a Data de Emissão (DT_EMISSAO) com 15/01/2025.
8. Selecione um Vendedor (CD_VENDTELEVENDAS).

Resultado esperado: O sistema calcula automaticamente:

• Dias = Trunc(300 / 50) = 6 dias
• DT_RETORNOTELEVENDAS = 21/01/2025
• HR_RETORNOTELEVENDAS = hora atual

O campo de data/hora de retorno é preenchido sem intervenção manual.

Valor vazio (QT_KMRETORNO = NULL ou 0)

O que faz	Detalhe
Ignora cálculo	A condição iQT_KMRETORNO <> '' é falsa; o bloco de cálculo não é executado
DT_RETORNOTELEVENDAS	Permanece vazio (a menos que seja informado manualmente por outro mecanismo)
HR_RETORNOTELEVENDAS	Permanece vazio

Simulação passo a passo

1. Acesse OFI001 (Parâmetros de Oficina).
2. Abra a aba Garantia.
3. Deixe o campo "KM p/cálculo Data Retorno Tele Vendas/Pós Vendas" em branco.
4. Salve o registro.
5. Abra MOF001 e crie uma nova OS para Televendas/Pós-Vendas.
6. Preencha NR_MEDIAKM e DT_EMISSAO.
7. Selecione um Vendedor.

Resultado esperado: DT_RETORNOTELEVENDAS e HR_RETORNOTELEVENDAS permanecem vazios — nenhum cálculo automático de retorno é executado.

Importante: A ausência de QT_KMRETORNO preenchedo não causa erro; o sistema simplesmente ignora o cálculo.

Parâmetros relacionados

Parâmetro	Descrição	Relação
ST_OBRIGAKM	Obriga informar quilometragem	Configurado em OFI001 — aba Garantia. Quando ativo, força o preenchimento do campo NR_QUIL na OS. Complementa a lógica de retorno.
NR_QUILOMETRAGEM	Quilometragem registrada	Campo complementar na mesma tabela PARMOFICINA.
NR_DIASGARANTIA	Dias de garantia	Campo na mesma aba da OFI001. Define o período de garantia — relacionado mas independente.

Regra geral

• O cálculo só dispara quando QT_KMRETORNO e NR_MEDIAKM estão ambos preenchidos.
• A hora de retorno é sempre a hora atual do sistema no momento do cálculo (TIME).
• O número de dias é arredondado para baixo (Trunc), ou seja, frações são descartadas (100/50 = 2, 120/50 = 2).

Tabela comparativa resumida

Cenário	QT_KMRETORNO	NR_MEDIAKM	Resultado
Ambos preenchidos	300,00	50,00	Calcula 6 dias de retorno
QT_KMRETORNO vazio	vazio	50,00	Sem cálculo — campo permanece vazio
NR_MEDIAKM vazio	300,00	vazio	Sem cálculo — campo permanece vazio
Ambos vazios	vazio	vazio	Sem cálculo — campo permanece vazio

Procedures impactadas

Rotinas Delphi com referência direta ao campo

Rotina	Arquivo	Linha	Descrição
Busca_Parametros	source/MOF001/UdmMOF001.pas	670, 694	Faz SELECT em PARMOFICINA incluindo QT_KMRETORNO e armazena em iQT_KMRETORNO
tabORDEMSERVICOCD_VENDTELEVENDASValidate	source/MOF001/UdmMOF001.pas	6661-6668	Executa o cálculo Dias = Trunc(iQT_KMRETORNO / NR_MEDIAKM) e preenche DT_RETORNOTELEVENDAS e HR_RETORNOTELEVENDAS

Referências SQL diretas (tabela PARMOFICINA, campo QT_KMRETORNO)

Nenhuma procedure/view em Scripts/ faz referência direta ao campo QT_KMRETORNO.

Candidatas por uso da tabela PARMOFICINA

Procedure/View	Arquivo	Linha
PARCELA_FINANC_MNF017	Scripts/PARCELA_FINANC_MNF017.sql	59
PARCELA_FINANCIAMENTO	Scripts/PARCELA_FINANCIAMENTO.sql	77
REABRE_OS	Scripts/REABRE_OS.sql	90
RETORNA_MOTIVOBLOQUEIO	Scripts/RETORNA_MOTIVOBLOQUEIO.sql	19
RETORNA_PRECOITEM	Scripts/RETORNA_PRECOITEM.sql	68
VERIFICA_BLOQUEIO	Scripts/VERIFICA_BLOQUEIO.sql	160
VIEW_DOCUMENTOSBLOQUEADOS	Scripts/VIEW_DOCUMENTOSBLOQUEADOS.sql	161
VIEW_ROF004	Scripts/VIEW_ROF004.sql	47
VIEW_ROF004_OFXMM	Scripts/VIEW_ROF004_OFXMM.sql	81
VIEW_ROF004B	Scripts/VIEW_ROF004B.sql	130
VIEW_ROF004B_V2	Scripts/VIEW_ROF004B_V2.sql	151
VIEW_ROF008	Scripts/VIEW_ROF008.sql	41

Nota: Estas rotinas utilizam a tabela PARMOFICINA mas não referenciam diretamente o campo QT_KMRETORNO. Não há impacto funcional direto documentado.