sar-android/_bmad-output/planning-artifacts/prd.md

stepsCompleted, status, completedAt, inputDocuments, workflowType, projectDocsCount, briefCount, researchCount, brainstormingCount, classification

stepsCompleted	status	completedAt	inputDocuments	workflowType	projectDocsCount	briefCount	researchCount	brainstormingCount	classification
step-01-init step-02-discovery step-02b-vision step-02c-executive-summary step-03-success step-04-journeys step-05-domain step-06-innovation step-07-project-type step-08-scoping step-09-functional step-10-nonfunctional step-11-polish step-12-complete	complete	2026-04-16	_bmad-output/project-context.md docs/index.md docs/project-overview.md docs/architecture.md docs/data-models.md docs/source-tree-analysis.md docs/development-guide.md docs/component-inventory.md	prd	7	0	0	0	projectType domain complexity projectContext feature schemaChange schemaVersion mobile_app sales_force_automation medium brownfield acrescimo_financeiro_pedido true v40_to_v41

Product Requirements Document - SARAndroid

Funcionalidade: Acréscimo Financeiro no Pedido Autor: Julio Data: 2026-04-16

Executive Summary

O SARAndroid é um app Android nativo para representantes de vendas que opera offline-first, sincronizando dados com PostgreSQL via JDBC. Esta funcionalidade implementa o cálculo automático de acréscimo financeiro no pedido com base na taxa configurada por forma de pagamento.

Problema: Pedidos fechados com formas de pagamento que possuem acréscimo chegam ao escritório com valor incorreto — a funcionalidade não existe no app. O representante não tem como saber o valor final correto sem calcular manualmente.

Solução: Ler tx_acrescimo da tabela local formapag (sincronizada de gestao.formapag.acresc no PostgreSQL), calcular o acréscimo ao selecionar a forma de pagamento, exibi-lo em campo dedicado e somá-lo ao total do pedido.

Por que agora: A taxa já existe no ERP — a informação está disponível. A implementação aproveita o pipeline de sync existente (ComunicaActivity), o modelo de pedido em uso (Pedido/ItemPedido) e a UI de edição de pedido (UpdatePedidoActivity). Nenhuma nova infraestrutura é necessária.

Impacto: Representantes fecham pedidos com valor correto, sem cálculo manual. Escritório recebe pedidos com valores corretos. Zero retrabalho de correção pós-sync.

Project Classification

• Tipo: App mobile Android nativo (Java, offline-first)
• Domínio: Força de Vendas / ERP Móvel
• Complexidade: Média — migração de schema SQLite (v40→v41), extensão do pipeline de sync, atualização da UI de pedido
• Contexto: Brownfield — extensão de funcionalidade em sistema em produção

Success Criteria

Sucesso do Usuário

• Ao selecionar forma de pagamento com tx_acrescimo > 0, o acréscimo é calculado e exibido instantaneamente, sem ação manual
• Campo acréscimo sempre visível no pedido (R$ 0,00 quando não há acréscimo)
• Total do pedido inclui acréscimo antes de qualquer confirmação
• Troca de forma de pagamento recalcula o acréscimo automaticamente

Sucesso do Negócio

• Pedidos sincronizados carregam sempre o valor total correto (subtotal + acréscimo)
• Zero retrabalho de correção de valor no escritório para pedidos com acréscimo

Sucesso Técnico

• Schema SQLite migrado de v40 para v41 sem perda de dados
• Campo tx_acrescimo sincronizado corretamente de gestao.formapag.acresc via ComunicaActivity
• Toda leitura de banco executada fora da UI thread

Resultados Mensuráveis

• 100% das formas de pagamento com acresc > 0 no PostgreSQL refletidas no SQLite após sync
• Recálculo ocorre na mesma interação de troca de forma de pagamento (< 100ms)

Product Scope

MVP — Mínimo Viável (Fase 1)

