sar-android/_bmad-output/implementation-artifacts/epic-2-retro-2026-04-16.md

Retrospectiva — Epic 2: Acréscimo Financeiro no Pedido

Data: 2026-04-16 Projeto: SARandroid Epic: 2 — Acréscimo Financeiro no Pedido Facilitador: Julio (Project Lead) Primeiro retro do projeto — sem retrospectiva anterior para comparar follow-through.

---

1. Resumo do Epic

Métrica	Valor
Stories planejadas	4
Stories concluídas	4 (100%)
FRs cobertos	FR5–FR13 (9 requisitos funcionais)
Code reviews aprovados	4/4
Migrações SQLite	v41→v42 (story 2.3), v42→v43 (story 2.4)
Arquivos de código alterados	6 únicos (DatabaseHelper, PedidoDB, PedidoConsultaDB, Pedido VO, MainPedidoFragment, TotalPedidoFragment)
Incidentes em produção	0 (feature ainda não publicada)
Débitos técnicos formalmente deferred	19 itens acumulados em deferred-work.md

Stories entregues

• 2.1 Exibir campo Acréscimo na tela do pedido (sempre R$ 0,00)
• 2.2 Calcular acréscimo ao selecionar forma de pagamento
• 2.3 Persistir acréscimo ao fechar o pedido
• 2.4 Exibir acréscimo na consulta de pedidos

---

2. O Que Foi Bem

• Padrão de migração SQLite robusto: cada story de migração (1.1, 2.3, 2.4) atualizou dbVersao + bloco onUpgrade + onCreate simultaneamente. Esse padrão triplo evitou a regressão clássica "instalação nova crasha porque só o upgrade foi atualizado" — explicitamente documentado em Story 2.4.
• Escopo por story bem isolado: cada history entregou 1 responsabilidade clara (UI → cálculo → persistência → consulta). Nada de stories-monstro que misturam camadas.
• Review adversarial tripla (Blind + EdgeCase + Auditor) consistentemente filtrou ruído de sinal: vários falsos positivos (ex: locale em Double.toString) foram corretamente classificados como dismiss, e os riscos reais (sync PG ausente, MD5 sem vl_acrescimo) foram deferred com justificativa.
• Tolerância a dados ausentes do ERP: padrão estabelecido em Story 1.2 (acresc ausente no PG) foi replicado em Story 2.4 (vl_acrescimo = 0.0 default na sync). Mantém retro-compatibilidade com schemas antigos.
• Separação pedido (editável) vs pedido_consulta (histórico): Story 2.4 identificou que o guard status >= STATUS_ENVIADO nos dois fragments (Main + Total) era necessário para preservar o valor histórico — evitou o bug sutil de "recalcular acréscimo de pedido enviado usando tx_acrescimo atual".
• Documentação de verificação manual: cada story incluiu roteiro de teste manual passo-a-passo (com SQL de inspeção, cenários de edge case). Mitigação razoável da ausência de testes automatizados no projeto.

---

3. O Que Não Foi Bem / Desafios

• Esquecimento inicial: Story 2.3 só migrou a tabela pedido, não pedido_consulta. O erro foi parcialmente sistemático — o padrão dual-DB do projeto (*DB.java + *ConsultaDB.java) exige que features que afetam ambas as tabelas migrem ambas. Story 2.4 teve que corrigir isso via v43. Lição: ao planejar features que afetam pedidos históricos, sempre verificar o par pedido + pedido_consulta desde a primeira story.
• Sync PG do vl_acrescimo permanece deferred (end-to-end incompleto). Das Jornadas do PRD, a Jornada 3 (consulta de pedido histórico com acréscimo) não está 100% funcional: pedidos que vêm do ERP via sync sempre terão vl_acrescimo = 0 em pedido_consulta até que PedidoPGSQL seja atualizado. Isso é documentado mas a feature ainda NÃO está production-ready sem esse incremento.
• Lógica de cálculo de acréscimo duplicada em 3 pontos (MainPedidoFragment.fillFields, MainPedidoFragment.atualizarResumoPedido, TotalPedidoFragment.FillFields): flagged em review da 2.2, repetido em 2.3 e 2.4. Cada story deferred a extração de helper. A duplicação cresceu (agora são 3 cópias com o mesmo guard de status).
• Débitos técnicos pré-existentes perpetuados: SQL por concatenação de string, cursor por índice posicional, Global.pedido sem null-check, UpdatePedItemActivity instanciada fora do lifecycle — cada review flagged, cada story deferred. Padrão: débito não-introduzido-por-esta-story nunca é resolvido nesta-story.
• Epic 1 sem retrospectiva: epic-1-retrospective ficou optional e foi pulado. Lições da Epic 1 (ex: verificar schema PG antes de implementar sync) só foram capturadas informalmente nos arquivos deferred-work.md.

