# Relatorio de Caixa Delphi - Analise para reproducao no PHP

Origem analisada:

- `C:\Projetos - Git Hub\Ecook_Delphi_Compartilhado\FRM_REL_CAIXA.pas`
- `C:\Projetos - Git Hub\Ecook_Delphi_Compartilhado\FRM_REL_CAIXA.dfm`

## Objetivo do relatorio

O relatorio Delphi gera um fechamento/conferencia de caixa em formato texto, com blocos opcionais habilitados por checkboxes. Ele cruza abertura/fechamento do caixa, vendas, modalidades de pagamento, movimentos manuais de caixa, recebimentos de clientes, cancelamentos, cortesias, descontos e comissao de garcons.

O relatorio trabalha por periodo e por sequencia de caixa. Quando o usuario seleciona `** Todos os caixas **`, a rotina monta uma lista com todas as sequencias abertas no periodo e aplica essa lista nos blocos que aceitam mais de um caixa.

## Filtros e opcoes da tela Delphi

Filtros principais:

- Periodo inicial e final (`dtp_INI`, `dtp_FIM`).
- Sequencia de caixa (`CMB_CAIXAS`), com opcao de todos os caixas.
- Modelo do relatorio (`RDG_MODELO_REL`): novo ou antigo.
- Modalidade de pagamento para recebimento analitico (`cbx_Formapag`).
- App de vendas para recebimento analitico (`CMB_APP_VENDAS`).

Blocos por checkbox:

- Apuracao de Caixa.
- Resumo Total dos Caixas.
- Debitos e Creditos.
- Resumo por Tipo de Venda.
- Detalhamento dos Recebimentos de Cliente.
- Detalhamento dos Recebimentos por Modalidade.
- Listagem de Vendas por Produto.
- Listagem de Produtos Cancelados.
- Listagem de Produtos em Cortesia.
- Recebimentos Analitico.
- Descontos Concedidos.
- Comissao de Garcons.

Modos auxiliares:

- Modo de exibicao de pizzas: agrupado ou detalhado.
- Modo de exibicao de clientes: agrupado ou desagrupado.
- Modo de exibicao de cancelados: agrupado ou desagrupado.
- Modo de exibicao de descontos: sintetico ou analitico.

## Tabelas principais

- `mov_caixa`: abertura, fechamento e movimentos do caixa.
- `fat_geral`: cabecalho das vendas/comandas.
- `fat_item`: itens vendidos, cancelados e cortesias.
- `mov_modalidade_pag`: modalidades de pagamento por venda.
- `cad_modalidade_pag`: cadastro de modalidades, descricao e configuracao de exibicao no caixa.
- `fin_contas_receber`: recebimentos de clientes/fiado e cancelamentos.
- `cad_cliente`: nome dos clientes.
- `cad_funcionario`: operadores, funcionarios e garcons.
- `cad_produto`: descricao dos produtos.
- `cad_grupo_produtos`: grupo dos produtos.
- `fiscal_geral`: dados fiscais usados no recebimento analitico.
- `mov_comissao_func`: comissao de garcons/funcionarios.

## Significado dos principais campos

### `mov_caixa`

- `MVC_SQCAIXA`: sequencia do caixa.
- `MVC_TIPOMOV = 0`: abertura do caixa.
- `MVC_TIPOMOV = 1`: fechamento do caixa.
- `MVC_TIPOMOV = 2`: sangria/saida.
- `MVC_TIPOMOV = 3`: entrada.
- `MVC_TIPOMOV = 4`: recebimento de cliente; valor negativo indica cancelamento de recebimento.
- `MVC_TIPOMOV = 6`: creditos de clientes.
- `MVC_TIPOMOV = 7`: pagamentos.
- `MVC_VALORMV`: valor do movimento.
- `MVC_DATAFIC`: data fiscal/operacional usada nos filtros.
- `MVC_DATAMOV`: data/hora real do movimento.
- `MVC_COD_FUN`: operador/funcionario.
- `MVC_MODALIDADE`: modalidade vinculada a sangria/entrada/fiado.

### `fat_geral`

- `FAT_CODIGOI`: codigo da venda.
- `FAT_SQCAIXA`: sequencia de caixa vinculada.
- `FAT_DATAINI`: data da venda usada nos filtros.
- `FAT_CANCELA`: venda cancelada quando diferente de zero.
- `FAT_RCFORMA = 1`: venda recebida/fechada.
- `FAT_REC_FUN > 0`: venda com funcionario de recebimento.
- `FAT_TIP_LOC`: tipo/local da venda.
- `FAT_TIPOVEN`: tipo de entrega/busca em delivery.
- `FAT_NUM_MES`: numero da mesa/comanda.
- `FAT_TOT_VAL`: valor bruto dos produtos.
- `FAT_TOT_CTX`: base antiga usada em alguns calculos; no Delphi foi substituida por `FAT_TOT_VAL` em pontos importantes.
- `FAT_TAXACVR`: couver.
- `FAT_TAXASVR`: taxa de servico ou entrega.
- `FAT_VALDESC`: desconto.
- `FAT_TOT_REC`: total recebido.
- `FAT_APP_NOME`: app de delivery.
- `FAT_IDORDER_IFOOD`: identificador iFood.
- `FAT_IDORDER`: identificador Neemo/app antigo.

### `fat_item`

- `FAT_CFATGER`: venda vinculada.
- `FAT_CANITEM`: informacao de cancelamento do item.
- `FAT_LOCAL_CANCELAMENTO`: terminal/IP/PC do cancelamento.
- `FAT_MOTCFT`: motivo do cancelamento.
- `FAT_CODITE1` a `FAT_CODITE4`: produtos/sabores.
- `FAT_QTD_ITE`: quantidade.
- `FAT_UNITARI`: valor unitario.
- `FAT_PRE_OPC`: valor de opcionais.
- `FAT_PRE_TOT`: total do item.
- `FAT_PRE_TIP`: tamanho/preco de pizza.
- `FAT_E_CORTESIA`: item em cortesia.
- `FAT_TOT_CORTESIA`: total em cortesia.
- `FAT_DAT_HOR_CORTESIA`: data/hora da cortesia.
- `FAT_MOT_CORTESIA`: motivo da cortesia.

### `cad_modalidade_pag`

- `MPG_CODIGOI`: codigo da modalidade.
- `MPG_DESCRIC`: descricao.
- `MPG_FIN_CTR = 1`: modalidade de venda a prazo/conta.
- `MPG_RELCAX = 1`: modalidade entra no relatorio de caixa principal.
- `MPG_RELCAX = 0`: modalidade fica como conferencia simples, sem totalizar no caixa principal.

## Regras de calculo extraidas

### Apuracao por caixa

Para cada caixa aberto (`MVC_TIPOMOV = 0`), o Delphi localiza o fechamento (`MVC_TIPOMOV = 1`) e monta um bloco com operador, abertura, fechamento e valores por modalidade.

Total liquido por modalidade no modelo novo:

```text
valor_liquido =
  total_recebido_na_modalidade
- troco_devolvido
+ recebimento_fiado
- sangria
+ entrada
+ abertura_do_caixa
```

A abertura do caixa entra principalmente na modalidade dinheiro no modelo novo.

### Total bruto da apuracao

O total bruto da apuracao soma as modalidades configuradas para aparecer no caixa (`MPG_RELCAX = 1`) e ajusta:

- subtrai troco devolvido;
- soma recebimento de fiado;
- subtrai sangrias;
- soma entradas;
- soma abertura do caixa no modelo novo.

Modalidades com `MPG_RELCAX = 0` sao exibidas em uma secao separada de simples conferencia. O comentario do Delphi cita modalidades como `iFood - Pg Online`.

### Resumo Total dos Caixas

O resumo total agrupa recebimentos por modalidade em `mov_modalidade_pag`, desconta troco (`MOV_MPGCODI = 0`) e calcula um total liquido geral:

```text
total_liquido =
  abertura_do_caixa
+ total_bruto
- saidas_do_caixa
- pagamentos
+ entradas_do_caixa
- vendas_a_prazo
+ recebimentos_de_cliente
- cancelamentos_de_recebimentos
+ creditos_de_clientes
```

### Resumo por tipo de venda

O Delphi separa vendas em:

- mesas/local: `FAT_TIP_LOC = 0` ou `FAT_TIP_LOC = 3`;
- balcao: `FAT_TIP_LOC = 1`;
- delivery/disk: `FAT_TIP_LOC = 2`;
- consignacao em regras especificas antigas;
- delivery por app/origem.

Para mesas:

```text
total =
  FAT_TOT_VAL
+ FAT_TAXACVR
+ FAT_TAXASVR
- FAT_VALDESC
```

Para balcao:

```text
total =
  FAT_TOT_VAL
- FAT_VALDESC
```

Para delivery:

```text
total =
  FAT_TOT_VAL
+ FAT_TAXASVR
- FAT_VALDESC
```

O ticket medio e calculado dividindo o total pela quantidade de comandas/vendas.

### Delivery e aplicativos

O Delphi possui varias classificacoes historicas para delivery:

