# Gestor — Software de Gestión Financiera y Fiscal para Empresas Angolanas

## Descripción
Aplicación de escritorio para gestión financiera y fiscal completa de PMEs (pequeñas y medianas empresas) en Angola. Cubre lançamentos, tesorería, facturação eletrónica conforme Decreto 71/25, IVA, IRT, INSS, folha salarial, contas a pagar, dívidas y relatórios fiscais. Diseñado para uso local en red empresarial — un PC servidor central, varios PCs cliente sin conocimientos técnicos requeridos.

## Cliente
Empresas angolanas pequeñas y medianas (4-5 empleados típico). Producto comercial — entregado mediante dos instaladores `.exe` profesionales (servidor + cliente) que el dueño instala sin tocar línea de comandos.

## Año
2026

## Tipo de proyecto
Aplicación web full-stack empaquetada como software de escritorio Windows nativo — desarrollo completo (arquitectura + programación + empaquetado + despliegue local LAN)

## Funcionalidades principales

### Módulos contables
- Lançamentos (transacciones manuales con IVA, categorías, contas, parceiros)
- Tesorería multi-conta (caja, banco, etc.) con movimentos consolidados
- Contas a pagar (despesas pendentes con vencimentos)
- Despesas fixas recorrentes (auto-geração mensal)
- Dívidas (a pagar / a receber) con histórico de pagamentos
- Facturação electrónica con 7 séries legales (FT, FR, NC, ND, FAC, AVR, ORC) conforme Decreto 71/25
- Diário financeiro consolidado

### Gestión empresarial
- Clientes y fornecedores con saldo aberto
- Funcionários com folha salarial mensal (cálculo IRT + INSS)
- Prestadores de serviços com retenções
- Categorias receita/despesa configuráveis

### Fiscalidade Angola
- IVA (regimes: Geral, Simplificado, Exclusão) — cálculo automático mensal/trimestral
- IRT 7 escalões (cálculo progressivo)
- INSS empresa + funcionário
- Encerramento de períodos fiscais com bloqueio retroactivo
- Relatórios fiscais exportáveis

### Administração
- Setup wizard inicial (criar empresa + conta admin)
- Gestão de utilizadores com perfis (owner, admin, employee)
- Reset de senha (UI + CLI fallback offline)
- Configuração de backup (pasta secundária NAS/USB)
- Auditoria completa de operações

### Robustez operacional
- Auto-discovery do servidor em LAN (cliente conecta sem configurar IP)
- Backup diário automático às 03:00 + manual sob demanda
- Serviço Windows resiliente (auto-restart em 3 camadas: WinSW + SCM + watchdog)
- Modo standalone (Chrome/Edge `--app=`) — aparência de programa nativo, sem abas nem barra URL

## Stack tecnológico
- **Frontend:** Next.js 16, React 19, TypeScript, Tailwind CSS 4
- **Backend:** Next.js API Routes (Node.js 22 LTS embutido)
- **Base de dados:** SQLite + WAL mode + better-sqlite3 nativo
- **ORM:** Prisma 7 con adapter better-sqlite3
- **Auth:** NextAuth v5 con Credentials + JWT + bcrypt
- **Service de descoberta:** mDNS / Bonjour (`gestor.local`) + scan LAN paralelo .NET
- **Empaquetado:** Inno Setup 6 (Pascal) — dois instaladores separados
- **Service Wrapper:** WinSW 3 (3 camadas auto-restart)
- **Tests:** Vitest (27 testes unitários)

## Arquitectura de despliegue

```
Servidor (1 PC dedicado)             Clientes (PCs empleados)
├── Gestor-Servidor-Setup.exe         ├── Gestor-Cliente-Setup.exe (~2 MB)
│   (~116 MB self-contained)          │
├── Node 22 portable                  ├── discover.ps1 (auto-find LAN)
├── better-sqlite3 pre-built          ├── launcher --app=URL standalone
├── Service Gestor (Next.js)          └── Atalho escritorio
├── Service GestorMDNS (publisher)
├── Watchdog Task Scheduler
└── Backup Task Scheduler (03:00)
```

## Decisiones técnicas destacadas
- **SQLite con WAL** sobre Postgres: zero-config, single-tenant local, resistente a cortes de luz
- **Next.js custom proxy.ts** (no middleware) — versión 16 breaking changes
- **Auto-discovery LAN** combinado: mDNS (95% dos casos) + scan TCP 254 IPs (fallback)
- **Modo `--app=` Chrome/Edge**: app web indistinguible de software nativo para usuarios
- **Service Wrapper triple defense**: imposible de matar accidentalmente, sobrevive crashes/reinicios/kills
- **Empaquetado profesional**: usuario angolano de 50 años sin conocimientos técnicos puede instalar y usar — zero CMD, zero `.env`, zero npm

## Material visual (em `imagens/`)
- `icon.svg` / `icon-512.png` / `icon-192.png` — Ícone "árvore" do Gestor (PWA + instalador + ventana standalone)

## Capturas a recolher
- Login standalone (modo `--app=`, sem abas)
- Dashboard com sidebar (módulos + saldo clientes/fornecedores)
- Lançamentos (form com IVA + conta + categoria)
- Facturação (criar fatura + impressão A4)
- IVA mensual (cálculo + encerramento)
- Folha salarial (cálculo IRT + INSS)
- /admin/users (gestão de utilizadores)
- /admin/configuracao (backup + retenção)
- Wizard do instalador `.exe` (passos com pasta backup)
- Atalhos no menú Iniciar (Iniciar/Parar/Reiniciar Servidor, Backup manual, Resetar Senha)