MFA022 — Movimentação MFA022

Fonte

• Form: source/MFA022/UMFA022.pas + source/MFA022/UMFA022.dfm
• DataModule: source/MFA022/UdmMFA022.pas + source/MFA022/UdmMFA022.dfm
• Package: source/MFA022/MFA022.dpk (requires: rtl, vcl, dbrtl, vclwinx, vclactnband, vclx, vcldb, FireDAC, FireDACCommonDriver, FireDACCommon, FireDACIBDriver, ipstudiowin, jCommon, jPesquisa)
• Shared units utilizadas: jDB, jSessao, jMessage, jReport, jLista, jValidate, jMenu
• Layouts de impressão: MFA022 (cadastro + opcional log) e MFA022_CD (relatorio gerencial com UNION de documentos)

Objetivo

Movimentação de manutencao e consulta de Beneficios concedidos a Clientes (Cartao Fidelidade CF e Cupom de Desconto CD) gerados a partir de documentos de origem (Orcamento, Pedido, Ordem de Serviço e Nota Fiscal). Permite visualizar o historico de alteracoes do beneficio, consultar o documento de origem e imprimir relatorios com quebras por mes, tipo de documento e tipo de beneficio. Opera sobre a tabela BENEFICIOCLIENTE (edicao, cancelamento logico via ST_BENEFICIOCLIENTE = 'C' e emissao do layout MFA022 / MFA022_CD).

Funcionalidades

• Aba "Dados do Beneficio": manutencao do registro na tabela BENEFICIOCLIENTE com lookup de Tipo Beneficio (TIPOBENEFICIO), Empresa (EMPRESAUSUARIO), Cliente (PESSOA), Veiculo (VEICULO) e consulta avancada por filtros.
• Aba "Relatório": filtros para geracao do relatorio gerencial de beneficios gerados x utilizados, com uniao de documentos (Orcamento, OS, Pedido, Nota) e opcoes de quebra.
• Historico de alteracoes do beneficio (LOGBENEFICIOCLIENTE) com opcao de impressão no layout do cadastro.
• Navegacao contextual (F9 em Código) para pesquisar beneficios ja existentes da empresa da sessao.
• Botao "Consultar Docto Origem" abre a tela de consulta adequada ao tipo do documento vinculado (CPD003 OS, CPD001 Pedido ou CNF001 Nota), propagando os parametros (NR_ORDEMSERVICO / NR_PEDIDO / NR_LANCAMENTO).
• Controle de acesso: com programa.tpAcesso = 2 oculta os botoes Novo / Salvar / Excluir e o separador 1.

Estrutura da Tela

Barra lateral (TToolBar):

Botao	Caption / Hint	Atalho
btnNovo	Novo Registro	<F5>
btnSalvar	Salvar Alteracoes	<F6>
btnExcluir	Excluir Registro	<F7>
btnLimpar	Cancelar Registro	<F4>
btnProcurar	Consultar	<F3>
btnAtualizar	Atualizar Registros	<F2>
btnImprimir	Imprimir	<F8>
btnSair	Sair	<F12>

PageControl (Paginas) com 2 abas:

Aba "Dados do Beneficio"

GroupBox "Gerenciamento de Beneficios Cliente":

