AAI | IAA

Desarrollo: Aplicación de E-commerce, Enfoque Estructurado con IA y el Protocolo RICECO
Desarrollo: Aplicación de E-commerce, Enfoque Estructurado con IA y el Protocolo RICECO
AI · E-COMMERCE · RICECO

Desarrollo: Aplicación de E-commerce, Enfoque Estructurado con IA y el Protocolo RICECO

Autor: Andrés Rojas, IA

Introducción

El desarrollo de aplicaciones web robustas y escalables requiere un enfoque metódico que abarque desde la conceptualización inicial hasta la implementación técnica y las futuras iteraciones. Este artículo detalla el proceso de desarrollo para una aplicación de comercio electrónico con un diseño mobile-first, diseñada para gestionar un catálogo de productos jerárquico y facilitar las operaciones de clientes, vendedores y administradores. Se pone un énfasis particular en cómo la colaboración con una inteligencia artificial, guiada por un protocolo de comunicación estructurado como RICECO, puede optimizar y clarificar el ciclo de vida del desarrollo de software.

El objetivo es presentar una guía que no solo documente la arquitectura y las tecnologías de un proyecto específico, sino que también sirva como un modelo para la colaboración efectiva entre desarrolladores humanos y sistemas de IA en tareas de desarrollo complejas.

1. Conceptualización del Proyecto

La base de cualquier aplicación exitosa es una comprensión clara de sus objetivos de negocio y los roles de los usuarios que interactuarán con ella. Este proyecto se centra en una plataforma de e-commerce con tres roles de usuario distintos, cada uno con responsabilidades y permisos específicos.

Rol de Usuario Responsabilidades Principales
Cliente Navegar por el catálogo de productos, filtrar, seleccionar artículos, gestionar un carrito de compras y enviar órdenes de compra.
Vendedor Recibir y registrar las órdenes de compra de los clientes, y generar las notas de entrega correspondientes para el despacho de productos.
Administrador Gestionar de forma integral todas las entidades de datos del sistema, incluyendo productos, categorías, proveedores y usuarios, con plenos poderes de creación, lectura, actualización y eliminación (CRUD).

El propósito fundamental de la aplicación es digitalizar y optimizar el flujo de pedidos, desde la selección del producto por parte del cliente hasta la gestión logística por parte del vendedor, todo bajo la supervisión y gestión de datos del administrador.

2. Modelo Conceptual y Estructura de Datos

Para soportar las funcionalidades descritas, se define un modelo de datos relacional que organiza la información de manera lógica y eficiente. El siguiente diagrama de Entidad-Relación (ER) ilustra las principales entidades del sistema y cómo se conectan entre sí.

Diagrama de Entidades y Relaciones

El núcleo del modelo de datos es la estructura jerárquica del catálogo de productos, que sigue una organización de cuatro niveles para permitir una clasificación granular y flexible de los artículos:

Colección → Categoría → Subcolección → Subcategoría → Producto

Esta estructura permite a los clientes navegar de lo general a lo específico, mejorando la experiencia de usuario y la capacidad de descubrimiento de productos. A continuación, se presenta una tabla que resume las entidades clave.

Entidad Propósito en el Sistema
COLLECTION Agrupa categorías relacionadas (ej. "Ropa de Verano").
CATEGORY Clasificación principal de productos (ej. "Camisetas").
SUBCOLLECTION Agrupación intermedia dentro de una categoría (ej. "Camisetas de Algodón").
SUBCATEGORY Clasificación más específica (ej. "Manga Corta").
PRODUCT El artículo individual disponible para la venta.
SUPPLIER El proveedor que suministra uno o más productos.
CUSTOMER El cliente que realiza las órdenes de compra.
PURCHASE_ORDER La orden de compra generada por un cliente.
DELIVERY_NOTE La nota de entrega generada por un vendedor para despachar productos.
MISSING_ITEM Registro de los productos de una orden que no se incluyeron en la entrega.

Para ilustrar la estructura de datos a nivel de objeto, el siguiente ejemplo muestra una representación en formato JSON de una entidad PRODUCT.

{
  "id": 101,
  "slug": "samsung-galaxy-s24",
  "supplier_id": 25,
  "article": "SG-S24",
  "code": "789123456",
  "name": "Samsung Galaxy S24",
  "description": "El último smartphone de Samsung con IA integrada.",
  "price": 1299.99,
  "subcategory_slug": "smartphones-android",
  "image_id": 450
}

3. Historias de Usuario y Casos de Uso

Las historias de usuario son una herramienta fundamental en el desarrollo ágil para capturar los requisitos desde la perspectiva del usuario final. Definen quién es el usuario, qué necesita hacer y por qué. A partir de estas historias, se derivan los casos de uso, que describen en detalle la interacción paso a paso entre el usuario y el sistema para lograr un objetivo específico.

