SMAS Almada
Android & iOS • App de Gestão de Contas de Água
Aplicação móvel que centraliza a relação digital entre a entidade gestora de água e saneamento e os seus clientes: faturas, pagamentos, leituras de contador, dados de contrato e comunicados num único canal nativo, seguro e multiplataforma.
A água como serviço digitalizado
A SMAS Almada digitaliza o ciclo completo da relação com o cliente: consulta de cadastro e contrato, histórico de faturas, pagamento por referência Multibanco, envio de leituras do contador e comunicação de campanhas e avisos através do ecrã inicial.
Dois front-ends, uma só lógica
Coexistência de duas implementações: uma Android 100% nativa (Jetpack Compose + Hilt + Retrofit) e uma versão multiplataforma (Compose Multiplatform) que partilha ~90% do código entre Android e iOS, com Interface nativa em SwiftUI/Xcode para iOS.
Arquitetura em camadas
Estrutura ui → domain → data com repositórios, ViewModels com padrão State/Event, mappers DTO→domínio, injeção de dependências (Koin / Hilt) e navegação declarativa (Voyager / Navigation Compose).
Segurança por design
Autenticação JWT com sessão gerida em armazenamento local seguro (SessionManager + DataStore/Multiplatform Settings), token Bearer via AuthInterceptor, e suporte a fluxos de ativação, recuperação de password e desbloqueio de conta.
Infraestrutura reprodutível
Docker Compose com API + SQL Server, Dockerfile multi-stage, GitHub Actions CI para testes unitários, UI tests em emulador e geração de artefactos (APK e framework iOS) a cada push para main.
Benefícios para a Entidade Gestora
Cada funcionalidade foi desenhada para melhorar a relação com os clientes, simplificar processos e aumentar a eficiência operacional.
| Funcionalidade | Benefício para a SMAS |
|---|---|
| Splash com comunicação | Canal direto para comunicar campanhas, avisos e novidades aos utilizadores no arranque da app. |
| Dados cadastrais | Exibição transparente dos dados do cliente e contrato, reduzindo pedidos de informação. |
| Histórico de faturas | Transparência total e redução de pedidos de informação e reimpressões. |
| Detalhes de fatura | Visualização detalhada da discriminação de custos e download da fatura oficial (PDF). |
| Dados de pagamento | Integração com meios de pagamento via referência Multibanco; acelera cobranças e reduz pendências. |
| Envio de leituras | Receção de leituras de contador em tempo real sem deslocação nem telefonemas. |
| Gestão de login | Autenticação segura com base pronta para suporte futuro a SSO/MFA. |
| Backend microserviço | Fácil integração com sistemas existentes, testabilidade elevada e documentação técnica Swagger. |
Funcionalidades Implementadas
Tudo o que uma entidade de águas precisa para um canal digital completo.
Splash Screen com Carrossel
Ecrã inicial com carrossel de campanhas e avisos (CarouselItem) e lista de funcionalidades em destaque (FeatureItem), servidos por endpoints públicos do backend — permite à entidade atualizar comunicação sem publicar nova versão da app.
Dados do Contrato & Cadastro
Cartão de contrato com todos os dados: cliente, NIF, morada, local de consumo, classe, tipo de contrato, entidade e número de contrato. Detalhe exibido diretamente no ecrã inicial após login.
Histórico de Faturas
Lista completa de faturas com ano, número, data de emissão, valor e estado (Pago Pendente). Interface de lista com cabeçalho claro e navegação para o detalhe de cada documento.
Detalhes da Fatura
Visualização detalhada do documento: período de faturação, consumo em m³, leitura anterior e atual, discriminação de custos por categoria (CostCategory) e download da fatura oficial em PDF.
Pagamento por Multibanco
Ecrã de pagamento com discriminação de valor (total e por rubrica) e dados de pagamento: Entidade e Referência MB, e valor total a pagar. Aumenta a rapidez de cobrança e reduz faturas em dívida.
Envio de Leituras
Submissão da leitura do contador diretamente da app, com informação do prazo-limite, mês de referência e último valor comunicado. Feedback imediato do resultado da submissão.
Autenticação Completa
Login, registo, recuperação de password, ativação de conta e desbloqueio de utilizador. Sessão mantida com token JWT e logout seguro, preparado para evolução para SSO/MFA.
Comunicações & Avisos
Área de comunicações dedicada para avisos de interrupções, campanhas de poupança de água, atualizações tarifárias e informação relevante para o cliente.
Ecrãs da App
Capturas de ecrã reais da aplicação Android nativa executada num dispositivo físico (Samsung Galaxy S20), ligada ao backend ASP.NET Core 9.0 em execução local via Docker. Todos os dados apresentados provêm da API em tempo real (dados de exemplo da seed).
1 Splash & Carrossel
Ecrã de arranque com comunicação dinâmica: carrossel de campanhas/avisos e destaques de funcionalidades (fatura eletrónica, leituras, gestão de contrato).
- Conteúdo servido por endpoints públicos do backend.
- Permite à entidade atualizar a comunicação sem publicar nova versão.
- Botões de acesso à área de cliente e contactos úteis.
2 Autenticação
Ecrã de login com identificador flexível — Código de Entidade, Utilizador ou NIF — e senha.
- Autenticação JWT com token reutilizado em todas as chamadas autenticadas.
- Acesso a registo e recuperação de senha.
- Sessão persistida em armazenamento local seguro.
3 Credenciais Preenchidas
Login preenchido com as credenciais de teste da seed (1 / 1), prontas a submeter com o botão ENTRAR.
- Validação do estado da conta antes da sessão: bloqueada, inativa ou senha para alterar.
- Mensagens de erro devolvidas diretamente pelo backend.
4 Home — Dados do Contrato
Ecrã inicial pós-login com o cartão do contrato e resumo do serviço.
- Classe: Social — Tipo: Doméstico — Entidade: 0128806.
- Leituras: última de 1541.00 m³ em 29/09/2025; próxima estimada em 30/12/2025.
- Última fatura: €37.12 pendente, pagável até 26/12/2025.
- Navegação inferior: Início, Faturas, Leitura.
5 Histórico de Faturas
Lista completa do histórico com documento, valor e estado.
- Fatura 2025/5617001 — €37.12 — Pendente
- Fatura 2025/5617002 — €36.91 — Pago
- Fatura 2025/5617003 — €26.66 — Pago
- Toque num documento para aceder ao detalhe.
6 Detalhe da Fatura
Detalhe da fatura 2025/5617001: emitida em 03/12/2025, vence em 26/12/2025, valor de €37.12, estado Pendente.
- PAGAR FATURA — abre os dados de pagamento Multibanco.
- DESCARREGAR PDF — download da fatura oficial.
- Secção "Detalhes da Fatura" com discriminação de custos (consumo por categoria).
7 Pagamento Multibanco
Ecrã de pagamento com discriminação completa do valor e dados para pagamento.
- Água €12.91 · Saneamento €11.89 · Resíduos €7.55 · Taxas do Estado €3.99 · IVA €0.78.
- Período de faturação: 03/11/2025 a 02/12/2025 — pagável até 26/12/2025.
- Valor total a pagar: €37.12.
- Dados Multibanco: entidade e referência para pagamento no terminal/cajero.
8 Comunicação de Leituras
Submissão da leitura do contador diretamente da app, com prazo e último valor informado.
- Prazo ativo: Enviar Até 31 agosto 2026 (data gerida pelo backend).
- Último valor informado: 1535.00 m³ em 30/12/2025.
- Validações de valor: leitura superior a 10 m³ e abaixo de 100.000 m³.
9 Leitura Submetida
Confirmação em tempo real após o envio da leitura para o backend.
- Mensagem de sucesso: Leitura de 1546 m³ submetida com sucesso!
- Registo gravado na base de dados com data e origem ("App").
- Feedback imediato do resultado da submissão.
Capturas obtidas em dispositivo físico com o backend local em Docker. Dados de exemplo da seed disponibilizados pelos endpoints /api/reading/info, /api/invoices/history e /api/home/data.
Fluxo na App
Do arranque ao pagamento, num fluxo contínuo e orientado por estados.
1 · Arranque
Splash com carrossel de campanhas e destaque das funcionalidades da app. A entrada pode ser feita em modo convidado para explorar os destaques antes do login.
2 · Autenticação
Login com credenciais (registo, recuperação de password, ativação e desbloqueio disponíveis). O token JWT é guardado e reutilizado em todas as chamadas autenticadas.
3 · Home
Saudação personalizada, dados do contrato, última leitura, próximas leituras estimadas (SMAS Almada e cliente) e a fatura mais recente com ação rápida "PAGAR AGORA" se estiver pendente.
4 · Faturas → Detalhe → Pagamento
Navegação em pilha: histórico de faturas → detalhe com discriminação de custos e download PDF → dados de pagamento Multibanco com entidade, referência e valor total.
5 · Leituras
Submissão da leitura com validação do período e prazo. O histórico de leituras e as próximas datas estimadas mantêm o cliente informado.
6 · Comunicações
Consultas de avisos e comunicados emitidos pela entidade, mantendo o utilizador sempre atualizado sobre o serviço.
Arquitetura Front-end (Kotlin Multiplatform)
A versão multiplataforma usa Compose Multiplatform (Kotlin) com interfaces 100% nativas no Android e iOS, partilhando a lógica de domínio, dados e DI num único módulo composeApp.
Camadas
Stack técnica
Versão Android Nativa (Referência)
Backend & API (ASP.NET Core 9)
Microserviço Web API em .NET 9.0 com Entity Framework Core + SQL Server, autenticação JWT e documentação Swagger/OpenAPI. Arquitetura em camadas: Controllers → Services → Data.
Stack técnica
Entidades (EF Core)
Endpoints
| Controller | Método | Endpoint | Auth | Descrição |
|---|---|---|---|---|
| Authentication | POST | /api/authentication/login | — | Login do utilizador |
| Authentication | POST | /api/authentication/register | — | Registo de novo utilizador |
| Authentication | POST | /api/authentication/recover | — | Recuperação de password |
| Authentication | POST | /api/authentication/activate | — | Ativar conta de utilizador |
| Authentication | POST | /api/authentication/unlock | — | Desbloquear utilizador |
| Splash Content | GET | /api/splashcontent/features | — | Funcionalidades do splash |
| Splash Content | GET | /api/splashcontent/carousel | — | Itens do carrossel |
| Home | GET | /api/home/data | 🔒 | Dados do ecrã inicial (contrato, fatura, leituras) |
| Invoices | GET | /api/invoices/history | 🔒 | Histórico de faturas |
| Invoices | GET | /api/invoices/{id} | 🔒 | Detalhes de uma fatura |
| Invoices | GET | /api/invoices/{id}/payment | 🔒 | Dados de pagamento da fatura |
| Invoices | POST | /api/invoices/{id}/download | 🔒 | URL da fatura em PDF |
| Reading | GET | /api/reading/info | 🔒 | Informação para submissão de leitura |
| Reading | POST | /api/reading/submit | 🔒 | Submeter valor da leitura |
Infraestrutura
Docker Compose com dois serviços: smas (API .NET) e sqlserver (SQL Server 2022). Dockerfile multi-stage na raiz do backend. Volume persistente sqlserver_data para os dados.
CI/CD (GitHub Actions)
Dois workflows em .github/workflows:
.NET CI (build + testes em main e pull requests) e
CI multiplataforma (testes unitários, UI tests em emulador AVD, análise estática com baseline e
build de APK Android + framework iOS como artefactos).
Testes & Integração Contínua
Qualidade medida em cada etapa do pipeline, da linha de comando ao emulador.
Testes Unitários (KMP)
Testes partilhados em commonTest para fakes, mappers, DTOs, repositórios, SessionManager e ViewModels, executados no Android/JVM, iOS via iosSimulatorArm64Test ou agregados com allTests.
UI Tests (Android Instrumented)
Testes de interface com Compose UI Test (connectedDebugAndroidTest) cobrindo os ecrãs principais com testTag dedicados (Home, Invoices, Payment, etc.), executados em emulador no CI.
Testes Backend (.NET)
xUnit + FluentAssertions + Moq + EF Core InMemory abrangendo todos os controllers (Authentication, Home, Invoices, Reading, SplashContent) com cobertura via Coverlet (dotnet test --collect:"XPlat Code Coverage").
Análise Estática & Cobertura
Detekt com configuração e baseline dedicados (config/detekt) e relatório Jacoco de cobertura (jacocoTestReport) gerado automaticamente após os testes de debug.
Como Executar & Repositórios
Backend (.NET)
# Full stack (API + SQL Server) docker-compose up --build # API apenas (requer SQL Server a correr) dotnet watch run --project Smas.Api/Smas.Api.csproj # Testes dotnet test # Migrations dotnet ef migrations add-p Smas.Data -s Smas.Api dotnet ef database update -p Smas.Data -s Smas.Api
Front-end (KMP)
# Android - debug ./gradlew :composeApp:assembleDebug ./gradlew :composeApp:installDebug # Testes unitários (Android/JVM) ./gradlew :composeApp:testDebugUnitTest # UI tests (emulador ligado) ./gradlew :composeApp:connectedDebugAndroidTest # iOS (Xcode) - abrir iosApp/iosApp.xcodeproj ./gradlew :composeApp:embedAndSignAppleFrameworkForXcode
Localização dos projetos
Backend: ~/projects/smas-dotnet · Front-end nativo Android: ~/AndroidStudioProjects/smas · Front-end multiplataforma: ~/AndroidStudioProjects/smas-multiplatform
Proposta de Cessão do Código-fonte
Projeto desenvolvido pela MadeTech como caso real de engenharia de software para o setor dos serviços municipalizados, formalizado numa proposta de cessão total de direitos patrimoniais à entidade gestora.
O que está incluído na cessão
- Front-end: Android Kotlin Nativo e Kotlin Multiplatform, com UIs nativas para Android e iOS.
- Backend: Microserviço em .NET Core 9.0 com documentação Swagger.
- Base de dados: Entity Framework Core com SQL Server e scripts de criação/população.
- Infraestrutura: Dockerfiles e instruções de deployment.
- Documentação: README, guia de instalação, endpoints Swagger e notas técnicas.
- Entrega: Repositório Git completo (com histórico), artefactos de build e instruções CI/CD básicas.
Termos propostos (indicativos)
- Modelo: cessão total de direitos patrimoniais sobre o código-fonte e documentação.
- Preço indicativo: €18.000 (totalmente negociáveis).
- Pagamento: 50% na assinatura do contrato; 50% na entrega do repositório e documentação.
- Garantia: correção de bugs críticos nos primeiros 30 dias após entrega (limite de 10 horas).
- Suporte pós-entrega: disponível mediante contrato de manutenção separado.
- Flexibilidade: aplicação totalmente adaptável — todas as funcionalidades podem ser customizadas conforme a necessidade da entidade.
Combinação de stacks
- Kotlin Multiplatform + Compose Multiplatform — UI nativa Android & iOS com lógica partilhada.
- Android nativo — Jetpack Compose, Hilt, Retrofit, Navigation Compose.
- ASP.NET Core 9 + EF Core + SQL Server — API segura, testável e documentada.
- Docker Compose — ambiente de desenvolvimento e produção reprodutível.
- GitHub Actions — CI com testes unitários, UI tests e artefactos de build.
Adaptabilidade
A arquitetura de backend é de fácil adaptação e integra-se a bases de dados ou Web APIs existentes sem necessidade de alterações no front-end. O mapeamento de dados é isolado na camada de repositórios, o que permite reutilizar toda a interface móvel sobre o sistema de faturação já instalado.
Setor: Serviços Municipalizados Água & Saneamento Faturação & Pagamentos