# DGestor Padaria — Especificação completa para desenvolvimento autônomo

Versão do documento: 1.0 — 02/10/2026
Dono do produto: Deivid (DGestor)
Executor: agente de desenvolvimento autônomo (Jarvis)
Pasta do projeto: `C:\wamp64\www\Dgestor_padaria`

Este documento é a fonte única de verdade. Leia inteiro antes de escrever a primeira linha de código.
Quando algo não estiver aqui, siga a seção 0.4 (como decidir sozinho).

---

## 0. Regras para o agente (leia primeiro)

### 0.1 Missão

Construir do zero um sistema SaaS de gestão para padarias, chamado **DGestor Padaria**, com:
PDV/caixa, comanda de cartão com código de barras, balcões configuráveis, venda por peso (balança),
cardápio/comanda digital, estoque (entrada, saída, perdas, inventário), produção com ficha técnica,
encomendas, financeiro, NFC-e, relatórios e licenciamento compatível com o Painel DGestor.

O sistema precisa ser **bonito, atrativo e principalmente intuitivo**: uma atendente de balcão
sem experiência com computador deve conseguir usar a tela do balcão em menos de 5 minutos de explicação.

### 0.2 Modo de trabalho autônomo

1. Trabalhe **fase por fase**, na ordem da seção 8. Não pule fases.
2. Antes de começar uma fase, escreva no `PROGRESSO.md` o que vai fazer.
3. Ao terminar cada fase: rode as migrations do zero (`php artisan migrate:fresh --seed`), rode todos os
   testes (`php artisan test`), e só marque a fase como concluída se tudo passar.
4. Faça commit git ao fim de cada tarefa relevante, com mensagem em português
   (ex.: `feat(cartoes): leitura de cartão abre comanda`). Inicialize o repositório git na fase 0.
5. Atualize o `PROGRESSO.md` depois de cada tarefa: feito, decisões tomadas, pendências.
6. Se travar num problema por mais de 3 tentativas, registre em `PROGRESSO.md` na seção
   "Bloqueios", contorne (mock, flag desligada) e siga para a próxima tarefa. Nunca pare o trabalho inteiro.
7. Ao final de tudo, escreva em `PROGRESSO.md` um resumo do que ficou pronto, como testar,
   e a lista do que depende do Deivid (seção 11).

### 0.3 Proibições absolutas

- Não mexa em **nenhuma outra pasta** de `C:\wamp64\www` além de `Dgestor_padaria`.
  As pastas `pdv_churras`, `jau`, `pico`, `brasa_clone` e outras são sistemas de clientes reais.
- Não publique nada na HostGator, não acesse FTP, não use credenciais reais de nenhum cliente.
- Não coloque senha, token, chave ou dado de cliente dentro do código. Tudo sensível vai no `.env`
  (que fica fora do git). Use `.env.example` com valores fictícios.
- Não emita NFC-e em ambiente de produção. Só homologação ou mock.
- Não apague bancos de dados que não sejam o do próprio projeto (`dgestor_padaria`, `dgestor_padaria_test`).

### 0.4 Como decidir sozinho quando algo não estiver especificado

Pergunte-se, nesta ordem:
1. Qual opção é mais simples para a atendente/dono da padaria? Escolha essa.
2. Qual opção tem menos cliques e menos digitação? Escolha essa.
3. Qual opção segue o padrão que já existe no próprio projeto? Escolha essa.
Registre a decisão em `PROGRESSO.md` → "Decisões tomadas sem especificação".

---

## 1. Visão do produto

### 1.1 Como funciona uma padaria com este sistema

1. **Antes de abrir:** a produção faz pães, bolos e salgados registrando **ordens de produção**.
   O sistema dá entrada no produto pronto e baixa automaticamente os insumos pela **ficha técnica**.
2. **Entrada do cliente:** o cliente pega um **cartão-comanda** (cartão plástico com código de barras).
3. **Balcões:** cada balcão (Pães, Lanchonete, Doces, Frios… — cada padaria cadastra os seus)
   lê o cartão e lança os itens: lendo o código do produto, tocando no produto na tela
   ou lendo a **etiqueta da balança** (produto vendido por peso).
   Itens de preparo (lanche, café, suco) vão para a tela/impressora da cozinha.
4. **Caixa:** o cliente entrega o cartão no caixa. O operador lê o cartão, confere, recebe
   (dinheiro, Pix, débito, crédito, misto), emite NFC-e e o cartão volta a ficar livre.
5. **Venda direta:** o caixa também vende sem cartão (cliente que só compra no caixa).
6. **Encomendas:** bolos e salgados encomendados com data de retirada, sinal pago e
   saldo cobrado na retirada.
7. **Gestão:** dono vê vendas, margens, perdas, estoque baixo, contas a pagar/receber e fluxo de caixa.

### 1.2 Público e contexto

- Padarias pequenas e médias, de 1 a ~10 balcões, 1 a 3 caixas.
- Usuários com pouca familiaridade com tecnologia. Ambiente barulhento e corrido.
- Equipamentos: PCs simples com Windows, tablets Android, leitores de código de barras USB
  (funcionam como teclado), impressoras térmicas 58/80 mm, balanças etiquetadoras.
- Internet às vezes instável.

### 1.3 Modelo SaaS

- **Uma instalação por cliente** (subdomínio próprio, ex.: `padariaxyz.dgestor.com.br`) com
  **banco MySQL próprio**, igual ao DGestor atual.
- Dentro de uma instalação: uma empresa, uma ou mais filiais.
- Licença controlada remotamente pelo **Painel DGestor** (seção 6.2).
- Teste grátis de 14 dias, depois assinatura.

---

## 2. Decisões técnicas (stack)

| Item | Escolha | Motivo |
| --- | --- | --- |
| Linguagem | PHP 8.2+ | Roda no WampServer local e na HostGator compartilhada |
| Framework | Laravel 11 | Estrutura, migrations, autenticação, testes, filas, agendamento |
| Banco | MySQL 8 / MariaDB 10.6+ | Padrão da HostGator; mesmo modelo de banco por cliente |
| Telas administrativas | Blade + Livewire 3 | Telas reativas sem SPA, fácil de manter |
| Telas de operação (balcão, caixa, cozinha) | Blade + Alpine.js + `fetch` para API JSON interna | Resposta instantânea à leitura de código, sem ida e volta pesada |
| CSS | Tailwind CSS 3 + componentes próprios (seção 4) | Visual consistente e moderno |
| Ícones | Lucide (SVG inline via componente Blade) | Leve, limpo, consistente |
| Gráficos | Chart.js | Simples, roda no navegador |
| Build | Vite, rodado **localmente**; a pasta `public/build` **vai no git** | HostGator compartilhada não tem Node |
| Testes | PHPUnit/Pest (feature tests) | Cada regra de negócio crítica testada |
| Filas e agendamentos | `QUEUE_CONNECTION=database` + cron `schedule:run` a cada minuto | Funciona em hospedagem compartilhada |
| Tempo real (cozinha, cartões) | Polling leve (a cada 3–5 s) com endpoint enxuto | Hospedagem compartilhada não suporta WebSocket |
| PWA | `manifest.json` + service worker simples | Instalar no tablet/celular como app |
| Fuso / idioma | `America/Sao_Paulo`, `pt_BR` em tudo | — |

**Verificação inicial obrigatória (fase 0):** rode `php -v`. Se a versão local for menor que 8.2,
registre em "Bloqueios" e use Laravel 10 (PHP 8.1) — o restante da especificação vale igual.

### 2.1 Convenções de código

- Nomes de tabelas e colunas em português, `snake_case`, plural nas tabelas (`produtos`, `cartoes`).
- Models em português no singular (`Produto`, `Cartao`, `Balcao`).
- Dinheiro: `DECIMAL(12,2)`. Quantidades: `DECIMAL(12,3)` (para kg). Nunca `float`.
- Todas as tabelas operacionais têm `empresa_id` e `filial_id` (quando fizer sentido).
- Soft delete (`deleted_at`) em cadastros (produtos, clientes, fornecedores, balcões, usuários).
- Toda regra de negócio fica em **Services** (`app/Services/...`), nunca em controller ou view.
  Ex.: `ComandaService::lancarItem()`, `CaixaService::fecharComanda()`, `ProducaoService::registrar()`.
- Toda operação que mexe em dinheiro ou estoque roda dentro de `DB::transaction()`.
- Movimentos de estoque e de caixa são **imutáveis**: correção é um novo lançamento de estorno, nunca UPDATE/DELETE.
- Validação com Form Requests. Mensagens em português.
- Autorização com Policies + Gates (seção 5).
- Datas exibidas `dd/mm/aaaa`, horas `HH:mm`, dinheiro `R$ 1.234,56`, peso `0,350 kg`.

### 2.2 Estrutura de pastas

```
Dgestor_padaria/
├── app/
│   ├── Http/Controllers/        (finos: recebem, chamam Service, devolvem view/JSON)
│   ├── Http/Controllers/Api/    (endpoints JSON das telas de operação)
│   ├── Livewire/                (telas administrativas)
│   ├── Models/
│   ├── Services/                (regras de negócio)
│   ├── Services/Fiscal/         (interface EmissorFiscal + adaptadores)
│   ├── Services/Pagamento/      (interface GatewayPagamento + adaptadores)
│   ├── Support/CodigoLido.php   (decodificador universal de códigos — seção 6.8)
│   └── Policies/
├── database/migrations/ seeders/ factories/
├── resources/views/
│   ├── components/ui/           (design system — seção 4)
│   ├── layouts/                 (app, operacao, publico, instalador)
│   └── ...
├── resources/js/ resources/css/
├── public/build/                (assets compilados — vão no git)
├── tests/Feature/ tests/Unit/
├── docs/                        (manual do usuário gerado no fim — seção 9.3)
├── ESPECIFICACAO_DGESTOR_PADARIA.md
├── PROGRESSO.md
└── .env.example
```

---

## 3. Instalação local (WampServer)

1. Projeto em `C:\wamp64\www\Dgestor_padaria`, banco `dgestor_padaria` (usuário `root`, sem senha, só local).
2. Acesso local via VirtualHost `http://padaria.local` apontando para `public/`.
   Se não conseguir criar VirtualHost, use `php artisan serve` e registre em `PROGRESSO.md`.
3. `.env.example` com: `APP_NAME="DGestor Padaria"`, `APP_LOCALE=pt_BR`, `APP_TIMEZONE=America/Sao_Paulo`,
   `DB_*`, `DGESTOR_LICENSE_KEY=`, `DGESTOR_MASTER_PASSWORD_HASH=`, `DGESTOR_SSO_SECRET=`, `DGESTOR_EMPRESA_SLUG=`,
   `FISCAL_PROVEDOR=mock`, `FISCAL_AMBIENTE=homologacao`.
4. Seeder de demonstração (`DemoPadariaSeeder`) com uma padaria fictícia completa:
   "Padaria Pão Dourado", 1 filial, balcões Pães / Lanchonete / Doces / Frios, 60 produtos realistas
   (pão francês por kg, sonho, bolo de cenoura, coxinha, café, pingado, misto quente, presunto por kg…),
   insumos (farinha, açúcar, ovos, leite, fermento, manteiga…), fichas técnicas, 100 cartões,
   usuários de cada perfil (senha `123456`), 30 dias de vendas fictícias para os relatórios terem dados.

---

## 4. Design, identidade visual e UX (obrigatório em TODAS as telas)

### 4.1 Princípios

1. **Óbvio na primeira olhada.** Cada tela tem UMA ação principal, em destaque, no mesmo lugar.
2. **Leitor primeiro.** Nas telas de operação o foco do cursor fica sempre no campo de leitura;
   o operador nunca precisa clicar antes de passar o leitor.
3. **Toque grande.** Botões de operação com no mínimo 56 px de altura; produtos em cards grandes com foto.
4. **Feedback imediato.** Toda leitura/ação dá retorno visual (destaque verde/vermelho) e sonoro
   (bip curto de sucesso, bip duplo grave de erro) em menos de 300 ms.
5. **Linguagem da padaria.** "Cartão", "Balcão", "Fechar conta", "Receber", "Fornada" — nunca jargão técnico
   ("registro", "entidade", "request", "erro 500").
6. **Errar é seguro.** Toda ação destrutiva pede confirmação clara; cancelamentos de item/venda exigem
   motivo e, se configurado, senha de gerente. Sempre há "Desfazer" para o último item lançado.
7. **Nada vazio.** Toda lista vazia mostra ilustração simples + frase + botão do próximo passo
   ("Nenhum balcão ainda. Crie o primeiro balcão").

### 4.2 Identidade visual

- Estilo: **quente, apetitoso e limpo** — remete a pão, forno e café, mas com interface moderna.
- Paleta (definir como tokens CSS / Tailwind `theme.extend.colors`):
  - `primaria` (crosta/caramelo): `#C2410C` (hover `#9A3412`, claro `#FFEDD5`)
  - `secundaria` (café): `#3F2A1E`
  - `fundo`: `#FFFBF5` (creme), cards `#FFFFFF`, bordas `#F1E4D3`
  - `texto`: `#1F1A17`, texto suave `#6B5E55`
  - `sucesso` `#15803D`, `alerta` `#B45309`, `erro` `#B91C1C`, `info` `#1D4ED8`
- **Modo escuro** opcional (alternador no perfil) — obrigatório para a tela da cozinha (fundo escuro).
- Fonte: **Inter** (interface) e **Nunito** (títulos), via Google Fonts com fallback de sistema.
  Tamanhos: base 16 px; telas de operação base 18 px; valores de total 32–48 px em negrito.
- Cantos arredondados `rounded-xl` (12 px) em cards, `rounded-lg` em botões e campos.
- Sombras suaves (`shadow-sm`), sem gradientes chamativos.
- Logomarca da padaria (upload) aparece no menu, no login, no cupom e no cardápio digital.
  A cor primária pode ser personalizada pela padaria (Configurações → Aparência), com sugestão automática
  extraída da logo; garanta contraste mínimo AA ao aplicar.
- Rodapé fixo discreto: "DGestor Padaria © 2026" (não editável pela padaria).

### 4.3 Componentes do design system (Blade, em `resources/views/components/ui/`)

Crie e use sempre estes componentes — nunca HTML solto repetido:
`button` (variantes: primario, secundario, perigo, fantasma; tamanhos sm/md/lg/xl), `input`, `money-input`
(máscara R$), `weight-input` (kg com 3 casas), `select`, `search-select` (com busca), `toggle`, `checkbox`,
`card`, `stat-card` (número grande + variação), `badge` (status coloridos), `table` (com ordenação, busca,
paginação e versão em cards no celular), `modal`, `drawer` (painel lateral), `toast` (canto superior direito),
`empty-state`, `confirm-dialog`, `tabs`, `stepper` (assistentes), `page-header` (título + descrição + ação
principal), `keyboard-hint` (mostra atalho de teclado no botão), `skeleton` (carregamento).

### 4.4 Layouts

1. **Layout administrativo** (`layouts/app`): menu lateral recolhível com ícones e grupos
   (Início, Vender, Produção, Estoque, Encomendas, Financeiro, Fiscal, Relatórios, Cadastros, Configurações),
   barra superior com filial atual, busca global (Ctrl+K: busca produto, cliente, encomenda, tela),
   notificações e usuário. No celular o menu vira barra inferior com 5 atalhos + "Mais".
2. **Layout de operação** (`layouts/operacao`): tela cheia, sem menu lateral, para Balcão, Caixa e Cozinha.
   Topo fino com nome do balcão/caixa, operador, relógio, indicador de conexão (verde/vermelho) e botão "Sair da operação".
3. **Layout público** (`layouts/publico`): cardápio digital e acompanhamento de encomenda, mobile-first.
4. **Layout instalador**: assistente em etapas centralizado.

### 4.5 Padrões de interação

- **Atalhos de teclado** visíveis nos botões das telas de operação: F2 buscar produto, F4 quantidade,
  F6 desconto, F8 cancelar item, F9 receber, F10 finalizar, Esc voltar, Ctrl+Z desfazer último item.
- Busca de produto por nome, código ou PLU, com tolerância a acento ("pao" encontra "Pão").
- Formulários: rótulo acima do campo, exemplo no placeholder, erro em vermelho abaixo do campo, botão salvar
  sempre visível (fixo no rodapé em formulários longos).
- Salvar mostra toast "Salvo!"; nunca recarregar a página inteira sem necessidade.
- Tabelas: filtros como "chips" no topo, busca instantânea, exportar CSV/Excel e PDF.
- Responsivo de 360 px (celular) a 1920 px. Telas de operação otimizadas para 1366×768 e tablets 10".
- Acessibilidade: contraste AA, foco visível, `aria-label` em botões de ícone, navegação por teclado.
- Ajuda contextual: ícone "?" no `page-header` abre um drawer com 3–5 passos de como usar aquela tela.

### 4.6 Primeira experiência (onboarding)

Após instalar, o dono vê um **assistente de configuração** (stepper, pode pular e voltar depois):
1. Dados da padaria e logo → 2. Cor da marca → 3. Balcões (sugere Pães, Lanchonete, Doces, Frios; marca/desmarca)
→ 4. Formas de pagamento → 5. Importar produtos (planilha modelo CSV) ou começar com produtos de exemplo
→ 6. Gerar cartões (quantidade + imprimir etiquetas) → 7. Convidar equipe (usuários e perfis).
O painel inicial mostra uma **lista de "primeiros passos"** com progresso até tudo estar configurado.

---

## 5. Perfis e permissões

| Perfil | Pode |
| --- | --- |
| Administrador (dono) | Tudo, inclusive configurações, usuários, financeiro e fiscal |
| Gerente | Tudo da operação + relatórios + estoque + produção + encomendas; aprova cancelamentos; sem configurações sensíveis (fiscal, licença, usuários administradores) |
| Caixa | Abrir/fechar caixa, receber cartões e vendas diretas, sangria/suprimento, encomendas (receber sinal/saldo), consultar preços |
| Balconista | Usar apenas o(s) balcão(ões) em que está liberado: lançar itens em cartões, consultar cartão |
| Produção | Ordens de produção, perdas, consulta de fichas técnicas e agenda de encomendas |
| Cozinha | Tela da cozinha (marcar preparando/pronto) |

- Permissões extras por usuário (checkboxes) além do perfil, como no DGestor atual
  (ex.: balconista que também pode registrar perdas).
- Usuário pode ser vinculado a um ou mais balcões e a uma filial.
- Ações sensíveis com **senha de gerente na hora** (configurável): cancelar item já lançado, cancelar venda,
  desconto acima de X%, reabrir caixa, bloquear/liberar cartão perdido.
- Alterar usuários e permissões exige confirmar a senha do administrador logado.
- Login com usuário + senha; opção "lembrar este aparelho" (30 dias) para tablets de balcão;
  troca rápida de operador no balcão por PIN de 4 dígitos.
- Bloqueio após 5 tentativas erradas por 15 minutos.

---

## 6. Módulos — telas, regras e critérios de aceite

Cada módulo lista: **telas**, **regras de negócio** e **pronto quando** (critérios de aceite que viram testes).

### 6.1 Instalador e onboarding

**Telas:** instalador web (`/instalar`) aberto automaticamente quando o banco está vazio:
conexão com banco → criar tabelas (migrations) → dados da empresa + filial → usuário administrador → concluído.
Depois, o assistente de configuração da seção 4.6.

**Regras:**
- O instalador grava as credenciais no `.env` local do servidor e **se trava** após concluir
  (não pode ser reaberto sem apagar um arquivo de trava `storage/app/instalado.lock`).
- Atualizações de versão: tela "Atualizações" (só administrador) mostra a versão atual, migrations pendentes,
  faz **backup do banco antes** e roda `migrate --force`. Se falhar, mostra o erro e o caminho do backup.
- Configuração do cliente (credenciais, slug, chaves) nunca fica em arquivo de código versionado —
  só no `.env`. Pacotes de atualização nunca contêm `.env`, `storage/` ou `public/uploads/`.

**Pronto quando:** instalação limpa em banco vazio leva a um sistema utilizável; rodar o instalador de novo é bloqueado;
atualização com migration pendente cria backup `.sql` em `storage/app/backups/` antes de migrar.

### 6.2 Licenciamento (compatível com o Painel DGestor)

O Painel DGestor V2 já controla os clientes do DGestor por este contrato. **Mantenha exatamente o mesmo contrato.**

Campos na tabela `empresas`: `criado_em`, `assinatura_valida_ate` (DATE NULL), `bloqueado_manualmente` (bool),
`teste_estendido_ate` (DATE NULL), `modulos_liberados` (VARCHAR, lista separada por vírgula).

**Cálculo do status** (função `LicencaService::status()`), retorna:
```
{ valido, emTeste, testeAte, assinaturaAte, diasRestantesTeste, bloqueadoManualmente, vitalicio }
```
- `testeAte` = maior entre (criado_em + 14 dias) e `teste_estendido_ate`.
- `vitalicio` = `assinatura_valida_ate >= 2099-01-01`.
- `valido` = não bloqueado manualmente E (em teste OU assinatura em dia).
- Sem licença válida: todas as rotas (inclusive login) redirecionam para a tela "Assinatura vencida",
  exceto `/licenciamento`, o cardápio público mostra "Loja temporariamente indisponível".
- Faixa amarela no topo nos últimos 5 dias de teste/assinatura: "Seu teste termina em X dias".

**Endpoint `/licenciamento`:**
- `GET /licenciamento?formato=json` (sem senha) → `{ sucesso, nome, status, modulos, csrf, bloqueado }`.
- `POST /licenciamento?formato=json` com `csrf` (do GET, mesma sessão/cookie), `senha_mestra` e `acao`:
  - `liberar` (padrão) + `assinatura_valida_ate` (Y-m-d) → define data e remove bloqueio manual
    (data ≥ 2099 = acesso permanente);
  - `bloquear`; `desbloquear`;
  - `prorrogar_teste` + `teste_estendido_ate`;
  - `modulo_liberar` / `modulo_bloquear` + `modulo`.
  - Resposta: `{ sucesso, mensagem, status, modulos }`.
- A senha mestra é comparada com hash do `.env` (`DGESTOR_MASTER_PASSWORD_HASH`), com `hash_equals`/`Hash::check`.
- 5 tentativas erradas bloqueiam por 15 minutos.
- Também existe a tela HTML `/licenciamento` com o mesmo formulário.

