# 📚 Documentação Técnica - eCook Plus

**Visão Geral**
O **eCook Plus** é uma plataforma SaaS (Software as a Service) com arquitetura **White Label** orientada a multi-inquilinos (multi-tenant). Projetada com foco em alta performance e escalabilidade, a aplicação web segue diretrizes para PWA (Progressive Web App), permitindo uma experiência fluida e nativa para usuários e administradores de restaurantes/filiais.

---

## 🛠 Stack Tecnológico

*   **Backend:** PHP 8.x (Estrutura modular baseada em APIs e classes).
*   **Banco de Dados:** MariaDB / MySQL (Engine InnoDB) com relacionamentos `ON DELETE CASCADE` para integridade referencial.
*   **Frontend / UI:** HTML5, CSS3 com variáveis nativas, JavaScript (Fetch API para requisições assíncronas).
*   **Padrão de Design UI:** Glassmorphism (Uso intensivo de painéis translúcidos, `backdrop-filter` e bordas suaves) garantindo um visual Premium.
*   **Integrações Previstas:** Estrutura base preparada para mensageria assíncrona (WhatsApp) via **Evolution API** e automações (n8n).

---

## 🗄 Arquitetura do Banco de Dados

A estrutura de dados foi rigorosamente normalizada para isolar informações de diferentes empresas, garantindo a integridade do modelo SaaS.

### Entidades Principais:
1.  **`cad_empresas`**: Core do sistema multi-tenant. Armazena as empresas (clientes) e seus respectivos subdomínios (ex: `ecookplus`, `teste123`).
2.  **`cad_filiais`**: Vinculada às empresas, permite que um único cliente gerencie múltiplas lojas/unidades físicas.
3.  **`cad_perfil`**: Gerenciamento de RBAC (Role-Based Access Control). Define níveis como `ADM`, `Gerente`, `Suporte`, etc.
4.  **`cad_usuarios`**: Tabela central de autenticação, amarrada à Empresa, Filial e Perfil. Senhas são protegidas com `password_hash()` (algoritmo bcrypt/Argon2).
5.  **`config`**: Motor da funcionalidade White Label. Armazena configurações independentes por `cfg_filial_id`, como:
    *   `cfg_cor_primaria`: Cor principal do painel (fundo).
    *   `cfg_cor_secundaria`: Cor de destaque (botões, ícones).
    *   `cfg_logo_caminho`: Caminho físico da imagem do logotipo no servidor.
6.  **Catálogo (`cad_categorias` e `cad_produtos`)**: Armazena o cardápio, estritamente amarrado ao ID da filial para isolamento de dados.

### Vendas legadas (`fat_geral`) — identificação do APP de delivery

Toda venda de **delivery** possui `FAT_TIP_LOC = 2`. Para saber **de qual aplicativo** a venda pertence, use o campo de identificador do pedido conforme a plataforma:

| APP | Condição |
|-----|----------|
| **Neemo** | `FAT_TIP_LOC = 2` **e** `FAT_IDORDER` preenchido (≠ vazio) |
| **iFood** | `FAT_TIP_LOC = 2` **e** `FAT_IDORDER_IFOOD` preenchido (≠ vazio) |
| **Demais apps** (Wabiz, CCM, Simsoft.App, Anota AI, Menu eCook etc.) | `FAT_TIP_LOC = 2` **e** `FAT_APP_IDORDER` preenchido (≠ vazio) |

**Exemplos SQL:**

```sql
-- Neemo
WHERE fat_geral.FAT_TIP_LOC = 2
  AND TRIM(COALESCE(fat_geral.FAT_IDORDER, '')) <> ''

-- iFood
WHERE fat_geral.FAT_TIP_LOC = 2
  AND TRIM(COALESCE(fat_geral.FAT_IDORDER_IFOOD, '')) <> ''

-- Outros apps de delivery
WHERE fat_geral.FAT_TIP_LOC = 2
  AND TRIM(COALESCE(fat_geral.FAT_APP_IDORDER, '')) <> ''
```

> **Implementação web:** filtros e identificação de app no Espelho de Comandas usam `espelhoComandaMontarSqlFiltroAppsDelivery()` e `espelhoComandaResolverCodAppDelivery()` em `includes/espelho_comanda.php`. Para demais apps, além de `FAT_APP_IDORDER` preenchido, o filtro exige `FAT_APP_NOME` correspondente ao app selecionado.

---

