sar-android/_bmad-output/project-context.md

project_name, user_name, date, sections_completed, status, rule_count, optimized_for_llm

project_name	user_name	date	sections_completed	status	rule_count	optimized_for_llm
SARAndroid	Julio	2026-04-16	technology_stack language_rules dual_database_pattern ui_activities critical_rules	complete	47	true

Contexto do Projeto para Agentes de IA

Este arquivo contém regras e padrões críticos que agentes de IA devem seguir ao implementar código neste projeto. Foco em detalhes não-óbvios que agentes poderiam deixar passar.

---

Stack de Tecnologia & Versões

• Linguagem: Java (sem Kotlin — não usar Kotlin em hipótese alguma)
• Plataforma: Android | Min SDK: 19 (Android 4.4) | Target SDK: 35
• Build system: Eclipse ADT (sem Gradle, sem Maven) — dependências são JARs em lib/, código gerado em gen/, output em bin/classes/. NUNCA criar build.gradle ou estrutura app/src/main/
• Banco local: SQLite via SQLiteOpenHelper (schema versão 40)
• Banco remoto: PostgreSQL via JDBC direto — driver DEVE ser postgresql-8.2-512.jdbc3.jar (NÃO atualizar: JDBC4 quebra silenciosamente no Android classloader)
• Data/Hora: joda-time 2.5 — usar DateTime/LocalDate/Period para TODAS as operações de data (nunca java.util.Date ou java.util.Calendar)
• FTP: commons-net 3.3
• Encoding: Strings com acentos SOMENTE em res/values/strings.xml (código-fonte tem histórico de CP1252 — não usar acentos hardcoded em Java)
• Memória: android:largeHeap="true" ativo por causa de fotos via FTP — cuidado com carregamento de imagens em dispositivos com RAM limitada
• Pacote raiz: br.com.jcsinformatica.sarandroid

Regras Específicas da Linguagem

Tratamento de Exceções

• WarningException é a exceção customizada para mensagens ao usuário — usar para erros que devem ser exibidos em AlertDialog (não RuntimeException)
• Global.getEmpresa() SEMPRE lança WarningException se chamado antes do login — envolver em try/catch em qualquer Activity que use dados da empresa

Herança de Activities

• Toda Activity pós-login DEVE estender GlobalActivity (não Activity diretamente)
• GlobalActivity.onCreate() configura o título com o nome da empresa — sempre chamar super.onCreate() como primeira instrução
• Toda nova Activity DEVE ser registrada em AndroidManifest.xml com android:screenOrientation="portrait"

Estado Global

• Global.empresa — único objeto Empresa ativo; definido no login, nunca nulo em tela pós-login
• Global.pedido e Global.pedItem — estado do pedido em edição; pode ser nulo
• Nunca instanciar Empresa diretamente nas Activities — sempre usar Global.getEmpresa()

Operações em Background

• Operações de rede (JDBC) e SQLite pesadas DEVEM rodar em Thread separada ou AsyncTask
• Nunca fazer IO de banco na UI thread — causa ANR
• Usar Handler ou runOnUiThread() para atualizar UI a partir de threads background

Nomenclatura

• DAOs SQLite: *DB.java ou *BD.java (ex: ClienteDB.java, FotosBD.java)
• DAOs PostgreSQL: *PGSQL.java (ex: ClientePGSQL.java)
• Value Objects: em vo/ sem sufixo (ex: Cliente.java, Pedido.java)
• Threads de busca: Thread* (ex: ThreadBuscaCliente.java)

Padrão Dual-Banco (SQLite + PostgreSQL)

Schema SQLite

• Toda alteração de schema DEVE ter entrada no onUpgrade() de DatabaseHelper com guard if (oldVersion < N) onde N é a nova versão
• dbVersao em DatabaseHelper DEVE ser incrementado a cada mudança de schema
• Versão atual: 40 — próxima alteração usa versão 41
• NUNCA dropar tabela em onUpgrade sem migrar dados

Ciclo de Vida de Conexão JDBC

• Toda conexão PostgreSQL DEVE ser fechada em bloco finally via ConnectionManager.closeAll()
• Nunca reutilizar conexões entre operações — criar nova conexão por operação
• Timeout de login: 20s — operações longas devem rodar em thread background
• Conexões JDBC NUNCA na UI thread

Padrão de Sincronização

• Par obrigatório por entidade: *DB.java (SQLite) + *PGSQL.java (PostgreSQL)
• MD5 é calculado no servidor PostgreSQL — NUNCA recomputar localmente para comparação
• ComunicaActivity é o ÚNICO orquestrador de sync — não criar sync fora dela
• Ordem de sync é obrigatória: empresa → representante → formas_pag → municipio → cliente → produto → pedido_consulta → peditem_consulta → ctr
• Sync parcial é estado normal — código deve tolerar entidades sem id_erp

