docs(wiki): add Subdominios & DNS Hostinger Manager documentation

Home.md

@@ -25,6 +25,7 @@ Selecione um tópico abaixo para acessar o guia detalhado:
 
 ### 🏢 4. Integração Multi-Tenant SaaS
 * [Integração de Empresa e Plugins Clientes](Plugin_Empresa_Integration.md): Visão geral da comunicação entre o Motor NewWhats e o plugin `newwhats-client` embarcado.
+* [Gerenciador de Subdomínios e DNS (Hostinger)](Subdominios_DNS_Manager.md): Painel central de DNS em tempo real e controle multitenancy de marcas visuais (Logos/Paletas HSL) para subdomínios da rede Clube67.
 
 ---
 

Subdominios_DNS_Manager.md

@@ -0,0 +1,63 @@
+# 🌐 Gerenciador de Subdomínios e DNS (Hostinger)
+
+O **Subdominio.Manager** é a solução de gerenciamento multitenancy de rede e identidade visual da plataforma Clube67. Ele centraliza o apontamento automático de DNS e a personalização visual dos tenants em um console web de alta performance.
+
+---
+
+## 🎨 1. Identidade & Subdomínios (SaaS Multitenancy)
+
+Este módulo controla a **marca visual** de cada cliente (tenant) da rede Clube67 e automatiza o apontamento do seu subdomínio correspondente.
+
+### ⚙️ Fluxo de Funcionamento e Persistência
+Quando um novo subdomínio é registrado através do painel:
+1. **Validação de Nível Único:** O sistema valida o nome do host via RegExp (`/^[a-zA-Z0-9][-a-zA-Z0-9]*$/`) para evitar subdomínios aninhados (ex: `cliente.staging.scoreodonto.com`), garantindo compatibilidade estrita com certificados SSL.
+2. **Criação de Zona DNS (Hostinger):** O backend realiza uma requisição `PUT` para a API de Desenvolvedores da Hostinger (`https://developers.hostinger.com/api/dns/v1/zones/{domain}`), injetando o novo registro (padrão tipo `A` apontando para o IP da VPS 1).
+3. **Persistência de Branding (PostgreSQL):** Caso a Hostinger retorne sucesso, o sistema salva os metadados de identidade visual na tabela `branding` do banco de dados `subdominio` no PostgreSQL local:
+   * **Logo URL:** URL da imagem do logotipo do cliente.
+   * **Cores Primária & Secundária:** Paleta de cores em formato hexadecimal para estilização em tempo de execução.
+   * **Título & Descrição:** Utilizados dinamicamente para injeção de SEO e Meta Tags.
+   * **Favicon URL:** Ícone personalizado da aba do navegador.
+
+### 🗑️ Exclusão Sincronizada (Cleanup Automático)
+Para evitar registros de DNS órfãos e desperdício de recursos, a exclusão de um subdomínio é **sincronizada**:
+* O backend lê as informações de apontamento do banco de dados.
+* Dispara uma requisição `DELETE` para a API da Hostinger, removendo o registro DNS correspondente.
+* Remove os registros correspondentes da tabela `subdomains` e `branding` no banco de dados local.
+
+---
+
+## ☁️ 2. DNS Real-Time (Hostinger)
+
+Uma aba administrativa com conexão direta à zona de DNS dos domínios da Hostinger, funcionando como um console de controle em tempo real.
+
+### 🌟 Funcionalidades Principais
+* **Query em Tempo Real:** Listagem instantânea de toda a tabela de DNS do domínio direto dos servidores da Hostinger (sem cache local).
+* **Filtros Dinâmicos:** Filtro reativo por tipos de registros (A, CNAME, TXT, MX, NS) e busca em tempo real por host ou conteúdo.
+* **Console de Inserção:** Permite adicionar qualquer registro DNS customizado (como chaves de verificação TXT do Google Search Console ou servidores de e-mail MX).
+* **Remoção Instantânea:** Um clique no ícone de lixeira dispara a remoção imediata do registro na API da Hostinger.
+
+---
+
+## 🏗️ 3. Arquitetura Técnica e Deploy GitOps
+
+O painel foi estruturado para suportar atualizações em milissegundos e estabilidade máxima.
+
+### 📦 Estrutura de Docker Compose
+Ambos os microsserviços utilizam montagem direta de volumes (Host ➜ Container) em vez de compilação de código dentro de imagens estáticas:
+* **Frontend:** Executa sobre `nginx:alpine` oficial, montando a pasta `./frontend/dist` e o arquivo `nginx.conf` como volumes de leitura.
+* **Backend:** Roda diretamente no `node:20-alpine`, montando a pasta `./backend` inteira e iniciando com `node server.js`.
+
+### 🚚 Fluxo de Promoção (GitOps)
+Quando o script de deploy mestre `deploy-prod-builder.sh` é acionado na VPS 4 (Laboratório):
+1. Compila o frontend React/TS localmente gerando a pasta `/dist`.
+2. Sincroniza arquivos de infraestrutura (`docker-compose.yml`, `nginx.conf` e scripts) via `rsync` para a VPS 1.
+3. Despacha o backend atualizado e a pasta `/dist` compilada.
+4. O container do Docker Nginx e Node.js refletem as alterações **instantaneamente na hora**, com tempo de inatividade zero.
+
+---
+
+## 🔐 4. Segurança de Credenciais
+
+Todas as comunicações com a Hostinger exigem uma `HOSTINGER_API_KEY` válida. O sistema protege essa chave de duas formas:
+1. **Configuração via Env:** A chave é carregada do arquivo `.env` do backend em produção.
+2. **Configuração Dinâmica:** O administrador pode fornecer a chave em tempo de execução através da interface de fallback. A chave fica salva em memória no backend protegida por CORS, sem nunca ser exposta ao cliente frontend ou ao código do navegador.