Manual Operacional do Suporte N3

1. Triagem, Roteamento e Escalonamento

O ecossistema de suporte do e-SUS AF opera em três níveis funcionais e técnicos de atendimento, assegurando que apenas problemas devidamente qualificados e insolúveis por regras de negócio alcancem o time de engenharia:

flowchart TD
    Inicio([Chamado do Usuário / Município / Estado]) --> N1[1. Suporte N1: Atendimento Inicial & FAQ]

    N1 --> Q1{Dúvida Operacional ou FAQ?}
    Q1 -->|Sim| R_N1[N1 responde e encerra chamado]
    Q1 -->|Não: Regra Negocial / Inconsistência| N2[2. Suporte N2: Análise Funcional & Negócio]

    N2 --> Q2{Resolvido por Regra ou Parâmetro?}
    Q2 -->|Sim| R_N2[N2 orienta N1 -> Encerramento]
    Q2 -->|Não: Suspeita de Bug / Erro 500 / BD| Q_DOR{Atende ao DoR do Suporte N3?}

    Q_DOR -->|Não: Incompleto| DEV_N2[Devolução para N2 com SLA Suspenso]
    DEV_N2 --> N2

    Q_DOR -->|Sim: 5 Critérios Atendidos| N3[3. Suporte N3: Análise Técnica Avançada]

    subgraph Atuacao_N3["Atuação Operacional do Suporte N3 (2 Membros)"]
        N3 --> N3_ANALISE[Inspeção de Logs, Banco de Dados e Código]
        N3_ANALISE --> N3_REPROD[Reprodução em Ambiente de Homologação]
        N3_REPROD --> Q_TIPO{Tipo de Resolução Identificada?}

        Q_TIPO -->|Inconsistência de Dados / Sem Bug de Código| SCRIPT_FLOW[Procedimento Seguro de Script de BD]
        SCRIPT_FLOW --> RET_N2[Disponibiliza ao N2 para Validação]

        Q_TIPO -->|Erro de Código: Sev 1 ou Sev 2| SUST_FLOW[Abre Issue: Roteia para Sustentação - Kanban]
        Q_TIPO -->|Erro de Código: Sev 3 ou Sev 4| EVO_FLOW[Abre Issue: Roteia para Backlog Evolução - Scrum]
    end

    RET_N2 --> N2_VALID[N2 Homologa em Produção / Homologação]
    N2_VALID --> N1_END[N1 comunica o usuário e encerra o chamado]

1.1. Níveis de Atendimento e Responsabilidades

2. Definition of Ready (DoR) de Entrada no N3 & Política de Devolução

Para assegurar que o Suporte N3 dedique seu tempo à investigação aprofundada e não à cobrança de dados elementares, foi estabelecido o Definition of Ready (DoR) obrigatório para todo chamado encaminhado pelo N2.

2.1. Os 5 Critérios Mandatórios do DoR

Todo ticket transferido para o Suporte N3 deve conter, sem exceção, os seguintes cinco elementos devidamente preenchidos:

1. Identificação Completa do Solicitante e Ambiente:
   • Unidade Federativa (UF), Município, Nome e Código CNES do Estabelecimento de Saúde.
   • Perfil de Acesso do usuário que encontrou o problema (ex.: Operador de Farmácia, Farmacêutico Responsável, Gestor Municipal).
   • Versão do sistema e ambiente em que o problema foi observado (Produção, Treinamento ou Homologação).
2. Passo a Passo Preciso de Reprodução:
   • Sequência cronológica e exata de telas, menus, abas e botões clicados.
   • Campos preenchidos e valores informados durante o fluxo que desencadeou a falha.
3. Massa de Dados e Identificadores Únicos:
   • Identificadores reais dos registros envolvidos: Número da Dispensação, CNS/CPF do Usuário/Paciente, Código/Lote do Medicamento, Número da Entrada/Nota Fiscal, etc.
4. Evidências Visuais e Temporais:
   • Capturas de tela (screenshots) ou gravações de tela em alta resolução.
   • Obrigatório: A captura deve exibir a barra de endereços com a URL completa e a data/hora do sistema operacional no momento da ocorrência.
