EMS
Portal de Gestão RPA
v2 Nitro

1.914 chamados (RTM) e 92 incidentes (INC) na base (período de 25/08/2023 a 27/10/2026)

Navegação do WorkspaceNC
Visão Geral
Horas Extras & Adicionais
Oficial
Sustentação & Incidentes
Portal Help Desk
Backlog Jira & Sprints
Estratégico / Funcional
Monitoramento Blue Prism
Inventário & Schedules
Painel de Gestão (RH)
Café de Produção & Foco
Apresentação Executiva (Deck)
Documentação & Arquitetura
Construtor de Dashboards
Topologia & Acessos
Central de Workspaces
Base Turso Multi-Tenant

Turso libSQL / D1 (db-ws-ems)

|

Guia do Usuário

  • 1. Navegação, Busca & Ficha 360º
  • 2. Visão Geral & 23 Widgets
  • 3. Esteira Funcional, WBS & ROI
  • 4. Monitoramento Técnico (Control Room)
  • 5. Arquitetura, VMs & Schedules
  • 6. Chamados de Sustentação & SLA
  • 7. Backlog, Sprints & Horas (Jira)
  • 8. Café de Produção & Mini Kanban
  • 9. Portal Help Desk & Aprovações
  • 10. RH, Pessoas, Mesa & Sistemas
  • 11. Páginas Customizadas & Construtor
  • 12. Como Usar a Assistente Nina
  • 13. Padrão Visual de Tabelas e Alinhamentos
Acesso Geral • Guia Oficial do Portal & Base da Nina

Guia do Usuário — Funções de Cada Tela, Tabela e Indicador

Manual prático de operação do Portal Cognition. Consulte o objetivo de cada módulo, o significado de todas as colunas das tabelas, os cálculos dos indicadores executivos e como utilizar o Café de Produção, o Mini Kanban Jira e a assistente virtual Nina no dia a dia.

Público-Alvo: Todos os Usuários, Analistas, Devs e Gestores
Integração IA: Base de Conhecimento Ativa da Nina
Atalho da Assistente: Ctrl + Espaço (ou botão inferior direito)
Idiomas Suportados: Português (BR), Inglês e Espanhol

1. Navegação Geral, Pesquisa Global e Ficha 360º

Ao acessar o portal, você visualiza a seleção de Workspaces (ambientes corporativos dedicados por cliente ou departamento, como EMS ou Recursos Humanos). Após escolher um workspace, a barra lateral retrátil à esquerda exibe todos os módulos liberados para o seu perfil de acesso.

Componente da Barra Superior Para que serve Como utilizar no dia a dia
Pesquisa Global Instantânea Localiza em tempo real qualquer robô (pelo código ou nome), colaborador, área de negócio, máquina virtual (Runner) ou sistema integrado. Digite ao menos 2 caracteres (ex.: NC0187 ou o nome de uma área). Ao clicar no resultado, o portal abre a Ficha Unificada 360º cruzando execuções, chamados de sustentação, horas no Jira e infraestrutura daquele item.
Central de Alertas (Sino) Reúne notificações operacionais, tarefas pendentes do Café de Produção, prazos do Cronograma WBS, solicitações aguardando aprovação e status de sincronização de bases. Clique no ícone de sino no canto superior direito para inspecionar pendências e saltar diretamente para a tela responsável.
Atalho Café & Miniplayer de Áudio Acesso de 1 clique ao seu espaço de produtividade pessoal e controle da trilha sonora ativa. Se uma playlist estiver tocando no Café, uma pílula de controle permanece visível no cabeçalho superior permitindo pausar ou retomar o áudio de qualquer tela.
Seletor de Tema e Idioma Alterna entre Modo Escuro e Modo Claro (salvo no seu perfil) e traduz toda a interface entre Português, Inglês e Espanhol. Use o botão de Sol/Lua e o seletor de idioma no canto superior direito.

2. Visão Geral Executiva e Catálogo dos 23 Widgets Nativos

A tela de Visão Geral é o painel de comando principal do workspace. No topo, ela apresenta 5 indicadores-chave (KPIs) clicáveis que funcionam como atalhos diretos para os módulos detalhados. Logo abaixo, exibe uma grade de widgets personalizável por usuário.

2.1 Indicadores Superiores (KPIs de Topo)

  • Robôs Ativos em Produção: Quantidade de automações em operação produtiva no workspace atual.
  • Execuções (Últimos 30 dias): Volume total de sessões disparadas no Control Room no período.
  • Taxa de Sucesso Operacional (%): Proporção de execuções concluídas sem falha sistêmica (Completed / Total).
  • Capacidade de Infraestrutura (Runners/VMs): Quantidade de máquinas virtuais dedicadas e seu estado de saúde.
  • Chamados de Sustentação: Volume de incidentes (INC) e requisições (RITM) monitorados pela equipe.

2.2 Catálogo de Widgets Disponíveis ("Personalizar Painel")

Ao clicar no botão Personalizar Painel no canto superior direito da Visão Geral, você pode ativar, desativar e reordenar (arrastando) até 23 widgets nativos:

Categoria Nome do Widget O que apresenta e qual pergunta responde
Executivo & ROI Funil da Esteira Funcional, Horas Economizadas por Área, Economia Financeira Estimada, Velocímetro de Meta Anual Mostra quantas automações estão em cada etapa (Backlog até Entregue), quais áreas de negócio mais economizam horas humanas e o percentual atingido da meta anual de entregas.
Operação Blue Prism Execuções por Dia (30d), Top Robôs por Volume, Robôs com Maior Taxa de Falha, Saúde das Filas (Work Queues), Mapa de Calor Horário (24h) Responde quais horários concentram maior carga nos Runners, quais robôs exigem atenção técnica imediata e o saldo de itens processados vs. exceções nas filas.
Sustentação & SLA Evolução de Incidentes vs. Requisições, Pareto de Causas Raiz, Cumprimento de SLA & MTTR, Chamados Críticos em Aberto Detalha o tempo médio de reparo (MTTR), percentual dentro do SLA e se as falhas decorrem de mudança no sistema alvo, infraestrutura, massa de dados ou regra de negócio.
Infra, Sprints & Pessoas Ocupação de Máquinas (VMs), Distribuição de Horas no Jira, Resumo da Sprint, Sistemas Mais Integrados, Minhas Tarefas do Café Consolida a alocação de servidores, o esforço apontado pela equipe na Sprint atual, os sistemas corporativos (SAP, Web, Banco) mais acionados e suas prioridades pessoais do dia.

3. Estratégico / Funcional (Pipeline de Demandas, WBS e ROI)

O módulo Estratégico / Funcional gerencia o ciclo de vida completo dos projetos de automação, desde a entrada da ideia no Backlog até a entrada em Produção e aferição do retorno financeiro (ROI).

3.1 Sub-abas da Tela Funcional

  • Visão Geral do Portfólio: Quadro síntese do pipeline por etapa da WBS (Backlog → Mapeamento → Viabilidade → PDD → Desenvolvimento → Homologação → Operação Assistida → Entregue) e filtros por Ano, Mês e Área de Negócio.
  • Tabela de Projetos e Demandas: Lista estruturada de todas as iniciativas com busca instantânea, ordenação e edição em modal ao clicar sobre a linha.
  • Análise de ROI e Horas Economizadas: Gráficos comparativos de ganho operacional (FTEs e horas poupadas por mês/ano) por diretoria e área solicitante.
  • Configuração de Cálculo: Parâmetros de custo/hora médio, fator de complexidade e premissas utilizadas no cálculo automático de payback e saving.

3.2 Dicionário de Colunas da Tabela Funcional

Coluna da Tabela Significado Funcional
Código / ID Identificador único da automação ou projeto (ex.: NC0187, AUT-042).
Processo / Iniciativa Nome descritivo do processo de negócio automatizado.
Área de Negócio Departamento solicitante beneficiado pela automação (ex.: Fiscal, Contábil, Folha de Pagamento, Logística).
Etapa / Status WBS Estágio atual no funil de engenharia RPA.
Horas Economizadas / Mês Estimativa validada de horas humanas liberadas mensalmente após a entrada do robô em produção.
Complexidade & Responsável Grau de esforço técnico (Baixa, Média, Alta) e analista/desenvolvedor líder da entrega.

4. Monitoramento Técnico RPA (Control Room / Blue Prism)

O módulo de Monitoramento Técnico fornece visibilidade em tempo real e histórica sobre as execuções dos robôs no Control Room, filas de itens e estabilidade diária.

Sub-aba / Tabela Colunas Principais Como interpretar os dados
Visão Geral & Críticas Robô, Execuções (30d), Falhas, Taxa de Sucesso (%), Última Falha, Favorito Destaca os robôs com maior incidência de terminação inesperada (Terminated) nos últimos 30 dias. Você pode marcar robôs prioritários com estrela para fixá-los no topo.
Sessões de Hoje Horário Início/Fim, Processo (Robô), Recurso (Runner/VM), Duração, Status da Sessão Exibe a grade cronológica das execuções disparadas no dia corrente, permitindo identificar atrasos de agendamento ou sessões travadas.
Itens & Filas (Work Queues) Nome da Fila, Total de Itens, Concluídos (Completed), Exceções (Exception), Pendentes (Pending), Tempo Médio/Item Mede a vazão transacional de cada fila de trabalho do Blue Prism. Um aumento de itens em Exception indica mudança de tela no sistema alvo ou inconsistência nos dados de entrada.
Infraestrutura Técnica Servidor / Runner, Status, Robôs Alocados, Taxa de Ocupação Relaciona cada máquina virtual aos robôs que nela executam para diagnóstico rápido de gargalos de hardware ou sessão presa de Windows/RDP.

4.1 Ferramentas de Filtro e Isolamento de Robôs (Busca e Consolidação por NC)

Em operações reais, um mesmo robô ou automação costuma ser composto por múltiplos processos encadeados no Blue Prism (por exemplo: Dispatcher, Performer e Consolidation, como no NC0383). Para simplificar a análise e evitar divergências de dados:

  • Dropdown de Processos com Opção Consolidada: Ao abrir o seletor de processos, robôs com múltiplos processos aparecem agrupados no topo (ex: Robô NC0383 (3 processos)). Selecionar o robô consolidado soma e correlaciona automaticamente todos os seus processos nos cards de KPI, gráficos diários e tabela detalhada.
  • Modal de Filtro com Busca em Tempo Real: Clicando em Filtrar robôs, utilize a barra de pesquisa rápida digitando o número (ex: 383) ou nome do processo. A lista filtra instantaneamente os processos correspondentes.
  • Ação Rápida "Isolar Busca": Ao digitar o termo de pesquisa, utilize o botão Isolar busca (X) para desmarcar automaticamente todos os outros processos do catálogo e manter selecionados apenas os processos filtrados, agilizando diagnósticos pontuais.
  • Botão "Isolar NC" por Linha: Cada processo identificado com código NC apresenta o botão de atalho Isolar NC, marcando de imediato todos os processos irmãos que pertencem àquele robô.
  • Indicador de Filtro Ativo & Limpeza Rápida: Quando houver processos ocultados, o botão destaca a contagem ativa (ex: Filtrar robôs (3 de 136)) e exibe o botão × Limpar filtro para restaurar a visualização completa com um único clique.

5. Arquitetura de Servidores, Inventário e Schedules (Grade 24h)

Os módulos de Arquitetura de Servidores e Inventário & Schedules documentam a malha de máquinas virtuais (VMs) e a janela horária em que cada robô é executado.

  • Topologia de Servidores: Apresenta os ambientes de Produção, Homologação e Desenvolvimento, especificando sistema operacional, memória RAM, vCPUs, endereço/hostname e licenças instaladas.
  • Grade Horária de Schedules (24h): Tabela e linha do tempo que mostram em quais faixas do dia (00h às 23h) cada robô ocupa um Runner, evitando colisões de agendamento.
  • Motor de Sugestão de Alocação: Ao planejar a entrada de um novo robô, informa a duração e janela desejada para que o portal indique qual máquina virtual possui maior folga operacional naquele horário.

6. Chamados de Sustentação (Incidentes, RITMs, SLA e MTTR)

A tela de Chamados de Sustentação consolida os tickets operacionais provenientes do ITSM corporativo (como ServiceNow) ou importados via planilha padronizada.

Indicador / Tabela Fórmula e Regra de Negócio Uso Operacional
Aderência de SLA (%) Percentual de chamados resolvidos dentro do prazo contratual de acordo com a severidade (Crítica, Alta, Média, Baixa). Monitora a qualidade do atendimento da equipe de sustentação RPA.
MTTR (Mean Time to Repair) Média de horas corridas ou úteis entre a abertura do incidente (INC) e sua resolução definitiva. Mede a velocidade de resposta e recuperação das automações em produção.
Tabela Detalhada de Tickets Colunas: Número (INC/RITM), Robô Relacionado, Área, Resumo, Prioridade, Status, Responsável, Data Abertura/Fechamento. Permite filtrar por período, área, status ou robô e exportar o relatório analítico para auditoria.

7. Gestão de Sprints, Backlog e Apontamento de Horas (Jira)

O módulo Backlog (Jira) integra as tarefas de engenharia e sustentação com os lançamentos de horas (worklogs) da equipe:

  • Quadro da Sprint (Board): Visualização das histórias, bugs e tarefas técnicas divididas por status da Sprint ativa.
  • Backlog Geral: Lista completa de issues priorizadas com código da chave, tipo de item, responsável e estimativa.
  • Análise de Horas por Colaborador & Qualidade das Horas: Tabela e gráficos que mostram o total de horas registradas por cada membro do squad no período selecionado, apoiando o fechamento de timesheet:
    • Equipe Ativa Monitorada: Avalia estritamente os integrantes ativos da equipe Cognition alocada no Jira, desconsiderando colaboradores inativos, ex-usuários (former users) e solicitantes do cliente.
    • Proteção do Dia Corrente (Expediente em Andamento): O dia de hoje (em curso) nunca é cobrado como falta ou anomalia. Ele não entra na lista de "Dias sem lançamento" e não gera déficit de horas antes do encerramento do dia.
    • Meta de Horas Esperadas: A meta esperada é calculada com base nos dias úteis já encerrados (8 horas por dia útil sem ausência cadastrada), somando o dia atual apenas quando o colaborador já registra a jornada completa de 8 horas.
    • Botão Sincronizar Jira: A própria tela de Qualidade das Horas disponibiliza o botão Sincronizar Jira e o carimbo de data e hora do último sync, permitindo puxar os apontamentos mais recentes do Jira Cloud em tempo real sem precisar navegar para outras abas.
  • Análise de Horas por Robô: Demonstra quais automações consumiram maior esforço de desenvolvimento ou manutenção evolutiva no mês.

8. Café de Produção, Minha Mesa, Mini Kanban Jira, Pomodoro e Cronograma WBS

O Café de Produção (acessado diretamente pelo botão Café na barra superior do portal) é a bancada individual de produtividade diária de cada colaborador. Ele concentra a Minha Mesa (demandas do Jira sob sua responsabilidade), organização pessoal, sub-visões dedicadas de trabalho, ambiência personalizável, foco cronometrado, gestão ágil de tarefas e acompanhamento arquitetural sem precisar alternar entre várias ferramentas externas.

Ferramenta do Café Funções e Controles Disponíveis Como tirar o máximo proveito
Sub-Visões do Café (Mesa do café, Minha mesa, Converse com a Nina e Foco e tempo) Seletor de 4 pílulas acima do Hero Banner à direita e botão de Modo Foco Imersivo (Tela Cheia) na barra superior. Use Mesa do café para ver todos os blocos integrados; Minha mesa para focar diretamente nas demandas do Jira sob sua responsabilidade e no seu Kanban; Converse com a Nina para expandir a assistente e o bloco de anotações; ou Foco e tempo para destacar apenas o Pomodoro, To-Do List, Mini Kanban e WBS.
Minha Mesa (Demandas do Jira no Café) Painel integrado dentro do Café exibindo KPIs de chamados Em Andamento, A Fazer, Sem Atualização (≥ 7 dias), Horas nos Abertos, Concluídos (30d) e os códigos NC em que você está trabalhando (com seletor de colaborador para gestores). Acompanhe em tempo real todas as entregas atribuídas ao seu usuário no Jira sem precisar sair do Café de Produção.
Seletor de Ambiente Visual (Café natural vs. Estúdio urbano) Pílulas no canto inferior direito do banner de boas-vindas (Seu café, [NOME]). Alterne entre a fotografia acolhedora de cafeteria orgânica (Café natural) e a estética arquitetônica moderna (Estúdio urbano). Sua preferência fica salva automaticamente.
Card Editorial da Nina no Café Saudação "O que vamos organizar hoje?", campo multi-linha (Enter envia, Shift + Enter quebra linha), acordeão Sobre a Nina e atalhos Minhas anotações e Ver conversa completa. Registre ideias rápidas, crie tarefas, consulte férias ou expanda a janela de conversa sem sair da sua bancada de produção.
Mini Kanban & Quadro Jira Pessoal Quadro interativo de 4 colunas (Backlog / Ideias, A Fazer Hoje, Em Execução (WIP) e Concluído) com suporte a arrastar e soltar (drag-and-drop), busca por chave/texto, filtro por categoria e criação rápida de cards com estimativa em horas. Clique em Puxar do Jira / WBS para importar automaticamente suas tarefas ativas do Jira e etapas do Cronograma WBS. Clique em Focar em qualquer card para movê-lo para Em Execução e iniciar imediatamente o timer Pomodoro vinculado a ele.
Gerador Automático de Daily Standup Botão Gerar Daily na barra do Mini Kanban. Com 1 clique, lê os cartões das colunas Concluído, Em Execução e A Fazer Hoje, monta o texto estruturado da sua reunião diária (Daily Standup), preenche o Bloco de Notas e copia automaticamente para sua área de transferência.
Bloco de Notas Rápidas (Scratchpad) Editor de texto persistente com salvamento automático por workspace e botões de modelos rápidos (+ Template Daily e + Checklist Deploy RPA). Use para guardar seletores XPath/SAP, queries SQL, payloads JSON de teste ou o roteiro de homologação de um robô antes do deploy.
Sessão de Foco (Timer Pomodoro) Cronômetro digital com ciclos de 25 min, 50 min e 90 min e banner superior Em Foco Agora. Ajuda a manter blocos de concentração profunda em uma única entrega por vez, emitindo aviso ao concluir o ciclo.
Minha To-Do List ("Uma coisa de cada vez") Checklist rápida sincronizada com a assistente Nina e com a Central de Notificações. Adicione lembretes rápidos do dia ou envie cartões do Kanban e etapas da WBS diretamente para sua checklist.
Cronograma de Desenvolvimento RPA (WBS) Tabela estruturada nas fases arquiteturais do robô (Init, Process e End), com horas estimadas, complexidade, data prevista e progresso percentual clicável (0% → 50% → 95% → 100%). Você pode cadastrar passos em tela ou clicar em Importar Excel para colar linhas diretamente da sua planilha de cronograma.
Trilha do Café — Seu mini Spotify & YouTube Music Card com botão Abrir mini Spotify, seletor de provedor (Spotify / YouTube Music), playlists de foco e suporte a inclusão de link de playlist própria. Ao iniciar a reprodução ou abrir o mini Spotify, o player permanece aberto e acessível no Hub enquanto você navega por qualquer outra tela do portal.

9. Portal Help Desk (Central de Chamados e Fluxo de Aprovação)

O módulo Portal Help Desk centraliza a abertura e o acompanhamento de solicitações internas para as equipes de Sustentação RPA, Infraestrutura, Acessos e Recursos Humanos:

  • Novo Chamado: Catálogo guiado por Categoria Geral, Subcategoria e Tipo de Serviço. O formulário adapta automaticamente os campos necessários e identifica se a solicitação exige aprovação de gestor.
  • Minhas Solicitações: Tabela com todos os chamados abertos pelo seu usuário, exibindo código do ticket, status atual, aprovador responsável e histórico de interações.
  • Visão do Aprovador: Habilitada para gestores, aprovadores designados e administradores, permitindo aprovar ou recusar solicitações pendentes com justificativa registrada em log.
  • Métricas de Atendimento: Painel analítico com volume de tickets por categoria, tempo médio de atendimento e distribuição por status.

10. Recursos Humanos (RH), Pessoas, Minha Mesa e Inventário de Sistemas

Módulo Objetivo e Tabelas Contidas
Painel de Gestão (RH do Gestor no Projeto) Painel executivo exclusivo do gestor com o recorte estrito da equipe alocada a este projeto, dividido em 6 visões estratégicas:
  • Visão Geral do Squad: KPIs de integrantes ativos, FTE dedicado, horas apontadas no mês, cards em andamento e distribuição por senioridade e frente de atuação.
  • Quadro de Colaboradores: Visualização alternável entre Modo Tabela e Modo Cards, exibindo cargo, senioridade, percentual de alocação, horas no Jira (30d), cards abertos e acesso ao portal.
  • Capacidade & Férias: Monitoramento de períodos de indisponibilidade programada (férias, folgas CLT, atestados) da equipe alocada, com botão para o gestor cadastrar novas ausências diretamente no projeto.
  • Esforço & Timesheet: Acompanhamento de horas lançadas pelo squad, percentual de participação e atalho direto para a análise de conformidade do timesheet no Jira.
  • Interlocutores do Cliente: Catálogo dos solicitantes, aprovadores e gestores do cliente que interagem com o projeto.
  • Horas Extras & Adicionais: Gestão mensal de serviços extraordinários, sobreaviso e plantões do squad, com filtros por competência (meses), cálculo automático de frações decimais e formato HH:MM, cadastro/edição/exclusão, exportação oficial para planilha Excel (.xlsx multi-abas idêntica ao modelo corporativo) e botão de cópia formatada em HTML para corpo de e-mail (Outlook/Gmail).
Minha Mesa (Integrada ao Café) Localizada dentro do Café de Produção (sub-visão Minha mesa), reúne os robôs sob sua responsabilidade, chamados do Jira atribuídos a você, horas lançadas e alertas de demandas sem atualização.
Sistemas e Tecnologias (Inventário) Catálogo de todos os sistemas alvo integrados pelas automações (SAP, portais web, bancos de dados, APIs, Active Directory), indicando tipo de conector, criticidade e quantos robôs dependem de cada aplicação.
Recursos Humanos Corporativo (5 Pilares) Disponível no workspace corporativo de RH, centraliza a gestão global da consultoria: Pessoas & Contratos, Controle de Férias CLT e Prazos Concessivos, Ciclo de Onboarding/Offboarding, Metas & Elegibilidade de Remuneração Variável (RV) e Escalas de Plantão de todos os workspaces da empresa.

11. Páginas Customizadas e Construtor Visual de Telas

O portal conta com um Construtor de Páginas que permite criar novos dashboards executivos e operacionais diretamente pelo navegador e publicá-los no menu lateral do workspace.

  • Como visualizar páginas criadas: Toda página publicada no Construtor aparece automaticamente na barra lateral esquerda para os perfis autorizados. Nela, qualquer usuário pode utilizar os Filtros Globais da Página (Slicers Reativos) no topo para filtrar simultaneamente todos os gráficos, indicadores e tabelas daquela tela, além de exportar a visão em PDF Executivo.
  • Biblioteca de 29 Elementos e 15 Fontes de Dados (Administradores): Superusuários podem combinar indicadores KPI, Velocímetro de Meta, Barra de Meta, Pódio Top 3, Matriz de Calor, Gráfico de Dispersão, Grade Horária 24h, Quadro Kanban, Linha do Tempo, Tabelas Buscáveis e qualquer um dos 23 Widgets Nativos conectando-os às 15 bases automáticas do portal ou a planilhas CSV/JSON próprias.

12. Como Usar a Assistente Virtual Nina (Consultas, Ações e Tours)

A Nina está disponível em todas as telas através do botão flutuante no canto inferior direito ou pelo atalho de teclado Ctrl + Espaço. Ela utiliza este Guia do Usuário e os dados ao vivo do seu workspace para responder dúvidas e executar ações:

O que você quer fazer Exemplos do que digitar ou clicar na Nina
Aprender a usar a tela aberta agora Clique no botão Tour desta tela no cabeçalho da Nina ou digite tour desta tela / como funciona esta tela.
Consultar meta anual e progresso de projetos Digite: quantos projetos faltam para bater a meta anual? ou qual a meta de projetos? — a Nina identifica o workspace ativo (ex: EMS Farmacêutica), cruza os robôs entregues em produção com a meta anual cadastrada e apresenta o saldo exato restante e os projetos em andamento na esteira funcional.
Tirar dúvidas sobre qualquer tela, tabela ou indicador Digite perguntas como: o que faz a tela de sustentação?, quais colunas tem na tabela funcional?, o que é MTTR?, como usar o mini kanban no café? ou explicar work queues.
Consultar a ficha completa de um robô Digite o código da automação, por exemplo: consultar NC0187 ou status do robô NC0187.
Navegar rapidamente entre módulos Digite: ir para esteira funcional, abrir monitoramento blue prism, ver horas no jira, abrir café de produção ou abrir guia do usuário.
Criar tarefas para o seu dia Digite: adicionar tarefa revisar logs do robô fiscal — a tarefa será incluída imediatamente na sua lista do Café de Produção.

13. Padrão Visual das Tabelas e Diretrizes de Consulta

Todas as tabelas do portal seguem uma convenção estrita de alinhamento semântico coluna x linha para proporcionar clareza de leitura, prevenir desalinhamentos e facilitar a interpretação tanto por pessoas quanto pela inteligência artificial Nina:

Tipo de Conteúdo Alinhamento Cabeçalho x Célula Exemplos no Portal Comportamento Visual
Textos, Títulos e Identificadores À Esquerda Código do Robô, Ticket Origem, Iniciativa, Área, Solicitante, Nome de Colaborador, Descrições. Garante leitura natural da esquerda para a direita, alinhando rigorosamente o título da coluna com os dados apresentados.
Métricas, Horas e Valores Financeiros À Direita (Tabular) Horas/Mês, Retorno ($), Custo Evitado ($), Total de Chamados, SLA em dias, Horas Lançadas e Esperadas no Jira. Usa tipografia numérica tabular (tabular-nums) para que casas decimais e ordens de grandeza alinhem verticalmente.
Status, Badges e Ações Operacionais Centralizado ou Em Bloco Badges de Etapa (Em Validação, Em Produção), Botões de Ação (Editar, Excluir), Selos de Conector. Foco equilibrado e botões táteis centralizados com espaçamento uniforme para cliques rápidos.
Rolagem e Responsividade Container Fluido Todas as tabelas envolvidas em .tablewrap. Mantém cabeçalhos fixos no topo durante rolagem vertical e permite navegação horizontal suave sem truncar dados essenciais.

Sumário Técnico (Admin)

  • 1. Visão Geral & Stack
  • 2. Segurança, HMAC & LGPD
  • 3. Arquitetura Multi-Tenant
  • 4. Catálogo de APIs REST
  • 5. Modelo de Dados & SQL
  • 6. Módulos & Regras de Negócio
  • 7. Roteamento & Frontend
  • 8. Operações & Manutenção
  • 9. Motor DS, Construtor & Kanban
Versão 2.6.0 • Produção Estável • Acesso Restrito Administrador

Portal Cognition — Manual de Arquitetura e Especificação Técnica

Documentação arquitetural de ponta a ponta: infraestrutura Edge Serverless, autenticação criptográfica HMAC-SHA256, governança LGPD, isolamento multi-tenant de banco de dados, catálogo de endpoints REST, motor unificado de dados (15 fontes), construtor de páginas (29 elementos e 23 widgets), produtividade Kanban no Café e base de conhecimento da IA Nina.

Ambiente: Serverless Edge Distribuído
Banco de Dados: Relacional Distribuído em Nuvem
Motor de IA: IA Generativa Corporativa (Isolada)
Classificação: Corporativo • Restrito TI / RPA

1. Visão Geral e Stack Tecnológica

O Portal Cognition é uma plataforma unificada de engenharia, governança, monitoramento operacional e produtividade estratégica voltada à esteira corporativa de Automação Robótica de Processos (RPA).

A solução consolida múltiplos domínios técnicos que historicamente operavam de forma fragmentada: sustentação operacional de incidentes e requisições (com conectores para ferramentas ITSM como ServiceNow, aplicado no projeto EMS, bem como esteiras customizadas de outros clientes), esteira funcional de savings e viabilidade WBS, telemetria de robôs RPA (Blue Prism e outras ferramentas de automação de mercado), topologia de runners virtuais, gestão de pessoas e conformidade trabalhista CLT, além de um ecossistema de produtividade com inteligência artificial isolada.

Edge Frontend (JAMstack)

Hospedado em infraestrutura Edge Anycast de alto desempenho. Distribuição estática com latência sub-50ms, carregamento assíncrono de módulos HTML via page-loader.js e controle granular de cache.

Serverless Backend

Funções serverless em JavaScript ES Modules executadas em ambiente V8 Isolates de alta performance. Processamento stateless, validação criptográfica de tokens e roteamento de APIs sob /functions/api/.

Banco de Dados Relacional

Armazenamento transacional distribuído com suporte a SQL padrão e comunicação segura via HTTPS/WebSockets com latência mínima, garantindo consistência ACID e isolamento físico ou lógico entre workspaces corporativos.

IA Generativa Integrada

Camada de inteligência generativa corporativa com inferência otimizada na borda. Respostas em tempo real para orientações de processos, busca semântica e suporte ao operador, operando sob mascaramento estrito de PII em conformidade com a LGPD.

1.1 Evolução e Roadmap Arquitetural (v2 Modern)

Com o objetivo de evoluir o portal para uma plataforma SaaS multicliente comercial de ponta, foi estabelecido o roadmap da v2 na branch dedicada v2-modern, incorporando as tecnologias mais eficientes do ecossistema:

  • TanStack Start & Nitro: Roteamento fortemente tipado de ponta a ponta, validação estrita de searchParams na URL via esquemas Zod (garantindo persistência perfeita de filtros de dashboards e eliminando erros em runtime) e motor desacoplado de nuvem (executável via Docker, VPS, Cloudflare Pages ou Node.js).
  • React 19 & shadcn/ui: Componentes de interface de alto padrão com código-fonte sob nosso total controle (Data Tables, Command Palette com atalho Ctrl+K, Dialogs acessíveis, Drawers e Tooltips nativos).
  • Tailwind CSS v4 (Oxide Engine): Compilação ultra-rápida em Rust com configuração CSS-first (@theme), permitindo customização instantânea de paletas por workspace e tema claro/escuro nativo.
  • Estratégia de Transição Faseada: Preservação completa da versão 1 em produção na branch main, com migração modular progressiva (Casca e Auth → Gestão e Horas Extras → Telemetria Blue Prism → Integrações Jira e Café).

2. Segurança da Informação, Autenticação e LGPD

A arquitetura de segurança do portal segue o princípio do Zero Trust e foi construída com camadas rigorosas de validação criptográfica, autorização baseada em papéis (RBAC) e anonimização preventiva em conformidade com a LGPD (Lei 13.709/2018).

2.1 Mecanismo de Autenticação HMAC-SHA256

O portal não utiliza sessões vulneráveis em memória de servidor central nem tokens opacos desprotegidos. As sessões são autenticadas por meio de tokens criptograficamente assinados:

  • Estrutura do Token: <payload_base64>.<assinatura_hex>.
  • Algoritmo de Assinatura: HMAC com função hash SHA-256 executada pela Web Crypto API nativa (crypto.subtle.sign e crypto.subtle.verify).
  • Chave Secreta (Secret): Fornecida via variável de ambiente restrita SESSION_SECRET injetada na camada segura do servidor (mínimo obrigatório de 32 caracteres).
  • Expiração Rigorosa: O payload contém o campo exp com validade máxima de 24 horas. Tokens com timestamp expirado são recusados automaticamente com HTTP 401.
  • Validação Ativa de Usuário: O token apenas identifica o usuário logado (login); o perfil (role) e a lista de workspaces vinculados são lidos diretamente do banco global a cada requisição. Caso um operador seja desativado ou rebaixado, seu acesso cessa imediatamente.
Validação Criptográfica de Sessão (functions/_shared/sessao.js)
// Verifica a assinatura HMAC-SHA256 utilizando a chave do servidor const enc = new TextEncoder(); const chave = await crypto.subtle.importKey( 'raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'] ); const valido = await crypto.subtle.verify( 'HMAC', chave, hexParaBytes(assinaturaHex), enc.encode(dadosB64) ); if (!valido) return null; // Assinatura violada

2.2 Matriz de Controle de Acesso Baseada em Papéis (RBAC)

Nível / Papel Escopo Operacional Permissões Concedidas Limitações e Travas
superuser Administrador Global Acesso total a todos os workspaces, criação e exclusão de projetos, gestão de permissões RBAC, auditoria de IA, exclusão definitiva e configurações de infraestrutura. Nenhuma restrição de workspace: superusuários possuem autoridade para criar, parametrizar, desativar ou excluir qualquer projeto cliente do portal.
admin Líder Técnico / Gestor Acesso a workspaces autorizados, gestão de chamados do seu squad, edição de premissas funcionais, aprovação de escalas e parametrização de metas de equipe. Não pode gerenciar usuários globais nem reconfigurar parâmetros de servidor.
user Desenvolvedor / Analista Visualização de dashboards, abertura de chamados, consulta a férias e horas no Jira, acompanhamento do cronograma RPA e uso da assistente Nina. Apenas leitura ou ações operacionais restritas ao seu usuário.

2.3 Conformidade LGPD • Anonimização Preventiva e Retenção

Garantia de Isolamento de Dados: O motor de inteligência artificial não possui acesso direto de leitura à base de dados transacional nem a registros brutos de colaboradores. Os dados passam por três camadas de isolamento e higienização antes de qualquer inferência.
  1. Mascaramento Preventivo de PII em Runtime: O utilitário mascararDadosSensiveis(texto) higieniza qualquer texto antes de transmiti-lo à IA e antes de gravá-lo no log de auditoria.
  2. Padrões Mascarados: CPFs ([CPF_MASCARADO]), CNPJs ([CNPJ_MASCARADO]), RGs ([RG_MASCARADO]), Telefones ([TELEFONE_MASCARADO]), E-mails ([EMAIL_MASCARADO]), Cartões/Contas ([DADO_BANCARIO_MASCARADO]), Senhas e Tokens ([CREDENTIAL_PROTEGIDA]), Salários e Valores Monetários ([VALOR_SIGILOSO]).
  3. Política de Retenção Temporal Estrita (60 dias): A tabela de auditoria ia_audit_logs descarta automaticamente qualquer registro com mais de 60 dias (created_at < datetime('now', '-60 days')), garantindo descarte de passivo jurídico.

3. Arquitetura Multi-Tenant e Resolução de Bancos

O portal implementa uma arquitetura multi-tenant híbrida, combinando um catálogo mestre compartilhado com bancos transacionais dedicados e isolados por workspace corporativo.

Nível do Banco Variável / Binding Escopo de Dados Tabelas Contidas
Global Master env.DB_GLOBAL ou env.DB Catálogo Geral e Governança do Portal users, projects, user_workspaces, ia_audit_logs, user_roles, role_permissions.
Workspace EMS (Projeto Cliente) env.DB_WS_EMS Operações de Sustentação & Automação RPA (Projeto EMS) sc_req_item, incident, jira_worklogs, pipeline_funcional, project_architecture, horas_extras.
Workspace RH env.DB_WS_RH Gestão de Pessoas & Conformidade CLT rh_employees, rh_vacations, rh_goals, rh_shifts, rh_onboarding, chamados.

A resolução de instâncias é intermediada dinamicamente pelo módulo functions/_shared/db-router.js:

  • Ao receber uma requisição HTTP, o cabeçalho ou payload informa o project_id (ex: ems, rh).
  • A função resolverBindingWorkspace(env, projectId) mapeia o binding correto. Se o workspace possuir banco próprio configurado, o tráfego é direcionado com isolamento físico; caso contrário, utiliza a instância padrão mantendo particionamento por chave.

4. Catálogo Completo de APIs REST (/functions/api/)

Todas as operações de escrita e consultas dinâmicas são expostas como endpoints HTTP seguros sob o prefixo /api/*. A autenticação exige o envio do cabeçalho Authorization: Bearer <token>.

Método • Rota Ação (action) Parâmetros Chave Resposta / Códigos Descrição Operacional
POST /api/auth login login, password 200 OK: { success, token, user }
401: Credenciais inválidas
Validação de credenciais no banco de dados relacional, conferência de hash SHA-256 e geração de token HMAC assinado.
POST /api/auth update_mode mode (light ou dark) 200 OK: { success, mode } Persistência individualizada da preferência de tema claro ou escuro no perfil do usuário no banco.
POST /api/projects list_for_user actorLogin 200 OK: { success, projects: [] } Retorna a lista de workspaces acessíveis pelo colaborador de acordo com sua permissão no banco global.
POST /api/projects update_settings id, stages, theme, target_year_automations 200 OK / 403 Forbidden Parametrização das etapas do funil WBS e metas de automação (exclusivo para superusuários).
POST /api/nina Prompt Chat prompt, historico 200 OK: { success, response, model } Processamento de linguagem natural pelo motor de IA generativa integrado, com anonimização prévia de PII e auditoria de log.
POST /api/rh listar_todos workspace_id 200 OK: { colabs, ferias, metas, escalas } Consolidação dos dados dos 5 pilares estratégicos de Recursos Humanos para o workspace ativo.
POST /api/jira sync_worklogs workspace_id, from_date 200 OK: { total_synced, worklogs: [] } Sincronização de apontamentos de horas da API do Jira Cloud para auditoria de produtividade.
POST /api/chamados criar titulo, descricao, categoria, prioridade 200 OK: { id, ticket_code } Abertura de ticket na Central de Chamados interna com disparo de fluxo de aprovação multinível.
POST /api/commit Salvar Arquivo path, content, message 200 OK: { success } Persistência versionada de arquivos CSV/JSON diretamente no repositório de dados do portal.
POST /api/people upsert, list, delete project_id, person: { id, name, email, role, status, org_type } 200 OK: { success, id } Cadastro unificado de pessoas e vínculos com suporte a organização (cognition, cliente, outros) e status ativo/inativo.
POST GET /api/horas-extras list, save, delete, import project_id, item: { id, mes, data, recurso, motivo, horas, horas_decimal, tipo, solicitacao } 200 OK: { success, itens: [...] } Gestão de horas extras e adicionais do squad por workspace. Suporta cadastro pontual ou em intervalo, cálculo automático de frações decimais e formato HH:MM e persistência multi-tenant isolada.

5. Modelo de Dados e Esquema SQL Relacional

Abaixo constam as definições de DDL (Data Definition Language) das tabelas fundamentais que sustentam a infraestrutura do portal:

DDL: Catálogo de Usuários, Workspaces e Auditoria de IA
-- 1. Usuários do Portal com perfil RBAC e modo visual persistido CREATE TABLE IF NOT EXISTS users ( login TEXT PRIMARY KEY, password_hash TEXT NOT NULL, name TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'user', -- 'superuser', 'admin', 'user' project_id TEXT DEFAULT 'ems', theme_mode TEXT DEFAULT 'dark', -- 'dark' ou 'light' created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 2. Workspaces e Projetos RPA CREATE TABLE IF NOT EXISTS projects ( id TEXT PRIMARY KEY, name TEXT NOT NULL, subtitle TEXT, logo_path TEXT, rpa_tool TEXT DEFAULT 'blueprism', target_year_automations INTEGER DEFAULT 10, stages TEXT, -- JSON com etapas do funil WBS active INTEGER DEFAULT 1, theme TEXT DEFAULT 'slate', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 3. Mapeamento de Vínculo Colaborador-Workspace (N:N) CREATE TABLE IF NOT EXISTS user_workspaces ( login TEXT NOT NULL, project_id TEXT NOT NULL, PRIMARY KEY (login, project_id) ); -- 4. Logs de Auditoria de IA com Descarte Temporal (60 dias) CREATE TABLE IF NOT EXISTS ia_audit_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, user_login TEXT, user_name TEXT, prompt_mascarado TEXT, resposta_mascarada TEXT, model TEXT, source TEXT DEFAULT 'edge-ai-runtime', duration_ms INTEGER, status TEXT );
DDL: Recursos Humanos, Férias CLT e Central de Chamados
-- 5. Colaboradores e Contratos de RH CREATE TABLE IF NOT EXISTS rh_employees ( employee_id TEXT PRIMARY KEY, full_name TEXT NOT NULL, email TEXT UNIQUE NOT NULL, role_title TEXT NOT NULL, contract_type TEXT DEFAULT 'CLT', -- 'CLT', 'PJ', 'Estagiário' primary_workspace_id TEXT DEFAULT 'ems', hours_weekly INTEGER DEFAULT 44, hourly_rate REAL DEFAULT 0, admission_date DATE NOT NULL, status TEXT DEFAULT 'active' ); -- 6. Saldos e Conformidade de Férias CLT CREATE TABLE IF NOT EXISTS rh_vacation_balances ( employee_id TEXT PRIMARY KEY, days_balance INTEGER DEFAULT 30, vesting_end DATE, -- Término do período aquisitivo concessive_deadline DATE, -- Limite concessivo antes da dobra legal deadline_status TEXT -- 'regular', 'warning', 'expired' ); -- 7. Central de Chamados e Service Desk CREATE TABLE IF NOT EXISTS service_tickets ( id INTEGER PRIMARY KEY AUTOINCREMENT, ticket_code TEXT UNIQUE, category TEXT NOT NULL, requester_login TEXT NOT NULL, assigned_to TEXT, title TEXT NOT NULL, description TEXT, priority TEXT DEFAULT 'media', -- 'baixa', 'media', 'alta', 'critica' status TEXT DEFAULT 'aberto', -- 'aberto', 'em_analise', 'concluido' created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 8. Cadastro Único de Pessoas com Vínculo Organizacional CREATE TABLE IF NOT EXISTS people ( project_id TEXT NOT NULL, id TEXT NOT NULL, display_name TEXT NOT NULL, email TEXT, email2 TEXT, login TEXT, jira_name TEXT, role TEXT, area TEXT, manager TEXT, status TEXT NOT NULL DEFAULT 'ativo', -- 'ativo', 'inativo' org_type TEXT DEFAULT 'cognition', -- 'cognition', 'cliente', 'outros' aliases TEXT, notes TEXT, source TEXT, updated_at TEXT, updated_by TEXT, PRIMARY KEY (project_id, id) ); -- 9. Horas Extras e Serviços Extraordinários do Squad (Multi-Tenant) CREATE TABLE IF NOT EXISTS horas_extras ( id TEXT NOT NULL, project_id TEXT NOT NULL, mes TEXT NOT NULL, mes_label TEXT, data TEXT NOT NULL, recurso TEXT NOT NULL, motivo TEXT NOT NULL, horas TEXT NOT NULL, horas_decimal REAL NOT NULL, tipo TEXT NOT NULL, solicitacao TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')), PRIMARY KEY (id, project_id) );

6. Módulos Operacionais e Regras de Negócio

6.1 Centro de Comando (Home & Workspaces)

Tela de entrada responsável pela governança de ambientes. Permite que superusuários criem novos workspaces corporativos, configurem funis de desenvolvimento customizados e gerenciem o ciclo de vida completo dos projetos clientes, incluindo status de ativação (soft delete) e exclusão definitiva quando aplicável.

6.2 Visão Geral Modular Dinâmica

Painel executivo com grade de widgets configurável individualmente por usuário e por workspace (armazenada em localStorage sob a chave vg_prefs_v2_<workspace>). Inclui reordenação por arrastar e soltar (drag-and-drop), skeletons de pré-carregamento e KPIs superiores consolidados em tempo real (Total de Robôs, Execuções, Taxa de Sucesso, Runners Ativos e Volume de Chamados).

6.3 Sustentação Operacional RPA (Incidentes & RITMs)

Ingestão e consolidação de relatórios e métricas de chamados operacionais (com suporte a conectores ITSM como ServiceNow — incident.csv e sc_req_item.csv — aplicados no projeto EMS, bem como formatos e esteiras padronizadas de outros clientes):

  • MTTR (Mean Time to Repair): Tempo médio de resolução de falhas de robôs.
  • Aderência de SLA: Percentual de tickets atendidos dentro do compromisso operacional.
  • Pareto de Causas Raiz: Classificação das falhas entre Mudança de Sistema (Ambiente Alvo), Infraestrutura, Input de Dados ou Erro de Código.

6.4 Esteira Funcional de Projetos RPA

Gestão do ciclo de vida das automações segundo metodologia WBS (Work Breakdown Structure). Acompanha o funil de desenvolvimento: Backlog → Mapeamento → Estudo de Viabilidade → PDD → Desenvolvimento → Homologação → Operação Assistida → Entregue. Calcula savings em horas humanas economizadas e retorno financeiro estimado, com exportação nativa em PowerPoint (PPTX) via PptxGenJS.

6.5 Monitoramento Técnico de Automações RPA (Ex: Blue Prism)

Telemetria direta da saúde das automações (com ingestão de arquivos técnicos como blueprism_tecnico.json no cliente EMS ou telemetrias equivalentes por ferramenta RPA). Avalia itens em fila (Work Queues), taxa de sucesso de execuções, incidentes abertos de robôs críticos e alertas automáticos de paradas não programadas.

6.6 Recursos Humanos, Pessoas & Férias CLT

Módulo estratégico com conformidade estrita às leis trabalhistas brasileiras (CLT):

  • Alertas de Prazos Concessivos: Monitora o período concessivo de férias. Dispara alertas amarelos com 60 dias de antecedência e alertas vermelhos para férias vencidas com risco de dobra legal obrigatória.
  • Metas & Bônus RV (Remuneração Variável): Lógica avaliativa invertida exclusiva do portal (Nota 1 = Excede expectativas/topo; Nota 5 = Muito abaixo/insuficiente). Fórmula de cálculo: RV = Target_Bonus × Bonus_Operacional × Coef_Individual × Pro_Rata.
  • Travas Sistêmicas de Elegibilidade: Para ser elegível ao bônus de RV, o colaborador deve possuir no mínimo 6 meses completos no exercício (admissão até 30/06), ausência total de sanções disciplinares e aprovação inegociável da aderência de apontamento de horas no JIRA.
  • Auditoria de Timesheet (Jira): Indicador de conformidade dos lançamentos de horas quinzenais e mensais, identificando apontamentos retroativos ou anomalias de esforço.
  • Escalas de Plantão & Sobreaviso: Calendário dinâmico de plantonistas responsáveis pela sustentação de robôs críticos em feriados e finais de semana.

6.7 Espaço Café de Produção, Minha Mesa Integrada, Sub-Visões, Ambiência & Mini Kanban Jira

Ambiente exclusivo para desenvolvedores e analistas focado na produtividade contínua (acessado pelo botão dedicado Café na barra superior e controlado por js/pages/cafe/init.js e js/pages/mesa/init.js):

  • 4 Sub-Visões Modulares e Modo Imersivo: Seletor de 4 modos (Mesa do café, Minha mesa, Converse com a Nina e Foco e tempo, persistido em cafe_subvisao_ativa), seletor de ambiência visual no Hero Banner (Café natural vs. Estúdio urbano em cafe_ambiente_visual) e modo tela cheia (cafeAlternarModoImersivo()).
  • Minha Mesa Integrada (Jira): Embute dentro do Café (`#cardCafeMinhaMesa`) a consulta ao endpoint /api/jira (ação minha_mesa), exibindo KPIs individuais de issues em andamento, a fazer, paradas (≥ 7 dias), horas apontadas e códigos NC ativos.
  • Card Editorial da Nina: Interface conversacional com suporte a entrada multi-linha (Enter envia, Shift + Enter insere quebra de linha), painel explicativo Sobre a Nina, atalho direto para Minhas anotações e expansão de histórico (Ver conversa completa).
  • Mini Kanban & Quadro Jira Pessoal: Quadro persistido por workspace (cafe_kanban_cards_<ws>) com 4 colunas (backlog, todo, doing, done), suporte a HTML5 Drag-and-Drop, sincronização automática com a fonte jira_issues e com o Cronograma WBS da Nina, e vínculo direto com o Pomodoro.
  • Gerador de Daily Standup & Bloco de Notas Técnico: Consolida os cartões concluídos, em execução e planejados em texto formatado para reunião diária, persistindo rascunhos técnicos na chave cafe_scratchpad_<ws>.
  • Cronômetro Pomodoro com Tarefa em Foco: Presets de 25m, 50m e 90m com banner de tarefa ativa (cafe_foco_tarefa_ativa) e alertas sonoros de transição.
  • Lista "Uma Coisa de Cada Vez" e Seu Mini Spotify: To-Do list conectada aos passos da WBS e card Trilha do Café — Seu mini Spotify com acionador rápido do miniplayer global e sincronização via postMessage.

6.8 Nina Assist (Assistente Virtual, Tour Contextual Multi-Trilhas e Base Documental)

Assistente conversacional flutuante baseada em IA generativa corporativa (js/core/nina.js e js/core/nina-tour.js), acionada pelo botão flutuante ou pelo atalho Ctrl + Space.

Possui 5 trilhas de Tour Guiado Interativo (portal, tela, operacao, construtor, cafe) com detecção dinâmica de elementos fixos e retração automática da sidebar, além de integração direta com a base estruturada do Guia do Usuário (window.PORTAL_USER_DOCS_KB) para explicar o funcionamento de qualquer tela, tabela ou indicador do sistema.

7. Roteamento, Ciclo de Vida e Inicialização

O portal opera como uma aplicação de página única (SPA — Single Page Application) desacoplada, utilizando Vanilla JavaScript moderno para performance máxima sem dependências pesadas.

7.1 Carregamento Dinâmico de Páginas (page-loader.js)

Ao abrir o portal, o script js/core/page-loader.js faz a busca paralela de todos os arquivos HTML em pages/*.html e partials/*.html, injetando-os dentro de #pageContainer e #modalsRoot no DOM principal.

Cada requisição anexa um parâmetro de controle de cache (?v=...). Quando todos os arquivos estão injetados e o DOM está pronto, o sistema dispara a fila de callbacks window.onAppReady(fn), garantindo que os controladores JavaScript iniciem apenas com seus elementos já presentes na árvore.

7.2 Máquina de Estados de Roteamento (router.js)

A navegação visual é orquestrada pela função central switchWorkspaceView(viewName):

  • Alterna a exibição das seções <section id="view..."> entre block e none.
  • Atualiza as classes ativas no menu lateral (#sidebar-menu-list).
  • Controla a visibilidade dos logos institucionais no topo e do botão "Sair do Workspace".
  • Valida permissões antes de exibir páginas restritas (ex: wsetup, acessos, construtor).

7.3 Internacionalização Dinâmica (i18n)

O portal suporta três idiomas em tempo real: Português do Brasil (pt-BR), Inglês (en) e Espanhol (es). Elementos HTML contêm o atributo data-i18n="chave", e o motor js/i18n/engine.js traduz textos, rótulos e títulos sem recarregar a página.

7.4 Padrão Arquitetural de Tabelas e Grid de Dados

O portal implementa regras globais em css/components.css para assegurar que nenhuma tabela sofra com herança inadequada de alinhamento entre cabeçalho (th) e células (td):

  • Base Universal Alinhada à Esquerda: Elementos th e td possuem por padrão text-align: left; vertical-align: middle;, eliminando falhas de alinhamento em colunas textuais subsequentes (como Área, Solicitante, Status e Descrição).
  • Utilitários Padronizados: Classes .num ou .r aplicam text-align: right; font-variant-numeric: tabular-nums; para colunas monetárias e de contagem; classe .center aplica text-align: center;.
  • Isolamento de Matrizes Especiais: A tabela de matriz mensal .painel (Sustentação) mantém a primeira coluna fixa à esquerda e as colunas dos meses alinhadas à direita com rolagem horizontal controlada.
  • Mapeamento Estrito por Módulo: Regras específicas de #tblFuncional (em css/funnel.css), #areaTable e #reqTable (em css/components.css) e #pplTabela (em css/pessoas.css) mapeiam as posições de cada coluna para garantir consistência visual perfeita.

7.5 Motor de Qualidade de Horas e Timesheet Jira (jira-analises.js)

O cálculo de qualidade dos apontamentos de horas é executado pela função pura analisarHoras() em functions/_shared/jira-analises.js, garantindo rigor e eliminando falsos positivos:

  • Proteção do Dia Corrente (Expediente em Andamento): O cálculo de dias com falta (missing_days) filtra estritamente d < hoje. Dessa forma, o dia de hoje — cujo expediente ainda está acontecendo — jamais é classificado como ausência ou falta de apontamento.
  • Cômputo Proporcional de Horas Esperadas: No período em aberto, a cobrança de horas esperadas (expected_h) é baseada na soma dos dias úteis já encerrados (8h por dia útil sem ausência cadastrada), integrando o dia de hoje apenas quando o colaborador já atinge a marca de 8 horas lançadas. Isso evita déficits irreais de horas para a equipe durante o horário comercial.
  • Filtragem e Resolução de Autores: A função acharMembro() faz o matching biunívoco entre os registros de jira_worklogs e o cadastro de colaboradores através de normalização Unicode NFD, remoção de acentos e pontuações (ex: Kepler.Sales ↔ Kepler Sales), cobrindo tanto accountId quanto displayName.
  • Sincronização Híbrida (updated + worklogDate): A consulta JQL na API /api/jira utiliza a condição (updated >= desde OR worklogDate >= desde). Isso impede que tickets antigos ou já encerrados (Done) que receberam novos lançamentos de horas sejam ignorados na sincronização incremental.
  • Sincronização Integrada na Interface: O frontend em js/pages/jira/analise-horas.js disponibiliza o botão jiraQlSincronizar() diretamente no banner de equipe, permitindo requisições incrementais ou completas (data.full = true) com exibição de data e hora da última sincronização.

7.6 Arquitetura do Painel de Gestão do Projeto (RH do Gestor)

O módulo pages/pessoas.html e seu controlador js/pages/pessoas/init.js foram arquitetados para atuar como o Painel de Gestão do Projeto, oferecendo a visão de RH restrita ao recorte operacional do ambiente ativo:

  • Isolamento de Escopo (Workspace Tenant): Em contraste com o workspace de RH (que opera com dados globais da empresa), o Painel de Gestão consulta /api/people com project_id específico, retornando estritamente os colaboradores alocados ao projeto ativo.
  • Métricas de Capacidade e Alocação (FTE): A função pplRenderVisaoGeral() computa a somatória de percentual_alocacao dos membros do squad (gerando o total de FTEs dedicados ao cliente), cruza com os apontamentos de jira_worklogs (30 dias) e monitora a quantidade de cards em andamento.
  • Planejamento de Ausências Integrado: A aba Capacidade & Férias integra-se diretamente à tabela jira_absences por meio do endpoint /api/jira (ações absence_add e absence_delete), permitindo ao gestor registrar férias, folgas e licenças do squad para planejamento de capacidade das sprints.
  • Chaveamento de Visualização (Grid Responsivo de Cards): O controlador implementa a função pplAlternarModoVisao('tabela' | 'cards'), permitindo alternar instantaneamente entre a tabela analítica e uma grade de cartões de perfil (.ppl-cards-grid) com avatar, tags de senioridade, área e links para a ficha individual do colaborador.

7.7 Identificação e Preenchimento Assistido de Áreas no Pipeline (area-detector.js)

O módulo js/pages/funcional/area-detector.js adiciona inteligência analítica para resolução de iniciativas sem departamento ou unidade de negócio associada no pipeline funcional, cumprindo a diretriz de confirmação mandatória pelo analista antes de qualquer alteração de dados:

  • Varredura por Expressões Regulares no Nome do Projeto/Bot (Método Prioritário): O algoritmo avalia o nome da iniciativa, o código NC e o processo do robô registrado no Blue Prism contra a lista canônica de áreas. Padrões de delimitação léxica por regex (\b, colchetes [...], underscores _..._ e hífens) realizam o matching direto de siglas operacionais:
    • Presença de PX (ex: [PX] Comprovante, PX_Lancamento) → Área PX (ou Marketing - Prescrição - PX);
    • Presença de CSI (ex: NC0026_CSI_FIS..., CSI - Faturas) → Área CSI (com qualificação automática para Csi - Fiscal ou Csi - Travel & Expense conforme subtipos);
    • Presença de GQ → Área Garantia da Qualidade;
    • Presença de P&D, PeD ou Resultados Analíticos → Área P&D;
    • Presença de JUR, Patentes ou Apol → Área Juridico;
    • Presença de SIP, Vendas ou Mercanet → Área Trade Marketing / Vendas;
    • Presença de Ariba ou Suprimentos → Área Compras - Suprimentos Indiretos;
    • Presença de Tempo de Processo → Área Engenharia de Processo;
    • Presença de HP ou Hospitalar → Área Diretoria Hospitalar.
  • Cruzamento Secundário com Tickets RITM: Caso a regex direta não encontre uma sigla no nome, a função carregarBasesDeteccaoArea() cruza o ticket de origem com data/ems/sc_req_item.csv e data/ems/areas_solicitantes.csv, localizando o solicitante e sua área.
  • Interface de Confirmação Assistida (modalAutoDetectArea): Exibe tabela com listagem das iniciativas sem área, grau de confiança da sugestão, justificativa transparente e seletor da área. O analista revisa, ajusta e confirma explicitamente as demandas desejadas antes da gravação no pipeline.
  • Sugestões Inline na Tabela e no Modal de Cadastro: Linhas sem área exibem badge de sugestão com botão de confirmação em 1 clique direto na célula, enquanto o modal de novo projeto sugere a área em tempo real durante a digitação do ticket ou iniciativa.

7.8 Widgets Modulares com Redimensionamento Dinâmico (visao-geral/init.js)

O motor da Visão Geral foi aprimorado para suportar largura ajustável sob demanda por card e proporções equilibradas de exibição:

  • Ajuste da Proporção do Widget Funil por Etapa: A classe .vg-s2 foi reconfigurada para ocupar 2 colunas da grade (grid-column: span 2) em vez de esticar em 100% da tela, permitindo que o Funil por Etapa e outros gráficos horizontais convivam lado a lado harmoniosamente em telas desktop.
  • Seletor de Tamanho no Cabeçalho de Cada Card: Cada widget recebe o controle .vg-size-toggle com as opções 1x (Compacto / 1 coluna), 2x (Médio / 2 colunas) e Full (Largura Total), acionando a função vgDefinirTamanhoWidget(id, size).
  • Persistência de Layout por Workspace: As escolhas de tamanho são gravadas na chave vg_prefs_v2_<workspace> do localStorage, mantendo a experiência personalizada de cada gestor e analista intacta entre sessões.
  • Configuração Integrada no Modal de Personalização: No modal Personalizar Painel (abrirModalCustomizarDash()), cada widget ativado conta com seletor de largura correspondente.

7.9 Diagnóstico e Topologia Multi-Tenant Distribuída Turso / D1 (migrate-d1.js)

A aba de infraestrutura de dados no Painel de Acessos e o endpoint functions/api/migrate-d1.js foram atualizados para refletir a topologia Multi-Tenant real baseada no Turso libSQL (com edge na região aws-sa-east-1) e Cloudflare D1:

  • Eliminação de Estouro de Subrequests (Batch Queries): O diagnóstico de tabelas foi migrado de requisições individuais isoladas para execução agrupada em lote (db.batch() e união de contagens), reduzindo o consumo de subrequests do Cloudflare Worker para menos de 8 chamadas no total, eliminando completamente falhas de Too many subrequests.
  • Inspeção Defensiva de Metadados: A contagem de registros verifica previamente a existência de tabelas via sqlite_master, retornando status limpo (não criada) sem abortar a requisição de status caso alguma tabela ainda não tenha sido inicializada.
  • Interface com Exibição de Motor e Host Ativo: A aba no Painel de Acessos foi consolidada como Topologia de Dados (Multi-Tenant), exibindo com clareza os três bancos ativos do cluster (Control Plane db-global, Workspace db-ws-ems e Workspace db-ws-rh), detalhando o motor em operação (Turso libSQL / aws-sa-east-1 ou Cloudflare D1) e isolando rotinas legadas de contingência em painel secundário retrátil.

8. Operações, Manutenção e Troubleshooting

8.1 Variáveis de Ambiente Mandatórias

Nome da Variável Tipo Finalidade Técnica
SESSION_SECRET Secret (Texto Seguro) Chave privada de 32+ caracteres para assinatura criptográfica HMAC-SHA256 dos tokens de sessão.
DATABASE_URL Texto (URL Segura) Endpoint de conexão HTTPS/WSS da camada de banco de dados relacional distribuído.
DATABASE_AUTH_TOKEN Secret (Bearer Token) Token de autorização mútua e controle de acesso aos clusters distribuídos de dados.
AI IA Engine Binding Vínculo com o catálogo de inteligência artificial para inferência dos modelos de linguagem corporativos.

8.2 Rotina de Limpeza e Retenção Temporal de Logs de Auditoria

Para garantir conformidade permanente com a LGPD e evitar acúmulo desnecessário de dados, execute periodicamente a rotina de limpeza de logs com mais de 60 dias:

Execução de Expiração de Logs (scripts/tools/expirar_ia_audit_logs.sh)
# Executa a limpeza de logs de auditoria com retenção padrão de 60 dias bash scripts/tools/expirar_ia_audit_logs.sh # Ou parametrize a retenção desejada (ex: 30 dias) node scripts/tools/expirar_ia_audit_logs.js --dias=30

8.3 Procedimentos de Contingência, Isolamento de Contexto e Troubleshooting

  • Isolamento de Escopo e Contexto Ativo da Nina: A cada requisição enviada a /api/nina, o frontend anexa o payload contexto contendo o identificador do workspace (projetoId), nome formal (projetoNome), perfil do ambiente (projeto de cliente vs RH corporativo), tela em foco, meta anual de automações cadastrada (target_year_automations) e consolidado numérico da esteira funcional (entregues em produção, em construção, backlog e cancelados). Isso garante que perguntas sobre metas, entregas e robôs sejam resolvidas dentro do escopo do cliente ativo (ex: EMS Farmacêutica), prevenindo desvios para módulos de RH corporativo.
  • Higienização e Proteção de Tags de Navegação: O frontend executa substituição textual amigável para tags [NAV:area:sub] quando posicionadas dentro de frases explicativas, evitando resíduos sintáticos (como lacunas antes de pontuação) e bloqueia a renderização de botões com códigos fictícios (como NCXXXX).
  • Motor de Filtro Consolidado Blue Prism (NC e Multi-Processos): O módulo js/pages/blueprism/tecnico.js implementa a função bptProcPermitido(idx) que suporta seleções consolidadas no formato NC:NCXXXX, permitindo que robôs com múltiplos processos (como NC0383 com Consolidation, Dispatcher e Performer) tenham suas métricas agregadas simultaneamente em sessões, itens, work queues e exceções. No modal flutuante de configuração, o motor oferece busca em tempo real com preservação de estado no localStorage (bpt_procs_ocultos), atalhos de isolamento por busca ou por código NC, e botão de restauração rápida.
  • Automação de ETL via GitHub Actions (Erro 403 / Permissão de Escrita): O workflow .github/workflows/atualizar_dados.yml executa periodicamente a extração e sincronização dos dados do Blue Prism e Jira com commit em data/. Para que o job possa realizar o push de volta ao repositório sem falhas de autenticação (HTTP 403), o workflow declara explicitamente a permissão permissions: contents: write tanto no nível global quanto no job build, utilizando o actions/checkout@v4 com o token de execução. Adicionalmente, caso o repositório possua políticas organizacionais herdadas, certifique-se de que em Settings → Actions → General → Workflow permissions esteja selecionada a opção Read and write permissions.
  • Falha na Troca de Workspace: Verifique se o cache do navegador reteve versões antigas de scripts. Realize um recarregamento forçado com Ctrl + F5.
  • Workers AI Indisponível (Erro na Nuvem): O endpoint /api/nina ativa automaticamente o fallback local, respondendo normalmente sem gerar erros 500 no console.
  • Sessão Expirada (HTTP 401): Ocorre após 24 horas da autenticação inicial. O portal detecta o status e redireciona o usuário para o formulário de login de forma transparente.
Governança Contínua: Sempre que um novo módulo, widget, fonte de dados ou ferramenta for adicionado ao portal, tanto o Guia do Usuário quanto esta Especificação Técnica são atualizados de forma sincronizada.

9. Motor de Dados Unificado (DS), Construtor Visual (ELEM/PCUS) e Widgets

Para permitir a criação de páginas e dashboards diretamente pela interface sem necessidade de deploy de código, o portal dispõe de três motores acoplados no frontend: js/core/dados.js (window.DS), js/core/elementos.js (window.ELEM) e js/pages/construtor/paginas.js (window.PCUS).

9.1 Catálogo de 15 Fontes de Dados Embutidas (DS.EMBUTIDAS)

ID da Fonte (dataset) Origem / Arquivo ou Endpoint Campos Normalizados Principais
funcional Memória ALL_FUNC / pipeline_funcional codigo, nome, area, etapa, status, horas_economizadas, roi, responsavel
sustentacao Memória ALL / incident.csv + sc_req_item.csv numero, tipo, robo, area, prioridade, status, sla, mttr_horas
bp_criticas, bp_hoje, bp_itens, bp_sessoes blueprism_tecnico.json Telemetria de robôs críticos (30d), sessões do dia corrente, volumetria de Work Queues e histórico de execuções por Runner.
infra_vms, infra_robos infra.json / project_architecture Inventário de máquinas virtuais (CPU, RAM, SO, status) e alocação de robôs/schedules por servidor.
jira_issues, jira_horas /api/jira / jira_worklogs Chaves da Sprint, status, prioridade, responsável, horas gastas por tarefa, colaborador e robô.
pessoas, chamados_hd, sistemas, cafe_cronograma, rh_ausencias Bases internas de Pessoas, Help Desk, Inventário Tecnológico, WBS do Café e Férias/Ausências RH Permitem cruzar indicadores operacionais com alocação de squad, catálogo de sistemas integrados e progresso de desenvolvimento WBS.

9.2 Catálogo de 29 Elementos Visuais (ELEM.TIPOS) e Filtros Reativos

  • Indicadores e Metas (6 tipos): kpi, kpi_icone, progresso, velocimetro (Gauge SVG semicircular), destaque e comparativo.
  • Gráficos Analíticos (9 tipos): barras, colunas, empilhado, linha, area, pizza, funil, dispersao (Scatter Plot X vs. Y) e matriz_calor (Heatmap 2D Categoria × Subcategoria).
  • Tabelas, Quadros e Listas (7 tipos): tabela (com busca instantânea local e exportação CSV), lista, podio (Top 3 Ouro/Prata/Bronze), kanban, grade_cards, timeline e grade_horaria (Ocupação 00h–23h).
  • Controles Interativos e Organização (6 tipos): filtro_pagina (Slicer global reativo que filtra em tempo real todos os blocos da página via ELEM.filtrosPagina), atalhos, checklist, alerta, texto e divisor.
  • Widgets Nativos Incorporados (widget_portal): Permite embutir qualquer um dos 23 widgets executivos de VG_WIDGETS dentro de páginas customizadas.
  • Portabilidade e Impressão: Suporte nativo a exportação/importação de definição de página em .json e folha de estilo @media print dedicada em css/construtor.css.