---

4. Principais Insights

1. Features que afetam pedidos precisam mapear os 2 fluxos desde o planejamento. Existem dois caminhos de leitura do pedido (BrowsePedido → PedidoDB para editáveis; BrowsePedidoConsulta → PedidoConsultaDB para históricos) e dois caminhos de escrita (save local + sync PG). Esquecer qualquer um deles cria trabalho retroativo.

2. Guard por status é o padrão idiomático do projeto para separar "valor computado em tempo real" de "valor congelado histórico". Já existia para descontoV; agora existe para vl_acrescimo. Candidato claro a extrair um helper compartilhado.

3. Tolerância "campo novo = 0" na sync PG é o padrão canônico: ao adicionar coluna no SQLite antes do PG, o read-path trata valor ausente como 0 (não erro). Assim o app é forward-compatible quando o PG recebe a coluna.

4. Débitos técnicos pré-existentes viram "invariantes silenciosas". A cada review eles reaparecem, a cada story são deferred. Para quebrar o ciclo, dedicar uma story explícita de refactor (ou um epic de "technical-debt burndown") é o único caminho — enxertar em stories funcionais é rejeitado corretamente como scope creep.

5. Review adversarial em 3 camadas teve custo/benefício alto. Mesmo com muitos findings falsos positivos, o Auditor aprovou todos os ACs sem violações e o EdgeCase identificou corretamente os 2 riscos reais (sync PG e MD5). Manteria a prática para features de complexidade similar.

---

5. Action Items

Débitos técnicos prioritários (carry-forward)

#	Item	Dono	Prioridade	Notas
A1	Sync PG do vl_acrescimo: atualizar PedidoPGSQL.insert (envio) e selectAllPedConsulta (retorno). Schema de destino varia por sistema: Gerente grava em gerente.pedidos.acrep (% taxa) + gerente.pedidos.acrev (valor). SIG grava em sig.pedidos.tx_acrescimo (só a taxa — valor é derivado server-side). Sem isso, Epic 2 não está production-ready.	Julio	Alta	Criar como Epic 3 ou Story 3.1 em módulo novo
A2	Incluir vl_acrescimo no MD5 de change-detection de pedido/pedido_consulta	Julio	Média	Depende de A1
A3	Extrair helper de cálculo de acréscimo compartilhado entre MainPedidoFragment.fillFields, MainPedidoFragment.atualizarResumoPedido e TotalPedidoFragment.FillFields	Julio	Média	Debt burndown
A4	Null-check global em acessos a Global.pedido (padrão defensivo)	Julio	Baixa	Afeta vários fragments; pacote técnico
A5	Migrar leitura de cursor para getColumnIndexOrThrow() em PedidoDB.selectAllFull e PedidoConsultaDB.selectFull	Julio	Baixa	Reduz risco quando JOINs mudam

Processo

