ProtoCord - Interface Web

Interface web do ProtoCord, destinada ao apoio operacional de analistas de suporte na criação de protocolos, consulta de histórico, verificação de liberações, transcrição de áudios de atendimento e uso de assistente com inteligência artificial.

1. Finalidade

O projeto entrega uma aplicação estática, executada no navegador, que consome a API do projeto modelo-discord-server. A interface não armazena informações sensíveis nem acessa serviços externos diretamente. Todo acesso a banco de dados, provedores de inteligência artificial, arquivos temporários e sistemas integrados ocorre por meio do servidor.

2. Funcionalidades

• Registro de protocolos com PRT, ticket, módulo, descrição, paliativo e ligação de referência.
• Consulta, filtragem, ordenação e paginação do histórico de protocolos.
• Painéis de acompanhamento de liberações e indicadores operacionais.
• Transcrição e tratamento de áudios de atendimento.
• Assistente com inteligência artificial, integrado ao servidor, para respostas baseadas em contexto real.
• Comparador de textos em html/comparador-textos.html.
• Autenticação por senha validada no servidor com sessão assinada retornada pela API.
• Configuração da URL da API em tempo de execução, sem necessidade de recompilar o projeto.

3. Tecnologias Utilizadas

• HTML, CSS e JavaScript.
• Tailwind CSS carregado por CDN.
• Chart.js, ApexCharts, SheetJS, Lucide, Animate.css e bibliotecas auxiliares carregadas conforme necessidade.
• Testes automatizados com node:test.

4. Estrutura De Pastas

modelo-discord/
├─ index.html                  # Página principal da aplicação
├─ style.css                   # Estilos globais
├─ html/
│  └─ comparador-textos.html   # Ferramenta auxiliar de comparação textual
├─ js/
│  ├─ runtime-config.js        # Configuração central da API
│  ├─ auth.js                  # Autenticação, sessão e encerramento de sessão
│  ├─ mecanica.js              # Fluxo principal de protocolos
│  ├─ ia-transcriber.js        # Gravação, envio e transcrição de áudio
│  ├─ ia-assistant*.js         # Assistente com inteligência artificial
│  ├─ kpi-modern.js            # Indicadores e percepções operacionais
│  ├─ dashboard-liberacoes.js  # Painel de liberações por versão e módulo
│  └─ ...
└─ tests/                      # Testes automatizados

5. Pré-Requisitos

• Node.js 20 ou superior para execução dos testes.
• Servidor estático local, como npx serve, Live Server ou python -m http.server.
• Servidor do ProtoCord publicado ou executando localmente.

6. Instalação

npm install

7. Configuração Da API

O arquivo js/runtime-config.js concentra a resolução da URL da API. O valor padrão é:

https://modelo-discord-server.vercel.app/api

Para usar outro servidor, injete a configuração antes dos demais scripts:

<script>
  window.PROTOCORD_RUNTIME_CONFIG = {
    API_BASE_URL: "http://localhost:3000/api"
  };
</script>

Também é possível configurar pelo console do navegador:

localStorage.setItem("PROTOCORD_API_BASE_URL", "http://localhost:3000/api");
location.reload();

8. Execução

Com serve:

npx serve . -l 5500

Acesse:

http://localhost:5500

Com Python:

python -m http.server 5500

9. Testes

npm test

Os testes validam configuração em tempo de execução, autenticação, fluxo de transcrição, interface de processamento e componentes de indicadores.

10. Rotas Consumidas

Uso	Rota
Saúde do servidor	GET /api/health
Autenticação	POST /api/autenticacao
Protocolos	GET/POST/DELETE /api/protocolos
Módulos	GET /api/modulos
Liberações	GET/POST /api/liberados
Notificações	GET /api/notificacao
Limpeza de notificações	GET /api/limpar_notificacao
Envio de áudio	POST /api/blob-upload
Transcrição estruturada	POST /api/transcrever
Transcrição direta	POST /api/transcricao-direta
Assistente	GET/POST /api/assistente

11. Variáveis De Configuração

Nome	Local	Finalidade
PROTOCORD_RUNTIME_CONFIG.API_BASE_URL	Navegador	URL base configurada antes da carga da aplicação.
PROTOCORD_API_BASE_URL	Navegador	URL base resolvida para chamadas HTTP.
PROTOCORD_API_SERVER_ORIGIN	Navegador	Origem do servidor sem o sufixo /api.
PROTOCORD_TRANSCRIBER_API	Navegador	Compatibilidade com fluxos anteriores de transcrição.

12. Observações De Manutenção

• Novos recursos devem usar window.getProtocordApiUrl("/rota").
• Chamadas para a API configurada recebem automaticamente Authorization: Bearer <sessao> por js/runtime-config.js.
• Segredos, chaves e credenciais nunca devem ser colocados no código da interface.
• Dados técnicos retornados pela API devem ser convertidos para linguagem operacional antes de serem exibidos ao usuário.
• Em alterações de servidor durante testes, limpe PROTOCORD_API_BASE_URL no localStorage, se necessário.

13. Segurança E Logs

• A senha não é mais enviada por query string; o login usa POST /api/autenticacao com corpo JSON.
• O token retornado pelo backend é mantido em localStorage por até 24 horas e anexado automaticamente nas chamadas ao backend oficial.
• O frontend não armazena chaves de Supabase, Groq, xAI, Vercel Blob ou Znuny.
• Logs de segurança ficam no backend; a interface evita registrar credenciais ou tokens no console.
• Testes cobrem o binding de autenticação e a inclusão automática do token em chamadas à API.

14. Documentação Técnica

A documentação oficial, manuais, mapa neural e relatórios ficam exclusivamente no repositório modelo-discord-server e são servidos pelo backend por rota autenticada. O frontend mantém apenas a interface de consulta: após autenticação, ele solicita os documentos via GET /api/autenticacao?doc=<chave> com token de sessão, sem publicar arquivos locais no GitHub Pages.

Não adicione diretórios docs/, PDFs, screenshots de manual ou geradores de documentação neste repositório. A fonte de verdade documental do projeto é o backend.

Plugin Interno Znuny

O ProtoCord inclui o plugin interno Transporte Znuny, carregado por js/protocord-znuny-transport-plugin.js. Ele adiciona um cog de configuracao dentro da pagina Transcrever, salva a configuracao do portal, recebe o pacote do botao Transportar e abre a tela de novo ticket com fallback de copia do relatorio em texto/HTML.

Configuracao rapida pelo mini-app ou pelo console:

localStorage.setItem("PROTOCORD_ZNUNY_BASE_URL", "https://<portal-rhede>");
localStorage.setItem("PROTOCORD_ZNUNY_TICKET_URL", "https://<portal-rhede>/znuny/index.pl?Action=AgentTicketPhone");

O plugin interno tambem grava znuny_auto_payload e conversa diretamente com a extensao propria em plugins/protocord-znuny-extension. O cog da pagina Transcrever mostra primeiro a area Extensao do navegador, com botao para baixar a release plugins/releases/protocord-znuny-extension-v1.0.0.zip, assistente de instalacao em 3 passos e configuracao dos IDs/valores dos campos. O transporte inclui as evidencias visuais no fim do relatorio HTML. Por politica dos navegadores, a instalacao silenciosa fora das lojas oficiais nao e permitida; o assistente reduz o passo a passo, mas a confirmacao do navegador continua necessaria.