chore: bootstrap MikroRMM local development baseline

- Baseline sobre upstream 2GT-Media-Group-LLC/mikrotik-manager @ 1a4b635 (v0.24.5-beta) - Adiciona docs/SISTEMA_ATUAL.md e CLAUDE.md (documentação operacional) - Ignora .secrets-local/ (nunca versionar secrets) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-08 18:20:03 -03:00
parent 1a4b635052
commit 7a4979e0e1
3 changed files with 155 additions and 0 deletions
@@ -145,3 +145,4 @@ vite.config.ts.timestamp-*
 # macOS
 .DS_Store
 site/
+.secrets-local/
@@ -0,0 +1,24 @@
+# CLAUDE.md — MikroRMM
+
+Antes de alterar qualquer coisa neste projeto, leia nesta ordem:
+1. Este arquivo (`CLAUDE.md`)
+2. `docs/SISTEMA_ATUAL.md`
+3. `git status`
+4. `git log -5 --oneline`
+
+## Regras permanentes
+
+- Buscar causa-raiz antes de aplicar qualquer correção.
+- Não alterar código sem entender o fluxo afetado.
+- Preservar compatibilidade DEV/PROD (mesmo `docker-compose.yml` como base).
+- Nunca versionar secrets. `.env` e `.secrets-local/` ficam fora do Git.
+- Mudança de schema exige migration (`backend/src/db/migrate.ts`), nunca alteração manual do banco.
+- Testes focados primeiro (teste/módulo afetado), depois suíte completa como gate final.
+- Smoke real (`docker compose ps` + `curl https://localhost/api/health`) quando a mudança afetar runtime.
+- Atualizar `docs/SISTEMA_ATUAL.md` quando a mudança alterar arquitetura ou estado de verdade do sistema (não é changelog).
+- Não executar ações destrutivas em RouterBOARD sem missão explícita autorizando.
+- Não conectar clientes reais durante desenvolvimento.
+- Não considerar uma missão concluída com Git sujo (`git status` deve estar limpo, salvo arquivos intencionalmente não commitados e justificados).
+
+## Ambiente local
+Ver seção 12 de `docs/SISTEMA_ATUAL.md`. Stack sobe com `docker compose up -d` a partir de `docker-compose.yml` (build local, não usar `docker-compose.ghcr.yml` em DEV).
@@ -0,0 +1,130 @@
+# MikroRMM — Sistema Atual
+
+## 1. Objetivo do sistema
+Plataforma de gestão e monitoramento de dispositivos MikroTik (RouterOS): inventário de clientes/dispositivos, polling de métricas, backups, automação, alertas, change guard, firmware rollout, topologia de rede.
+
+## 2. Base upstream
+- Projeto: MikroTik Manager (2GT Media Group LLC)
+- Repositório: https://github.com/2GT-Media-Group-LLC/mikrotik-manager
+- Licença: ver `LICENSE` na raiz do repo
+- Remote local: `origin` → https://github.com/2GT-Media-Group-LLC/mikrotik-manager.git
+- Commit baseline: `1a4b6350528b8c656ab7a84ee4806a8a86cf9932` (branch `main`, tag semântica v0.24.5-beta)
+- Branch de trabalho MikroRMM: `mikrormm-dev`
+
+## 3. Arquitetura atual
+Stack Docker Compose com 5 serviços: `nginx` (proxy/reverse proxy + estáticos do frontend), `backend` (API Node/Express + poller + coletor NetFlow), `postgres` (dados relacionais), `redis` (filas BullMQ), `influxdb` (métricas de série temporal).
+
+## 4. Estrutura do repositório
+- `backend/` — API Node.js/TypeScript (Express, BullMQ, Socket.IO, SSH2)
+- `frontend/` — SPA React 19 + Vite + TailwindCSS
+- `nginx/` — Dockerfile, `nginx.conf`, `entrypoint.sh` (gera cert self-signed se ausente)
+- `docs/` — documentação (mkdocs)
+- `scripts/` — utilitários e fixtures de seed
+
+## 5. Containers e serviços
+| Serviço  | Imagem                | Porta host (DEV)      | Healthcheck |
+|----------|-----------------------|------------------------|-------------|
+| nginx    | build local           | 80, 443                | nenhum definido no compose |
+| backend  | build local           | 2055/udp (NetFlow)     | `GET /api/health` |
+| postgres | postgres:15-alpine    | interno                | `pg_isready` |
+| redis    | redis:7-alpine        | interno                | `redis-cli ping` |
+| influxdb | influxdb:2.7          | interno                | `influx ping` |
+
+## 6. Banco de dados
+PostgreSQL 15, banco `mikrotik_manager`, usuário `mikrotik`. Migrations em `backend/src/db/migrate.ts`, executadas automaticamente no boot do backend (idempotente — cria usuário admin default apenas se a tabela `users` estiver vazia).
+
+## 7. Redis / filas
+BullMQ para jobs de polling/automação. `maxmemory` configurável via `REDIS_MAXMEMORY` (default 512mb), política `noeviction` (ver comentário no `docker-compose.yml`).
+
+## 8. InfluxDB / métricas
+InfluxDB 2.7, org/bucket configuráveis via env (`INFLUXDB_ORG`, `INFLUXDB_BUCKET`), token de admin gerado no setup inicial.
+
+## 9. Frontend
+React 19 + Vite + TailwindCSS, servido como estático pelo nginx. Build gera chunk principal >500KB (aviso do Vite, não bloqueante).
+
+## 10. Backend
+Node.js/TypeScript, Express, autenticação JWT, TOTP opcional, OIDC opcional, coletor NetFlow/IPFIX na porta 2055/udp, backups, SSH (ssh2) para RouterOS.
+
+## 11. Autenticação
+JWT (`JWT_SECRET`), senha com bcryptjs, suporte a TOTP e OIDC. Usuário admin default criado na migration inicial (`admin/admin`) — **a senha padrão DEVE ser trocada imediatamente após o primeiro login** (feito nesta instalação DEV; ver seção 12 do CLAUDE.md).
+
+## 12. Ambiente DEV
+- Diretório: `D:\PROJETOS\MIKROTIK RMM\mikrormm` (Windows 11, Git Bash/MINGW64)
+- Docker: 29.6.2 / Compose v5.3.1
+- Compose usado: `docker-compose.yml` (build local a partir do código-fonte, não `docker-compose.ghcr.yml`)
+- Portas publicadas: 80 (HTTP), 443 (HTTPS self-signed), 2055/udp (NetFlow)
+- `.env` local com secrets DEV gerados aleatoriamente (nunca versionado)
+- `TZ=America/Bahia`
+
+## 13. Ambiente PROD planejado
+Infraestrutura Docker dedicada da GTI. Deve manter paridade com DEV (mesmo `docker-compose.yml` como base, variando apenas `.env`/secrets/domínio/CORS). Não implementado nesta missão.
+
+## 14. Variáveis de ambiente
+Somente nomes e finalidade (ver `.env.example` para a lista completa):
+- `HTTP_PORT`, `HTTPS_PORT` — portas publicadas do nginx
+- `TZ` — timezone dos containers
+- `CORS_ORIGIN` — origens permitidas pela API
+- `DB_PASSWORD` — senha do PostgreSQL
+- `JWT_SECRET` — segredo de assinatura JWT
+- `ENCRYPTION_KEY` — chave de criptografia de senhas de dispositivos (32 bytes)
+- `INFLUXDB_TOKEN`, `INFLUXDB_ORG`, `INFLUXDB_BUCKET`, `INFLUXDB_ADMIN_PASSWORD` — InfluxDB
+- `POLLER_*` — tuning do poller de dispositivos
+- `REDIS_MAXMEMORY` — teto de memória do Redis
+
+## 15. Como iniciar
+```bash
+docker compose up -d
+```
+
+## 16. Como parar
+```bash
+docker compose down
+```
+
+## 17. Como rebuildar
+```bash
+docker compose build
+docker compose up -d
+```
+
+## 18. Como verificar saúde
+```bash
+docker compose ps
+curl -k https://localhost/api/health
+```
+
+## 19. Como executar testes
+```bash
+# backend
+cd backend && npm ci && npm test && npm run lint && npx tsc --noEmit
+# frontend
+cd frontend && npm ci && npm test -- --run && npm run lint && npm run build
+```
+
+## 20. Persistência e volumes
+Volumes nomeados: `postgres_data`, `redis_data`, `influxdb_data`, `backups_data`, `certs_data`, `app_data`. Persistência comprovada via `docker compose restart` nesta missão.
+
+## 21. Backup do próprio MikroRMM
+Backend expõe rotas de backup de dispositivos (`backups_data`); backup do próprio stack MikroRMM (dump de `postgres_data`/`influxdb_data`) ainda não documentado/procedimentado — pendente de missão futura.
+
+## 22. Segurança atual
+- `.env` fora do Git (confirmado via `git check-ignore`)
+- Secrets DEV gerados aleatoriamente (DB_PASSWORD 32c, JWT_SECRET 64c hex, ENCRYPTION_KEY 32c, INFLUXDB_TOKEN 64c hex, INFLUXDB_ADMIN_PASSWORD 24c)
+- Senha padrão do admin alterada (ver `.secrets-local/dev-admin-password.txt`, fora do Git)
+- Certificado HTTPS self-signed gerado pelo nginx (`nginx/entrypoint.sh`) — adequado só para DEV
+- Lint de segurança (`eslint-plugin-security`) roda no baseline com 270 (backend) + 108 (frontend) warnings, 0 erros — não corrigido nesta missão (fica para auditoria)
+
+## 23. Integrações atuais
+Nenhuma integração externa real conectada (GLPI, Slack, SFTP, RouterBOARD real) — fora do escopo desta missão.
+
+## 24. Funcionalidades atualmente disponíveis
+Conforme upstream v0.24.5-beta: gestão de clientes/dispositivos, polling, backups, automação, alertas, change guard, firmware rollout, topologia, NetFlow, OIDC, TOTP. Ver `README.md` do upstream para detalhes completos.
+
+## 25. Funcionalidades GTI ainda não implementadas
+Integração GLPI, SFTP, Slack, onboarding customizado, renomeação para "MikroRMM", RouterBOARD real conectada.
+
+## 26. Procedimento para mudanças com IA
+Ver `CLAUDE.md` na raiz do projeto.
+
+## 27. Prompt/missão operacional atual
+**Missão 00 — Preparar Ambiente Dev Local** (concluída): bootstrap e baseline apenas. Clonar upstream, subir stack local via build de código-fonte, validar saúde/login/testes, documentar, manter Git limpo, zero secrets versionados. Proibido nesta missão: renomear o produto, redesenhar UI, implementar GLPI/SFTP/Slack, alterar autenticação/schema/Change Guard, conectar RouterBOARD real, corrigir achados de auditoria. Próxima missão recomendada: **Auditoria Técnica e de Segurança da Base Upstream**.