backendDonMarco/README.md

Don Marco — Administración Financiera (LAN)

Aplicación web multiusuario para gestión de ingresos (ventas, servicios, alquileres), egresos (gastos diarios/fijos), personal y reportes consolidados. Pensada para operar en la red local de una pequeña empresa con un servidor central.

1. Stack tecnológico recomendado

Capa	Tecnología	Motivo
Frontend	React 18 + Vite	UI rápida, componentes reutilizables para planillas dinámicas
Backend	Node.js + Express	API REST ligera, fácil de mantener en LAN
Base de datos	SQLite (better-sqlite3)	Almacenamiento local en el servidor, sin instalar MySQL/PostgreSQL
Auth	JWT + bcrypt	Sesiones stateless, contraseñas hasheadas
Despliegue	Docker Compose + Nginx	Un solo comando en el servidor de la red

Nota: Aunque mencionaste “almacenamiento local”, para multiusuario en red conviene SQLite en el servidor (no localStorage del navegador), para que todos vean los mismos datos. El token JWT sí se guarda en localStorage del cliente.

2. Estructura del proyecto

DonMarcoBackend/
├── docker-compose.yml
├── README.md
├── .env.example
├── backend/
│   ├── Dockerfile
│   ├── package.json
│   └── src/
│       ├── index.js
│       ├── db.js
│       ├── seed.js
│       ├── middleware/auth.js
│       ├── routes/
│       │   ├── auth.js
│       │   ├── users.js
│       │   ├── sheets.js
│       │   └── reports.js
│       └── utils/calculations.js
└── frontend/
    ├── Dockerfile
    ├── nginx.conf
    ├── package.json
    ├── vite.config.js
    └── src/
        ├── App.jsx
        ├── api/client.js
        ├── context/AuthContext.jsx
        ├── components/
        │   ├── Layout.jsx
        │   ├── IngresoSheet.jsx
        │   ├── GastoSheet.jsx
        │   └── PersonalSheet.jsx
        ├── pages/
        │   ├── LoginPage.jsx
        │   ├── HomePage.jsx
        │   ├── ReportesPage.jsx
        │   └── AdminPage.jsx
        ├── utils/calc.js
        └── styles/global.css

3. Credenciales por defecto

Usuario	Contraseña	Rol
JEFE	MACAN	Superusuario / administrador

Cambie la contraseña del JEFE en producción desde el panel de administración o actualizando la base de datos.

4. Funcionalidades implementadas

• Login seguro y menú con pestañas (Ventas, Servicios, Alquileres, Gastos, Personal, Reportes, Salir).
• Panel de administración: crear usuarios, contraseñas y permisos ver/editar por planilla.
• Planillas con filas en blanco al inicio y botón + para agregar líneas ilimitadas.
• Cálculos automáticos: Precio Total, Utilidad, totales de cierre.
• Gastos con clasificación diario / fijo / variable.
• Personal: hasta 10 mensualizados y 5 eventuales por registro.
• Reportes diario, semanal y mensual con filtro de fechas y selección de planillas.
• Cierre semanal de gastos diarios y consolidado mensual en reportes.

5. Ejecución con Docker (recomendado en el servidor LAN)

Primera vez o actualización (importante: usar --no-cache)

Si no ve la pestaña "Cierre de Gestión", las imágenes Docker están viejas. Debe reconstruir sin caché:

Windows (PowerShell):

cd DonMarcoBackend
.\docker-update.ps1

Linux / Git Bash:

cd DonMarcoBackend
chmod +x docker-update.sh
./docker-update.sh

Manual:

docker compose down
docker compose build --no-cache
docker compose up -d

Verificar que Docker tiene la versión correcta

curl http://localhost:4000/api/health

Debe responder "version": "1.2.0" y "features": ["historial-gestiones", "cierre-gestion", ...].

En el navegador (http://IP-DEL-SERVIDOR:8888 por defecto):

• Pestaña Administración (solo usuario JEFE) → sección Cierre de gestión
• Cada planilla tiene barra lateral con gestiones anteriores (solo lectura)
• Al pie: Don Marco v1.2.0 — Historial de gestiones (Docker)

Acceso en la red

• Web: http://IP-DEL-SERVIDOR:8888 (puerto configurable en .env → DONMARCO_WEB_PORT)
• API: http://IP-DEL-SERVIDOR:4000/api/health

Cierre de gestión (solo JEFE)

1. Ingresar como JEFE / MACAN
2. Clic en Administración (menú superior)
3. En Cierre de gestión, elegir el último día del mes → Cerrar gestión
4. La planilla principal muestra solo la gestión actual; el historial está en la barra lateral (solo lectura)
5. Tras el cierre, los usuarios cargan filas nuevas con el botón +

Los datos en SQLite se conservan en el volumen donmarco_data al actualizar Docker.

6. Desarrollo local (sin Docker)

Terminal 1 — API:

cd backend
npm install
npm run dev

Terminal 2 — Web:

cd frontend
npm install
npm run dev

Abrir http://localhost:3000 (el proxy de Vite redirige /api al puerto 4000).

7. Variables de entorno

Copie .env.example a .env y defina al menos:

JWT_SECRET=un-secreto-largo-unico

En Docker, JWT_SECRET se lee desde el entorno del host o del archivo .env junto a docker-compose.yml.

8. Fórmula de reportes

Para diario, semanal y mensual (en el rango de fechas seleccionado):

Resultado = (Ventas + Alquileres + Servicios) − Total Gastos − Total Personal

El sistema indica UTILIDAD o PÉRDIDA según el signo del resultado neto.

---

Desarrollado como base funcional lista para ampliar (exportación PDF, respaldos automáticos, HTTPS con certificado interno, etc.).