#	Item	Dono
P1	Ao planejar feature que toca pedido, adicionar checklist: "afeta pedido, pedido_consulta, ambos, ou só PG?" — incorporar no template de story	Julio
P2	Rodar retrospectiva de Epic 1 retroativamente (lições de migração SQLite, sync PG com coluna ausente, FormaPagamentoDB patterns) ou explicitamente documentar que Epic 1 foi skipped	Julio
P3	Considerar transicionar epic-1 e epic-2 de in-progress para done no sprint-status.yaml agora que todas as stories estão done (ação imediata, feita nesta retro)	Julio

---

6. Próximo Epic — Preparação

Status: Epics 1 e 2 são os únicos definidos em epics.md. Não há Epic 3 planejado.

Feature completa?

Funcionalmente:

• Ciclo offline-first (criar pedido com acréscimo, salvar, ver total correto) — ✅ completo
• Consulta histórica de pedido local com acréscimo — ✅ completo (via BrowsePedido / PedidoDB)
• Consulta histórica de pedido sincronizado do ERP com acréscimo — ⚠️ INCOMPLETO (depende de A1)

Pré-requisitos para fechar a feature em produção

1. Implementar A1 (sync PG do vl_acrescimo) antes de considerar a feature production-ready.
2. Validação manual em dispositivo real com ERP conectado: criar pedido com acréscimo, sincronizar, reabrir via BrowsePedidoConsulta, confirmar que o valor histórico aparece corretamente.
3. Treinamento/comunicação com representantes sobre o novo campo "Acréscimo" na tela do pedido.

Recomendação

Criar novo epic ("Epic 3: Sync Bidirecional de Acréscimo PG↔SQLite") antes de declarar a feature encerrada. Escopo mínimo:

• Gerente (Global.SISTEMA_GERENTE):

  • DDL server-side: adicionar acrep REAL DEFAULT 0 e acrev REAL DEFAULT 0 em gerente.pedidos
  • PedidoPGSQL.insert (branch Gerente, linha ~129): enviar ped.getFormapag().getTxAcrescimo() → acrep e ped.getVlAcrescimo() → acrev
  • selectAllPedConsulta (branch Gerente): ler acrep+acrev, popular Pedido.vlAcrescimo

• SIG (Global.SISTEMA_SIG):

  • DDL server-side: adicionar tx_acrescimo REAL DEFAULT 0 em sig.pedidos
  • PedidoPGSQL.insert (branch SIG, linha ~342): enviar ped.getFormapag().getTxAcrescimo() → tx_acrescimo (só a taxa — valor é calculado server-side)
  • selectAllPedConsulta (branch SIG): ler tx_acrescimo e calcular vlAcrescimo = total × tx/100 para popular o VO

• Tolerar ausência das colunas no PG durante migração (padrão Story 1.2)

• Incluir os campos no MD5 de change-detection (item A2)

---

7. Readiness Assessment

Dimensão	Status	Observações
Testing & Quality	⚠️ Parcial	Sem suite automatizada (limitação do projeto Eclipse ADT). Roteiros manuais documentados em cada story. Recomendado: validação em dispositivo real antes de publicar APK.
Deployment	🔴 Não publicado	APK ainda não gerado/publicado. Aguardando A1 (sync PG).
Aceitação de stakeholder	🔴 Pendente	Stakeholders (representantes de vendas, escritório) ainda não viram a feature rodando.
Saúde técnica	✅ Sólida	Migrações idempotentes, guards de status consistentes, nenhuma regressão introduzida.
Bloqueadores carry-forward	⚠️ Sim	A1 (sync PG) bloqueia a Jornada 3 end-to-end. Feature não é production-ready sem ele.

---

8. Conclusão

Epic 2 entregou o escopo planejado com qualidade consistente em todas as 4 stories. Os débitos técnicos acumulados são previsíveis (padrões pré-existentes do projeto brownfield) e estão documentados. A feature NÃO está 100% end-to-end funcional até que a sync PG do vl_acrescimo seja implementada (item A1).

Lição principal para próximos epics: features que afetam o modelo de pedido precisam planejar os 4 caminhos (read/write × local/PG) desde a primeira story, em vez de descobrir lacunas no final.