# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Idioma

Responder sempre em **português (Brasil)**.

## Projeto

eCook-Plus LOJA — painel web SaaS multi-tenant (White Label) para restaurantes/filiais. Stack: PHP 8.x puro (sem framework), MariaDB/MySQL (PDO), HTML5/CSS3/JS vanilla (Fetch API), UI em glassmorphism. Não há build tool, bundler, gerenciador de pacotes (composer/npm) nem suíte de testes automatizados neste repositório — é servido diretamente por Apache/PHP (ver `.htaccess`, `setup.php`).

Nome/versão do app: `includes/app_config.php` (`ECOOK_APP_NOME`, `ECOOK_APP_VERSAO`).

Documentação de referência completa (ler antes de tarefas maiores): `README.md` e `CONVENCOES_DESENVOLVIMENTO.md`.

## Escopo das alterações

Mudanças mínimas e focadas; reutilizar funções e padrões existentes; **não refatorar código não relacionado à tarefa**. Sem over-engineering — evitar abstrações desnecessárias. Comentários só para lógica de negócio não óbvia. Testes só se solicitado ou com valor real. Commits só quando o usuário pedir explicitamente.

## Estrutura de diretórios

```
index.php              # Motor SPA/PWA, login, roteador AJAX, shell do painel
layout_login.php       # Tela de login
logout.php
paginas/               # Telas carregadas via AJAX ou carga inicial (markup, sem lógica pesada)
includes/              # Lógica de domínio, permissões, conexões, helpers
api/                   # Endpoints JSON (CRUD, downloads, integrações) — delegam para includes/
css/, js/              # Um par por módulo quando necessário
sql/                   # Scripts DDL/DML de referência
IMG/                   # Logos e imagens estáticas
```

`paginas/*.php` (markup) → `includes/*.php` (lógica de domínio) → `api/*.php` (camada HTTP JSON, delega para includes/). Manter essa separação.

## Arquitetura multi-tenant

### Conexões de banco

| Arquivo | Uso |
|---------|-----|
| `includes/conecta.php` | Banco **operacional da loja logada** (tenant da sessão ou padrão local) |
| `includes/conecta_loja.php` | Banco fixo da instalação LOJA (`simsoftdsv_ecookplus_loja`) — ADM local |
| `includes/conecta_master.php` | Orquestrador SaaS (empresas, login global, usuários master) |
| `includes/conecta_tenant.php` | Conexão dinâmica por credenciais de tenant |

**Regra:** em telas/APIs que operam dados da loja do usuário logado, usar `obterPdoBancoLojaLogada()` de `includes/perfil_acesso.php` (retorna `['pdo' => PDO, 'nome_banco' => string]`).

### Login (3 camadas em `index.php`)

1. **ADM local** — `cad_usuarios` no banco LOJA, perfil `ADM`.
2. **ADM Master / Dono SaaS** — `usuarios_master` ou `empresas` no banco master.
3. **Funcionários** — `login_global` + tenant da empresa no master.

Sessão relevante: `logado`, `usuario_nivel`, `filial_id`, `tenant_db_*`, `adm_empresa_selecionada`, `emp_nome`.

Banco legado da loja (tenant) espelha o eCook Desktop Delphi: `cad_produto` (singular), `cad_grupo_produtos`, `fat_geral`, `cad_ficha_producao_*`, etc.

## Perfis e permissões (RBAC)

**Estado atual:** não existe módulo de "Controle de Permissão". O RBAC é simples e hardcoded — `cad_perfil` guarda só o nome do perfil (`per_id`, `per_nome`); o acesso é decidido por comparações de string em PHP sobre `$_SESSION['usuario_nivel']`. Sem DDL em `sql/` para `cad_perfil` ainda.

Helpers em `includes/perfil_acesso.php`:

