Skip to content

beerandbytes/facturas

BranchesTags

Repository files navigation

InvoicePal - Sistema de Gestión de Facturas

InvoicePal Deno Fresh License

Una aplicación web moderna y completa para gestionar facturas, clientes y generar informes de facturación.

Características • Instalación • Uso • Despliegue

📋 Tabla de Contenidos

✨ Características

  • 📄 Gestión Completa de Facturas

    • Crear, editar y visualizar facturas con todos los datos necesarios
    • Numeración automática por serie
    • Múltiples líneas de factura con diferentes tipos de IVA
    • Cálculo automático de totales e impuestos
    • Vista previa optimizada para impresión
    • Exportación a Excel (XLSX)

  • 👥 Gestión de Clientes

    • Directorio completo de clientes con datos de facturación
    • Búsqueda rápida de clientes
    • Reutilización de datos al crear facturas
    • Edición y eliminación de clientes

  • 📊 Informes y Análisis

    • Dashboard con KPIs en tiempo real
    • Estadísticas de ventas, IVA devengado y ticket medio
    • Gráficos de evolución mensual
    • Distribución de tipos de IVA

  • 🔐 Sistema de Roles y Permisos

    • Tres niveles de acceso: Administrador, Emisor y Consulta
    • Control granular de permisos
    • Gestión de usuarios por administradores

  • 💾 Exportación y Backup

    • Exportación de facturas individuales a Excel
    • Backup completo en formato JSON
    • Restauración de datos

  • 🎨 Interfaz Moderna

    • Diseño responsive y adaptable
    • Interfaz intuitiva y fácil de usar
    • Optimizada para impresión
    • Navegación clara y organizada

🛠️ Tecnologías Utilizadas

  • Deno - Runtime de JavaScript/TypeScript moderno
  • Fresh - Framework web full-stack para Deno
  • Preact - Biblioteca de UI ligera y rápida
  • Tailwind CSS - Framework CSS utility-first
  • DaisyUI - Componentes para Tailwind CSS
  • Deno KV - Base de datos key-value integrada
  • SheetJS (XLSX) - Exportación a Excel

📦 Requisitos Previos

Antes de instalar InvoicePal, asegúrate de tener instalado:

  • Deno versión 1.40 o superior

    # Verificar instalación
deno --version

  • Un editor de código (recomendado: VS Code con extensión Deno)

  • Navegador web moderno (Chrome, Firefox, Safari, Edge)

🚀 Instalación

1. Clonar el Repositorio

git clone https://github.com/tu-usuario/facturas.git
cd facturas

2. Instalar Dependencias

Las dependencias se descargan automáticamente al ejecutar Deno. No es necesario ejecutar npm install o similar.

3. Iniciar el Servidor de Desarrollo

deno task start

El servidor se iniciará en http://localhost:8000

4. Acceder a la Aplicación

Abre tu navegador y visita:

http://localhost:8000

⚙️ Configuración Inicial

1. Registro de Usuario

La primera vez que uses la aplicación, necesitas crear una cuenta:

  1. Ve a la página de registro (/auth/register)
  2. Completa el formulario con:
    • Nombre de usuario: Elige un nombre único
    • Contraseña: Crea una contraseña segura
    • Rol: Selecciona el rol inicial (recomendado: admin para el primer usuario)
  3. Haz clic en "Registrarse"

⚠️ Importante: El primer usuario debería tener rol admin para poder gestionar otros usuarios y configurar la aplicación.

2. Iniciar Sesión

  1. Ve a la página de login (/auth/login)
  2. Ingresa tu nombre de usuario y contraseña
  3. Haz clic en "Iniciar Sesión"

3. Configurar Datos del Emisor

Antes de crear facturas, configura los datos de tu empresa:

  1. Inicia sesión en la aplicación
  2. Ve a Configuración en el menú lateral
  3. Completa los siguientes campos:
    • Nombre/Razón Social: Nombre completo de tu empresa
    • NIF/CIF: Número de identificación fiscal
    • Dirección:
      • Calle
      • Código postal
      • Población
      • Provincia
      • País
  4. Haz clic en "Guardar Configuración"