**Módulos liberáveis** (chaves): `comanda_cartao`, `balanca`, `producao`, `encomendas`, `cardapio_digital`,
`nfce`, `financeiro_avancado`, `multi_filial`. PDV/caixa, cadastros, estoque básico e relatórios básicos
estão sempre disponíveis. Durante o teste grátis, **todos** os módulos ficam liberados.
Helper `modulo('balanca')` usado em rotas (middleware `modulo:balanca`), menus e APIs.
Módulo bloqueado aparece no menu com cadeado e uma tela explicando o recurso e "Fale com a DGestor para liberar".

**SSO DGestor (entrar pelo Painel):** rota `/sso-entrar?token=` — token = `base64(json).hmac_sha256(json_b64, DGESTOR_SSO_SECRET)`,
JSON com `email`, `nome`, `empresa` (deve bater com `DGESTOR_EMPRESA_SLUG`), `papel` (`admin`, `gestor`, `equipe`), `exp`.
Mapeamento: `admin` → Administrador; `gestor` → Administrador se não houver nenhum, senão Gerente; `equipe` → Balconista.
Cria o usuário local no primeiro acesso.

**Pronto quando:** testes cobrem todos os estados (teste, teste prorrogado, assinatura ativa, vencida, bloqueada,
vitalício), todas as ações do POST, senha errada, limite de tentativas, módulo bloqueado barrando rota e API.

### 6.3 Empresa, filiais e usuários

- Empresa: razão social, nome fantasia, CNPJ, IE, endereço, telefone/WhatsApp, logo, cor primária,
  regime tributário, Instagram, horário de funcionamento.
- Filiais: nome, endereço, ativa. Tudo operacional é por filial (caixas, balcões, cartões, estoque).
- Usuários: nome, login (e-mail ou apelido), senha, PIN de 4 dígitos (opcional), perfil, permissões extras,
  filial, balcões permitidos, ativo. Log de último acesso.

### 6.4 Cadastros

**Categorias:** nome, cor, ícone, ordem de exibição, ativa. Ex.: Pães, Doces, Bolos, Salgados, Lanchonete,
Bebidas, Frios, Mercearia.

**Produtos** — formulário em abas (Básico, Venda, Estoque, Produção, Fiscal), só mostrando campos relevantes ao tipo:
- Básico: nome, categoria, foto, descrição, ativo, esgotado hoje (toggle rápido).
- **Tipo**: `revenda` (compra e vende: refrigerante), `producao_propria` (pão, bolo — tem ficha técnica),
  `insumo` (farinha — não aparece para venda), `servico` (taxa de cartão perdido, taxa de entrega).
- Venda: preço, **unidade** (`UN`, `KG`, `G`, `L`, `ML`), **vendido por peso** (bool), preço por kg,
  código de barras (EAN), **código PLU** (código da balança, até 6 dígitos), balcões onde aparece
  (padrão: todos os balcões cujas categorias incluem a do produto), vai para cozinha (bool) + local de preparo,
  permite observação ("sem cebola"), adicionais (opcional: complementos com preço).
- Estoque: controla estoque (bool), estoque mínimo, validade em dias (para etiqueta e alerta), custo atual
  (calculado: última compra para revenda/insumo; ficha técnica para produção própria).
- Fiscal: NCM, CEST, CFOP, CST/CSOSN, origem, unidade tributável (pré-preenchidos por categoria; validação de NCM com 8 dígitos).
- Ações em massa: reajustar preço por %, ativar/desativar, mudar categoria.
- Importação/exportação por planilha CSV/XLSX com modelo para baixar e pré-visualização antes de importar
  (mostra o que será criado, atualizado e os erros por linha).
- Impressão de etiquetas de prateleira/gôndola (nome, preço, código de barras).

**Fornecedores:** nome, CNPJ/CPF, contato, telefone/WhatsApp, e-mail, endereço, prazo de pagamento padrão.

**Clientes:** nome, telefone/WhatsApp (principal identificador), CPF (para nota), e-mail, endereço,
data de aniversário, observações, limite de fiado, saldo devedor. Busca rápida por telefone.

**Formas de pagamento:** dinheiro, Pix, débito, crédito, vale-refeição/alimentação, fiado (conta do cliente),
outros — cada uma com ativo, taxa % (para relatório de taxa de maquininha), dias para receber.

### 6.5 Balcões configuráveis

Cada padaria cria os seus balcões. Pode ter só caixa + 1 balcão, ou quantos quiser.

**Campos:** filial, nome (ex.: "Pães"), cor, ícone, categorias que vende (multi-seleção), produtos extras
avulsos, local de preparo padrão (para itens que vão à cozinha), impressora de comprovante do balcão (opcional),
usuários permitidos, exige leitura de cartão (bool, padrão sim), permite venda direta sem cartão (bool, padrão não),
ativo, ordem.

**Regras:**
- Um balcão só mostra/aceita os produtos das categorias dele + extras. Ler o código de um produto de outro
  balcão mostra aviso "Este produto é do balcão Doces. Lançar mesmo assim?" (permitido se o usuário tiver permissão).
- Todo item lançado guarda `balcao_id` e `usuario_id` → relatório de vendas por balcão e por atendente.

**Pronto quando:** criar/editar/desativar balcão; balcão sem categorias mostra aviso; balconista só entra nos balcões dele.

### 6.6 Cartões-comanda (módulo `comanda_cartao`)

**Cadastro:** gerar em lote (de N até M), cada cartão com `numero` (ex.: 001–200) e `codigo` de barras
(Code 128, formato `CMD` + filial + número, ex.: `CMD01-0042`; também aceitar cartões já impressos cadastrando
o código lido). Status: `livre`, `em_uso`, `bloqueado`, `perdido`.
Tela de impressão de etiquetas/cartões em folha A4 (grade) e em impressora térmica de etiquetas.

**Regras:**
- Ler cartão `livre` em um balcão → abre uma comanda nova vinculada ao cartão (status vira `em_uso`).
- Ler cartão `em_uso` → retoma a comanda aberta.
- Ler cartão `bloqueado`/`perdido` → erro claro em vermelho com som; não lança nada.
- Um cartão só pode ter **uma** comanda aberta (garantido por índice único + transação).
- Ao receber no caixa, a comanda fecha e o cartão volta a `livre` automaticamente.
- **Cartão perdido:** caixa marca como perdido; o sistema cobra a taxa configurada (produto tipo serviço) e
  permite fechar a comanda pelo número digitado.
- **Transferir/juntar:** juntar dois cartões numa conta (família que pegou 2 cartões) e transferir item entre cartões.
- **Painel de cartões abertos:** grade com todos os cartões em uso, valor, tempo aberto, balcões por onde passou.
  Destaque em amarelo após X minutos (configurável, padrão 90) e em vermelho após Y horas.
- No **fechamento do caixa**, se existirem cartões abertos, o sistema avisa e lista.
- Consumo mínimo/multa por cartão não devolvido: configurável (valor), lançado como item de serviço.

**Pronto quando:** testes de abrir, retomar, cartão bloqueado, concorrência (dois balcões lendo o mesmo cartão
livre ao mesmo tempo geram UMA comanda), fechar libera o cartão, perdido com taxa, juntar e transferir.

### 6.7 Tela do balcão (a tela mais importante do sistema)

Layout de operação, otimizado para tablet e PC com leitor.

```
┌──────────────────────────────────────────────────────────────────────┐
│ Balcão PÃES · Maria · 07:42 · ● online                    [Sair]     │
├───────────────────────────────┬──────────────────────────────────────┤
│  [ Passe o CARTÃO ou o PRODUTO ]  ← campo sempre focado               │
│                               │  CARTÃO 042            R$ 18,40      │
│  Categorias: (Pães)(Doces)…   │  ─────────────────────────────────    │
│  ┌────┐┌────┐┌────┐┌────┐     │  Pão francês 0,350 kg     R$ 6,30    │
│  │foto││foto││foto││foto│     │  Sonho x2                 R$ 9,00    │
│  │nome││nome││nome││nome│     │  Café pingado             R$ 3,10    │
│  │R$  ││R$  ││R$  ││R$  │     │                                      │
│  └────┘└────┘└────┘└────┘     │  [Desfazer último] [Concluir ✓]      │
└───────────────────────────────┴──────────────────────────────────────┘
```

**Fluxo:**
1. Tela ociosa mostra grande: "Passe o cartão do cliente".
2. Leu cartão → painel direito mostra o cartão, itens já lançados (de todos os balcões, os de outros balcões em cinza) e total.
3. Leu produto/etiqueta ou tocou num produto → item entra na lista com animação e bip.
   Produto por peso tocado na tela abre teclado numérico para digitar o peso (ou lê da balança se integrada).
4. "Concluir" (ou ler o próximo cartão, ou 20 s sem ação) → salva e volta para a tela ociosa.
   Os itens são gravados **a cada lançamento** (não se perde nada se a internet cair no meio).
5. Quantidade: botões + / − no item ou tecla F4. Observação: toque longo no item.
6. Itens com "vai para cozinha" disparam pedido para o local de preparo assim que lançados.

**Regras:** lançar item exige cartão lido (se o balcão exige cartão); cancelar item já lançado segue a seção 5;
toda ação registra quem, quando e de qual balcão.

**Pronto quando:** um balconista consegue, só com leitor, abrir cartão, lançar 3 itens (um por etiqueta de peso)
e concluir em menos de 15 segundos; teste automatizado do fluxo via API.

### 6.8 Leitura de códigos e balança (módulo `balanca` para a parte de peso)

Crie `App\Support\CodigoLido` — um decodificador único usado por balcão, caixa e estoque.
Dado o texto lido, devolve **um** de: `cartao`, `etiqueta_balanca`, `produto`, `encomenda`, `desconhecido`.
Ordem de tentativa:
1. Bate com o formato/código de algum cartão da filial → `cartao`.
2. EAN-13 começando com o **prefixo da balança** (padrão `2`) → `etiqueta_balanca`.
3. Bate com `codigo_barras` ou `codigo_plu` de produto → `produto`.
4. Formato de encomenda (`ENC` + número) → `encomenda`.

**Etiqueta de balança (EAN-13):** configuração por filial em "Configurações → Balança":
- prefixo (padrão `2`), tamanho do código do produto (4, 5 ou 6 dígitos), o que vem depois:
  **valor total** (ex.: `0630` = R$ 6,30) ou **peso** (ex.: `00350` = 0,350 kg), casas decimais, dígito verificador.
- Formato padrão (mais comum em balanças Toledo/Filizola configuradas como "preço"): `2 PPPP 0 VVVVV D`
  (prefixo, PLU com 4 dígitos, 1 dígito fixo, valor com 5 dígitos em centavos, verificador).
- Ao decodificar: acha o produto pelo PLU; se vier valor, calcula peso = valor ÷ preço/kg (3 casas);
  se vier peso, calcula valor = peso × preço/kg. Grava ambos no item. Valida o dígito verificador.
- Tela **"Testar etiqueta"**: campo para ler uma etiqueta real e mostrar o que o sistema entendeu
  (produto, peso, valor) — para o técnico configurar na instalação.
- Exportar cadastro de PLUs (código, nome, preço/kg, validade dias) em CSV/TXT para carregar na balança.
- Não aceitar a mesma etiqueta duas vezes na mesma comanda sem confirmação (proteção contra leitura dupla).

**Balança ligada ao computador (opcional, fase final):** leitura via Web Serial API (Chrome/Edge) com protocolo
configurável (Toledo/Filizola padrão "P0" — envia peso estável). Botão "Ler peso". Se não houver suporte, esconder o botão.

**Pronto quando:** testes unitários de `CodigoLido` com etiquetas de valor, de peso, PLU de 4/5 dígitos,
verificador inválido, produto inexistente e código de cartão.

### 6.9 Caixa / PDV

**Abertura:** operador informa fundo de troco (sugere o do último fechamento). Um caixa aberto por operador/terminal.

**Tela do caixa** (layout de operação), duas formas de uso na mesma tela:
- **Receber cartão:** lê o cartão → mostra todos os itens agrupados por balcão, total, desconto (com limite por perfil),
  CPF na nota (opcional), botão **Receber (F9)**.
- **Venda direta:** lê/busca produtos direto no caixa (pão no caixa, refrigerante) sem cartão.
- Pode juntar vários cartões numa única cobrança (família).

**Recebimento:** modal grande com as formas de pagamento como botões; valor restante sempre visível;
pagamento misto (parte Pix, parte dinheiro); troco calculado em destaque; fiado exige cliente e respeita limite.
Integração com maquininha: nesta versão, registrar manualmente (o operador passa na maquininha e confirma).
Pix: mostrar QR Code estático da chave da empresa com o valor (BR Code com valor), confirmação manual;
deixe a interface `GatewayPagamento` pronta (`criarCobranca`, `conferirWebhook`) para Pix dinâmico no futuro.

**Ao finalizar:** fecha comanda, libera cartão(ões), baixa estoque dos itens (produtos que controlam estoque),
registra movimento no caixa por forma de pagamento, emite NFC-e se módulo ligado (ou pergunta "Emitir nota?"
conforme configuração), imprime cupom (não fiscal ou DANFE NFC-e), volta para a tela inicial.

**Outras ações:** sangria e suprimento (com motivo), reimprimir último cupom, cancelar venda (senha de gerente,
estorna estoque e caixa, cancela NFC-e se emitida dentro do prazo), consultar preço.

**Fechamento:** conferência cega (operador informa quanto tem em cada forma sem ver o esperado), depois o
sistema mostra esperado × informado × diferença; relatório de fechamento impresso; aviso de cartões abertos.

**Pronto quando:** testes de abertura, venda direta, recebimento de cartão com pagamento misto e troco,
desconto acima do limite bloqueado, fiado acima do limite bloqueado, cancelamento estornando estoque e caixa,
fechamento com diferença.

### 6.10 Cozinha / locais de preparo

- Locais de preparo cadastráveis (ex.: Chapa, Café, Confeitaria) com impressora opcional.
- **Tela da cozinha (KDS):** modo escuro, cards por pedido com número do cartão, balcão de origem, itens,
  observações e tempo decorrido; toque muda status `novo → preparando → pronto`. Som ao chegar pedido novo.
  Atualização por polling a cada 3 s.
- Quando fica pronto, o balcão de origem vê um aviso "Cartão 042 — Misto quente pronto".
- Impressão automática do ticket no local de preparo (via agente de impressão — seção 6.18).

### 6.11 Cardápio e comanda digital (módulo `cardapio_digital`)

- Página pública mobile-first `/{slug}` (ou raiz pública do subdomínio) com logo, cor da padaria, horário,
  status aberto/fechado, categorias, fotos, preços, selo "esgotado hoje".
- **QR Code na mesa/balcão de consumo:** o cliente monta o pedido no celular informando o **número do cartão**
  que está segurando (ou o QR impresso no próprio cartão) → os itens entram na comanda do cartão como pedido
  "aguardando confirmação"; o balcão/caixa confirma com um toque (evita pedido falso).
- **Pedido antecipado / encomenda online:** cliente escolhe itens, data/hora de retirada, informa nome e WhatsApp;
  vira uma encomenda com status "recebida" (seção 6.14). Valor mínimo e antecedência mínima configuráveis.
