01. Resumo para Leigos

02. Analogia: O que é hospedagem?

O que é um servidor?

Um servidor (Server) é um computador ligado 24 horas por dia, 7 dias por semana, que guarda os arquivos do seu site e os mostra quando alguém visita seu endereço na internet.

O que é um domínio?

Um domínio (Domain) é o endereço que você digita no navegador. Exemplo: starhosting.com.br. É como o CEP da sua casa, mas na internet.

O que é uma hospedagem?

Hospedagem (Hosting) é o serviço de "alugar um pedacinho de servidor" para guardar os arquivos do seu site. Sem hospedagem, seu site não aparece na internet.

03. Por que o StarHosting existe?

Problemas que o StarHosting resolve

Quem se beneficia?

• Dono do sistema (Admin) — lucra com as assinaturas dos clientes
• Parceiros — ganham comissão por trazer clientes
• Clientes — ganham um site profissional sem saber programar

Fluxo completo de uma venda

04. Quem usa o sistema?

O sistema tem 3 tipos de usuários (chamados de roles ou níveis):

Fonte: db.php, tabela "usuarios", campo "nivel" (linhas 17-27)

05. O que cada pessoa faz no sistema?

admin Administrador

• Cria e gerencia parceiros e clientes
• Cria sites com criação automatizada (Nginx + SSL)
• Acessa ferramentas de administração do servidor
• Visualiza logs de atividade de todos os usuários
• Corrige permissões e configurações do servidor

URLs de acesso:

• Login: /admin/login
• Dashboard: /admin/
• Clientes: /admin/clientes
• Parceiros: /admin/coordenadores
• Sites: /admin/sites
• Ferramentas: /admin/sites (aba Ferramentas)
• Logs: /admin/logs

parceiro Parceiro / Coordenador

• Gerencia seus próprios clientes (cria, edita, desativa)
• Gerencia os sites de seus clientes
• Configura domínios para os sites

URLs de acesso:

• Login: /login
• Dashboard: /painel/ ou /parceiro/
• Clientes: /painel/clientes
• Sites: /painel/sites

cliente Cliente

• Visualiza seus sites
• Faz upload e deleta arquivos
• Aplica templates nos sites
• Edita informações do site (título, logo, etc.)
• Visualiza suas notificações e logs

URLs de acesso:

• Login: /login
• Dashboard: /cliente/
• Site: /cliente/site?id=X
• Upload: /cliente/upload?site_id=X
• Template: /cliente/template?id=X
• Editar: /cliente/editar?id=X

06. Diagrama de Componentes

O que acontece quando você visita um site?

1. Você digita starhosting.com.br no navegador.
2. O DNS (Domain Name System) traduz o endereço para o IP 137.131.229.136.
3. O Nginx recebe a requisição na porta 443 (HTTPS).
4. Se for uma página PHP (como /admin), o Nginx envia para o PHP-FPM.
5. O PHP-FPM executa o código, acessa o SQLite, e devolve o HTML.
6. O navegador mostra a página para você.

07. Tecnologias Utilizadas

Fonte: CHANGELOG.md (linhas 1-50), config.php, main.py

08. Estrutura de Diretórios

09. Banco de Dados (SQLite)

Tabela: usuarios (quem usa o sistema)

Fonte: db.php, linhas 17-27

Tabela: sites (os sites criados)

Fonte: db.php, linhas 29-42

Tabela: logs_acao (registro de ações)

Fonte: db.php, linhas 44-52

Tabela: notificacoes (avisos para o usuário)

Fonte: db.php, linhas 54-62

Tabela: templates (modelos de site)

Fonte: db.php, linhas 64-71

Relacionamento entre tabelas

10. Autenticação e Sessões

Como funciona o fluxo de login?

O que é bcrypt?

BCrypt é um algoritmo de criptografia que transforma sua senha em uma sequência de caracteres que NINGUÉM consegue decifrar. Mesmo se alguém roubar o banco de dados, não vai conseguir ver sua senha.

Exemplo:

Código PHP que faz isso:

// Auth.php - Função login()
function login($email, $senha) {
    $db = getDB();
    $stmt = $db->prepare('SELECT * FROM usuarios WHERE email = :email AND ativo = 1');
    $stmt->bindValue(':email', $email, SQLITE3_TEXT);
    $result = $stmt->execute();
    $user = $result->fetchArray(SQLITE3_ASSOC);
    
    // password_verify() compara a senha digitada com o hash salvo
    if ($user && password_verify($senha, $user['senha_hash'])) {
        $_SESSION['user_id'] = $user['id'];
        $_SESSION['user_nome'] = $user['nome'];
        $_SESSION['user_email'] = $user['email'];
        $_SESSION['user_nivel'] = $user['nivel'];
        $_SESSION['user_coordenador_id'] = $user['coordenador_id'];
        return $user['nivel']; // Retorna "admin", "parceiro" ou "cliente"
    }
    return false; // Senha errada ou usuário inativo
}

Fonte: auth.php, linhas 4-23

Como o sistema protege as páginas?

Existem 3 funções de proteção:

Fonte: auth.php, linhas 38-65

11. Sistema de Tiers (Planos)

Fonte: config.php, linhas 19-23

Como o código valida os limites?

// functions.php - Verificar limite de sites
function checkSiteLimit($cliente_id, $tier) {
    $config = getConfig();
    $limit = $config['tier_limits'][$tier]['sites'] ?? 0;
    $db = getDB();
    $current = (int)$db->querySingle(
        "SELECT COUNT(*) FROM sites WHERE cliente_id = $cliente_id"
    );
    return $current < $limit; // true se pode criar mais
}

// functions.php - Verificar espaço em disco
function checkDiskLimit($cliente_id, $tier) {
    $config = getConfig();
    $limit_mb = $config['tier_limits'][$tier]['disco_mb'] ?? 0;
    $used_mb = calculateDiskUsage($cliente_id);
    return $used_mb < $limit_mb;
}

Fonte: functions.php, linhas 179-211

12. Templates de Sites

Templates são modelos prontos de site. Quando um cliente cria um site, ele pode escolher um template e o sistema gera o HTML automaticamente.

Templates disponíveis (Tier Basic)

Fonte: CHANGELOG.md (linhas 44-50)

13. Sistema de Email

O sistema usa PHPMailer para enviar emails via Brevo SMTP (antigo Sendinblue).

Configuração SMTP

Fonte: .env, linhas 6-12

Como enviar um email (código PHP)

// Importar a função
require_once __DIR__ . '/functions/email.php';

// Enviar email simples
sendEmail(
    'cliente@email.com',           // Destinatário
    'Bem-vindo ao StarHosting',    // Assunto
    '<h1>Olá!</h1><p>Seu site foi criado.</p>',  // Corpo HTML
    'admin'                        // Remetente (admin/suporte/noreply)
);

// Enviar email de suporte
sendEmail(
    'cliente@email.com',
    'Seu ticket foi respondido',
    '<p>Sua solicitação foi atendida.</p>',
    'suporte'
);

Remetentes disponíveis

Fluxo de envio

Arquivo de configuração

A função sendEmail() está em:

/var/www/gerenciador/php/functions/email.php

Fonte: functions/email.php (60 linhas)

14. PWA (App Instalável)

O StarHosting tem suporte a PWA com:

• manifest.json — arquivo que diz ao celular como instalar o app
• sw.js (Service Worker) — faz o app funcionar offline
• Ícones em diferentes tamanhos para celular

Arquivos do PWA

Como funciona o Service Worker

// Quando instala, salva páginas principais no cache
self.addEventListener('install', e => {
  e.waitUntil(
    caches.open('starhosting-v1').then(cache => {
      return cache.addAll([
        '/painel',          // Página do painel
        '/admin',           // Página do admin
        '/static/style.css' // CSS do sistema
      ]);
    })
  );
});

// Quando visita uma página, primeiro tenta cache
self.addEventListener('fetch', e => {
  e.respondWith(
    caches.match(e.request).then(resp => {
      return resp || fetch(e.request);  // Cache ou rede
    })
  );
});

Fonte: pwa/sw.js (69 linhas)

Como instalar no celular

1. Abra starhosting.com.br no Chrome do celular
2. Toque no botão "⋮" (três pontos) no canto superior direito
3. Toque em "Adicionar à tela inicial"
4. Confirme o nome e toque em "Adicionar"
5. Pronto! Agora tem um ícone do StarHosting na tela do celular

15. Domínios e SSL

Domínios configurados

Fonte: CHANGELOG.md (linhas 34-38)

SSL (Certificado de Segurança)

Fonte: config.php (linhas 10-11), /etc/nginx/sites-available/starhosting (linhas 13-14)

Segurança do Nginx

O Nginx bloqueia acesso a arquivos internos:

# Bloquear arquivos internos
location ~ ^/(config|functions|auth|db)\.php$ { deny all; }
location ~ ^/includes/ { deny all; }
location ~ /\. { deny all; }                    # Arquivos ocultos
location ~ \.(db|sqlite|env)$ { deny all; }    # Banco e config

Fonte: /etc/nginx/sites-available/starhosting (linhas 38-41)

16. Visão Geral dos Endpoints

O StarHosting tem 3 domínios com 2 backends diferentes:

Total de endpoints: 44 (27 páginas HTML + 6 JSON PHP + 4 JSON FastAPI + 3 static + 2 debug + 2 auth)

17. Autenticação da API

PHP (starhosting.com.br) — Sessões

Usa sessões PHP (cookies). Quando o usuário faz login, o servidor cria uma sessão e guarda os dados do usuário. O navegador envia o cookie de sessão automaticamente a cada pedido.

// Como funciona internamente:
// 1. Usuário envia email + senha
// 2. Servidor verifica no banco (SQLite)
// 3. Se correto, cria sessão com dados do usuário
// 4. Envia cookie "PHPSESSID" para o navegador
// 5. Navegador envia cookie a cada pedido
// 6. Servidor lê cookie e sabe quem é o usuário