Caption	Campo	Controle
Código	ID_BENEFICIO	TDBEdit (readonly fora de insercao; F9 busca BENEFICIOCLIENTE da empresa)
No Cartao	NR_CARTAO	TDBEdit (obrigatorio quando TIPOBENEFICIO.ST_CARTAOIMPRESSO = 'S'; OnExit busca cartao)
Cod Cupom	CD_CUPOMDESCONTO	TDBEdit (visivel quando TP_BENEFICIO = 'CD')
Empresa	CD_EMPRESA + NM_EMPRESA	TDBEdit (F9 busca EMPRESAUSUARIO)
Tipo	CD_TIPOBENEFICIO + NM_BENEFICIO	TDBEdit (F9 busca TIPOBENEFICIO)
Cliente	CD_PESSOA + NM_PESSOA	TDBEdit (F9 busca PESSOA ativa)
Veiculo	NR_PLACAVEICULO + DS_VEICULO	TDBEdit (F9 busca VEICULO; obrigatorio quando TIPOBENEFICIO.ST_CONTROLAVEICULO = 'S')
Doc. Origem	DS_ORIGEMDOCUMENTO	TDBEdit read-only, com botao "Consultar Docto Origem" (btnConsultarDoctoOrigem) que abre CPD003/CPD001/CNF001
Emissao	DT_EMISSAO	TwwDBDateTimePicker
Vencimento	DT_VENCIMENTO	TwwDBDateTimePicker
lblStatus	(labels dinamico: "Aguardando Fechamento da OS No ...", "Cancelado", "Vencido", "Ativo")	TLabel

GroupBox "Historico de Alteracoes": DBGrid com colunas Data, Usuario, Ocorrencia (master-detail por ID_BENEFICIO via LOGBENEFICIOCLIENTE).

GroupBox "Consulta": DBGrid com colunas ID, Cod. Tipo, Dt. Emissao (resultados do tabBENEFICIOCLIENTE apos consulta / F9 / atualizacao).

Aba "Relatório"

GroupBox "Filtros para Consulta":

Caption	Campo	Controle / Observacoes
Empresa	CD_EMPRESA	TDBEdit (F9 EMPRESAUSUARIO)
Tipo Benef.	CD_TIPOBENEFICIO + DS_TIPOBENEFICIO	TDBEdit (F9 TIPOBENEFICIO)
Tipo Beneficio (readonly)	TP_BENEFICIO	wwDBComboBox espelho: "Cartao Fidelidade (Cliente) / Cupom de Desconto"
Cod Cupom	CD_CODCUPOM	TDBEdit
Emissao de / ate	DT_EMISSAODE / DT_EMISSAOATE	TwwDBDateTimePicker (filtra data do documento consumidor)
Promocao de / ate	DT_PROMODE / DT_PROMOATE	TwwDBDateTimePicker (filtra BF.DT_EMISSAO do beneficio)
ID Benef.	ID_BENEFICIO	TDBEdit
Documentos	TP_TIPODOCUMENTO	wwDBComboBox: "Orcamento / Pedido / Ordem de Serviço / Nota Fiscal / Todos" (default Todos)

GroupBox "Opcoes de Quebras":

Caption	Campo	Efeito no SQL
Tipo Documento	ST_QUEBRADOC	Gera DS_QUEBRA2 com rotulo "Tipo Doc.: ..." (senao NULL)
Tipo Beneficio	ST_QUEBRATIPO	Gera DS_QUEBRA3 com rotulo "Promocao: CD - NM" (senao NULL)
Mes	ST_QUEBRAMES	Gera DS_QUEBRA1 com "Mes: MM/YYYY" (senao NULL)

Painel inferior (Panel1) com o botao Imprimir <F8> (btnImprimeRelatorio, dispara o mesmo btnImprimirClick do toolbar).

Parametros que Influenciam

MFA022 nao consulta tabelas-parametro (PARM*/CONFIG*) no codigo — nao constam em docs/screens/TABELAS_PARAMETROS.md com referencias cruzadas a este módulo.

O comportamento dinamico do formulario e controlado por campos do proprio TIPOBENEFICIO (lido via lookup de CD_TIPOBENEFICIO) e, indiretamente, pela empresa da sessao:

Tabela	Campo	Efeito
TIPOBENEFICIO	ST_CARTAOIMPRESSO	Quando 'S', label "No Cartao" fica em negrito e NR_CARTAO vira obrigatorio no BeforePost (W-0000 "Numero de Cartao deve ser Informado").
TIPOBENEFICIO	ST_CONTROLAVEICULO	Quando 'S', label "Veiculo" fica em negrito e NR_PLACAVEICULO vira obrigatorio no BeforePost (W-0000 "Placa do Veiculo deve ser Informada").
TIPOBENEFICIO	TP_BENEFICIO	'CD' oculta NR_CARTAO e mostra CD_CUPOMDESCONTO; 'CF' mostra NR_CARTAO e oculta CD_CUPOMDESCONTO.
TIPOBENEFICIO	ST_ATIVO	Validate de CD_TIPOBENEFICIO bloqueia tipo inativo ('N'). Mensagem referencia cadastro [TFA084].
sessao.Empresa.cd_Empresa	—	Parametro :CD_EMPRESA do SQL principal; default do filtro de relatorio (CD_EMPRESA) e da busca F9 em EMPRESAUSUARIO.

Regras de Negocio

1. Edicao exclusiva do registro existente — o SQL exposto no /*AND*/ permite consultar, mas o InsertSQL do UpdateSQL grava com ID_BENEFICIO recebido do usuario. A geracao automatica de ID via GeraSequencia(SEQ_BENEFICIOCLIENTE) esta comentada; atualmente so e possivel atualizar beneficios ja criados por outros módulos (produtores — MFA020/MFA021, MNF001/MNF004, MPD034 etc.).
2. Cancelamento logico — btnExcluirClick nao executa DELETE fisico: muda ST_BENEFICIOCLIENTE de 'V' para 'C' e faz CommitRetaining. Se ja esta cancelado ('C'), exibe E-1745. Confirma com C-1746 antes e mostra I-1749 no sucesso.
3. Obrigatorios no BeforePost (tabBENEFICIOCLIENTEBeforePost):
   • ID_BENEFICIO informado (W-0000 "Informe o Código do Beneficio para Consultar!").
   • CD_ORIGEMDOCUMENTO informado (W-0000 "Origem do Documento deve ser informado!").
   • NR_CARTAO quando TIPOBENEFICIO.ST_CARTAOIMPRESSO = 'S'.
   • NR_PLACAVEICULO quando TIPOBENEFICIO.ST_CONTROLAVEICULO = 'S'.
4. Validacao de duplicidade de cartao (tabBENEFICIOCLIENTENR_CARTAOValidate) — consulta BENEFICIOCLIENTE para cartoes nao vencidos (DT_VENCIMENTO >= CURRENT_DATE) com mesmo NR_CARTAO (UPPER/TRIM); lanca W-1752 com o ID duplicado.
5. Validacao de tipo beneficio (tabBENEFICIOCLIENTECD_TIPOBENEFICIOValidate) — consulta TIPOBENEFICIO; bloqueia inexistente ou com ST_ATIVO='N' (W-0000 referencia [TFA084]); carrega NM_BENEFICIO e TP_BENEFICIO.
6. Validacao de empresa (tabBENEFICIOCLIENTECD_EMPRESAValidate) — usa JValidate.TEmpresa + ValidaEmpresa (shared jValidate) e alimenta NM_EMPRESA.
7. Validacao de pessoa (tabBENEFICIOCLIENTECD_PESSOAValidate) — usa ValidaPessoa (shared jValidate) e alimenta NM_PESSOA.
8. Validacao de veiculo (tabBENEFICIOCLIENTENR_PLACAVEICULOValidate) — consulta VEICULO + MARCAVEICULO + MODELOVEICULO para montar DS_VEICULO. Placa inexistente lanca W-0000 referencia [TTR001].
9. Rotulo de status dinamico (tabBENEFICIOCLIENTEAfterScroll):
   • ST_BENEFICIOCLIENTE = 'A' → "Aguardando Fechamento da OS No ..." (clTeal).
   • ST_BENEFICIOCLIENTE = 'C' → "Cancelado" (clRed).
   • Se vencido (CURRENT_DATE > DT_VENCIMENTO) → "Vencido" (clRed).
   • ST_BENEFICIOCLIENTE = 'V' → "Ativo" (clBlack).
   • TP_ORIGEMDOCUMENTO em (9,10) — Orcamento — oculta o botao Consultar Docto Origem.
10. Roteamento "Consultar Docto Origem" (btnConsultarDoctoOrigemClick) — abre por ordem de presenca: NR_ORDEMSERVICO → CPD003; NR_PEDIDO → CPD001; NR_LANCAMENTO → CNF001. Falta de acesso no menu lanca W-0000 (OS) ou W-1747 (Pedido/Nota).
11. Controle de acesso — tpAcesso = 2 oculta Novo/Salvar/Excluir/Separador1 no iniciar.
12. Impressao Dados do Beneficio (btnImprimirClick na aba Cadastro) — chama GeraRelatorio com layout MFA022, incluindo opcionalmente o SQL do LOGBENEFICIOCLIENTE como sub-dataset apos confirmacao C-1750 ("Historico de Alteracoes").
13. Impressao Relatório gerencial (btnImprimirClick na aba Relatório) — layout MFA022_CD:
    • Valida DT_PROMODE <= DT_PROMOATE e DT_EMISSAODE <= DT_EMISSAOATE (W-0000).
    • Monta CTE BENEFICIOGERADO unindo BENEFICIOCLIENTEREGISTRO + BENEFICIOCLIENTE + TIPOBENEFICIO + 2x ORIGEMDOCUMENTO (origem do beneficio e origem do documento consumidor).
    • Aplica filtros dinamicos via concatenacao com Nulo(...) em CD_CODCUPOM, CD_TIPOBENEFICIO, TP_TIPODOCUMENTO (mapeia para faixas de OD.TP_ORIGEMDOCUMENTO: OR=9,10 / PD=2,6 / OS=3,7,8 / NT=1,5), ID_BENEFICIO, DT_PROMO (BF.DT_EMISSAO) e CD_EMPRESA/DT_EMISSAO nos UNIONs por documento.
    • UNION ALL em 5 SELECTs (ORCAMENTOPECAITEM+ORCAMENTOPECA, 2x ORDEMSERVITEM/SERVICOITEM+ORDEMSERVICO, ITEMPEDIDO+PEDIDO, ITEMNOTA+NOTA), filtrando por TP_ORIGEMDOCUMENTO (9, 7, 8, 6, 5).
    • Se ExecutaConsulta(...)[3] = '' lanca W-0000 "Consulta nao retornou registros!" antes de chamar GeraRelatorio.
14. Defaults de filtro (cdsFILTROSRELATAfterInsert): CD_EMPRESA = empresa da sessao, TP_TIPODOCUMENTO = 'TT' (Todos), ST_QUEBRADOC = 'S', ST_QUEBRATIPO = 'S', ST_QUEBRAMES = 'S'.

Datasets e SQL

Dataset	Tabela(s)	Descricao
tabBENEFICIOCLIENTE (TFDQuery + TFDUpdateSQL updBENEFICIOCLIENTE)	BENEFICIOCLIENTE (BC) INNER TIPOBENEFICIO (B) + ORIGEMDOCUMENTO (OC); LEFT EMPRESA (E), PESSOA (P), VEICULO (V), MARCAVEICULO (M), MODELOVEICULO (O)	SQL principal da aba Cadastro. Parametros: :CD_EMPRESA (duplicado no COALESCE para permitir null). Placeholder /*AND*/ usado em ConsultaAvancada e no edtID_BENEFICIOExit para filtrar por ID. UpdateSQL grava ST_BENEFICIOCLIENTE='N' no insert; update regrava todos os campos exceto DT_REGISTRO ('NOW'). Delete fisico esta definido mas nao e acionado pela UI.
tabLOGBENEFICIOCLIENTE (TFDQuery, MasterSource = dsBENEFICIOCLIENTE, MasterFields = ID_BENEFICIO)	LOGBENEFICIOCLIENTE (LG)	Detail do beneficio selecionado. Parametro :ID_BENEFICIO. AfterOpen posiciona no ultimo registro.
cdsFILTROSRELAT (TClientDataSet em memoria)	—	Armazena filtros da aba Relatório (CD_EMPRESA, NM_EMPRESA, CD_TIPOBENEFICIO, DS_TIPOBENEFICIO, TP_BENEFICIO, CD_CODCUPOM, DT_EMISSAODE/ATE, DT_PROMODE/ATE, ID_BENEFICIO, TP_TIPODOCUMENTO, ST_QUEBRADOC/TIPO/MES).
SQL dinamico em btnImprimirClick (aba Relatório)	BENEFICIOCLIENTEREGISTRO, BENEFICIOCLIENTE, TIPOBENEFICIO, 2x ORIGEMDOCUMENTO, ORCAMENTOPECAITEM, ORCAMENTOPECA, ORDEMSERVITEM, ORDEMSERVICO, SERVICOITEM, ITEMPEDIDO, PEDIDO, ITEMNOTA, NOTA, PESSOA, ITEM	CTE BENEFICIOGERADO + UNION ALL dos documentos consumidores; filtrado por WHERE dinamico construido com Nulo(). Resultado alimenta layout MFA022_CD.
Consulta ad-hoc (edtNR_CARTAOExit)	BENEFICIOCLIENTE	SELECT ID_BENEFICIO, NR_CARTAO FROM BENEFICIOCLIENTE WHERE NR_CARTAO = ... para localizar beneficio pelo cartao lido.
Consulta ad-hoc (tabBENEFICIOCLIENTENR_CARTAOValidate)	BENEFICIOCLIENTE	Busca duplicidade de cartao ativo para disparar W-1752.
Consulta ad-hoc (tabBENEFICIOCLIENTECD_TIPOBENEFICIOValidate)	TIPOBENEFICIO (TB)	Carrega NM_BENEFICIO, ST_ATIVO, TP_BENEFICIO.
Consulta ad-hoc (tabBENEFICIOCLIENTENR_PLACAVEICULOValidate)	VEICULO (V) LEFT MARCAVEICULO (M), MODELOVEICULO (O)	Monta DS_VEICULO a partir de placa.
Consulta ad-hoc (edtID_BENEFICIOExit)	BENEFICIOCLIENTE via sqlBENEFICIOCLIENTE	Substitui /*AND*/ por AND BC.ID_BENEFICIO = ... para confirmar existencia do beneficio apos digitar o codigo. Dispara W-1751 se nao encontrar.

Pesquisas F9 (jPesquisa Busca): TIPOBENEFICIO, EMPRESAUSUARIO, PESSOA, VEICULO, BENEFICIOCLIENTE.

Mensagens do catalogo mensagens.pt-BR utilizadas: E-1745, C-1746, W-1747, I-1748, I-1749, C-1750, W-1751, W-1752, alem dos genericos W-0000, I-0047 e similares.

Tabelas de Escrita (INSERT/UPDATE/DELETE)

Tabela	Operacoes
BENEFICIOCLIENTE	DELETE, INSERT, SELECT, UPDATE

Tabelas de Leitura (SELECT)

Tabela	Operacoes
BENEFICIOCLIENTEREGISTRO	SELECT
EMPRESA	SELECT
ITEM	SELECT
ITEMNOTA	SELECT
ITEMPEDIDO	SELECT
LOGBENEFICIOCLIENTE	SELECT
MARCAVEICULO	SELECT
MODELOVEICULO	SELECT
NOTA	SELECT
ORCAMENTOPECA	SELECT
ORCAMENTOPECAITEM	SELECT
ORDEMSERVICO	SELECT
ORDEMSERVITEM	SELECT
ORIGEMDOCUMENTO	SELECT
PEDIDO	SELECT
PESSOA	SELECT
SERVICOITEM	SELECT
TIPOBENEFICIO	SELECT
VEICULO	SELECT

Procedures Chamadas

Nao ha chamadas a stored procedures no codigo de MFA022 (apenas consultas selectable/DML diretos via ExecutaConsulta/FDQuery).

Tabelas via Procedures (acesso indireto)

Nao se aplica (sem procedures chamadas).

Dependencias Aferentes (quem alimenta esta tela)

Telas que escrevem em tabelas lidas por esta tela (BENEFICIOCLIENTE, BENEFICIOCLIENTEREGISTRO, LOGBENEFICIOCLIENTE e documentos de origem).

Tela	Título	Tabelas em Comum
MFA020	Geracao de Beneficios Cliente	BENEFICIOCLIENTE, BENEFICIOCLIENTEREGISTRO, LOGBENEFICIOCLIENTE
MFA021	Manutencao de Beneficios	BENEFICIOCLIENTE, LOGBENEFICIOCLIENTE
MNF001	Nota Fiscal Entrada/Saida	NOTA, ITEMNOTA, ORIGEMDOCUMENTO, BENEFICIOCLIENTEREGISTRO
MNF004	Emissao de Nota Fiscal	NOTA, ITEMNOTA, ORIGEMDOCUMENTO
MPD002	Manutencao de Pedidos	PEDIDO, ITEMPEDIDO, ORIGEMDOCUMENTO
MPD034	Pedido de Venda	PEDIDO, ITEMPEDIDO, ORIGEMDOCUMENTO, BENEFICIOCLIENTEREGISTRO
MPD005	Ordem de Serviço	ORDEMSERVICO, ORDEMSERVITEM, SERVICOITEM, ORIGEMDOCUMENTO
MPD019	Orcamento de Pecas	ORCAMENTOPECA, ORCAMENTOPECAITEM, ORIGEMDOCUMENTO
TFA084	Cadastro de Tipo de Beneficio	TIPOBENEFICIO
TFA001	Cadastro de Pessoa	PESSOA
TFA006	Cadastro de Empresa	EMPRESA
TPO001	Cadastro de Produto	ITEM
TTR001	Cadastro de Veiculo	VEICULO, MARCAVEICULO, MODELOVEICULO

Lista consolidada a partir de tools/output/table_screen_map.json. Telas alimentadoras adicionais (ex.: módulos fiscais que gravam NOTA/ITEMNOTA e módulos de logistica que alimentam VEICULO) podem aparecer conforme novas analises.

Dependencias Eferentes (quem consome dados desta tela)

Telas que leem BENEFICIOCLIENTE (unica tabela escrita pela MFA022).

Tela	Título	Tabelas em Comum
MFA020	Geracao de Beneficios Cliente	BENEFICIOCLIENTE
MFA021	Manutencao de Beneficios	BENEFICIOCLIENTE
MNF001	Nota Fiscal Entrada/Saida	BENEFICIOCLIENTE
MNF004	Emissao de Nota Fiscal	BENEFICIOCLIENTE
MPD002	Manutencao de Pedidos	BENEFICIOCLIENTE
MPD005	Ordem de Serviço	BENEFICIOCLIENTE
MPD019	Orcamento de Pecas	BENEFICIOCLIENTE
MPD034	Pedido de Venda	BENEFICIOCLIENTE
CPD001	Consulta de Pedido	BENEFICIOCLIENTE
CPD003	Consulta de Ordem de Serviço	BENEFICIOCLIENTE
CNF001	Consulta de Nota Fiscal	BENEFICIOCLIENTE
RFA*	Relatórios de Faturamento / Beneficios	BENEFICIOCLIENTE

Todas as telas que validam ou aplicam descontos de beneficios em Pedidos/OS/Notas (módulos produtores de desconto por beneficio) sao consumidoras potenciais. Lista canonica cruzada com tools/output/table_screen_map.json.