Rol Historia de Usuario Clave
Cliente Como cliente, quiero poder filtrar productos por categoría para encontrar rápidamente lo que busco.
Vendedor Como vendedor, quiero que el sistema me muestre los artículos faltantes al crear una nota de entrega para gestionar el inventario.
Administrador Como administrador, quiero poder cargar productos masivamente desde un archivo XLSX para agilizar la gestión del catálogo.

Estos relatos se traducen en flujos de trabajo concretos. Por ejemplo, el caso de uso "Realizar un Pedido" implica que el cliente navegue, seleccione productos, los añada a un carrito y finalmente confirme la orden, lo que desencadena una notificación al vendedor. Este proceso define una secuencia clara de interacciones que deben ser implementadas en la interfaz de usuario y la lógica de negocio.

4. El Proceso de Desarrollo Asistido por IA

La colaboración con sistemas de inteligencia artificial puede acelerar significativamente el desarrollo, pero requiere una comunicación precisa. El protocolo RICECO es un marco estructurado para formular instrucciones a una IA, asegurando que los resultados sean predecibles, completos y alineados con los requisitos del proyecto.

El Protocolo RICECO

RICECO es un acrónimo que desglosa una solicitud en seis componentes clave:

Componente Descripción
Role (Rol) Define la personalidad o el perfil profesional que la IA debe adoptar (ej. "Actúa como un desarrollador backend senior").
Instruction (Instrucción) La tarea específica y directa que debe realizarse (ej. "Desarrolla una aplicación web para gestionar entidades con operaciones CRUD").
Context (Contexto) Proporciona el trasfondo, el propósito y la información necesaria para entender la tarea en profundidad.
Examples (Ejemplos) Ilustraciones concretas que guían a la IA sobre el resultado esperado (ej. flujos de trabajo de ejemplo).
Constraints (Restricciones) Limitaciones técnicas, de estilo o de otro tipo que deben respetarse (ej. "Usa el ORM Drizzle y sigue la estructura de Next-Faster").
Output Format (Formato de Salida) Define la estructura que debe tener la respuesta de la IA (ej. "Proporciona un plan de desarrollo seguido de una solicitud de confirmación").

Al utilizar este protocolo, el desarrollador puede guiar a la IA para generar artefactos de alta calidad, como planes de desarrollo, esquemas de base de datos, componentes de código y documentación. La IA, actuando como un par programador, puede proponer soluciones, identificar dependencias y escribir código boilerplate, liberando al desarrollador para que se concentre en la lógica de negocio más compleja y la arquitectura general.

Protocolo ejemplo

Role: Act as a senior backend developer writing React frontend code. You operate with precision, propose a detailed development plan before implementing changes, and always request explicit confirmation before proceeding with implementation.

Instruction: Develop a mobile-first web application to manage the following entities with full CRUD operations (Create, Read, Update, Delete): PRODUCT, CATEGORY, SUBCATEGORY, COLLECTION, SUBCOLLECTION, IMAGE, SUPPLIER, CUSTOMER, PURCHASE_ORDER, DELIVERY_NOTE.

Context: Background: This is an e-commerce application with three primary user roles: CUSTOMER: Can browse products, filter by categories and subcategories, select products, add them to cart, modify cart contents, and submit the cart as a PURCHASE_ORDER to a SALESPERSON. SALESPERSON: Receives PURCHASE_ORDERs from customers, records them in the system, and creates DELIVERY_NOTEs for fulfillment. ADMIN: Has full access to all entities with complete CRUD capabilities. Purpose: Enable customers to place purchase orders, allow salespersons to process orders and generate delivery notes, and provide administrators with comprehensive data management tools. Tone: Professional and business-oriented.

Constraints: Technical Stack: Use Drizzle ORM schema following the hierarchical e-commerce product catalog structure from Next-Faster https://github.com/ethanniser/NextFaster. The product organization follows a 4-level deep categorization: Collection → Category → Subcollection → Subcategory → Product. Entity Definitions: COLLECTION: id (primary key), name, slug. CATEGORY: slug (primary key), name, collection_id (foreign key → COLLECTION), image. SUBCOLLECTION: id (primary key), name, category_slug (foreign key → CATEGORY). SUBCATEGORY: slug (primary key), name, subcollection_id (foreign key → SUBCOLLECTION), image. PRODUCT: id (primary key), slug, supplier_id (foreign key → SUPPLIER), article (optional), code (optional), name, description, price, subcategory_slug (foreign key → SUBCATEGORY), image_id (foreign key → IMAGE). IMAGE: id (primary key), title, url. SUPPLIER: id (primary key), name, contact. CUSTOMER: id (primary key), name, address, phone, taxpayer_id. PURCHASE_ORDER: id (primary key), customer_id (foreign key → CUSTOMER), product_id (foreign key → PRODUCT), quantity. DELIVERY_NOTE: (Structure to be defined based on business requirements). Admin-Specific Requirements: XLSX File Upload The ADMIN interface must support uploading .xlsx files with the following fields (in Spanish): Proveedor (supplier code), Artículo (article code, optional), Código (code number, optional), Descripción (description), Categoría (zero, one, or many category "tags", optional), Imagen (Image URL, optional). CRUD Operations Full Create, Read, Update, and Delete capabilities for all entities listed above. Salesperson-Specific Requirements: MISSING_ITEM List Generation For every DELIVERY_NOTE created, the system must automatically generate a MISSING_ITEM list for the SALESPERSON, showing which products from the PURCHASE_ORDER are not included in the delivery.