// Exemplo de como verificar login:
if (!isLoggedIn()) {
    // Não está logado → redirecionar para login
    header('Location: /login');
    exit;
}

// Exemplo de como verificar se é admin:
requireAdmin();  // Redireciona se não for admin

Fonte: auth.php (login(), isLoggedIn(), requireAdmin())

FastAPI (ai.ckvm.duckdns.org) — API Key

Usa API Key no header X-API-Key. A chave é validada contra a variável de ambiente INTERNAL_API_KEY.

// Como funciona internamente:
// 1. Cliente envia request com header X-API-Key
// 2. FastAPI lê a variável de ambiente INTERNAL_API_KEY
// 3. Compara as duas chaves
// 4. Se forem iguais, processa o pedido
// 5. Se forem diferentes, retorna erro 401

// Exemplo de chamada com curl:
curl -X POST https://ai.ckvm.duckdns.org/api/v1/analise \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2c33bb2a66d7e1aa96f262d9d9429edc47e53ca6e167dbc30894c935a93d687" \
  -d '{"id_camera": "cam01", "imagem_base64": "..."}'

Fonte: ai-api/main.py (middleware de autenticação)

Comparação dos dois sistemas

18. Login/Logout

Endpoints de autenticação

Fluxo completo de login

Fluxo de logout

// O que acontece quando você clica em "Sair":
// 1. Navegador envia GET /logout
// 2. Servidor destroi a sessão (session_destroy())
// 3. Servidor redireciona para /
// 4. Navegador perde o cookie PHPSESSID
// 5. Usuário não está mais logado

// Código simplificado:
session_start();
session_destroy();           // Destroi a sessão
header('Location: /');       // Redireciona para home
exit;

Onde cada perfil vai após login

Fonte: auth.php (login(), logout()), login.php, logout.php

Fonte: login.php, logout.php, admin/login.php

19. Painel Admin (HTML)

Fonte: admin/index.php, admin/clientes.php, admin/sites.php, admin/logs.php

20. Admin API JSON (tools.php)

URL: /admin/api/tools.php?action=X

Método: GET

Auth: Admin (session)

Resposta: JSON

Fonte: admin/api/tools.php (197 linhas)

Exemplo de resposta JSON (get_server_status)

{
    "ok": true,
    "owner": "ubuntu:www-data",
    "perms": "2775",
    "nginx": "active",
    "php": "active",
    "disk": {
        "total": "193G",
        "used": "21G",
        "percent": "11%"
    },
    "ram": {
        "total": "23Gi",
        "used": "7.1Gi",
        "free": "15Gi"
    },
    "uptime": "2 days, 3:45",
    "ssl_certs": 3,
    "sites": 3
}

Função runLocal() vs run()

21. Painel Parceiro

Quem pode acessar?

Endpoints do Painel Parceiro

Como o parceiro cria um cliente

// Quando o parceiro preenche o formulário e clica "Criar":
// 1. POST /painel/clientes com: nome, email, senha, tier
// 2. Sistema cria o usuário no banco SQLite
// 3. Automaticamente define coordenador_id = ID do parceiro logado
// 4. Envia email de boas-vindas para o novo cliente
// 5. Cliente pode acessar /painel com suas credenciais

// Código simplificado:
requireCoordOrAdmin();
$cliente_id = $_SESSION['user_id'];  // ID do parceiro logado
// ...
$stm->execute([
    $nome, $email, $senha_hash, $tier,
    $cliente_id  // ← Isso vincula o cliente ao parceiro
]);

Fonte: painel/site_create.php, painel/clientes.php

22. Painel Cliente

O que o cliente pode fazer?

Endpoints do Painel Cliente

O que significa "Login+Owner"?

O sistema verifica se o usuário está logado E se o site pertence a ele. Exemplo:

// cliente/site.php
requireLogin();
$site = getSiteById($_GET['id']);
if ($site['cliente_id'] != $_SESSION['user_id']) {
    // Este site NÃO é seu! Acesso negado.
    header('Location: /cliente/');
    exit;
}

Fonte: cliente/site.php, cliente/upload.php

23. API de IA (FastAPI)

Domínio: ai.ckvm.duckdns.org

Backend: FastAPI (Python)

Modelo: Qwen2.5-VL 3B (via Ollama)

Request body: /api/v1/analise

{
    "id_camera": "cam01",          // ID da câmera (obrigatório)
    "imagem_base64": "base64...",  // Imagem em Base64 (obrigatório)
    "formato": "jpeg",             // Formato da imagem (opcional, default: jpeg)
    "prompt_customizado": "..."    // Prompt personalizado (opcional)
}

Response: /api/v1/analise

{
    "status": "sucesso",
    "data_processamento": "2026-06-03T04:00:00",
    "tempo_execucao_segundos": 2.35,
    "total_objetos": 5,
    "resultado": {
        "total_objetos": 5,
        "objetos": [
            {
                "classe": "garrafa",
                "confianca": 0.95,
                "bounding_box": {"x1": 100, "y1": 200, "x2": 300, "y2": 500}
            }
        ]
    }
}

Request body: /api/v1/chat