- Página de acompanhamento `/pedido/{codigo}` com status.

### 6.12 Estoque

**Movimentos** (tabela imutável `estoque_movimentos`), tipos:
`entrada_compra`, `saida_venda`, `estorno_venda`, `producao_entrada`, `producao_consumo`, `perda`,
`ajuste_inventario`, `transferencia_saida`, `transferencia_entrada`, `ajuste_manual`.
Cada movimento: produto, filial, quantidade (+/−), custo unitário, origem (tipo + id), usuário, motivo, data.
Saldo atual em `estoque_saldos` (produto × filial), atualizado na mesma transação.

**Telas:**
- **Posição de estoque:** lista com saldo, mínimo, custo, valor total, status (ok / baixo / zerado / negativo),
  filtros por categoria e tipo. Saldo negativo é permitido em venda (padaria não pode parar) mas aparece em vermelho.
- **Entrada de compra:** fornecedor, nº da nota, data, itens (busca + leitor), quantidade, custo, validade/lote opcional,
  frete/desconto rateado; gera conta a pagar (com parcelas e vencimentos) automaticamente.
  Importar XML de NF-e de compra para preencher itens (vincular item do fornecedor ao produto na primeira vez e lembrar).
- **Perdas e sobras:** lançamento rápido do fim do dia ("pão francês 2,5 kg — sobra/doação/quebra/vencido"),
  com motivos configuráveis. Relatório de perdas em R$ por motivo e produto.
- **Inventário:** abrir inventário (por categoria ou geral), contar (pode ser no celular com leitor/câmera),
  ver diferenças, aprovar → gera ajustes.
- **Transferência entre filiais** (módulo `multi_filial`).
- **Alertas:** estoque abaixo do mínimo e validade próxima aparecem no painel inicial e em Notificações;
  sugestão de compra (o que está abaixo do mínimo, com último fornecedor e custo).
- **Histórico (kardex)** por produto.

**Pronto quando:** venda baixa estoque, cancelamento estorna, compra soma e gera conta a pagar,
perda baixa e aparece no relatório, inventário aprovado ajusta a diferença exata.

### 6.13 Produção e ficha técnica (módulo `producao`)

**Ficha técnica** (por produto de produção própria): rendimento (ex.: 1 receita = 120 unidades ou 6 kg),
insumos com quantidade (em unidade do insumo; conversão g↔kg, ml↔l), perda padrão %, modo de preparo (texto),
tempo de preparo, foto. Pode usar outro produto de produção própria como insumo (ex.: massa base, recheio).
Mostra **custo por unidade** calculado e **margem** atual (preço − custo) com alerta se margem < meta configurável.

**Ordem de produção / fornada:** escolher produto, quantidade de receitas (ou quantidade final desejada → calcula receitas),
responsável. Ao confirmar: `producao_entrada` do produto pronto e `producao_consumo` de cada insumo, numa transação.
Permitir ajustar o consumo real e o rendimento real antes de confirmar (ex.: rendeu 115 em vez de 120).
- **Planejamento do dia:** tela com sugestão de produção = média de vendas do mesmo dia da semana nas últimas
  4 semanas + encomendas do dia − estoque atual. O padeiro ajusta e gera as ordens de uma vez.
- **Produção paga por quantidade (colaboradores):** opcional, vincular ordem a colaborador com valor por unidade
  → relatório de pagamento por período.

**Pronto quando:** custo por unidade correto em ficha com sub-receita; ordem de produção move estoques exatamente;
sugestão de produção calcula conforme a fórmula com dados do seeder.

### 6.14 Encomendas (módulo `encomendas`)

- Cadastro rápido: cliente (busca por telefone; cria na hora), itens do catálogo e/ou item livre com descrição
  e preço (ex.: "Bolo 2 kg, massa branca, recheio ninho, escrita: Parabéns Ana"), foto de referência (upload),
  data e hora de retirada ou entrega (endereço + taxa), observações.
- Valores: total, **sinal** (valor ou % padrão configurável), saldo. Sinal recebido no caixa vira recebimento
  vinculado à encomenda; saldo cobrado na retirada.
- Status: `orcamento`, `confirmada`, `em_producao`, `pronta`, `retirada`, `cancelada` (com regra de devolução do sinal).
- **Agenda:** visão de calendário (dia/semana) e lista do dia; cores por status; impressão da ficha da encomenda
  para a produção (com código `ENC000123` em código de barras para dar baixa lendo no caixa).
- WhatsApp: botões que abrem `wa.me` com mensagem pronta (confirmação, pronta para retirada, lembrete na véspera).
- Itens da encomenda entram no planejamento de produção do dia.

**Pronto quando:** criar encomenda com sinal, ver na agenda, mudar status, ler o código no caixa e receber o saldo
fechando a encomenda; cancelar com e sem devolução de sinal gera os lançamentos certos.

### 6.15 Financeiro

- **Contas a pagar:** manual ou geradas por compras; categorias (insumos, aluguel, energia, salários, impostos…),
  fornecedor, vencimento, parcelas, recorrência mensal, anexos (boleto/nota), baixa total ou parcial com
  conta/forma de pagamento. Alertas de vencidas e a vencer em 3 dias no painel.
- **Contas a receber:** fiado de clientes (gerado pelo caixa), encomendas com saldo, recebíveis de cartão
  (previsão pela taxa e dias da forma de pagamento). Extrato do cliente com envio por WhatsApp.
  Juros/multa por atraso configuráveis no fiado.
- **Contas/caixas financeiros:** caixa da loja, banco(s), cofre. Transferências entre contas.
- **Fluxo de caixa:** realizado e previsto por dia/semana/mês, em gráfico e tabela.
- **DRE simplificado mensal:** faturamento − taxas de cartão − CMV (custo pelas fichas/compras) − perdas
  − despesas por categoria = resultado.
- Todos os lançamentos com auditoria (quem criou, quem baixou, quando).

### 6.16 Fiscal — NFC-e (módulo `nfce`)

- Interface `App\Services\Fiscal\EmissorFiscal` com métodos: `emitir(Venda)`, `consultar`, `cancelar(motivo)`,
  `inutilizar(serie, de, ate, motivo)`, `statusServico()`.
- Adaptadores: `MockEmissor` (padrão em desenvolvimento: gera chave e XML fictícios, permite testar tudo) e um
  adaptador para **API fiscal terceirizada** (deixar estrutura pronta e configurável por empresa: provedor, token,
  ambiente; implementar um provedor de mercado escolhido pelo agente com documentação pública, sempre em homologação).
- Configuração fiscal da empresa: CNPJ, IE, regime (Simples/Normal), CSC e ID do CSC, série, próximo número,
  ambiente (homologação/produção), certificado A1 (upload .pfx + senha, armazenado criptografado).
- Na finalização da venda: emitir, imprimir DANFE NFC-e no cupom (QR Code de consulta), guardar XML
  em `storage/app/fiscal/{ano}/{mes}/` e na tabela `notas_fiscais`.
- Se a SEFAZ/provedor falhar: venda é finalizada normalmente, nota fica `pendente` e um job tenta reenviar;
  painel mostra notas pendentes/rejeitadas com motivo e botão "reenviar".
- Cancelamento dentro do prazo legal, inutilização de numeração, relatório de notas, exportação de XMLs do mês (ZIP)
  para o contador.
- Validações antes de emitir: produto com NCM, CFOP e CST/CSOSN preenchidos; senão, mostrar exatamente o que falta.

### 6.17 Painel inicial e relatórios

