snglpi/docs/RODAMP.MD

Roadmap de Evolucao - SN <-> GLPI

Visao Geral

Objetivo: elevar confiabilidade, observabilidade e arquitetura da integracao sem interromper operacao.

Principios:

• migracao incremental (sem Big Bang)
• manter compatibilidade com fluxo atual
• cada fase precisa ter criterio claro de aceite

Fases (ordem recomendada)

Fase 0 - Baseline e seguranca operacional (1 semana)

Objetivo: criar base para evolucao segura.

Entregas:

• checklist oficial de deploy/rollback em producao
• backup e restore testado para banco intermediario
• playbook de incidentes (falha SN, falha GLPI, falha DB)
• padrao de versionamento e convencao de commits

Criterios de aceite:

• rollback executado com sucesso em ambiente de teste
• documentacao revisada e aprovada

Risco: baixo

---

Fase 1 - Logs estruturados e rastreabilidade (1-2 semanas)

Objetivo: saber exatamente onde e por que falhou.

Entregas:

• padrao de log com contexto por camada e direcao:
  • [USECASE][GLPI>SN]
  • [USECASE][SN>GLPI]
  • [SERVICE], [REPOSITORY], [INTEGRATION]
• correlation_id por ciclo e por ticket
• campos padrao nos logs: ticket_number, sn_ticket_id, glpi_ticket_id, source_last, step
• metricas minimas por ciclo: processados, sucesso, erro, duracao

Criterios de aceite:

• conseguir rastrear 1 ticket de ponta a ponta por correlation_id
• reduzir tempo de diagnostico de erro em pelo menos 50%

Risco: baixo

---

Fase 2 - Estabilizacao final de fluxos (1 semana)

Objetivo: fechar lacunas de negocio antes de refatoracao pesada.

Entregas:

• bateria manual oficial para incidente e requisicao
• validacao de regras finais:
  • resolucao GLPI -> SN
  • reabertura SN -> GLPI
  • fechamento permanente GLPI nao reabre
  • fora de escopo nao reabre
• hardening de idempotencia em comentarios/tarefas

Criterios de aceite:

• 100% do checklist de fluxos principais aprovado em DEV

Risco: baixo

---

Fase 3 - Modularizacao progressiva (monolito modular, estilo clean) (3-5 semanas)

Objetivo: organizar o sistema em modulos com fronteiras claras.

Entregas:

• estrutura em camadas:
  • domain (regras e entidades)
  • application (casos de uso)
  • infrastructure (DB, APIs, logger)
  • interfaces (cron/controllers)
• definicao de portas/adapters para SN, GLPI e repositorios
• migracao por vertical (ticket -> comment -> status)

Criterios de aceite:

• novos casos de uso entram sem acoplar controller direto a SQL/API
• arquitetura documentada em diagrama simples

Risco: medio

---

Fase 4 - GLPI via API (2-4 semanas)

Objetivo: reduzir dependencia de escrita direta no banco GLPI.

Entregas:

• cliente GLPI API para:
  • criar ticket
  • inserir comentario
  • inserir tarefa
  • atualizar status
• fallback controlado para SQL apenas enquanto necessario
• comparativo de comportamento API x SQL em DEV

Criterios de aceite:

• ao menos 1 fluxo completo operando via API com sucesso
• sem regressao de regras de negocio

Risco: medio

---

Fase 5 - Sincronizacao de imagens/anexos (3-6 semanas)

Objetivo: suportar anexos dos dois lados.

Entregas:

• modelagem de rastreio de anexos (source_id, destiny_id, hash, status)
• pipeline SN -> GLPI e GLPI -> SN:
  • listar anexos
  • baixar binario
  • validar tipo/tamanho
  • upload no destino
• deduplicacao por hash
• retries com backoff

Criterios de aceite:

• anexos de teste sobem nos dois sentidos com rastreabilidade
• sem duplicacao de anexos no reprocessamento

Risco: alto

---

Fase 6 - Qualidade e teste automatizado (2-4 semanas, em paralelo)

Objetivo: diminuir risco de regressao.

Entregas:

• testes unitarios de mapeamento/status/regras
• testes de integracao com mocks de SN e GLPI
• smoke test automatizado por ciclo

Criterios de aceite:

• cobertura minima em regras criticas
• pipeline bloqueando merge em caso de regressao

Risco: medio

Backlog Tecnico (prioridade)

P1:

• logs estruturados + correlation_id
• checklist oficial de deploy/rollback
• bateria de testes de requisicao

P2:

• modularizacao por casos de uso
• GLPI API para comentarios/tarefas

P3:

• anexos/imagens bidirecional
• observabilidade avancada (dashboards/alertas)

Definicao de Pronto (DoD) por fase

• codigo revisado
• documentacao atualizada
• evidencias de teste anexadas
• plano de rollback definido

Observacao

Este roadmap prioriza estabilidade de operacao antes de expansao funcional. A transicao para arquitetura modular deve ser gradual e guiada por casos de uso reais.