Detalle de trabajo

El problema

Las aplicaciones de gestión comercial suelen crecer de forma desordenada:

• lógica de negocio dispersa,
• reglas implícitas no documentadas,
• endpoints acoplados directamente a modelos,
• dificultad para introducir cambios sin romper flujos existentes.

Además, operaciones como:

• confirmación de compras o ventas,
• movimientos de stock,
• movimientos de cash,
• backups y restauraciones,

requieren control, trazabilidad y protección, no simples CRUDs.

La solución

Diseñé una API con una arquitectura estrictamente gobernada, donde cada responsabilidad está claramente delimitada y documentada.

Arquitectura por capas

Separación explícita y no negociable de responsabilidades:

• Model Representa la estructura de la base de datos y la serialización (to_dict).
• Service Contiene la lógica de negocio y las reglas operativas.
• Controller Gestiona los datos, validaciones y orquestación de llamadas.
• API / Router Define los endpoints y el contrato de la API.

Si cambia algo, se toca una sola capa, no todo el sistema.

Arquitectura Base + Extensiones

Uno de los aprendizajes clave de este proyecto es el uso de una arquitectura Base + especialización:

• BaseModel
  • id
  • auditoría (created_at, updated_at)
  • soft delete (is_active, deleted_at)
  • to_dict()
• Modelos reales heredan, amplían o sobrescriben solo lo necesario.

Lo mismo ocurre con:

• BaseService
• BaseController
• BaseRouter

Que implementan el CRUD estándar:

• create
• get_all
• get_by_id
• update
• delete (soft delete)
• restore

Y que luego se especializan según las reglas de negocio documentadas.

• coherencia en todo el proyecto,
• menor duplicación,
• evolución controlada.

Dominio y modelo conceptual (DDD informal)

Durante el desarrollo descubrí que estaba aplicando, de forma natural, una arquitectura DDD informal:

• Entities
  • users
  • products
  • customers
  • suppliers
• Aggregates
  • stock locations
  • stock por producto
  • cash accounts
• Documents
  • albaranes de compra
  • albaranes de venta
  • depósitos de stock
  • transferencias de efectivo
• Events
  • movimientos de stock
  • movimientos de caja

Los documentos no son solo datos: representan acciones que impactan en los aggregates mediante eventos.

Funcionalidad principal

Gestión comercial

• Usuarios y roles (ADMIN / USER)
• Productos, clientes y proveedores

Stock

• Ubicaciones
• Stock por ubicación
• Depósitos entre ubicaciones

Cash

• Cuentas de caja
• Transferencias y movimientos

Documentos de negocio

• Albaranes de compra
• Albaranes de venta
• Confirmación de documentos
• Reglas explícitas por estado (DRAFT / CONFIRMED)

Seguridad, roles y control de acceso

• Autenticación mediante JWT (access + refresh)
• Tokens incluyen password_changed_at
• Invalidación automática de tokens tras cambio de contraseña

Roles:

• ADMIN
  • gestión de usuarios
  • backups y restores
  • operaciones críticas
• USER
  • operaciones de negocio estándar

Reglas de seguridad explícitas:

un usuario no puede borrarse a sí mismo ni eliminar el último admin.

Copias de seguridad y salvaguarda de datos

El sistema incluye soporte explícito de backups:

• Exportación completa de la base de datos vía endpoint
• Restauración desde backup
• Servicio dedicado para estas operaciones

La protección de datos forma parte del diseño, no un añadido posterior.

Stack técnico

• Lenguaje: Python
• Framework: Flask (WSGI)
• Base de datos: SQLite
• ORM: SQLAlchemy
• Autenticación: JWT
• Testing: pytest, pytest-cov
• CORS: Flask-Cors
• Configuración: python-dotenv

Operación y despliegue

• Backend desplegado en PythonAnywhere
• Actualización operativa documentada en el repo
• Base de datos SQLite en producción
• Sistema funcionando y accesible públicamente

🔗 API en producción

🔗 Repositorio GitHub

Origen del sistema de trabajo

Este proyecto es uno de los primeros donde empecé a formalizar el uso de IA en el desarrollo.

La carpeta docs/ contiene:

• contratos de arquitectura,
• reglas explícitas para el uso de IA,
• plantillas base,
• catálogos de errores,
• documentación como fuente de verdad.

Aquí aparecen ya conceptos que luego evolucionaron hacia:

• trabajo gobernado,
• cierre formal de decisiones,
• separación de roles,
• y finalmente el enfoque PDCA + orchestrator / executor que uso actualmente.

Qué demuestra este proyecto

Este proyecto demuestra mi capacidad para:

• Diseñar backends complejos con reglas de negocio reales
• Construir arquitecturas gobernadas y extensibles
• Aplicar principios cercanos a DDD
• Integrar seguridad, control y trazabilidad
• Operar software en producción
• Evolucionar hacia un sistema de trabajo reproducible y controlado

Imágenes del proyecto