Jornadas suportadas: Todas as 4 jornadas mapeadas

• Migração schema v40→v41: ALTER TABLE formapag ADD COLUMN tx_acrescimo REAL DEFAULT 0
• Sync em ComunicaActivity: mapear gestao.formapag.acresc → formapag.tx_acrescimo
• FormaPagamentoDB: expor tx_acrescimo no VO FormaPagamento
• UpdatePedidoActivity/fragment: campo acréscimo sempre visível; recálculo automático ao selecionar forma de pagamento; fórmula: acrescimo = subtotal × (tx_acrescimo / 100); total = subtotal + acrescimo
• Persistência: gravar valor calculado do acréscimo e total no registro do pedido
• Consulta: exibir total com acréscimo em pedidos que já possuem o campo; pedidos sem o campo não são alterados

Growth Features (Fase 2)

• Relatório de acréscimos por período/representante
• Destaque visual quando acréscimo for alto

Visão (Fase 3)

• Múltiplas taxas por forma de pagamento (ex: parcelado com juros progressivos)
• Acréscimo por faixa de valor do pedido

Riscos e Mitigações

Risco	Mitigação
tx_acrescimo = NULL em registros antigos	DEFAULT 0 na migração + tratar NULL como 0.0 em código
Sync parcial (formapag não sincronizada)	Comportamento gracioso: acréscimo = 0, pedido funciona normalmente
Tabela pedido sem campo para valor do acréscimo	⚠️ Verificar schema antes da implementação — pode exigir coluna adicional na migração

User Journeys

Jornada 1 — Representante: Pedido com Acréscimo (caminho feliz)

Cena: Carlos, representante, fecha os itens do pedido na loja do cliente e seleciona "Boleto 30/60/90" (2,5% de acréscimo financeiro).

Ação: O campo "Acréscimo" atualiza instantaneamente para R$ 87,50 (2,5% sobre R$ 3.500,00). O total passa para R$ 3.587,50.

Resolução: Carlos mostra o total correto ao cliente e fecha o pedido. O escritório recebe o valor já correto — sem ligação para corrigir.

Jornada 2 — Representante: Troca de Forma de Pagamento

Cena: Carlos já selecionou "Boleto 30/60/90" (2,5% acréscimo), mas o cliente prefere pagar à vista ("Dinheiro", sem acréscimo).

Ação: Carlos troca a forma de pagamento. O campo "Acréscimo" retorna para R$ 0,00 e o total volta para R$ 3.500,00 automaticamente.

Resolução: O pedido reflete a escolha correta do cliente sem cálculo manual.

Jornada 3 — Representante: Consulta de Pedido Antigo com Acréscimo

Cena: Carlos consulta um pedido fechado no mês anterior que tinha acréscimo registrado.

Ação: A tela de consulta exibe o valor total incluindo o acréscimo que constava no pedido.

Resolução: Carlos vê o histórico correto. Pedidos antigos sem o campo não são alterados.

Jornada 4 — Sync: Taxa Atualizada no ERP Chega ao App

Cena: O gestor atualiza a taxa de acréscimo do "Boleto 30/60/90" de 2,5% para 3,0% no ERP (gestao.formapag.acresc = 3.0).

Ação: Carlos executa a comunicação no app. O sync lê gestao.formapag.acresc e grava 3.0 em formapag.tx_acrescimo no SQLite.

Resolução: No próximo pedido, o acréscimo é calculado com a taxa atualizada sem nenhuma ação manual no app.

Rastreabilidade Jornada → Capacidade

Capacidade	Jornada
Leitura de tx_acrescimo ao carregar forma de pagamento	1, 2
Cálculo: acrescimo = subtotal × (tx_acrescimo / 100)	1
Recálculo automático ao trocar forma de pagamento	2
Campo acréscimo sempre visível (R$ 0,00 quando zero)	1, 2
Total = subtotal + acréscimo	1
Consulta: exibir total com acréscimo quando existir no registro	3
Sync: gestao.formapag.acresc → formapag.tx_acrescimo	4