5. Comprovação Técnica do Erro:
   • Código de status HTTP (ex.: 500 Internal Server Error, 400 Bad Request, 403 Forbidden).
   • Mensagem de erro exibida na interface ou capturada na aba Network / Console das Ferramentas de Desenvolvedor (F12) do navegador.

+--------------------------------------------------------------------------------------------------+
|                             CHECKLIST DO DoR DE ENTRADA NO SUPORTE N3                           |
+---+-------------------------------------------+--------------------------------------------------+
| # | Critério Obrigatório                      | Detalhe Esperado                                 |
+---+-------------------------------------------+--------------------------------------------------+
| 1 | Identificação do Solicitante e Ambiente   | UF, Município, CNES, Perfil, Versão do e-SUS AF  |
| 2 | Passo a Passo de Reprodução               | Sequência linear de ações até o erro             |
| 3 | Massa de Dados & Identificadores          | IDs, CNS, Lote, Dispensação, etc.                |
| 4 | Evidências Visuais com URL e Data/Hora    | Prints/Vídeos legíveis com URL visível           |
| 5 | Comprovação Técnica do Erro               | Código HTTP, Exception ou Resposta de API        |
+---+-------------------------------------------+--------------------------------------------------+

2.2. Política de Devolução de Tickets Incompletos

• Ação Imediata: O ticket é devolvido ao N2 na ferramenta de chamados com o status "Aguardando Informações do N2".
• Suspensão de SLA: A contagem do tempo de atendimento (SLA do N3) é imediatamente pausada (Clock Stop) no momento da devolução.
• Justificativa Padronizada: O analista do N3 deve registrar no chamado uma nota técnica apontando especificamente quais critérios do DoR não foram atendidos e quais informações adicionais são necessárias para viabilizar a análise.
• Retomada da Contagem: O SLA do N3 volta a contar apenas quando o N2 reenviar o chamado com todas as pendências sanadas.
• Meta de Qualidade: A Taxa de Devolução para o N2 é monitorada mensalmente e deve permanecer abaixo de 10%, indicando a eficácia da triagem funcional do N2.

3. Procedimento Seguro de Scripts de Banco de Dados

Intervenções diretas em banco de dados em ambiente de produção representam alto risco operacional e de integridade dos dados de saúde pública. O Suporte N3 deve seguir estritamente o protocolo em 5 etapas para elaboração, teste, aprovação e execução de scripts corretivos de dados.

flowchart LR
    E1["1. Diagnóstico & Análise de Logs"] --> E2["2. Construção do Script Transacional"]
    E2 --> E3["3. Validação em Homologação"]
    E3 --> E4["4. Revisão & Aprovação Técnica"]
    E4 --> E5["5. Execução em Produção & Pós-Validação"]

3.1. As 5 Etapas do Procedimento Seguro

Etapa 1: Diagnóstico e Análise de Logs

• O N3 identifica a causa da inconsistência correlacionando os logs da aplicação com consultas SQL de leitura (SELECT) realizadas em banco de leitura/réplica.
• O N3 mapeia todas as tabelas e chaves estrangeiras impactadas pelo problema.

Etapa 2: Construção do Script Transacional Padronizado

• Transacionalidade Obrigatória: Todo script deve rodar dentro de um bloco transacional explícito (BEGIN TRANSACTION, COMMIT ou ROLLBACK).
• Verificação de Impacto (ROWCOUNT): O script deve validar a quantidade de linhas que serão afetadas antes de efetivar as alterações. Se a contagem divergir do esperado, o script deve abortar via ROLLBACK.
• Idempotência e Segurança: Scripts devem conter cláusulas WHERE estritas utilizando chaves primárias ou identificadores únicos inquestionáveis.
• Cabeçalho Obrigatório: Todo arquivo SQL deve conter cabeçalho com número do chamado, autor, data, descrição do objetivo e hash de validação.

Etapa 3: Validação Prévia em Homologação / Staging

