GesCon — Sistema de Gestão Condominial

Sistema de gestão condominial em AdvPL/TLPP, rodando sobre o AdvPP (compilador/VM open-source para AdvPL/TLPP, escrito em Go). Serve dois propósitos: uso real de administração de condomínio, e case de validação de robustez do compilador — o desenvolvimento deste projeto encontrou e corrigiu 5 bugs reais (persistência de work-area, Recover sem variável nomeada, ponto de entrada com #include, comparação com Nil derrubando a VM, diálogos não bloqueantes no desktop) e motivou 4 capacidades novas (TCSqlExec/TCSqlQuery, TMailMessage, FWMenuSelect/FWGetText, FWHash) no AdvPP — ver ARQUITETURA.md.

Aplicação desktop: advplc build gera um executável autocontido que abre em janela nativa (Fyne), com banco SQLite local. Não há servidor nem navegador envolvidos.

Login de administrador e menu navegando entre as telas: cadastro de unidades e condôminos, lançamento de despesas, Fechamento Mensal com rateio por fração ideal, cobranças e registro de pagamento, mala direta com envio real de e-mail, relatórios (balancete, inadimplência, extrato por unidade, despesas por categoria), contabilidade em partida dobrada (lançamento manual, despesa rateada, validação de integridade, balancete e fechamento de período), auditoria com seis validadores de anomalia e alertas, boleto bancário Itaú/Bradesco, avisos do condomínio, gestão de usuários e tokens, e acesso do condômino às próprias cobranças por token.

scripts/bootstrap-db.sh    # banco
scripts/build.sh           # executável
./gescon                   # abre a janela

O portal do condômino na web está adiado — ver GUIA_UTILIZACAO.md, seção 8.

• Guia de utilização — instalação, compilação, execução e problemas comuns.
• Manual do usuário — passo a passo de cada tela.
• Padrão de GUI — como escrever tela neste projeto: primitivas disponíveis, o padrão de formulário e as armadilhas do AdvPP, todas verificadas na janela real.
• Documentação funcional — o que o sistema faz, telas, regras de negócio, limitações conhecidas.
• Documentação técnica — stack, estrutura de arquivos, modelo de dados, decisões de implementação.
• Histórico de design — spec, plano de implementação e ledger de execução (processo completo, não só o resultado).

Requisitos

• advplc v1.24.0+ — v1.22.1 corrigiu um bug real de ponto de entrada que impedia rodar qualquer projeto AdvPL multi-arquivo como o GesCon; v1.23.0 adicionou FWMenuSelect/FWGetText (menu de navegação); v1.23.1-v1.23.4 trouxeram identidade visual própria (web e desktop) e corrigiram um bug real de diálogo não bloqueante no desktop; v1.23.5 adicionou FWHash (usado pelo login); v1.24.0 adicionou 3º argumento bIsPassword em FWGetText (campo de senha mascarado em web e desktop). Todos achados/motivados durante este projeto.
• sqlite3 (CLI, só para o bootstrap do schema).

Rodando

Duas formas de rodar, mesmo banco de dados e mesmo menu por baixo:

Web (advplc serve) — abre num navegador, útil pra acessar de qualquer dispositivo na rede:

./scripts/bootstrap-db.sh   # cria as tabelas (uma vez, ou após mudar schema.sql)
advplc serve gescon.prw     # sobe em http://localhost:8080

Desktop (advplc build) — um executável nativo só, sem navegador, sem servidor rodando à parte:

./scripts/bootstrap-db.sh
export ADVPP_SRC=/caminho/pro/checkout/do/AdvPP   # necessário pra compilar
advplc build gescon.prw -o GesConApp
./GesConApp

No primeiro acesso (nenhum usuário cadastrado ainda), o sistema pede pra escolher login e senha do administrador e já entra. O campo de senha é mascarado (3º argumento bIsPassword=.T. de FWGetText). A senha nunca é gravada em texto puro (hash SHA-256).

Testes

advplc run tests/db_test.prw
advplc run tests/login_test.prw
advplc run tests/fechamento_test.prw
advplc run tests/pagamento_test.prw
advplc run tests/malas_test.prw
advplc run tests/relatorios_test.prw
advplc run tests/portal_test.prw
advplc run tests/contabil_test.prw             # testes unitários do sistema contábil
advplc run tests/contabil_e2e_test.prw         # teste end-to-end: fluxo completo

Mala direta (envio real de e-mail)

GcMalaDireta(cCompetencia) envia uma mensagem personalizada por condômino com cobrança não paga na competência. Configuração via variáveis de ambiente — não GetMV(), que é um stub no AdvPP (sempre retorna o valor padrão, nunca lê configuração real):

export GESCON_SMTP_HOST=smtp.exemplo.com
export GESCON_SMTP_PORT=587       # opcional, default 587
export GESCON_SMTP_USER=usuario   # opcional, sem auth se vazio
export GESCON_SMTP_PASS=senha
export GESCON_SMTP_FROM=gescon@seucondominio.com

Sem GESCON_SMTP_HOST, GcMalaDireta não tenta enviar nada e retorna 0 (comportamento seguro por padrão).

Escopo

Plano 1 (v1): login, cadastros (unidades, condôminos, despesas), fechamento mensal (rateio por fração ideal), cobranças + registrar pagamento, mala direta, relatórios (balancete, inadimplência, extrato, despesas por categoria).

Plano 2: senha mascarada (FWGetText bIsPassword), boleto bancário (Itaú/Bradesco, código de barras e linha digitável), gestão de usuários (criar admin, gerar/revogar token temporário), portal do condômino (token-based read-only access).

Limitações conhecidas

• A tela de Cobranças permite editar/excluir registros livremente pela UI (mesmo FWMBrowse editável dos demais cadastros) — a garantia de "valor travado no fechamento" é imposta pela lógica de negócio, não pela UI. Aceitável para a v1 (login único, uso pessoal/piloto). Ver docs/ARQUITETURA.md para o motivo técnico.
• Os relatórios também são telas de FWMBrowse — dá pra clicar Incluir/Alterar/Excluir neles, mas não faz sentido (o conteúdo é recalculado do zero na próxima abertura).