Examples: Example 1: Customer Workflow. Customer browses products filtered by "Electronics" → "Smartphones" → "Android". Customer adds 2 units of "Samsung Galaxy S24" to cart. Customer reviews cart and submits it as a PURCHASE_ORDER. SALESPERSON receives the order notification . Example 2: Admin Product Upload. ADMIN uploads an .xlsx file with columns: Proveedor, Artículo, Código, Descripción, Categoría, Imagen. System parses the file and creates/updates PRODUCT records. System links products to appropriate SUPPLIER, CATEGORY, SUBCATEGORY, and IMAGE entities. Example 3: Delivery Note Creation. SALESPERSON creates a DELIVERY_NOTE for PURCHASE_ORDER #123. PURCHASE_ORDER contains: Product A (qty: 5), Product B (qty: 3), Product C (qty: 2). DELIVERY_NOTE includes: Product A (qty: 5), Product B (qty: 1). System generates MISSING_ITEM list: Product B (missing: 2), Product C (missing: 2).

Output Format: For each implementation request, provide: Development Plan: A structured breakdown of the implementation steps, including: Database schema changes (if any), Backend API endpoints required, Frontend components to be created/modified, State management approach, Estimated complexity and dependencies. Confirmation Request: Explicitly ask for approval before proceeding with code implementation. Implementation: Upon confirmation, deliver: Clean, well-commented code, Component structure following React best practices, Mobile-first responsive design, Error handling and validation, Type safety (TypeScript if applicable). Testing Considerations: Brief notes on what should be tested.

5. Arquitectura y Tecnologías

La selección de la pila tecnológica es una decisión crítica que impacta la escalabilidad, el mantenimiento y la experiencia del desarrollador. Para este proyecto, se ha optado por un conjunto de tecnologías modernas y eficientes:

  • Frontend: React con TypeScript para construir una interfaz de usuario interactiva, segura en tipos y mantenible. El diseño se aborda con un enfoque mobile-first para garantizar una experiencia óptima en dispositivos móviles.
  • ORM: Drizzle ORM, un mapeador relacional de objetos para TypeScript que ofrece un rendimiento excelente y una sintaxis cercana a SQL, facilitando la interacción con la base de datos de una manera segura y eficiente.
  • Base de Datos: Aunque no se especifica un motor concreto, Drizzle es compatible con bases de datos relacionales populares como PostgreSQL o MySQL, que son opciones robustas y probadas para aplicaciones de e-commerce.

Esta arquitectura promueve una separación clara de responsabilidades entre el frontend y el backend, permitiendo un desarrollo y despliegue independientes.

6. Iteraciones Futuras y Mejoras

Un proyecto de software nunca está completamente "terminado". Siempre hay oportunidades para mejorar y añadir nuevas funcionalidades. Algunas posibles iteraciones para esta aplicación incluyen:

  • Sistema de Autenticación de Usuarios: Implementar un sistema de inicio de sesión para que los clientes puedan ver su historial de pedidos y guardar su información.
  • Pasarelas de Pago: Integrar servicios de pago como Stripe o PayPal para permitir transacciones en línea directas.
  • Módulo de Inventario: Desarrollar un sistema de gestión de stock que se actualice automáticamente con cada compra y entrega.
  • Notificaciones en Tiempo Real: Implementar notificaciones push o por correo electrónico para clientes y vendedores sobre el estado de los pedidos.
  • Análisis y Reportes: Crear un panel de control para que los administradores y vendedores puedan visualizar métricas de ventas, productos más populares y otros KPIs.

Conclusión

El desarrollo de esta aplicación de e-commerce demuestra cómo un enfoque estructurado, que combina principios sólidos de ingeniería de software con la colaboración de una inteligencia artificial, puede llevar a resultados exitosos. El uso del protocolo RICECO para guiar a la IA, junto con un modelo de datos bien definido y una pila tecnológica moderna, establece una base sólida para construir una aplicación funcional, escalable y fácil de mantener. Las futuras iteraciones permitirán enriquecer la plataforma, añadiendo valor tanto para los usuarios como para el negocio.

Referencias