rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
928eb795e6
michangarrito/docs/02-especificaciones/ESPECIFICACION-COMPONENTES.md
rckrdmrd 928eb795e6 [SIMCO-V38] feat: Actualizar a SIMCO v3.8.0 + cambios apps 
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8
- Cambios en backend y frontend

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 08:53:05 -06:00

503 lines
17 KiB
Markdown
Raw Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink