AGENTS.md

1# AGENTS.md — Diretrizes do Projeto Comanda Digital
2 
3> Este arquivo define as regras, padrões e contexto do projeto.
4> Todo agente de IA ou desenvolvedor DEVE ler este arquivo antes de qualquer alteração.
5 
6---
7 
8## 📌 Visão Geral
9 
10**Comanda Digital** é um SaaS multi-tenant para gestão de restaurantes.
11Cada restaurante é isolado por `restaurante_id`. Nenhuma query pode misturar dados entre restaurantes.
12 
13- **Domínio produção:** https://pantanaldev.com.br
14- **Repositório:** github.com/friamericardo-ux/Sistema-Restaurante
15- **Deploy:** Coolify v4 + Docker + Hetzner CPX22 (2 vCPU, 4GB RAM)
16 
17---
18 
19## 🏗️ Stack Técnica
20 
21| Camada | Tecnologia |
22|---|---|
23| Backend | Python 3.11 + Flask |
24| Banco de dados | MySQL 8 (PyMySQL + SQLAlchemy) |
25| Deploy | Docker + Coolify |
26| Proxy/SSL | Traefik + Let's Encrypt |
27| Frontend | HTML + CSS + JS (Jinja2 templates) |
28 
29---
30 
31## 📁 Estrutura de Pastas
32 
33```
34/
35├── app.py                  # Entrypoint Flask + rotas principais
36├── repository.py           # Todas as queries ao banco de dados
37├── migrations/             # Scripts SQL de migração (001, 002...)
38├── static/
39│   ├── css/                # Estilos — NÃO alterar sem pedido explícito
40│   ├── js/                 # Scripts frontend
41│   └── img/                # Imagens e uploads
42├── templates/              # HTML Jinja2
43├── .env                    # Variáveis locais — NUNCA commitar
44├── AGENTS.md               # Este arquivo
45└── requirements.txt        # Dependências Python
46```
47 
48---
49 
50## 🔒 Regras de Segurança — OBRIGATÓRIAS
51 
521. **NUNCA** commitar `.env` ou qualquer arquivo com credenciais
532. **NUNCA** expor `SECRET_KEY`, senhas de banco ou API keys no código
543. Senhas de usuário SEMPRE com `werkzeug.security` (hash bcrypt)
554. Toda rota autenticada DEVE verificar `session['user_id']` e `session['restaurante_id']`
565. `SESSION_COOKIE_SECURE=True` em produção
576. Inputs do usuário SEMPRE sanitizados antes de queries SQL
58 
59---
60 
61## 🏢 Regras de Multi-Tenancy — CRÍTICO
62 
63- Toda query DEVE filtrar por `restaurante_id`
64- O `restaurante_id` vem sempre da sessão: `session['restaurante_id']`
65- **NUNCA** retornar dados de um restaurante para outro
66- Superadmin (`role='superadmin'`) pode ver todos — tratar separado
67 
68```python
69# CORRETO
70produtos = db.execute(
71    "SELECT * FROM produtos WHERE restaurante_id = %s", 
72    (session['restaurante_id'],)
73)
74 
75# ERRADO — vaza dados entre restaurantes
76produtos = db.execute("SELECT * FROM produtos")
77```
78 
79---
80 
81## 🗄️ Banco de Dados
82 
83**Conexão:** MySQL via `DATABASE_URL` no ambiente (nunca hardcoded)
84 
85**Tabelas principais:**
86- `restaurantes` — cadastro dos tenants
87- `users` — com colunas: id, username, password_hash, role, restaurante_id
88- `produtos` — cardápio por restaurante
89- `adicionais` + `adicional_categoria` — extras dos produtos
90- `pedidos_delivery` — pedidos com status e entregador
91- `mesas` + `historico_mesas` — gestão de mesas
92- `configuracoes` — configs por restaurante (taxa entrega, WhatsApp etc)
93- `caixa_sessoes` + `caixa_fechamentos` — controle de caixa
94- `clientes_cache` — cache de clientes por restaurante
95- `schema_migrations` — controle de versão do banco
96 
97**Regras:**
98- Migrations numeradas sequencialmente: `001_`, `002_`, etc.
99- Toda nova tabela ou coluna = nova migration, nunca alterar migration existente
100- Usar apenas MySQL — sem SQLite em produção
101 
102---
103 
104## 🐍 Padrões de Código Python
105 
106```python
107# Estrutura padrão de rota Flask
108@app.route('/admin/exemplo')
109@login_required
110def exemplo():
111    try:
112        restaurante_id = session['restaurante_id']
113        dados = repository.buscar_dados(restaurante_id)
114        return render_template('exemplo.html', dados=dados)
115    except Exception as e:
116        app.logger.error(f"Erro em /admin/exemplo: {e}")
117        return jsonify({'erro': 'Erro interno'}), 500
118```
119 
120- Toda lógica de banco vai em `repository.py` — não inline no `app.py`
121- Usar `try/except` em toda rota
122- Logar erros com `app.logger.error()` — não usar `print()` em produção
123- Retornar JSON para rotas `/api/` e HTML para rotas de página
124 
125---
126 
127## 🎨 Frontend
128 
129- CSS já está definido e funcional — **não alterar** sem pedido explícito
130- Templates Jinja2 em `/templates/`
131- JS de polling do painel delivery em `static/js/painel.js`
132- Não adicionar bibliotecas externas sem aprovação
133 
134---
135 
136## 🚀 Deploy e Ambiente
137 
138**Variáveis de ambiente obrigatórias no Coolify:**
139```
140DATABASE_URL=mysql+pymysql://mysql:SENHA@HOST:3306/default
141SECRET_KEY=<chave forte gerada>
142FLASK_ENV=production
143```
144 
145**Fluxo de deploy:**
1461. Push para `main` no GitHub
1472. Coolify detecta e rebuilda automaticamente
1483. Verificar logs no Coolify após deploy
149 
150**NUNCA** reiniciar containers manualmente sem saber o impacto.
151 
152---
153 
154## ✅ Checklist antes de qualquer alteração
155 
156- [ ] Li o AGENTS.md completo
157- [ ] A mudança filtra por `restaurante_id`?
158- [ ] Tem `try/except` na rota?
159- [ ] Não estou alterando CSS sem pedido?
160- [ ] Não estou commitando `.env`?
161- [ ] Se mudou banco → criei migration nova?
162- [ ] Testei localmente antes de sugerir o deploy?
163 
164---
165 
166## 🐛 Problemas conhecidos (atualizar conforme resolver)
167 
168- [ ] `/api/dashboard/resumo` retorna 500 — causa: query com erro ou tabela faltando
169- [ ] `/admin/adicionais` retorna 500 — mesma causa provável
170- [ ] Logs de DEBUG no `app.py` e `repository.py` — remover após estabilizar
171- [ ] `SESSION_COOKIE_SECURE` desativado temporariamente — reativar após HTTPS estável
172 
173---
174 
175*Última atualização: 27/04/2026*
176