## ⚙️ Módulos e APIs Documentadas

### 1. Provisionamento de Empresas (`api/criar_empresa.php`)
Endpoint restrito utilizado pelos administradores do sistema para provisionar novos clientes no ambiente SaaS.

*   **Segurança:** Protegido via chave secreta (`HTTP_X_API_KEY`).
*   **Fluxo de Execução:**
    1.  Valida os dados de entrada via payload JSON.
    2.  Verifica colisão de `emp_subdominio`.
    3.  Cria a Empresa em `cad_empresas`.
    4.  Cria a filial "Matriz" em `cad_filiais`.
    5.  Provisiona o usuário Master (`cad_usuarios`) já criptografado e amarrado à filial e empresa.
    6.  Injeta a configuração visual padrão em `config` (Azul escuro/Azul claro e logo padrão).
*   **Retorno:** JSON com status HTTP adequado, devolvendo os IDs gerados para integração futura.

### 2. Personalização Visual White Label (`paginas/config.php` & `api/salvar_config_visual.php`)
Módulo voltado para os administradores das lojas (filiais) customizarem a identidade de seu painel.

*   **Frontend (Live Preview):** 
    *   Uso de inputs dinâmicos (`<input type="color">`) que disparam eventos de JS em tempo real.
    *   Atualização imediata das CSS Variables (`--cor-primaria`, `--cor-secundaria`) no DOM via `document.documentElement.style.setProperty`, criando um "Live Preview" sem recarregar a página.
    *   Pré-visualização do logotipo via `FileReader` nativo do JS.
*   **Backend (Persistência e Segurança):**
    *   Upload restrito a `MIME Types` seguros (`image/jpeg`, `image/png`, `image/svg+xml`) usando `finfo`.
    *   Exclusão automática do logo antigo no servidor físico com `unlink()` para evitar acúmulo de arquivos órfãos.
    *   Operação de banco com **MySQL Upsert** (`INSERT ... ON DUPLICATE KEY UPDATE`), garantindo que o painel nunca quebre por ausência de registro prévio e economizando requisições `SELECT`.
    *   Retorno com Timestamp Anti-cache (`?t=123456...`) para forçar o navegador a renderizar a nova imagem imediatamente.

---

## 📦 Cadastro de Produtos (referência Delphi → Web)

Documentação de referência para implementação futura do módulo web, espelhando o formulário legado do eCook Desktop.

**Fonte Delphi 2010:**
- `C:\Projetos - Git Hub\Ecook_Delphi_Compartilhado\FRM_CADASTRO_PRODUTOS.pas`
- `C:\Projetos - Git Hub\Ecook_Delphi_Compartilhado\FRM_CADASTRO_PRODUTOS.dfm`

**Status web:** ainda não implementado. O banco legado da loja já utiliza `cad_produto` (singular) em relatórios e dashboards — ver `includes/espelho_comanda.php`, `paginas/dashboard.php`, `includes/curva_abc_produtos.php`.

### Visão geral

Formulário modal central do eCook Desktop para **incluir, alterar ou clonar** produtos do cardápio/estoque. Não é apenas nome + preço: concentra operação de restaurante, fiscal, produção, imagens e integrações.

**Identificadores:**
| Campo | Descrição |
|-------|-----------|
| `ITE_CODIGOI` | ID interno (sequencial em `Config` → variável `CAD_PRODUTO_SEQCOD`) |
| `ITE_CODIGOL` | Código livre de 4 dígitos (ex.: `0054`); pode ser gerado automaticamente |

**Modos de abertura (variáveis Delphi):**
| Modo | Variável | Comportamento |
|------|----------|---------------|
| Novo | `VB_NOVO_REGISTRO = TRUE` | INSERT completo |
| Editar | `VS_CODIGO_ALTERAR` | UPDATE |
| Clonar | `VB_PRRODUTO_CLONAR = TRUE` | Carrega produto existente como base para novo registro |

### Abas do formulário (12 abas)

| # | Aba | Conteúdo principal |
|---|-----|-------------------|
| 1 | **Principais** | Grupo, classificação, flags (opcionais, combo, lançamento rápido, taxa de serviço, estoque na venda), matriz de preços (Mesa/Balcão/Delivery × Normal/Sabores/Meia-Inteira), margens, cálculo de custo (F12), fornecedores vinculados |
| 2 | **Impressão** | Locais de impressão (Mesa, Balcão, Disk), ticket unitário, ticket de conferência, senha para retirada |
| 3 | **Estoque** | Saldo mínimo, qtd. embalagem, unidade comercial, controle de rotatividade/falta na venda; exibe saldos da empresa |
| 4 | **Cód. Barras** | CRUD de múltiplos códigos (`cad_codigo_barras`) |
| 5 | **Fiscal** | Tributação SAT e NFe, NCM, CEST, origem, ST (MVA, alíquota etc.), ANP (revenda de gás); habilitada só se `Config.TRIBUTACAO_FISCAL = 1` |
| 6 | **Imagens** | Foto em BLOB (`cad_arquivos` → campo `ITE_LISTAIMG`) |
| 7 | **Ingredientes** | Dois campos de texto livre (`ITE_INGRED1`, `ITE_INGRED2`) |
| 8 | **Produtos Combo** | Itens filhos do combo (`cad_produto_combo`); aba só ativa se “Produto é combo = Sim” |
| 9 | **Ficha Técnica** | BOM/receita (`cad_ficha_producao_*`); só para classificação “Produção interna” |
| 10 | **Comissão do Produto** | Leitura de `cad_comissao_itens` (valores/% por Mesa, Balcão, Delivery) — **não grava nesta tela** |
| 11 | **Opcionais** | Lista produtos do grupo de opcionais (`GRU_OPCGRU` do grupo) — **somente consulta** |
| 12 | **Balança** | Produto pesado, descrição reduzida, tipo filtro (P/U), validade |

**Classificação do produto** (`ITE_COD_CLS` — combo fixo, não é tabela):
- `00` — Revenda
- `01` — Produção interna (habilita Ficha Técnica)
- `02` — Matéria prima
- `03` — Uso interno

### Regras de negócio relevantes

- O **grupo** (`cad_grupo_produtos`) define: aceita **sabores** (`GRU_ACTSAB`), **meia/inteira** (`GRU_ACTMEI`) e **grupo de opcionais** (`GRU_OPCGRU`).
- **Preços** variam por canal (Mesa / Balcão / Delivery) e por tipo (Normal, 4 sabores configuráveis via `Config.DESCRI_PROPRECO1..4`, Meia/Inteira).
- **Ficha técnica** recalcula custos do produto pai (atalho F12).
- **Gravação (F10)** persiste em cascata: produto → códigos de barras → combo → ficha → estoque → fornecedores → imagem.
- Atalhos: **F1** cadastros auxiliares (grupos etc.), **F5** validades (form externo `FRM_PRODUTO_VALIDADE`), **Esc** sair.
- Depende de **configurações globais** (`Config`): margens (`MARGEM_CUSTO_PRODUTO_*`), nomes dos sabores, revenda de gás (`REVENDA_DE_GAS`), bloqueio de estoque na venda, emissão fiscal (`TRIBUTACAO_FISCAL`) etc.

### Fluxo de gravação (Delphi)

```
Validar campos
  → Salvar imagem em cad_arquivos
  → INSERT ou UPDATE em cad_produto
  → GravaCodigoDeBarras
  → GravaCombo (se produto for combo)
  → GravaFicha (se classificação = Produção interna)
  → GravaEstoque
  → Gravar_Produto_Fornecedor
```

Procedures Delphi: `GravaProdutoNovo`, `GravaProdutoEditado`, `GravaCodigoDeBarras`, `GravaCombo`, `GravaFicha`, `GravaEstoque`, `Gravar_Produto_Fornecedor`, `Salvar_Imagem`.

### Tabelas envolvidas

#### Escrita (CRUD neste formulário)

| Tabela | Papel |
|--------|-------|
| `cad_produto` | Tabela principal — preços, flags, fiscal, margens, custos, balança |
| `cad_produto_estoque` | Estoque por empresa (`EST_CODEMP` + `EST_CODITE`); grava saldo mínimo |
| `cad_codigo_barras` | Múltiplos códigos de barras por produto |
| `cad_produto_combo` | Itens que compõem um combo (produto pai × filhos + qtd + preço) |
| `cad_ficha_producao_geral` | Cabeçalho da ficha técnica (1 registro por produto produzido) |
| `cad_ficha_producao_itens` | Ingredientes/insumos da ficha técnica |
| `cad_arquivos` | Imagem do produto (BLOB); referenciada por `ITE_LISTAIMG` |
| `cad_produto_fornecedor` | Vínculo produto × fornecedor × empresa |
| `Config` | Sequencial `CAD_PRODUTO_SEQCOD` e parâmetros globais |

