Rotas, permissões e WebSocket para plugins nativos

Crie uma página de status que lê e altera um registro da empresa autenticada. Ao confirmar uma mudança, o backend avisa as páginas abertas pelo WebSocket do Titan Continuum. Cada página consulta novamente a API com sua própria sessão e seu próprio escopo.

Pré-requisitos

  • Instalação de homologação do Titan Continuum com PHP 8.2 ou superior, MySQL com InnoDB e Workerman atendendo o WebSocket do host.
  • Acesso de mantenedor para incluir código nativo revisado na distribuição. A instalação consiste em publicar a pasta do projeto em titansource/plugins/native/status pelo processo normal da equipe.
  • Um administrador de homologação e duas contas comuns de teste, com IDs conhecidos e sem dados de produção.
  • Noções de PHP, PDO e JavaScript. Para preparar o ambiente do SDK, use o guia de desenvolvimento e a referência da CLI.

O tutorial usa o manifesto de um plugin nativo. Nele, permissions é um mapa de grupos e chaves. O manifesto FEX usa uma lista de chaves em permissions. Aprovar e selecionar um FEX no Plugin Manager registra a versão selecionada no catálogo. Páginas, menus e tópicos deste tutorial são registrados pelo carregador de módulos nativos.

1. Declare rotas, menu e tópicos

Crie titansource/plugins/native/status e organize os arquivos conforme a árvore abaixo.

status/
├── manifest.json
├── index.php
├── api.php
├── service.php
└── assets/
    └── status.js

Salve o manifesto completo do tutorial em manifest.json.

{
  "id": "empresa.status",
  "name": "Status da operação",
  "version": "1.0.0",
  "apiVersion": 1,
  "runtime": "php",
  "entrypoint": "service.php",
  "dependencies": [],
  "permissions": {
    "Status": {
      "plugin_status.acessar": "Consultar e atualizar o status da operação"
    }
  },
  "routes": {
    "ext-status/index": "ext-status-atualizacoes",
    "ext-status/api": "ext-status-atualizacoes"
  },
  "topics": {
    "ext-status-atualizacoes": "plugin_status.acessar"
  },
  "controllers": {
    "ext-status/index": "index.php",
    "ext-status/api": "api.php"
  },
  "navigation": [
    {
      "path": "ext-status/index",
      "label": "Status da operação",
      "icon": "chart-line",
      "requires": ["plugin_status.acessar"],
      "badge": ""
    }
  ],
  "schemas": {"empresa_status": 1},
  "assets": ["status.js"]
}

O diretório status determina a primeira parte da rota, o prefixo da permissão e o prefixo do tópico. O ID empresa.status identifica o módulo para dependências e migrações. Use reversaUrl() no PHP para gerar links válidos também para instalações montadas em um prefixo.

2. Prepare os dados de teste por empresa

O exemplo possui uma tabela de vínculos administrados pelo plugin e uma tabela de registros. A sessão do Titan identifica o usuário. A tabela de vínculos determina a empresa desse usuário neste plugin. Seu ambiente pode oferecer um serviço autorizador próprio para o vínculo. Resolva o escopo no servidor em todas as consultas.

Defina a migração e as funções de acesso aos dados em service.php.

<?php
declare(strict_types=1);

use Titan\Architect\Core\NativeMigrations;

function statusInstalar(PDO $pdo): void
{
    require_once dirname(__DIR__, 3).'/nucleo/core/NativeMigrations.php';
    NativeMigrations::apply($pdo, 'empresa.status', 'empresa_status', static function () use ($pdo): void {
        $pdo->exec('CREATE TABLE IF NOT EXISTS empresa_status_vinculos (
            user_id BIGINT UNSIGNED PRIMARY KEY,
            empresa_id BIGINT UNSIGNED NOT NULL
        ) ENGINE=InnoDB');
        $pdo->exec('CREATE TABLE IF NOT EXISTS empresa_status_registros (
            empresa_id BIGINT UNSIGNED NOT NULL,
            id BIGINT UNSIGNED NOT NULL,
            situacao VARCHAR(20) NOT NULL,
            versao INT UNSIGNED NOT NULL DEFAULT 1,
            PRIMARY KEY (empresa_id, id)
        ) ENGINE=InnoDB');
    });
}

function statusEmpresa(PDO $pdo, int $usuario): int
{
    $consulta = $pdo->prepare('SELECT empresa_id FROM empresa_status_vinculos WHERE user_id=?');
    $consulta->execute([$usuario]);
    return (int)$consulta->fetchColumn();
}

function statusRegistro(PDO $pdo, int $empresa, int $id): ?array
{
    $consulta = $pdo->prepare('SELECT id, situacao, versao FROM empresa_status_registros
        WHERE empresa_id=? AND id=?');
    $consulta->execute([$empresa, $id]);
    $registro = $consulta->fetch(PDO::FETCH_ASSOC);
    if (!$registro) {
        return null;
    }
    return ['id' => (int)$registro['id'], 'situacao' => $registro['situacao'], 'versao' => (int)$registro['versao']];
}

function statusResponder(int $codigo, array $dados): never
{
    http_response_code($codigo);
    echo json_encode($dados, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    exit;
}

Após incluir o plugin na distribuição de homologação, execute statusInstalar($pdo) com a conexão da instalação. Aplique a migração pelo procedimento administrativo do ambiente, fora de transações de negócio. Para usar as instruções SQL em um banco descartável, troque 101 e 202 pelos IDs das duas contas de teste.

INSERT INTO empresa_status_vinculos (user_id, empresa_id) VALUES (101, 10), (202, 20);
INSERT INTO empresa_status_registros (empresa_id, id, situacao)
    VALUES (10, 1, 'normal'), (20, 1, 'atencao'), (20, 2, 'normal');

O uso do mesmo id em empresas distintas permite verificar que a consulta depende da combinação (empresa_id, id).

3. Proteja o controlador da página e a API

Salve este index.php. O cabeçalho da aplicação carrega o cliente WebSocket e aplica o menu da sessão.

<?php
declare(strict_types=1);

$raiz = dirname(__DIR__, 3);
require_once $raiz.'/config/database.php';
verificarAutenticacao();
reversaExigirPermissao('plugin_status.acessar');

$esc = static fn (string $valor): string => htmlspecialchars($valor, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$tituloPagina = 'Status da operação';
require $raiz.'/includes/header.php';
?>
<section aria-labelledby="status-titulo" data-status-app
         data-api="<?= $esc(reversaUrl('ext-status/api')) ?>"
         data-csrf="<?= $esc(reversaCsrfToken()) ?>">
    <h1 id="status-titulo">Status da operação</h1>
    <p data-situacao aria-live="polite">Carregando status.</p>
    <form data-status-form>
        <label for="status-situacao">Nova situação</label>
        <select id="status-situacao" name="situacao">
            <option value="normal">Normal</option>
            <option value="atencao">Atenção</option>
        </select>
        <button type="submit" disabled>Salvar</button>
    </form>
    <p data-status-mensagem role="status"></p>
</section>
<script src="<?= $esc(reversaUrl('plugin-assets/status/status.js')) ?>" defer></script>
<?php
require $raiz.'/includes/footer.php';
echo '</div></body></html>';

Salve este api.php. O GET lê o registro. O POST revalida o método, a sessão, a permissão, o CSRF, o vínculo e o registro da empresa. A versão esperada impede que a gravação sobrescreva silenciosamente uma mudança concorrente.

<?php
declare(strict_types=1);

$raiz = dirname(__DIR__, 3);
require_once $raiz.'/includes/resposta.php';
require_once __DIR__.'/service.php';
reversaCabecalho('Content-Type: application/json; charset=utf-8');
reversaCabecalho('Cache-Control: no-store, private');

if (!defined('REVERSA_WEBSOCKET_EXECUCAO') || REVERSA_WEBSOCKET_EXECUCAO !== true) {
    statusResponder(405, ['ok' => false, 'erro' => 'Use o WebSocket do Titan.']);
}

require_once $raiz.'/config/database.php';
verificarAutenticacao();
reversaExigirPermissao('plugin_status.acessar');

$metodo = $_SERVER['REQUEST_METHOD'] ?? '';
if (!in_array($metodo, ['GET', 'POST'], true)) {
    statusResponder(405, ['ok' => false, 'erro' => 'Método não permitido.']);
}
if ($metodo === 'POST') {
    reversaCsrfExigir();
}

$empresa = statusEmpresa($pdo, (int)$_SESSION['usuario_id']);
if ($empresa < 1) {
    statusResponder(403, ['ok' => false, 'erro' => 'Sua conta não tem empresa vinculada neste plugin.']);
}
$entrada = $metodo === 'POST' ? $_POST : $_GET;
$id = filter_var($entrada['id'] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if ($id === false) {
    statusResponder(422, ['ok' => false, 'erro' => 'Informe um ID válido.']);
}
if ($metodo === 'GET') {
    $registro = statusRegistro($pdo, $empresa, $id);
    if ($registro === null) {
        statusResponder(404, ['ok' => false, 'erro' => 'Registro não encontrado.']);
    }
    statusResponder(200, ['ok' => true, 'registro' => $registro]);
}

$situacao = $_POST['situacao'] ?? null;
$versao = filter_var($_POST['versao'] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
if (!in_array($situacao, ['normal', 'atencao'], true) || $versao === false) {
    statusResponder(422, ['ok' => false, 'erro' => 'Situação ou versão inválida.']);
}

try {
    $pdo->beginTransaction();
    $atualizar = $pdo->prepare('UPDATE empresa_status_registros SET situacao=?, versao=versao+1
        WHERE empresa_id=? AND id=? AND versao=?');
    $atualizar->execute([$situacao, $empresa, $id, $versao]);
    if ($atualizar->rowCount() !== 1) {
        $pdo->rollBack();
        if (statusRegistro($pdo, $empresa, $id) === null) {
            statusResponder(404, ['ok' => false, 'erro' => 'Registro não encontrado.']);
        }
        statusResponder(409, ['ok' => false, 'erro' => 'O registro mudou. Atualize a página antes de gravar.']);
    }
    $pdo->commit();
} catch (Throwable $erro) {
    if ($pdo->inTransaction()) {
        $pdo->rollBack();
    }
    throw $erro;
}

require_once $raiz.'/includes/realtime.php';
$eventoPublicado = true;
try {
    reversaWsPublicar($pdo, 'ext-status-atualizacoes');
} catch (Throwable $erro) {
    $eventoPublicado = false;
    error_log('empresa.status: atualização confirmada, aviso WebSocket indisponível.');
}
statusResponder(200, ['ok' => true, 'evento_publicado' => $eventoPublicado]);

reversaExigirPermissao() valida a autorização da sessão em cada entrada. O escopo do objeto continua na consulta SQL. Uma página oculta no menu e um usuário com permissão concedida sem vínculo são casos distintos. Neste tutorial, a mesma chave concede consulta e edição. Em um plugin com perfis diferentes, declare e exija chaves específicas nas ações de escrita.

O aviso sai depois do commit. Uma falha de publicação posterior produz evento_publicado: false, com a operação já confirmada. Para eventos com garantia de entrega e reprocessamento, use a fila transacional descrita na arquitetura.

4. Atualize a página ao receber o aviso

Salve este assets/status.js. O fetch do Titan encaminha operações registradas do mesmo host pelo WebSocket. Use URLSearchParams ou FormData para os campos de POST. O cliente fornece observe() e devolve uma função para cancelar a observação.

(() => {
    'use strict';
    const app = document.querySelector('[data-status-app]');
    if (!app) return;

    const form = app.querySelector('[data-status-form]');
    const botao = form.querySelector('button');
    const texto = app.querySelector('[data-situacao]');
    const mensagem = app.querySelector('[data-status-mensagem]');
    const live = window.ReversaRealtime;
    const url = new URL(app.dataset.api, location.href);
    url.searchParams.set('id', '1');
    let versao = null;
    let gravando = false;
    let ultimaConsulta = 0;

    async function consultar() {
        const consulta = ++ultimaConsulta;
        try {
            const resposta = await fetch(url, {headers: {Accept: 'application/json'}});
            if (!resposta.ok) throw new Error('Consulta indisponível.');
            const {registro} = await resposta.json();
            if (consulta !== ultimaConsulta) return;
            versao = registro.versao;
            texto.textContent = registro.situacao === 'normal' ? 'Normal' : 'Atenção';
        } catch {
            if (consulta !== ultimaConsulta) return;
            versao = null;
            texto.textContent = 'Status indisponível.';
        } finally {
            botao.disabled = gravando || versao === null;
        }
    }

    if (!live?.supports(url)) {
        texto.textContent = 'Rota indisponível. Confira a instalação e recarregue a página.';
        return;
    }
    const parar = live.observe('ext-status-atualizacoes', consultar);
    window.addEventListener('pagehide', (evento) => { if (!evento.persisted) parar(); });

    form.addEventListener('submit', async (evento) => {
        evento.preventDefault();
        if (gravando || versao === null) return;
        gravando = true;
        botao.disabled = true;
        mensagem.textContent = '';
        try {
            const corpo = new URLSearchParams(new FormData(form));
            corpo.set('id', '1');
            corpo.set('versao', String(versao));
            const resposta = await fetch(url, {
                method: 'POST',
                headers: {Accept: 'application/json', 'X-CSRF-Token': app.dataset.csrf},
                body: corpo,
            });
            const dados = await resposta.json();
            if (!resposta.ok) {
                mensagem.textContent = dados.erro ?? 'Gravação recusada.';
            } else {
                mensagem.textContent = dados.evento_publicado
                    ? 'Atualização salva.' : 'Atualização salva. Aviso às outras páginas indisponível.';
            }
        } catch {
            mensagem.textContent = 'Confira a situação atual antes de tentar salvar novamente.';
        } finally {
            await consultar();
            gravando = false;
            botao.disabled = versao === null;
        }
    });
})();

observe() recebe o nome de um tópico ou uma lista. O callback é agendado quando a conexão fica pronta, quando ela retorna e quando o tópico muda. Ele também pode rodar ao voltar para uma aba visível. Use {initial: false} quando já fizer a primeira leitura por outro caminho. O callback recebe um aviso de mudança sem os dados do registro, pode agrupar mudanças próximas e deve sempre ler o estado atual pela API. As sessões autorizadas no tópico podem observar o momento do aviso. Preserve informações da empresa e identificadores de objetos no endpoint com escopo.

Fluxo de uma alteração

Navegador A autenticado
  → POST ext-status/api pelo WebSocket, com CSRF e versão esperada
  → controlador valida permissão, empresa e registro
  → transação confirma a alteração
  → reversaWsPublicar grava o tópico autorizado
  → Workerman notifica sessões com a permissão do tópico
  → observe agenda nova leitura no navegador B
  → GET ext-status/api reaplica autorização e escopo do navegador B

Referência do manifesto e do transporte

Campo ou API Contrato do exemplo
id ID namespaced empresa.status. A instalação usa o diretório status. O prefixo titan. é reservado aos módulos distribuídos pelo Titan.
routes Mapa de caminho lógico sem barra inicial ou .php para tópico. Extensões nativas adotam ext-<diretório>/<rota> e declaram cada controlador.
controllers Mapa da mesma chave de rota para um arquivo PHP na raiz do plugin.
permissions Mapa de grupo para chave e rótulo. Para status, a chave começa com plugin_status.. Para um diretório com hífen, o prefixo de permissão usa _ no lugar do hífen.
topics Mapa de canal para uma permissão declarada pelo próprio plugin. Use ext-<diretório>-<sinal> com até 32 bytes ASCII. O diretório pode incluir hífens. O sinal segue [a-z][a-z0-9]*.
navigation path aponta para a rota e requires lista as permissões exigidas no menu. label, icon e badge completam a entrada.
assets Caminhos públicos relativos a assets/. A URL usa /plugin-assets/<diretório>/<arquivo>. Mantenha constantes privadas, dados de empresas e código PHP fora dessa lista.
reversaWsPublicar($pdo, $topico) Registra um aviso do tópico ativo. Canal personalizado ausente ou bloqueado é recusado. O código responsável publica explicitamente depois do commit.
window.ReversaRealtime.observe(topic, callback, options) Agenda leituras após avisos e no ciclo de conexão. Retorna função de cancelamento.
window.ReversaRealtime.supports(url) Confere se a operação está registrada para o transporte no navegador. A validação de acesso ocorre no servidor.

Homologue com e sem permissão

  1. Publique a pasta de teste com o procedimento normal da instalação e confirme empresa.status no catálogo nativo. Aplique a migração e os dados de teste. Confirme que o WebSocket está conectado no navegador.
  2. Em Administração, confira o grupo Status. Conceda plugin_status.acessar à primeira conta comum. Entre com ela em dois navegadores ou janelas isoladas e abra Status da operação.
  3. Grave uma alteração na primeira janela. A segunda deve consultar a API de novo. Confira o quadro changed do WebSocket e as consultas no painel de rede. O quadro deve conter o nome do tópico. Busque o estado de cada empresa pela API.
  4. Use a segunda conta comum sem concessão. O menu deve sumir. Acesse a rota da página diretamente e chame a API por fetch de uma página autenticada da mesma instalação. Confira HTTP 403 e ausência da notificação do tópico nessa sessão. A API deve negar antes de consultar ou alterar os dados do plugin.
  5. Conceda a permissão à segunda conta e abra uma sessão nova. Para id=1, confirme que cada conta vê o próprio registro. Para id=2, a primeira deve receber 404. Verifique no banco de homologação que a escrita nunca altera um registro da outra empresa.
  6. Com uma conta autorizada, envie um POST de homologação sem CSRF ou com token inválido. Confira a recusa e ausência da gravação. Em duas sessões autorizadas da mesma empresa, envie uma versão desatualizada e confirme HTTP 409.
  7. Interrompa e restabeleça a conexão em uma janela de teste. A interface deve buscar o estado atual. Suspenda o módulo na próxima distribuição de homologação e confirme que autenticação, Home, Perfil e Plugin Manager continuam acessíveis. As rotas e o tópico de Status devem sair do catálogo ativo.

Resultados esperados e diagnóstico

Resposta ou sintoma Verificação
401 na API Verifique a sessão da conexão WebSocket. Entre novamente ou recarregue após a troca de conta.
403 com sessão ativa Confirme a permissão do plugin, o vínculo de empresa e o CSRF no POST.
404 da página ou do recurso público Confirme a pasta, o manifesto, o mapa de controladores, o catálogo ativo e o caminho relativo do arquivo.
404 da API para um registro Confira o ID e o vínculo da conta. Objetos de outra empresa seguem a mesma resposta de um objeto ausente.
405 em acesso HTTP direto à API Faça a consulta a partir de uma página autenticada com o cliente WebSocket inicializado.
409 Leia o registro novamente. O usuário pode conferir a versão atual antes de decidir pela gravação.
422 Confira o formato dos campos. O exemplo aceita normal ou atencao e inteiros positivos para ID e versão.
Rota indisponível no cliente Confira supports(url) e o manifesto ativo. O WebSocket recusa requisições que indiquem uma operação fora do catálogo.
A tela grava, mas outra janela fica antiga Verifique evento_publicado, a conexão, a chave de permissão do tópico e as consultas disparadas por observe. As abas ocultas voltam a consultar ao ficarem visíveis.
Conexão perdeu a resposta durante o POST Releia o estado antes de repetir. A transação pode ter sido confirmada.