{
    "id_sessao": "sessao_abc123",           // ID da sessão (qualquer string)
    "historico_mensagens": [                // Lista de mensagens (mínimo 1)
        {
            "role": "user",                 // "user" ou "assistant"
            "content": "Olá!",              // Texto da mensagem
            "images": ["base64..."]         // Opcional: imagens em base64
        }
    ],
    "num_ctx": 32768                        // Opcional: contexto do modelo (default 32768)
}

Campos do Request

Response: /api/v1/chat

{
    "status": "sucesso",
    "id_sessao": "sessao_abc123",
    "data_resposta": "2026-06-03T07:00:00.123456",
    "mensagem_resposta": {
        "role": "assistant",
        "content": "Olá! Tudo bem sim, e você?"
    },
    "performance": {
        "eval_count": 12,
        "tokens_por_segundo": 7.5
    }
}

Campos do Response

Exemplo de chamada (curl)

# Chat simples (texto)
curl -X POST http://localhost:8080/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY_AQUI" \
  -d '{
    "id_sessao": "minha_sessao",
    "historico_mensagens": [
        {"role": "user", "content": "Olá, tudo bem?"}
    ]
  }'

# Chat com imagem (multimodal)
BASE64=$(base64 -w 0 minha_foto.jpg)
curl -X POST http://localhost:8080/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY_AQUI" \
  -d "{
    \"id_sessao\": \"minha_sessao\",
    \"historico_mensagens\": [
        {
            \"role\": \"user\",
            \"content\": \"O que tem nesta imagem?\",
            \"images\": [\"$BASE64\"]
        }
    ]
  }"

Como funciona o fluxo

Chat multimodal (com imagens)

O campo images aceita uma lista de strings Base64. Use isso para enviar imagens junto com o texto.

{
    "id_sessao": "analise_foto",
    "historico_mensagens": [
        {
            "role": "user",
            "content": "Analise esta imagem e descreva o que vê",
            "images": ["data:image/jpeg;base64,/9j/4AAQSkZJRg..."]
        }
    ],
    "num_ctx": 32768
}

Diferença entre /api/chat e /api/generate

Configuração do modelo (Ollama)

Fonte: ai-api/config.py, CHANGELOG.md (linhas 14-24)

Resultados Reais da API de Visão

10 imagens reais processadas pela API em 03/06/2026. Cada imagem foi enviada para o modelo qwen2.5vl:3b via /api/v1/analise.

Imagem	Objetos Detectados	Tempo	Descrição
	10 carros	129s	Cena urbana com múltiplos carros em estacionamento/rua
	10+ pessoas	246s	Multidão de pedestres em rua movimentada
	10+ pessoas	246s	Grupo de pessoas em ambiente externo
	3 pessoas, 2 motos	165s	Pessoas e motocicletas em rua
	Pessoas, 2 motos	148s	Cena com motocicletas e pedestres
	1 carro + objetos	245s	Carro em estacionamento com múltiplos objetos
	20+ pessoas	246s	Grupo grande de pessoas em evento/rua
	1 carro	124s	Carro isolado em cena
	1 pessoa	135s	Pessoa em plano próximo
	1 supermercado	17s	Fachada de supermercado/loja

Exemplo de resposta JSON real (pic08.jpg — 1 carro detectado)

{
    "status": "sucesso",
    "data_processamento": "2026-06-03T06:54:25.755305",
    "tempo_execucao_segundos": 123.58,
    "total_objetos": 0,
    "resultado": {
        "raw_response": "```json\n{\n  \"objetos\": [\n    {\n      \"nome\": \"carro\",\n      \"coordenadas\": [217, 210, 330, 332],\n      \"confianca\": 0.9\n    }\n  ],\n  \"total\": 1\n}\n```"
    }
}

Exemplo de resposta JSON real (pic04.jpg — 3 pessoas + 2 motos)

{
    "status": "sucesso",
    "data_processamento": "2026-06-03T06:41:43.013860",
    "tempo_execucao_segundos": 165.19,
    "resultado": {
        "raw_response": "```json\n{\n  \"objetos\": [\n    {\n      \"nome\": \"pessoa\",\n      \"coordenadas\": [\n        [79, 100, 156, 310],\n        [161, 94, 293, 326],\n        [282, 104, 408, 330]\n      ],\n      \"confianca\": 0.9\n    },\n    {\n      \"nome\": \"motocicleta\",\n      \"coordenadas\": [\n        [156, 154, 294, 328],\n        [282, 159, 408, 330]\n      ],\n      \"confianca\": 0.9\n    }\n  ],\n  \"total\": 2\n}\n```"
    }
}

Resumo dos tempos de processamento

Tempo médio: ~170 segundos (2 min 50s) por imagem em CPU ARM.

24. Tabela Resumo de Todos os Endpoints

25. Como Rodar o Sistema

Verificar status dos serviços

# Verificar Nginx (servidor web)
sudo systemctl status nginx
# Deve mostrar: Active: active (running)

# Verificar PHP-FPM (executa código PHP)
sudo systemctl status php8.3-fpm
# Deve mostrar: Active: active (running)

# Verificar Ollama (inteligência artificial)
systemctl status ollama
# Deve mostrar: Active: active (running)

# Verificar FastAPI (API de IA)
systemctl status ai-api
# Deve mostrar: Active: active (running)

# Verificar disco (quanto espaço sobrou)
df -h
# Deve mostrar: /dev/sda1  11% used (21G/193G)

# Verificar RAM (quanta memória está usando)
free -h
# Deve mostrar: 7.1Gi/23Gi used

Reiniciar serviços

# Reiniciar Nginx (se o site não carrega)
sudo systemctl restart nginx

# Reiniciar PHP-FPM (se o PHP não executa)
sudo systemctl restart php8.3-fpm

# Reiniciar Ollama (se a IA não responde)
sudo systemctl restart ollama

# Reiniciar FastAPI (se a API de IA não responde)
sudo systemctl restart ai-api

Verificar logs (quando algo dá errado)

# Logs do Nginx (erros de servidor web)
sudo tail -f /var/log/nginx/error.log

# Logs do Nginx (quem acessou o site)
sudo tail -f /var/log/nginx/access.log

# Logs do PHP (erros de código PHP)
sudo tail -f /var/log/php8.3-fpm.log

# Logs do Ollama (erros da IA)
journalctl -u ollama -f

# Logs do FastAPI (erros da API de IA)
journalctl -u ai-api -f

Quando usar cada comando

Fonte: CHANGELOG.md, testes de deploy

26. Como Criar uma Página Nova

Passo 1: Criar o arquivo PHP

# Exemplo: criar página "relatorios" no painel admin
nano /var/www/gerenciador/php/admin/relatorios.php

Passo 2: Usar o template base

<?php
require_once __DIR__ . '/../../config.php';
require_once __DIR__ . '/../../db.php';
require_once __DIR__ . '/../../auth.php';

requireAdmin(); // Protege para admin apenas

$titulo = "Relatórios";
?>
<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?= $titulo ?> - StarHosting</title>
    <link rel="stylesheet" href="/static/style.css">
</head>
<body>
    <h1>Relatórios do Sistema</h1>

    <!-- Seu conteúdo aqui -->
    <p>Total de clientes: <?= count(getAllClientes()) ?></p>
    <p>Total de sites: <?= count(getAllSites()) ?></p>

</body>
</html>

Passo 3: Acessar via Nginx

O Nginx já faz rewrite automático — você não precisa digitar .php:

• /admin/relatorios → /admin/relatorios.php

Fonte: /etc/nginx/sites-available/starhosting (linhas 47-49)

27. Como Criar uma API Nova

Passo 1: Criar arquivo PHP que retorna JSON

<?php
// /var/www/gerenciador/php/admin/api/meu_endpoint.php
require_once __DIR__ . '/../../../config.php';
require_once __DIR__ . '/../../../db.php';
require_once __DIR__ . '/../../../auth.php';

// Verificar autenticação
if (!isLoggedIn() || $_SESSION['user_nivel'] !== 'admin') {
    http_response_code(403);
    echo json_encode(['ok' => false, 'msg' => 'Não autorizado']);
    exit;
}

header('Content-Type: application/json');

$action = $_GET['action'] ?? '';

switch ($action) {
    case 'minha_acao':
        // Lógica aqui
        echo json_encode(['ok' => true, 'dados' => '...']);
        break;
    
    default:
        echo json_encode(['ok' => false, 'msg' => 'Ação inválida']);
}
?>

Passo 2: Chamar via JavaScript

fetch('/admin/api/meu_endpoint.php?action=minha_acao')
    .then(r => r.json())
    .then(data => {
        if (data.ok) {
            console.log('Sucesso:', data.dados);
        } else {
            console.error('Erro:', data.msg);
        }
    });

Exemplo completo: API de estatísticas

<?php
// /var/www/gerenciador/php/admin/api/stats.php
require_once __DIR__ . '/../../../config.php';
require_once __DIR__ . '/../../../db.php';
require_once __DIR__ . '/../../../auth.php';

if (!isLoggedIn() || $_SESSION['user_nivel'] !== 'admin') {
    http_response_code(403);
    echo json_encode(['ok' => false, 'msg' => 'Não autorizado']);
    exit;
}

header('Content-Type: application/json');

$db = getDB();

// Contar usuários
$total_users = $db->query("SELECT COUNT(*) FROM usuarios")->fetchColumn();

// Contar sites
$total_sites = $db->query("SELECT COUNT(*) FROM sites")->fetchColumn();

// Contar por tier
$sites_by_tier = $db->query(
    "SELECT tier, COUNT(*) as count FROM sites GROUP BY tier"
)->fetchAll(PDO::FETCH_KEY_PAIR);

echo json_encode([
    'ok' => true,
    'stats' => [
        'total_users' => $total_users,
        'total_sites' => $total_sites,
        'sites_by_tier' => $sites_by_tier
    ]
]);
?>

28. Como Rodar os Testes

Pré-requisitos

• Node.js v24+ (instalado via NVM)
• Arquivo /var/www/gerenciador/tests/.env com credenciais

Executar todos os testes

# Opção 1: via run_tests.sh (recomendado)
bash /var/www/run_tests.sh

# Opção 2: via pasta tests
cd /var/www/gerenciador/tests
bash run_all.sh

Estrutura dos testes

/var/www/gerenciador/tests/
├── run_all.sh                    # Executa tudo
├── .env                          # Credenciais (protegido por .gitignore)
├── helpers/
│   └── auth.sh                   # Função get_session_cookie()
├── api/
│   ├── endpoints_test.sh         # 7 testes de endpoints gerais
│   ├── tools_noauth_test.sh      # 3 testes sem autenticação
│   └── tools_auth_test.sh        # 8 testes com autenticação
├── MANUAL_TESTS.md               # 10 testes manuais
├── RELATORIO_VALIDACAO.md        # Relatório formal
├── RELATORIO_VALIDACAO_HONESTO.md # Relatório honesto (com problemas conhecidos)
└── AUDITORIA_PROTOCOLO_VERDADE.md # Auditoria do protocolo

Testes disponíveis

Fonte: CHANGELOG.md (linhas 186-200), tests/MANUAL_TESTS.md

29. Boas Práticas e Convenções

Convenções de nomenclatura

O que NÃO fazer

• ❌ Nunca usar sed para editar código — pode quebrar formatação e caracteres especiais
• ❌ Nunca expor o arquivo .env — contém senhas e chaves de API
• ❌ Nunca inventar dados — sempre usar fatos verificáveis
• ❌ Nunca usar sudo desnecessariamente — minimiza riscos de segurança
• ❌ Nunca commitar segredos no Git — ficam visíveis para quem clonar o repositório
• ❌ Nunca modificar arquivos fora do escopo declarado — pode quebrar funcionalidade

Protocolo da Verdade (resumo)

• Toda afirmação deve ter fonte verificável (arquivo, linha, comando)
• Se não souber, dizer "Dados insuficientes" — nunca inventar
• Nunca inventar, especular ou assumir
• Mostrar raciocínio passo a passo
• Aceitar feedback negativo como verdade

Fonte: PROTOCOLO_VERDADE.md (249 linhas)

30. Arquivos Importantes

31. Comandos Úteis

Serviços

# Status dos serviços (ver se está rodando)
sudo systemctl status nginx
sudo systemctl status php8.3-fpm
sudo systemctl status ollama
sudo systemctl status ai-api

# Reiniciar serviços (quando algo trava)
sudo systemctl restart nginx
sudo systemctl restart php8.3-fpm
sudo systemctl restart ollama
sudo systemctl restart ai-api

Nginx

# Testar configuração (antes de reiniciar!)
sudo nginx -t
# Deve mostrar: syntax is ok, test is successful

# Reiniciar (depois de testar)
sudo systemctl restart nginx

# Ver config do painel
cat /etc/nginx/sites-available/starhosting

# Ver config de um site específico
cat /etc/nginx/sites-available/site_xyz

SQLite

# Abrir banco de dados
sqlite3 /var/www/gerenciador/database.db

# Comandos úteis no SQLite
.tables                          # Listar tabelas
.schema usuarios                 # Ver estrutura da tabela
SELECT COUNT(*) FROM sites;      # Contar sites
SELECT * FROM usuarios;          # Ver todos os usuários
.quit                            # Sair

Ollama

# Listar modelos instalados
ollama list

# Ver modelos carregados (na memória)
ollama ps

# Puxar modelo (download)
ollama pull qwen2.5vl:3b

# Testar modelo (conversa)
ollama run qwen2.5vl:3b "Olá, tudo bem?"

Logs

# Logs do Nginx (erros e acessos)
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

# Logs do PHP
sudo tail -f /var/log/php8.3-fpm.log

# Logs do sistema
journalctl -u nginx -f
journalctl -u ollama -f
journalctl -u ai-api -f

Discos

# Uso de disco (quanto espaço sobrou)
df -h

# Tamanho das pastas (onde está ocupando espaço)
du -sh /var/www/sites/*
du -sh /var/www/gerenciador/*

Git

# Ver status das alterações
git status

# Ver últimas 10 alterações
git log --oneline -10

# Criar branch nova
git checkout -b nova-funcionalidade

# Voltar alteração (cuidado!)
git checkout -- arquivo.php

32. Pendências e Próximos Passos

Fonte: CHANGELOG.md (linhas 210-240)

33. API Pública (Planejada)

Por que não expor as APIs internas?

Arquitetura

Decisões de Arquitetura

Tabela api_clients

CREATE TABLE api_clients (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    client_id TEXT UNIQUE NOT NULL,        -- identificador público
    secret_hash TEXT NOT NULL,             -- bcrypt do secret (nunca o secret cru)
    nome TEXT NOT NULL,                    -- nome do cliente/app
    plan TEXT DEFAULT 'basic',             -- basic/premium/business
    scopes TEXT DEFAULT '["read"]',        -- JSON: ["read","write","analyze"]
    rate_limit INTEGER DEFAULT 100,        -- req/dia
    ativo INTEGER DEFAULT 1,               -- 0=desativado, 1=ativo
    ultimo_acesso DATETIME,
    criado_em DATETIME DEFAULT CURRENT_TIMESTAMP
);

Dependências a instalar

# 1. Extensão PHP para Redis
sudo apt install php-redis -y
sudo systemctl restart php8.3-fpm

# 2. Biblioteca JWT via Composer
cd /var/www/gerenciador/php
composer require firebase/php-jwt

Custo: ~2MB de disco, 0 serviços novos (Redis já roda)

Endpoints planejados

Segurança (padrão de mercado)

• HTTPS obrigatório — já temos via Cloudflare
• Rate limit headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• HTTP 429 — com header Retry-After quando excede
• JWT expira em 15 min — refresh token para sessões longas
• Secret nunca mais mostrado — após criação, só hash no banco
• Log de auditoria — toda chamada registrada
• CORS configurado — only origins permitidos

Exemplos de Uso

1. Autenticar — obter JWT

# Passo 1: Gerar token (client_id + secret)
curl -X POST https://starhosting.com.br/api/public/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "meu_app_001",
    "secret": "a1b2c3d4e5f6..."
  }'

# Resposta:
{
  "ok": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900,
  "plan": "basic",
  "scopes": ["read"]
}

2. Consultar status do sistema

# Passo 2: Usar o JWT para acessar endpoints
curl https://starhosting.com.br/api/public/v1/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Resposta:
{
  "ok": true,
  "status": {
    "nginx": "active",
    "php": "active",
    "disk_percent": 11,
    "ram_used": "7.1Gi",
    "sites": 3
  }
}

3. Listar sites do cliente

curl https://starhosting.com.br/api/public/v1/sites \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Resposta:
{
  "ok": true,
  "sites": [
    {
      "id": 1,
      "dominio": "minhalojja.com.br",
      "tier": "basic",
      "status": "ativo",
      "ssl_ativo": true
    }
  ],
  "total": 1,
  "limite": 1
}

4. Enviar imagem para análise (IA)

# Enviar imagem em base64 para análise
curl -X POST https://starhosting.com.br/api/public/v1/ai/analise \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "imagem_base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "id_camera": "cam01"
  }'

# Resposta:
{
  "ok": true,
  "resultado": {
    "total_objetos": 5,
    "objetos": [...]
  },
  "tempo_execucao": 2.5
}

5. Chat com IA

curl -X POST https://starhosting.com.br/api/public/v1/ai/chat \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "mensagem": "Olá, qual é o status do meu site?",
    "id_sessao": "sessao_abc123"
  }'

# Resposta:
{
  "ok": true,
  "resposta": "Seu site minhaloja.com.br está ativo e funcionando normalmente.",
  "id_sessao": "sessao_abc123"
}

6. Quando o rate limit excede

# Se o cliente fizer muitas requisições, recebe 429:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717430400
Retry-After: 3600

{
  "ok": false,
  "error": "rate_limit_exceeded",
  "message": "Limite diário atencido. Tente novamente amanhã.",
  "retry_after": 3600
}

7. Exemplo em JavaScript (fetch)

// Autenticar
const authRes = await fetch('/api/public/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'meu_app_001',
    secret: 'a1b2c3d4e5f6...'
  })
});
const { token } = await authRes.json();

// Usar o token
const sitesRes = await fetch('/api/public/v1/sites', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const sites = await sitesRes.json();
console.log(sites);

8. Exemplo em PHP (cURL)

<?php
// Autenticar
$ch = curl_init('https://starhosting.com.br/api/public/v1/auth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'client_id' => 'meu_app_001',
        'secret' => 'a1b2c3d4e5f6...'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);
$data = json_decode(curl_exec($ch), true);
$token = $data['token'];

// Usar o token
$ch = curl_init('https://starhosting.com.br/api/public/v1/sites');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
    CURLOPT_RETURNTRANSFER => true
]);
$sites = json_decode(curl_exec($ch), true);
print_r($sites);
?>

Arquivos a criar

34. Chat API Interna (Implementada)

O que a Chat API faz

Arquitetura

Autenticação

A API usa autenticação por API Key dinâmica. A chave é gerada a cada minuto:

// Como gerar a chave:
$timestamp = time();        // ex: 1780492821
$dia = (int)date('d');       // ex: 3
$valor = $timestamp * $dia;  // ex: 5341478463
$key = base64_encode($valor); // ex: "NTM0MTQ3ODQ2Mw=="

// Validar:
// 1. Decodifica base64 → obtém valor
// 2. Divide por dia → obtém timestamp
// 3. Verifica se timestamp está dentro de 24h

Endpoints

Exemplos de Uso (curl)

1. Gerar API Key válida

# Gerar chave via PHP
php -r '
$timestamp = time();
$dia = (int)date("d");
$valor = $timestamp * $dia;
echo base64_encode((string)$valor);
'
# Saída: NTM0MTQ3ODQ2Mw==

2. Criar sessão e enviar primeira mensagem

curl -X POST https://api.starhosting.com.br/send.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{
    "mensagem": "Olá, qual o prazo de entrega?",
    "user_id": "cliente_123",
    "loja_id": "lojaX",
    "contexto_loja": "Loja de roupas. Produtos: camisetas, calças."
  }'

# Resposta:
{
  "ok": true,
  "resposta": "Olá! O prazo de entrega é de 3 a 5 dias úteis.",
  "session_id": "lojaX_cliente_123",
  "tokens_usados": 45
}

3. Enviar segunda mensagem (mantém contexto)

curl -X POST https://api.starhosting.com.br/send.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{
    "mensagem": "E tem frete grátis?",
    "user_id": "cliente_123",
    "loja_id": "lojaX"
  }'

# IA lembra que falou de entrega → responde sobre frete

4. Atualizar contexto (mantém histórico)

curl -X POST https://api.starhosting.com.br/contexto.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{
    "session_id": "lojaX_cliente_123",
    "contexto_loja": "Loja de roupas. PROMOÇÃO: frete grátis acima de R$99.",
    "force_new_session": false
  }'

# Resposta:
{
  "ok": true,
  "compactado": false,
  "msg": "Contexto atualizado, histórico mantido"
}

5. Forçar nova sessão (zerar histórico)

curl -X POST https://api.starhosting.com.br/contexto.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{
    "session_id": "lojaX_cliente_123",
    "contexto_loja": "Loja de eletrônicos agora.",
    "force_new_session": true
  }'

# Resposta:
{
  "ok": true,
  "compactado": true,
  "historico_zerado": true,
  "msg": "Contexto atualizado e histórico zerado"
}

6. Usuário confuso → histórico expandido

curl -X POST https://api.starhosting.com.br/send.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{
    "mensagem": "Como assim? Não entendi",
    "user_id": "cliente_123",
    "loja_id": "lojaX"
  }'

# Bot detecta "como assim" + "não entendi" → usa 100 msgs em vez de 30

7. Forçar compactação manual

curl -X POST https://api.starhosting.com.br/compact.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw==" \
  -d '{"session_id": "lojaX_cliente_123"}'

# Resposta:
{
  "ok": true,
  "compactado": true,
  "mensagens_removidas": 25,
  "resumo": "Cliente perguntou sobre prazo de entrega e frete grátis para São Paulo."
}

8. Ver histórico completo

curl "https://api.starhosting.com.br/history.php?session_id=lojaX_cliente_123" \
  -H "X-API-Key: NTM0MTQ3ODQ2Mw=="

# Resposta:
{
  "ok": true,
  "session_id": "lojaX_cliente_123",
  "loja_id": "lojaX",
  "contexto_loja": "Loja de roupas...",
  "total_mensagens": 8,
  "historico": [...]
}

Compactação

Sinais de Confusão

Quando a mensagem contém algum destes termos, o bot usa 100 mensagens em vez de 30:

• "não entendi", "como assim", "pode repetir"
• "o que?", "pode explicar", "confuso"
• "como?", "que?", "de novo"

Arquivos

Fonte: /var/www/gerenciador/php/api/chat/ (640 linhas totais)

Apêndice A. Credenciais e Configurações

Apêndice B. Protocolo da Verdade (v2.5)

O Protocolo da Verdade é um conjunto de regras que governa como o sistema (e suas IAs) devem processar informações. Versão: v2.5.

Princípios Fundamentais

1. Ancoragem Factual Absoluta — Toda afirmação deve ser baseada em fontes verificáveis. Proibido inventar, especular ou assumir.
2. Transparência de Evidências — Toda alegação técnica deve ter sua fonte oficial. Citações mortas ou alucinadas são violação crítica.
3. Anti-Arrogância — Eliminar vieses pessoais e sycophancy (concordância injustificada). Correto factual > soar útil.
4. Anti-Dados Mock — Proibido usar dados fictícios, returns hardcoded, ou placeholders em funções complexas.

Correção de Erros do Usuário

1. Anti-Gaslighting Algorítmico — NUNCA assumir que o sistema está correto e que o usuário ou seu software está errado.
2. Blacklist Anti-Looping — Se uma abordagem falhar 2 vezes, registrar na "Blacklist Registry" e NUNCA mais tentar.
3. Blacklist Comportamental (v2.5) — Aplica-se a padrões comportamentais: Helpfulness Bias, Scope Creep, Premature Action.

Gatekeeper de Compactação de Contexto

• NUNCA invocar /compact no meio de um processo lógico complexo.
• Compactar APENAS no final de um ciclo completo.

Escopo e Disciplina de Edição (v2.5)

1. Declaração Obrigatória de Escopo — ANTES de qualquer edição, declarar: Escopo, Exclusões, Intenção.
2. Execução de Limite de Edição — NUNCA modificar arquivo fora do escopo declarado.
3. Auto-Verificação Periódica — A cada 3-4 execuções de ferramentas, pausar e verificar: "Estou dentro do escopo?"

Apêndice C. Glossário

Apêndice D. Histórico deste Documento

StarHosting — Documentação Completa v1.2
Última atualização: 03/06/2026
starhosting.com.br