`: Informa o diagnóstico e clima emocional do pátio.
- `
`: Alerta visual imediato de atritos, trincas ou atrasos de cronograma.
- `
`: Matriz de status do andamento técnico.
```
---
# CATEGORIA: FINANCEIRO
O módulo **Financeiro** do Sistrom ERP é o núcleo de consolidação contábil, fiscal e de tesouraria do ecossistema [Passage 476, 900]. Ele opera sob as restrições síncronas de multi-tenancy (`id_empresas`) e elimina de forma transparente qualquer necessidade de digitação manual de dados [Passage 476, 548, 813].
Toda a movimentação operacional do sistema (fechamento de orçamentos, emissão de ordens de compras, processamento de folha de pagamento de RH e compensações de cheques) alimenta de forma reativa e automática os registros de contas a pagar, contas a receber, tesouraria, fluxo de caixa e o Demonstrativo de Resultados do Exercício (DRE) [Passage 457, 476, 477].
---
```
┌──────────────────────────────────────┐
│ PEDIDOS DE VENDAS / ORÇAMENTOS │
└──────────────────┬───────────────────┘
│ (Aprovação / Faturamento)
▼
┌──────────────────────────────────────┐
│ CONTAS À RECEBER │
└──────────────────┬───────────────────┘
│ (Baixa / Compensação)
▼
┌────────────────┐ ┌──────────────────────────────────────┐ ┌────────────────┐
│ BANCOS │◄───┤ FLUXO DE CAIXA ├───►│ DRE │
└────────────────┘ └──────────────────▲───────────────────┘ └────────────────┘
│ (Baixa / Compensação)
│
┌──────────────────┴───────────────────┐
│ CONTAS À PAGAR │
└──────────────────▲───────────────────┘
│ (Geração automática)
│
┌─────────────────┴───────────────────┐
│ COMPRAS / RH / DESPESAS / PROCESSO │
└─────────────────────────────────────┘
```
---
### MÓDULO 1: CADASTRO DE BANCOS E CONTAS CORRENTES (`bancos-list` & `contas-correntes-list`)
Este módulo gerencia a infraestrutura de tesouraria do Tenant, mapeando as contas correntes físicas e carteiras virtuais de faturamento de retaguarda [Passage 876].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtypes:** `bancos-list` [Passage 876] (para instituições financeiras) e `contas-correntes-list` [Passage 876, 204] (para as contas).
* **ViewModel:** `ERP.bancos.list.viewModel` [Passage 201] e `ERP.contasCorrentes.list.viewModel` [Passage 208].
* **Formulário de Conta Corrente (`contas-correntes-form`):**
* `id_bancos`: Combobox vinculada ao banco selecionado [Passage 200, 202].
* `favorecido` (Razão Social/Nome), `documento` (CNPJ/CPF com validação dinâmica de máscara no ViewModel `cnpjLabel` [Passage 208]), `agencia`, `conta`, `pix` [Passage 193, 194].
* `saldo_inicial` (moneyfield) e `saldo_data` [Passage 204, 206].
* Toggles booleanos: `padrao_pagamento` e `padrao_recebimento` [Passage 197, 206] (definem as contas padrão para automação de baixas do contas a pagar e receber [Passage 206]).
* **API de Comunicação e Back-End (PHP):**
* **Endpoint de Contas:** `mod/marmoraria/cadastros/financeiro/bancos/php/response.php` [Passage 198, 199]
* **Classe PHP:** `Contas` (arquivo: `Contas.php` sob `contas_correntes/php/`) [Passage 632].
* **Métodos principais:**
* `consultar()`: Lista as contas correntes aplicando o filtro multi-tenant `t1.id_empresas = $this->empresa->id` e expurgando de forma síncrona registros marcados logicamente como excluídos (`!ISDATE(t1.excluido_em)`) [Passage 632].
* `salvar_conta()`: Insere ou atualiza os dados da conta corrente associada [Passage 200].
* `trocar()`: Permite a substituição controlada de contas correntes de faturamento em lote no banco de dados [Passage 207].
* **Persistência de Dados e Visões de Banco (MariaDB):**
* **Tabela Principal:** `contas_correntes` [Passage 632].
* **Visão de Caixa Unificada (`view_contas_correntes`):**
Esta view do MariaDB é o coração do caixa em tempo real [Passage 837]. Ela calcula o saldo atualizado de cada conta corrente de forma reativa, somando o `saldo_inicial` físico cadastrado com todas as movimentações síncronas de conciliações em lote compensadas no fluxo de caixa (`view_contas_pagar_receber_saldos`) [Passage 838]:
```sql
CREATE OR REPLACE VIEW view_contas_correntes_{id_empresas} AS
SELECT
t1.id,
t1.id_empresas,
t1.conta_corrente,
IFNULL(t1.saldo_inicial, 0) + IFNULL(SUM(t2.compensado), 0) AS saldo_atual
FROM contas_correntes AS t1
LEFT JOIN view_contas_pagar_receber_saldos_{id_empresas} AS t2 ON t2.id_conta_corrente = t1.id
INNER JOIN bancos AS t3 ON t3.id = t1.id_bancos
INNER JOIN dados_faturamentos_contas AS t4 ON t4.id_contas_correntes = t1.id
WHERE t1.id_empresas = {id_empresas}
GROUP BY t1.id;
``` [Passage 838]
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Contas Correntes** [Passage 876].
2. Para cadastrar uma nova conta, clique em **Novo** [Passage 206].
3. Selecione o **Banco** correspondente [Passage 200] e preencha a **Agência**, **Conta** e a **Chave Pix** [Passage 193, 194].
4. No campo **Saldo Inicial**, digite o valor físico atual da conta (Ex: `50000.00`) [Passage 206].
5. Ative as chaves **Pagamento** e **Recebimento** para definir esta conta como a preferencial da marmoraria para faturamentos automáticos [Passage 197, 206].
6. Clique em **Salvar** [Passage 197]. *O sistema registrará de imediato o saldo de tesouraria [Passage 204], gerando a base para as projeções financeiras em tempo real [Passage 838].*
---
### MÓDULO 2: CONTAS À PAGAR (`contas-pagar-dashboard`)
Gerencia as saídas de caixa e obrigações da empresa com fornecedores, prestadores de serviços e repasses trabalhistas de folha de pagamento [Passage 477, 898].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
```
[Interface: contas-pagar-dashboard]
│
┌────────────────┴────────────────┐
▼ ▼
[Grid: contas-pagar-list] [Wizard: contas-pagar-incluir-form]
│ │
└────────────────┬────────────────┘
▼ (POST / AJAX)
[API: contas_pagar/php/response.php]
│
▼
[Classe: ContasPagar.php]
│
┌──────────────────┴──────────────────┐
▼ (Gravação física) ▼ (Baixa em lote via CSV)
[Tabela: contas_pagar] [Método: relatorio_compras]
```
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `contas-pagar-dashboard` (painel principal de abas em Card Layout) [Passage 76].
* **Sub-componentes integrados:**
* `contas-pagar-list`: Grade principal de lançamentos ativos [Passage 79].
* `contas-pagar-incluir-form`: Formulário Wizard estruturado em Cards síncronos de preenchimento sequencial [Passage 40, 48]:
* *Card 1 (PRINCIPAL):* Fornecedor Credor (`id_empresa_credora`), Tipo de Despesa (`id_tipos_pagamentos`), Centro de Custo da Obra (`id_obras`), Número do Documento/Nota Fiscal [Passage 41].
* *Card 2 (PARCELAS):* Aciona o componente grid editável `contas-pagar-parcela-grid` para fracionar a dívida em parcelas informando valores, vencimentos e formas de pagamento síncronas [Passage 38, 42, 45].
* *Card 3 (DEVEDORA):* Empresa pagadora do grupo Tenant (`id_empresa_devedora`) e a Conta Corrente de saída de recursos [Passage 42, 43].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/contas_pagar/php/response.php` [Passage 531]
* **Classe PHP:** `ContasPagar` [Passage 513].
* **Lógica de Baixa Síncrona:**
* `baixar_individual()`: Executa a liquidação de um título específico informando juros, descontos, data e conta corrente de liquidação [Passage 50]. Ao salvar, verifica a permissão de segurança `baixar_pagamento` [Passage 50].
* `baixar_todos()`: Realiza a baixa automatizada em lote de todos os pagamentos vencidos ou do dia [Passage 515].
* `renegociar_divida()`: Agrupa duplicatas em atraso sob um novo acordo parcelado, alterando os registros originais síncronamente para o status `'RENEGOCIADO'` e gravando as novas parcelas [Passage 137, 840].
* **Mecanismo de Baixa por Arquivo (Importação de Extrato Bancário em CSV):**
O controller `ERP.contaspagar.incluir.form.controller` gerencia o assistente visual de conciliação por arquivo bancário [Passage 43, 51]. O operador realiza o upload de um arquivo de extrato bancário formatado em CSV UTF-8 [Passage 51, 52].
O PHP em retaguarda analisa o arquivo de extrato [Passage 52]:
1. Varre as linhas mapeando síncronamente: **Data, Lançamento, Razão Social, CNPJ, Valor, Forma de Pagamento e Categoria** [Passage 51].
2. Verifica se a Razão Social/CNPJ do credor já está cadastrada em **Dados p/ Faturamento** (`dados_faturamentos`) [Passage 51, 117].
3. Caso a flag `incluir` esteja ativa e o título de pagamento não exista na base de dados, o ERP gera de forma autônoma o contas a pagar de origem [Passage 52] e, em seguida, executa de forma automática e imediata a baixa e compensação do caixa síncronamente [Passage 51, 52].
* **Persistência de Dados e Visões de Banco (MariaDB):**
* **Tabela Principal:** `contas_pagar` [Passage 516].
* **View de Contas a Pagar (`view_contas_pagar`):**
Dinamiza e unifica os títulos, calculando reativamente os acréscimos de atrasos, descontos de antecipações e a string amigável de status (`situacao` baseada em condicionais temporais como `EM ATRASO`, `PAGAR HOJE`, `PAGO NO PRAZO` e `RENEGOCIADO`) [Passage 839, 840].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse **Financeiro > Contas à Pagar** [Passage 898].
2. Para lançar uma fatura de compra de insumos, clique no botão **Incluir** [Passage 40].
3. No **Passo 1**, selecione o fornecedor credor (Ex: `Distribuidora de Abrasivos Aliança`), a categoria de despesa (`Insumos de Fábrica`) e vincule o centro de custo da obra caso seja material exclusivo para um projeto [Passage 41].
4. No **Passo 2**, insira o valor total da nota e defina o número de parcelas (Ex: `3` parcelas com vencimentos a cada 30 dias) [Passage 38, 42].
5. No **Passo 3**, confirme a empresa pagadora, a conta corrente de saída dos recursos e clique em **Salvar** [Passage 42, 43, 44].
6. *Para dar baixa em um título pago:* Selecione a parcela desejada na grade e clique em **Baixar** [Passage 50]. No popup, valide se houve descontos ou multas (Ex: digite `50.00` de desconto por pagamento antecipado), escolha a data do pagamento, a conta corrente e clique em **Confirmar** [Passage 50, 110, 111]. *O sistema efetuará de forma síncrona o débito e lançará a despesa correspondente na conta [Passage 838, 840].*
---
### MÓDULO 3: CONTAS À RECEBER (`contas-receber-dashboard`)
Gerencia as faturas de vendas e as entradas de recursos financeiros dos clientes da marmoraria [Passage 476, 898].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `contas-receber-dashboard` (painel principal) [Passage 143].
* **Sub-views integradas:** `contas-receber-list` [Passage 119], `contas-receber-pendente` [Passage 144] e `contas-receber-compensado` [Passage 144].
* **Formulário de Inclusão (`contas-receber-incluir-form`):**
* Wizard estruturado em abas:
* *Aba 1:* Cliente devedor (`id_empresa_devedora`), Tipo de receita (`id_tipos_pagamentos`), notas de faturamento e toggle de `previsao` de entrada [Passage 101].
* *Aba 2:* Grade de distribuição de parcelas (`contas-receber-parcela-grid`) mapeando vencimentos e faturamentos parciais [Passage 101, 104].
* *Aba 3:* Empresa credora receptora do grupo Tenant e a respectiva conta de recebimento padrão [Passage 101, 102].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/contas_receber/php/response.php` [Passage 545, 546]
* **Classe PHP:** `ContasReceber` [Passage 546].
* **Métodos e Regras de Negócio:**
* `recebimentos()`: Lista os recebimentos ativos com base no filtro do Tenant logado [Passage 139].
* `baixar_individual()`: Executa a baixa síncrona do recebimento na tesouraria [Passage 116]. Exige a validação da permissão `baixar_recebimento` [Passage 116].
* `salvar_historico()`: Permite aos analistas de cobrança registrar o histórico de contatos e renegociações com clientes inadimplentes [Passage 84, 85, 118].
* **Persistência de Dados e Visões de Banco (MariaDB):**
* **Tabela Principal:** `contas_receber` [Passage 550].
* **Visão de Recebíveis (`view_contas_receber`):**
Cruza dinamicamente os recebimentos do caixa do Tenant, as informações de obras (`obras`) e as contas de destino, fornecendo de forma transparente o status temporal do recebimento (`RECEBIDO NO PRAZO`, `RECEBIDO EM ATRASO`, `EM ATRASO`, `RECEBER HOJE` ou `INADIMPLENTE`) [Passage 845, 846, 847].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Contas à Receber** [Passage 898, 899].
2. Para auditar e monitorar títulos em atraso, verifique a grade principal ou acesse a aba **Dívidas** [Passage 143, 144].
3. *Para registrar uma ação de cobrança:* Selecione a fatura do cliente inadimplente na grade e clique em **Cobrança** (ou dê um clique na linha de histórico) [Passage 84].
4. No prompt interativo aberto em tela, digite síncronamente o resumo do contato com o cliente (Ex: *"Cliente Marcos Silva atendeu e confirmou que efetuará o Pix referente à parcela 2 amanhã de manhã"*) [Passage 84].
5. Clique em **Confirmar** [Passage 85]. *O ERP registrará de forma imutável a anotação no prontuário histórico do título (`salvar_historico`), auxiliando auditorias de inadimplência [Passage 85, 118].*
6. *Para realizar a baixa do valor recebido:* Clique em **Baixar** [Passage 116]. No formulário apresentado [Passage 115], confira o valor depositado (inclusive registrando acréscimos de juros de atraso ou descontos comerciais [Passage 124]), selecione a data do depósito e a conta corrente de destino do crédito [Passage 115, 116], clicando em **Confirmar** para concluir a compensação síncrona [Passage 116].
---
### MÓDULO 4: RECONCILIAÇÃO E PRORROGAÇÃO DE DÍVIDAS (RENEGOCIAÇÃO)
Este módulo fornece ao gestor de caixa a inteligência necessária para unificar duplicatas vencidas e estruturar acordos comerciais sob novas datas de faturamento e parcelas no caixa de forma síncrona [Passage 77, 137].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `contas-pagar-renegociar` [Passage 79] e `contas-receber-renegociar-form` [Passage 133].
* **ViewModel e Controller:** `ERP.contasreceber.renegociar.form.controller` [Passage 135].
* **Funcionamento:** O operador abre a tela e seleciona síncronamente as IDs das duplicatas vencidas ou em cobrança (`id_dividas`) [Passage 137]. O ViewModel calcula síncronamente a somatória da dívida e a exibe em tela (`totalDivida`) [Passage 135]. O operador pode então preencher uma nova grade de distribuição de parcelas (`parcelasGrid`) definindo os novos vencimentos e formas síncronas de pagamento [Passage 68, 134].
* **API de Comunicação e Back-End (PHP):**
* Ao submeter a renegociação via POST (`m: "renegociar_divida"`), o PHP de retaguarda executa síncronamente em banco [Passage 137]:
1. Verifica e valida a permissão operacional `incluir_recebimento` ou `incluir_pagamento` [Passage 137].
2. Executa um update em bloco nas duplicatas originais informadas: `UPDATE contas_receber SET renegociada = 1, pago_em = CURDATE(), compensado_em = CURDATE()` [Passage 550, 847]. Isso de forma transparente liquida as dívidas vencidas na base histórica e as marca com a situação de agrupamento `'RENEGOCIADO'` [Passage 847].
3. Cria os novos registros síncronamente em tabela com base na array JSON de parcelas enviadas (`parcelas`) [Passage 137, 550], amarrando o faturamento ao fluxo financeiro sem duplicidade de dados.
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse **Financeiro > Contas à Receber** e selecione a aba **Dívidas** [Passage 143, 144].
2. Marque no checkbox da grade os títulos vencidos do cliente inadimplente que fará o acerto (Ex: selecione 3 duplicatas atrasadas que somam R$ 15.000,00) [Passage 137].
3. Clique no botão superior **Renegociar** [Passage 133].
4. O sistema abrirá a tela exibindo o total do débito de R$ 15.000,00 [Passage 135].
5. Em **Forma de Recebimento**, selecione o novo acordo combinado (Ex: `BOLETO BANCÁRIO`) [Passage 134].
6. Na grade de parcelas abaixo, distribua o novo plano de pagamento síncrono do cliente (Ex: crie 3 parcelas de R$ 5.000,00 com vencimentos para 30, 60 e 90 dias) [Passage 68].
7. Clique em **Confirmar** [Passage 137]. *O MariaDB baixará síncronamente as 3 parcelas antigas marcando-as como 'RENEGOCIADO' [Passage 550, 847], gerará os 3 novos títulos a vencer de recebimento em carteira [Passage 137, 550], mantendo o histórico de inadimplência auditável [Passage 847].*
---
### MÓDULO 5: GESTÃO E CUSTÓDIA DE CHEQUES (`cheque-list`)
Este módulo gerencia a custódia física, repasses para fornecedores, devoluções de mercado e compensações bancárias síncronas de cheques de terceiros e próprios do Tenant [Passage 14, 477, 898].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
```
[Interface Visual: cheque-list]
│
(listswiper: Arraste de balão)
│
┌─────────────────────────┴─────────────────────────┐
▼ (onCompensado) ▼ (onDevolvido)
[API: m: compensar_cheque] [API: m: devolver_cheque]
│ │
▼ (Gatilho MariaDB: AFTER UPDATE) ▼ (Gatilho MariaDB: AFTER UPDATE)
[Baixa síncrona "pago" na conta] [Reabre a dívida na conta]
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `cheque-list` [Passage 898].
* **ViewModel e Stores:**
* Store principal: proxy apontado para `m: "consultar"`, trazendo colunas agrupadas por `empresa_emissora_nome` [Passage 15].
* Campos do modelo de dados: `id`, `numero`, `valor` [Passage 13], `situacao` [Passage 15] (Ex.: `'À COMPENSAR'`, `'COMPENSADO'`, `'DEVOLVIDO'`), `predatado_em`, `compensado_em` [Passage 15], `imagem` e `imagem_url` [Passage 13, 15].
* **Ações Avançadas de Varredura (Plugin ListSwiper):**
A interface Modern do Sistrom ERP implementa o arraste lateral direto do balão do cheque para controle rápido [Passage 14]:
* *Arraste para a Esquerda:* Aciona ações de auditoria visual: **Usuários** (`onUsuarios`), **Restaurar** (`onRestaurar`) e anexar comprovante físico **Imagem** (`onImagem` / `onUpload` de arquivos Jpeg/PNG do cheque para custódia no servidor [Passage 12, 14]).
* *Arraste para a Direita:* Dispara transações de compensação de tesouraria de forma síncrona: **Devolvido** (`onDevolvido` - sinaliza cheque sem fundos [Passage 14]) e **Compensado** (`onCompensado` - confirma o depósito e compensação no banco [Passage 14]).
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/financeiro/cheques/php/response.php` [Passage 489]
* **Classe PHP:** `Cheques` (arquivo: `Cheques.php` sob `financeiro/cheques/php/`) [Passage 487].
* *Mapeamento de Regras de Negócio:*
* `consultar()`: Lista os cheques da carteira do Tenant logado e auto-compila o caminho absoluto para as imagens em `/financeiro/cheques/` [Passage 487, 488].
* `faturamentos()`: Associa o cheque compensado síncronamente aos faturamentos e orçamentos que deram origem à transação de crédito [Passage 488].
##### C. Persistência de Dados e Gatilhos de Banco (MariaDB)
* As compensações de cheques geram reações contábeis em cascata de forma automatizada no banco de dados [Passage 477].
* **A Trigger AFTER UPDATE de `cheques_parcelas` do MariaDB monitora as alterações [Passage 477]:**
* **Gatilho de Compensação:** No instante em que o status do cheque é alterado para **`COMPENSADO`**, o banco de dados executa de forma 100% autônoma o update de baixa da parcela vinculada no contas a pagar ou contas a receber de retaguarda: `UPDATE contas_receber SET pago = valor, pago_em = CURDATE(), compensado_em = CURDATE() WHERE id = [origem_id] AND origem_tabela = 'cheques_parcelas'` [Passage 477].
* **Gatilho de Devolução (Estorno):** Caso o cheque seja marcado como **`DEVOLVIDO`**, a trigger do MariaDB de forma transparente **reabre a dívida no caixa de retaguarda síncronamente**, zerando o valor pago na parcela correspondente e alterando sua situação de volta para `'EM ATRASO'`, recalculando os juros e notificando síncronamente a mesa de cobrança [Passage 477].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Cheques** [Passage 898].
2. Na grade apresentada, localize o cheque do cliente sob custódia física da empresa [Passage 15].
3. *Para anexar a foto física do cheque:* Deslize o dedo sobre a linha do cheque para a **Esquerda** e clique em **Imagem** [Passage 14]. Realize o upload do arquivo do documento e confirme [Passage 12].
4. *Para registrar o depósito e compensação no banco:* Deslize a linha do cheque para a **Direita** e clique em **Compensado** [Passage 14].
5. O sistema solicitará a data da compensação bancária. Informe o dia atual e confirme. *O MariaDB executará síncronamente os gatilhos, baixará a duplicata de origem no contas a receber como pago [Passage 477] e aumentará síncronamente o saldo disponível na conta corrente vinculada [Passage 838].*
6. *Se o banco notificar devolução por falta de fundos:* Deslize a linha para a **Direita** e selecione **Devolvido** [Passage 14]. *A trigger de retaguarda reabrirá síncronamente a pendência no contas a receber do cliente [Passage 477], permitindo que a mesa de cobrança reinicie as ações de recuperação de crédito de imediato [Passage 477, 846].*
---
### MÓDULO 6: TRANSFERÊNCIAS ENTRE CONTAS (`financeiro-transferencias-grid`)
Este módulo processa a transferência eletrônica de valores entre contas do próprio Tenant ou saídas para custódia em contas de sócios, operando sob a lógica rigorosa de dupla entrada síncrona [Passage 188, 871].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `financeiro-transferencias-grid` [Passage 188].
* **Funcionamento:** Abre a janela de edição em linha flutuante do tipo Sheet (`findPlugin("grideditable")`) [Passage 191].
* **Campos de Entrada:**
* `id_empresa_devedora` (Origem) e `id_empresa_devedora_conta` (Conta corrente de saída) [Passage 19, 20].
* `id_empresa_credora` (Destino) e `id_empresa_credora_conta` (Conta corrente de entrada do crédito) [Passage 20, 21].
* `valor` (moneyfield) e `pagar_em` (datafield, maxDate: hoje - impede agendamentos futuros sem provisão real de caixa) [Passage 189].
* *Classificações Fiscais de Entrada e Saída:* `id_tipos_pagamentos` (Classifica a saída, Ex: Despesa de faturamento) [Passage 189] e `id_tipos_recebimentos` (Classifica a entrada, Ex: Receita de faturamento intercompany) [Passage 189].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint:** `mod/marmoraria/financeiro/transferencias/php/response.php` [Passage 591].
* **Classe PHP:** `Transferencias` [Passage 592].
* **Regra de Dupla Entrada Contábil no Caixa (MariaDB):**
No momento em que o operador salva a transferência [Passage 191], o sistema cria síncronamente **dois lançamentos lógicos cruzados em banco** de forma atômica [Passage 871]:
1. Um registro de **Débito (SAÍDA)** na tabela `contas_pagar` vinculado à conta corrente de origem [Passage 871].
2. Um registro de **Crédito (ENTRADA)** na tabela `contas_receber` vinculado à conta de destino, marcando o ID de origem do contas pagar na chave de amarração contábil (`origem_tabela = 'contas_pagar'`) [Passage 871].
*Isso garante que ao auditar o extrato do caixa, a saída e a entrada sejam compensadas e espelhadas síncronamente em ambas as pontas da tesouraria [Passage 871].*
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse **Financeiro > Transferências** [Passage 899].
2. Clique no botão superior **Incluir** [Passage 191].
3. No formulário aberto na lateral direita [Passage 191]:
* Na seção **Origem (Devedora)**, escolha a empresa e a conta de onde o dinheiro está saindo (Ex: `Itaú Unibanco - Conta Corrente Principal`) [Passage 19, 20].
* Na seção **Destino (Credora)**, selecione a conta de destino do crédito (Ex: `Nu Pagamentos S.A. - Fundo de Caixa Fábrica`) [Passage 20, 21].
* Preencha o **Valor** (Ex: `12000.00`) and a **Data** da transação [Passage 189].
* Em **Classificar Saída**, selecione a categoria contábil (Ex: `Transferência de Saldo de Caixa`) [Passage 189].
4. Clique em **Salvar** [Passage 191]. *De forma automática, o ERP executará os lançamentos contábeis de saída no Itaú [Passage 871] e de entrada no Nubank de forma síncrona [Passage 871], equilibrando as carteiras de tesouraria do Tenant [Passage 838].*
---
### MÓDULO 7: CONCILIAÇÃO BANCÁRIA (`conciliacao-bancaria-grid`)
Este módulo compara os registros contábeis internos da marmoraria com a realidade financeira apresentada pelas instituições bancárias, forçando a compensação das duplicatas baixadas [Passage 21, 22, 899].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `conciliacao-bancaria-grid` [Passage 899].
* **Formulário de Lançamento Avulso (`conciliacao-bancaria-form`):**
Utilizado para inserir transações avulsas detectadas no extrato bancário direto (Ex: tarifas, taxas de TED/Pix) [Passage 21]:
* `id_tipos_pagamentos` (combobox relacional): Exige obrigatoriamente a seleção de uma categoria que possua a flag `conciliacao = true` ativa na tabela de tipos de pagamentos [Passage 22]. Se o operador escolher uma classificação inadequada, o front-end intercepta e bloqueia a transação: *"Essa categoria não pode ser selecionada, selecione uma categoria do tipo de conciliação bancária"* [Passage 22].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/conciliacao_bancaria/php/response.php` [Passage 21, 493]
* **Classe PHP:** `ConciliacaoBancaria` [Passage 491].
* **Método `consultar()`:** Retorna o extrato para a conta corrente solicitada (`id_contas_correntes`) [Passage 492].
* **Persistência de Dados e Visões de Banco (MariaDB):**
* **Tabela Principal:** `view_conciliacao_bancaria` [Passage 492].
* **Comportamento do Caixa:** Quando o operador realiza a conciliação bancária de faturamentos, as parcelas baixadas síncronamente recebem a data física de compensação na coluna `compensado_em` [Passage 23]. Isso muda reativamente o saldo líquido da conta corrente na visão consolidada de saldos reais de banco do ERP (`view_contas_correntes`) [Passage 838].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Conciliação Bancária** [Passage 899].
2. No seletor superior, escolha a **Conta Corrente** que deseja analisar.
3. O sistema carregará na grade os títulos baixados internos que ainda não foram confirmados pelo banco [Passage 23].
4. *Para lançar tarifas detectadas no extrato do banco:* Clique em **Adicionar** [Passage 22].
5. No formulário aberto [Passage 21], selecione o Tipo de Despesa (Ex: `Tarifas Bancárias`) [Passage 22], digite o valor, a data da movimentação e clique em **Salvar** [Passage 22]. *O ERP blinda a inserção exigindo que a categoria seja cadastrada como tipo conciliação em banco [Passage 22].*
6. *Para confirmar as duplicatas:* Selecione os lançamentos correspondentes na grade e clique em **Compensar**. *O MariaDB carimbará síncronamente a coluna `compensado_em` de cada título de faturamento [Passage 23, 29], alterando o status da duplicata para compensado de imediato [Passage 23].*
---
### MÓDULO 8: FLUXO DE CAIXA E PREVISÃO DE SALDO (`fluxo-caixa-dashboard` & `contas-pagar-saldo`/`contas-receber-saldo`)
O módulo de Fluxo de Caixa centraliza e consolida todas as previsões e realizações de receitas e despesas do caixa do Tenant para controle estratégico de liquidez [Passage 186, 899].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `fluxo-caixa-dashboard` [Passage 186].
* **Layout:** Card Layout para navegação síncrona de abas [Passage 186]:
* `fluxo-caixa-movimento`: Apresenta uma grade do tipo pivô (`Ext.pivot.Grid`) rica para mineração analítica de dados de entradas e saídas de caixa [Passage 169].
* `fluxo-caixa-extrato`: Grade detalhada exibindo de forma horizontal o **Saldo Anterior** e as colunas calculadas síncronamente: **Previsto**, **Realizado**, **Compensado** e **Perdoado** [Passage 152, 154].
* `card-fluxo-caixa-bancos` e `card-fluxo-caixa-contas`: Exibem gráficos cartesianos de linha moderna com zoom tátil (`panzoom`) com projeções futuras síncronas de saldo para os próximos 6 meses [Passage 148, 150, 151].
* **Mapeamento MVVM (ViewModel / Stores):**
* **ViewModel:** `ERP.fluxocaixa.extrato.viewModel` [Passage 160].
* **Store `extratos`:** Proxy AJAX consumindo a rota `m: "extratos"` [Passage 163]. Realiza filtros de datas SQL nativas na retaguarda no momento da busca (`extratoPeriodo1.value:sqlDate` a `extratoPeriodo2.value:sqlDate`) [Passage 34, 35].
* **Fórmulas Reativas de Caixa (`saldoPrevisto`, `saldoRealizado`, `saldoCompensado`):**
Recuperam em tempo real as somatórias calculadas síncronamente pela store e exibem no cabeçalho em negrito os indicadores de caixa pt-BR [Passage 154, 160, 161]:
* `saldoPrevisto`: Soma de entradas/saídas agendadas [Passage 154, 160].
* `saldoRealizado`: Soma de movimentações de baixas confirmadas [Passage 154, 160].
* `saldoCompensado`: Saldo real líquido disponível nas contas de banco [Passage 154, 160].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/fluxo_caixa/php/response.php` [Passage 590]
* **Classe PHP:** `FluxoCaixa` [Passage 579].
* **Método `saldos()` / `projecao_saldos_banco()`:**
Executa um algoritmo altamente otimizado para calcular as projeções de caixa para os próximos 6 meses [Passage 576, 577]:
1. Consulta de forma atômica no MariaDB a somatória dos saldos atuais de tesouraria de cada banco: `SUM(saldo_atual)` em `view_contas_correntes` [Passage 576].
2. Varre e coleta as somatórias de todas as movimentações financeiras futuras em aberto agendadas em contas a pagar e contas a receber agrupadas por mês e banco [Passage 577, 578].
3. Em PHP, monta um laço iterativo projetando síncronamente mês a mês o saldo acumulado (`$saldos_banco[$rec->id_bancos] += $rec->total_mes`), alimentando os gráficos cartesianos de forma instantânea [Passage 577, 579].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Fluxo de Caixa** [Passage 899].
2. O painel mestre de abas apresentará o resumo gráfico das projeções das carteiras [Passage 148, 186].
3. *Para auditar a conciliação diária:* Clique na aba **Extrato** [Passage 186].
4. No seletor de filtros à esquerda, selecione a conta de banco que deseja auditar e determine o período temporal das movimentações de caixa [Passage 32, 153].
5. O ExtJS carregará de forma imediata as movimentações do pátio [Passage 152]. No cabeçalho superior, confira os balizadores em negrito (Ex: `COMPENSADO: R$ 342.000,00`, `PREVISTO: R$ 358.000,00` - sinalizando os títulos a vencer agendados que entrarão em carteira) [Passage 154, 160].
6. *Para auditar de onde veio um crédito:* Dê um duplo clique na linha de entrada do extrato. O ERP abrirá de forma transparente o modal detalhando o documento fiscal, a obra do cliente ou o pedido que gerou a compensação financeira de retaguarda síncronamente [Passage 169, 172].
---
### MÓDULO 9: DRE - DEMONSTRATIVO DE RESULTADO EXERCÍCIO (`financeiro-dre-grid`)
O **DRE** é o painel de consolidação tributária e contábil do Sistrom ERP [Passage 900]. Ele confronta de forma estruturada as receitas brutas de faturamento e vendas contra as deduções fiscais de impostos e despesas corporativas para apurar o lucro líquido real do Tenant [Passage 891, 900].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `financeiro-dre-grid` [Passage 146, 900].
* **Funcionamento:** Grade minimalista de layout compacto contendo apenas as colunas `descricao` (Estilo negrito aplicado de forma dinâmica via formulas do ViewModel `cellStyle`) [Passage 146, 147] e `valor` (moneyfield pt-BR) [Passage 147].
* **Barra Superior (tbar):** Combobox de anos cadastrados `{anos}` [Passage 147, 148]. Ao alterar o ano, o controller dispara `onSelectAno`, limpa requisições anteriores e recarrega síncronamente a store `{dre}` [Passage 147].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/dre/php/response.php` [Passage 567]
* **Classe PHP:** `Dre` [Passage 566].
* **Método `consultar()` / `imprimir()`:**
Consolida o ano fiscal em memória síncrona [Passage 566]:
1. Varre as movimentações de caixa compensadas na base histórica no período e as agrupa pelas categorias contábeis primárias e secundárias (`tipos_pagamentos` [Passage 524]).
2. Calcula os impostos IRPJ e CSLL devidos aplicando de forma reativa a alíquota tributária corporativa correspondente à faixa de lucro operacional do Tenant cadastrada nos parâmetros (`rh_parametros_irpj` [Passage 891]).
3. Estrutura o DRE organizando de forma hierárquica [Passage 566]:
* `(+) RECEITA BRUTA DE VENDAS` (Faturamentos de orçamentos e pedidos) [Passage 781].
* `(-) DEDUÇÕES E IMPOSTOS` (IPI, impostos sob salários) [Passage 478, 892].
* `(=) RECEITA LÍQUIDA`
* `(-) CUSTOS DE MATERIAIS E INDUSTRIALIZAÇÃO` (Insumos, compras de chapas) [Passage 425].
* `(=) LUCRO BRUTO`
* `(-) DESPESAS OPERACIONAIS / DESPESAS FIXAS` (Folha bruta de RH, vales) [Passage 882, 896].
* `(=) RESULTADO OPERACIONAL LÍQUIDO (Lucro/Prejuízo)` [Passage 566].
4. Disponibiliza síncronamente na tela o download do relatório analítico oficial em PDF [Passage 567].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > DRE - Contabilidade** [Passage 900].
2. Na barra de ferramentas superior, selecione o **Ano de Referência** que deseja auditar (Ex: `2026`) [Passage 147, 148].
3. A grade carregará de imediato a estrutura contábil [Passage 146, 147]. Avalie a linha **Receita Bruta** para certificar o faturamento comercial do período.
4. Navegue pelas linhas de **Custos Operacionais** para auditar as saídas consolidadas de RH e despesas de matéria-prima.
5. Verifique a linha final **Resultado do Exercício** em negrito [Passage 147]. Se estiver positivo (em tom azul), indica lucro operacional líquido; se negativo (vermelho), sinaliza prejuízo de caixa no ano fiscal [Passage 147, 566].
6. *Para gerar a via física para contabilidade:* Clique no botão **Imprimir** para compilar síncronamente o relatório em PDF [Passage 567].
---
### MÓDULO 10: CENTRO DE CUSTO DE OBRA (`centro-custo-obra-grid`)
Permite ao gestor financeiro acompanhar de forma minuciosa a rentabilidade individual de cada obra em andamento, comparando de forma reativa os custos estimados no orçamento contra os gastos reais consolidados [Passage 8, 9].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `centro-custo-obra-grid` [Passage 8].
* **Seletor superior:** `obras-select` (`reference: "obras"` - com o filtro restritivo de centro de custo `{centrocusto: true}` habilitado) [Passage 8]. Ao selecionar a obra, o controller `ERP.centrocusto.obra.grid.controller` carrega síncronamente a store `{extratos}` vinculando o ID do projeto (`id_obras`) [Passage 10, 11].
* **Exibição de Indicadores no Rodapé (bbar):**
Contém campos calculados de forma reativa pelo ViewModel com base nas somatórias da store [Passage 9, 10]:
* `lucroEstimado`: Diferença bruta calculada no orçamento original [Passage 9].
* `lucroReal`: Receitas de faturamento compensadas menos as despesas reais debitadas [Passage 9].
* `custoExcedente`: Valor gasto na execução que ultrapassou a meta original de custos [Passage 9].
* **API de Comunicação e Back-End (PHP):**
* **Endpoint:** `mod/marmoraria/financeiro/centro_custo_obra/php/response.php` [Passage 11]
* **Classe PHP:** `CentroCusto` [Passage 484].
* **Algoritmo de Cálculo de Desvios de Custos:**
O método `consultar()` monta a visão financeira da obra [Passage 484]. Ele recupera as somatórias de receitas faturadas e as metas de despesas e executa varreduras síncronas de custos dinâmicos [Passage 484, 485]:
1. **Consumo de Estoques Internos:** Varre a tabela de históricos de estoques (`estoques_materiais_historicos`) buscando saídas registradas com justificativa contendo o nome da obra: `historico LIKE '%[Nome da Obra]%' AND operacao = 'SAÍDA'` [Passage 485]. Ele extrai o valor de custo das chapas de pedras consumidas no pátio (`quantidade * valor`) e soma síncronamente como despesa real da obra [Passage 485, 486].
2. **Repasses de Mão de Obra de RH:** Busca e soma todos os vales em dinheiro e bônus pagos a instaladores e medidores associados àquele projeto específico na tabela de RH (`rh_funcionarios_vales`) [Passage 857].
3. **Despesas Financeiras Diretas:** Soma todos os títulos do contas a pagar quitados que foram marcados com o ID do centro de custo da obra (`id_obras`) [Passage 857].
4. **Cálculo da Diferença:** Compara o somatório das despesas contra as metas de custos estimados [Passage 486]. Se a despesa superou a previsão, calcula o percentual excedente: `(valor_total_despesa - valor_total_custo_estimado) / valor_total_custo_estimado * 100` [Passage 486] e retorna a string amigável de alerta no JSON (`custoExcedente`) [Passage 486].
---
#### 📘 Guia de Operação (Seguindo a Trilha do Dinheiro)
1. Acesse o menu **Financeiro > Centro de custo de obra** [Passage 900].
2. No dropdown superior autocomplete **Informe a obra**, comece a digitar o nome do canteiro ou cliente e selecione o projeto [Passage 8, 10].
3. A grade carregará de imediato o extrato consolidado de receitas e despesas [Passage 8, 10].
4. No cabeçalho ou rodapé, avalie os balizadores financeiros [Passage 9]:
* **Total Receita:** O valor líquido que o cliente de fato já pagou e compensou [Passage 9].
* **Total Despesa:** O custo acumulado síncrono da obra (somando o contas a pagar quitado, as pedras consumidas e os vales de instaladores) [Passage 9, 485, 486].
5. Verifique o campo **Custo Excedente** [Passage 9]. Se o gasto real superou a previsão, o sistema destacará em vermelho informando o estouro de orçamento (Ex: *"Estouro de 12% em relação à estimativa original"*) [Passage 486].
6. *Para auditar a origem de um desvio:* Varre as linhas da grade e localize os lançamentos de saída de estoque para identificar se houve quebra de chapas CNC no pátio ou redimensionamento inadequado das medidas de corte do mármore [Passage 485, 486].
---
### ⚡ VÍNCULOS TRANSVERSAIS ("SEGUINDO O RASTRO DO DINHEIRO")
A arquitetura do Sistrom ERP funciona como uma engrenagem contábil e transacional integrada síncrona [Passage 476, 477]. Toda movimentação física ou de processos dispara gatilhos de retaguarda que atualizam o caixa do Tenant, permitindo rastrear o dinheiro ponta a ponta:
```
[Orçamento Fechado] ──► (Triggers) ──► [Aprovação do Pedido] ──► (Contas à Receber) ──► [Compensação no Caixa]
│
▼
[Consolidação DRE] ◄── [Fluxo de Caixa] ◄── (Baixa / Extrato) ◄── (Contas à Pagar) ◄── [Rh / Compras / EPI]
```
#### 1. Do Fechamento Comercial à Mesa de Contas à Receber:
* No instante em que o vendedor altera o status de um orçamento de mármore para **`status_orcamento = 'FECHADO'`** [Passage 715], o sistema inicializa os parâmetros de faturamento acordados [Passage 312].
* A aprovação do pedido comercial invoca síncronamente a rotina PHP `aprovar()` [Passage 476]. O ERP blinda a transação e, de forma 100% autônoma, varre a array de parcelas de faturamento cadastrada nas condições de pagamento (`marmoraria_orcamentos_condicoes_pagamentos`) [Passage 312, 761] e **insere síncronamente cada parcela como um título de entrada em `contas_receber`** [Passage 476], alimentando de imediato a projeção futura de saldos do caixa [Passage 838].
#### 2. Das Compras e Departamento Pessoal à Mesa de Contas à Pagar:
* O mesmo motor transacional opera nas saídas [Passage 477]. Ao aprovar síncronamente na retaguarda um **Pedido de Compra** de produtos, matéria-prima ou despesa fixa [Passage 4, 477, 883], ou ao efetuar o fechamento mensal da **Folha de Pagamento** de RH [Passage 457, 797], o sistema de retaguarda PHP de forma automática [Passage 457, 477]:
* Pesquisa pelo CNPJ/CPF e auto-cadastra os dados dos funcionários ou fornecedores em **Dados p/ Faturamento** para evitar omissões cadastrais no DRE [Passage 455, 457].
* **Injeta síncronamente as duplicatas correspondentes na tabela de `contas_pagar`** [Passage 457, 477, 797], amarrando a origem transacional (`origem_tabela = 'rh_folhas_pagamentos'`, etc.) [Passage 797], blindando o caixa de perdas e garantindo o provisionamento correto de saídas na tesouraria de forma transparente [Passage 842].
#### 3. Das Baixas ao Fluxo de Caixa, DRE e Centro de Custo:
* Ao realizar o recebimento de uma fatura de cliente ou o pagamento de um insumo de fábrica [Passage 50, 116], os títulos passam para o status de baixado [Passage 842, 844].
* A conciliação bancária compensa de forma definitiva os valores carimbando a coluna `compensado_em` no banco [Passage 23, 29].
* Esta transação de tesouraria de forma instantânea retroalimenta todo o ecossistema [Passage 838, 852-853]:
* Muda reativamente o saldo disponível na conta de banco em `view_contas_correntes` [Passage 838].
* Insere a movimentação líquida em tempo real na visão consolidada de **Fluxo de Caixa** (`view_fluxo_caixa`) [Passage 852-853].
* Alimenta de forma direta as somas de despesas reais do projeto em **Centro de Custo de Obra** (`view_obras_despesas`) [Passage 856-857].
* Injeta o valor na base de apuração anual para consolidação e geração do **DRE - Contabilidade** de retaguarda de forma 100% reativa [Passage 566], finalizando a esteira financeira do Sistrom ERP de ponta a ponta de forma síncrona.
---
### MÓDULO 11: MESA DE INTELIGÊNCIA ARTIFICIAL FINANCEIRA (`contas-pagar-gemini` & `contas-receber-gemini` & `fluxo-caixa-gemini`)
O módulo Financeiro do Sistrom ERP é equipado com assistentes de Inteligência Artificial integrados ao banco de dados e arquivos de tesouraria, operando de forma nativa sob as visões analíticas de caixa do Tenant [Passage 35, 96, 164].
---
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtypes:** `contas-pagar-gemini` [Passage 35], `contas-receber-gemini` [Passage 96] e `fluxo-caixa-gemini` [Passage 164].
* **Funcionamento:** Componente split-panel com o histórico de discussões e canais à esquerda (`assuntosGrid` [Passage 35, 96]) e o chat conversacional cibernético à direita [Passage 35, 96].
* **ViewModel e Formulas:**
O ViewModel de faturamento altera de forma reativa a diretriz do prompt de acordo com o foco do chat de tesouraria (`conversaAtiva` [Passage 36, 97, 166]):
* Se `conversaAtiva == 'banco'`: Configura como `"CONVERSA ATIVA COM BANCO DE DADOS"` [Passage 36, 97, 166]. (Habilita a IA a estruturar e rodar queries SQL de consulta de saldos no MariaDB).
* Se `conversaAtiva == 'documento'`: Configura como `"CONVERSA ATIVA PARA ANÁLISE DE DOCUMENTO"` [Passage 36, 97, 166]. (Habilita a IA a analisar síncronamente PDFs de faturamento e notas fiscais XML anexadas aos títulos).
* **API de Comunicação e Back-End (PHP - Roteador de Intenções):**
* **Endpoint Principal:** `mod/marmoraria/financeiro/fluxo_caixa/gemini/php/response.php` [Passage 165]
* **Classe PHP:** `Gemini` [Passage 568].
* **O Motor de Tradução de Linguagem Natural (`pegar_esquema`):**
Para permitir que o gestor financeiro faça perguntas abertas (Ex: *"Qual o saldo realizado de hoje?"* ou *"Quanto tenho para pagar em atraso?"* [Passage 36, 166]), o PHP utiliza o método privado **`pegar_esquema()`** [Passage 495, 533].
Este método atua como o dicionário de sinônimos técnicos e nomes físicos de colunas do banco de dados, blindando o envio de perguntas ao LLM e garantindo que o agente estratégico gere queries SQL seguras baseadas nas views do Tenant logado [Passage 495, 511, 533, 544]:
* Se o usuário falar: *"pagar"*, *"despesa"* ou *"saída"* ➔ Mapeia síncronamente para a view `view_contas_pagar` [Passage 511].
* Se falar *"recebimento"*, *"entrada"* ou *"cliente"* ➔ Mapeia síncronamente para a view `view_contas_receber` [Passage 544].
* Se falar *"conta corrente"*, *"banco"* ou *"extrato"* ➔ Mapeia para a view `view_fluxo_caixa`, coluna `conta_corrente` [Passage 495, 570].
* Se falar *"valor previsto"*, *"previsão"* ou *"futuro"* ➔ Mapeia para a coluna `previsto` [Passage 495, 496, 570].
* Se falar *"valor realizado"*, *"compensado"* ou *"baixado"* ➔ Mapeia para a coluna `compensado` [Passage 497, 571].
* Se falar *"atrasado"*, *"vencido"* ou *"cobrança"* ➔ Mapeia para a coluna `situacao` com o filtro fixo implícito `situacao = 'EM ATRASO'` [Passage 508, 509, 541].
* *Geração do Dossiê:* O agente strategic `AgChat` recebe os dados do banco de dados, processa os cálculos temporais e os exibe em tela dentro de cartões de layout modernos com o estilo CSS da Sistrom (`cyber-card` e mini-tabelas pt-BR) [Passage 445, 446, 447].
---
## CATEGORIA: ORÇAMENTOS
A categoria de **Orçamentos** é a engrenagem mestre de precificação, engenharia de vendas e fechamento do Sistrom ERP [Passage 213, 629]. Ela calcula com precisão matemática milimétrica os custos industriais (Méria, Corte, Acabamento, Mão de Obra de Instalação, Fretes, Viagens/Estadias e Impostos) e os converte síncronamente em propostas comerciais de alta precisão [Passage 70, 71, 133, 629].
Abaixo está o mapeamento detalhado dos módulos críticos solicitados: **Configurações do Orçamento** e **SAC / WhatsApp Messenger**.
---
### MÓDULO 1: CONFIGURAÇÕES DO ORÇAMENTO (`orcamento-configuracoes`)
Este módulo gerencia as regras comportamentais, as margens de tolerância/segurança, as preferências fiscais de faturamento direto, as vias de impressão de PDF, as listas de distribuição de notificações automáticas por e-mail e os comportamentos automáticos de baixas de estoque do orçamento [Passage 6, 7, 11, 13].
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE DADOS
```
[Interface: orcamento-configuracoes] (Ext.form.Panel)
│
(onSalvar - AJAX/POST via Form)
│
▼
[API: orcamentos/orcamentos/php/response.php]
│
▼
[Back-End PHP: Orcamentos.php]
│
┌───────────────────┴───────────────────┐
▼ (Escrita Física) ▼ (Trigger Reativa BF)
[marmoraria_orcamentos_configuracoes] <─── [marmoraria_orcamentos] (Clonagem)
```
##### A. Front-End (Sencha ExtJS v7.3.1)
* **Componentes de Interface (View):**
* **xtype:** `orcamento-configuracoes` [Passage 6, 39]. Habilitado como um `Ext.form.Panel` scrollable (ou `Ext.Dialog` maximizável na versão dialog [Passage 39]).
* **Estrutura de Propriedades e Grupos (`fieldset`):**
* *Layout de Impressão (PDF):* `id_empresa_pdf` (combobox corporativo) [Passage 40], `exibir_contato_empresa_pdf` (checkbox) [Passage 40], `exibir_endereco_empresa_pdf` (checkbox) [Passage 40] e `imagem` / `imagem_capa` (filefield de upload para capa de orçamento de dimensões `1180x1300` ou `2360x3100` dependendo do dispositivo) [Passage 7, 16, 40, 46].
* *Regras de Faturamento:* `faturamento_direto` (checkbox - repassa reativamente o custo de compra do bloco/chapa bruto direto para o fornecedor parceiro) [Passage 7, 40] e `exibir_faturamento` (checkbox - exibe os dados cadastrais do cliente no cabeçalho do PDF) [Passage 7, 40].
* *Margens de Segurança:* `perc_margem_perda` (percentfield - acréscimo de descarte em caso de materiais fora da tabela de preços) [Passage 8, 41], `perc_margem_orcamento` (percentfield - margem de folga do levantamento físico) [Passage 8, 41] e `perc_margem_excedente` (percentfield - limite tolerável de material excedente para produção de peças adicionais) [Passage 8, 41].
* *Agrupamentos no PDF:* `agrupar_colunas` (selectfield: `0-Desabilitado`, `1-Material + Beneficiamento`, `2-Material + Mão de Obra`, `3-Beneficiamento + Mão de Obra`) [Passage 8, 41, 838] e `agrupar_colunas_rotulo` (descritivo do bloco consolidado no PDF) [Passage 838].
* *Exibição de Transparência (Ajustes de Centavos):* `exibir_diferenca_valor` (selectfield: `0-Não exibir`, `1-Apenas orçamentos`, `2-Apenas pedidos`, `3-Exibir em ambos`) [Passage 9, 43], `exibir_diferenca_valor_desconto` (rótulo para desconto de arredondamento por câmbio) [Passage 9, 44] e `exibir_diferenca_valor_acrescimo` (rótulo para acréscimo matemático) [Passage 9, 44].
* *Exibições de Relações e Cubas:* `exibir_resumo_material_sem_perda`, `exibir_resumo_material_com_perda` (exibe cubagem/m² limpos ou brutos), `exibir_resumo_valores_agrupados_andar_ambiente` (resumo de custos por local físico) [Passage 10].
* *Automações do Pátio:* `auto_completar_medidas` (checkbox - auto-preenche as dimensões da peça com base no último produto similar) [Passage 12], `auto_descrever_medidas` (escreve as dimensões na string de descrição do item) [Passage 12], `auto_incluir_subitens` (checkbox) [Passage 12] e `baixa_automatica_estoque` (checkbox - ao finalizar ordens de cortes na fábrica, baixa os insumos e chapas brutas reativamente do estoque) [Passage 12, 13].
* *Prazos e Alertas (Dias):* `dias_sem_mexer_orcamento` (alerta de ociosidade) [Passage 11], `dias_sem_resposta_do_cliente` (alerta comercial) [Passage 11] e `dias_sem_aprovar_pedido` [Passage 11].
* *Filtro e Roteamento de PDF por E-mail:* Caixas de texto dinâmicas para e-mails de retaguarda: `lista_email_cobranca`, `lista_email_via_obra` [Passage 15], `lista_email_via_pedido` [Passage 15], `lista_email_via_custo` [Passage 15], `lista_email_via_producao` [Passage 15] e `lista_email_via_excedente` [Passage 15].
* **Mapeamento MVVM (ViewModel / Store / Controller):**
* **Model:** `ERP.orcamento.configuracoes.model` mapeia síncronamente os tipos de variáveis e flags do banco de dados [Passage 13-16].
* **ViewController (`ERP.orcamentos.configuracoes.controller`):**
* No `init()`, dispara uma requisição `GET` para o endpoint em PHP com os parâmetros `m: "configuracoes"` e `id_orcamentos: this.idOrcamentos()` para readequar e popular síncronamente os campos do formulário (`form.reset()`, `form.setValues()`) [Passage 46].
* O método `onSalvar()` valida se o usuário possui a permissão de alçada operacional `alterar_configuracoes_orcamento` [Passage 47]. Sendo aprovada, realiza a submissão síncrona do formulário (`form.submit()`) chamando a action `salvar_configuracoes` [Passage 47].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/orcamentos/orcamentos/php/response.php` [Passage 46, 47, 572].
* **Classe PHP:** `Orcamentos` [Passage 572].
* **Método `salvar_configuracoes`:** Invoca a função herdada `get_post_records()` [Passage 496] para sanitizar as strings do formulário e executa síncronamente o `UPDATE` físico sobre a tabela de parametrização [Passage 531].
##### C. Persistência de Dados e Cascata reativa (MariaDB 5.6.36)
* **Tabela de Dados:** `marmoraria_orcamentos_configuracoes` [Passage 566, 842].
* **Mecanismo de Herança via Triggers (The "Budgets Cloning Flow"):**
O Sistrom ERP implementa um fluxo síncrono de herança de parametrização para evitar que o orçamentista tenha que reconfigurar as margens e PDFs ao duplicar orçamentos [Passage 852, 853]:
* Quando um novo orçamento comum é criado do zero, a trigger `BEFORE INSERT` em `marmoraria_orcamentos` herda reativamente todos os padrões comerciais da tabela matriz de Tenant `marmoraria_configuracoes` [Passage 858].
* Se o novo orçamento for gerado por clonagem (`m: "copiar"`) [Passage 523], revisão de escopo (`m: "revisar"`) [Passage 524] ou criação de opção de venda (`m: "opcao"`) [Passage 525], a trigger reativa do MariaDB detecta a flag `new.pai_id > 0` e **clona síncronamente toda a linha de configurações de impressão, e-mails, comissões e impostos diretamente do orçamento pai** (`WHERE id_orcamentos = new.pai_id`) para a nova chave primária `new.id` [Passage 852, 853], eliminando duplicidade ou falha humana de precificação.
---
### MÓDULO 2: SAC / WHATSAPP MESSENGER (`messenger`)
Este módulo atua como a central de comunicação e atendimento reativo da marmoraria, conectando o pátio de vendas e pós-vendas diretamente ao WhatsApp dos clientes [Passage 922, 923]. Ele viabiliza o envio instantâneo de faturamentos, revisões de propostas, e utiliza um motor inteligente de formatação de mensagens interativas [Passage 85, 95, 837].
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE COMUNICAÇÃO
```
[Interface Visual: messenger] (Ext.Panel)
│
┌───────────────────────────┴───────────────────────────┐
▼ (Visualizar / Tratar) ▼ (Disparo Automático)
[orcamentos-mensagens] [enviar_mensagem_lista_opcoes]
│ │
▼ (onConfirm: iniciar_assunto) ▼ (Chamada de API Síncrona)
[response.php (mensagens)] ──► [ia_conversas] [WhatsApp Cloud API REST]
```
##### A. Front-End (Sencha ExtJS v7.3.1)
* **Componentes de Interface (View):**
* **xtype:** `messenger` (ou `orcamentos-mensagens` para controle contextual do grid de orçamentos) [Passage 26, 922].
* **Layout:** `fit` [Passage 26]. Habilita um painel com split lateral apresentando a árvore de tópicos cadastrados (`assuntosGrid` / `assuntosTree`) e o chat síncrono responsivo com balões de diálogo [Passage 27, 253].
* **Ação de Iniciar Tópico (`onIncluir`):** Abre a janela de cadastro rápido de discussões comerciais `Ext.Dialog.form` [Passage 27]. Solicita:
1. O número do Orçamento ou Pedido (`id_orcamentos`) [Passage 27].
2. O assunto mestre da conversação (`assunto` - maxLength 150) [Passage 27].
* **ViewController (`ERP.orcamentos.mensagens.view`):**
Ao salvar, valida permissões do tipo `iniciar_conversa_orcamento` [Passage 28], dispara chamada de API para o response em PHP e, de imediato, recarrega a árvore de canais síncronamente [Passage 28, 30].
* **Plugin Swiper de Ação em Linha (`listswiper`):**
Permite que o operador de atendimento faça interações por gestos no chat [Passage 14, 396]:
* *Swiper Left (Gestos de Entrada):* Enviar e-mail síncrono (`onCommitEmail`) e efetuar ligação telefônica (`onCommitTelefone`) [Passage 396, 415].
* *Swiper Right (Gestos de Saída):* Chamar via celular (`onCommitCelular`) ou disparar mensagem direta para o WhatsApp (`onCommitWhatsApp`) [Passage 396, 415].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint de Mensagens:** `mod/marmoraria/orcamentos/mensagens/php/response.php` [Passage 28, 516].
* **Algoritmo de Atendimento Automatizado (WhatsApp Cloud API):**
A classe PHP `Marmoraria` implementa o motor de mensageria ativa da API oficial do WhatsApp [Passage 837]:
```php
function enviar_mensagem_lista_opcoes($para, $texto_corpo, $titulo_menu, $secoes) {
$secoes_formatadas = array();
foreach ($secoes as $secao) {
$opcoes_formatadas = array();
foreach ($secao->opcoes as $opcao) {
array_push($opcoes_formatadas, array(
"id" => substr($opcao->id, 0, 200),
"title" => substr($opcao->text, 0, 20),
"description" => property_exists($opcao, "tooltip") ? substr($opcao->tooltip,0,70) : ""
));
}
array_push($secoes_formatadas, array(
"title" => substr(property_exists($secao,"titulo") ? $secao->titulo : $titulo_menu,0,20),
"rows" => $opcoes_formatadas
));
}
// Monta o payload JSON REST e despacha síncronamente via cURL para o gateway WhatsApp
}
``` [Passage 837]
* **Processador de Link de Propostas:**
Ao gerar com êxito as vias fiscais ou PDF de faturamento (`imprimir_orcamento`) [Passage 95], o sistema monta a string de encaminhamento direto e a codifica em URL amigável pt-BR [Passage 76]:
```php
$mensagem = array();
array_push($mensagem, "Seguem em anexo os arquivos de seu orçamento de " . $P->obra_nome);
array_push($mensagem, $url_do_pdf_servidor);
App.util.page.open.whatsapp($fone_cliente, join("%0a", $mensagem));
``` [Passage 76]
##### C. Persistência de Dados (MariaDB)
* **Tabela de Discussões Mestre:** `ia_conversas` (ou `marmoraria_orcamentos_mensagens`) [Passage 491, 898].
* **Tabela de Prontuário de Mensagens:** `marmoraria_orcamentos_mensagens_conversas` [Passage 516].
* **Tabela de Controle de Confirmação:** `marmoraria_orcamentos_mensagens_conversas_lidas` [Passage 517, 595].
---
### 📘 GUIA DE OPERAÇÃO OPERACIONAL (MANUAL DO USUÁRIO)
#### Objetivo da Categoria de Orçamentos
Centralizar os parâmetros comerciais e financeiros da marmoraria, adaptando o ERP a margens operacionais de sobras e perdas industriais de pedras brutas e disponibilizando canais síncronos de acompanhamento, envio e pós-vendas no WhatsApp de forma direta [Passage 11, 40, 76, 306].
#### Operações Passo a Passo
##### 1. Parametrizar a Margem de Segurança e Agrupamento de Colunas
1. Acesse o menu **Orçamento > Configurações** [Passage 923].
2. O sistema abrirá a interface parametrizadora de orçamentos [Passage 6, 39].
3. Na seção **Margem**, preencha [Passage 8, 41]:
* **Material:** Digite `15.00` (Percentual de acréscimo para margem de perda no corte de chapas brutos) [Passage 8, 41].
* **Orçamento:** Digite `5.00` (Percentual de acréscimo para folga geral da proposta) [Passage 8, 41].
* **Excedente:** Digite `10.00` (Limite máximo tolerado para material excedente produzido no pátio) [Passage 8, 41].
4. Na seção **Agrupamentos**, no campo **Agrupamento de colunas**, selecione a opção `Material + Beneficiamento` [Passage 8, 41, 838]. *Isso instrui o motor matemático do MariaDB a unificar custos e apresentar preços finais limpos e sem quebras detalhadas no PDF do cliente [Passage 8].*
5. Clique em **Salvar** [Passage 13, 45]. O controller validará suas permissões e gravará síncronamente na tabela mestre de retaguarda [Passage 47].
##### 2. Configurar a Relação de E-mails de Produção e Custo de Obras
1. Ainda na tela de **Configurações do Orçamento** [Passage 6, 39], navegue até o painel inferior de campos de e-mail.
2. No campo **PDF - Via de Produção**, insira os e-mails dos encarregados da fábrica (Ex: `serra1@marmoraria.com.br; acabamento@marmoraria.com.br`) [Passage 15, 45].
3. No campo **PDF - Via de Excedente**, preencha o e-mail da controladoria (Ex: `diretoria@marmoraria.com.br`) [Passage 11, 15, 45].
4. Salve. Quando a proposta for aprovada e transicionar síncronamente para o status de Pedido Comercial, o ERP enviará de forma 100% autônoma o PDF correspondente para cada e-mail cadastrado, otimizando os prazos industriais sem digitação manual de relatórios [Passage 241, 269].
##### 3. Enviar Holerite e Propostas via WhatsApp (SAC / Messenger)
1. Acesse a grade de orçamentos ou pedidos no dashboard comercial [Passage 897, 926].
2. Selecione a proposta comercial ativa e clique no botão **Conversar** (ícone de chat) [Passage 84].
3. O sistema abrirá o painel de **SAC / WhatsApp** [Passage 253, 922].
4. Caso já exista um canal de discussões cadastrado para o cliente, selecione-o na árvore esquerda; caso contrário, clique em **Incluir**, defina o assunto (Ex: *Alinhamento de Medidas do Lavabo Master*) e confirme [Passage 27, 28, 104].
5. Para disparar a proposta gerada: clique em **Imprimir** [Passage 85]. No pop-up de arquivos de impressão bem-sucedidos [Passage 76], clique em **WhatsApp** [Passage 74].
6. O ERP formatará reativamente o texto pt-BR com os links de download em PDF [Passage 76], invocando síncronamente o método `App.util.page.open.whatsapp` para disparar a mensagem diretamente para o smartphone do cliente com 1 clique [Passage 76].
---
### ⚡ VÍNCULOS TRANSVERSAIS E CASCATA REATIVA DO ECOSSISTEMA
As **Configurações de Orçamentos** e a **Mensageria** operam de forma direta retroalimentando as tabelas e faturamentos de retaguarda do Sistrom ERP:
* **Validação de Trava Comercial via CRM:**
No momento em que o vendedor altera o status de uma proposta comercial no quadro Kanban do CRM para **`FECHADO`** (visando transformá-lo em Pedido de Venda ativo) [Passage 101, 522], a trigger do MariaDB e a classe em PHP varrem de forma síncrona as configurações de faturamento cadastrados [Passage 101]: se a flag `exibir_faturamento` estiver ativa [Passage 838] mas o cliente correspondente não possuir CNPJ/CPF cadastrado em **Dados p/ Faturamento** (`dados_faturamentos`) [Passage 101], o ERP interrompe síncronamente a transação, impede o fechamento comercial e emite o alerta visual na interface ExtJS [Passage 101]: *"Antes de fechar o orçamento, você deve atribuir um CNPJ/CPF, Endereço e todos os dados cadastrais para faturamento."*
* **Baixa Automática de Estoques e Ordens de Cortes:**
Se no módulo de configurações a flag **`baixa_automatica_estoque`** estiver marcada como `TRUE` [Passage 804], o ciclo de vida de produção é otimizado [Passage 804]. No instante em que o encarregado da fábrica altera síncronamente o status de uma Ordem de Corte para `FINALIZADO` no pátio [Passage 804], a classe `Instalacoes` de retaguarda dispara uma varredura [Passage 803, 804]. O banco de dados calcula reativamente o quantitativo quadrado (m²) consumido na peça [Passage 804], localiza a ID correspondente em `estoques_materiais` e **executa reativamente e em tempo real a baixa física de chapas brutas no estoque do pátio**, registrando o log histórico de movimentação sem que o estoquista tenha que digitar um único dado [Passage 804, 805].
---
## CATEGORIA: ORÇAMENTO
### SUBCATEGORIA: TABELAS DE PREÇOS
A subcategoria de **Tabelas de Preços** do Sistrom ERP é a espinha dorsal de inteligência analítica e financeira do módulo de Orçamentos [Passage 842]. Ela funciona como um **motor paramétrico de formação de preços**, responsável por desestruturar peças complexas de mármores ou granitos em variáveis fiscais e de custo elementares: **Matéria-Prima (Material), Industrialização (Corte e Acabamento) e Mão de Obra de Campo (Instalação)** [Passage 280].
Além dos itens principais de pátio, o sistema gerencia com precisão matemática os **produtos indiretos de revenda**, os **serviços extras** (próprios ou terceirizados) e os **complementos operacionais** parametrizados por regras adaptativas de rendimento [Passage 43, 50, 169, 648].
---
```
[ESTÚDIO DE PRECIFICAÇÃO]
│
┌───────────────────────────────────────┼───────────────────────────────────────┐
▼ ▼ ▼
[Matérias Primas] [Industrialização] [Outros Custos]
- Materiais (m²/m³) - Cortes (m²/MLN/UN) - Complementos (Rendimento)
- Acabamentos (m²) - Acabamentos (VENDA/PERC) - Serviços Indiretos (Extra)
- MDO Instalação (m²/MLN/UN) - Produtos Indiretos (Revenda)
│ │ │
└───────────────────────────────────────┼───────────────────────────────────────┘
▼
[Stored Procedure Central]
`CALCULAR_MARMORARIA_ORCAMENTO`
│
▼
[Simulação de Preços]
`tabela-preco-cotacao`
```
---
### MÓDULO 1: TABELAS E CATEGORIAS DE PREÇOS (`tabelas-categorias-precos-list`)
Este módulo atua como o agrupador mestre de precificação, permitindo que a marmoraria inquilina gerencie síncronamente múltiplas tabelas de vendas (Ex: *Tabela Padrão*, *Tabela Construtoras*, *Parceiros Arquitetos*) divididas por categorias de aplicação [Passage 182, 842].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `tabelas-categorias-precos-list` [Passage 182].
* **Layout:** `hbox` dividindo a tela em duas grades paralelas de edição rápida síncrona [Passage 182]:
1. `tabela-grid` (Esquerda): Gerencia as tabelas mestres (`id_tabelas`) [Passage 182, 412].
2. `categoria-grid` (Direita): Associa as categorias de precificação (`id_categorias`) [Passage 121, 412].
* **Ações da Toolbar (tbar):** Incluir, Copiar ou Excluir Tabelas e Categorias [Passage 121].
* **Proxy de Conexão:** Rota AJAX para `mod/marmoraria/orcamentos/precos/tabelas_categorias/php/response.php` [Passage 469].
* **Retaguarda (PHP & MariaDB):**
* **Classe PHP:** `Precos` [Passage 469].
* **Lote de Importação:** O método `importar_tabela_preco_orcamento` permite duplicar tabelas e sincronizar reativamente todos os produtos e acabamentos vinculados à empresa parceira logada de forma síncrona [Passage 183].
---
### MÓDULO 2: PRECIFICAÇÃO DE MATÉRIAS PRIMAS (`tabela-preco-material-list`)
Este painel gerencia a precificação base de todas as chapas, ladrilhos e blocos brutos em estoque, convertendo compras em moedas estrangeiras e adicionando impostos, fretes e margens para gerar o preço final de venda do m² [Passage 70, 188, 633, 843].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `tabela-preco-material-list` [Passage 843].
* **Ações de Lote:** O menu `manutencao-menu` aciona popups síncronos para **Alterar Custo** (`tabela-preco-material-alterar-custo-form`), **Alterar Venda** [Passage 154, 161, 162], **Redefinir Perda** e **Redefinir Lucro** [Passage 154, 155].
* **A Fórmula do Motor Tributário do Material (MariaDB 5.6.36):**
Sempre que um material bruto é inserido ou reajustado em banco, as triggers síncronas de banco **`marmoraria_materiais_precos_tg_bf_insert`** (BEFORE INSERT) [Passage 650] e **`marmoraria_materiais_precos_tg_bf_update`** (BEFORE UPDATE) [Passage 650, 651] calculam reativamente o custo real e o preço de venda pt-BR [Passage 649, 650]:
1. **Custo Real Reais (IPI + Frete + Moeda):**
Se o material for importado (`moeda != 'REAL'`), o banco síncronamente puxa a cotação ativa (`conversor_moeda`) [Passage 432, 768]. O custo é consolidado somando a compra bruta, o frete por m² e o valor calculado de IPI [Passage 650]:
\\[\text{Valor Custo} = \text{Compra} + \text{Frete} + \left( \frac{\text{IPI}}{100} \times \text{Compra} \right)\\] [Passage 650]
2. **Preço Final de Venda de Prateleira (Perda + Lucro + Impostos Internos):**
Para formar a venda m², o MariaDB aplica a cascata de margens e impostos [Passage 650, 652]:
\\[\text{Valor Venda} = \frac{\frac{\text{Valor Custo} \times (1 + \text{Perda}/100)}{1 - \text{Lucro}/100}}{1 - \text{Imposto}/100}\\] [Passage 650, 652]
---
### MÓDULO 3: PRECIFICAÇÃO DE ACABAMENTOS DE MATERIAIS (`tabela-preco-acabamento-list`)
Determina o preço de custo e venda de perfis de acabamentos específicos aplicados às bordas das chapas brutas de mármore (Ex: boleado simples, bisotado) [Passage 64, 557, 844].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **xtype:** `tabela-preco-acabamento-list` [Passage 844].
* **Tabela MariaDB:** `marmoraria_materiais_acabamentos_precos` [Passage 410, 414].
* **API PHP:** `Precos` (`mod/marmoraria/orcamentos/precos/acabamentos/php/response.php`) [Passage 412, 418].
---
### MÓDULO 4: PRECOS DE PRODUTOS PARA INDUSTRIALIZAÇÃO (`tabela-preco-produto-list`)
Gerencia o preço específico de **Corte** (serrada de fábrica) e **Instalação** (mão de obra / MDO do colocador) de cada produto de pátio por unidade de medida [Passage 166, 240, 558, 843].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `tabela-preco-produto-list` [Passage 164, 843].
* **Parametrização por Tipos de Peças:**
O produto recebe a tag `tipo_peca` (`NORMAL`, `CUBA`, `NICHO`, `COLUNA`, `CAIXA`, `PISADA`) [Passage 240]. Esse campo é lido reativamente pela Stored Procedure de cálculo de m² do pátio para inferir de forma tridimensional as áreas das abas e saias laterais, calculando o peso total em kg e a cubagem exata de corte [Passage 240, 280, 671].
* **Persistência (MariaDB):**
* **Tabela:** `marmoraria_produtos_precos` [Passage 559].
* **Unidades Flexíveis:** Permite estipular custos diferenciados se cobrados por m², metro linear (MLN), unidade (UN), peça (PÇ) ou conjunto (CJ) [Passage 166, 240].
---
### MÓDULO 5: PRECOS DE ACABAMENTOS DE PRODUTOS / BENEFICIAMENTO (`tabela-preco-beneficiamento-list`)
Controla os custos e as vendas do beneficiamento dos produtos (Ex: colagem de meia esquadria em pias esculpidas, polimento de cubas) [Passage 123, 843].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **xtype:** `tabela-preco-beneficiamento-list` [Passage 843].
* **Tabela MariaDB:** `marmoraria_acabamentos_produtos_precos` [Passage 419, 422].
* **Lógica de Formação Dinâmica por Percentual (O Diferencial do Sistrom):**
O acabamento de produto não precisa de um preço de venda fixo [Passage 123]. O orçamentista pode parametrizar o campo `preco` como `'PERCENTUAL'` e definir o `perc_mat` (Ex: `20.00%`) [Passage 123].
No cálculo, a trigger e a procedure de fechamento de orçamento buscam o preço de venda bruto da chapa do material e **calculam de forma autônoma e reativa o valor de venda do acabamento como percentual do material selecionado**, garantindo que materiais nobres (Ex: Quartzito) cobrem acabamentos proporcionalmente mais caros que granitos comuns [Passage 731]:
```sql
t1.venda = IF(t2.preco = 'PERCENTUAL' AND t2.perc_mat > 0, (_venda_bruta_mat * (t2.perc_mat / 100)), ...)
``` [Passage 731]
---
### MÓDULO 6: TABELA DE COMPLEMENTOS (`tabela-preco-complemento-list`)
Este módulo gerencia a carteira de insumos complementares atrelados ao item principal (Ex: mão francesa, grampos, vedantes de silicone, argamassas, rejuntes) [Passage 41, 125, 844].
#### ⚙️ Mapeamento Arquitetural e Regras Matemáticas de Rendimento
```
[Orçamento: Item Principal] (M² ou MLN)
│
▼ (Injeção de Complemento)
[marmoraria_complementos]
│
┌────────────────────────┴────────────────────────┐
▼ (Se tipo_calculo = 'MLN') ▼ (Se tipo_calculo = 'M²')
[Math.ceil(total_mln / rendimento_mln)] [Math.ceil(total_m2 / rendimento_m2)]
│ │
└────────────────────────┬────────────────────────┘
▼
[Calcula Quantidade síncrona]
```
* **Front-End (Sencha ExtJS v7.3.1):**
* **xtype:** `tabela-preco-complemento-list` [Passage 125, 844].
* **Campos de Modelagem (`checklists-estudio`):**
* `tipo_calculo` (ENUM: `'M²'`, `'MLN'`) [Passage 131, 645].
* `rendimento_m2` e `rendimento_mln` (moneyfield) [Passage 131, 645].
* `de_m2` e `ate_m2` (Define a faixa de metragem total da obra na qual este complemento será aplicado síncronamente) [Passage 126, 131].
* **O Algoritmo de Cálculo do Rendimento em Lote (MariaDB):**
Os complementos calculam de forma 100% autônoma o quantitativo físico a ser vendido para o cliente final [Passage 43, 50]. A fórmula lê a metragem total linear ou quadrada do item mestre e divide pelo rendimento nominal, aplicando um arredondamento para cima (`Math.ceil`) para garantir faturamento de embalagens fechadas de argamassas ou unidades inteiras de suportes [Passage 43, 50, 131]:
* **Se cálculo por Metro Linear (MLN) - Ex: Mão Francesa:**
\\[\text{Quantidade} = \lceil \frac{\text{Total MLN}}{\text{Rendimento MLN}} \rceil\\] [Passage 43, 50]
* **Se cálculo por Metro Quadrado (M²) - Ex: Cola Cuba / Argamassas:**
\\[\text{Quantidade} = \lceil \frac{\text{Total M²}}{\text{Rendimento M²}} \rceil\\] [Passage 43, 50]
---
### MÓDULO 7: PRODUTOS INDIRETOS DE REVENDA (`tabela-preco-produto-indireto-list`)
Gerencia os produtos industrializados que a marmoraria adquire de terceiros e revende diretamente na proposta (Ex: cubas de inox de sobrepor, torneiras, ralos ocultos) [Passage 168, 846].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **xtype:** `tabela-preco-produto-indireto-list` [Passage 168, 846].
* **Mapeamento de Impostos Intercomerciais (`produto`):**
O produto indireto é classificado em banco no seletor `produto` entre `'MATERIAL'`, `'BENEFICIAMENTO'` ou `'INSTALAÇÃO'` [Passage 169]. Esta classificação síncrona instrui o motor fiscal em PHP (`response.php`) no momento da aprovação do orçamento, de forma que o imposto de saída do item de revenda seja provisionado reativamente na coluna de retenção correspondente, garantindo a fidedignidade do DRE [Passage 32, 33, 80, 81].
---
### MÓDULO 8: SERVIÇOS INDIRETOS EXTRA (`tabela-preco-servico-indireto-list`)
Controla os serviços extras fornecidos na obra (Ex: remoção e descarte de tampos antigos, impermeabilização química de quartzitos, içamento por fora de prédios) [Passage 29, 176, 845].
#### ⚙️ Mapeamento Arquitetural e Fluxo de Dados
* **xtype:** `tabela-preco-servico-indireto-list` [Passage 176, 845].
* **Regra de Margem mínima e Venda:**
Opera com campos `custo_minimo` [Passage 181] e `venda_minima` [Passage 181]. Se o fechamento do orçamento de campo apurar uma metragem insignificante cujo valor não cubra a vinda do instalador, o MariaDB de forma síncrona despreza a metragem e **aplica de forma imediata o valor mínimo parametrizado na tabela**, salvaguardando a rentabilidade do projeto [Passage 34, 181, 743].
---
### MÓDULO 9: SIMULAÇÃO DE PREÇOS EM TEMPO REAL (`tabela-preco-cotacao`)
Este módulo é a ferramenta tática de balcão de vendas da marmoraria, permitindo que o vendedor projete instantaneamente valores para qualquer produto sem precisar iniciar uma proposta formal de faturamento [Passage 133, 846].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE SIMULAÇÃO
```
[Vendedor: tabela-preco-cotacao] (Grid)
│
(Selec. Tabela ➔ Selec. Categoria ➔ Selec. Material)
│
▼ (onSelectMaterial - AJAX/GET)
[API: orcamentos/precos/cotacoes/php/response.php]
│
▼ (Método: Cotacoes::listar)
[Executa Cálculo Matemático em PHP]
│
▼ (Retorna JSON consolidado)
[Exibe na Grade de Simulação do ERP]
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `tabela-preco-cotacao` [Passage 133, 846].
* **Estrutura de Toolbar de Seleção Encadeada (Mestre-Detalhe):**
O vendedor realiza o filtro sequencial através de comboboxes com escopos reativos [Passage 133, 134]:
1. `tabela-select` (Tabela de Preço base) [Passage 133] ➔ Dispara `onSelectTabela` habilitando a combo de categorias [Passage 134, 136].
2. `categoria-select` (Categoria de Preço) [Passage 134] ➔ Dispara `onSelectCategoria` abrindo o filtro de materiais [Passage 134, 136].
3. `material-select` (Material / Chapa) [Passage 134] ➔ Dispara `onSelectMaterial`, atualiza os parâmetros extras da store e invoca o carregamento síncrono da grade [Passage 134, 137].
* **Grade de Visualização (Colunas de Projeções):**
* *Coluna 1 (Material):* Preço de venda m² calculado do material com impostos de Tenant [Passage 134].
* *Coluna 2 (Corte):* Preço de venda m²/MLN do corte com reajustes [Passage 135].
* *Coluna 3 (Valor Final):* **Soma Síncrona** de Material + Corte em negrito [Passage 135].
* *Coluna 4 (Instalação):* Preço de venda m²/MLN da mão de obra de montagem [Passage 135].
* *Coluna 5 (Preço Final):* **Custo Consolidado total por m² (Material + Corte + Instalação)** destacado em tom azul pastel (`bg: #E3F2FD`, `color: #1565C0`) [Passage 136].
##### B. API de Comunicação e Regras em PHP
* **Endpoint:** `mod/marmoraria/orcamentos/precos/cotacoes/php/response.php` [Passage 138, 433].
* **Classe PHP:** `Cotacoes` [Passage 430] ➔ Método: `listar` [Passage 430].
* **Lógica de Desidratação Fiscal em Tempo de Simulação:**
O PHP executa em milissegundos o cálculo dinâmico simulado para os produtos cadastrados [Passage 431, 432]:
1. Recupera as alíquotas fiscais configuradas nos parâmetros corporativos da marmoraria logada (`perc_imposto_mat`, `perc_imposto_mdo`, `perc_imposto_benef`) [Passage 431, 432].
2. Puxa a moeda de compra da chapa (Ex: `DÓLAR`) e aplica a conversão ativa de câmbio (`conversor_moeda` [Passage 432, 768]).
3. Executa a desidratação fiscal de venda do material aplicando as retenções de saída configuradas [Passage 432]:
```php
$venda_mat_base = ($tabela->valor_venda * $cambio);
$valor_venda_material = ($perc_imposto_mat > 0) ? ($venda_mat_base / ((100 - $perc_imposto_mat) / 100)) : $venda_mat_base;
``` [Passage 432]
4. Varre os produtos e calcula síncronamente as saídas de cortes e instalações correspondentes à tabela, devolvendo o JSON pt-BR estruturado para preenchimento imediato da grade ExtJS [Passage 432, 433].
---
### 📘 GUIA DE OPERAÇÃO COMERCIAL (MANUAL DE ORÇAMENTISTA)
```
Orçamento (Categoria) [Passage 914]
├── SAC (messenger) [Passage 914]
├── Configurações (orcamento-configuracoes) [Passage 915]
└── Tabelas de preços (Subcategoria) [Passage 915]
├── 1. Tabelas e Categorias [Passage 915]
├── 2. Industrialização -> Produtos [Passage 915, 916]
├── 3. Industrialização -> Acabamentos [Passage 916]
├── 4. Matérias primas -> Materiais [Passage 916]
├── 5. Matérias primas -> Acabamentos [Passage 916, 917]
├── 6. Complementos [Passage 917]
├── 7. Estadias [Passage 917]
├── 8. Fretes [Passage 918]
├── 9. Serviços indiretos [Passage 918]
├── 10. Produtos indiretos [Passage 918, 919]
└── 11. Simulação de Preços [Passage 919]
```
---
### MÓDULO 1: TABELAS E CATEGORIAS (`tabelas-categorias-precos-list`)
Este módulo gerencia os **perfis de precificação** e agrupamentos lógicos de vendas da marmoraria [Passage 182, 842]. Ele permite criar tabelas distintas para diferentes nichos de mercado (Ex: *Construtoras*, *Consumidor Final*, *Arquitetos Parceiros*) e categorizar as peças de forma organizada [Passage 21, 182, 631].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabelas-categorias-precos-list` [Passage 363]
* **Estrutura:** Dividido em duas grades paralelas (`tabela-grid` para as tabelas mestres [Passage 363] e `categoria-grid` para as categorias [Passage 364]).
* **Edição:** `gridcellediting` habilitado para alteração inline de nomes e descrições [Passage 364].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/tabelas_categorias/php/response.php` [Passage 367].
* **Classe PHP:** `Precos` (Mapeia as ações síncronas `tabelas`, `categorias`, `copiar_tabela` [Passage 684, 685, 687]).
* **Banco de Dados:**
* **Tabelas:** `marmoraria_tabelas_precos` (IDs e nomes das tabelas) [Passage 627, 688] e `marmoraria_categorias_precos` (Categorias associadas) [Passage 627, 689].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Como Incluir uma Tabela de Preço:** Na grade à esquerda, clique em **Incluir** [Passage 364]. Um registro em branco surgirá na célula [Passage 22]. Digite o nome (Ex: `CONSTRUTORAS - MARGEM REDUZIDA`) e salve [Passage 21].
2. **Como Duplicar um Perfil Contábil:** Selecione a tabela de origem, clique em **Copiar** [Passage 364, 367]. O ERP abrirá um prompt solicitando o nome da nova tabela [Passage 367]. Digite (Ex: `CÓPIA CONSTRUTORAS`) [Passage 368]. O banco executará o método `copiar_tabela()`, duplicando síncronamente todos os preços cadastrados de materiais, acabamentos e produtos para o novo perfil [Passage 686].
3. **Como Cadastrar as Categorias de Peças:** Na grade à direita, clique em **Incluir** [Passage 370]. Adicione as categorias de uso (Ex: `COZINHAS`, `BANHEIROS`, `LAREIRAS`) [Passage 246, 256]. Elas servirão de base para cruzar com as rochas e custos de cortes [Passage 250, 314].
---
### MÓDULO 2: INDUSTRIALIZAÇÃO -> PRODUTOS (`tabela-preco-produto-list`)
Gerencia os preços de **Corte** (serragem na máquina Ponte CNC) e **Instalação** (mão de obra física do colocador) para cada tipo de produto industrializado da marmoraria [Passage 166, 240, 558, 843].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-produto-list` [Passage 334].
* **ViewModel/Stores:** Store `{produtos}` apontando para o endpoint via proxies estruturados [Passage 335, 340].
* **Colunas Críticas:** `produto` [Passage 338], `tipo_material` (Chapa, Ladrilho, Pedra) [Passage 338], `custo_corte` [Passage 347], `venda_corte` [Passage 347] e `venda_mdo` (Preço de Instalação) [Passage 347].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/produtos/php/response.php` [Passage 342, 347].
* **Método:** `reajustar` (processa alterações matemáticas em lote) [Passage 347].
* **Banco de Dados:**
* **Tabela:** `marmoraria_produtos_precos` [Passage 674].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Mapear Unidades de Medidas:** Defina a forma como o corte e a instalação serão medidos [Passage 501]. Para tampos complexos, configure `unidade_corte = 'MLN'` (Metro Linear) e `unidade_mdo = 'M²'` [Passage 339, 501].
2. **Definir Custos de Produção e Venda:**
* Dê um duplo clique na célula de **Corte - Custo** (Ex: insira `35.00` por MLN para serra ponte) [Passage 200].
* No campo **Venda**, se quiser precificar com base no lucro percentual, dê um duplo clique na coluna `lucro_corte` [Passage 343]. Digite `40` (%) [Passage 277]. O ViewController chamará de forma instantânea a função `App.util.calc.venda.produto` para salvar o valor corrigido no MariaDB [Passage 343].
3. **Configurar Preço do Colocador:** Em **Instalação (Mão de Obra)**, insira o preço de custo pago ao colocador e o preço que será faturado para o cliente (Ex: Custo: `120.00` / Venda: `250.00` por M²) [Passage 35].
---
### MÓDULO 3: INDUSTRIALIZAÇÃO -> ACABAMENTOS (`tabela-preco-beneficiamento-list`)
Mapeia a precificação de beneficiamentos e usinagens aplicados diretamente nas peças (Ex: colagem de meia esquadria em pias esculpidas, polimento de cubas) [Passage 123, 843].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-beneficiamento-list` [Passage 268].
* **Colunas:** `acabamento` [Passage 258], `custo` [Passage 646], `venda` [Passage 646], `perc_mat` (Percentual sobre o material) [Passage 259] e `preco` (VENDA, PERCENTUAL, VENDA E PERCENTUAL) [Passage 259, 260].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/beneficiamentos/php/response.php` [Passage 264, 268].
* **Banco de Dados:**
* **Tabela:** `marmoraria_acabamentos_produtos_precos` [Passage 638, 645].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Diferenciar Cobrança Fixa de Cobrança Percentual:**
* *Cobrança Fixa:* Se o acabamento de colagem custa um preço fixo, selecione o método `PRECO = 'VENDA'` [Passage 259, 260] e insira o valor (Ex: `90.00` por MLN) [Passage 62].
* *Cobrança Percentual (Markup de Luxo):* Para usinagens complexas em rochas sensíveis, selecione `PRECO = 'PERCENTUAL'` [Passage 259, 260] e insira o percentual no campo **Material (%)** (Ex: `20.00`%) [Passage 259]. *O sistema calculará síncronamente o preço da usinagem baseando-se no m² da chapa utilizada, garantindo faturamento proporcional à nobreza do material [Passage 731].*
---
### MÓDULO 4: MATÉRIAS PRIMAS -> MATERIAIS (`tabela-preco-material-list`)
Este painel é o coração de custos das rochas [Passage 843]. Ele gerencia o preço base de todas as chapas e blocos, calculando de forma síncrona taxas de câmbio de moedas estrangeiras, IPI e custos de perdas do pátio para formular a venda [Passage 633, 843].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-material-list` [Passage 310]. Uses `lockedgrid` para fixação de identificação do material [Passage 310].
* **Formulários Auxiliares:** `tabela-preco-material-incluir-form` [Passage 325], `tabela-preco-material-alterar-custo-form` [Passage 326], `tabela-preco-material-redefinir-venda-form` [Passage 327].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/materiais/php/response.php` [Passage 328, 330, 333, 334].
* **Métodos:** `incluir_categoria` [Passage 328], `alterar_custo` [Passage 330, 696], `copiar_tabela` [Passage 667].
* **Banco de Dados:**
* **Tabela:** `marmoraria_materiais_precos` [Passage 663, 665, 668].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Como Cadastrar uma Rocha Importada em Moeda Estrangeira:**
* Clique em **Incluir** [Passage 311]. No formulário [Passage 306], selecione o material (Ex: `Mármore Carrara`) [Passage 306].
* Selecione a **Moeda** como `DÓLAR` [Passage 307] e informe o valor bruto cobrado pela distribuidora no campo **Compra (m²)** (Ex: `150.00` USD) [Passage 307].
2. **Configurar Imposto e Markup:**
* Preencha o **IPI** da rocha (Ex: `5.00`%) [Passage 316, 650] and the **Frete** por m² cobrado pela transportadora (Ex: `12.00` BRL) [Passage 303, 316].
* Determine o percentual de **Perda** da chapa (Ex: `15.00`%) [Passage 317] and the target **Lucro** (Ex: `45.00`%) [Passage 317].
* *O MariaDB converterá síncronamente o valor pelo câmbio do dia, somará impostos e margem de corte, registrando o preço final de venda em reais [Passage 650, 652].*
---
### MÓDULO 5: MATÉRIAS PRIMAS -> ACABAMENTOS (`tabela-preco-acabamento-list`)
Mapeia o custo e a venda dos acabamentos que são usinados diretamente nas bordas das chapas brutoras (Ex: boleado simples, bisotê, reto) [Passage 64, 557, 844].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-acabamento-list` [Passage 248].
* **Stores:** Proxy consumindo `m: "acabamentos"` [Passage 268].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/acabamentos/php/response.php` [Passage 251, 263, 269].
* **Banco de Dados:**
* **Tabela:** `marmoraria_materiais_acabamentos_precos` [Passage 626, 630, 633].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Atualizar Tabela de Borda:** Selecione a tabela de preços e a categoria no topo [Passage 249, 250]. Dê um duplo clique na célula do acabamento correspondente (Ex: `Boleado Simples`) [Passage 248].
2. **Operar Custos de Polimento:** Insira o valor cobrado pela hora de polimento (Custo) e o preço a faturar na proposta (Venda) (Ex: Custo: `22.00` / Venda: `55.00` por MLN) [Passage 40]. O sistema usará essa base para somar ao m² da chapa quando o orçamentista desenhar o tampo com esse acabamento [Passage 841].
---
### MÓDULO 6: COMPLEMENTOS (`tabela-preco-complemento-list`)
Este painel gerencia a biblioteca de insumos e suportes acessórios da marmoraria, aplicando de forma síncrona o **cálculo adaptativo de rendimento** por metragem linear ou m² [Passage 41, 125, 844].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-complemento-list` [Passage 268].
* **Configuração de Edição:** `grideditable` com painel de propriedades de largura 550px [Passage 269].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/complementos/php/response.php` [Passage 276, 278].
* **Banco de Dados:**
* **Tabelas:** `marmoraria_complementos` (matriz de complementos) [Passage 650, 651] e `marmoraria_produtos_complementos` (amarração aos produtos) [Passage 652].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Configurar Rendimento de Argamassas/Silicone (m²):**
* Selecione o complemento (Ex: `Cola Silicone PU para Cubas`) [Passage 268].
* Seta o **Tipo de cálculo** para `M²` [Passage 278] e o **Rendimento M²** para `3.00` [Passage 278]. *Isso indica que uma bisnaga de silicone PU atende síncronamente até 3 metros quadrados de peças montadas [Passage 97].*
2. **Configurar Rendimento de Suportes Metálicos (MLN):**
* Para o item `Mão Francesa de Aço` [Passage 270], configure **Tipo de cálculo** como `MLN` [Passage 136, 278] e o **Rendimento MLN** como `0.80` [Passage 136, 278].
* *O motor de cálculo do MariaDB dividirá o metro linear total da pia por 0.80 e arredondará síncronamente para cima, faturando a quantidade exata de suportes para garantir a segurança estrutural sem prejuízo para a fábrica [Passage 43, 50, 136].*
---
### MÓDULO 7: ESTADIAS (`tabela-preco-estadia-list`)
Este módulo gerencia as diárias de viagens, estadias e alimentação cobradas em propostas para montagens em outras cidades [Passage 157, 917]. Ele calcula de forma reativa os custos baseando-se na **metragem da obra contra a capacidade diária de trabalho da equipe (rendimento diário)** [Passage 123, 157].
#### ⚙️ Mapeamento Arquitetural
```
[Ficha Técnica: tabela-preco-estadia-list] (Grid)
│
(onSalvar - AJAX/POST via Form)
│
▼
[API: orcamentos/precos/estadias/php/response.php]
│
▼
[Back-End PHP: Precos.php (consultar)]
│
▼
[Tabela: marmoraria_estadias]
```
##### A. Front-End (Sencha ExtJS v7.3.1)
* **Componente View (Grid):**
* **xtype:** `tabela-preco-estadia-list` [Passage 284].
* **Controller:** `tabela-preco-estadia-list` [Passage 285].
* **ViewModel:** `tabela-preco-estadia-list` [Passage 284].
* **Plugins:** `gridfilters` [Passage 285], `grideditable` (abre folha lateral de edição com largura de 500px) [Passage 285].
* **Estrutura de Colunas:**
* `nome`: Descritivo da despesa de viagem (Ex: diária técnica de colocador, hospedagem) [Passage 285].
* `rendimento_m2`: Rendimento diário de montagem por m² (Mapeia a capacidade média de m² instalados por dia por equipe) [Passage 123, 286].
* `custo` / `custo_minimo`: Preços de custo de viagem e diária do instalador [Passage 286].
* `venda` / `venda_minima`: Preços a faturar no orçamento do cliente [Passage 286, 287].
* `padrao`: Checkbox que indica se a diária entra automática em novos orçamentos [Passage 288].
* `incluso`: Checkbox que define se o custo será omitido e diluído no m² final do tampo [Passage 288].
##### B. API de Comunicação e Backend
* **Endpoint Principal:** `mod/marmoraria/orcamentos/precos/estadias/php/response.php` [Passage 656].
* **Classe PHP:** `Precos` ➔ Método `consultar` (carrega as estadias de retaguarda do Tenant logado) [Passage 655].
* **Importação/Clonagem:** A classe `Importar` em `estadias/php/Importar.php` permite ao administrador do sistema sincronizar tabelas de estadias entre empresas inquilinas com um único clique [Passage 654, 655].
##### C. Persistência de Dados (MariaDB)
* **Tabela Principal:** `marmoraria_estadias` [Passage 654].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Como Cadastrar uma Regra de Diária de Montadores:**
* Acesse **Orçamento > Tabelas de preços > Estadias** [Passage 917].
* Clique em **Incluir** [Passage 287]. Na folha lateral, preencha:
* **Nome:** `Instalação de Bancadas - Viagem Acima de 100km` [Passage 285].
* **Rend. Diário (m²):** Digite `4.00` [Passage 286]. *Isso indica que uma equipe de montadores consegue assentar no máximo 4 m² de tampos por dia.*
* **Custo:** Digite `150.00` (valor pago de hospedagem/alimentação por ajudante por dia) [Passage 286].
* **Custo mín:** Digite `300.00` (garantia mínima de diárias) [Passage 286].
* **Venda:** Clique no ícone de calculadora (`calcVenda`) ao lado [Passage 286]. O sistema abrirá um prompt perguntando a margem de lucro [Passage 277]. Digite `40` (%) [Passage 277]. O ERP calculará de forma automática a venda diária como `R$ 250,00` [Passage 277].
* Clique em **Salvar** [Passage 285].
2. **Como Funciona o Cálculo Automático no Orçamento:**
* Ao desenhar um orçamento de montagem complexa medindo **10 m²** em outra cidade [Passage 157]:
* O orçamentista vincula a diária cadastrada na aba de viagens [Passage 146].
* O motor matemático do Sistrom de forma transparente executa a divisão:
\\[\text{Dias} = \lceil \frac{\text{Total m²}}{\text{Rendimento Diário m²}} \rceil = \lceil \frac{10}{4} \rceil = \lceil 2.5 \rceil = 3 \text{ diárias}\\] [Passage 157]
* Desta forma, o ERP faturará automaticamente 3 diárias completas para o cliente, cobrindo o alojamento e a alimentação dos profissionais durante o tempo total do serviço em campo, sem risco de esquecimento por parte do orçamentista [Passage 137, 157].
---
### MÓDULO 8: FRETES (`tabela-preco-frete-list`)
Este módulo gerencia a precificação logística de transportes de tampos e chapas [Passage 291, 918]. Ele permite cadastrar a frota da empresa e calcular síncronamente o frete com base em **pesagem física (kg), distância rodada (km) e capacidade do veículo** [Passage 148, 290, 861].
#### ⚙️ Mapeamento Arquitetural
```
[Ficha Técnica: tabela-preco-frete-list] (Grid)
│
(onSalvar - AJAX/POST via Form)
│
▼
[API: orcamentos/precos/fretes/php/response.php]
│
▼
[Back-End PHP: Precos.php (consultar)]
│
▼
[Tabela: marmoraria_fretes]
```
##### A. Front-End (Sencha ExtJS v7.3.1)
* **Componente View (Grid):**
* **xtype:** `tabela-preco-frete-list` [Passage 290].
* **Controller:** `tabela-preco-frete-list` [Passage 292].
* **ViewModel:** `tabela-preco-frete-list` [Passage 294].
* **Plugins:** `gridfilters` [Passage 291], `gridcellediting` (edição rápida do valor inline de tabelas de fretes) [Passage 291].
* **Estrutura de Colunas:**
* `veiculo`: Nome/Descrição do veículo (Ex: Carretinha Acabamento, Caminhão Munck) [Passage 294].
* `carga_maxima_kg`: Capacidade máxima de tração e carga em kg [Passage 294].
* `custo_dentro_estado` / `venda_dentro_estado`: Preço do frete dentro do estado inquilino [Passage 294].
* `custo_fora_estado` / `venda_fora_estado`: Preço de faturamento rodoviário para outras unidades federais [Passage 294].
##### B. API de Comunicação e Backend
* **Endpoint Principal:** `mod/marmoraria/orcamentos/precos/fretes/php/response.php` [Passage 293].
* **Classe PHP:** `Precos` ➔ Método `consultar` [Passage 658].
* **Importação:** A classe `Importar` em `fretes/php/Importar.php` duplica os parâmetros da frota em lote de forma síncrona [Passage 656, 658].
##### C. Persistência de Dados (MariaDB)
* **Tabela Principal:** `marmoraria_fretes` [Passage 656, 659].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Como Cadastrar um Veículo da Frota:**
* Acesse **Orçamento > Tabelas de preços > Fretes** [Passage 918].
* Clique em **Incluir** [Passage 291]. Na linha editável exibida [Passage 291]:
* **Veículo:** Digite `Caminhão Iveco Daily` [Passage 294].
* **Carga máxima (kg):** Digite `2500` [Passage 294].
* **Custo dentro do estado:** Digite `150.00` [Passage 294, 316].
* **Venda dentro do estado:** Digite `280.00` [Passage 294].
* **Custo fora do estado:** Digite `250.00` (custo acrescido por despesas de pedágios) [Passage 294].
* **Venda fora do estado:** Digite `450.00` [Passage 294].
* O ERP salvará síncronamente ao clicar fora da célula através do listener `complete: "onSalvar"` [Passage 291].
2. **Como Funciona o Cálculo Logístico Automático no Orçamento:**
* No momento em que o orçamentista monta uma proposta [Passage 33]:
* O sistema soma de forma transparente o peso de todos os tampos de pedras com base em suas espessuras e densidades em kg (Ex: peso total da proposta deu **3.600 kg**) [Passage 148, 530, 841].
* Na aba de **Frete** do orçamento, o usuário clica em **CALCULAR** [Passage 146, 147].
* O MariaDB de forma instantânea executa o laço: como a pesagem física de 3.600 kg excede a capacidade máxima cadastrada para o caminhão Iveco Daily (2.500 kg) [Passage 294]:
* **O sistema sugere reativamente a quantidade de `viagens = 2`**, duplicando síncronamente o preço do frete a faturar no holerite da proposta de forma automatizada [Passage 148].
* O usuário pode definir se o frete será apresentado como uma linha de subtotal separada ou distribuído de forma diluída nas colunas das peças no PDF (`exibir_frete = 1` ou `2`) [Passage 150].
---
### MÓDULO 9: SERVIÇOS INDIRETOS EXTRA (`tabela-preco-servico-indireto-list`)
Controla os serviços extras fornecidos na obra que não envolvem industrialização (Ex: remoção e descarte de tampos antigos, impermeabilização química, içamentos) [Passage 29, 176, 845].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-servico-indireto-list` [Passage 354]. Habilita popup `grideditable` para edição inline do escopo de serviços [Passage 354].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/servicos_indiretos/php/response.php` [Passage 360].
* **Banco de Dados:**
* **Tabela:** `marmoraria_servicos_indiretos` [Passage 681, 683].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Cadastrar Serviço Avulso:** Clique em **Incluir** [Passage 356]. Selecione a categoria (Ex: `Impermeabilização com Vedante de Quartzo`) [Passage 355] and the **Unidade** como `M²` [Passage 355].
2. **Configurar Trava de Custo Mínimo:**
* No campo **Venda**, insira o preço cobrado por metro quadrado (Ex: `45.00` por M²) [Passage 355].
* No campo **Venda mín**, defina a trava de deslocamento mínimo do técnico (Ex: `250.00`) [Passage 355].
* *Se o orçamentista fechar a impermeabilização de um lavabo pequeno de apenas 1,5 M², o ERP desprezará a multiplicação por M² (que daria R\$ 67,50) e aplicará de forma automática e imediata a trava de R\$ 250,00 no orçamento, blindando a empresa de prejuízos de locomoção [Passage 181].*
---
### MÓDULO 10: PRODUTOS INDIRETOS DE REVENDA (`tabela-preco-produto-indireto-list`)
Gerencia as mercadorias acabadas que a marmoraria adquire de terceiros e revende diretamente aos clientes (Ex: cubas de inox, torneiras de luxo, ralos) [Passage 168, 846].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-produto-indireto-list` [Passage 348].
* **Colunas:** `produto` (relação à tabela de revenda) [Passage 348], `custo` [Passage 350], `venda` [Passage 350], `perc_lucro` [Passage 351].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/produtos_indiretos/php/response.php` [Passage 352, 353].
* **Banco de Dados:**
* **Tabela:** `marmoraria_produtos_indiretos` (ou `produtos_diversos` [Passage 859]).
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Como Cadastrar Cuba de Sobrepor:** Clique em **Incluir** [Passage 349]. No autocomplete de produtos de retaguarda, selecione a cuba de inox de revenda [Passage 349].
2. **Configurar Compra e MarkUp:**
* Preencha o preço pago ao fabricante no campo **Custo** (Ex: `120.00` por UN) [Passage 350] and the **Venda** final para o cliente (Ex: `300.00` por UN) [Passage 350, 351].
* O sistema calculará síncronamente a margem de lucro nominal [Passage 351]. No momento da venda, o ERP lançará de forma automática o título no contas a pagar de compra e deduzirá a mercadoria do estoque de revenda na finalização [Passage 841].
---
### MÓDULO 11: SIMULAÇÃO DE PREÇOS EM TEMPO REAL (`tabela-preco-cotacao`)
Este módulo é o **balcão virtual rápido** de vendas do Sistrom ERP [Passage 133, 846]. Ele permite que o vendedor projete em milissegundos orçamentos informais de M² para os clientes na recepção, sem poluir a base de dados de propostas reais de faturamento [Passage 133, 134].
#### ⚙️ Mapeamento Arquitetural
* **Front-End:**
* **xtype:** `tabela-preco-cotacao` [Passage 279].
* **Componentes de Entrada (tbar):** Comboboxes encadeados (`tabela-select` [Passage 279] ➔ `categoria-select` [Passage 280] ➔ `material-select` [Passage 280]).
* **ViewModel:** `ERP.tabelaPreco.cotacao.viewModel` [Passage 283].
* **API & Backend:**
* **Endpoint:** `mod/marmoraria/orcamentos/precos/cotacoes/php/response.php` [Passage 284].
* **Ação:** `listar` [Passage 284].
* **Banco de Dados:** Varre síncronamente e cruza dados das views de moedas e parâmetros tributários [Passage 431, 432].
#### 📘 Manual de Operação: Como Configurar e Operar
1. **Seleção Encadeada de Variáveis:**
* No campo **1º Selecione a Tabela de Preço**, aponte para o perfil desejado (Ex: `CONSTRUTORAS`) [Passage 246, 279].
* No campo **2º Selecione a Categoria**, aponte para o grupo de rochas (Ex: `QUARTZOS IMPORTADOS`) [Passage 246, 280].
* No campo **3º Selecione o Material para cotar**, selecione a rocha cadastrada (Ex: `Quartzito Taj Mahal`) [Passage 280].
2. **Leitura de Resultados (Preço de Prateleira sem Erros):**
* A grade será preenchida de imediato exibindo todos os produtos industrializados associados [Passage 282, 284].
* Localize o item `Bancada de Pia de Banheiro` [Passage 280] e verifique síncronamente: preço final da chapa m² com impostos de faturamento [Passage 280], o custo do corte linear [Passage 281] and the mão de obra do assentador em campo [Passage 281].
* *No campo destacado em azul pastel **PREÇO FINAL**, o sistema exibirá o preço fechado m² da bancada instalada na obra do cliente, permitindo simulações de vendas instantâneas e seguras [Passage 282].*
---
### ⚡ VÍNCULOS TRANSVERSAIS E GATILHOS DO ECOSSISTEMA DE PREÇOS
O motor de **Tabelas de Preços** opera de forma unificada com todo o ecossistema do Sistrom ERP, retroalimentando de forma reativa os estoques e a contabilidade do Tenant:
```
[Reajuste em Materiais Preços] ──► (Trigger AFTER UPDATE) ──► [Recalcula Itens síncronamente]
│
▼
[Atualiza Faturamento no DRE]
```
* **Propagação Reativa de Preços de Chapas em Orçamentos Ativos:**
A precificação de chapas e acabamentos do pátio de matérias-primas interage ativamente com as propostas comerciais abertas [Passage 652].
Sempre que um gestor de compras reajusta o custo de aquisição de um material na tabela matriz (`marmoraria_materiais_precos`) [Passage 652], a trigger do MariaDB **`marmoraria_materiais_precos_tg_af_update`** (AFTER UPDATE) é disparada em nível de banco de dados [Passage 652].
Ela de forma autônoma varre síncronamente todos os itens de orçamentos e propostas em andamento do Tenant que façam uso daquele material (`id_materiais = new.id_materiais`) e que **não estejam marcados como preços fixados** (`fixar_valores_unitarios = 0` / `fixar_material_precos = 0`) [Passage 352, 353, 717] e **recalcula de forma transparente e em tempo real a cascata fiscal do item**, atualizando o contas a receber estimado sem que o vendedor tenha que reabrir ou reescrever a proposta manualmente, blindando a marmoraria de prejuízos causados por volatilidade de câmbio ou de mercado [Passage 652, 734].
---
### 📐 CATEGORIA: ORÇAMENTOS
### VIEWPORT MASTER: PAINEL DE COMANDO (`orcamentos-dashboard`)
O módulo **`orcamentos-dashboard`** é o coração comercial do Sistrom ERP [Passage 263]. Desenvolvido em Sencha ExtJS Modern Toolkit, ele adota uma arquitetura em **Card Layout** para garantir máxima velocidade de navegação, alternando de forma reativa entre visões táticas (DRE, KPIs, funil e gráficos) e as rotinas de engenharia de custos [Passage 263, 265, 852].
---
#### ⚙️ MAPEAMENTO DA ESTRUTURA DO DASHBOARD (CARD LAYOUT)
```
[Viewport Master: orcamentos-dashboard]
│
┌───────────────────┬─────────────────┼───────────────────┬───────────────────┐
▼ (Card 0) ▼ (Card 1) ▼ (Card 2) ▼ (Card 3) ▼ (Card 4)
[Dashboard KPIs] [Grade Geral] [Abas Form] [Relatórios] [Copiloto AI]
(kpis, funil, etc) (orcamentos-list) (orcamentos-form) (orc-relatorios) (orcamentos-gemini)
```
* **Card 0 - Painel de KPIs:** Exibe cards de dados em tempo real (orçamentos ativos, totais em aberto, fechados e taxa de conversão) [Passage 266, 267], juntamente com os componentes de gráficos `card-orcamentos-funilvendas` [Passage 265], `card-orcamentos-topobras` [Passage 35, 265] e `card-orcamentos-orcamentista` [Passage 34, 265].
* **Card 1 - Consulta Geral (`orcamentos-list`):** A grade principal de busca e monitoramento [Passage 118, 265].
* **Card 2 - Mesa de Trabalho (`orcamentos-form`):** O formulário sequencial estruturado em etapas (Index 0 a 9) para a criação do orçamento do zero [Passage 88, 92, 103, 265].
* **Card 3 - Relatórios (`orcamentos-relatorios`):** Central de compilação de PDFs personalizados, por status, materiais ou orçamentistas [Passage 256, 265].
* **Card 4 - Copiloto AI (`orcamentos-gemini`):** Interface de linguagem natural integrada ao banco comercial (Vertex/Gemini SDK) [Passage 25, 26, 266].
---
#### 📘 GUIA COMPLETO: COMO CRIAR UM ORÇAMENTO DO INÍCIO AO FIM
Abaixo está o fluxo operacional detalhado passo a passo, simulando a operação em ambiente real do ERP.
---
### PASSO 1: IDENTIFICAÇÃO BASE E CLASSIFICAÇÃO (INDEX 0, 1, 2)
Na barra superior do dashboard, clique no botão **Novo Orçamento** [Passage 263, 264]. O sistema irá transicionar síncronamente para o Card do Formulário (`orcamentos-form`), iniciando na primeira etapa do Wizard [Passage 88, 265].
##### 1. Dados de Cabeçalho e Origem (Index 0):
* **Cliente/Obra:** No campo autocomplete `id_obras`, comece a digitar o nome da obra do cliente [Passage 360]. O sistema listará as obras em andamento [Passage 432]. Ao selecionar, o ERP preenche de forma automática os endereços e contatos principais cadastrados na retaguarda [Passage 825, 918].
* **Responsáveis de Campo:** Vincule o contato direto no campo `id_obras_contatos` e defina o responsável técnico ou arquiteto em `id_obras_pessoas` [Passage 90, 361].
* **Definição Estética:** O campo `id_titulos` (`orcamento-cadastro-titulo-select`) determina as descrições de subtítulo e os rótulos de apresentação final impressos no PDF comercial [Passage 90, 642, 644].
* **Classificação Tática (Etiqueta):** No checkboxgroup, determine se a proposta é do tipo:
* **Extra:** Orçamento complementar a um pedido já fechado [Passage 91].
* **Concorrência:** Sinaliza que a proposta está sob disputa acirrada de mercado [Passage 91].
* **Cortesia:** Zera de forma síncrona os faturamentos contábeis [Passage 91, 103].
* **Cotação:** Proposta informal de balcão [Passage 92].
* **Moeda de Conversão:** O seletor `conversor_moeda` permite que o orçamentista gere orçamentos em moedas estrangeiras (como Dólar ou Euro), aplicando reativamente a taxa de câmbio informada no campo `conversor_valor` sobre toda a base de cálculo [Passage 110, 241].
##### 2. Projetos e Arquivos (Index 1 & 2):
* Avance clicando em **Próximo** [Passage 237]. A aba de **Contatos** (`orcamentos-contatos-grid`) permite vincular múltiplos e-mails e telefones de faturamento [Passage 92, 113].
* Na aba de **Projetos** (`orcamentos-projetos-grid`), faça o upload ou registre o nome dos arquivos arquitetônicos (desenhos em CAD/PDF) que basearam as medidas das peças, garantindo rastreabilidade técnica [Passage 92, 113, 239].
---
### PASSO 2: ENGENHARIA DE PEÇAS E ITENS (INDEX 3 - `orcamentos-itens`)
A aba **Itens do Orçamento** (`orcamentos-itens`) é o módulo central de precificação do orçamentista [Passage 92]. Ela consiste em um painel dividido horizontalmente com a árvore de itens à esquerda (`itensTree`) e painéis de propriedades à direita [Passage 146, 155, 156].
```
[Aba 3: orcamentos-itens] (Split Panel)
│
┌────────────────────────┴────────────────────────┐
▼ (Esquerda - TreeColumn) ▼ (Direita - Propriedades)
[itensTree (Grade)] [Abas Acopladas]
- Número / Posição (ordem) - Descrição do item (Froala)
- Unidade (M², MLN, UN, PÇ) - Acabamentos do produto (Grid)
- Medidas (Med.1, Med.2, Med.3) - Desconto/Acréscimo no item
```
##### 1. Composição de Itens Tradicional:
1. Clique no botão **Incluir** na barra de ferramentas e insira um **Andar** (Ex: *2º Pavimento*) [Passage 146, 147].
2. Adicione um **Ambiente** (Ex: *Suíte Master*), selecionando a matéria-prima desejada no combobox autocomplete (Ex: *Quartzito Taj Mahal - ESP 2.00cm*) [Passage 147].
3. Com o ambiente selecionado na árvore [Passage 147], clique no botão **Compor** (`itemId: "compor-btn"`) [Passage 198]. O assistente inteligente (`orcamentos-assistente`) será aberto na lateral direita [Passage 205].
4. Selecione o produto de fábrica (Ex: *Tampo com Cuba Esculpida*) [Passage 631]. Preencha os campos geométricos [Passage 149]:
* `medida_1` (Comprimento): `1.80` metros [Passage 149].
* `medida_2` (Largura/Profundidade): `0.60` metros [Passage 149].
5. **A Mágica da Inferência Tridimensional de Peças Especiais:**
Se o produto for classificado em banco sob o tipo de peça **`CUBA`**, **`NICHO`**, **`CAIXA`**, **`COLUNA`** ou **`PISADA`** [Passage 631], o sistema exibe reativamente campos para abas e profundidades [Passage 852]. Ao salvar, o ERP calcula de forma autônoma a somatória m² de todas as faces de colagem da pedra e o peso físico em kg [Passage 852].
6. **Acréscimo de Curvas e Peças Duplas:**
Caso a peça possua design orgânico, ative a chave **Peça Curva** (`tipo_curva`) [Passage 632]. O ExtJS aplicará de forma síncrona o percentual de acréscimo de corte e beneficiamento configurado em `perc_curva` sobre o subtotal da peça [Passage 150, 632].
##### 2. O Recurso de Comando Inteligente (AI Tree Builder):
Para acelerar o preenchimento de propostas extensas, o Sistrom ERP oferece o **Comando Inteligente** [Passage 158]:
1. Clique no botão **Comando** (ícone `x-fa fa-terminal`) [Passage 147].
2. No campo de texto rico, digite em linguagem natural (ou utilize o microfone integrado):
* *“Lavatório de 1,50x0,60 em Branco Prime com saia de 15cm e frontão reto de 10cm”* [Passage 157, 158].
3. Clique em **Confirmar** [Passage 10]. O PHP enviará o texto de forma síncrona ao Vertex AI utilizando o dicionário amigável [Passage 801, 842]. A IA interpreta as medidas, extrai a pedra de registro, calcula a metragem linear de frontões e saias [Passage 843, 844], e devolve a estrutura aninhada montada em formato JSON de volta para a grade ExtJS, populando toda a árvore de itens em 2 segundos [Passage 10, 842].
---
### PASSO 3: RECURSOS AVANÇADOS DA ÁRVORE DE ITENS
O orçamentista sênior possui um conjunto de ações rápidas no submenu **Recursos** da barra de ferramentas [Passage 199]:
##### 1. Redefinição de Custos e Vendas de Balcão:
Ao dar um duplo clique em qualquer item na árvore, a barra lateral de propriedades é desbloqueada [Passage 155]. No entanto, para alterações globais do orçamento ativo, utilize as ações do submenu **Industrialização** [Passage 200]:
* **Material (`redefinir-preco-material`):** Permite alterar de forma síncrona os preços de custo e venda m² de todas as pedras utilizadas naquela proposta de forma unificada [Passage 200, 826].
* **Acabamento (`redefinir-preco-acabamento`):** Redefine em lote as cobranças lineares de beneficiamento [Passage 200].
* **Corte e Instalação (`redefinir-preco-cortemdo`):** Ajusta os preços de serragem e diárias do colocador em lote [Passage 200, 201].
##### 2. Trocar de Material em Lote (`onTrocarMaterial`):
Se o cliente assinar o orçamento mas decidir alterar a cor da rocha (Ex: trocar todos os tampos de *Granito Preto São Gabriel* por *Quartzito Taj Mahal*) [Passage 202]:
* Selecione o material de origem e aponte a nova pedra [Passage 202]. O ERP varre de forma automática a árvore de itens, altera os códigos de matérias-primas e recalcula de forma reativa os preços com base nas alíquotas da nova rocha selecionada, preservando as medidas do projeto [Passage 202].
##### 3. Definir Preço Final com Ajuste Matemático Unitário (`onDefinirPrecoFinal`):
Se o orçamento totalizar R\$ 12.342,80 e a diretoria concordar em fechá-lo em um valor redondo de R\$ 12.000,00 [Passage 221]:
1. Selecione a ação **Definir preço final** [Passage 202]. Digite o valor de `12000.00` [Passage 221].
2. O sistema identificará a diferença e exibirá o prompt [Passage 221, 222]: *"O que deseja fazer com a diferença de R\$ 342,80?"*
3. Selecione a opção **Desconto** ou **Acréscimo** [Passage 222]. O motor matemático em PHP divide síncronamente a diferença e a dilui de forma ponderada e unitária nos preços de vendas de cada item da árvore, evitando distorções contábeis e fiscais para emissão posterior de notas fiscais [Passage 222].
---
### PASSO 4: INSUMOS COMPLEMENTARES E RENDIMENTOS (INDEX 4)
A aba **Complementos** gerencia a injeção de insumos acessórios necessários para a instalação da pedra (Ex: cola PU, grampos de aço, tubos de silicone, argamassas) [Passage 41, 114].
```
[Aba 4: orcamentos-complementos] (HBox)
│
┌───────────────────────────┴───────────────────────────┐
▼ (Esquerda - Grid) ▼ (Direita - TreeGrid)
[Complementos Disponíveis] (Matriz) [Complementos Orçados] (Vínculo)
```
1. O painel esquerdo lista os complementos cadastrados no banco [Passage 41].
2. **Selecione e arraste** o complemento desejado sobre a árvore de itens do orçamento à direita para aplicá-lo ao ambiente [Passage 41, 46].
3. **Cálculo Automático por Fórmula de Rendimento:**
O sistema realiza o cálculo com base no rendimento parametrizado na tabela mestre [Passage 80, 81]:
* **Se Tipo de Cálculo for `MLN` (Ex: Mão Francesa):** Divide o comprimento total das pias pelo rendimento e arredonda para cima (`Math.ceil`) para garantir faturamento de peças inteiras [Passage 81]:
\\[\text{Quantidade} = \lceil \frac{\text{Total Linear}}{\text{Rendimento MLN}} \rceil\\] [Passage 80, 81]
* **Se Tipo de Cálculo for `M²` (Ex: Argamassa/Cola):** Aplica a fórmula sobre a cubagem quadrada total das pedras, faturando embalagens ou bisnagas cheias de forma reativa e transparente [Passage 80, 81].
---
### PASSO 5: LOGÍSTICA E DESLOCAMENTOS - VIAGENS E FRETES (INDEX 5)
Esta aba é dividida em dois painéis paralelos de controle logístico de fretes [Passage 92]:
##### 1. Diárias e Hospedagens de Colocadores (`orcamentos-estadias`):
* O painel esquerdo gerencia as estadias de viagens [Passage 92].
* Ao vincular uma diária de montadores, o sistema analisa de forma síncrona o m² total dos tampos em orçamento e divide pela capacidade média diária de instalação da equipe (campo `rendimento_m2` da estadia) [Passage 82, 115]:
\\[\text{Dias Previstos} = \lceil \frac{\text{Metragem Total m²}}{\text{Rendimento Diário m²}} \rceil\\] [Passage 82, 115]
* Exemplo: Se o orçamento totaliza 10 m² e o rendimento diário da dupla de montadores é de 4 m², o sistema calcula síncronamente a necessidade de **3 dias de hospedagens e diárias completas**, blindando a marmoraria contra prejuízos causados por prolongamento de estadias [Passage 82, 115].
##### 2. Dimensionamento e Pesagem do Frete:
O painel de **Frete** à direita é um componente estendido que realiza cálculo preventivo [Passage 92]:
1. **Pesar Material do Cliente:** Deixe marcado para habilitar o motor físico [Passage 93].
2. O ViewModel soma dinamicamente o peso em kg de todas as bancadas e tampos configurados no orçamento com base nas espessuras e densidades das rochas, exibindo o resultado em tempo real no campo **TOTAL KG** [Passage 94, 112].
3. No combobox **Veículo** (`id_fretes`), selecione o transporte correspondente (Ex: *Caminhão Iveco Daily - Cap. Máxima 2.500 kg*) [Passage 94, 478].
4. Clique no botão **CALCULAR** [Passage 93, 108]. Se o peso total do orçamento (Ex: 3.600 kg) exceder a capacidade máxima do Iveco, **o ERP altera reativamente e de forma síncrona a quantidade para `2 Viagens`**, dobrando o custo e venda do frete para cobrir o frete extra de forma automática [Passage 73, 94].
---
### PASSO 6: ANOTAÇÕES, PROJEÇÕES E MARGENS COMERCIAIS (INDEX 6, 7, 8)
##### 1. Cláusulas e Observações (Index 6):
* Na aba de **Observações**, clique em **Padrão** para carregar do banco de dados as regras contratuais corporativas padrão do Tenant (como prazos de entrega e condições técnicas de canteiro) [Passage 96, 233].
* Você pode usar a grid de observações disponíveis à esquerda para selecionar cláusulas específicas e adicioná-las diretamente no editor de rich text **Froala** [Passage 231, 232, 233].
##### 2. Auditoria e Revisão de Custos (Index 7):
* A aba **Revisão** apresenta o componente contábil **`orcamentos-custos`** [Passage 56, 96].
* Ele exibe grades agrupadas e editáveis para todos os insumos e etapas: *Materiais, Produtos, Acabamentos e Omissos* [Passage 56, 61, 65, 66].
* O orçamentista sênior pode reajustar custos e vendas diretamente nas células de forma síncrona [Passage 57, 59, 63]. Se desejar blindar o markup de oscilações cambiais ou alterações de tabelas matrizes de preços, marque a caixa de verificação **Fixar Preço** (`fixar_material_venda`), definindo que o sistema respeitará o valor digitado de forma imutável [Passage 60, 61].
##### 3. Mesa de Fechamento de Markup (Index 8):
* Exibe o consolidado financeiro do orçamento confrontando Custo Total, Venda Líquida e o Lucro Estimado em dinheiro e percentual [Passage 96, 97].
* **Painel Accordion à Direita (`Impostos, RTs, Descontos...`):**
* **Impostos:** Customize as alíquotas fiscais incidentes (Material, MDO e Beneficiamento) de forma síncrona para esta proposta específica [Passage 98].
* **Reserva Técnica (RT):** Defina as comissões pagas para os especificadores da obra (arquiteto parceiro), podendo parametrizar percentuais diferenciados sobre Material, Beneficiamento e MDO [Passage 99, 100].
* **Abatimentos e Acréscimos:** O campo de **Crédito** permite utilizar saldos acumulados de clientes [Passage 101]. Os triggers dos campos de Desconto e Acréscimo chamam o utilitário de calculadora (`onCalcDesconto`) para faturar descontos percentuais e preencher o valor líquido nominal [Passage 101, 102].
---
### PASSO 7: CONDIÇÕES DE PAGAMENTOS E ENCAMINHAMENTO (INDEX 9)
O último passo do Wizard gerencia a distribuição das faturas de entrada no caixa da marmoraria [Passage 103]:
1. A grid editável **`orcamentos-condicoes`** permite que o orçamentista parcele síncronamente os pagamentos [Passage 103, 117].
2. Clique em **Parcelar/Condições de pagamentos** para abrir o assistente em lote [Passage 47, 501].
3. Preencha as percentagens e datas estimadas (Ex: 50% de entrada via PIX e 50% em 30 dias no boleto bancário) [Passage 47, 48].
4. O ViewModel valida de forma síncrona e em tempo real se a soma das parcelas atinge o valor total de venda do orçamento (`saldoRestante === 0`), impedindo a gravação com inconsistências de centavos [Passage 49, 117, 343].
---
#### ⚡ RECURSOS EXCLUSIVOS DO GRID GERAL (`orcamentos-list`)
Com o orçamento salvo, você retorna à grade de monitoramento (`orcamentos-list`) [Passage 118, 133]. Ela dispõe de submenus e ações de lote de alta performance:
```
[Orçamento Selecionado no Grid]
│
├─► [Alterar] ──► Copiar (Gera clone síncrono com novas chaves) [Passage 119, 137]
│ ──► Revisar (Gera versão de escopo ligada ao pai) [Passage 119, 137]
│ ──► Opção (Cria alternativa de material e preço) [Passage 119, 137]
│
├─► [Sinalizar] ──► Muda Status para: ORÇANDO / ENVIADO / CONCORRÊNCIA [Passage 121, 122]
│ *(Move automaticamente o card no Kanban do CRM)* [Passage 853]
│
└─► [Fechar] ──► Executa rotina contábil, cria títulos no contas a receber, [Passage 123]
gera a Ordem de Corte e dispara checklists da fábrica [Passage 852, 853].
```
1. **Mecanismo de Versões e Escopos (Alterar):**
* **Copiar:** Duplica o orçamento síncronamente para outra obra ou cliente, herdando em lote toda a árvore de itens, complementos, fretes e regras comerciais [Passage 119, 137].
* **Revisar:** Cria uma revisão sequencial do orçamento (Ex: *ORÇAMENTO #1045 - REV 1*). O sistema marca o registro original como substituído de forma autônoma [Passage 119, 122].
* **Opção:** Cria uma alternativa de precificação para o mesmo projeto (Ex: Opção 1 em Granito e Opção 2 em Quartzito), facilitando a escolha para o cliente final [Passage 119, 137].
2. **Impressão Inteligente (PDFs):**
O menu **Imprimir** permite exportar vias diferenciadas baseadas nas configurações do orçamento [Passage 120, 413]:
* *Catálogo:* PDF unificando as imagens conceituais associadas aos ambientes [Passage 120].
* *Comparativo:* Gera síncronamente um relatório cruzando duas opções ou revisões da mesma obra para demonstrar as variações de custos para o cliente [Passage 120].
* *Via de Produção:* Exporta o PDF técnico omitindo de forma síncrona preços e dados financeiros de vendas, enviando estritamente as medidas tridimensionais das peças para as serras e acabadores da fábrica [Passage 15, 413].
* *Resumo de Custo:* PDF analítico exclusivo da diretoria detalhando custos de pedras brutoras, mão de obra de corte, comissões de RT e a margem real líquida de lucro da proposta [Passage 121, 413].
---
## CATEGORIA: ORÇAMENTOS
### MÓDULO CRÍTICO: CONVERSAS SOBRE ORÇAMENTOS E PEDIDOS (`orcamentos-mensagens`)
O módulo **`orcamentos-mensagens`** é o hub de comunicação e atendimento reativo integrado diretamente às propostas comerciais e pedidos de vendas do Sistrom ERP [Passage 32, 921-922]. Diferente de um sistema de mensagens genérico ou de chats isolados, ele funciona como uma central unificada que vincula síncronamente as conversas da equipe comercial e os contatos de clientes às suas respectivas entidades de faturamento (Orçamentos ou Pedidos) [Passage 32, 922].
Ele conta com um motor inteligente de gatilhos automáticos para menções, criação descentralizada de subtópicos, importação em lote de históricos do WhatsApp e auditoria de leitura e visualização de arquivos [Passage 34, 47, 59].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE DADOS
```
[Interface: orcamentos-mensagens]
│
┌──────────────────────┴──────────────────────┐
▼ (Lado Esquerdo - Master) ▼ (Lado Direito - Detail)
[assuntosGrid] [msgPanel] (Card Layout)
(Store: assuntos PHP) ┌───────────┼───────────┐
│ ▼ ▼ ▼
│ [Discussão] [Visualizações] [Participantes]
│ (msgList) (lidas store) (usuariosGrid)
▼ (onSelecionar) │ │ │
Carrega mensagens e ativa ──► checarMensagens│ │ │
temporizador síncrono (5s) (Poller) ▼ ▼ ▼
│ [mod/marmoraria/orcamentos/mensagens/php/response.php]
▼ │
[Gatilhos Especiais] ▼
- # -> onHashtag (Novo Canal) [Back-End PHP: Mensagens.php]
- @ -> mentionPicker (Adiciona User) │
│ ▼
└────────────────────────► Persiste em: [Tabelas MariaDB]
(marmoraria_orcamentos_mensagens...)
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **Componente Viewport Principal (Master-Detail):**
* **xtype:** `orcamentos-mensagens` [Passage 32].
* **Configuração de Inicialização:** `pedidos: false` [Passage 32]. O método `updatePedidos` monitora esta flag para alternar dinamicamente o comportamento e os parâmetros extras do Ajax entre propostas comerciais (`pedidos: false` ➔ "Conversas sobre Orçamentos") e contratos fechados (`pedidos: true` ➔ "Conversas sobre Pedidos de Vendas") [Passage 32, 40, 41, 921-922].
* **Painel de Assuntos (Esquerda - Master):**
* **reference:** `assuntosGrid` [Passage 43] | **Store:** `{assuntos}` [Passage 43].
* *Colunas de Resumo:* Título do Orçamento/Pedido (`titulo`), Assunto Principal (`assunto`), Data e Hora do Último Contato (`ultima_mensagem_em`), e Totalizador de mensagens do canal (`conversas`) [Passage 33, 34].
* *Ações da Toolbar:* Novo Assunto (`onIncluir` [Passage 33, 43]) e Excluir Canal (`onExcluir` [Passage 33, 45]).
* **Painel de Mensagens e Discussões (Direita - Detail):**
* **reference:** `msgPanel` [Passage 34] | **Layout:** `card` com transição do tipo slide [Passage 34].
* **Card 0 - Discussão (Fila do Chat):**
* **reference:** `msgList` [Passage 34] | **Store:** `{mensagens}` [Passage 35].
* **itemTpl (Speech Bubbles):** Renderiza dinamicamente as classes de balões estilo cyber [Passage 37]: `speechbubble my` se for mensagem própria do usuário logado (`eu === true` [Passage 37, 72]) ou `speechbubble them` para mensagens de terceiros [Passage 37]. Exibe sinalizadores de Favorito (estrela dourada) and Notificado (sino azul) se ativos na tabela de leitura de retaguarda [Passage 37, 275].
* **Plugin Swiper de Gestos (`listswiper`):**
* *Arraste p/ Esquerda:* Responder à mensagem selecionada (`onResponderMensagem` [Passage 37]), Favoritar/Desfavoritar (`onFavoritarMensagem` [Passage 37, 38]), Chamar no WhatsApp (`onCommitWhatsApp` [Passage 38]), ou Enviar E-mail (`onCommitEmail` [Passage 38]).
* *Arraste p/ Direita:* Notificar Equipe via sistema (`onNotificarMensagem` [Passage 38]), Ver Mensagem Pai (`onVerMensagem` [Passage 38, 59]), e Auditar Visualizações (`onVerMensagemLida` [Passage 38, 59]).
* **Card 1 - Visualizações:** Exibe a grade de usuários que leram a mensagem selecionada (`lidas` store, baseada no campo `lida_em`) [Passage 59, 73].
* **Card 2 - Participantes:** Grade `usuariosGrid` para gerenciar os participantes vinculados síncronamente ao canal de discussões [Passage 39, 40].
* **Barra de Digitação e Uploads (bbar do Card de Mensagens):**
* **reference:** `mensagem` (textareafield [Passage 35]) | Atalho: Ctrl + Enter dispara síncronamente `onEnviarMensagem` [Passage 36, 55].
* **Botão Enviar:** Chama `onEnviarMensagem` [Passage 36, 55].
* **Menu de Anexos (Paperclip):**
* *E-mail:* Upload de arquivos `.eml` ou `.msg` [Passage 36].
* *Documento / Imagem / Vídeo / Áudio:* Filtra síncronamente por MIME types utilizando o gravador e câmera do dispositivo [Passage 36, 37].
##### B. API de Comunicação (response.php)
* **Endpoint Unificado:** `mod/marmoraria/orcamentos/mensagens/php/response.php` [Passage 32, 646].
* **Poller de Atualização em Tempo Real (`checar_mensagens`):**
A arquitetura front-end implementa um mecanismo de polling ativo para evitar atrasos na mesa de vendas [Passage 46, 47]. No momento em que um assunto é selecionado (`onSelecionar` [Passage 42]), o controller limpa os processos anteriores e dispara `checarMensagens()`, o qual consulta o banco a cada 5 segundos (`Ext.defer` [Passage 42, 47]) em busca de novos registros [Passage 46, 47].
##### C. Back-End (Classes PHP v7.1.33)
* **Classe de Negócio:** `Mensagens` (arquivo: `app/mod/marmoraria/orcamentos/mensagens/php/Mensagens.php`) [Passage 616].
* **Processador e Formatador de Tags (`_formatar_mencoes_e_topicos`):**
Ao receber uma mensagem via POST, o PHP executa uma varredura para higienizar e enriquecer o texto antes de persistir [Passage 624, 643]:
1. *Mapeamento de Menções (@Usuário):* Varre a view de funcionários ativos do Tenant (`view_usuarios_empresas`) ordenada pelo tamanho do nome decrescente (evitando falsos positivos em nomes compostos) [Passage 644]. Se identificar um `@Nome`, converte síncronamente a string em marcação HTML forte e itálica (`@Nome`) [Passage 645].
2. *Mapeamento de Canais (#Assunto):* Varre as discussões do orçamento (`marmoraria_orcamentos_mensagens`) [Passage 645]. Se encontrar um `#ASSUNTO`, formata em negrito (`#ASSUNTO`), permitindo cliques de redirecionamento no front-end [Passage 645].
* **Mecanismo de Linkagem Dinâmica (`AutoEmbed`):**
O método `enviar_mensagem()` instancia síncronamente a classe `AutoEmbed` [Passage 625]. Se o texto contiver links de internet, o PHP recupera a URL, desliga scripts nocivos e insere de forma automática um card HTML de visualização do site dentro do corpo do chat [Passage 625].
* **Parser de WhatsApp (`importar_whatsapp`):**
O método descompacta o arquivo ZIP enviado pelo usuário no servidor [Passage 637]. O helper oficial `WhatsApp` varre o arquivo TXT síncronamente executando as seguintes ações integradas [Passage 574, 575]:
1. *Varre Linha por Linha:* Identifica data, hora, nome do usuário de origem e a mensagem correspondente [Passage 574, 886].
2. *Busca Amigável de Telefones:* Consome `pegar_id_usuario_por_nome_whatsapp()` para cruzar o nome do WhatsApp com a tabela física de cadastros do RH (`usuarios_whatsapp`), encontrando o ID real do usuário no sistema [Passage 571, 574].
3. *Blindagem contra Duplicados (SHA2):* Gera uma hash SHA2 em nível de banco de dados (`SHA2(data + hora + mensagem, 256)`) [Passage 574]. Se a hash já existir na tabela histórica de conversas, o loop ignora o registro, evitando redundância [Passage 574].
4. *Salvamento de Mídias:* Move de forma automática fotos, vídeos e áudios gravados no ZIP para a pasta física `/obras/conversas/[id_orc]/whatsapp/`, gravando as tags HTML correspondentes de forma transparente [Passage 576, 577, 637].
##### D. Persistência de Dados (MariaDB 5.6.36)
* `marmoraria_orcamentos_mensagens`: Cabeçalho dos canais de discussões dos orçamentos (id, id_orcamentos, id_usuarios, assunto, criado_em) [Passage 896].
* `marmoraria_orcamentos_mensagens_conversas`: Armazena o prontuário histórico das mensagens enviadas [Passage 897].
* **Trigger `marmoraria_orcamentos_mensagens_conversas_tg_bf_insert` (BEFORE INSERT):**
Calcula de forma automática a hash SHA2 do corpo da mensagem se a coluna `codigo` for enviada nula, assegurando a blindagem de importação em lote [Passage 904].
* `marmoraria_orcamentos_mensagens_conversas_lidas`: Gerencia se a mensagem foi curtida/favoritada, lida (`lida_em`) ou se possui agendamento de notificação via sistema para data futura (`notificar_em`) [Passage 898].
* `marmoraria_orcamentos_mensagens_usuarios`: Tabela física n:n de participantes [Passage 900].
* **Visão de Banco Integrada (`view_marmoraria_orcamentos_mensagens`):**
Esta view do MariaDB unifica as conversas do Tenant aplicando o filtro restritivo de multi-tenant e alçada de segurança do participante [Passage 905]:
```sql
CREATE OR REPLACE VIEW view_marmoraria_orcamentos_mensagens_{id_empresas} AS
SELECT t1.*, t2.id_obras, t2.id_empresas,
IFNULL(t5.conversas, 0) AS conversas,
IFNULL(t5.ultima_mensagem_em, t1.criado_em) AS ultima_mensagem_em,
t6.usuarios_list_id
FROM marmoraria_orcamentos_mensagens AS t1
INNER JOIN marmoraria_orcamentos AS t2 ON t2.id = t1.id_orcamentos
LEFT JOIN view_marmoraria_orcamentos_mensagens_resumo_{id_empresas} AS t5 ON t5.id_mensagens = t1.id
WHERE t2.id_empresas = {id_empresas}
AND (t6.usuarios_list_id REGEXP '((^[[:<:]]".$this->usuario->id."$)...');
``` [Passage 905, 906, 907]
---
#### 📘 GUIA DE OPERAÇÃO (MANUAL DO USUÁRIO SÊNIOR)
##### Objetivo do Módulo
Centralizar o fluxo de tratativas, envios de arquivos e discussões técnicas de cada orçamento ou pedido em um único ambiente auditável, eliminando conversas perdidas e permitindo o reuso de históricos do WhatsApp e notificações de prazos táticos para o time de vendas [Passage 27, 34, 43, 624, 625].
##### Operações Passo a Passo
##### 1. Iniciar uma Nova Conversa/Canal
1. Acesse o menu **Orçamentos > Conversas** [Passage 921-922].
2. O ERP abrirá a grade contendo a listagem de assuntos ativos do seu setor [Passage 33].
3. Clique em **Iniciar** (ícone `x-fa fa-comment-dots`) na toolbar esquerda [Passage 32, 33].
4. O pop-up do formulário ExtJS solicitará [Passage 43]:
* **Orçamento / Pedido:** Comece a digitar o número da proposta ou nome do cliente e selecione no dropdown select [Passage 43, 79].
* **Assunto:** Digite o tema da conversa (Ex: `ALTERAÇÃO DO PERFIL DE BORDA DA ILHA`) [Passage 43].
5. Clique em **Confirmar**. O MariaDB gravará síncronamente em `marmoraria_orcamentos_mensagens` [Passage 44, 896] e criará de imediato a folha de chat vazia na tela [Passage 44, 45].
##### 2. O Atalho Rápido para Novo Canal (Gatilho Hashtag `#`)
Para criar um novo tópico sem sair da caixa de texto ativa:
1. Com o chat de um orçamento aberto [Passage 35], vá na área de digitação inferior.
2. Digite `#` [Passage 47].
3. O sistema abrirá de forma instantânea a caixa de diálogo: *"Informe o assunto do novo canal para este Orçamento/Pedido:"* [Passage 48].
4. Digite o nome do assunto em letras minúsculas (Ex: `medicao tecnica`) [Passage 48].
5. Pressione **Confirmar**. O ERP converterá de forma automática a string para maiúsculas (`MEDICAO TECNICA`) [Passage 48, 49], inserirá o novo canal como um nó na árvore lateral [Passage 49, 50] e substituirá o `#` no seu texto ativo por um link em negrito do canal [Passage 50, 593].
##### 3. Mencionar um Colega e Adicionar Participantes (Gatilho Arroba `@`)
Para chamar a atenção de um desenhista ou medidor sobre um detalhe do orçamento:
1. No campo de mensagem, digite `@` [Passage 47].
2. O sistema abrirá a lista flutuante `mentionPicker` trazendo os usuários cadastrados [Passage 51]. Comece a digitar o nome do colega (Ex: `Marcos Silva`) e selecione-o [Passage 51, 52].
3. Se Marcos Silva não for participante do canal do orçamento, o ERP exibirá de forma inteligente o prompt na tela [Passage 53]: *"O usuário mencionado Marcos Silva não se encontra na lista de participantes. Deseja incluir o usuário mencionado como participante dessa conversa?"*
4. Clique em **Sim** [Passage 53]. Marcos é inserido síncronamente em `marmoraria_orcamentos_mensagens_usuarios` [Passage 65] e o sistema carimba o log histórico síncrono em tela [Passage 572]: `@MARCOS SILVA, AGORA FAZ PARTE DESTA CONVERSA`.
##### 4. Importar Conversa Compactada do WhatsApp (Histórico Físico)
Caso tenha combinado os detalhes do fechamento da pedra com o arquiteto via WhatsApp e precise documentar no ERP:
1. No seu smartphone ou computador, abra a conversa com o cliente no WhatsApp, clique em *Mais > Exportar conversa* e selecione a opção **Anexar mídias** para gerar o arquivo `.zip`.
2. Acesse o chat do orçamento correspondente no Sistrom ERP [Passage 123].
3. Na barra superior da Discussão, clique em **Importar** (ícone WhatsApp verde) [Passage 34].
4. Selecione o arquivo ZIP e clique em **Confirmar** [Passage 68, 69].
5. O backend PHP processará síncronamente a descompactação em lote [Passage 69]: ele interpretará o TXT, cruzará os números de telefone para associar a autoria real aos usuários do ERP [Passage 571, 574], salvará as mídias (fotos de cubas, desenhos, áudios) e injetará todo o histórico de conversação formatado dentro da linha do tempo do orçamento, auditável síncronamente pela diretoria [Passage 346-347, 576, 577, 637].
##### 5. Agendar Notificação de Mensagem (Acompanhamento Tático)
Se um medidor enviou uma foto do canteiro indicando que a parede está úmida e você precisa cobrar o cliente na próxima semana:
1. Localize o balão da mensagem contendo a foto no chat [Passage 37].
2. Arraste o balão da mensagem para a **Direita** e clique em **Notificação** (ícone do sino) [Passage 38, 61].
3. O ERP abrirá o assistente de alertas [Passage 62]. Configure:
* **Data de Notificação:** Defina o vencimento do alerta (Ex: `20/08/2026`) [Passage 569, 633].
* **Notificar em quantos dias?** Informe o prazo de antecedência [Passage 569, 633].
4. Confirme. O sistema gravará síncronamente as variáveis na tabela `conversas_lidas` [Passage 569, 633]. Ao atingir a data, o sistema disparará de forma autônoma um alerta visual no painel do orçamentista e enviará um e-mail de notificação de pendência, evitando falhas de pós-vendas [Passage 531, 569, 633].
---
### ⚡ VÍNCULOS TRANSVERSAIS E GATILHOS DO ECOSSISTEMA
O módulo de **Conversas sobre Orçamentos** (`orcamentos-mensagens`) opera como um motor transacional altamente integrado síncrono do Sistrom ERP:
* **Relação síncrona com o Fluxo de Caixa e Cobrança:**
No instante em que o operador financeiro realiza o recebimento parcial de uma fatura de cliente ou dá baixa de um título do contas a receber vencido em `view_contas_receber` [Passage 846]: se a parcela for marcada pelo usuário como recebida em atraso ou inadimplente [Passage 849], as triggers de banco consultam de forma ativa se o pedido correspondente possui um canal de discussões aberto [Passage 562]. Caso possua, o sistema insere síncronamente um log histórico no prontuário de mensagens da obra: `PAGAMENTO DA PARCELA X CONFIRMADO NO VALOR DE R$ Y`, permitindo que o vendedor audite o status de crédito do cliente no ato da conversa sem ter que abrir o financeiro [Passage 562].
* **Notificação de Inatividade do Menu de Notificações:**
Se no módulo de **Configurações do Orçamento** (`orcamento-configuracoes`) o gerente comercial estipulou que propostas em aberto não podem ficar paradas por mais de `15 dias` (`dias_sem_mexer_orcamento = 15`) [Passage 10, 860], o robô de retaguarda do MariaDB executa uma varredura diária de inatividade [Passage 860].
Se encontrar orçamentos sem novas interações no chat de mensagens há mais de 15 dias [Passage 860], ele gera de forma autônoma uma linha de alerta em `list-notificacoes` (Notificações) para o orçamentista responsável com o link dinâmico: `"Existe 1 Orçamento que está há mais de 15 dias sem sua interação."` ao clicar, o sistema direciona o usuário síncronamente de volta ao chat para reaquecimento da venda [Passage 533, 860, 861].
---
## CATEGORIA: PRODUÇÃO
A categoria de **Produção** (Chão de Fábrica e Logística) do Sistrom ERP é o motor industrial que transforma matérias-primas brutas (blocos e chapas) em peças acabadas de alta especificação técnica (pias esculpidas, tampos, nichos e escadas) e gerencia sua entrega e montagem final na obra [Passage 610, 740, 741].
Abaixo está o mapeamento detalhado de toda a esteira produtiva do ERP, detalhando a arquitetura síncrona MVVM, fluxos de persistência no MariaDB, controllers em PHP e manuais táticos de operação [Passage 48, 186, 215, 221, 779].
---
### ⚙️ ECOSSISTEMA GERAL DE PRODUÇÃO (CHÃO DE FÁBRICA)
O fluxo operacional e de dados corre de forma síncrona e encadeada através de triggers e procedures no banco de dados [Passage 740, 861, 866]:
```
[Orçamento Fechado] ➔ [Pedido de Venda] ➔ [Gerar Ordem de Corte] (Reserva Matéria-Prima)
│
▼
[Montar Plano de Corte] (Aproveitamento CNC) ➔ [Kanban de Produção] (Serrador / Acabador)
│
▼
[Registrar Romaneio] (Logística/Pesagem/Frota) ➔ [Checklist de Qualidade / QR Code]
│
▼
[Instalação na Obra] (Apontamento de Campo) ➔ [Fechamento / Repasse Financeiro (RH)]
```
---
### MÓDULO 1: PAINEL COMERCIAL E TELEMETRIA DA FÁBRICA (`producao-dashboard`)
Este módulo atua como a torre de controle da diretoria industrial da marmoraria, confrontando o cronograma de faturamento, prazos de execução físicos e gargalos de desperdício em tempo real [Passage 221, 224, 232].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE DADOS
```
[Viewport Panel: producao-dashboard] (Card Layout)
│
┌────────────────────────────────┼────────────────────────────────┐
▼ (Index 0) ▼ (Index 1) ▼ (Index 2)
[Dashboard KPIs] [producao-relatorios] [producao-gemini]
- cardProducao (Obras Ativas) (Personalizados / PDFs) (Copiloto AI)
- cardProduzir (A Cortar)
- Grid: obraList
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **Componente Viewport Principal:**
* **xtype:** `producao-dashboard` [Passage 221].
* **Layout:** `card` com efeito visual slide de transição lateral [Passage 221].
* **Abas de Toolbar Superior (tbar):** Alterna síncronamente o index ativo do painel mestre entre: *Dashboard (0)* [Passage 222], *Relatórios (1)* [Passage 222], *Copilot IA (2)* [Passage 222], e *Obras (3 - `obrasfechadas`)* [Passage 222, 238].
* **Cartões de KPIs Reativos (Index 0):**
* `cardProducao`: Exibe "Obras em Produção" (`em_producao` do JSON de retaguarda) [Passage 223, 239].
* `cardProduzir`: Exibe "A produzir" (O.C.s aguardando liberação técnica) [Passage 223, 239].
* `cardProduzido`: Exibe m² finalizados [Passage 239].
* `cardEficiencia`: "Eficiência de Produção" (Média de dias gastos por m² faturado) [Passage 224].
* **Componentes de Gráficos de Telemetria:**
* `card-producao-centrocusto`: Gráfico do tipo Radar Polar (`polar`) exibindo as despesas reais vs estimadas por obra síncronamente [Passage 1, 2].
* `card-producao-excedentes`: Gráfico de dispersão medindo sobras e descartes de chapas por canteiro de obras [Passage 3, 5].
* `card-producao-mensal`: Gráfico cartesiano de barras (`cartesian` / `bar`) cruzando m² aprovados, pendentes e reposições nos últimos 12 meses [Passage 6, 7].
* `card-producao-top-reposicao-materiais`: Gráfico de barras horizontal demonstrando quais pedras geram mais retrabalhos (quebras no corte) [Passage 10, 11, 12].
* **Grade Geral de Acompanhamento de Obras (`obraList`):**
* Exibe as obras fechadas correlacionando o progresso físico de fábrica contra o progresso de recebimento financeiro [Passage 224, 231].
* Utiliza colunas ricas de progresso (`widgetcell` com `xtype: "progress"`) alimentadas por fórmulas síncronas do ViewModel para renderizar de forma reativa a cor da célula com base nas etapas concluídas [Passage 113-114, 227-230]:
* `cyber-disabled-cell` (Cinza): Aguardando início [Passage 113, 120].
* `cyber-critical-cell` (Roxo/Magenta): Andamento parcial [Passage 114, 121].
* `cyber-warning-cell` (Amarelo): 100% Produzido (Chapas prontas no cavalete aguardando transporte) [Passage 113, 121].
* `cyber-payment-cell` (Azul): 100% Entregue síncronamente via Romaneio na obra [Passage 113, 120].
* `cyber-success-cell` (Verde): 100% Instalado e com Termo de Aceite assinado pelo cliente [Passage 113, 120].
* **Mapeamento MVVM (ViewModel):**
* **ViewModel:** `ERP.producao.dashboard.viewModel` (alias: `viewmodel.producao-dashboard`) [Passage 240].
* **Stores principais:** `{obrasFechadas}` (Proxy Ajax apontando para `obras_fechadas` [Passage 241, 243]), `{prazosExecucoes}` [Passage 244] e `{obrasExcedentes}` [Passage 240].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/php/Dashboard.php` [Passage 780]
* **Método `kpis()`:** Varre síncronamente no MariaDB a somatória total das ordens de cortes ativas da empresa e de recebimentos do caixa corporativo para alimentar os KPI Cards de cabeçalho [Passage 239].
---
### MÓDULO 2: GERENCIAMENTO DE ORDENS DE CORTES (`producao-ordenscortes-grid`)
Este módulo é a mesa de trabalho de engenharia de produção, onde os desenhos técnicos em CAD são convertidos síncronamente em Ordens de Cortes (O.C.s) detalhadas para as serras [Passage 171, 740, 741].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE DADOS
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-ordenscortes-grid` [Passage 169].
* **Plugins:** `summaryrow` (Soma o m² e KG total enviado para corte [Passage 174, 175]), `gridfilters` [Passage 169] e `listpaging` [Passage 169].
* **Ações e Submenus Técnicos:**
* `Aprovação` (Split Button): Abre o submenu contendo **Aprovar** e **Recusar** [Passage 169, 170]. Ao acionar aprovação, o ViewController dispara `onAprovar` [Passage 170]. O sistema exibe o prompt ExtJS de "Previsão de Entrega" [Passage 181], valida se o usuário possui alçada (`permissao("aprovar_ordem_corte")` [Passage 181]) e envia o POST AJAX alterando o status [Passage 181].
* `Execução`: Abre o menu contendo **Produzir** (`onRetomar`), **Suspender** (`onSuspender`), e **Finalizar** (`onFinalizar` [Passage 170]).
* `Imprimir` (Split Button): Permite gerar os PDFs de **Etiquetas** de segurança para colagem nas peças ou os **Desenhos das peças** agrupados por ambiente para os serradores da fábrica [Passage 171].
* `QRCode` (`onGerarQRCode`): Gera e compila síncronamente o token numérico da Ordem de Corte em uma imagem PNG para impressão e rastreio de pátio [Passage 126, 127].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/ordens_cortes/php/response.php` [Passage 779, 780].
* **Classe PHP:** `OrdensCortes` [Passage 779-780]
* **Ações Processadas (`m`):** `consultar` [Passage 185], `aprovar` [Passage 181], `incluir_item` [Passage 144], `excluir_item` [Passage 166], `duplicar_item` [Passage 166] e `gerar_desenho` [Passage 182].
##### C. Persistência de Dados (MariaDB)
* **Tabela de Ordens de Cortes:** `marmoraria_ordens_cortes` [Passage 746, 849]
* *Campos:* `id`, `id_empresas` (Tenant), `id_pedidos` (FK), `id_areas` [Passage 849], `status_execucao` (ENUM: `'PARADO'`, `'EM PRODUÇÃO'`, `'FINALIZADO'`), `status_aprovacao` (ENUM: `'EDITANDO'`, `'AGUARDANDO'`, `'APROVADO'`, `'RECUSADO'`), `iniciar_producao_em`, `notas` [Passage 849].
* **Tabela de Itens para Corte:** `marmoraria_ordens_cortes_itens` [Passage 762, 850]
* *Campos:* `id`, `id_ordens_cortes` (FK), `id_itens` (Amarra síncrona ao item do orçamento original) [Passage 148, 861], `volume` (Quantidade física de peças) [Passage 148], `largura`, `altura`, `total_m2` [Passage 148], `acabamento` (metro linear - MLN) [Passage 148, 861], `id_materiais`, `rotulo_item`, `rotulo_ambiente`, `rotacionar` (boolean) [Passage 148, 168].
* **Visão de Banco de Rastreabilidade (`view_marmoraria_ordens_cortes`):**
Esta visão consolida as O.C.s do Tenant aplicando o filtro restritivo de segurança e calculando reativamente os status com base em datas temporais (`status_producao`) [Passage 871]:
```sql
CREATE OR REPLACE VIEW view_marmoraria_ordens_cortes_{id_empresas} AS
SELECT t1.*, t2.numero, t5.nome AS obra,
IF(t1.status_execucao = 'FINALIZADO', 'PRODUÇÃO CONCLUÍDA',
IF(t1.status_aprovacao = 'RECUSADO', 'PRODUÇÃO CANCELADA',
IF(t1.status_execucao = 'EM PRODUÇÃO', 'PRODUZINDO',
IF(DATEDIFF(t1.iniciar_producao_em, CURDATE()) = 0, 'PRODUZIR HOJE',
IF(DATEDIFF(t1.iniciar_producao_em, CURDATE()) < 0, 'PRODUÇÃO ATRASADA',
CONCAT('PRODUZIR EM ', DATEDIFF(t1.iniciar_producao_em, CURDATE()), ' DIAS')))))) AS status_producao
FROM marmoraria_ordens_cortes AS t1
INNER JOIN marmoraria_orcamentos AS t2 ON t2.id = t1.id_pedidos
WHERE t2.id_empresas = {id_empresas};
``` [Passage 871, 872]
---
### MÓDULO 3: DIAGRAMAÇÃO E ENCAIXE CNC (`producao-planoscortes`)
Ferramenta visual utilizada pelo programador de CNC para simular o aproveitamento de chapas brutas e diminuir o descarte de retalhos [Passage 186].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E DIAGRAMAÇÃO VISUAL
```
[Programador: producao-planoscortes] (hbox)
│
┌──────────────────────────────┴──────────────────────────────┐
▼ (Painel Esquerdo - vbox) ▼ (Painel Direito - Auto)
[Parâmetros e Chapas] [Área do Canvas (HTML5)]
- combo O.C. (Apenas 'EM PRODUÇÃO') - Drag & Drop de peças
- Chapas e Peças Disponíveis - Duplo Clique (Rotaciona 90º)
- inputs: Kerf, Margem, Escala - Resumo de Aproveitamento m²
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-planoscortes` [Passage 186] | **Layout:** `hbox` [Passage 186].
* **Painel de Parâmetros e Filtros (Esquerda - vbox):**
* **Seletor O.C.:** `combobox` que consome a store `{ordenscortes}` filtrando estritamente ordens no status `'EM PRODUÇÃO'` [Passage 186].
* **Seletor de Chapas:** `combobox` reativo carregando materiais cadastrados na O.C. [Passage 186].
* **Parâmetros de Corte (Fieldset):**
* `kerfField` (intfield): Espessura do disco de serra diamantado em milímetros (kerf) para desconto síncrono [Passage 187].
* `margemField` (intfield): Desconto de esquadrejamento de bordas da chapa bruta em milímetros [Passage 187].
* `escalaField` (intfield): Fator de pixel para metros para renderização dinâmica (Padrão: `210px` representam `1 metro` síncrono) [Passage 187, 191].
* **Grid de Peças Disponíveis:** Renderiza a lista de peças da O.C. com comprimento, largura e se aceita rotação (`rotacionar`) [Passage 168, 187, 188].
* **Grid de Chapas Disponíveis:** Exibe as chapas brutas em estoque com suas medidas correspondentes [Passage 188].
* **Botão ENCAIXAR (`onGerarPlano`):** Dispara o algoritmo de auto-encaixe bidimensional de peças na chapa [Passage 189, 190].
* **Botão GERAR PDF (`onSalvarPlano`):** Compila o desenho tático do encaixe e força o download do mapa de corte para o operador da serra [Passage 190].
* **Área do Prancheta de Desenho (Direita):**
* **itemId:** `canvasArea` [Passage 190]. Renderiza dinamicamente contêineres HTML representando a chapa mestre (`wrapperChapa`) [Passage 191] e as peças internas de forma proporcional.
* **Interatividade Drag & Drop e Rotação:** O operador pode reposicionar as peças arrastando-as na tela e, ao efetuar um **duplo clique** sobre o contêiner da peça, o ExtJS intercepta e inverte síncronamente a largura pela altura, rotacionando a peça em 90º para testar novos encaixes [Passage 190].
* **Cálculo Dinâmico de Aproveitamento:** O ViewController soma as áreas das peças encaixadas e exibe em tempo real o indicador no cabeçalho do canvas [Passage 191]:
* **Utilizado:** m² total consumido e o percentual de aproveitamento [Passage 191].
* **Sobra Bruta:** m² descartado e o percentual de perda da chapa [Passage 191].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/planos_cortes/php/response.php` [Passage 191, 192].
* **Métodos (`m`):** `ordenscortes` [Passage 191, 192], `materiais` [Passage 192, 193] and `chapas` [Passage 193].
---
### MÓDULO 4: ESTEIRA E KANBAN DA FÁBRICA (`producao-kanban`)
Este módulo é o painel interativo da fábrica, organizando as Ordens de Cortes em colunas reativas correspondentes a cada máquina de corte ou acabamento [Passage 106, 509].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE TRABALHO
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-kanban` [Passage 106] | **Layout:** `vbox` [Passage 106].
* **Contêiner Dinâmico de Colunas:** `reference: "kanban"`, `layout: "hbox"` com scroll horizontal [Passage 106, 107]. No método `onLoadMaquinas`, o controller limpa colunas anteriores, varre as máquinas de produção ativas (`maquinas` store [Passage 107, 110]) e adiciona dinamicamente componentes **`producao-kanban-card`** paralelos na tela [Passage 107, 108].
* **Componente Coluna Kanban (`producao-kanban-card`):**
* **xtype:** `producao-kanban-card` [Passage 92] | **Width:** `300` [Passage 93].
* **Configuração:** `maquina: record.data` [Passage 93, 108]. Carrega em sua store `{ordens}` as O.C.s que se encontram síncronamente alocadas naquela máquina [Passage 94, 101].
* **Ações de Cabeçalho do Card:**
* Mover de Máquina (`onMover`): Transiciona a O.C. entre colunas (Ex: da Serra CNC para o acabador) [Passage 93].
* Histórico (`onHistorico`): Abre o grid de auditoria `producao-banban-historico` para identificar quem moveu a peça [Passage 93, 100].
* Gerenciar Ordem (`onGerenciar`): Abre o painel maximizado (`win-gerenciar-oc` [Passage 95]) exibindo a grade de peças da O.C. [Passage 95]. Permite que o encarregado atribua síncronamente o **Serrador** (`id_trab_serrador`) e o **Acabador** (`id_trab_acabador`) para cada peça de forma unitária através de cliques em ferramentas diretamente na célula (`gridcellediting`) [Passage 98, 99].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/kanban/php/response.php` [Passage 101, 778]
* **Métodos principais (`m`):**
* `maquinas`: Carrega as máquinas ativas cadastradas [Passage 110].
* `ordens_cortes`: Lista as O.C.s filtrando síncronamente por ID de máquina e Tenant [Passage 101].
* `reordenar_maquinas`: Grava no MariaDB a reordenação sequencial das colunas do Kanban [Passage 109].
##### C. Persistência de Dados (MariaDB)
* **Tabela de Máquinas de Produção:** `maquinas_producao` [Passage 827]
* *Campos:* `id`, `id_empresas` (Tenant), `nome`, `tipo` (ENUM: `'CORTE'`, `'ACABAMENTO'`), `id_areas`, `ordem` [Passage 509, 511].
* **Tabela de Histórico de Movimentação do Kanban:** `marmoraria_ordens_cortes_historico` [Passage 104, 105].
---
### MÓDULO 5: EXPEDIÇÃO E ROMANEIOS (`producao-romaneios-grid`)
Gerencia o carregamento físico dos veículos da marmoraria, a cubagem tática e a roteirização de entregas das pedras prontas para as obras [Passage 216, 217, 740, 741].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE CARREGAMENTO
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-romaneios-grid` [Passage 215] | **Layout:** `hbox` [Passage 215].
* **Painel Esquerdo (Lista de Romaneios):**
* **xtype:** `list` | **Reference:** `romaneioList` [Passage 215]. Exibe os romaneios de transporte em aberto, com visual tático destacando placas de veículos e nomes de motoristas [Passage 215, 217].
* **Painel Direito (Grid Detalhado de Itens):**
* **xtype:** `grid` | Consome a store `{romaneios}` [Passage 216, 220].
* **Ações de Toolbar:**
* Entregar (`onEntregar`): Abre o Wizard de montagem de romaneios `producao-romaneios-form` [Passage 210, 216].
* Entregue (`onEntregue`): Executa a baixa de entrega síncrona, carimbando o faturamento do lote e atualizando as progress bars do dashboard comercial [Passage 216, 861].
* Arquivos: Abre a janela flutuante `win-romaneio-upload` para upload e custódia digital de comprovantes de entrega assinados ou fotos da carga [Passage 216, 218].
* **Formulário de Montagem de Romaneios (`producao-romaneios-form`):**
* O usuário seleciona a O.C. correspondente [Passage 213]. O sistema carrega os itens de corte pendentes [Passage 214].
* Através do plugin `gridrowdragdrop`, o operador **arrasta as peças** da grade de cortes disponíveis para a grade de Romaneados, configurando a quantidade que será enviada no veículo (`entregar`) e agrupando as bancadas em "Conjuntos" de montagem (Ex: *Bancadas Cozinha Área Gourmet*) [Passage 211, 212].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/romaneios/php/response.php` [Passage 214, 220]
* **Métodos (`m`):** `consultar` [Passage 220], `ordenscortes` [Passage 214] and `salvar` [Passage 213].
##### C. Persistência de Dados (MariaDB)
* **Tabela Principal:** `marmoraria_romaneios` [Passage 131, 696].
* **Tabela de Itens:** `marmoraria_romaneios_itens` [Passage 867].
---
### MÓDULO 6: APONTAMENTO DE INSTALAÇÕES (`producao-instalacoes-tree`)
Este componente é a ferramenta de campo do gestor de obras e medidores técnicos, controlando os cartões de ponto de instalações e acertos financeiros das equipes de montadores [Passage 87, 88].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE INSTALAÇÃO
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-instalacoes-tree` [Passage 87] | **Layout:** `fit` [Passage 87].
* **Componente de Árvore (`tree`):**
* Vinculado à TreeStore `{tree}` [Passage 87]. Renderiza a hierarquia dinâmica de controle de campo organizada de forma aninhada: **Obra ➔ Colocador/Instalador ➔ Dia de Trabalho (Cartão Ponto)** [Passage 88, 91].
* *Colunas de Telemetria:* Cartão de ponto (datafield [Passage 88]), Horas Trabalhadas [Passage 88], M² Contratado em Pedido [Passage 88, 91], m² Instalado no Período [Passage 91, 124], e status do pagamento de RT/Comissão [Passage 125].
* **Wizard de Acertos de Serviços (`producao-instalacoes-lotedialog`):**
* Ao dar duplo clique sobre um dia de trabalho na árvore, abre-se a janela de inserção de medição [Passage 77, 78].
* O sistema lista as peças de tampos vinculadas ao pedido do cliente (`itens` store [Passage 78, 83, 84]).
* O instalador preenche a quantidade quadrada ou linear de fato assentada em parede (`quantidade`) [Passage 78, 80] and o custo combinado de colocação (`custo_unitario`) [Passage 78, 80].
* **Auditoria de Limites Físicos:** O ViewController lê reativamente as colunas e **bloqueia a submissão se a quantidade informada superar o saldo do contrato do cliente** (`quantidade_saldo`), impedindo desvios ou erros de apontamentos em duplicidade [Passage 79, 81].
* **Quadro de Parcelamento de RT de Instaladores (`producao-instalacoes-parcelas-grid`):**
* Mapeia o parcelamento de pagamento para os trabalhadores (Ex: 30/60/90 dias) [Passage 85].
* Apresenta uma fórmula dinâmica com cores neon para alertar se a somatória das parcelas agendadas fecha de forma idêntica contra o total de custos pendentes de montagem: **Verde (Bateu)**, **Laranja (Faltando)**, ou **Vermelho (Estourou)** [Passage 86].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/instalacoes/php/response.php` [Passage 75, 91, 92].
* **Métodos (`m`):** `consultar` [Passage 91], `horarios` [Passage 82], `servicos` [Passage 75, 83] and `produtos_avulsos` [Passage 77].
---
### MÓDULO 7: REQUISIÇÃO DE INDUSTRIALIZAÇÃO DE BLOCOS (`producao-industrializacoes-grid`)
Gerencia as frentes de serrada primária do pátio, onde blocos brutos de rochas são pesados e industrializados em tear de fios diamantados para fabricação e entrada de chapas polidas no estoque [Passage 16, 38, 772].
---
#### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO DE TEAR
```
[Ficha Técnica: producao-industrializacoes-form] (vbox)
│
┌────────────────────────────────┴────────────────────────────────┐
▼ (Tear do Bloco) ▼ (Finalização / Tear)
[Grade: ITENS RESQUISITADOS] [Grade: ITENS PRODUZIDOS]
- Bloco bruto retirado de estoque - Chapas e Lâminas produzidas
- inputs: Desconto bloco, Acréscimo lâmina - inputs: Volumes, Comprimento, Altura
│ │
└────────────────────────────────┬────────────────────────────────┘
▼ (Insumos consumidos)
[Grade: INSUMOS UTILIZADOS]
- Consumo de abrasivos, resinas e fios
```
##### A. Front-End (Sencha ExtJS v7.3.1 Modern Toolkit)
* **xtype:** `producao-industrializacoes-grid` [Passage 48].
* **Plugins:** `summaryrow` [Passage 49], `rowexpander` (abre visualização rápida das chapas geradas no tear [Passage 49]) e `gridfilters` [Passage 49].
* **Formulário de Solicitação (`producao-industrializacoes-form`):**
* O usuário seleciona o Bloco de mármore do estoque (`estoques` store [Passage 38, 47, 48]), indicando as medidas do bloco bruto (comprimento, altura, largura/espessura) [Passage 32, 45].
* Determina os acréscimos operacionais de retaguarda: espessura da lâmina do tear em centímetros (`acrescimo_espessura_chapa` [Passage 39, 45]) e desconto de largura do bloco [Passage 39, 45].
* **Formulário de Finalização de Tear (`producao-industrializacoes-finalizar-form`):**
* **xtype:** `producao-industrializacoes-finalizar-form` [Passage 15].
* **Interface Mestre-Detalhe Dividida:**
* *Grid Esquerda (Itens Requisitados):* Exibe o bloco bruto com seu m³ nominal [Passage 16].
* *Grid Direita (Itens Produzidos):* Permite ao operador digitar síncronamente a quantidade de volumes (chapas) produzidos na serrada, com comprimento, altura e espessura final da pedra polida [Passage 19-21].
* *Grid Inferior (Insumos Utilizados):* Grade editável onde o operador anexa e deduz síncronamente do estoque os insumos consumidos na máquina durante o processo (Ex: bisnagas de resinas epóxi, rolos de redes de reforço, lixas de polimento e dentes de fios diamantados), com salvamento síncrono via `salvar_insumo` [Passage 23, 27, 28].
##### B. API de Comunicação e Back-End (PHP)
* **Endpoint Principal:** `mod/marmoraria/producao/industrializacoes/php/Industrializacoes.php` [Passage 771]
* **Métodos principais (`m`):** `consultar` [Passage 69], `salvar_produzido` [Passage 774], `finalizar` [Passage 29, 30] (que de forma transparente atualiza síncronamente o inventário do estoque do pátio diminuindo o bloco bruto e injetando as chapas finais polidas [Passage 31]).
---
### 📘 GUIA DE OPERAÇÃO OPERACIONAL (MANUAL DO CHÃO DE FÁBRICA)
#### Objetivo da Categoria
Garantir o monitoramento rígido dos prazos de corte, aproveitamento máximo de chapas no CNC, rastro de movimentações físicas via QR Code e a correta conciliação financeira do Chão de Fábrica ao caixa da marmoraria inquilina [Passage 30, 46, 126, 171].
---
#### OPERAÇÃO 1: DO PEDIDO À ORDEM DE CORTE (LIBERAÇÃO)
1. Acesse o menu **Produção > Ordens de Cortes** [Passage 922].
2. A grade exibirá as O.C.s geradas automaticamente pelo fechamento de propostas comerciais no status de `'ELABORANDO'` [Passage 185].
3. Selecione a O.C. e clique em **Aprovação > Aprovar** [Passage 169].
4. O sistema abrirá o prompt ExtJS de "Previsão de Entrega" [Passage 181]. Insira a data estimada para faturamento do romaneio e clique em **OK** [Passage 181].
5. A O.C. transiciona síncronamente para o status **`APROVADO`** [Passage 181]. *A partir de agora, o lote de chapas brutas correspondente às peças do projeto encontra-se de forma transparente RESERVADO no estoque, impedindo que o mesmo material seja vendido ou cortado para outra obra [Passage 740, 741].*
---
#### OPERAÇÃO 2: PROGRAMAÇÃO E DIAGRAMAÇÃO CNC (PLANO DE CORTE)
1. Acesse o menu **Produção > Planos de Cortes** [Passage 922].
2. No combobox superior **Ordens de cortes disponíveis**, selecione a O.C. liberada anteriormente [Passage 186].
3. No dropdown de materiais, escolha o lote de chapas reservado [Passage 186].
4. Defina a espessura do disco diamantado no campo **Kerf Disco** (Ex: `3` mm) and a margem de esquadrejamento de pontas (Ex: `10` mm) [Passage 187, 191].
5. O ExtJS carregará de forma imediata a grid de peças táticas e a grid de chapas brutas [Passage 187, 188].
6. Clique no botão **ENCAIXAR** [Passage 189]. O sistema renderizará reativamente na prancheta direita a distribuição das peças sobre a chapa [Passage 190, 191].
7. *Refinamento Táctil:* Arraste as peças na tela para reposicioná-las [Passage 190]. Se precisar de rotação de veios de quartzitos, dê um **duplo clique** sobre a peça para rotacioná-la síncronamente em 90º [Passage 190].
8. Verifique o indicador **Utilizado** no rodapé: se o aproveitamento estiver ideal (Ex: `88%`), clique em **GERAR PDF** para enviar o plano e etiquetas de bipagem para a máquina CNC [Passage 171, 190, 191].
---
#### OPERAÇÃO 3: INICIAR E APONTAR A PRODUÇÃO NO KANBAN
1. O gerente de produção acessa o menu **Produção > Linha de Produção** para auditar o Chão de Fábrica [Passage 923].
2. A O.C. recém-aprovada surgirá no cabeçalho superior do Kanban horizontal [Passage 106].
3. Clique no ícone de engrenagem do card **Gerenciar Ordem** [Passage 93] para abrir a grade de peças [Passage 95].
4. Clique no ícone de edição ao lado da linha da peça [Passage 98, 99]. No dropdown select ExtJS [Passage 153], aponte o Serrador CNC responsável [Passage 98] and a máquina de corte utilizada [Passage 153].
5. Clique em **Salvar**. A O.C. será alocada de forma visual na coluna correspondente à máquina parametrizada no Kanban de forma instantânea [Passage 107, 108], iniciando síncronamente a contagem do tempo de fabricação e dias parados do Chão de Fábrica [Passage 178].
---
#### OPERAÇÃO 4: SEPARAÇÃO, PESAGEM E CARREGAMENTO DE CAMINHÃO (ROMANEIOS)
1. Ao finalizar o acabamento, o sistema emite o alerta visual [Passage 113, 117]. Acesse o menu **Produção > Romaneios** [Passage 923].
2. Clique no botão **Entregar** na barra de ferramentas superior [Passage 216].
3. O Wizard `producao-romaneios-form` será carregado [Passage 210]. Selecione a O.C. finalizada do cliente [Passage 213].
4. O sistema somará automaticamente o peso de todas as bancadas e tampos com base em suas densidades e dimensões, exibindo a pesagem em kg em tempo real na tela [Passage 174, 220].
5. Selecione o veículo da frota e o motorista responsável. *O ERP cruzará síncronamente o peso total do lote contra a capacidade de tração máxima do caminhão no MariaDB: se ultrapassado o limite físico, o controller emite o alerta impedindo a saída sem o fracionamento de viagens [Passage 73, 94, 217].*
6. Arraste as peças prontas do grid de cortes para a grade de entrega e clique em **Salvar** [Passage 211, 213]. *O romaneio é gerado no banco síncronamente [Passage 213], pronto para bipagem de etiqueta no portão de expedição.*
---
#### OPERAÇÃO 5: EXECUÇÃO DE CAMPO E ACERTO FINANCEIRO DE PARCELAS
1. A equipe de campo realiza o assentamento das bancadas na casa do cliente [Passage 337].
2. O encarregado de instalações acessa **Produção > Instalações** [Passage 923].
3. Na árvore do colocador selecionado [Passage 88, 91], clique em **Incluir** [Passage 87].
4. Selecione as peças finalizadas na obra [Passage 78]. O sistema exibirá de forma síncrona a quantidade m² contratada e o saldo pendente [Passage 78, 79].
5. Preencha no campo de acertos a metragem quadrada assentada (Ex: `2.40` m²) e confirme o valor pago de colocação (Ex: `R$ 150,00` por m²) [Passage 80].
6. Ao salvar, a classe em PHP executa a rotina síncrona [Passage 776]: ela atualiza as progress bars de montagem do dashboard comercial [Passage 18, 230], altera o status da peça para instalada [Passage 113, 124] e **gera de forma 100% automatizada o agendamento de repasse financeiro do contas a pagar para a conta corrente Pix do instalador na tesouraria**, alimentando o DRE de retaguarda sem nenhuma redigitação manual [Passage 660, 661, 874].
---
### ⚡ VÍNCULOS TRANSVERSAIS DO ECOSSISTEMA COMERCIAL E DE PRODUÇÃO
O módulo de **Produção** funciona como o validador físico-financeiro do Sistrom ERP, reagindo a eventos e travando processos de forma transparente:
* **Travamento Síncrono de Duplicidade de O.C.s:**
O ERP blinda de forma nativa a integridade industrial para impedir que uma fábrica gere ordens de cortes duplicadas para o mesmo pedido comercial [Passage 746]. No momento em que o orçamentista tenta processar uma O.C. via endpoint PHP (`response.php` [Passage 779]), o método intercepta e executa de forma atômica no banco [Passage 746]:
```php
$sql = "SELECT COUNT(*) AS existente FROM marmoraria_ordens_cortes WHERE id_pedidos = " . $id_pedido;
$exist = $this->fetch_object($this->query($sql))->existente > 0;
if ($exist) {
print json_encode(array(
"success" => false,
"title" => "Pedido em produção",
"msg" => "Não será possível continuar, porque esse pedido já foi passado para produção"
));
return false;
}
``` [Passage 746]
* **Ação síncrona de Baixas de Estoques e Checklists de Qualidade:**
No instante em que o operador em campo realiza o encerramento do checklist de montagem na obra (Ex: *"Termo de Aceite Assinado"* no aplicativo `ColocApp` ou formulário ExtJS de instalações `rh_cartoes_pontos_obras_servicos`) [Passage 337], o banco do MariaDB dispara em retaguarda os gatilhos de finalização de ordens [Passage 843].
O sistema localiza a O.C. correspondente em `marmoraria_ordens_cortes`, altera reativamente seu status para `FINALIZADO` [Passage 843], calcula o quantitativo real m² gasto [Passage 843] e **executa de forma transparente a baixa física de chapas brutas no estoque do pátio**, registrando de forma imutável a data de saída em `movimentado_em = NOW()` sem que nenhum estoquista precise tocar no teclado do terminal [Passage 626, 740, 741].
---
# 📐 CATEGORIA: DESENHO TÉCNICO
## 🔮 MÓDULO MASTER: MODELAGEM 3D (`sketchup`)
O módulo **`sketchup`** do Sistrom ERP é a coroa de ouro da engenharia de vendas e detalhamento tridimensional do sistema [Passage 2, 872]. Ele consiste em um software de **CAD tridimensional em nuvem 100% integrado ao ERP** [Passage 11, 461].
Ao unir o poder gráfico do **Three.js (WebGL)** no front-end, a flexibilidade estrutural do **Sencha ExtJS Modern Toolkit**, orquestrações de arquivos em **PHP v7.1.33**, heranças físicas no **MariaDB v5.6.36**, e os agentes autônomos de inteligência artificial do **Gemini/Vertex SDK**, o orçamentista é capaz de modelar peças complexas, casar veios de chapas reais do estoque, usinar furos de cubas e exportar de imediato toda a estrutura paramétrica e volumétrica para precificação na proposta comercial [Passage 11, 12, 55, 68, 72, 455, 461].
---
### ⚙️ MAPEAMENTO ARQUITETURAL E FLUXO GRÁFICO (RASTREAMENTO DE FLUXO)
```
[Interface Viewport: sketchup] (Ext.Container)
│
┌────────────────────────────────────────┼────────────────────────────────────────┐
▼ (Lado Esquerdo - Canvas 3D) ▼ (Lado Direito - Painel ExtJS) ▼ (Barra de Ferramentas)
[canvasContainer] [listaElementosCena (Tree)] [Ações do Estúdio]
- WebGL Renderer (Three.js) - Elementos parametrizados - Shapes / IA Terminal
- OrbitControls / Transform - Form. Propriedades - Usinagem / Snap
- Smart Guides (Linhas Neon) - Ajustes de Texturas (Veios) - Exportar Orc. / O.C.
│ │ │
└────────────────────────────────────────┼────────────────────────────────────────┘
▼ (Ajax / POST / Multipart)
[mod/marmoraria/sketchup/php/response.php]
│
┌───────────────────────┴───────────────────────┐
▼ ▼
[Back-End PHP: Sketchup.php] [Agente de Inteligência Artificial]
│ - AgSketchup (Linguagem ➔ JSON)
│ - AgImagem (Render e Fotorrealismo)
▼ │
[Persistência física no MariaDB] ▼
- marmoraria_sketchup_cenas [Vertex AI / Gemini API Gateway]
- marmoraria_sketchup_cenas_capturas
```
#### 1. Front-End (WebGL & Sencha ExtJS Modern)
* **Componente de Visualização (View):**
* **xtype:** `sketchup` (definido em `ERP/app/mod/marmoraria/sketchup/view.js`) [Passage 2].
* **ViewModel:** `ERP.Sketchup.viewModel` (alias: `viewmodel.sketchup`) [Passage 2, 105].
* **ViewController:** `ERP.Sketchup.viewController` (alias: `controller.sketchup`) [Passage 2, 11].
* **Layout:** Contêiner flexível que acopla o pranchão WebGL à esquerda e o painel de propriedades do sólido à direita (com largura fixa de 550px, colapsável para o lado direito) [Passage 6].
* **O Coração Gráfico (Three.js & Canvas Integration):**
O método `onCanvasContainerPainted(container)` inicializa de forma síncrona o motor gráfico tridimensional [Passage 12]. Ele analisa as dimensões da div do DOM (`clientWidth`, `clientHeight`) [Passage 12], instancia o renderizador WebGL (`THREE.WebGLRenderer`), define a cor de fundo (adotando uma paleta sofisticada baseada na variável de tema: `0x1a1c23` para Dark Mode ou `0xf4f5f7` para Light Mode) [Passage 12], cria a câmera perspectivada (`THREE.PerspectiveCamera`) e adiciona a grade do palco (`THREE.GridHelper`) utilizando cores coordenadas (`0x00e5ff` para o centro ativo e `0x2b2d42` para as linhas acessórias) [Passage 12].
* **Controle de Órbita e Manipulação (`orbitControls` & `transformControls`):** Permitem ao usuário orbitar a cena de forma suave (`THREE.OrbitControls`) e selecionar/arrastar/rotacionar os sólidos formados no espaço 3D (`THREE.TransformControls`) [Passage 11].
* **O Segredo da Altura de Trabalho (0.9m Plane):**
Para garantir a integridade geométrica no espaço bidimensional do mouse, o Raycaster do Three.js projeta o clique diretamente em um plano horizontal virtual invisível posicionado síncronamente na altura de 0.90 metros (altura ergonômica padrão de tampos de banheiros e cozinhas), salvaguardando o alinhamento plano das peças desenhadas [Passage 17]:
```javascript
var alturaBase = me.pontosDesenho.length > 0 ? me.pontosDesenho.y : 0.9;
var drawPlaneDown = new THREE.Plane(new THREE.Vector3(0, 1, 0), -alturaBase);
me.raycaster.ray.intersectPlane(drawPlaneDown, intersectPointDraw);
``` [Passage 17]
* **Guias Inteligentes Dinâmicas (`SmartGuides`):**
Ao selecionar um sólido, o ViewController calcula síncronamente as distâncias em relação ao tampo principal ("Pai") debaixo da peça selecionada [Passage 49, 50]. Utilizando o radar (`Box3.expandByScalar(0.5)`), o Three.js desenha no ar **Linhas Tracejadas Azul Neon** (`THREE.LineDashedMaterial` com cor `0x00aaff`) [Passage 50, 51] and **Sprites de Textos 3D deitados no chão** (`criarTexto3D` via CanvasTexture de resolução 512x128) [Passage 33, 51] informando as distâncias exatas de folgas e margens de colagem em metros (Esquerda, Direita, Frente, Fundo) [Passage 51, 52].
* **Mapeamento de Stores e Dados no ViewModel:**
* `elementosCena`: Árvore de dados (`type: "tree"`) vinculada à lista hierárquica lateral do ExtJS, espelhando cada sólido e suas medidas físicas (comprimento, largura, espessura e acabamentos) [Passage 6, 107].
* `texturas`: Store reativa que se comunica síncronamente com `m: "consultar_texturas"` [Passage 106]. Ela traz as fotos em alta resolução de chapas e blocos reais cadastrados no estoque de materiais do pátio para o casamento de veios [Passage 8, 72, 106].
* `albumCapturas`: Catálogo interno que armazena os snapshots tridimensionais (fotos e perspectivas tiradas pelo orçamentista) convertidos em strings baseada em MIME base64 de qualidade `0.90` [Passage 76, 80, 107].
---
#### 2. Usinagens e Matemática Geométrica (Constructive Solid Geometry - CSG BSP Visual Core)
O estúdio 3D do Sistrom implementa de forma avançada a tecnologia de **Constructive Solid Geometry (CSG)** e representação por **Binary Space Partitioning (BSP)** para efetuar cortes mecânicos e modelagens paramétricas em tempo real sobre os sólidos de pedras [Passage 54, 56, 58].
##### A. Corte Meia-Esquadria em 45 Graus (`aplicarCorte45CSG`):
Ao acionar o corte em 45º [Passage 54], o ViewController clona a geometria original do sólido selecionado e calcula as dimensões de sua caixa virtual (`Box3`) [Passage 54]. Ele projeta uma cunha de corte e executa de forma síncrona o fatiamento inclinado na borda parametrizada (Topo, Base, Esquerda, Direita), modificando de forma atômica o buffer de vértices (`toNonIndexed` e recalculando as normais com `computeVertexNormals`) [Passage 5, 54, 57], gerando o acabamento meia esquadria em pias ou tampos suspensos.
##### B. Recortes Subtrativos de Cubas, Cooktops e Lixeiras de Embutir:
Quando um orçamentista arrasta e posiciona um **"Molde"** (representado por sólidos com a cor de sistema **Vermelho Puro `#ff0000`**) sobre a pedra principal [Passage 55, 65, 68]:
1. O sistema executa um radar de colisão com `Box3.intersectsBox(boxEl)` para localizar a pedra de menor volume sob o molde [Passage 55, 58].
2. Dispara uma máscara visual (`App.util.loadMask.show`: *"Usinando pedra..."*) [Passage 55] e converte ambas as malhas de Three.js em polígonos BSP (`CSG.fromMesh`) [Passage 56].
3. Efetua síncronamente a operação de subtração matemática booleana em memória:
```javascript
var bspAlvo = CSG.fromMesh(cleanMesh);
var bspMolde = CSG.fromMesh(moldeFantasma);
var bspResultado = bspAlvo.subtract(bspMolde);
var meshResultado = CSG.toMesh(bspResultado, pedraAlvo.matrixWorld, pedraAlvo.material);
``` [Passage 56]
4. **A Imutabilidade da Usinagem:** A malha usinada tem sua geometria atualizada, o molde vermelho é expurgado da cena [Passage 56, 57] e o sistema carimba a flag de imutabilidade **`userData.isUsinada = true`** na peça [Passage 57, 63]. *A partir deste instante, as quinas e dimensões básicas da peça são travadas em banco para evitar que uma alteração acidental de arredondamento de quinas no ExtJS apague ou corrompa as usinagens e furações físicas criadas na rocha [Passage 63].*
---
#### 3. Casamento de Veios (Mapeamento Analítico de Texturas)
O casamento de veios em mármores e quartzitos nobres é operado de forma visual e precisa pelo orçamentista [Passage 9]:
```
[Lado Esquerdo: WebGL Material]
│
(Sincroniza coordenadas com base na chapa mestre padrão: 3.20m x 2.00m)
│
▼
- Zoom / Escala (tex_escala) ──► Re-dimensiona repeat.set() [Passage 9, 61]
- Mover X (tex_offset_x) ──► Desloca horizontalmente [Passage 10, 61]
- Mover Y (tex_offset_y) ──► Desloca verticalmente [Passage 10, 61]
│
▼
[Aplica THREE.MirroredRepeatWrapping em ambas as pontas]
```
* **A Chapa Mestre Industrial:** O motor de texturas utiliza como escala real padrão as dimensões médias de chapas industriais brutas de **3.20 metros de comprimento por 2.00 metros de altura** [Passage 61, 91].
* **O Algoritmo de Mapeamento (`sincronizarDimensoesETextura`):**
No instante em que o operador seleciona a imagem real da rocha do estoque para a peça [Passage 8], o ViewController carrega a textura via `THREE.TextureLoader` e aplica as variáveis calculadas de repetições e translações [Passage 61, 75]:
```javascript
var larguraChapaVirtual = 3.20 / userEscala;
var alturaChapaVirtual = 2.00 / userEscala;
matBase.map.repeat.set(1 / larguraChapaVirtual, 1 / alturaChapaVirtual);
matBase.map.offset.set(0.5 + userOffsetX, 0.5 + userOffsetY);
matBase.map.wrapS = THREE.MirroredRepeatWrapping;
matBase.map.wrapT = THREE.MirroredRepeatWrapping;
matBase.map.center.set(0.5, 0.5);
``` [Passage 61]
*Isso garante que ao mover os spinners de Offsets X/Y ou Escala no formulário ExtJS [Passage 9, 10], a textura se desloque sobre o tampo com precisão milimétrica, permitindo alinhar perfeitamente os veios de painéis de quartzitos que serão cortados lado a lado, dando o efeito estético de "livro aberto" (bookmatching) de forma visível para aprovação síncrona do cliente [Passage 9, 10, 61].*
---
#### 4. O Motor de IA: Comando Inteligente e Capas Fotorrealistas (Gemini SDK)
O módulo é integrado ao gateway de inteligência artificial de retaguarda do Sistrom ERP [Passage 455]:
* **Comando Inteligente de Desenho (`comando_gerar_pecas`):**
O botão de terminal de prompt superior ativa a IA conversacional [Passage 4, 96]. O orçamentista digita o comando em linguagem natural (Ex: *"Cria uma bancada de 2 metros por 60cm com frontão de 15cm e uma saia de 20cm"*) [Passage 96, 97].
O PHP aciona a classe **`AgSketchup`** [Passage 455, 529]. Ela lê a lista de produtos cadastrados da marmoraria inquilina e gera de forma autônoma a árvore paramétrica aninhada em JSON [Passage 469, 529].
O ViewController recebe a matriz de dados e, através de `gerarPecasViaIA(jsonIA)`, executa de forma sequencial e síncrona o laço iterativo `instanciarIaNode` [Passage 97, 98]: ele calcula os m² e espessuras [Passage 98], monta a extrusão no canvas [Passage 100], realiza o acoplamento magnético das laterais baseando-se nas tags semânticas (Ex: posiciona síncronamente as saias e frontões "acima" ou "abaixo" nas quinas corretas do tampo pai) [Passage 102, 103], organizando de imediato todo o projeto tridimensional em tela [Passage 105].
* **Renderização Fotorrealista de Capa de Apresentação:**
Se no modal de geração de PDF do projeto o operador ativar o checkbox **"Gerar fotorrealismo do ambiente para a Capa"** [Passage 84], o back-end PHP invoca a inteligência de visão **`AgImagem`** [Passage 455, 467].
A IA realiza uma leitura unificada de todos os descritivos técnicos de ambientes e peças salvos na cena [Passage 467], traduz o tecnes técnico para descrições arquitetônicas requintadas em inglês (`_traduzirTecnesParaVisual` e `_getDecoracaoAmbiente`) [Passage 499, 500, 507] e, através do motor de difusão por prompts estruturados tridimensionais (Vertex AI / Imagen), **compila e salva de forma síncrona uma capa fotorrealista de alta definição (aspectRatio 3:4)** refletindo os materiais e especificações reais do projeto, compondo a primeira página do prontuário PDF do cliente de forma transparente e profissional [Passage 467, 507].
---
#### 5. Exportação de Engenharia de Custos (3D para o Orçamento)
Ao concluir a modelagem, o orçamentista clica no botão **Exportar** [Passage 68]. O ViewController executa um protocolo rigoroso de validação de negócios em cascata antes de enviar o payload limpo para o servidor em PHP [Passage 68, 70]:
```
[Mesa de Desenho 3D: serializeScene]
│
▼ (Validação 1: Hierarquia de Agrupamentos)
¿Peças complementares (saias/frontões) estão acopladas ao Pai?
│
├─► NÃO ➔ Exibe Alerta e aborta [Passage 68]
└─► SIM ➔ Avança
│
▼ (Validação 2: Presença de Moldes)
¿Existem sólidos vermelhos (#ff0000) na cena?
│
├─► SIM ➔ Alerta: "Exportados como MOLDES (Medidas Zeradas)" [Passage 69]
└─► NÃO ➔ Avança
│
▼ (Validação 3: Itens Omissos)
¿Existem elementos sem amarração com códigos de produtos do Catálogo?
│
├─► SIM ➔ Alerta: "Serão exportados como OMISSOS no orçamento" [Passage 69, 70]
└─► NÃO ➔ Executa POST síncrono
│
▼
[Back-End PHP: exportar_ambiente_orcamento()] ➔ [Grava fisicamente nos Itens do Orçamento]
```
* **O Algoritmo de Gravação nos Itens do Orçamento (`exportar_ambiente_orcamento`):**
O endpoint em PHP recebe o payload JSON e desestrutura a composição geométrica [Passage 71, 461]. Ele varre a árvore do desenho e de forma síncrona executa a injeção em banco [Passage 461]:
1. **Peças Planas e Volumétricas (Tampas e Cubas):** Insere como itens com unidade `M²` ou `UN` em `marmoraria_orcamentos_itens`, convertendo síncronamente as medidas calculadas da geometria do Three.js para as colunas físicas de largura e comprimento do banco [Passage 461, 517].
2. **Peças Lineares (Saias e Frontões):** Lê a rotação (`is_vertical`) e dimensões e as insere síncronamente como subitens de Metro Linear (`MLN`) aninhados ao item mestre [Passage 461, 462, 517].
3. **Usinagens e Perfis de Acabamentos de Bordas:** Insere síncronamente as usinagens de bordas (bisotê, reto, boleado) na tabela de acabamentos do item com a metragem exata calculada do perímetro tridimensional da peça desenvolvida [Passage 461, 518], gerando as tabelas de preços e garantindo que o orçamento de faturamento final reflita exatamente a engenharia física desenhada na prancheta, eliminando retrabalhos ou omissões de precificação de mão de obra.
---
#### 6. Relações e Modelagem de Banco de Dados (MariaDB 5.6.36)
O módulo de Modelagem 3D persiste e gerencia suas entidades de forma normalizada para garantir a rastreabilidade e integridade dos projetos:
##### A. Tabela de Cabeçalho de Projetos 3D (`marmoraria_sketchup_cenas`):
Armazena a estrutura mestre e o estado serializado tridimensional da prancheta de desenho associado síncronamente ao usuário criador e inquilino global [Passage 856]:
* `id_empresas` (BIGINT, FK para `empresas(id)`) [Passage 856, 857].
* `id_usuarios` (BIGINT, FK para `usuarios(id)`) [Passage 856, 857].
* `id` (BIGINT, Auto-Incremento, PK) [Passage 856].
* `titulo` (VARCHAR de tamanho máximo 75) [Passage 856].
* `json_cena` (LONGTEXT - Grava toda a estrutura serializada em JSON minificado contendo as posições, rotações, escalas, uuid de malhas, texturas aplicadas, escalas de veios e parâmetros dos sólidos da prancheta) [Passage 856].
* `criado_em` (DATETIME) e `atualizado_em` (TIMESTAMP) [Passage 856].
##### B. Tabela de Custódia Digital de Capturas (`marmoraria_sketchup_cenas_capturas`):
Gerencia as perspectivas e fotos tiradas com a câmera virtual do estúdio para montagem do catálogo de apresentações em PDF [Passage 857]:
* `id` (BIGINT, PK) [Passage 857].
* `id_cena` (BIGINT, FK para `marmoraria_sketchup_cenas(id)` com cascata de exclusão) [Passage 857].
* `imagem` (VARCHAR de tamanho máximo 255 - Nome do arquivo físico JPG armazenado na pasta do projeto no servidor `/sketchup/[id_projeto]/`) [Passage 458, 857].
* `descritivo` (TEXT - Notas técnicas e especificações automáticas geradas pelo frustum de visão da câmera 3D sobre o ambiente) [Passage 76, 77, 857].
---
### 📘 GUIA DE OPERAÇÃO CAD 3D (MANUAL DE ORÇAMENTISTA)
#### Objetivo do Módulo
Disponibilizar uma bancada de desenho interativa, permitindo modelar peças sob medidas, aplicar usinagens subtrativas (recortes de cubas/cooktops), casar a continuidade dos veios de quartzitos e granitos reais do estoque em tempo real, e gerar apresentações PDF ricas com capas realistas de IA para fechar vendas de alto padrão [Passage 8, 9, 58, 83, 84].
---
#### OPERAÇÃO 1: DESENHAR UMA BANCADA E ANDAR (ANDAR E PEÇA)
1. Acesse o menu **Desenho Técnico > Modelagem 3D** [Passage 872].
2. Clique no ícone superior de **Shapes (Desenhar)** [Passage 4] e selecione **Retângulo** [Passage 4].
3. Clique uma vez na prancheta central para marcar a quina de início do tampo [Passage 17].
4. O pop-up ExtJS **Medidas da Peça** se abrirá síncronamente no canto inferior esquerdo [Passage 35, 36]. Preencha:
* **Largura (m):** `2.00` [Passage 41].
* **Profundidade (m):** `0.60` [Passage 41].
5. Pressione **Enter** ou clique em **Desenhar** [Passage 36, 40]. *O Three.js criará síncronamente o tampo volumétrico (com espessura de 3cm) flutuando no espaço a 0.90m de altura [Passage 44, 45].*
6. Na lista lateral direita, dê um duplo clique no nome padrão da peça na árvore e digite: `BANCADA PRINCIPAL` [Passage 6]. No dropdown de catálogo, associe esta peça ao produto `Tampo de Cozinha` [Passage 67].
---
#### OPERAÇÃO 2: ACOPLAMENTO MAGNÉTICO E HIERARQUIA (FRONTÃO E SAIA)
Para desenhar o frontão e garantir que ele fique perfeitamente encostado na parede da bancada de forma correta e síncrona:
1. Clique no botão de toolbar superior de **Shapes** [Passage 4] e selecione **Retângulo** [Passage 4].
2. Clique na prancheta para definir a quina [Passage 17]. No formulário de medidas, informe: **Comprimento:** `2.00` e **Profundidade:** `0.15` (altura do frontão) [Passage 41]. No campo de propriedades lateral direita, altere a espessura da peça para `2cm` (`0.02` m) [Passage 105].
3. Ative a chave **Vertical** no formulário para colocar a peça "em pé" [Passage 531].
4. Aproxime a peça da bancada principal utilizando as setas direcionais do TransformControls [Passage 11].
5. Com a peça selecionada, clique no ícone **Agrupar/Vincular** na barra de ferramentas [Passage 53, 69].
6. O sistema executará o algoritmo magnético em milissegundos (`vincularPecaHierarquia`) [Passage 53]. Ele detectará a proximidade física da bancada, acoplará síncronamente o frontão em pé rente à borda traseira superior da pia [Passage 53, 54] e o inserirá de forma automática como um subitem hierárquico à bancada principal na árvore lateral do ExtJS, herdando de imediato a textura da pedra de retaguarda [Passage 54, 65].
---
#### OPERAÇÃO 3: CASAR OS VEIOS DA PEDRA (TEXTURIZAÇÃO)
Para realizar o alinhamento estético de um quartzito exótico sobre a bancada principal:
1. Com a bancada principal selecionada [Passage 60], vá ao painel de propriedades lateral direita e acesse o fieldset **Textura** [Passage 7].
2. No combobox **Material**, digite o nome e selecione a foto real da chapa cadastrada no pátio (Ex: *Quartzito Taj Mahal - Lote #45*) [Passage 8, 72]. O Three.js cobrirá síncronamente o tampo com a imagem da pedra de retaguarda [Passage 91].
3. Caso os veios estejam muito grandes ou descentralizados: utilize o spinner **Zoom** para adequar o tamanho real (Ex: digite `1.20` para aumentar o tamanho visual dos veios) [Passage 9].
4. Utilize os spinners **Mover Esq/Dir** e **Mover Cima/Baixo** (deslocamento síncrono de offsets X e Y) para mover a imagem e centralizar a parte mais bela do veio da rocha no centro do tampo tridimensional, garantindo um faturamento visual luxuoso para o cliente final [Passage 10, 61].
---
#### OPERAÇÃO 4: RECORTAR FURO DE COOKTOP E CUBA (USINAGENS CSG)
Para usinar de forma limpa o nicho para cooktop na bancada:
1. Na barra de ferramentas de **Shapes**, clique em **Retângulo** [Passage 4].
2. Desenhe uma peça com as dimensões de encaixe do cooktop (Ex: **Largura:** `0.56` m / **Profundidade:** `0.48` m) [Passage 41].
3. No painel de propriedades lateral, altere a cor no seletor **Cor** para **Molde Vermelho** [Passage 7, 8]. *Isso converte síncronamente o sólido em um cortador mecânico.*
4. Arraste o molde vermelho e posicione-o síncronamente no centro geométrico da bancada de cozinha [Passage 55, 58].
5. Com o molde selecionado, clique no botão superior **Recortar/Furar (Usinagem CSG)** (ícone de tesoura ou ferramenta) [Passage 57, 59].
6. O ERP executará síncronamente os cálculos em lote [Passage 59]: o molde vermelho desaparecerá, e a bancada de cozinha apresentará de imediato a furação interna perfeita de 56cm x 48cm no WebGL [Passage 59, 503]. O tampo receberá o carimbo imutável de usinagem, blindando sua engenharia [Passage 57].
---
#### OPERAÇÃO 5: TIRAR Perspectivas E GERAR O SLIDESHOW PDF COM CAPA IA
Para documentar o projeto de engenharia de forma inconfundível para o cliente:
1. Posicione a câmera virtual do Three.js em uma bela perspectiva de topo inclinada na tela [Passage 495].
2. Clique no ícone de câmera superior **Snapshot (Tirar Foto)** [Passage 3, 76].
3. O sistema desativará temporariamente as grades e renderizadores secundários [Passage 76], processará uma captura limpa de alta resolução e abrirá o painel **Revisar Captura do Projeto** [Passage 76, 79]. No campo de especificações, a IA de frustum listará de forma automática as peças e acabamentos visíveis (Ex: *"BANCADA DE COZINHA: 1 Peça de 2.00x0.60m, Material: Quartzito Taj Mahal, Usinada com furos de Cooktop"*) [Passage 77, 78]. Clique em **Salvar** para registrar a imagem no Álbum de Capturas [Passage 80].
4. Repita a operação tirando outras fotos de quinas e detalhes [Passage 76].
5. Clique no botão de toolbar superior **Gerar Apresentação (PDF)** [Passage 83].
6. No formulário ExtJS apresentado, informe o título (Ex: *Projeto Cozinha de Luxo - Residência Flamboyant*) [Passage 84]. Ative a chave **Inteligência Artificial (Capa) - Gerar fotorrealismo do ambiente para a Capa** [Passage 84] and clique em **GERAR** [Passage 84]. *O PHP executará síncronamente o Gemini SDK, compilará o descritivo de ambientes, gerará uma capa fotorrealista deslumbrante [Passage 467], montará as páginas do relatório A4 contendo as fotos e o termo de aceito de medidas técnico no PDF final [Passage 468], abrindo o arquivo para download na tela síncronamente [Passage 469].*
---
#### OPERAÇÃO 6: EXPORTAR PROJETO PARA PRECIFICAÇÃO NO ORÇAMENTO
Com a modelagem finalizada, assinada e homologada pelo cliente, clique no botão **Exportar Orçamento** [Passage 68].
O sistema validará os subitens lineares, as geometrias volumétricas das cubas usinadas e as posições dos acabamentos [Passage 68, 69]. Sendo aprovada a varredura síncrona [Passage 69], o ERP de forma automática e transparente injetará os itens no orçamento de destino do cliente [Passage 71, 461]: ele preencherá o comprimento e a largura das peças na grade, somará as metragens lineares de saias e frontões acoplados como subitens [Passage 461, 517], e cadastrará os custos e as vendas de beneficiamentos síncronamente na propostas comercial, permitindo que a mesa de faturamento emita os boletos e parcelas do contas a receber baseando-se estritamente na engenharia 3D real desenvolvida [Passage 461, 533].
---