# Arquitetura Padrão — Fábrica de Apps (Multi-Tenant)

> **planilhaprofissional.com**
> Referência fixa de arquitetura. Não é preenchida por projeto — o PRD de cada app apenas referencia este documento e registra os desvios específicos, se houver.

---

## 1. Camadas Técnicas

| Camada | Componentes |
|---|---|
| **Frontend** | React · TypeScript · Vite · Shadcn/UI |
| **Backend** | Supabase · PostgreSQL · Edge Functions |
| **Segurança** | RLS em todas as tabelas · Políticas de acesso padronizadas · Storage protegido · Perfis (Administrador, Operador, Cliente) |
| **Qualidade** | Playwright (testes automatizados) · Validação de formulários · Tratamento de erros · Logs de auditoria |
| **Publicação** | GitHub · Vercel · Versionamento por ambiente (desenvolvimento, homologação, produção) |

> **Vantagem do modelo:** a partir do segundo app, a estrutura não é reinventada — reutiliza-se uma base já testada e validada.

---

## 2. Conceito Multi-Tenant

Cada empresa possui um identificador único. Todos os tenants compartilham o mesmo banco; o isolamento de dados é feito pelo campo `company_id`. **Nenhum cliente pode visualizar informações de outro cliente.**

| Empresa | Exemplo |
|---|---|
| Empresa A | Pet Shop Feliz |
| Empresa B | Clínica Veterinária Central |
| Empresa C | Mercado Econômico |

---

## 3. Estrutura de Módulos

Módulos previstos, ativáveis ou desativáveis por assinatura:

- PetCare
- Finanças
- Galões
- Supermercado
- CRM
- RH
- Estoque

---

## 4. Estrutura de Domínios

| Domínio | Função |
|---|---|
| `app.planilhaprofissional.com` | Portal principal |
| `petcare.planilhaprofissional.com` | Módulo PetCare |
| `financas.planilhaprofissional.com` | Módulo Finanças |
| `galoes.planilhaprofissional.com` | Módulo Galões |
| `mercado.planilhaprofissional.com` | Módulo Supermercado |
| `crm.planilhaprofissional.com` | Módulo CRM |

---

## 5. Padrão Visual

**Paleta oficial:** `#184A4E` · `#9FA488` · `#CAB77D` · `#ECE4BB` · `#F8F9FA`
**Fonte:** Tahoma em 100% das telas, documentos e materiais.

| Papel | Cor | HEX |
|---|---|---|
| Primária (títulos, botões principais) | Verde principal | `#184A4E` |
| Secundária (apoio, gráficos, destaques) | Verde complementar | `#9FA488` |
| Destaque leve | Dourado | `#CAB77D` |
| Base / linhas | Bege claro | `#ECE4BB` |
| Fundo | Cinza claro | `#F8F9FA` |

> **Regra de ouro:** se tudo chama atenção, nada chama atenção. Cores de alerta (vermelho) e sucesso (verde) são complementares pontuais — nunca substituem a paleta principal.

**Princípios:**
- Interface limpa e profissional
- Responsivo e Mobile First
- Componentização

---

## 6. Padrão de UX Obrigatório (todo app da fábrica)

### 6.1 Menu sanduíche (obrigatório)

- Menu sanduíche em **todos** os apps — **celular e desktop (PC)**
- Mesma estrutura de navegação nos dois formatos
- Itens mínimos do menu: **Comece Aqui** · **LGPD / Termos** · telas funcionais do app · **Alterar Senha** · **Sair**

### 6.2 Aba "Comece Aqui" (obrigatória — primeira aba)

- Deve ser a **primeira aba/tela** após o login (ou na landing, se aplicável)
- Conteúdo obrigatório:
  - Instruções completas de uso do app
  - Passo a passo de primeiros acessos
  - Link para **vídeo do YouTube** com orientações iniciais (URL definida no PRD de cada app)
  - Atalhos para suporte (WhatsApp e e-mail — ver rodapé)

### 6.3 Aba "LGPD / Termos de Uso" (obrigatória)

- Aba dedicada com:
  - Política de privacidade e LGPD
  - Termos de uso e restrições
  - Licença **não exclusiva** — uso pessoal, proibida revenda e redistribuição
  - Sanções em caso de descumprimento
- Texto alinhado ao padrão Planilha Profissional (adaptar detalhes no PRD do app)

### 6.4 Rodapé fixo (obrigatório em todas as telas)

Rodapé visível em **100% das telas** do app, com o conteúdo fixo abaixo:

| Item | Valor |
|------|-------|
| Crédito | Desenvolvido por **planilhaprofissional.com** |
| WhatsApp | +55 66 99238-8026 (link `https://wa.me/5566992388026`) |
| Suporte | suporte@planilhaprofissional.com |

---

