HR_INTERVALORET - Tempo mínimo entre retiradas de itens locados no mesmo dia

Tela: MFA001 - Parâmetros de Faturamento Localização: Parâmetros → Faturamento → aba Locações (pagLocacao em UMFA001.dfm:10630-10631) → GroupBox5 ' Parâmetros de Locações ' → campo Tempo Mínimo entre as Retiradas (label Label69 em UMFA001.dfm:10675-10689, Caption = 'Tempo Mínimo entre as Retiradas', posicionado em Left=56, Top=70) Tabela: PARMFATUR.HR_INTERVALORET Tipo: Hora / Intervalo (DOM_TIME no DDL — docs/schema/tables/PARMFATUR.sql:151); TTimeField no client (UdmMFA001.pas:203); editado via TwwDBDateTimePicker edtDT_RETIRADA (UMFA001.dfm:10829-10853) com UnboundDataType = wwDTEdtTime e DisplayFormat = 'HH:mm:ss' Valor padrão: NULL — o AfterInsert de tabPARMFATUR em UdmMFA001.pas:434 não atribui default para este campo. O campo nasce vazio e o DOM_TIME do DDL também não define DEFAULT. Validação (MFA001): não há OnValidate para tabPARMFATURHR_INTERVALORET em UdmMFA001.pas (grep retornou apenas a declaração do field na linha 203; nenhum handler). Qualquer hora válida é aceita, inclusive 00:00:00.

O que o parâmetro faz

HR_INTERVALORET é o intervalo mínimo (em horas/minutos/segundos) exigido entre duas retiradas de itens locados no mesmo dia para um mesmo ponto/data de retirada. É consultado exclusivamente pela tela de Locações MPD043 no momento em que o operador valida a disponibilidade de um item locado.

Quando o locatário tenta agendar uma retirada (LOCACAO.DT_RETIRADA), o sistema busca todas as demais locações já confirmadas (ST_LOCACAO IN ('P','T')) para a mesma data de retirada, calcula a diferença entre o horário da retirada em curso e o horário de cada retirada existente e, se essa diferença for menor ou igual a HR_INTERVALORET, exibe um aviso listando os atendimentos que conflitam.

O objetivo operacional é evitar sobrecarga no balcão de retirada — se a loja leva, por exemplo, 30 minutos para preparar/entregar cada pedido de locação, o parâmetro configurado em 00:30:00 garante que dois clientes não sejam agendados para retirar no mesmo horário (ou muito próximos).

Telas impactadas

Módulo	Código	Papel
Parâmetros de Faturamento	MFA001	Produtora — cadastra/edita o valor no campo edtDT_RETIRADA (na aba Locações). CRUD da PARMFATUR inclui o campo em SELECT/INSERT/UPDATE (UdmMFA001.dfm:211, 2407, 2573, 2802, 3091)
Locações	MPD043	Única consumidora. Lê PARMFATUR.HR_INTERVALORET na procedure local ValidaDisponibilidadeItem (UdmMPD043.pas:3003-3143) e compara com a diferença de horários entre retiradas da mesma data

Campos envolvidos

Campo	Tabela	Papel
HR_INTERVALORET	PARMFATUR	Intervalo mínimo exigido entre retiradas (este parâmetro)
DT_RETIRADA	LOCACAO	Data/hora de retirada agendada — a parte hora é o que é comparado com o intervalo
DT_DEVOLUCAO	LOCACAO	Filtro: só entram no comparativo locações com DT_DEVOLUCAO IS NOT NULL
ST_LOCACAO	LOCACAO	Filtro: IN ('P','T') — pendente / em andamento
ST_LOCADO	LOCACAOITEM	Filtro: = 'S' — item efetivamente locado
ST_TROCADO	LOCACAOITEM	Filtro: = 'N' — item ainda não trocado
NR_LOCACAO	LOCACAO	Identificador do atendimento listado no aviso de conflito

---

Comportamento / Uso

Valor = 00:00:00 (ou NULL)

Aspecto	Comportamento
Consulta em MPD043 (UdmMPD043.pas:3088-3091)	SELECT HR_INTERVALORET FROM PARMFATUR WHERE CD_EMPRESA = ...
Condição para ativar (linha 3092)	if (Resultado[0] <> '') then begin ... end;
Efeito com NULL	Resultado[0] = '' → todo o bloco de verificação de intervalo é pulado. Nenhum aviso é emitido, independentemente de quantas retiradas já existam no mesmo dia/horário.
Efeito com 00:00:00	Resultado[0] = '00:00:00' → entra no bloco. Na comparação CompareTime(Hr_Intervalo, 00:00:00) <= 0, como qualquer diferença positiva é > 0, só duas retiradas agendadas para o mesmíssimo segundo disparam o aviso. Efetivamente desliga a regra para casos práticos.

