Manual Operacional da Sustentação & Gestão de Incidentes

1. Fluxo Contínuo Kanban da Sustentação

Diferente da frente de Evolução, que opera sob ciclos planejados de Release Train (Scrum 2+1), a Sustentação atua em regime de fluxo contínuo puxado (Kanban). Esse desacoplamento protege o time de desenvolvimento de interrupções diárias e assegura que os incidentes de produção recebam tratamento técnico imediato sem a rigidez de cerimônias de sprint.

flowchart TD
    IN[1. Entrada de Demanda: Issue Técnica do Suporte N3] --> TRIAG{2. Classificação de Severidade}

    TRIAG -->|Sev 1: Incidente Crítico / Bloqueio Total| HOT_FLOW[Gatilho de Hotfix Imediato - Fura-Fila]
    TRIAG -->|Sev 2: Defeito Grave sem Workaround| KANBAN_TOP[Entrada no Topo do Backlog Kanban]

    subgraph Esteira_Kanban["Esteira de Execução da Sustentação (WIP Rigorosamente Controlado)"]
        KANBAN_TOP --> COL_ANALISE[3. Análise & Diagnóstico Técnico]
        HOT_FLOW --> COL_DEV[4. Desenvolvimento da Correção Cirúrgica]
        COL_ANALISE --> COL_DEV

        COL_DEV --> COL_TEST[5. Criação de Teste Automatizado de Regressão]
        COL_TEST --> COL_CR[6. Code Review Obrigatório - Tech Lead / Sênior]
        COL_CR --> COL_QA[7. Validação Técnica & Homologação em Staging]
    end

    COL_QA --> AUTH{8. Aprovação Formal Técnica e Negocial?}
    AUTH -->|Reprovado| COL_DEV
    AUTH -->|Aprovado| MERGE_MAIN[9. Merge na main com Tag Patch vX.Y.Z+1 & Deploy]

    MERGE_MAIN --> SYNC_CHECK{10. Existe branch release/* ativa?}
    SYNC_CHECK -->|Sim| DO_SYNC[11. Sincronização OneFlow: Cherry-Pick na release/*]
    SYNC_CHECK -->|Não| FINAL_NOTIF[12. Atualização da Issue e Notificação ao N2/N1]
    DO_SYNC --> FINAL_NOTIF
    FINAL_NOTIF --> FIM([Incidente Encerrado em Produção])

1.1. Etapas do Ciclo de Vida da Demanda

1. Entrada e Triagem: A demanda chega exclusivamente via issue técnica formalizada pelo Suporte N3, já acompanhada de logs, passos de reprodução, identificadores de dados e hipótese diagnóstica.
2. Priorização e Roteamento:
   • Sev 1: Entra imediatamente em execução como Hotfix Emergencial, ignorando a fila regular.
   • Sev 2: É posicionada no topo da coluna de Backlog da Sustentação, sendo puxada para atendimento conforme a liberação de WIP nas etapas seguintes.
3. Análise e Diagnóstico Detalhado: O desenvolvedor responsável reproduz a falha localmente, isola a causa raiz e elabora a proposta de intervenção de menor impacto arquitetural.
4. Correção Cirúrgica: O código é alterado de forma estrita, restringindo-se exclusivamente ao reparo do defeito mapeado, sem refatorações amplas ou cosméticas.
5. Teste Automatizado de Regressão: Construção obrigatória de teste unitário, de integração ou ponta a ponta (E2E) que comprove a falha antes do patch e garanta o sucesso após a aplicação.
6. Code Review: O Pull Request (PR) é inspecionado por no mínimo um desenvolvedor sênior ou pelo Líder Técnico, avaliando potenciais efeitos colaterais e segurança.
7. Validação em Staging (Homologação): O pacote de correção é publicado em ambiente espelho de produção (Staging) para validação técnica pelo QA e validação funcional pelo Suporte N2 ou PO.
8. Aprovação e Autorização: O Líder Técnico emite a aprovação técnica e o PO valida a liberação do pacote.
9. Publicação (Merge na main): O PR é integrado à branch main gerando a tag semântica de patch (vX.Y.Z+1) e disparando o pipeline automatizado de deploy.
10. Sincronização OneFlow: Se houver uma branch de release em andamento (release/vX.Y.0), o commit de correção é propagado imediatamente via cherry-pick.
11. Comunicação de Encerramento: A issue é documentada com notas técnicas de release e devolvida ao Suporte N2 para encerramento do chamado junto ao município.

2. Matriz de Severidades e Políticas de Atendimento

A categorização correta da severidade orienta a velocidade de resposta, a estratégia de ramificação no Git e a esteira de publicação aplicável:

3. Políticas do Quadro Kanban e Limites de WIP

O quadro Kanban da sustentação é gerenciado com o objetivo de minimizar o Lead Time (tempo total desde a entrada da issue até a publicação em produção) e maximizar o Throughput de correções de qualidade.

3.1. Visão Estrutural do Quadro Kanban

+-------------------+-------------------+-------------------+-------------------+-------------------+-------------------+
| Backlog Sust.     | Em Análise        | Em Correção       | Code Review       | Validação / QA    | Pronto / Deploy   |
| (WIP: 5)          | (WIP: 2)          | (WIP: 2)          | (WIP: 2)          | (WIP: 2)          | (Sem Limite)      |
+-------------------+-------------------+-------------------+-------------------+-------------------+-------------------+
| [Sev 2] Issue #14 | [Sev 2] Issue #12 | [Sev 1] Hotfix #13| [Sev 2] Issue #10 | [Sev 2] Issue #08 | Tag v2.4.1 (Prod) |
| [Sev 2] Issue #15 | [Sev 2] Issue #11 |                   | [Sev 2] Issue #09 |                   | Tag v2.4.0 (Prod) |
| [Sev 2] Issue #16 |                   |                   |                   |                   |                   |
+-------------------+-------------------+-------------------+-------------------+-------------------+-------------------+

3.2. Políticas Explícitas e Regras de Transição por Coluna

3.3. Gestão de Gargalos e Protocolo "Pare a Linha" (Stop the Line)

• Ação Mandatória: O desenvolvedor ocioso ou que acabou de finalizar uma correção deve atuar diretamente na coluna onde o fluxo está represado:
  • Se o gargalo estiver em Code Review, realiza a revisão imediata dos PRs pendentes;
  • Se o gargalo estiver em Validação / QA, apoia na execução de testes em Staging ou na preparação de massa de dados;
• Benefício: Essa disciplina elimina o acúmulo de código pronto não validado, reduz drasticamente o tempo de entrega de correções aos municípios e evita merges conflitantes acumulados.

4. Ciclo de Vida do Hotfix Emergencial (Sev 1)

O procedimento de Hotfix Emergencial é reservado exclusivamente para incidentes de severidade Sev 1. Ele estabelece uma esteira ultrarrápida e segura para restaurar a operação sem violar os padrões de qualidade e integridade do repositório.

flowchart TD
    GAT["1. Incidente Sev 1 Detectado (N3 / Monitoramento)"] --> ALERTA["2. Alerta Imediato ao Tech Lead e PO"]
    ALERTA --> AUTORIZA{"3. Autorização Conjunta de Hotfix?"}

    AUTORIZA -->|Não: Classificado como Sev 2/3| KANBAN_FLOW[Direciona para Fila Kanban Regular]
    AUTORIZA -->|Sim: Aprovado| RAMIFICA["4. Ramificação da Tag de Produção na main:
git checkout vX.Y.Z
git checkout -b hotfix/issue-slug"]

    RAMIFICA --> FIX_DEV["5. Implementação Cirúrgica do Fix"]
    FIX_DEV --> AUTO_TEST["6. Escrita Obrigatória de Teste Automatizado de Regressão"]

    AUTO_TEST --> FAST_CR["7. Code Review Expresso (Tech Lead / Sênior)"]
    FAST_CR --> STAGING_VAL["8. Deploy em Staging & Validação QA / N2"]

    STAGING_VAL --> MERGE_FAST["9. Merge Fast-Track na main (--no-ff)"]
    MERGE_FAST --> TAG_PATCH["10. Criação de Tag Semântica vX.Y.Z+1"]
    TAG_PATCH --> DEPLOY_PROD["11. Deploy Automatizado em Produção"]

    DEPLOY_PROD --> CHERRY_PICK["12. Sincronização OneFlow Obrigatória (Cherry-Pick na release/*)"]
    CHERRY_PICK --> FECHA_ISSUE["13. Fechamento do Incidente & Relatório Pós-Morte"]

4.1. Passo a Passo Operacional do Hotfix

1. Gatilho e Autorização Conjunta

• A constatação de um incidente Sev 1 dispara alerta no canal de emergência da equipe.
• O Líder Técnico (avaliação de risco e arquitetura) e o Product Owner (avaliação de impacto operacional e autorização negocial) formalizam o início da esteira emergencial.

2. Ramificação a partir da Tag de Produção

O hotfix NUNCA é ramificado a partir da ponta (HEAD) da branch main, pois a main pode conter commits de outras features recém-integradas que ainda não foram homologadas. A branch deve nascer estritamente da tag da versão atualmente em produção:

# 1. Garantir que o repositório local possui todas as tags atualizadas
git checkout main
git pull origin main --tags

# 2. Criar a branch de hotfix a partir da tag de produção ativa (ex.: v2.4.0)
git checkout v2.4.0
git checkout -b hotfix/14350-bloqueio-login-govbr

3. Implementação Cirúrgica e Teste Automatizado Mandatório

• A modificação deve ser estritamente focal, corrigindo apenas a causa raiz do incidente.
• É obrigatória a adição de um teste automatizado (unitário, integração ou E2E) que reproduza a falha e certifique a eficácia do fix:

# Executa commits com mensagens semânticas
git commit -m "fix(auth): corrige validacao de token expirado no login Gov.br"
git commit -m "test(auth): adiciona teste de regressao para sessao expirada"

4. Validação em Staging e Code Review Expresso

• O PR é aberto apontando para a branch main.
• O pipeline de CI executa a suite de testes automatizados e gera o artefato de Staging.
• O Líder Técnico realiza a revisão técnica expressa e o QA valida a correção em ambiente de homologação espelho.

5. Merge, Tag Semântica e Publicação

Após a aprovação formal, o merge é realizado preservando o histórico de ramificação (--no-ff), seguido da criação da tag de patch:

# Merge na main e publicação da tag patch
git checkout main
git pull origin main
git merge --no-ff hotfix/14350-bloqueio-login-govbr -m "fix(hotfix): merge hotfix v2.4.1 (#14350)"
git tag -a v2.4.1 -m "Hotfix emergencial v2.4.1 - Correcao de autenticacao Gov.br"
git push origin main --tags

# Exclusão da branch temporária de hotfix
git branch -d hotfix/14350-bloqueio-login-govbr
git push origin --delete hotfix/14350-bloqueio-login-govbr

5. Sincronização OneFlow Obrigatória (Anti-Regressão)

No modelo de ramificação OneFlow, a branch main é a única branch perpétua. Quando um hotfix é aplicado e publicado na main, surge um ponto crítico de governança se houver uma branch de release temporária (release/vX.Y.0) em andamento durante a Sprint de Estabilização.

5.1. O Risco de Regressão Silenciosa

        (Produção v2.4.0)
               o------------------[Hotfix v2.4.1]-------------------> main (v2.4.1)
                \                                                        ^
                 \                                                       | (Merge Final v2.5.0)
                  \-----[Features S1/S2]-----> release/v2.5.0 ---------->| [PERIGO: Sobrescreve o fix!]
                                               (Sem o Hotfix!)

Se a branch release/v2.5.0 foi criada antes do hotfix e não for atualizada, no momento em que ela for mergeada de volta na main ao término da estabilização, o bug corrigido no hotfix poderá ser reintroduzido em produção na versão v2.5.0, configurando uma regressão catastrófica.

5.2. Procedimento Operacional de Cherry-Pick

Sempre que um hotfix for integrado na main, o desenvolvedor responsável pela sustentação deve executar imediatamente o procedimento de sincronização:

flowchart TD
    HF_MERGED["Hotfix integrado na main (Tag v2.4.1)"] --> CHECK_REL{"Existe branch release/* ativa em homologação?"}

    CHECK_REL -->|Não| SYNC_OK["Sincronização desnecessária: main é a única base"]
    CHECK_REL -->|Sim: ex.: release/v2.5.0| PULL_REL["1. Atualiza repositório local com a branch de release:
git checkout release/v2.5.0
git pull origin release/v2.5.0"]

    PULL_REL --> CHERRY_CMD["2. Aplica o commit do hotfix:
git cherry-pick <HASH_COMMIT_HOTFIX>"]
    CHERRY_CMD --> CONF_TEST{"Ocorreu conflito de merge?"}

    CONF_TEST -->|Sim| RESOLV["3. Desenvolvedor resolve conflito com apoio do Tech Lead
git add . && git cherry-pick --continue"]
    CONF_TEST -->|Não| PUSH_REL["4. Envia alteração sincronizada:
git push origin release/v2.5.0"]
    RESOLV --> PUSH_REL

    PUSH_REL --> QA_ALERT["5. Notifica QA para revalidação do teste de regressão na release"]

Comandos Git de Sincronização:

# 1. Obter o hash do commit de correção na main
git log -n 5 --oneline main

# 2. Alternar para a branch de release ativa e atualizar
git checkout release/v2.5.0
git pull origin release/v2.5.0

# 3. Executar o cherry-pick do commit específico do hotfix
git cherry-pick a1b2c3d4

# 4. Em caso de conflito, resolver os arquivos, adicionar e continuar:
# git status
# git add <arquivos-resolvidos>
# git cherry-pick --continue

# 5. Enviar a branch de release atualizada para o repositório remoto
git push origin release/v2.5.0

6. Definition of Done (DoD) da Sustentação

Um item de Sustentação ou Hotfix é considerado formalmente concluído e entregue somente quando atender a todos os 7 critérios do checklist abaixo:

### Checklist do Definition of Done (DoD) da Sustentação

- [ ] **1. Correção Cirúrgica e Segura**: O código alterado restringe-se pontualmente à correção da falha descrita na issue, sem inclusão de refatorações ou modificações cosméticas acessórias.
- [ ] **2. Teste Automatizado de Regressão Obrigatório**: Adicionado teste automatizado (unitário, integração e/ou E2E) que reproduz o cenário da falha e valida o funcionamento correto pós-correção.
- [ ] **3. Code Review Técnico Aprovado**: PR inspecionado e aprovado por no mínimo 1 desenvolvedor sênior ou pelo Líder Técnico, com pipeline de CI 100% verde.
- [ ] **4. Validação em Ambiente de Staging**: Correção validada e homologada tecnicamente pelo QA e/ou Suporte N2 em ambiente espelho de produção.
- [ ] **5. Merge na `main` com Tag Semântica**: Merge realizado na branch `main` via PR com parâmetro `--no-ff` e gerada a respectiva tag de patch (`vX.Y.Z+1`).
- [ ] **6. Sincronização OneFlow Efetuada**: Se houver branch `release/*` em aberto, o commit foi replicado via `git cherry-pick` e os testes de regressão foram confirmados na release.
- [ ] **7. Documentação e Notificação de Encerramento**: Release Notes atualizados, issue devidamente documentada com a causa raiz e chamado devolvido ao Suporte N2 para comunicação ao usuário.

7. Acordos de Nível de Serviço (SLA) & Métricas da Sustentação

A operação de sustentação é monitorada continuamente por indicadores de produtividade, agilidade e qualidade de engenharia:

7.1. Tabela de SLAs da Sustentação

7.2. Painel de Indicadores de Qualidade