#### Leitura / lookup (cadastros auxiliares)

| Tabela | Uso no formulário |
|--------|-------------------|
| `cad_grupo_produtos` | Grupo do produto; regras de sabores, meia e opcionais |
| `cad_local_imp` | Locais de impressão de produção |
| `cad_produto_origem` | Origem fiscal do produto |
| `cad_tributacao` | Perfis fiscais (SAT e NFe) |
| `cad_cst` | CST vinculado à tributação |
| `cad_cest` | Validação/descrição do CEST |
| `cad_tabela_ibpt` | Validação de NCM |
| `cad_unid_comercial` | Unidade de compra |
| `cad_fornecedor` | Seleção de fornecedores |
| `cad_empresa` | Exibição no grid de fornecedores |
| `cad_funcionario` | Operador no vínculo fornecedor |
| `cad_especie_doc` | Espécie de documento no fornecedor |
| `cad_comissao_itens` | Comissão por produto (somente leitura nesta tela) |
| `cad_produto` | Produtos filhos (combo, ficha, opcionais) |

#### Relacionada em tela externa

| Tabela | Observação |
|--------|------------|
| `cad_produto_validade` | Botão **F5 Validades** abre `FRM_PRODUTO_VALIDADE` (fora do `.pas` principal) |

**Total no escopo do formulário:** 21 tabelas (+ `cad_produto_validade` via atalho externo).

### Plano sugerido para implementação web

**Referências de padrão no projeto:**
- **Layout de listagem + modal (modelo):** seção [Modelo de Layout para Cadastros (Vue → Web)](#-modelo-de-layout-para-cadastros-vue--web) — baseado em `ProdutosPage.vue`
- Layout/CRUD existente: `paginas/cadastro_usuario.php`
- Convenções: `CONVENCOES_DESENVOLVIMENTO.md`
- Produto legado (regras de negócio): `includes/espelho_comanda.php`

**Entregáveis previstos:**
1. `paginas/cadastro_produtos.php` (listagem + formulário por abas)
2. APIs PHP para CRUD (`api/produtos/...` ou actions POST no padrão do projeto)
3. Entrada no menu/rotas (`index.php`)
4. CSS/JS mínimo seguindo white label existente
5. Permissões (ADM/DONO ou conforme perfil do projeto)

**Fases sugeridas:**
| Fase | Escopo |
|------|--------|
| **1 — MVP** | Abas 1, 2, 3, 6 + listagem/edição básica |
| **2** | Códigos de barras, combo, ficha técnica, fornecedores |
| **3** | Fiscal completo, balança, validades (F5), comissão |

**Antes de codar:** mapear colunas reais de `cad_produto` no banco da loja e comparar com os campos do INSERT/UPDATE Delphi (`GravaProdutoNovo` / `GravaProdutoEditado` em `FRM_CADASTRO_PRODUTOS.pas`).

---

## 🎨 Modelo de Layout para Cadastros (Vue → Web)

Referência visual e estrutural para **telas de cadastro** no eCook Plus Web. Baseado no projeto **PROVIDA** (Vue 3).

**Fonte Vue:**
- `C:\Projetos - Git Hub\PROVIDA\PV_Pedidos_Admin_Vue\src\pages\ProdutosPage.vue`
- Persistência do modo de visualização: `src/composables/useLayout.ts` (`viewMode_produtos`: `grid` | `list`)

**Uso:** replicar este padrão em PHP/HTML/CSS (adaptando variáveis white label `--cor-primaria`, `--cor-secundaria`) em cadastros futuros — produtos, grupos, fornecedores etc.

### Estrutura geral da página

```
page-layout
├── SidebarNav          (menu lateral — equivalente ao menu do eCook Plus)
└── page-content
    ├── TopBar          (título da tela, ex.: "Produtos")
    └── page-body       (padding: 24px 28px; mobile: 12px)
        ├── filterbar   (filtros + ações)
        ├── list-summary (contador: "N produto(s)")
        └── list        (cards OU tabela)
            ├── loading / error / empty
            └── conteúdo filtrado e ordenado
```

Modais sobrepostos (fora do fluxo normal):
- **Modal de edição/cadastro** (`produto-overlay`)
- **Modal banco de imagens** (`banco-overlay`) — opcional
- **Preview de imagem** (`image-preview-overlay`)
- **Toast de feedback** (`produto-toast`, fixo no rodapé)

### 1. Barra de filtros (`filterbar`)

Container flex com borda arredondada, fundo de superfície e `flex-wrap`.

**Lado esquerdo — `filterbar__filters`:**
| Elemento | Classe | Comportamento |
|----------|--------|---------------|
| Busca por ID | `filterbar__search filterbar__search--id` | Campo estreito (~80px) |
| Busca textual | `filterbar__search` | Placeholder livre (nome, marca…) — `flex: 1` |
| Select | `filterbar__select` | Ex.: categorias — opção “Todas” vazia |
| Switches | `filterbar__switch` + `filterbar__switches` | Toggles estilo iOS (Ativo, Disponível, etc.) — classe `.active` quando ligado |

**Lado direito — `filterbar__actions`:**
| Botão | Função |
|-------|--------|
| Ícone galeria | Banco de imagens (visualizar) |
| Ícone `+` | Adicionar registro (só se `canWrite`) |
| Ícone download | Exportar Excel |
| **View toggle** | Alternar **Grade (Cards)** vs **Lista (Tabela)** |

**Toggle de visualização (`filterbar__view-toggle`):**
- Dois botões 32×32px agrupados com borda comum
- `.filterbar__view-btn.active` → destaque (cor gold/ secundária)
- Ícones SVG: grade 2×2 = cards; linhas = lista
- Preferência persistida em memória (`useLayout`) — no PHP pode usar `localStorage`

**Filtragem:** client-side sobre array carregado; todos os filtros combinados com AND.

### 2. Resumo da listagem (`list-summary`)

Texto discreto acima da lista: `"{{ total }} produto(s)"` — fonte 13px, cor muted.

### 3. Modo Cards (`viewMode === 'grid'`)

Grid responsivo: `repeat(auto-fill, minmax(260px, 1fr))`, gap 20px.

**Card (`product-card`):**
- Clique no card inteiro → abre edição
- **Topo:** imagem 160px ou placeholder 📦
- **Corpo:** nome (bold, max 2 linhas), ID, marca, preço, badge de status (`.active` verde / `.inactive` vermelho)
- **Rodapé:** botões de ação com `@click.stop` — ✏️ Editar, ⧉ Clonar, 🖼 Ver imagem
- Hover: `translateY(-3px)`, sombra, borda destacada

### 4. Modo Lista (`viewMode === 'list'`)

Tabela CSS Grid (`products-grid`):

**Cabeçalho (`products-grid__header`):**
- Fundo cor primária, texto branco
- Colunas com botões `.sortable` — clique alterna asc/desc (indicador ▲/▼)
- Colunas exemplo: Produto, Marca, Categoria, Preço, Estoque, Estado, Disp., Ação

**Linhas (`product-entry` → `products-grid__row`):**
- Grid: `2.5fr 1.2fr 1.5fr 1fr 0.7fr 0.7fr 0.7fr auto`
- Clique na linha → edição
- Nome em bold + badge de ID inline (`product-id-badge`)
- Linhas ímpares com fundo alternado (`--pv-surface-2`)
- Hover: fundo cream
- Coluna Ação: mesmos botões do card (editar, clonar, imagem)

**Estados da lista:**
- `LoadingSpinner` — “Carregando…”
- `list__error` — erro com mensagem
- `list__empty` — “Nenhum produto encontrado.”

**Mobile (≤768px):** cabeçalho da tabela oculto; linhas viram flex wrap.

### 5. Modal de edição/cadastro (`produto-overlay`)

Overlay fullscreen semitransparente; card central max ~820px, max-height 92vh.

**Estrutura do modal:**
```
produto-card
├── produto-header     → título dinâmico + botão × fechar
├── produto-body       → scroll vertical
│   ├── produto-body__top (grid 1fr + 280px)
│   │   ├── produto-body__fields  (formulário)
│   │   └── produto-body__image   (preview + ações de imagem, sticky)
│   ├── campos full-width (ex.: textarea descrição)
│   └── pform-error (mensagem de validação)
└── produto-footer     → Cancelar | Salvar/Cadastrar
```

**Modos do modal:**
| Modo | Título | Ação |
|------|--------|------|
| `create` | Adicionar Produto | POST — botão “Cadastrar” |
| `edit` | Editar Produto | PUT — botão “Salvar” |
| clone | Adicionar Produto | POST com dados copiados + sufixo `[Cópia]` |

**Formulário (`pform-*`):**
- `pform-group` — label + input/select
- `pform-row` — grid 2 colunas (mobile: 1 coluna)
- `pform-row--checks` — checkboxes inline
- `pform-input` — inputs com borda arredondada, fundo surface-2
- Validação inline antes do submit; botão salvar com estado `disabled` + texto “Salvando…”

**Bloco de imagem (lateral direita):**
- Preview 300×300px (mobile: 180px, imagem sobe no topo)
- Botões: 🖼 Banco | 📤 Upload | ✕ Limpar
- Upload via input `file` oculto

**Feedback pós-salvar:**
- Toast fixo inferior (`produto-toast.success` / `.error`), auto-hide ~4s
- Fecha modal e recarrega listagem

### 6. Padrões de interação a replicar

| Ação | Comportamento |
|------|---------------|
| Clicar card/linha | Abre modal em modo `edit` |
| Botão ✏️ | Mesmo que clicar (stop propagation) |
| Botão ⧉ | Abre modal `create` com dados clonados |
| Ordenação | Client-side; toggle asc/desc no mesmo campo |
| Permissão escrita | Ocultar botões Novo/Editar/Clonar/Salvar se read-only |
| Export Excel | Gera planilha dos itens **filtrados e ordenados** |

### 7. Classes CSS principais (mapeamento para PHP)

Reutilizar nomenclatura BEM ao criar CSS no eCook Plus:

| Bloco | Uso |
|-------|-----|
| `.filterbar`, `.filterbar__filters`, `.filterbar__actions` | Barra superior |
| `.filterbar__view-toggle`, `.filterbar__view-btn` | Toggle cards/lista |
| `.list-summary` | Contador |
| `.product-card-grid`, `.product-card` | Modo cards |
| `.products-grid`, `.products-grid__header`, `.products-grid__row` | Modo lista |
| `.produto-overlay`, `.produto-card`, `.produto-header/body/footer` | Modal CRUD |
| `.pform-group`, `.pform-row`, `.pform-input` | Campos do formulário |
| `.produto-toast` | Feedback |

**Variáveis de tema (Vue):** `--pv-surface`, `--pv-border`, `--pv-gold`, `--pv-primary`, `--pv-cream` — no eCook Plus mapear para `--cor-primaria`, `--cor-secundaria` e tons derivados.

### 8. Adaptação para cadastro de produtos eCook

Combinar:
- **Regras de negócio e abas** → referência Delphi (seção anterior)
- **Layout listagem + modal** → este modelo Vue

Sugestão de evolução do modal Delphi (12 abas) dentro do padrão Vue:
- Manter listagem igual (filterbar + cards/lista)
- No modal, usar **abas internas** (`Tab_Principal`, `TAB_ESTOQUE`…) no `produto-body` em vez de formulário único simples
- Filterbar do PROVIDA pode ganhar filtros eCook: grupo, código livre, ativo, classificação

---

## 📱 Layout Responsivo (Mobile)

Todas as telas do painel foram revisadas para uso em **celular e tablet**. O shell principal (`index.php`) já possui menu lateral tipo **drawer** abaixo de 768px; as páginas carregadas em `#conteudo-dinamico` seguem os breakpoints abaixo.

### Breakpoints padrão

| Largura | Uso |
|---------|-----|
| **≤ 480px** | Celulares estreitos — grids em coluna única, mapas e KPIs compactos |
| **≤ 768px** | Celular / mobile — formulários empilhados, botões largura total, padding reduzido |
| **≤ 900px** | Tablet — grids duplos viram coluna, cabeçalhos de relatório empilham |
| **≥ 769px** | Desktop — sidebar fixa; opção de recolher (`collapsed`) |

### Arquivos centrais

| Arquivo | Função |
|---------|--------|
| `css/style.css` | Shell: sidebar drawer, overlay, topbar, `#conteudo-dinamico` |
| `css/responsive.css` | Regras mobile **compartilhadas** (toast, dashboards, modais, config) — incluído em `index.php` |
| `includes/estilos_relatorio_wrap.php` | Layout de **relatórios** (Espelho, Documentos Fiscais, Curva ABC, Caixa, Mapa) — filtros, KPIs, tabelas com scroll horizontal |
| `includes/btn_voltar_topo.php` | Botão “voltar ao topo” escuta scroll de `#conteudo-dinamico` (não só `window`) |

### Status por tela (`paginas/`)

| Tela | Responsividade |
|------|----------------|
| `graficos.php` | Completa — classe `graficos-financeiros-wrap`, grids com `min-width: 0`, ApexCharts redimensiona no mobile |
| `dashboard_operacional.php` | Completa — KPIs e ranking via `css/responsive.css` |
| `espelho_comandas.php` | Completa — via `estilos_relatorio_wrap.php` |
| `documentos_fiscais.php` | Completa — wrap + modais em `responsive.css` |
| `curva_abc_produtos.php` | Completa — wrap + filtros ABC no mobile |
| `relatorio_caixa.php` | Completa — wrap + abas analíticas `@900px` |
| `mapa_calor_delivery.php` | Completa — mapa redimensionado, controles empilhados `@900px` |
| `cadastro_produtos.php` / `cadastro_grupos.php` | Completa — `css/cadastro_produtos.css` (`@768px`) |
| `cadastro_usuario.php` / `cadastro_equipe.php` | Completa — CSS mobile-first inline |
| `config.php` | Completa — classe `config-visual-page`, botão salvar largura total |
| `config_log.php` | Completa — `css/config_log.css` (`@768px`) |
| `403.php` | Adequada — card centralizado com `max-width` |
| `layout_login.php` | Adequada — `@480px` no container de login |

### Diretrizes para novas telas

1. **Viewport:** `<meta name="viewport" content="width=device-width, initial-scale=1.0">` (já em `index.php`).
2. **Evitar larguras fixas** em formulários; preferir `flex-wrap`, `minmax()` e `width: 100%` em `@768px`.
3. **Tabelas largas:** envolver em `.resumo-canais-scroll` com `min-width` na tabela e scroll horizontal no mobile.
4. **Botões de ação** em filtros: empilhar e usar `width: 100%` abaixo de 768px (padrão do wrap de relatórios).
5. **Modais:** `width: 96vw`, `max-height: 92dvh` no mobile — ver `css/responsive.css`.
6. **Scroll interno:** o conteúdo rola em `#conteudo-dinamico`; listeners de scroll devem usar esse elemento, não apenas `window`.
7. **Relatórios novos:** reutilizar `renderEstilosRelatorioWrap()` e classes `espelho-comandas-wrap` / `graficos-container`.
8. **Teste manual:** Chrome DevTools → iPhone SE / Pixel + rotação landscape em telas com mapas ou tabelas.

---

## 🛡️ Padrões e Boas Práticas Adotadas

Para manter o nível de alta precisão e evitar débitos técnicos, todo o desenvolvimento deve seguir estas regras vitais:

1.  **Consultas Parametrizadas (PDO):** Nunca concatenar variáveis diretamente nas strings SQL. Utilizar sempre `prepare()` e `execute([])` para bloquear 100% de tentativas de SQL Injection.
2.  **Validação de Tipo e Regex:** Dados sensíveis, como cores em Hexadecimal, devem ser processados sob a máscara `preg_match('/^#[a-fA-F0-9]{6}$/i')` no PHP para evitar injeção de scripts no CSS.
3.  **Arquivos Completos:** Todas as classes e scripts devem ser mantidos de forma coesa, com blocos Try/Catch cobrindo todo o escopo de banco de dados (`PDOException`), evitando exposição de erros crus no Front-end.
4.  **Respostas em JSON Uniformes:** Toda API deve retornar um cabeçalho explícito (`application/json`) e uma estrutura previsível: `{"sucesso": bool, "mensagem": string, "dados_extras": mixed}`.
5.  **Formatação de datas na interface:** Toda data/hora exibida ao usuário na tela deve usar o padrão brasileiro **`dd/mm/aaaa hh:mm`** (ex.: `16/06/2026 14:30`).
    *   **PHP (renderização server-side):** `date('d/m/Y H:i', $timestamp)` ou equivalente após `strtotime()`.
    *   **JavaScript (listagens/modais AJAX):** converter valores vindos do banco (`YYYY-MM-DD HH:MM:SS`) antes de exibir — ver `formatDataHora()` em `js/config_log.js`.
    *   **Filtros `<input type="date">`:** manter `YYYY-MM-DD` (padrão HTML); apenas a **apresentação** na grade, detalhes e relatórios usa `dd/mm/aaaa hh:mm`.
    *   APIs JSON podem continuar retornando ISO/MySQL; a formatação visual fica no PHP/JS da tela.

---
*Fim do Documento.*