ProtectorAnalytics · ProtectorAnalytics · Apr 5, 2026 · Apr 5, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,177 @@
+# Contribuindo para o Protector Traffic Control
+
+Guia para desenvolvedores da equipe Protector trabalharem neste repositório.
+
+---
+
+## Padrão de commits
+
+Seguimos **Conventional Commits** em português:
+
+```
+<tipo>: <descrição curta em imperativo>
+
+[corpo opcional explicando o porquê]
+```
+
+### Tipos aceitos
+
+| Tipo | Uso |
+|---|---|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `docs` | Mudança apenas em documentação |
+| `refactor` | Refatoração sem mudança de comportamento |
+| `perf` | Melhoria de performance |
+| `test` | Adição ou ajuste de testes |
+| `chore` | Tarefas de build, deps, config |
+| `security` | Correção de vulnerabilidade |
+| `UI` | Mudanças de interface |
+
+### Exemplos
+
+```
+feat: adiciona importação de veículos via Excel
+fix: corrige timezone nas capturas exibidas no dashboard
+security: sanitiza input do serial da câmera contra SQL injection
+docs: atualiza manual técnico com passo de reinicialização
+```
+
+---
+
+## Fluxo de branches
+
+- **`main`**: produção. Deploy automático na Vercel após merge.
+- **`develop`**: integração (opcional, se o time preferir).
+- **`feat/*`**: nova funcionalidade (ex: `feat/importacao-excel`).
+- **`fix/*`**: correção de bug (ex: `fix/heartbeat-offline`).
+- **`docs/*`**: apenas documentação (ex: `docs/github-readme`).
+- **`security/*`**: correção de vulnerabilidade.
+- **`refactor/*`**: refatoração.
+
+### Fluxo padrão
+
+```bash
+git checkout main
+git pull
+git checkout -b feat/minha-feature
+
+# ... código ...
+
+git add .
+git commit -m "feat: descrição"
+git push -u origin feat/minha-feature
+
+# abrir PR no GitHub
+```
+
+---
+
+## Pull Requests
+
+### Checklist antes de abrir PR
+
+- [ ] Código testado localmente (`npm run dev`)
+- [ ] Sem credenciais/tokens commitados
+- [ ] Variáveis novas adicionadas ao `.env.example`
+- [ ] Migrations SQL em `sql/` se schema mudou
+- [ ] Documentação atualizada se comportamento mudou
+- [ ] Commits seguem Conventional Commits
+
+### Template de PR
+
+```markdown
+## O que muda
+<descrição em 1-2 linhas>
+
+## Por quê
+<motivação/contexto>
+
+## Como testar
+1. ...
+2. ...
+
+## Checklist
+- [ ] Testado localmente
+- [ ] Docs atualizadas
+- [ ] Sem breaking changes (ou documentadas)
+```
+
+---
+
+## Padrões de código
+
+### JavaScript (Node.js)
+
+- **CommonJS** (`require`/`module.exports`) — compatibilidade com Vercel Functions
+- **2 espaços** de indentação
+- **async/await** sobre callbacks
+- Validar **todos** os inputs de APIs públicas (`lib/validators.js`)
+- **Nunca** expor `service_role key` ao frontend
+- Tratar erros com `try/catch` e gravar em `debug_log` quando relevante
+
+### SQL
+
+- Nome de tabelas e colunas em **snake_case** e português
+- **UUID** como PK em todas as tabelas novas
+- **RLS habilitado** por padrão em tabelas novas
+- Migrations em `sql/migration-<nome>.sql`, nunca editar `schema.sql` diretamente
+- Sempre incluir `criado_em TIMESTAMPTZ DEFAULT now()`
+
+### Frontend (dashboard/admin)
+
+- HTML/JS puro (sem framework)
+- **Nunca** armazenar `service_role key` no frontend
+- Usar `anon key` do Supabase + RLS
+- Atualização automática do dashboard a cada 30s
+
+---
+
+## Segurança
+
+**Antes de commitar**:
+
+- [ ] Sem `.env` no stage (`git status`)
+- [ ] Sem tokens/senhas hardcoded
+- [ ] Inputs validados e sanitizados
+- [ ] Sem exposição de `SUPABASE_SERVICE_KEY` em código client-side
+
+**Vulnerabilidades críticas**: criar branch `security/*` e abrir PR como prioridade.
+
+---
+
+## Testes locais
+
+```bash
+# Rodar dev server (Vercel emulado)
+npm run dev
+
+# Testar captura com payload mock
+npm run test:captura
+
+# Criar super admin (primeira vez)
+SUPABASE_URL=... SUPABASE_SERVICE_KEY=... \
+SUPER_ADMIN_EMAIL=admin@protector.com.br \
+SUPER_ADMIN_SENHA=SuaSenha \
+node scripts/create-super-admin.js
+```
+
+---
+
+## Deploy
+
+- **Preview**: cada PR gera URL de preview automaticamente na Vercel
+- **Produção**: merge em `main` dispara deploy automático
+
+**Variáveis de ambiente**: gerenciadas no dashboard Vercel. Ao adicionar nova variável, documentar no `.env.example` e em `docs/IMPLANTACAO.md`.
+
+---
+
+## Contato
+
+- **Repositório**: github.com/ProtectorAnalytics/protector-lombada
+- **Dúvidas técnicas**: equipe Protector Sistemas
+
+---
+
+**Protector Sistemas** — Guia de contribuição · Abril 2026
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,50 @@
+PROTECTOR TRAFFIC CONTROL - LICENÇA DE SOFTWARE PROPRIETÁRIO
+
+Copyright (c) 2026 Protector Sistemas. Todos os direitos reservados.
+
+Este software e sua documentação associada ("Software") são propriedade
+intelectual exclusiva da Protector Sistemas e estão protegidos pelas leis
+de direitos autorais do Brasil (Lei 9.610/1998), pela Lei de Software
+(Lei 9.609/1998) e por tratados internacionais.
+
+RESTRIÇÕES:
+
+1. É PROIBIDA a reprodução, distribuição, modificação, engenharia reversa,
+   descompilação, disassembly ou criação de obras derivadas deste Software,
+   no todo ou em parte, sem autorização prévia e expressa por escrito da
+   Protector Sistemas.
+
+2. É PROIBIDO o uso comercial, sublicenciamento, venda, aluguel,
+   empréstimo ou qualquer forma de cessão deste Software a terceiros sem
+   autorização prévia e expressa por escrito da Protector Sistemas.
+
+3. O acesso ao código-fonte por colaboradores, clientes ou parceiros está
+   condicionado à assinatura de contratos específicos de confidencialidade
+   (NDA) e/ou licenciamento.
+
+4. O Software é licenciado aos clientes finais no modelo SaaS (Software
+   como Serviço), mediante contrato comercial específico, sem transferência
+   de propriedade intelectual ou direito de acesso ao código-fonte.
+
+AUSÊNCIA DE GARANTIA:
+
+O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIAS DE QUALQUER NATUREZA,
+EXPRESSAS OU IMPLÍCITAS, INCLUINDO, MAS NÃO SE LIMITANDO A, GARANTIAS DE
+COMERCIALIZAÇÃO, ADEQUAÇÃO A UM PROPÓSITO ESPECÍFICO E NÃO VIOLAÇÃO.
+
+LIMITAÇÃO DE RESPONSABILIDADE:
+
+EM NENHUMA HIPÓTESE A PROTECTOR SISTEMAS SERÁ RESPONSÁVEL POR QUAISQUER
+DANOS DIRETOS, INDIRETOS, INCIDENTAIS, ESPECIAIS, EXEMPLARES OU
+CONSEQUENCIAIS DECORRENTES DO USO OU DA IMPOSSIBILIDADE DE USO DESTE
+SOFTWARE, AINDA QUE TENHA SIDO AVISADA DA POSSIBILIDADE DE TAIS DANOS.
+
+CONTATO:
+
+Para solicitações de licenciamento, parcerias ou dúvidas:
+Protector Sistemas
+https://protectorsistemas.com.br
+
+---
+
+All Rights Reserved. Proprietary and Confidential.
diff --git a/README.md b/README.md
@@ -0,0 +1,148 @@
+# Protector Traffic Control
+
+> Plataforma web para gerenciamento de **Lombadas Educativas Inteligentes** com câmeras ALPHADIGI — detecção de placas, medição de velocidade por radar e notificação automática para condomínios e vias privadas.
+
+**Versão 2.0** · Proprietário: [Protector Sistemas](https://protectorsistemas.com.br)
+
+---
+
+## O que é
+
+Sistema SaaS que integra câmeras ALPHADIGI instaladas em lombadas educativas, captura placas e velocidade dos veículos que passam, e gera notificações em PDF por e-mail quando o limite configurado é ultrapassado. O documento é **meramente educativo** — não tem valor de multa oficial.
+
+**Casos de uso:**
+- Condomínios residenciais com lombada interna
+- Vias privadas (hotéis, resorts, empresas, universidades)
+- Controle de velocidade orientativo em áreas de pedestres
+
+---
+
+## Arquitetura em 1 parágrafo
+
+A câmera ALPHADIGI instalada no local envia (via HTTP Push) os dados de cada passagem para um endpoint único na Vercel (`/placa`). O backend identifica a câmera pelo serial embutido no payload, valida, salva a foto no Supabase Storage e os metadados no PostgreSQL. Se a velocidade excede o limite do cliente, gera um PDF personalizado via PDFKit e dispara e-mail (Nodemailer/SMTP) para os destinatários cadastrados. Dashboard web em tempo real e painel admin multi-tenant complementam o fluxo.
+
+Fluxo completo em [`docs/ARQUITETURA.md`](docs/ARQUITETURA.md).
+
+---
+
+## Stack
+
+| Camada | Tecnologia |
+|---|---|
+| **Runtime** | Node.js serverless (Vercel Functions) |
+| **Banco de dados** | Supabase (PostgreSQL + RLS) |
+| **Storage** | Supabase Storage (bucket privado) |
+| **Frontend** | HTML + JS (SPA) — `dashboard/` e `admin/` |
+| **PDF** | PDFKit |
+| **E-mail** | Nodemailer (SMTP cPanel / Gmail) |
+| **Imagens** | Sharp (redimensionamento/otimização) |
+| **Hardware** | Câmeras ALPHADIGI (radar + OCR de placa) |
+| **Deploy** | Vercel + Cron de limpeza diária |
+
+---
+
+## Documentação
+
+| Documento | Para quem | Conteúdo |
+|---|---|---|
+| [`docs/MANUAL_USUARIO.md`](docs/MANUAL_USUARIO.md) | Síndico / operador | Como usar dashboard, cadastrar veículos, gerenciar alertas |
+| [`docs/MANUAL_TECNICO.md`](docs/MANUAL_TECNICO.md) | Técnico de campo | Configuração completa da câmera ALPHADIGI (campo a campo) |
+| [`docs/IMPLANTACAO.md`](docs/IMPLANTACAO.md) | DevOps / admin | Deploy do zero: Supabase → Vercel → primeiro cliente |
+| [`docs/ARQUITETURA.md`](docs/ARQUITETURA.md) | TI / auditoria | Fluxo de dados, diagrama e decisões técnicas |
+| [`docs/LGPD.md`](docs/LGPD.md) | Jurídico / DPO | Papéis, bases legais, retenção, medidas de segurança |
+
+---
+
+## Quick start
+
+```bash
+# 1. Clonar e instalar
+git clone https://github.com/ProtectorAnalytics/protector-lombada.git
+cd protector-lombada
+npm install
+
+# 2. Configurar variáveis de ambiente
+cp .env.example .env
+# (preencher SUPABASE_*, SMTP_* e CRON_SECRET)
+
+# 3. Rodar localmente
+npm run dev   # usa vercel dev
+```
+
+Deploy em produção: seguir [`docs/IMPLANTACAO.md`](docs/IMPLANTACAO.md).
+
+---
+
+## Endpoints principais
+
+| Rota | Método | Função |
+|---|---|---|
+| `/placa` | POST | Recebe capturas das câmeras ALPHADIGI |
+| `/api/heartbeat` | POST | Sinal de vida das câmeras (a cada 10 s) |
+| `/api/config` | GET | Config pública do Supabase para frontend |
+| `/api/cron-limpeza` | GET | Limpeza de capturas > 15 dias (cron diário 06:00) |
+| `/api/admin/*` | CRUD | Clientes, câmeras, usuários, veículos, e-mails, dashboard |
+| `/admin` | UI | Painel multi-tenant (super_admin) |
+| `/dashboard` | UI | Dashboard do cliente (admin_cliente / operador) |
+
+---
+
+## Limites operacionais
+
+- **Rate limit**: 120 req/min por câmera
+- **Retenção de capturas**: 15 dias (apagadas por cron diário)
+- **Offline threshold**: câmera marcada como offline após 5 min sem heartbeat
+- **Tamanho máx. de foto**: otimizado via Sharp antes do upload
+
+---
+
+## Segurança
+
+- Conexão HTTPS obrigatória
+- Autenticação JWT (Supabase Auth)
+- Row Level Security (RLS) habilitado em todas as tabelas
+- Bucket de fotos **privado** (acesso via signed URL)
+- Rate limit por câmera
+- Log de auditoria (`audit_log`) para operações sensíveis
+- Três perfis de acesso: `super_admin`, `admin_cliente`, `operador`
+
+Tratamento de dados pessoais detalhado em [`docs/LGPD.md`](docs/LGPD.md).
+
+---
+
+## Estrutura do repositório
+
+```
+protector-lombada/
+├── api/              # Vercel Functions (serverless)
+│   ├── admin/        # Endpoints do painel admin (CRUD)
+│   ├── captura.js    # Recebe dados das câmeras
+│   ├── heartbeat.js  # Health check das câmeras
+│   └── cron-limpeza.js
+├── lib/              # Lógica compartilhada (Supabase, PDF, e-mail, auth)
+├── site/             # Landing page
+├── dashboard/        # SPA do cliente
+├── admin/            # SPA do admin
+├── sql/              # Schema + migrations do Supabase
+├── scripts/          # Utilitários (create-super-admin, etc.)
+├── docs/             # Documentação
+├── .env.example
+├── vercel.json
+└── package.json
+```
+
+---
+
+## Contribuindo
+
+Contribuições internas seguem o guia em [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+---
+
+## Licença
+
+Software proprietário. Todos os direitos reservados à Protector Sistemas. Ver [`LICENSE`](LICENSE).
+
+---
+
+**Protector Traffic Control** — Lombada Educativa Inteligente