Resultado esperado: o parâmetro fica inativo. Locações podem ser agendadas sem espaçamento entre horários de retirada.

Valor > 00:00:00

Aspecto	Comportamento
Consulta inicial	Em ValidaDisponibilidadeItem (chamada em MPD043), lê HR_INTERVALORET e converte via StrToTime para Hr_IntervaloRet: TTime
Laço de comparação	Para cada locação em aberto na mesma data (CAST(L.DT_RETIRADA AS DATE) = :data_em_edicao), calcula `Hr_Intervalo =
Condição de conflito	if CompareTime(Hr_Intervalo, Hr_IntervaloRet) <= 0 then → adiciona linha à MsgAviso
Saída	Após o laço, se houver conflitos, emite W-0000 com "Já existem Atendimentos com retirada agendada para DD/MM/AAAA." seguido do detalhamento por atendimento

Observações importantes:

• O aviso é emitido via msgcodigo('W-0000', ...) — é informativo (warning), não impede o post da locação. O operador vê a lista de conflitos e decide se mantém o agendamento.
• O parâmetro não tem OnValidate na MFA001, então o administrador pode gravar qualquer valor, inclusive horários absurdos (ex.: 23:59:59). Cabe à documentação operacional orientar valores realistas.
• A query só enxerga locações da mesma empresa (L.CD_EMPRESA = :empresa_do_item) e do mesmo status operacional ('P' = Pendente, 'T' = em trânsito/atendimento).

Simulação passo a passo

Pré-requisitos do cenário:

• PARMFATUR.HR_INTERVALORET = 00:30:00 (30 minutos) definido em MFA001 → Locações.
• Empresa com duas locações já agendadas para 15/05/2026:
  • Locação 1001 → DT_RETIRADA = 15/05/2026 09:00:00, ST_LOCACAO = 'P'.
  • Locação 1002 → DT_RETIRADA = 15/05/2026 10:00:00, ST_LOCACAO = 'P'.
• Operador está incluindo um item na Locação 1003 com DT_RETIRADA = 15/05/2026 09:20:00.

1. Em MFA001 → aba Locações → informe Tempo Mínimo entre as Retiradas = 00:30:00. Salve (F6). Valor grava em PARMFATUR.HR_INTERVALORET.

2. Em MPD043, ao validar a disponibilidade do item da Locação 1003 (disparado em ValidaDisponibilidadeItem), o sistema:

   1. Confirma que a locação está em andamento (ST_LOCACAO = 'A' na rotina) e já passou pelas checagens de saldo/disponibilidade anteriores.

   2. Lê HR_INTERVALORET = 00:30:00.

   3. Faz o SELECT das locações do mesmo dia → retorna 1001 (09:00) e 1002 (10:00).

   4. 1001 vs 1003: |09:00 − 09:20| = 00:20:00. CompareTime(00:20, 00:30) = -1 ≤ 0 → conflito. Adiciona à lista: "Atendimento 1001 - Hora de Retirada 09:00:00 - Intervalo de 00:20:00.".

   5. 1002 vs 1003: |10:00 − 09:20| = 00:40:00. CompareTime(00:40, 00:30) = 1 > 0 → OK, não é conflito.

   6. Ao final, como MsgAviso tem linhas, emite:

      ⚠ W-0000: " Já existem Atendimentos com retirada agendada para 15/05/2026.
Atendimento 1001 - Hora de Retirada 09:00:00 - Intervalo de 00:20:00."

3. O operador confirma/ajusta o horário conforme a política da loja.

Resultado esperado: o sistema avisa sobre qualquer retirada da mesma data cujo horário esteja a menos de (ou igual a) HR_INTERVALORET do horário em edição, mas permite que o operador prossiga se julgar adequado (o raise é warning, não erro bloqueante).

Casos de borda

Cenário	Comportamento
Retiradas em datas diferentes	Filtro CAST(L.DT_RETIRADA AS DATE) = :data_atual exclui — só compara locações do mesmo dia civil.
Locação com ST_LOCACAO = 'F' (finalizada) ou 'C' (cancelada)	Ignoradas (filtro IN ('P','T')).
Locação sem DT_DEVOLUCAO preenchida	Ignorada (L.DT_DEVOLUCAO IS NOT NULL).
Locação com LI.ST_TROCADO = 'S' ou LI.ST_LOCADO = 'N'	Ignorada (filtros em LOCACAOITEM).
Vários itens no mesmo atendimento	A procedure é chamada por item; para cada item validado, repete a consulta.

---

Referências no Código Fonte

Delphi — MFA001 (cadastro do parâmetro)

Arquivo	Linhas	Papel
source/MFA001/UMFA001.dfm	10630-10631	TTabSheet pagLocacao com Caption = 'Locações', ImageIndex = 3
source/MFA001/UMFA001.dfm	10633-10645	TGroupBox GroupBox5 ' Parâmetros de Locações ' (container visual)
source/MFA001/UMFA001.dfm	10675-10689	TLabel Label69 com Caption = 'Tempo Mínimo entre as Retiradas', Left=56, Top=70
source/MFA001/UMFA001.dfm	10829-10853	TwwDBDateTimePicker edtDT_RETIRADA — DataField = 'HR_INTERVALORET', DataSource = dmMFA001.dsPARMFATUR, UnboundDataType = wwDTEdtTime, DisplayFormat = 'HH:mm:ss'
source/MFA001/UdmMFA001.pas	203	Declaração tabPARMFATURHR_INTERVALORET: TTimeField
source/MFA001/UdmMFA001.pas	434-...	tabPARMFATURAfterInsert não atribui default (o campo nasce NULL)
source/MFA001/UdmMFA001.dfm	211	SelectSQL: lista PARMFATUR.NR_DIASRETIRADA, PARMFATUR.HR_INTERVALORET, ...
source/MFA001/UdmMFA001.dfm	1511-1513	Definição do TTimeField com FieldName = 'HR_INTERVALORET', Origin = '"PARMFATUR"."HR_INTERVALORET"'
source/MFA001/UdmMFA001.dfm	2407, 2573	InsertSQL: inclui HR_INTERVALORET na cláusula de INSERT e em VALUES (..., :HR_INTERVALORET, ...)
source/MFA001/UdmMFA001.dfm	2802	UpdateSQL: HR_INTERVALORET = :HR_INTERVALORET,
source/MFA001/UdmMFA001.dfm	3091	RefreshSQL: PARMFATUR.NR_DIASRETIRADA, PARMFATUR.HR_INTERVALORET, ...

Delphi — MPD043 (consumidora)

Arquivo	Linhas	Papel
source/MPD043/UdmMPD043.pas	3003-3143	Procedure livre ValidaDisponibilidadeItem — contém o bloco inteiro de verificação de intervalo de retirada
source/MPD043/UdmMPD043.pas	3010	Declaração Hr_Retirada, Hr_IntervaloRet, Hr_RetiradaAtual, Hr_Intervalo: TTime
source/MPD043/UdmMPD043.pas	3015	Hr_RetiradaAtual := StrToTime(FormatDateTime('HH:mm:ss', dmMPD043.tabLOCACAODT_RETIRADA.AsDateTime))
source/MPD043/UdmMPD043.pas	3087-3094	Leitura do parâmetro: SELECT HR_INTERVALORET FROM PARMFATUR WHERE CD_EMPRESA = ... → Hr_IntervaloRet := StrToTime(Resultado[0])
source/MPD043/UdmMPD043.pas	3097-3111	Consulta das locações pendentes do mesmo dia (LOCACAO + LOCACAOITEM + LOCACAODEVOL, filtros DT_DEVOLUCAO IS NOT NULL, ST_TROCADO = 'N', ST_LOCADO = 'S', ST_LOCACAO IN ('P','T'), mesmo CAST(DT_RETIRADA AS DATE))
source/MPD043/UdmMPD043.pas	3114-3133	Laço de cálculo do Hr_Intervalo e comparação CompareTime(Hr_Intervalo, Hr_IntervaloRet) <= 0 → monta MsgAviso
source/MPD043/UdmMPD043.pas	3134-3138	Se houve conflitos, emite msgcodigo('W-0000', ...) com a lista de atendimentos

DDL

• docs/schema/tables/PARMFATUR.sql:151 — HR_INTERVALORET DOM_TIME, (sem NOT NULL, sem default → permite NULL).

SQL — Procedures

Nenhuma stored procedure em Scripts/ referencia HR_INTERVALORET (grep em Scripts/ retornou zero matches). Toda a regra de intervalo é executada no cliente Delphi, em UdmMPD043.pas.