sar-android/docs/development-guide.md

Guia de Desenvolvimento — SARAndroid

Pré-requisitos

Ferramenta	Versão	Notas
Eclipse	4.x com ADT Plugin	Ambiente original do projeto
Android SDK	API 23+	target=android-23 em project.properties
JDK	7 ou 8	compatível com Android SDK
Android Studio	qualquer	via "Import Eclipse ADT Project"

⚠️ Sem Gradle. Este projeto NÃO usa gradlew. Não existe build.gradle. Não tente criar um.

Abrindo o Projeto

Eclipse ADT

1. File → Import → Android → Existing Android Code
2. Aponte para a pasta raiz do projeto
3. Confirmar que project.properties detectou target=android-23

Android Studio

1. File → New → Import Project
2. Selecionar "Eclipse ADT (Eclipse.project)"
3. O AS vai converter para Gradle automaticamente (apenas para abertura)
4. Atenção: Não commitar os arquivos Gradle gerados pelo AS

Estrutura de Build (Eclipse ADT)

src/          → código-fonte Java
gen/          → R.java gerado automaticamente (não editar)
res/          → recursos (layouts, strings, drawables)
lib/          → JARs de dependência (postgresql, joda-time, commons-net)
bin/          → build output (não versionar)
AndroidManifest.xml
project.properties    → target=android-23
.classpath            → referências de classpath

Adicionando Dependências

Não há Maven/Gradle. Para adicionar uma biblioteca:

1. Copiar o JAR para lib/
2. Abrir .classpath e adicionar entry <classpathentry kind="lib" path="lib/nome.jar"/>
3. No Eclipse: Project → Properties → Java Build Path → Libraries → Add JARs

Modificando o Schema SQLite

1. Adicionar colunas/tabelas em DatabaseHelper.onCreate() no novo schema completo
2. Adicionar bloco if (oldVersion < N) em DatabaseHelper.onUpgrade() com os ALTERs
3. Incrementar dbVersao de 40 para N em DatabaseHelper
4. Nunca modificar blocos de versões anteriores em onUpgrade()

// DatabaseHelper.java
final static int dbVersao = 41; // era 40

@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
    // ... blocos anteriores ...
    if (oldVersion < 41) {
        db.execSQL("ALTER TABLE produto ADD COLUMN nova_coluna TEXT;");
    }
}

Adicionando uma Nova Activity

1. Criar a classe estendendo GlobalActivity (pós-login) ou Activity (pré-login)
2. Registrar em AndroidManifest.xml:

<activity
    android:name="br.com.jcsinformatica.sarandroid.meumodulo.MinhaActivity"
    android:label="@string/app_release"
    android:screenOrientation="portrait" />

3. Criar layout em res/layout/activity_minha.xml
4. Se for listagem: criar layout de item em res/layout/list_minha.xml
5. Se for listagem: criar adapter em uimodels/SimpleArrayAdapterMinha.java

Padrão de Tratamento de Erros

// Erros ao usuário → WarningException → AlertDialog via Util.sendError
try {
    Empresa emp = Global.getEmpresa(); // pode lançar WarningException
    // ...
} catch (WarningException e) {
    Util.sendError(this, e); // exibe AlertDialog com a mensagem
} catch (Exception e) {
    Util.sendError(this, e); // exibe AlertDialog com stack trace
}

Padrão de Operações em Background

// Busca em Thread separada (nunca na UI thread)
new Thread(new Runnable() {
    @Override
    public void run() {
        final List<Cliente> resultado = new ClienteDB().selectAll(context);
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                adapter.clear();
                adapter.addAll(resultado);
            }
        });
    }
}).start();

Padrão de Acesso ao SQLite

// Sempre fechar o database após uso
DatabaseHelper dbHelper = new DatabaseHelper(context);
SQLiteDatabase db = dbHelper.getWritableDatabase();
try {
    // operações
} finally {
    db.close();
    dbHelper.close();
}

Padrão de Conexão PostgreSQL

// Sempre fechar em finally
Connection conn = null;
PreparedStatement stmt = null;
ResultSet rs = null;
try {
    conn = ConnectionManager.getConnection(context, config);
    stmt = conn.prepareStatement("SELECT ...");
    rs = stmt.executeQuery();
    // processar
} catch (Exception e) {
    throw e;
} finally {
    ConnectionManager.closeAll(conn, stmt, rs); // sempre!
}

Strings e Encoding

• Nunca usar acentos hardcoded em código Java (histórico de encoding CP1252)
• Todas as strings visíveis ao usuário em res/values/strings.xml
• Usar getString(R.string.minha_string) ou @string/minha_string em XML

Executando o App

1. Conectar dispositivo Android ou iniciar emulador (API 19+)
2. Eclipse: Run → Run As → Android Application
3. Ou Android Studio: Run → Run 'app'

Debug de Conexão PostgreSQL

• Usar TestaConexao.java para verificar conectividade antes de sync
• Logs via android.util.Log.d("TAG", "mensagem")
• Timeout de conexão: 20 segundos (definido em ConnectionManager)

Sem Testes Automatizados

O projeto não tem infraestrutura de testes. Validação é manual:

• Testar em dispositivo físico (API 19+) para comportamento real
• Testar sincronização com servidor PostgreSQL de desenvolvimento
• Verificar comportamento offline: criar pedidos sem conexão, sincronizar depois