• Proibição Absoluta: É expressamente proibido executar em produção qualquer script que não tenha sido executado e homologado previamente em ambiente de Homologação ou base espelho sanitizada.
• O N3 valida se o script corrigiu o estado da entidade sem quebrar constraints de integridade referencial, triggers ou regras de auditoria.

Etapa 4: Revisão e Aprovação Técnica

• O script SQL e o relatório de validação em homologação são submetidos para aprovação formal do Líder Técnico (Tech Lead) ou do responsável de banco de dados (DBA).
• O parecer de aprovação deve ser registrado e anexado ao chamado técnico.

Etapa 5: Execução em Produção e Pós-Validação Funcional

• A execução em produção é realizada em janela operacional apropriada.
• Imediatamente após a execução, o N3 executa scripts de conferência (SELECT) para certificar o estado final dos dados.
• O chamado é devolvido ao N2 com os dados de comprovação para que o usuário/município valide o sucesso da operação na interface.

3.2. Exemplo Prático de Script SQL Transacional Seguro

Abaixo está o modelo padronizado de script SQL transacional adotado pelo e-SUS AF:

-- ============================================================================
-- PROJETO: e-SUS Assistência Farmacêutica (e-SUS AF)
-- CHAMADO / ISSUE: #14285 - Correção de status travado em dispensação
-- AUTOR: Suporte N3 (Analista de Diagnóstico)
-- DATA CRIAÇÃO: 2026-08-23
-- AMBIENTE DE VALIDAÇÃO: Homologação (Validado com sucesso em 2026-08-23 14:30)
-- APROVADOR TÉCNICO: Tech Lead e-SUS AF
-- OBJETIVO: Atualizar status da dispensação ID 98452 de 'PROCESSANDO' para 'FINALIZADA'
--           devido a timeout de confirmação na integração local.
-- ============================================================================

DO $$
DECLARE
    v_cnes_alvo VARCHAR := '2458963';
    v_dispensacao_id BIGINT := 98452;
    v_linhas_afetadas INT := 0;
    v_status_atual VARCHAR;
BEGIN
    -- 1. Verificação prévia do estado atual do registro
    SELECT status_dispensacao 
      INTO v_status_atual
      FROM tb_dispensacao
     WHERE id_dispensacao = v_dispensacao_id
       AND codigo_cnes = v_cnes_alvo;

    IF v_status_atual IS NULL THEN
        RAISE EXCEPTION 'Registro não encontrado para o CNES % e Dispensação ID %.', v_cnes_alvo, v_dispensacao_id;
    END IF;

    IF v_status_atual <> 'PROCESSANDO' THEN
        RAISE EXCEPTION 'Status inesperado: %. Esperado: PROCESSANDO. Operação cancelada.', v_status_atual;
    END IF;

    -- 2. Execução da atualização com filtro estrito
    UPDATE tb_dispensacao
       SET status_dispensacao = 'FINALIZADA',
           dt_atualizacao = NOW(),
           ds_justificativa_ajuste = 'Ajuste operacional via Chamado #14285'
     WHERE id_dispensacao = v_dispensacao_id
       AND codigo_cnes = v_cnes_alvo
       AND status_dispensacao = 'PROCESSANDO';

    GET DIAGNOSTICS v_linhas_afetadas = ROW_COUNT;

    -- 3. Validação de integridade do volume de linhas afetadas
    IF v_linhas_afetadas <> 1 THEN
        RAISE EXCEPTION 'Falha de integridade: % linhas afetadas. Esperado exatamente 1 linha. Executando ROLLBACK.', v_linhas_afetadas;
    END IF;

    -- 4. Registro de log de auditoria operacional
    INSERT INTO tb_auditoria_operacional (
        id_registro_afetado, 
        nm_tabela, 
        ds_operacao, 
        nm_operador, 
        dt_operacao, 
        ds_motivo
    ) VALUES (
        v_dispensacao_id, 
        'tb_dispensacao', 
        'UPDATE_STATUS', 
        'SUPORTE_N3', 
        NOW(), 
        'Chamado #14285 - Correção de trava de timeout'
    );

    RAISE NOTICE 'Script executado com sucesso. 1 registro atualizado e auditoria registrada.';
END $$;

-- Em execução interativa com transação explícita:
-- BEGIN;
-- [Executa bloco acima]
-- COMMIT; -- ou ROLLBACK se houver qualquer divergência

3.3. Diretrizes Críticas de Segurança de Dados

4. Encaminhamento para Engenharia & Templates Padronizados de Issues

Quando a investigação técnica do Suporte N3 conclui que a resolução do problema exige modificação no código-fonte da aplicação (correção de algoritmo, ajuste de validação de frontend, tratamento de exception no backend, alteração de DDL via migração controlada), o N3 deve formalizar a abertura de uma Issue Técnica.

4.1. Regra de Roteamento por Severidade

flowchart TD
    N3_DIAG[Diagnóstico Técnico N3: Necessária Alteração de Código] --> CLASS{Classificação de Severidade}

    CLASS -->|Sev 1: Incidente Crítico / Bloqueio Total| SUST[Encaminha para SUSTENTAÇÃO - Kanban]
    CLASS -->|Sev 2: Defeito Grave sem Workaround| SUST
    CLASS -->|Sev 3: Defeito Médio com Workaround| EVO[Encaminha para BACKLOG DA EVOLUÇÃO - Scrum]
    CLASS -->|Sev 4: Defeito Baixo / Visual / Débito Técnico| EVO

    SUST --> SUST_KANBAN[Entra na Fila Prioritária da Sustentação]
    EVO --> EVO_BACKLOG[Entra no Backlog de Refinamento do PO]

• Sustentação (Fluxo Contínuo Kanban):
  • Sev 1 (Incidente Crítico): Indisponibilidade geral do sistema, perda iminente de dados de saúde, paralisação total de dispensação em municípios ou falha de autenticação geral.
  • Sev 2 (Defeito Grave): Funcionalidade principal inoperante sem solução de contorno (workaround), erro HTTP 500 recorrente em operações de rotina.
• Evolução (Release Train Scrum - 2+1):
  • Sev 3 (Defeito Médio): Falha em fluxo secundário, mensagem de erro confusa com contorno viável para o usuário.
  • Sev 4 (Defeito Baixo / Cosmético): Erro de alinhamento visual, inconsistência de texto, formatação de relatório sem perda de informação.

4.2. Template Padronizado: [Sustentação - Sev 1/2]

Este template deve ser utilizado exclusivamente para bugs críticos e graves direcionados à célula de Sustentação:

## [Sustentação] <Título Conciso do Incidente / Defeito>

