---
id: SPEC-ESPECIFICACION-COMPONENTES
type: Specification
title: "Especificacion de Componentes - MiChangarrito"
status: Published
created_at: 2026-01-04
updated_at: 2026-01-10
simco_version: "3.8.0"
author: "Equipo MiChangarrito"
tags:
  - 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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`:

```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](./ARQUITECTURA-DATABASE.md)
- [Integraciones Externas](./INTEGRACIONES-EXTERNAS.md)
- [Environment Inventory](../../orchestration/inventarios/DEVENV-MASTER-INVENTORY.yml)
- [Database Inventory](../../orchestration/inventarios/DATABASE_INVENTORY.yml)

---

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