K.I.M.R.A. (Kim-ra): Kivy Inventory Management and Reporting Application.

español | english

cómo su nombre lo indica, esto es como un simple crud, un crud con pasos extra, que fué desarrollado por mi matius54 por motivo de una evaluación universitaria y para entender el desarrollo de aplicaciones moviles usando kivy y kivymd, con sqlite como motor de base de datos

requisitos originales

• inicio de sesión
• registro de usuario
• control de inventario
• emisión de reportes
• buscador
• comunicación inter aplicación (wifi) (no implementado)

características técnicas

• base de datos usada sqlite3 en data.db
• hashing y validación de contraseñas realizada con bcrypt
• interfaz gráfica hecha con kivy y kivymd
• capacidad de exportar reportes en html y pdf con Jinja2 y weasyprint
• no se usó ningún archivo o string en el lenguaje llamado kv o kvlang de kivy, todos los widgets son construidos a través de instanciación y luego añadidos con add_widget() por motivos de diseño y control

funciones

• interfaz
  • modo oscuro modo claro configurable
  • feedback inmediato a través de snackbar
  • diálogos de confirmación en operaciones que modifican la base de datos
• usuarios
  • inicio de sesión para cada usuario
  • registro de usuarios
  • buscador
  • deshabitar (borrado lógico) y borrado real
• control de inventario
  • agrupación por categorías
  • buscador por categorías
• buscador
  • la barra de busqueda además de buscar incidencias del texto que escribas en todos los campos de texto también busca por id
• emisión de reportes
  • stock crítico
  • precio total
  • productos registrados
  • usuarios registrados
  • en formato pdf y html
• extra
  • creación automática de las tablas si no existen

pantallas

• auth
  • login: formulario de inicio de sesión
  • register: formulario de registro
• dashboard
  • product
    • list: muestra los elementos con capacidad de buscar
    • edit: permite editar un elemento
    • details: vista detallada con opciones de borrar o editar
    • create: permite añadir nuevos elementos
    • tagList: muestra las tags que existen y sus relaciones con el producto que se está editando
  • tag
    • list: muestra los elementos con capacidad de buscar
    • edit: permite editar un elemento
    • details: vista detallada con opciones de borrar o editar
    • create: permite añadir nuevos elementos
  • user
    • list: muestra los elementos con capacidad de buscar
    • edit: permite editar un elemento
    • details: vista detallada con opciones de borrar o editar
    • create: permite añadir nuevos elementos
  • config
    • main: pantalla principal
    • user: ajustes relacionados a la configuración del usuario
    • disabledUsers: lista de usuarios deshabilitados
    • detailsUsers: detalles de los usuarios deshabilitados
  • report
    • main: pantalla principal

estructura general

el proyecto sigue la estructura modelo, vista controlador (mvc)

• /libs: modelo, donde se realiza toda la interacción con la base de datos
• /views: vistas de toda la aplicación, incluidas las clases custom, dentro de /views/dashboard, el archivo screen.py define la clase de la que las otras pantallas del panel de control heredan, y cada pantalla de dashboard tiene un archivo index.py, me robé el término del desarrollo web, es el archivo que instancia y unifica las demás pantallas, se encarga de la gestión del screenmanager local y del flujo de información y eventos entre las pantallas
• main.py: aquí además de establecer la conexión a la base de datos y establecer la estructura de las pantallas, también es el controlador, se gestionan las conexiones y validaciones básicas de todas las operaciones que modifican la base de datos
• database.py: esta clase establece la conexión cargando schema.sql y luego guarda el objeto de conexión para su posterior uso por las clases modelo

¿cómo correrlo?

1. descarga el código de este repositorio, con un git clone, o descargándolo como zip y descomprimiendolo

git clone https://github.com/matius54/kimra

2. crea un venv (recomendable para evitar colisiones con otras dependencias que tengas instaladas), y ejecuta pip install -r requirements.txt, luego espera a que se descargue e instale todo

pip install -r requirements.txt

3. (opcional), para convertir html a pdf (habilitar la emisión de reportes en formato pdf) el sistema depende de weasyprint.exe para realizar la conversión, únicamente en windows, para hacerlo funcionar debes descargar el último binario disponible weasyprint-windows.zip desde este link y luego descomprimirlo y colocar el .exe en la raíz del proyecto
4. ejecuta main.py en la raíz del proyecto

python main.py

TO DO

el objetivo de este proyecto es ser un poco más que un crud, asi que faltaron algunas cosas

• i18n: (no implementado) internacionalización, traducir la interfaz a diferentes idiomas
• populate.py: (no implementado) un script para llenar la base de datos (quizá con faker o datos pregenerados) y poder hacer pruebas rápidamente
• image.py: (no implementado) desarrollar, procesar y mostrar imagenes en la interfaz directamente desde la base de datos, (sin depender de un directorio en almacenamiento local)
• buildozer: aún no es posible compilar a apk u otras distribuciones para otros sistemas operativos
• utilizar todo el modelo que se encuentra en schema.sql (aunque algunas tablas fueron pensadas para una extensión del proyecto)
• además del cambio de tema (modo oscuro/claro) también permitir el cambio de color (accent color)
• separar la lógica del controlador y validaciones fuera del main.py, idealmente a controllers/
• añadir patron middleware para las validaciones repetitivas
• si es posible no depender de weasyprint
• mejorar la estructura de las vistas, separar los widgets compuestos de los widgets simples
• definir una clase general para los index.py y así poder eliminar código repetido
• en general abstraer más dentro de las pantallas de /dashboard
• cambiar los campos reales (real) de la base de datos que representan valores monetarios y convertirlos a enteros (integer), para eliminar los errores de coma flotante
• implementar las funciones que quedaron fuera por falta de tiempo, como:
  • la opción de cambiar contraseña
  • la opción de habilitar usuario
  • desactivar tu propia cuenta
  • guardar reportes y gestionar los emitidos en la base de datos
  • mostrar el icono de la categoría del producto en la lista de productos
  • y algunas cosas más, ideas que no llegaron al código (aún)

licencia

• MIT: eres libre de hacer lo que quieras con éste código, analizarlo, usarlo como base para otro proyecto, integrarlo a otros proyectos, usarlo para entrenar modelos de IA, modificarlo o venderlo con fines comerciales o como parte de un producto, todo mientras operes dentro de la licencia mit, recuerda que sólo obtienes esto y nada, más, as is, :3
• se usaron parte de las plantillas proporcionadas por éste proyecto, se encuentran en views/card.py, en views/button.py y en views/textfield.py
• el logo que se incluye en los reportes se encuentra en templates/logo.jpg fué generado con herramienta de generación de imágenes de google, nano banana
• algunos fragmentos de código fueron coautorados por gemini 3 fast