## 7. PWA — Obrigatório em todos os apps

- **Todos** os apps da fábrica são **PWA** (Progressive Web App)
- Landing page de apresentação antes do acesso, exibida quando o app ainda **não** está instalado
- Botão **"Instalar App"** sempre visível para quem ainda não instalou:
  - **PC (desktop):** instalação via navegador (Chrome/Edge)
  - **Celular:** instalação na tela inicial (Android/iOS compatível)
- `manifest.json` e `service worker` configurados em todo projeto
- Ícones PWA nos tamanhos padrão (192×192 e 512×512)

---

## 8. Isolamento de Schema e Senhas por App (Supabase)

Cada app possui **isolamento total** — sem comunicação de autenticação ou dados com outros apps.

### 8.1 Regra de ouro

> Um app = um schema PostgreSQL isolado = credenciais isoladas. Nenhum app acessa tabelas ou senhas de outro app.

### 8.2 Schema isolado no Supabase (Table Editor)

Cada app deve ter um **schema próprio** no Supabase, visível e gerenciável no Table Editor:

| App | Schema sugerido | Exemplo |
|-----|----------------|---------|
| PetCare | `petcare` | `petcare.users`, `petcare.audit_logs` |
| Finanças Pro | `financas` | `financas.users`, `financas.transactions` |
| GalõesPro | `galoes` | `galoes.users`, `galoes.orders` |

**Regras:**
- Criar schema dedicado por app — **nunca** misturar tabelas de apps diferentes no schema `public` sem isolamento
- Prefixar ou agrupar todas as tabelas do app dentro do seu schema
- RLS habilitado em **todas** as tabelas do schema
- Políticas de acesso restritas ao schema do próprio app
- Service Role e chaves de API do app acessam **apenas** o schema daquele app

### 8.3 Senha isolada por app

- Cada usuário possui credenciais **válidas somente naquele app** — login do PetCare não funciona no Finanças Pro
- Senhas armazenadas com hash seguro (bcrypt ou padrão Supabase Auth no projeto/schema do app)
- **Sem SSO compartilhado** entre apps até decisão explícita documentada como desvio no PRD

### 8.4 Tabelas mínimas de controle de acesso (por schema)

Cada schema deve conter, no mínimo:

| Tabela | Função |
|--------|--------|
| `users` ou perfil vinculado ao Auth | Usuários do app |
| `user_credentials` ou campo em perfil | Controle de senha (hash — nunca texto puro) |
| `password_change_log` | Histórico de alterações de senha (auditoria) |

**Campo obrigatório para alteração de senhas:**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `password_changed_at` | `timestamptz` | Data/hora da última alteração |
| Tela **Alterar Senha** | UI | Senha atual · nova senha · confirmação · validação de força |

Fluxo obrigatório:
1. Usuário acessa **Alterar Senha** pelo menu sanduíche
2. Informa senha atual + nova senha + confirmação
3. Sistema valida, atualiza hash e grava `password_changed_at`
4. Registro em `password_change_log` e `audit_logs` (ver [AUDITORIA.md](AUDITORIA.md))

### 8.5 Proibições

- Compartilhar tabela de usuários entre apps
- Reutilizar JWT/sessão de um app em outro
- Consultar schema de outro app via Edge Function sem autorização explícita no PRD

---

## 9. Planos e Níveis de Acesso por Compra

O nível de acesso do usuário é definido no momento da compra via Hotmart e armazenado no banco (campo `plan` ou `subscription_tier` por usuário/empresa). O login e a interface se adaptam automaticamente ao plano adquirido — **o usuário nunca vê o que não está no seu plano.**

| Plano | Acesso | Exemplo de uso |
|---|---|---|
| **Gratuito / Trial** | Funcionalidades básicas, prazo limitado | 7 dias de teste sem cartão |
| **Básico** | Módulos essenciais, sem relatórios avançados | Plano entrada — menor valor |
| **Profissional** | Módulos completos + relatórios + exportação | Plano intermediário |
| **Premium / Enterprise** | Todos os módulos + multi-usuário + suporte prioritário | Plano topo — maior valor |

### Regras obrigatórias de implementação

- O campo `plan`/`subscription_tier` é gravado no Supabase no momento da confirmação de compra (webhook Hotmart)
- RLS filtra os dados e funcionalidades pelo plano — **nunca pelo frontend isolado**
- Telas bloqueadas exibem mensagem clara com botão de upgrade (nunca erro genérico)
- Downgrade ou cancelamento reflete imediatamente após confirmação do webhook
- Cada plano deve estar documentado no PRD do app com: nome, preço, módulos incluídos e limitações

---

*Documento de referência fixa — planilhaprofissional.com*
*Qualquer desvio desta arquitetura deve ser registrado no PRD do projeto específico.*