| Termo | Função | Quem |
|-------|--------|------|
| Admin / ADM | `isUsuarioAdmin()` | `usuario_nivel === 'ADM'` |
| Usuário da Loja | `isUsuarioLoja()` | DONO, GERENTE, equipe (qualquer um que não seja ADM) |
| Só Admin | `isSomenteAdmin()` | cadastro usuário global, config visual |
| Admin + Loja | `isAdminOuLoja()` | relatórios, espelho, cadastros operacionais |

Não confundir: ADM técnico/SaaS ≠ usuário operacional da loja. `usu_nivel_id == 1` protege o usuário/perfil Master — não pode ser excluído nem inativado.

A sessão guarda sempre uma string (`usuario_nivel`); não há consulta centralizada ao banco para autorizar telas — cada tela/API checa manualmente (`isAdminOuLoja()`, `in_array(..., ['ADM','DONO'])`, etc.). Se for evoluir este módulo, ver diretrizes detalhadas em `.cursorrules` antes de mexer.

## Roteamento e SPA

- Página: `index.php?p=<chave>` (ex.: `index.php?p=cadastro_produtos`)
- Menu ativo: `index.php?p=<chave>&m=menu-<chave>`
- AJAX: `index.php?ajax=true&p=<chave>`
- Conteúdo dinâmico rola em `#conteudo-dinamico` — listeners de scroll devem usar esse elemento, não `window`.

### Registrar nova tela

1. Criar `paginas/nome_tela.php`.
2. Adicionar rota em `menuRotasPorNivel()` em `includes/menu_navegacao.php`.
3. Relatório → incluir em `menuPaginasRelatorios()`; cadastro → `menuPaginasCadastros()`; configuração → `menuPaginasConfiguracoes()`.
4. Adicionar item no menu em `includes/sidebar.php` (ou submenu).
5. Relatório pesado → considerar carga assíncrona em `$paginasCargaInicialAssincrona` no `index.php`.

## Padrões de código PHP

### SQL e segurança

1. Sempre PDO parametrizado — `prepare()` + `execute([])`. Nunca concatenar variáveis em SQL.
2. Validação de tipos (ex.: cores hex: `preg_match('/^#[a-fA-F0-9]{6}$/i', $cor)`).
3. Try/catch em operações de banco (`PDOException`); não expor erros crus ao usuário.
4. Uploads: validar MIME com `finfo`; restringir tipos seguros.

### APIs (`api/*.php`)

```php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
// Verificar sessão/permissão
// obterPdoBancoLojaLogada() quando operar banco da loja
echo json_encode([...], JSON_UNESCAPED_UNICODE);
```

Estrutura JSON padrão: `{ "sucesso": true|false, "mensagem": "...", "dados_extras": ... }`. APIs internas usam parâmetro `acao` via GET/POST (`listar`, `obter`, `salvar`). APIs externas (ex.: `criar_empresa.php`) protegidas com `HTTP_X_API_KEY`.

### Lógica de negócio

Regras reutilizáveis em `includes/<modulo>.php`; a página e a API incluem o mesmo include de domínio. Prefixos de funções por módulo (`cadProd*`, `espelhoComanda*`). CSS/JS por módulo versionados via query string (`?v=N`).

## UI / UX

- Glassmorphism: classes `.glass-card`, variáveis CSS `--cor-primaria`, `--cor-secundaria`, `--cor-texto`. Tema carregado via `includes/tema_visual.php` (tabela `config`).
- Layout de cadastros (padrão PROVIDA → Web): `filterbar` (filtros/ações/toggle) + `list-summary` + grid de cards ou tabela (`products-grid`) + modal overlay (`produto-overlay`/`produto-card`) + toast (`produto-toast`). Referências: `paginas/cadastro_produtos.php`, `paginas/cadastro_grupos.php`, `paginas/cadastro_usuario.php`. Detalhes completos no `README.md` (seção "Modelo de Layout para Cadastros").
- Relatórios carregados via AJAX devem emitir o wrap compartilhado:
  ```php
  require_once __DIR__ . '/../includes/estilos_relatorio_wrap.php';
  renderEstilosRelatorioWrap();
  ```
  Classes `espelho-comandas-wrap` / `graficos-container`.
- Datas na interface: `dd/mm/aaaa hh:mm` (PHP: `date('d/m/Y H:i', ...)`; JS: converter antes de exibir, ver `formatDataHora()` em `js/config_log.js`). Inputs `<input type="date">` continuam em `YYYY-MM-DD`. APIs JSON podem retornar ISO/MySQL; a formatação fica na camada de exibição.

## Responsividade

| Breakpoint | Uso |
|------------|-----|
| ≤ 480px | Celulares estreitos |
| ≤ 768px | Mobile — drawer sidebar, formulários empilhados |
| ≤ 900px | Tablet |
| ≥ 769px | Desktop — sidebar fixa |

Arquivos centrais: `css/style.css` (shell), `css/responsive.css` (regras mobile compartilhadas, incluído em `index.php`), `includes/estilos_relatorio_wrap.php` (relatórios). Evitar larguras fixas; tabelas largas usam `.resumo-canais-scroll`; modais `width: 96vw; max-height: 92dvh` no mobile.

## Regra de negócio — delivery (`fat_geral`)

Vendas delivery: `FAT_TIP_LOC = 2`. Identificação do app:

| App | Condição |
|-----|----------|
| Neemo | `FAT_IDORDER` preenchido |
| iFood | `FAT_IDORDER_IFOOD` preenchido |
| Demais apps | `FAT_APP_IDORDER` + `FAT_APP_NOME` correspondente |

Funções em `includes/espelho_comanda.php`: `espelhoComandaMontarSqlFiltroAppsDelivery()`, `espelhoComandaResolverCodAppDelivery()`.

## Cadastro de produtos (Delphi → Web)

Fonte legado: `FRM_CADASTRO_PRODUTOS.pas` (repositório Delphi compartilhado, fora deste repo). Tabela principal: `cad_produto` (singular). Implementação web em fases (MVP → fiscal completo): `paginas/cadastro_produtos.php`, `includes/cadastro_produtos.php`, `api/cadastro_produtos.php`. Grupo (`cad_grupo_produtos`) define sabores, meia/inteira e opcionais. Detalhes das 12 abas do formulário legado e plano de fases: ver `README.md`.

## Resposta obrigatória ao final de tarefas que alterem o repositório

Regra `alwaysApply` em `.cursor/rules/arquivos-modificados.mdc`. Toda resposta que altera arquivos deve terminar com:

```markdown
### Arquivos modificados

**Criados** (se houver)
- caminhos relativos à raiz do projeto

**Alterados** (se houver)
- caminhos relativos à raiz do projeto
```

Se nada foi alterado: *Nenhum arquivo modificado.* Incluir **todos** os arquivos tocados (PHP, CSS, JS, APIs, menu, rotas em `index.php`, includes compartilhados, documentação criada na mesma tarefa) — não omitir arquivos pequenos.

## Arquivos de referência rápida

| Assunto | Arquivo |
|---------|---------|
| Convenções | `CONVENCOES_DESENVOLVIMENTO.md` |
| Documentação técnica completa | `README.md` |
| Versão do app | `includes/app_config.php` |
| Rotas e menu | `includes/menu_navegacao.php`, `includes/sidebar.php` |
| Permissões | `includes/perfil_acesso.php` |
| Tema visual | `includes/tema_visual.php` |
| Wrap de relatórios | `includes/estilos_relatorio_wrap.php` |
| Modelo CRUD | `paginas/cadastro_usuario.php`, `paginas/cadastro_produtos.php` |
| Modelo API | `api/cadastro_produtos.php` |
| Log de acesso | `includes/mov_log_acesso.php`, `api/mov_log.php` |