- delivery sem app;
- iFood (`FAT_IDORDER_IFOOD`);
- Neemo/app antigo (`FAT_IDORDER`);
- Wabiz;
- CCM;
- Menu eCook;
- Simsoft.App;
- Anota AI;
- buscar ou entregar via `FAT_TIPOVEN`.

Na versao PHP atual do sistema ja existe uso de `FAT_APP_NOME`, entao o novo relatorio deve preferir este campo quando preenchido.

### Produtos cancelados

Busca itens em `fat_item` com `FAT_CANITEM <> ''`, vinculados ao `fat_geral` do periodo/caixa. Pode listar:

- comanda;
- local da venda;
- operador de inclusao;
- operador de cancelamento;
- data/hora do cancelamento;
- terminal/IP/PC;
- motivo;
- produto;
- quantidade;
- valor unitario/opcionais/total.

### Produtos em cortesia

Busca itens em cortesia, usando principalmente `FAT_E_CORTESIA` e campos historicos:

- `FAT_TOT_CORTESIA`;
- `FAT_DAT_HOR_CORTESIA`;
- `FAT_MOT_CORTESIA`.

### Recebimentos de clientes

Usa `fin_contas_receber`:

- recebidos: `((CTR_DTAREC > 0) OR (CTR_VALDUP <= 0))` e `CTR_CODCLI > 0`;
- caixa de baixa: `CTR_SEQCAI_BAI`;
- cancelados: `CTR_CANCEL = 1`;
- caixa de cancelamento: `CTR_SEQCAI_CAN`;
- modalidade: `CTR_CODMOD_REC`.

Pode exibir agrupado por cliente ou desagrupado por recebimento/modalidade.

### Recebimento analitico

Lista venda por venda a partir de `fat_geral`, com `fiscal_geral` opcional, incluindo:

- comanda;
- mesa/balcao/delivery;
- total de produtos;
- cortesias;
- couver;
- taxa de servico/entrega;
- descontos;
- total recebido;
- cupom fiscal normal/cancelado/sem cupom;
- modalidades de pagamento da venda.

Tambem permite filtro por modalidade e por app.

## Lista de tarefas para criar o Novo Relatorio de Caixa

### Etapa 1 - Fundacao

- Criar rota `relatorio_caixa`.
- Criar item no menu de relatorios.
- Criar pagina `paginas/relatorio_caixa.php`.
- Criar include de regras/queries `includes/relatorio_caixa.php`.
- Usar o mesmo layout responsivo dos demais relatorios.
- Aplicar carregamento longo para bases grandes.

### Etapa 2 - Filtros

- Periodo inicial/final com default em hoje.
- Periodo rapido: hoje, ontem, semana, 15 dias, 30 dias, 60 dias e mes atual.
- Combo de sequencia de caixa.
- Modelo novo/antigo.
- Checkboxes dos blocos do relatorio.
- Bloco opcional **Indicadores complementares** (cards de vendas, valor bruto/recebido, descontos, cancelados e cortesias).
- Persistencia dos filtros em sessao.

### Etapa 3 - Apuracao do caixa

- Listar caixas abertos e fechados.
- Apurar modalidades por caixa.
- Tratar dinheiro e troco.
- Tratar `MPG_RELCAX`.
- Tratar sangrias e entradas por modalidade.
- Tratar recebimentos de fiado.
- Tratar recebimentos cancelados e creditos de clientes.
- Exibir diferenca entre valor calculado e valor digitado no fechamento.

### Etapa 4 - Resumos

- Resumo total dos caixas.
- Resumo por tipo de venda.
- Resumo por delivery/app.
- Ticket medio por canal.
- Total por modalidade.

### Etapa 5 - Detalhamentos

- Recebimentos de clientes.
- Recebimentos cancelados de clientes.
- Recebimento analitico por comanda.
- Produtos vendidos por grupo/produto.
- Produtos cancelados.
- Produtos em cortesia.
- Descontos concedidos.
- Comissao de garcons.

### Etapa 6 - Conferencia e impressao

- Botao imprimir.
- Botao exportar/baixar.
- Modo sintetico e analitico.
- Comparar totais com o Delphi usando a mesma base e periodo.
- Ajustar diferencas conhecidas por cliente/configuracao.

## Primeira versao PHP criada nesta etapa

A primeira versao no projeto deve entregar:

- tela no menu;
- filtros principais;
- bloco opcional de indicadores complementares;
- resumo por tipo de venda;
- recebimentos por modalidade;
- apuracao por caixa em formato conferivel;
- base tecnica pronta para adicionar os demais blocos sem reescrever a tela.