Chaves e Identidade

• id_erp = chave no ERP remoto (pode ser NULL para registros criados offline)
• id_* = chave local SQLite autoincrement — nunca enviar ao servidor
• Pedidos criados offline têm id_erp = NULL até a próxima sync — tratar como caso especial
• Ao inserir dados do servidor: SEMPRE verificar (id_empresa, id_erp) com SELECT antes do INSERT
• NUNCA usar INSERT OR REPLACE em tabelas com FKs ativas — usar SELECT + INSERT/UPDATE

Restrições de Integridade

• FOREIGN KEY com PRAGMA foreign_keys = ON ativo — respeitar todas as FKs
• UNIQUE(id_empresa, id_erp) ON CONFLICT ABORT — conflito lança exceção, não substitui
• Toda tabela principal tem id_empresa — SEMPRE filtrar por empresa nas queries

Regras de UI & Activities

Estrutura de Telas

• Padrão CRUD: Browse* (lista) → Update* (edição) por entidade
• Listas usam ListView + SimpleArrayAdapter* customizado em uimodels/
• Busca em lista: thread dedicada ThreadBusca* — nunca buscar na UI thread
• Toda tela é portrait-only (android:screenOrientation="portrait")

Navegação

• Fluxo: SplashScreen → LoginActivity → MainActivity → feature Activities
• MainActivity usa ExpandableListView com ExpandableListAdapter
• Passagem de dados entre Activities: via Intent.putExtra() com IDs (não objetos serializados)
• Pedido em edição: via Global.pedido e Global.pedItem (não via Intent)

Layouts & Resources

• Layouts em res/layout/ — nomenclatura: activity_*.xml, list_*.xml, fragment_*.xml
• Strings com texto visível ao usuário SEMPRE em res/values/strings.xml
• Tema: AppTheme definido em res/values/styles.xml
• Menus em res/menu/ — padrão menu_*.xml

Fragments (Pedido)

• UpdatePedidoActivity usa fragments: FlexPedidoFragment, ItensPedidoFragment, TotalPedidoFragment
• Comunicação entre fragment e activity via interface callback — não acessar activity diretamente
• PedidoTabAdapter gerencia as abas do pedido

Permissões

• INTERNET + ACCESS_NETWORK_STATE — para JDBC e FTP
• WRITE_EXTERNAL_STORAGE / READ_EXTERNAL_STORAGE — para fotos de produtos
• FileProvider configurado em res/xml/provider_paths.xml para compartilhar arquivos

Regras Críticas — O Que NÃO Fazer

Proibições Absolutas

• ❌ NUNCA adicionar dependências via Gradle/Maven — projeto usa JARs em lib/ apenas
• ❌ NUNCA escrever Kotlin — somente Java
• ❌ NUNCA fazer operações de banco (SQLite ou JDBC) na UI thread
• ❌ NUNCA atualizar o driver PostgreSQL (JDBC4 quebra no Android classloader)
• ❌ NUNCA usar INSERT OR REPLACE em tabelas com FKs ativas
• ❌ NUNCA hardcodar strings com acentos em código Java — usar res/values/strings.xml
• ❌ NUNCA criar Activity sem registrá-la no AndroidManifest.xml
• ❌ NUNCA acessar Global.getEmpresa() sem try/catch de WarningException
• ❌ NUNCA criar lógica de sync fora de ComunicaActivity

Armadilhas Comuns

• Confundir id_erp com id_* local — são chaves diferentes com propósitos distintos
• Pedidos offline têm id_erp = NULL — sempre verificar antes de usar como FK remota
• MD5 vem do servidor — nunca recomputar localmente para comparação
• onUpgrade() sem guard de versão apaga dados de usuários em produção
• Conexão JDBC sem finally + closeAll() causa leak de conexão

Sem Testes Automatizados

• O projeto não tem infraestrutura de testes (sem JUnit, sem Espresso)
• Não criar arquivos de teste — não há como executá-los no build atual
• Validação é manual via dispositivo/emulador Android

---

Diretrizes de Uso

Para agentes de IA:

• Ler este arquivo antes de implementar qualquer código
• Seguir TODAS as regras exatamente como documentadas
• Em caso de dúvida, preferir a opção mais restritiva
• Atualizar este arquivo se novos padrões emergirem

Para humanos:

• Manter este arquivo enxuto e focado nas necessidades dos agentes
• Atualizar quando o stack de tecnologia mudar
• Revisar quando houver mudanças de arquitetura significativas
• Remover regras que se tornarem óbvias com o tempo

Última atualização: 2026-04-16