**Painel inicial (dono/gerente):** cards grandes — vendas de hoje (R$ e nº), ticket médio, comparação com o
mesmo dia da semana anterior, cartões abertos agora, encomendas de hoje, contas a pagar hoje, estoque baixo,
perdas de ontem. Gráfico de vendas por hora do dia e vendas dos últimos 30 dias. Lista "primeiros passos" até configurar tudo.

**Relatórios** (todos com filtro de período/filial, exportar Excel/PDF, impressão):
vendas por dia/hora/forma de pagamento; vendas por produto e categoria (curva ABC); vendas por **balcão** e por
**atendente**; margem por produto; perdas; posição e valor de estoque; produção (produzido × vendido × perdido por produto);
encomendas por período; fechamentos de caixa; cancelamentos e descontos (auditoria); clientes (fiado, mais compram,
aniversariantes); financeiro (pagar/receber/fluxo/DRE); notas fiscais.

### 6.18 Impressão

- Cupom/ticket em HTML formatado para 58 e 80 mm (configurável por impressora), impresso pelo navegador
  (`window.print` com CSS de impressão) como modo padrão.
- **Agente de impressão local** (opcional, para impressão silenciosa e automática na cozinha): especifique e
  implemente um endpoint de fila `GET /api/impressao/pendentes?terminal=` + `POST /api/impressao/{id}/ok`
  autenticado por token do terminal. O agente Windows (fora deste projeto) consulta a fila e imprime em ESC/POS.
  Gere também os comandos ESC/POS do lado do servidor (texto + corte) para o agente só repassar.
- Impressoras lógicas: "Caixa 1", "Cozinha Chapa", "Confeitaria" mapeadas por terminal/local de preparo.
- Etiquetas: cartões-comanda, produtos (gôndola), produção (nome, data de fabricação, validade).

### 6.19 Configurações, backup e auditoria

- Configurações em abas: Empresa, Aparência, Balcões, Cartões, Balança, Caixa (fundo de troco padrão, conferência cega,
  limite de desconto, senha de gerente para ações), Formas de pagamento, Impressoras, Fiscal, Cardápio digital,
  Encomendas (sinal padrão, antecedência), Notificações.
- **Backup:** diário automático (agendado) do banco em `storage/app/backups` mantendo os últimos 14;
  botão de backup manual e download (só administrador). Restaurar só pelo administrador com confirmação dupla.
- **Auditoria:** tabela `auditoria` (usuário, ação, entidade, id, dados antes/depois em JSON, IP, data) para:
  cancelamentos, descontos, alterações de preço, ajustes de estoque, abertura/fechamento de caixa, mudanças de
  permissões e licença. Tela de consulta com filtros.
- Página "Sobre": versão do sistema, versão do banco, status da licença.

---

## 7. Modelo de dados (mínimo — o agente pode acrescentar colunas, nunca remover estas)

Todas com `id` BIGINT, `created_at`, `updated_at`; cadastros com `deleted_at`.

| Tabela | Colunas principais |
| --- | --- |
| `empresas` | razao_social, nome_fantasia, cnpj, ie, regime_tributario, telefone, whatsapp, endereco (json), logo, cor_primaria, slug, criado_em, assinatura_valida_ate, bloqueado_manualmente, teste_estendido_ate, modulos_liberados |
| `filiais` | empresa_id, nome, endereco (json), ativa |
| `users` | empresa_id, filial_id, nome, login, email, password, pin_hash, perfil, permissoes_extra (json), ativo, ultimo_acesso_em |
| `balcao_user` | balcao_id, user_id |
| `categorias` | empresa_id, nome, cor, icone, ordem, ativa |
| `produtos` | empresa_id, categoria_id, nome, descricao, foto, tipo, unidade, vendido_por_peso, preco, preco_kg, codigo_barras, codigo_plu, envia_cozinha, local_preparo_id, permite_observacao, controla_estoque, estoque_minimo, validade_dias, custo_atual, ncm, cest, cfop, cst_csosn, origem, ativo, esgotado_hoje |
| `produto_balcao` | produto_id, balcao_id (extras avulsos) |
| `adicionais`, `produto_adicional` | complementos opcionais com preço |
| `fornecedores` | empresa_id, nome, documento, contato, telefone, email, endereco, prazo_padrao_dias |
| `clientes` | empresa_id, nome, telefone, cpf, email, endereco (json), aniversario, limite_fiado, observacoes |
| `formas_pagamento` | empresa_id, nome, tipo (dinheiro, pix, debito, credito, voucher, fiado, outro), taxa_percentual, dias_recebimento, ativa, ordem |
| `balcoes` | filial_id, nome, cor, icone, local_preparo_id, impressora_id, exige_cartao, permite_venda_direta, ativo, ordem |
| `balcao_categoria` | balcao_id, categoria_id |
| `locais_preparo` | filial_id, nome, impressora_id, ativo |
| `cartoes` | filial_id, numero, codigo (único por filial), status, comanda_aberta_id, ultimo_uso_em |
| `comandas` | filial_id, cartao_id (null), origem (cartao, venda_direta, encomenda, digital), status (aberta, fechada, cancelada), cliente_id, aberta_por, aberta_em, fechada_em, venda_id. Índice único parcial lógico: um cartão com uma comanda aberta (garantir via `cartoes.comanda_aberta_id` + lock) |
| `comanda_itens` | comanda_id, produto_id, balcao_id, user_id, quantidade, peso_kg, preco_unitario, total, observacao, codigo_lido, status (lancado, cancelado), status_preparo (null, novo, preparando, pronto, entregue), cancelado_por, motivo_cancelamento |
| `caixas` | filial_id, user_id, terminal, fundo_troco, status, aberto_em, fechado_em, conferencia (json), diferenca |
| `caixa_movimentos` | caixa_id, tipo (venda, sangria, suprimento, estorno, sinal_encomenda, recebimento_fiado), forma_pagamento_id, valor, descricao, origem_tipo, origem_id, user_id |
| `vendas` | filial_id, caixa_id, cliente_id, subtotal, desconto, acrescimo, total, troco, cpf_nota, status (concluida, cancelada), user_id, cancelada_por, motivo_cancelamento |
| `venda_comanda` | venda_id, comanda_id (uma venda pode juntar vários cartões) |
| `venda_itens` | venda_id, produto_id, balcao_id, quantidade, peso_kg, preco_unitario, desconto, total, custo_unitario |
| `venda_pagamentos` | venda_id, forma_pagamento_id, valor, recebido, troco |
| `estoque_movimentos` | filial_id, produto_id, tipo, quantidade (+/−), custo_unitario, origem_tipo, origem_id, motivo, user_id |
| `estoque_saldos` | filial_id, produto_id, quantidade, custo_medio |
| `compras`, `compra_itens` | fornecedor, nota, data, totais / produto, quantidade, custo, validade, lote |
| `inventarios`, `inventario_itens` | status, contagem, diferença |
| `fichas_tecnicas`, `ficha_tecnica_itens` | produto_id, rendimento, unidade_rendimento, perda_padrao, modo_preparo / insumo_id, quantidade, unidade |
| `producoes`, `producao_itens` | ficha_id, produto_id, receitas, quantidade_prevista, quantidade_real, responsavel_id, colaborador_id, status / insumo consumido real |
| `encomendas`, `encomenda_itens` | codigo, cliente_id, retirada_em, tipo_entrega, endereco, taxa_entrega, total, sinal, status, observacoes, foto_referencia / produto_id (null), descricao, quantidade, preco |
| `contas_financeiras` | tipo (pagar, receber), categoria_id, fornecedor_id, cliente_id, descricao, valor, vencimento, pago_em, valor_pago, conta_id, origem_tipo, origem_id, parcela, recorrencia |
| `categorias_financeiras`, `contas_bancarias`, `transferencias` | — |
| `notas_fiscais` | venda_id, modelo (65), serie, numero, chave, status (pendente, autorizada, rejeitada, cancelada), protocolo, motivo, xml_path, ambiente, tentativas |
| `impressoras`, `fila_impressao` | nome, largura (58/80), tipo, destino / impressora_id, conteudo, status |
| `configuracoes` | filial_id (null = empresa), chave, valor (json) |
| `auditoria` | user_id, acao, entidade, entidade_id, antes (json), depois (json), ip |
| `notificacoes` | padrão do Laravel |

---

## 8. Fases de desenvolvimento (siga esta ordem)

Cada fase só termina quando: migrations rodam do zero, seeder de demonstração roda, testes passam,
as telas da fase seguem a seção 4, e o `PROGRESSO.md` foi atualizado.

| Fase | Entrega | Pronto quando |
| --- | --- | --- |
| 0. Fundação | Laravel instalado, git, `.env.example`, Tailwind/Alpine/Livewire, design system (seção 4.3), layouts, login, perfis/permissões, instalador, licenciamento + SSO, middleware de módulos, auditoria, página de componentes `/dev/componentes` (só em local) | Login funciona; todos os testes da 6.2 passam; página de componentes mostra todos os componentes nos dois temas |
| 1. Cadastros | Empresa, filiais, usuários, categorias, produtos (todas as abas), fornecedores, clientes, formas de pagamento, importação CSV, onboarding (4.6), seeder de demonstração | Dono cadastra produto por peso com PLU em < 1 min; importação mostra prévia e erros |
| 2. Caixa e venda direta | Abertura/fechamento, venda direta com leitor, recebimento misto, troco, desconto, sangria/suprimento, cupom 58/80 mm, baixa de estoque | Testes da 6.9 passam |
| 3. Balcões, cartões e balança | Balcões, cartões (lote + etiquetas), tela do balcão (6.7), `CodigoLido`, etiqueta de balança, recebimento de cartão no caixa, juntar/transferir, painel de cartões abertos | Testes da 6.6 e 6.8 passam; fluxo do balcão completo pelo navegador |
| 4. Cozinha e impressão | Locais de preparo, KDS, aviso de pronto no balcão, fila de impressão + ESC/POS | Pedido lançado no balcão aparece na cozinha em ≤ 5 s |
| 5. Estoque | Movimentos, saldos, compras + conta a pagar + XML NF-e, perdas, inventário, alertas, kardex | Testes da 6.12 passam |
| 6. Produção | Fichas técnicas com sub-receita, custo e margem, ordens de produção, planejamento do dia, pagamento por produção | Testes da 6.13 passam |
| 7. Encomendas e cardápio digital | Encomendas, agenda, sinal/saldo, WhatsApp, cardápio público, pedido pelo cartão via QR, encomenda online | Testes da 6.14 passam; cardápio abre bem em celular 360 px |
| 8. Financeiro | Pagar/receber, fiado com juros, contas bancárias, fluxo de caixa, DRE | Valores do DRE batem com vendas/compras/perdas do seeder |
| 9. Fiscal | Interface + MockEmissor + adaptador de API terceirizada (homologação), configuração fiscal, reenvio, cancelamento, XMLs | Venda gera nota no mock; falha deixa pendente e o job reenvia |
| 10. Painel e relatórios | Painel inicial, todos os relatórios da 6.17, exportações | Todos os relatórios abrem com dados do seeder em < 2 s |
| 11. Acabamento | PWA, modo escuro, balança via Web Serial, revisão de UX tela a tela (checklist 9.2), manual do usuário, pacote de deploy | Checklist 9.2 completo para todas as telas |

---

## 9. Qualidade

### 9.1 Testes

- Feature tests para todos os critérios "Pronto quando" da seção 6.
- Unit tests para `CodigoLido`, `LicencaService`, cálculo de custo de ficha técnica, troco, rateio, DRE.
- Banco de testes separado (`dgestor_padaria_test`) ou SQLite em memória quando compatível.
- Factories para todos os models.

### 9.2 Checklist de UX por tela (revise cada tela antes de fechar a fase 11)

- [ ] A ação principal é óbvia e está no mesmo lugar das outras telas
- [ ] Funciona no celular (360 px) sem rolagem horizontal
- [ ] Estado vazio com orientação do próximo passo
- [ ] Carregamento com skeleton, nunca tela branca
- [ ] Erros em português claro, dizendo o que fazer
- [ ] Ações destrutivas pedem confirmação
- [ ] Telas de operação: foco no campo de leitura, atalhos visíveis, som de sucesso/erro
- [ ] Textos sem jargão técnico
- [ ] Contraste AA e foco visível
- [ ] Ajuda "?" com passo a passo

### 9.3 Documentação para o cliente

Gere em `docs/manual/` um manual do usuário em Markdown, em linguagem simples, com uma página por tarefa:
"Como abrir o caixa", "Como lançar no balcão", "Como configurar a balança", "Como cadastrar uma ficha técnica",
"Como registrar uma encomenda", etc. Também `docs/INSTALACAO_HOSTGATOR.md` (seção 10).

### 9.4 Desempenho e segurança

- Endpoints de operação (ler código, lançar item) respondem em < 200 ms locais; use índices em
  `cartoes.codigo`, `produtos.codigo_barras`, `produtos.codigo_plu`, `comanda_itens.comanda_id`.
- Proteção CSRF, validação de entrada, escape de saída (Blade), upload só de imagens (jpg/png/webp, até 3 MB,
  redimensionadas), rate limit no login e no `/licenciamento`, senhas com bcrypt.
- Nenhuma rota de API de operação sem autenticação (exceto cardápio público e licenciamento conforme 6.2).

---

## 10. Publicação na HostGator (documentar, não executar)

Escreva `docs/INSTALACAO_HOSTGATOR.md` explicando:
1. Criar subdomínio `cliente.dgestor.com.br` com **document root apontando para `/public`** do projeto
   (alternativa: `.htaccess` na raiz redirecionando para `public/`).
2. Criar banco MySQL e usuário pelo cPanel.
3. Enviar os arquivos (sem `.env`, `storage/logs`, `node_modules`), com `vendor/` e `public/build/` incluídos
   (HostGator compartilhada não roda Composer/Node de forma confiável).
4. Acessar `/instalar`.
5. Cron no cPanel: `* * * * * php /home/USUARIO/caminho/artisan schedule:run >> /dev/null 2>&1`.
6. Versão do PHP no cPanel ≥ 8.2 e extensões: pdo_mysql, mbstring, openssl, curl, gd, zip, intl, bcmath, fileinfo.
7. Atualização: enviar pacote **sem** `.env`/`storage`/`uploads` e rodar "Atualizações" no sistema.
Gere também um script `scripts/gerar_pacote.ps1` que cria o ZIP de deploy excluindo o que não deve ir.

---

## 11. O que depende do Deivid (registrar como pendência, não bloquear o trabalho)

- Escolha final do provedor de API fiscal, conta e token; certificado A1, CSC e regime tributário da padaria piloto.
- Marca/modelo da balança e formato real da etiqueta (o sistema já é configurável e tem a tela "Testar etiqueta").
- Quantidade de cartões e impressão física dos cartões.
- Senha mestra de licenciamento, segredo SSO e slug para conectar ao Painel DGestor.
- Logo e identidade da padaria piloto (usar a fictícia "Padaria Pão Dourado" até lá).
- Teste no WampServer e publicação na HostGator.
- Decisão sobre Pix dinâmico/maquininha integrada (estrutura pronta, integração futura).