Factureo

📄 Descripción del proyecto

Factureo es una plataforma web para PyMEs que centraliza inventario, clientes, ventas y nómina ligera. El backend está construido con Flask + MongoDB, la interfaz usa Bootstrap 5 con CSS modular y los procesos de nómina se automatizan con tareas asíncronas y generación de PDF. El objetivo es ofrecer un flujo de trabajo claro, métricas rápidas y pantallas accesibles en desktop y mobile.

Características principales

• Autenticación local y social (Google/Microsoft) con manejo de roles.
• Módulos de Inventario, Clientes y Ventas con reportes y comprobantes PDF.
• Dashboard con métricas en tiempo real y gestión de perfil (avatar, tema, datos de empresa).
• Módulo de nómina con cálculo automático, plantillas PDF y workers RQ/Redis para envíos por correo.
• Páginas públicas (landing, contacto, noticias, términos/privacidad) con componentes reutilizables.

⚙️ Requisitos

• Python 3.10 o superior (necesario).
• MongoDB Atlas o instancia MongoDB 4.4+ accesible vía MONGO_URI.
• Redis opcional para colas RQ (requerido para envíos de nómina).
• Node.js 18+ opcional si se desea compilar assets adicionales (no requerido en la configuración actual).
• PowerShell 5.1+ en Windows o un shell equivalente (bash/zsh) en otros sistemas.

🚀 Instrucciones de instalación y ejecución

1. Clonar el repositorio

git clone https://github.com/andresforero1033/factureox.git
cd factureox/factureo_backend

2. Crear y activar un entorno virtual

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

• Copia .env.example a .env.
• Ajusta los valores obligatorios:

  MONGO_URI=mongodb+srv://<usuario>:<password>@<cluster>.mongodb.net/factureo
  SECRET_KEY=<clave-aleatoria>
  SESSION_COOKIE_NAME=factureo_session

• Variables opcionales: REDIS_URL, MAIL_*, credenciales OAuth.

5. Inicializar índices y datos (opcional)

python .\scripts\init_db.py
python .\scripts\seed_data.py  # carga datos de muestra

6. Ejecutar la aplicación

python app.py

Accede en http://127.0.0.1:5000.

QA y desarrollo

• Linter: pip install -r requirements-dev.txt && ruff check .
• Tests: pytest -q (requiere MongoDB disponible; para aislar usa fixtures o mocks).
• Worker RQ (si usas REDIS_URL): python -m rq worker -u %REDIS_URL% nomina.

📁 Estructura de carpetas explicada

• factureo_backend/app.py: punto de entrada Flask (crea y lanza la app).
• factureo_backend/config.py: configuración general y lectura de variables .env.
• factureo_backend/db.py: helper para obtener colecciones MongoDB.
• factureo_backend/factureo/
  • __init__.py: factoría create_app, registro de blueprints y OAuth.
  • blueprints/: controladores Flask segmentados por dominio (auth, clientes, ventas, etc.).
  • services/: capa de acceso a datos (MongoService, validaciones ObjectId).
  • payroll/: lógica de nómina (cálculo, PDF, esquemas Pydantic).
  • tasks/: tareas asíncronas (cola RQ para nómina).
• factureo_backend/templates/: vistas Jinja2 con estructura limpia de Bootstrap.
• factureo_backend/static/: CSS modular, JS por componente y assets.
• factureo_backend/scripts/: utilidades para inicializar índices, backfill y datos seed.
• tests/: pruebas PyTest para smoke tests y cálculos de nómina.
• CHANGELOG.md: historial de cambios.

🔗 Rutas principales (API o vistas)

• GET / – Landing pública con noticias destacadas.
• GET|POST /login – Formulario de autenticación tradicional.
• GET|POST /register – Registro de cuentas.
• GET /dashboard – Panel con métricas rápidas.
• GET|POST /clientes/ – Listado y filtros de clientes.
• POST /clientes/crear – Alta de clientes.
• GET|POST /inventario/ – Gestión de productos con filtros por término/categoría.
• POST /ventas/ – Registro de ventas y cálculo de totales.
• GET /ventas/comprobante/<id> – Comprobante HTML de venta.
• GET /ventas/comprobante/<id>/pdf – Descarga PDF del comprobante.
• GET|POST /contacto – Formulario de contacto público.
• GET /terminos y GET /privacidad – Páginas legales.
• Endpoints OAuth: /login/google, /auth/google/callback, /login/microsoft, /auth/microsoft/callback.

🧠 Explicación de los módulos principales

• Autenticación (factureo/blueprints/usuarios.py): maneja login local y social, registro, dashboard, perfil y recuperación de contraseña. Se apoya en MongoService para CRUD de usuarios.
• Inventario (factureo/blueprints/inventario.py): administra la colección productos, con campos clave (nombre, cantidad, precio, categoria, owner_id, etc.) y valida operaciones por usuario.
• Clientes (factureo/blueprints/clientes.py): gestiona la colección clientes (datos de contacto, identificación, estado, owner_id).
• Ventas (factureo/blueprints/ventas.py): opera sobre la colección ventas, agregando items, descuentos e impuestos; genera comprobantes HTML/PDF y sincroniza existencias en productos.
• Noticias (factureo/blueprints/noticias.py): CRUD básico para la colección news (título, resumen, autor, URL de imagen, flags published).
• Pagos de nómina (factureo/payroll/): core.py calcula devengados/deducciones, schemas.py valida entradas (empleados, periodos, timesheets) y pdf.py produce comprobantes.
• Servicios (factureo/services/mongo_service.py): capa genérica con manejo de errores, conversión segura de ObjectId y helpers CRUD; centraliza el acceso a MongoDB.
• Tareas (factureo/tasks/nomina.py): define jobs RQ para enviar comprobantes de nómina por correo; reutiliza la lógica de payroll y configura plantillas Jinja2 para emails.

---

¿Quieres contribuir? Abre un issue o PR. Si Factureo te resulta útil, una estrella al repositorio siempre suma.