Domain-Specific Requirements

Operação Offline-First

• O cálculo do acréscimo usa exclusivamente dados sincronizados no SQLite — nenhuma chamada de rede no momento do cálculo
• tx_acrescimo = NULL tratado como 0.0 em todo o código — formas de pagamento sem o campo no ERP não geram erro

Consistência Histórica do Pedido

• O valor do acréscimo calculado é gravado no pedido no fechamento — não recalculado na consulta
• Garante que pedidos históricos não mudem de valor se a taxa for alterada futuramente no ERP

Integração ERP

• Fonte única de verdade da taxa: gestao.formapag.acresc no PostgreSQL
• Propagação exclusiva via ComunicaActivity → formapag.tx_acrescimo no SQLite
• O campo acresc pode não existir em versões antigas do schema PostgreSQL — o sync tolera a ausência sem interromper a comunicação

Mobile Platform Requirements

• Plataforma: Android nativo Java exclusivamente — sem Kotlin, sem cross-platform
• Min SDK 19 — cálculo usa operações aritméticas básicas, sem APIs modernas
• Orientação: Portrait-only, conforme padrão do projeto
• Offline: 100% offline — taxa lida do SQLite local, cálculo em memória
• Permissões: Nenhuma permissão adicional necessária
• Dependências: Nenhuma — sem JARs novos em libs/
• UI thread: Toda leitura de tx_acrescimo do SQLite em thread background, conforme regra do projeto
• Herança: Todas as Activities envolvidas já estendem GlobalActivity — padrão mantido

Functional Requirements

Sincronização de Dados

• FR1: O sistema sincroniza gestao.formapag.acresc (PostgreSQL) para formapag.tx_acrescimo (SQLite) durante a comunicação
• FR2: O sistema trata tx_acrescimo = NULL como 0.0, sem erro ou interrupção

Schema e Migração

• FR3: O sistema migra o schema SQLite de v40 para v41, adicionando tx_acrescimo REAL DEFAULT 0 na tabela formapag
• FR4: A migração preserva todos os registros existentes de formas de pagamento

Cálculo de Acréscimo

• FR5: O representante visualiza o valor do acréscimo financeiro em campo dedicado no pedido, sempre visível
• FR6: O sistema calcula o acréscimo ao selecionar forma de pagamento: acrescimo = subtotal × (tx_acrescimo / 100)
• FR7: O sistema recalcula o acréscimo automaticamente ao trocar a forma de pagamento
• FR8: O campo acréscimo exibe R$ 0,00 quando tx_acrescimo = 0 ou NULL
• FR9: O total do pedido reflete subtotal + acrescimo

Persistência do Pedido

• FR10: O sistema grava o valor calculado do acréscimo no registro do pedido ao fechar
• FR11: O sistema grava o total com acréscimo no registro do pedido ao fechar

Consulta de Pedidos

• FR12: O representante visualiza o total com acréscimo em pedidos fechados que possuem o campo gravado
• FR13: O sistema exibe pedidos sem campo de acréscimo sem alteração ou erro

Non-Functional Requirements

Performance

• Recálculo do acréscimo ao trocar forma de pagamento: < 100ms (operação aritmética em memória, sem I/O)
• Leitura de tx_acrescimo do SQLite: executada em thread background, sem impacto na responsividade da UI

Confiabilidade

• tx_acrescimo = NULL nunca causa NullPointerException — tratamento defensivo obrigatório em todo ponto de acesso
• Migração v40→v41 idempotente: múltiplas execuções de onUpgrade() não corrompem dados

Integração

• Sync tolera ausência da coluna acresc no PostgreSQL (schemas antigos) sem interromper a comunicação
• Após sync bem-sucedido: tx_acrescimo reflete acresc para 100% das formas de pagamento ativas