Estos datos se usarán automáticamente al crear nuevas facturas.

📖 Uso de la Aplicación

Dashboard

El dashboard es la página principal donde puedes ver:

KPIs (Indicadores Clave de Rendimiento)

  • Ventas del Trimestre: Suma total de todas las facturas
  • IVA Devengado: Total de IVA recaudado
  • Facturas Emitidas: Número total de facturas creadas

Acciones Rápidas

  • 📄 Nueva Factura: Acceso directo para crear una factura
  • 💾 Backup JSON: Descargar todos los datos de la aplicación en formato JSON
  • 👥 Gestionar Usuarios: Solo visible para administradores

Gestión de Facturas

Crear una Nueva Factura

  1. Acceso: Desde el dashboard, haz clic en "Nueva Factura" o ve a Facturas → Nueva Factura

  2. Datos del Destinatario:

    • Nombre/Razón Social: Nombre completo del cliente
    • NIF/CIF: Número de identificación fiscal del cliente
    • Dirección completa: Calle, código postal, población, provincia y país
    • Email: (Opcional) Email del cliente para envío

  3. Datos de la Factura:

    • Serie: Letra o código de serie (ej: "F", "A", "B", "F25")
    • Número: Se genera automáticamente si se deja vacío (secuencial por serie)
    • Fecha de expedición: Fecha en que se emite la factura
    • Fecha de vencimiento: (Opcional) Fecha límite de pago

  4. Líneas de Factura:

    • Descripción: Descripción del producto o servicio
    • Cantidad: Cantidad de unidades
    • Precio unitario: Precio por unidad
    • Tipo de IVA: Selecciona entre 21%, 10%, 4%, 0% o exento
    • Descuento: (Opcional) Porcentaje de descuento aplicado

    Puedes agregar múltiples líneas haciendo clic en "Agregar Línea"

  5. Guardar: Haz clic en "Guardar Factura" para almacenarla

💡 Consejo: Si guardas clientes frecuentes en la sección de Clientes, podrás seleccionarlos rápidamente al crear facturas, ahorrando tiempo.

Ver Facturas

  1. Ve a Facturas en el menú lateral
  2. Verás una tabla con todas las facturas emitidas mostrando:
    • ID de la factura (serie-número)
    • Fecha de expedición
    • Cliente destinatario
    • Importe total
  3. Haz clic en el icono de ojo (👁️) para ver los detalles completos de una factura

Editar una Factura

  1. Ve a la página de detalles de la factura
  2. Haz clic en el botón "Editar"
  3. Modifica los campos necesarios
  4. Guarda los cambios

Nota: Solo usuarios con rol admin o emisor pueden crear y editar facturas.

Exportar Factura a Excel

  1. Ve a la página de detalles de la factura
  2. Haz clic en el botón "Exportar XLS"
  3. Se descargará un archivo Excel con todos los datos de la factura

Imprimir Factura

  1. Ve a la página de detalles de la factura
  2. Haz clic en el botón "Imprimir"
  3. Se abrirá el diálogo de impresión del navegador
  4. La vista se optimiza automáticamente para impresión

Eliminar una Factura

  1. Ve a la página de detalles de la factura
  2. Haz clic en el botón "Eliminar"
  3. Confirma la eliminación
  4. ⚠️ Advertencia: Esta acción no se puede deshacer

Gestión de Clientes

Agregar un Cliente

  1. Ve a Clientes en el menú lateral
  2. Haz clic en el botón "Nuevo Cliente"
  3. Completa el formulario:
    • Nombre/Razón Social: (Obligatorio)
    • NIF/CIF: (Obligatorio)
    • Dirección completa: Calle, código postal, población, provincia, país
    • Email: (Opcional)
    • Teléfono: (Opcional)
  4. Haz clic en "Guardar Cliente"

Ver Clientes

En la página de Clientes verás una tabla con:

  • Nombre/Razón Social
  • NIF/CIF
  • Email
  • Acciones disponibles (ver detalles, editar, eliminar)

Buscar Clientes

  1. En la página de Clientes, usa el campo de búsqueda
  2. Puedes buscar por nombre, NIF o email
  3. Los resultados se filtran automáticamente

Editar un Cliente

  1. En la tabla de clientes, haz clic en el icono de editar
  2. Modifica los campos necesarios
  3. Guarda los cambios

Eliminar un Cliente

  1. En la tabla de clientes, haz clic en el icono de eliminar
  2. Confirma la eliminación
  3. ⚠️ Advertencia: Esta acción no se puede deshacer

✅ Beneficio: Al tener clientes guardados, al crear una factura podrás seleccionarlos desde un listado, ahorrando tiempo y evitando errores de escritura.

Informes y Análisis

La sección de Informes te proporciona una visión detallada de tu facturación:

KPIs Disponibles

  • Ingresos Totales: Suma de todas las facturas emitidas
  • IVA Recaudado: Total de IVA devengado en todas las facturas
  • Número de Facturas: Cantidad total de facturas emitidas
  • Ticket Medio: Promedio de importe por factura (Ingresos Totales / Número de Facturas)

Gráficos y Visualizaciones

  • Evolución Mensual: Gráfico de barras mostrando las ventas por mes
  • Distribución de IVA: Visualización del tipo de IVA más utilizado

💡 Uso: Utiliza estos informes para analizar tus ventas, planificar tu negocio y preparar declaraciones de IVA.

Configuración

En la página de Configuración puedes:

Editar Datos del Emisor

  1. Actualiza la información de tu empresa
  2. Modifica cualquier campo (nombre, NIF, dirección)
  3. Guarda los cambios

Zona de Peligro

  • Borrar todos los datos:
    • Esta acción elimina permanentemente todas las facturas, clientes y configuraciones
    • ⚠️ ¡Usa con precaución!
    • Se recomienda hacer un backup antes de usar esta función

Administración de Usuarios

Solo disponible para usuarios con rol admin.

Acceder a la Administración

  1. Desde el dashboard, haz clic en "Gestionar Usuarios"
  2. O accede directamente a /admin/users

Ver Usuarios

Verás una lista de todos los usuarios registrados con:

  • Nombre de usuario
  • Rol actual
  • Acciones disponibles

Cambiar el Rol de un Usuario

  1. En la lista de usuarios, localiza el usuario que deseas modificar
  2. Selecciona el nuevo rol desde el menú desplegable:
    • admin: Acceso completo
    • emisor: Puede crear y editar facturas
    • consulta: Solo lectura
  3. El cambio se aplica automáticamente

Eliminar un Usuario

  1. En la lista de usuarios, haz clic en el botón de eliminar
  2. Confirma la eliminación
  3. ⚠️ Advertencia: Eliminar un usuario no elimina las facturas que haya creado. Los datos permanecen en el sistema.

🔐 Roles y Permisos

La aplicación tiene tres roles con diferentes permisos:

Permiso Admin Emisor Consulta
Crear facturas ✅ ✅ ❌
Editar facturas ✅ ✅ ❌
Eliminar facturas ✅ ✅ ❌
Ver facturas ✅ ✅ ✅
Exportar facturas ✅ ✅ ✅
Gestionar clientes ✅ ✅ ✅
Ver informes ✅ ✅ ✅
Configurar aplicación ✅ ❌ ❌
Gestionar usuarios ✅ ❌ ❌
Exportar datos (backup) ✅ ✅ ✅

Descripción de Roles

  • 👑 Administrador (admin)

    • Acceso completo al sistema
    • Puede gestionar usuarios y configurar la aplicación
    • Ideal para propietarios y administradores del sistema

  • 📝 Emisor (emisor)

    • Puede crear y editar facturas
    • Puede gestionar clientes
    • No puede configurar la aplicación ni gestionar usuarios
    • Ideal para empleados que emiten facturas

  • 👁️ Consulta (consulta)

    • Solo puede ver facturas y clientes
    • No puede crear ni editar nada
    • Puede exportar datos
    • Ideal para contadores o auditores

🚀 Despliegue

Despliegue en Producción

1. Construir la Aplicación

deno task build

Esto generará los archivos optimizados en el directorio _fresh/.

2. Ejecutar en Producción

deno task preview

O directamente:

deno run -A main.ts

3. Variables de Entorno (Opcional)

Puedes crear un archivo .env para configurar variables de entorno:

PORT=8000
DENO_KV_PATH=./kv_data

4. Despliegue en Servicios Cloud

Deno Deploy
  1. Conecta tu repositorio a Deno Deploy
  2. Configura el comando de inicio: deno run -A main.ts
  3. Despliega automáticamente
Otros Servicios
  • Fly.io: Configura un Dockerfile o usa el runtime de Deno
  • Railway: Conecta el repositorio y configura el comando de inicio
  • Heroku: Usa un buildpack de Deno

Nota: Para producción, considera usar Deno KV remoto en lugar de local para mejor persistencia.

🛠️ Comandos Disponibles

# Iniciar servidor de desarrollo (con hot-reload)
deno task start

# Construir para producción
deno task build

# Previsualizar build de producción
deno task preview

# Ejecutar tests
deno task test

# Verificar código (formato, lint, tipos)
deno task check

# Actualizar Fresh
deno task update

📁 Estructura del Proyecto

facturas/
├── components/          # Componentes reutilizables
│   ├── Dashboard/      # Componentes del dashboard
│   └── Landing/        # Componentes de la página de inicio
├── islands/            # Componentes interactivos (Preact Islands)
├── routes/             # Rutas de la aplicación
│   ├── api/           # Endpoints API
│   ├── auth/          # Autenticación
│   ├── facturas/      # Gestión de facturas
│   ├── clientes/      # Gestión de clientes
│   └── admin/         # Administración
├── src/               # Código fuente
│   ├── auth/         # Sistema de autenticación y roles
│   ├── db/           # Acceso a base de datos (Deno KV)
│   ├── types/        # Tipos TypeScript
│   └── utils/        # Utilidades
├── static/           # Archivos estáticos (CSS, imágenes)
├── tests/            # Tests unitarios
├── deno.json         # Configuración de Deno
├── fresh.config.ts   # Configuración de Fresh
├── main.ts           # Punto de entrada de producción
└── dev.ts            # Punto de entrada de desarrollo

🆘 Solución de Problemas

No puedo iniciar sesión

  • Verifica que el usuario existe
  • Asegúrate de usar la contraseña correcta
  • Si olvidaste la contraseña, un administrador puede ayudarte o puedes crear un nuevo usuario

No veo la opción de crear facturas

  • Verifica tu rol de usuario
  • Solo usuarios admin y emisor pueden crear facturas
  • Contacta a un administrador para cambiar tu rol

Los datos no se guardan

  • Verifica que tienes permisos de escritura en el directorio
  • Revisa la consola del navegador para errores
  • Asegúrate de que el servidor está corriendo correctamente
  • Verifica que Deno KV tiene permisos para escribir

Error al exportar a Excel

  • Asegúrate de que el navegador permite descargas
  • Verifica que no hay bloqueadores de pop-ups activos
  • Prueba con otro navegador

El servidor no inicia

  • Verifica que Deno está instalado correctamente: deno --version
  • Asegúrate de tener permisos de red: deno run -A
  • Revisa que el puerto 8000 no esté en uso
  • Verifica los logs en la consola

📝 Notas Importantes

  • Almacenamiento: Los datos se guardan en Deno KV (base de datos local por defecto)
  • Backup: Es recomendable hacer backups regulares usando la función "Backup JSON" desde el dashboard
  • Seguridad: Las contraseñas se almacenan de forma segura usando hash
  • Sesiones: Las sesiones se mantienen mientras el navegador esté abierto
  • Persistencia: En producción, considera usar Deno KV remoto para mejor persistencia y escalabilidad

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

  1. Fork el proyecto
  2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
  3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
  4. Push a la rama (git push origin feature/AmazingFeature)
  5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

InvoicePal - Simplificando la gestión de facturas

Hecho con ❤️ usando Deno y Fresh

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages