# KAMBA — Sistema de Gestión para Gimnasios en Angola

## Descripción
Aplicación de escritorio para gestión completa de gimnasios en Angola. Controla socios, planes, suscripciones, pagos, transferencias, gastos, facturación electrónica, impuestos, nómina, prestadores de servicios y reportes financieros. Está pensada para operar localmente en Windows, con un PC servidor y varios PCs cliente conectados en la misma red LAN.

## Cliente
Gimnasios angolanos que necesitan una herramienta local, simple de instalar y adaptada a la operación diaria del negocio. Producto empaquetado como software Windows con instalador de servidor y cliente.

## Año
2026

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

## Funcionalidades principales

### Gestión de socios
- Cadastro de socios con documento, contacto, fecha de nacimiento, género, foto, notas médicas y estado activo
- Perfil de socio con historial y edición de datos
- Planes configurables con duración, precio, IVA y estado activo
- Suscripciones con inicio, fin, estado, precio al momento de creación y renovación
- Cancelación de suscripciones con motivo, fecha y posible reembolso

### Operación del gimnasio
- Dashboard con KPIs de socios activos, vencidos, ingresos, gastos y resultado neto
- Registro y consulta de transferencias/pagos vinculados a la operación
- Gestión de categorías de ingresos y gastos
- Control de gastos con proveedor, método de pago, IVA soportado y notas

### Facturación e impuestos Angola
- Facturación electrónica con series y numeración por tipo documental
- Facturas, edición, detalle e impresión A4
- Notas de crédito vinculadas a facturas originales
- Cálculo de IVA por régimen y generación de periodos fiscales
- Módulo de impuestos con IVA, IRT, INSS y retenciones aplicables

### Equipo y prestadores
- Gestión de empleados con cargo, salario bruto, fecha de inicio y estado activo
- Folha de salários con cálculo de IRT, INSS trabajador, INSS patronal, salario neto y estado de pago
- Gestión de prestadores de servicios con NIF, actividad y cuenta bancaria
- Pagos a prestadores con retención, monto bruto, monto neto y fecha de pago

### Administración
- Setup inicial para crear empresa y usuario administrador
- Login con NextAuth y roles de usuario
- Gestión de usuarios desde panel admin
- Configuración de empresa, régimen fiscal e IVA por defecto
- Auditoría de operaciones por entidad, usuario y fecha

### Robustez operacional
- Base de datos SQLite local con WAL mode para instalación simple y resistente
- Cliente con `discover.ps1` para localizar el servidor por `kamba.local` y fallback TCP en LAN
- Instaladores Inno Setup separados para servidor y cliente
- Servidor preparado para ejecutarse como servicio Windows
- Interfaz rediseñada en portugués angolano con sistema visual propio KAMBA

## Stack tecnológico
- **Frontend:** Next.js 16, React 19, TypeScript, Tailwind CSS 4
- **UI:** Lucide React, componentes propios (`ActionButton`, `Badge`, `KPICard`, `Sidebar`, `KambaLogo`)
- **Backend:** Next.js API Routes
- **Base de datos:** SQLite + WAL mode + better-sqlite3
- **ORM:** Prisma 7 con adapter better-sqlite3
- **Auth:** NextAuth v5 con Credentials + JWT + bcrypt
- **Fiscalidad:** lógica propia para IVA, IRT, INSS, facturación y notas de crédito
- **Exportación:** xlsx / xlsx-js-style para reportes
- **Descubrimiento LAN:** mDNS / `kamba.local` + scan TCP por PowerShell
- **Empaquetado:** Inno Setup 6 — instaladores separados servidor + cliente
- **Tests:** Vitest configurado

## Arquitectura de despliegue

```
Servidor (1 PC dedicado)             Clientes (PCs empleados)
├── Kamba-Servidor-Setup.exe          ├── Kamba-Cliente-Setup.exe
│   (self-contained)                  │
├── Next.js app                       ├── discover.ps1 (auto-find LAN)
├── SQLite + better-sqlite3           ├── conexión a kamba.local / IP LAN
├── Service Windows                   └── Atalho escritorio
├── API Routes
├── Prisma migrations
└── Base de datos local kamba.db
```

## Decisiones técnicas destacadas
- **SQLite con WAL**: instalación local sin servidor externo, ideal para gimnasios pequeños y medianos
- **Next.js empaquetado**: la misma app funciona como web full-stack y como software de escritorio instalado
- **Separación servidor/cliente**: el cliente es ligero y solo descubre/conecta al servidor en la LAN
- **mDNS + fallback TCP**: reduce configuración manual para usuarios sin perfil técnico
- **Prisma 7 + better-sqlite3**: acceso tipado y rápido a una base local persistente
- **Sistema visual KAMBA**: rediseño con logo propio, sidebar oscuro, acento naranja, tipografía Inter/Outfit e iconografía Lucide
- **Fiscalidad angolana integrada**: IVA, IRT, INSS, retenciones y documentos fiscales tratados como parte central del producto
- **Modelo multi-área**: socios, finanzas, facturación, equipo y administración comparten empresa, usuarios y auditoría

## Material visual (em `imagens/`)
- `logo-kamba.svg` — Logo completo KAMBA
- `logo-kamba-icon.svg` — Ícono KAMBA para app, sidebar e instalador

## Capturas a recolher
- Login con logo KAMBA y card oscuro
- Dashboard con KPIs financieros y operacionales
- Lista de socios con búsqueda, estados y acciones
- Perfil de socio con suscripciones e historial
- Planes y creación/edición de suscripciones
- Facturas: lista, creación, detalle e impresión A4
- Impuestos: IVA/IRT/INSS y generación de periodos
- Folha de salários con cálculo de salario neto
- Prestadores con pagos y retenciones
- Reportes financieros con exportación Excel
- Panel admin de usuarios y configuraciones
- Wizard de instalador servidor/cliente en Windows