**Severidade:** [Sev 1 - Crítico | Sev 2 - Grave]
**Módulo Afetado:** [ex.: Dispensação / Movimentação de Estoque / Integração RNDS / Autenticação]
**Chamado N2 de Origem:** [#14320]
**Impacto Operacional:** [Descrever quem e quantos municípios/estabelecimentos estão impactados]

---

### 1. Descrição do Problema
[Descrição clara e objetiva do comportamento incorreto em produção]

### 2. Passo a Passo de Reprodução
1. Acessar o módulo `[Nome do Módulo]` > `[Submenu]`;
2. Informar os dados de teste: CNES `[1234567]`, Paciente CNS `[7000...]`;
3. Clicar no botão `[Confirmar Dispensação]`;
4. Observar o travamento e a mensagem de erro HTTP 500.

### 3. Evidências Técnicas
* **URL:** `https://esusaf.saude.gov.br/farmacia/dispensacao/confirmar`
* **Código HTTP:** `500 Internal Server Error`
* **Trecho do Stack Trace / Exception:**
```text
java.lang.NullPointerException: Cannot invoke "br.gov.saude.esus.model.Lote.getQuantidadeDisponivel()" because "lote" is null
    at br.gov.saude.esus.service.DispensacaoService.validarSaldoEstoque(DispensacaoService.java:142)
    at br.gov.saude.esus.service.DispensacaoService.executarDispensacao(DispensacaoService.java:88)

{
  "idEstabelecimento": 2458963,
  "idMedicamento": 1024,
  "idLote": null,
  "quantidade": 30
}

4. Hipótese Diagnóstica do Suporte N3

• Arquivo / Classe Suspeita: DispensacaoService.java (linha 142) e dispensacao-form.component.ts.
• Causa Provável: O frontend permite submeter a dispensação de medicamento sem selecionar explicitamente o lote quando há apenas 1 lote cadastrado, enviando idLote: null, o que causa NPE no backend ao tentar recuperar a quantidade disponível.
• Solução Técnica Sugerida: Adicionar validação no backend para exigir idLote não nulo e ajustar o auto-select do lote único no frontend.

5. Dados de Contato e Homologação

• Analista N3 Responsável: [Nome do Integrante N3]
• Ambiente de Reprodução Confirmada: Homologação v2.4.1

  ---
  
  ### 4.3. Template Padronizado: `[Bug-Backlog - Sev 3/4]`
  
  Este template deve ser utilizado para defeitos não emergenciais encaminhados ao Product Owner para priorização na esteira de Evolução:
  
  ```markdown
  ## [Bug-Backlog] <Título do Defeito / Inconsistência>
  
  **Severidade:** [Sev 3 - Médio | Sev 4 - Baixo]
  **Módulo Afetado:** [ex.: Relatórios / Cadastros Básicos / Configurações]
  **Chamado N2 de Origem:** [#14110]
  **Existe Solução de Contorno (Workaround)?** [Sim | Não]
  
  ---
  
  ### 1. Comportamento Atual
  [Descrever o que o sistema está fazendo incorretamente]
  
  ### 2. Comportamento Esperado
  [Descrever o que o sistema deveria fazer de acordo com a regra de negócio]
  
  ### 3. Solução de Contorno (*Workaround*)
  [Descrever como o usuário pode contornar a limitação até que a correção definitiva seja lançada, ex.: "O usuário pode exportar o relatório em formato CSV e aplicar o filtro manualmente no Excel."]
  
  ### 4. Passo a Passo de Reprodução
  1. Acessar o menu `Relatórios` > `Posição de Estoque`;
  2. Selecionar o filtro de data inicial `01/08/2026` e final `15/08/2026`;
  3. Marcar a opção `Exportar PDF`;
  4. O arquivo gerado apresenta desformatação na coluna de lote quando o nome do medicamento ultrapassa 40 caracteres.
  
  ### 5. Evidências Anexadas
  * Screenshots do erro de layout em anexo.
  * Logs funcionais sem erros no backend (apenas inconsistência de CSS/JasperReports).
  
  ### 6. Sugestão Técnica do N3
  * Ajustar quebra de linha automática na tabela do template JasperReports `relatorio_posicao_estoque.jrxml`.
  

5. Tabela de SLAs Operacionais do Suporte N3 & Indicadores

Para garantir a previsibilidade e a excelência no atendimento às demandas que chegam ao Suporte N3, aplicam-se os seguintes Acordos de Nível de Serviço (Service Level Agreements - SLAs):

5.1. Matriz de SLAs do Suporte N3

Horário de Atendimento Padrão do Suporte N3:
Segunda a Sexta-feira, das 08:00 às 18:00 (Dias Úteis, Horário de Brasília).

5.2. Regras e Condições de Suspensão de SLA (Clock Stop)

A contagem de tempo do SLA do Suporte N3 é suspensa nas seguintes situações formais:

1. Aguardando Informações do N2: O chamado foi devolvido por não atender ao DoR de entrada.
2. Aguardando Aprovação Técnica de Script: O script está em análise pelo Líder Técnico / DBA.
3. Aguardando Validação do Solicitante / Município: O script foi aplicado em homologação/produção e o chamado aguarda confirmação final de sucesso pelo N2/usuário.
4. Encaminhado para Engenharia: Uma vez que a issue foi criada e aceita pela Sustentação ou Evolução, o SLA do N3 é finalizado com sucesso, iniciando o SLA/ciclo da respectiva esteira de desenvolvimento.

5.3. Painel de Indicadores de Desempenho do Suporte N3

O desempenho operacional do time de Suporte N3 é acompanhado quinzenalmente através dos seguintes indicadores-chave: