michangarrito/docs/02-especificaciones/ESPECIFICACION-COMPONENTES.md

id	type	title	status	created_at	updated_at	simco_version	author	tags
SPEC-ESPECIFICACION-COMPONENTES	Specification	Especificacion de Componentes - MiChangarrito	Published	2026-01-04	2026-01-10	3.8.0	Equipo MiChangarrito	componentes backend frontend mobile api arquitectura

Especificación de Componentes - MiChangarrito

Última actualización: 2026-01-10

---

Resumen de Componentes

Componente	Puerto	Framework	Estado
Frontend Web	3140	React 19.2.0 + Vite 7.x	Implementado
Backend API	3141	NestJS 10.x	Implementado
MCP Server	stdio	MCP SDK 1.x	Implementado
WhatsApp Service	3143	NestJS 10.x	Implementado
Mobile App	8081	React Native 0.76	En desarrollo

---

Backend API

Ubicación

apps/backend/

Módulos (18 total)

Módulo	Descripción	Endpoints Base	Estado
AuthModule	Autenticación JWT	/auth/*	Implementado
TenantsModule	Multi-tenancy	/tenants/*	Implementado
ProductsModule	CRUD productos	/products/*	Implementado
SalesModule	Punto de venta	/sales/*	Implementado
CustomersModule	Clientes y fiado	/customers/*	Implementado
InventoryModule	Stock y movimientos	/inventory/*	Implementado
OrdersModule	Pedidos WhatsApp	/orders/*	Implementado
SubscriptionsModule	Planes y tokens	/subscriptions/*	Implementado
MessagingModule	Conversaciones	/messaging/*	Implementado
BillingModule	Facturación CFDI 4.0	/billing/*	Implementado
PaymentsModule	CoDi/SPEI/Tarjetas	/payments/*	Implementado
ReferralsModule	Sistema de referidos	/referrals/*	Implementado
MarketplaceModule	B2B Proveedores	/marketplace/*	Implementado
IntegrationsModule	Webhooks externos	/integrations/*	Implementado
InvoicesModule	Timbrado CFDI SAT	/invoices/*	Implementado
WidgetsModule	Widgets y atajos	/widgets/*	Implementado
CategoriesModule	Categorías productos	/categories/*	Implementado
CodiSpeiModule	Pagos CoDi/SPEI	/codi-spei/*	Implementado

Endpoints Detallados

AuthModule (/auth)

Método	Endpoint	Descripción
POST	/auth/register	Registro de nuevo usuario
POST	/auth/login	Inicio de sesión
POST	/auth/refresh	Renovar token JWT
POST	/auth/logout	Cerrar sesión
POST	/auth/forgot-password	Solicitar reset de password
POST	/auth/reset-password	Resetear password
GET	/auth/me	Obtener usuario actual
PUT	/auth/change-password	Cambiar password

TenantsModule (/tenants)

Método	Endpoint	Descripción
POST	/tenants	Crear nuevo tenant
GET	/tenants/:id	Obtener tenant
PUT	/tenants/:id	Actualizar tenant
GET	/tenants/:id/settings	Configuración del tenant
PUT	/tenants/:id/settings	Actualizar configuración
POST	/tenants/:id/logo	Subir logo
GET	/tenants/:id/stats	Estadísticas del tenant

ProductsModule (/products)

Método	Endpoint	Descripción
GET	/products	Listar productos
POST	/products	Crear producto
GET	/products/:id	Obtener producto
PUT	/products/:id	Actualizar producto
DELETE	/products/:id	Eliminar producto
POST	/products/:id/image	Subir imagen
GET	/products/categories	Listar categorías
POST	/products/categories	Crear categoría
GET	/products/search	Buscar productos
POST	/products/bulk	Importación masiva

SalesModule (/sales)

Método	Endpoint	Descripción
GET	/sales	Listar ventas
POST	/sales	Registrar venta
GET	/sales/:id	Obtener venta
PUT	/sales/:id/cancel	Cancelar venta
GET	/sales/today	Ventas del día
GET	/sales/summary	Resumen de ventas
POST	/sales/:id/payment	Registrar pago
GET	/sales/:id/receipt	Generar recibo

CustomersModule (/customers)

Método	Endpoint	Descripción
GET	/customers	Listar clientes
POST	/customers	Crear cliente
GET	/customers/:id	Obtener cliente
PUT	/customers/:id	Actualizar cliente
DELETE	/customers/:id	Eliminar cliente
GET	/customers/:id/purchases	Historial de compras
GET	/customers/:id/fiados	Fiados del cliente
POST	/customers/:id/fiados	Crear fiado
POST	/customers/:id/fiados/:fiadoId/payment	Pagar fiado

InventoryModule (/inventory)

Método	Endpoint	Descripción
GET	/inventory	Estado del inventario
GET	/inventory/:productId	Stock de producto
POST	/inventory/movement	Registrar movimiento
GET	/inventory/movements	Historial de movimientos
GET	/inventory/low-stock	Productos bajo stock
GET	/inventory/value	Valor del inventario
POST	/inventory/adjust	Ajuste de inventario
POST	/inventory/count	Conteo físico

OrdersModule (/orders)

Método	Endpoint	Descripción
GET	/orders	Listar pedidos
POST	/orders	Crear pedido
GET	/orders/:id	Obtener pedido
PUT	/orders/:id	Actualizar pedido
PUT	/orders/:id/status	Cambiar estado
DELETE	/orders/:id	Cancelar pedido
GET	/orders/pending	Pedidos pendientes
POST	/orders/:id/confirm	Confirmar pedido

SubscriptionsModule (/subscriptions)

Método	Endpoint	Descripción
GET	/subscriptions/plans	Listar planes
GET	/subscriptions/current	Suscripción actual
POST	/subscriptions/subscribe	Suscribirse a plan
POST	/subscriptions/cancel	Cancelar suscripción
PUT	/subscriptions/upgrade	Cambiar plan
GET	/subscriptions/tokens	Balance de tokens
POST	/subscriptions/tokens/purchase	Comprar tokens
GET	/subscriptions/usage	Historial de uso

InvoicesModule (/invoices)

Método	Endpoint	Descripción
GET	/invoices	Listar facturas CFDI
POST	/invoices	Crear factura
GET	/invoices/:id	Obtener factura
PUT	/invoices/:id	Actualizar factura
DELETE	/invoices/:id	Eliminar factura (borrador)
POST	/invoices/:id/stamp	Timbrar CFDI ante SAT
POST	/invoices/:id/cancel	Cancelar CFDI
GET	/invoices/:id/pdf	Descargar PDF
GET	/invoices/:id/xml	Descargar XML

WidgetsModule (/widgets)

Método	Endpoint	Descripción
GET	/widgets	Listar widgets configurados
POST	/widgets	Crear widget
PUT	/widgets/:id	Actualizar widget
DELETE	/widgets/:id	Eliminar widget

CategoriesModule (/categories)

Método	Endpoint	Descripción
GET	/categories	Listar categorías
POST	/categories	Crear categoría
GET	/categories/:id	Obtener categoría
PUT	/categories/:id	Actualizar categoría
DELETE	/categories/:id	Eliminar categoría
PUT	/categories/:id/reorder	Reordenar categoría

CodiSpeiModule (/codi-spei)

Método	Endpoint	Descripción
POST	/codi-spei/codi/generate	Generar QR CoDi
GET	/codi-spei/codi/:id/status	Estado de pago CoDi
POST	/codi-spei/spei/reference	Generar referencia SPEI
GET	/codi-spei/spei/:reference/status	Estado de pago SPEI
GET	/codi-spei/transactions	Historial transacciones
GET	/codi-spei/virtual-accounts	Cuentas virtuales
POST	/codi-spei/virtual-accounts	Crear cuenta virtual
GET	/codi-spei/summary	Resumen CoDi/SPEI
POST	/codi-spei/webhook	Webhook de notificaciones

BillingModule (/billing)

Método	Endpoint	Descripción
GET	/billing/invoices	Listar facturas
POST	/billing/invoices	Crear factura (CFDI 4.0)
GET	/billing/invoices/:id	Obtener factura
POST	/billing/invoices/:id/cancel	Cancelar factura
GET	/billing/invoices/:id/pdf	Descargar PDF
GET	/billing/invoices/:id/xml	Descargar XML
POST	/billing/invoices/:id/send	Enviar por email
GET	/billing/tax-config	Configuración fiscal
PUT	/billing/tax-config	Actualizar configuración fiscal

PaymentsModule (/payments)

Método	Endpoint	Descripción
POST	/payments/codi/generate	Generar QR CoDi
GET	/payments/codi/:id/status	Estado de pago CoDi
POST	/payments/spei/reference	Generar referencia SPEI
GET	/payments/spei/transactions	Transacciones SPEI
POST	/payments/card	Pago con tarjeta
GET	/payments/virtual-accounts	Cuentas virtuales
POST	/payments/virtual-accounts	Crear cuenta virtual
GET	/payments/config	Configuración de pagos

ReferralsModule (/referrals)

Método	Endpoint	Descripción
GET	/referrals/code	Obtener código de referido
POST	/referrals/code/generate	Generar nuevo código
GET	/referrals/stats	Estadísticas de referidos
GET	/referrals/history	Historial de referidos
GET	/referrals/rewards	Recompensas pendientes
POST	/referrals/rewards/:id/claim	Reclamar recompensa
POST	/referrals/validate/:code	Validar código

MarketplaceModule (/marketplace)

Método	Endpoint	Descripción
GET	/marketplace/suppliers	Listar proveedores
GET	/marketplace/suppliers/:id	Detalle de proveedor
GET	/marketplace/suppliers/:id/products	Productos del proveedor
POST	/marketplace/orders	Crear orden a proveedor
GET	/marketplace/orders	Mis órdenes
GET	/marketplace/orders/:id	Detalle de orden
POST	/marketplace/suppliers/:id/review	Calificar proveedor
POST	/marketplace/suppliers/:id/favorite	Agregar a favoritos
GET	/marketplace/favorites	Mis proveedores favoritos
GET	/marketplace/search	Buscar productos/proveedores

IntegrationsModule (/integrations)

Método	Endpoint	Descripción
POST	/integrations/webhook/stripe	Webhook Stripe
POST	/integrations/webhook/mercadopago	Webhook Mercado Pago
POST	/integrations/webhook/spei	Webhook SPEI/STP
POST	/integrations/webhook/whatsapp	Webhook WhatsApp
GET	/integrations/credentials	Credenciales de integración
PUT	/integrations/credentials	Actualizar credenciales

Ejecución

cd apps/backend
npm run start:dev    # Desarrollo
npm run build        # Producción

---

WhatsApp Service

Ubicación

apps/whatsapp-service/

Capacidades

• Envío de mensajes texto
• Mensajes interactivos (botones, listas)
• Templates de WhatsApp
• Recepción via webhook
• Procesamiento LLM

Webhook

GET  /webhook/whatsapp  # Verificación Meta
POST /webhook/whatsapp  # Recepción de mensajes

Ejecución

cd apps/whatsapp-service
npm run start:dev

---

MCP Server

Ubicación

apps/mcp-server/

Herramientas Disponibles

Productos:

• list_products - Listar productos
• get_product_details - Detalles de producto
• check_product_availability - Verificar stock

Pedidos:

• create_order - Crear pedido
• get_order_status - Estado de pedido
• update_order_status - Actualizar estado
• cancel_order - Cancelar pedido

Fiado:

• get_fiado_balance - Saldo de cliente
• create_fiado - Registrar fiado
• register_fiado_payment - Registrar pago
• get_fiado_history - Historial
• check_fiado_eligibility - Verificar elegibilidad

Clientes:

• get_customer_info - Info de cliente
• register_customer - Registrar cliente
• get_customer_purchase_history - Historial compras
• get_customer_stats - Estadísticas

Inventario:

• check_stock - Verificar stock
• get_low_stock_products - Productos con stock bajo
• record_inventory_movement - Registrar movimiento
• get_inventory_value - Valor del inventario

Ejecución

cd apps/mcp-server
npm run build
npm start

---

Frontend Web

Ubicación

apps/frontend/

Stack

• React 19.2.0
• Vite 7.x
• TailwindCSS 4.x
• React Router 7.x
• TanStack Query 5.x
• Zustand (estado global)
• React Hook Form + Zod

Páginas (12 total)

Ruta	Página	Descripción	Estado
/login	Login	Inicio de sesión	Implementado
/register	Register	Registro de usuario	Implementado
/	Dashboard	Resumen y estadísticas (requiere auth)	Implementado
/products	Products	Catálogo de productos	Implementado
/sales	Sales	Punto de venta (POS)	Implementado
/orders	Orders	Gestión de pedidos	Implementado
/customers	Customers	Lista de clientes	Implementado
/fiado	Fiado	Gestión de crédito	Implementado
/inventory	Inventory	Control de stock	Implementado
/billing	Billing	Facturación CFDI	Implementado
/referrals	Referrals	Sistema de referidos	Implementado
/marketplace	Marketplace	Proveedores B2B	Implementado
/settings	Settings	Configuración	Implementado

Componentes Principales

src/
├── components/
│   ├── common/          # Botones, inputs, modales
│   ├── layout/          # Header, Sidebar, Footer
│   ├── dashboard/       # Widgets de dashboard
│   ├── products/        # ProductCard, ProductForm
│   ├── sales/           # POS, Cart, PaymentModal
│   ├── customers/       # CustomerList, CustomerForm
│   ├── inventory/       # StockTable, MovementForm
│   ├── billing/         # InvoiceForm, InvoiceList
│   └── marketplace/     # SupplierCard, OrderForm
├── hooks/               # Custom hooks (useProducts, useSales, etc.)
├── services/            # API clients
├── stores/              # Zustand stores
└── pages/               # Páginas principales

Ejecución

cd apps/frontend
npm run dev      # Desarrollo (http://localhost:3140)
npm run build    # Producción
npm run preview  # Preview de build

---

Mobile App (React Native)

Ubicación

apps/mobile/

Stack

• React Native 0.76
• Expo SDK 52
• React Navigation 7.x
• TanStack Query 5.x
• Zustand

Pantallas (10 total)

Pantalla	Descripción	Estado
Login	Inicio de sesión	Implementado
Dashboard	Resumen del día	Implementado
Products	Catálogo de productos	Implementado
Sales	Punto de venta móvil	Implementado
Customers	Lista de clientes	Implementado
Fiado	Gestión de créditos	Implementado
Inventory	Control de stock	Implementado
Orders	Pedidos recibidos	Implementado
Notifications	Centro de notificaciones	Implementado
Settings	Configuración	Implementado

Ejecución

cd apps/mobile
npm run start       # Expo dev server
npm run android     # Android emulator
npm run ios         # iOS simulator (Mac only)
npm run build:apk   # Build APK

---

Configuración de Entorno

Variables requeridas en .env:

# Base de datos
DB_HOST=localhost
DB_PORT=5432
DB_NAME=michangarrito_dev
DB_USER=michangarrito_dev
DB_PASSWORD=MCh_dev_2025_secure

# JWT
JWT_SECRET=<secret>
JWT_EXPIRATION=7d

# WhatsApp
WHATSAPP_ACCESS_TOKEN=<token>
WHATSAPP_PHONE_NUMBER_ID=<id>
WHATSAPP_VERIFY_TOKEN=<token>

# LLM
LLM_PROVIDER=openrouter
LLM_API_KEY=<key>
LLM_MODEL=anthropic/claude-3-5-haiku-latest

# Stripe
STRIPE_SECRET_KEY=<key>
STRIPE_WEBHOOK_SECRET=<secret>

# CFDI (Facturación)
PAC_PROVIDER=facturapi
FACTURAPI_KEY=<key>

# SPEI
SPEI_PROVIDER=stp
STP_EMPRESA=MiChangarrito

---

Referencias

• Arquitectura Database
• Integraciones Externas
• Environment Inventory
• Database Inventory

---

Version: 2.0.0 Fecha: 2026-01-10 Actualizado: Sincronización con desarrollo - 17 módulos backend, 11 páginas frontend, 10 pantallas mobile