rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add complete epic documentation and orchestration inventories

Browse Source 
Sprint 3-4 deliverables:
- 28 epics documented (MCH-001 to MCH-028)
- 7 development phases fully documented
- DATABASE_INVENTORY.yml, BACKEND_INVENTORY.yml, FRONTEND_INVENTORY.yml
- Task traces for database and frontend

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
rckrdmrd 2026-01-07 05:40:13 -06:00
parent 48dea7a5d0
commit 3bba4ce6d7
36 changed files with 7431 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/01-epicas/MCH-001-infraestructura-base.md Normal file
View File

@ -0,0 +1,97 @@
# MCH-001: Infraestructura Base
## Metadata
- **Codigo:** MCH-001
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-04
- **Fecha fin:** 2026-01-05
## Descripcion
Setup inicial del proyecto MiChangarrito incluyendo estructura monorepo, configuracion de base de datos PostgreSQL multi-tenant, pipelines CI/CD, y entornos de desarrollo.
## Objetivos
1. Establecer estructura de proyecto monorepo
2. Configurar PostgreSQL con multi-tenant (RLS)
3. Setup de entornos de desarrollo
4. Configurar CI/CD basico
## Alcance
### Incluido
- Estructura de carpetas monorepo (apps/, database/, docs/)
- PostgreSQL con schemas separados
- Scripts de recreacion de BD
- Docker Compose para desarrollo
- GitHub Actions basico
### Excluido
- Deployment a produccion
- Kubernetes (futuro)
- Monitoring avanzado
## Arquitectura
```
michangarrito/
├── apps/
│ ├── backend/ # NestJS API
│ ├── web/ # React Dashboard
│ ├── mobile/ # Expo App
│ ├── mcp-server/ # Gateway LLM
│ └── whatsapp-service/ # Bot WhatsApp
├── database/
│ ├── schemas/ # DDL files
│ ├── seeds/ # Data inicial
│ └── *.sh # Scripts
├── docs/
└── orchestration/
```
## Entregables
| Entregable | Estado | Archivo/Ubicacion |
|------------|--------|-------------------|
| Estructura monorepo | Completado | `projects/michangarrito/` |
| DDL base PostgreSQL | Completado | `database/schemas/00-02.sql` |
| Scripts BD | Completado | `database/*.sh` |
| Docker Compose | Completado | `docker-compose.yml` |
## Dependencias
### Depende de
- Ninguna (epica inicial)
### Bloquea a
- MCH-002 (Auth)
- MCH-003 (Productos)
- MCH-010 (MCP Server)
## Criterios de Aceptacion
- [x] Estructura de carpetas creada
- [x] PostgreSQL ejecutandose con schemas
- [x] Script drop-and-recreate funcional
- [x] Extensiones uuid-ossp, pgcrypto habilitadas
- [x] Funcion current_tenant_id() operativa
## Notas Tecnicas
- **Puerto PostgreSQL:** 5432
- **Puerto Redis:** 6379
- **Base de datos:** michangarrito_platform
- **Multi-tenant:** Via tenant_id + RLS
## Historias de Usuario Relacionadas
| ID | Historia | Estado |
|----|----------|--------|
| US-001 | Como DevOps, quiero poder recrear la BD facilmente | Completado |
| US-002 | Como Dev, quiero estructura clara de proyecto | Completado |
---
**Ultima actualizacion:** 2026-01-07

137
docs/01-epicas/MCH-002-autenticacion.md Normal file
View File

@ -0,0 +1,137 @@
# MCH-002: Autenticacion
## Metadata
- **Codigo:** MCH-002
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-05
- **Fecha fin:** 2026-01-06
## Descripcion
Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono con OTP (SMS/WhatsApp), PIN de 4 digitos para acceso rapido, soporte biometrico opcional, y JWT para sesiones.
## Objetivos
1. Login via telefono + OTP
2. PIN de 4 digitos para acceso rapido
3. Soporte biometrico (Face ID/huella)
4. Gestion de sesiones JWT
5. Roles: owner, employee, viewer
## Alcance
### Incluido
- Registro con telefono
- OTP via SMS/WhatsApp
- PIN de 4 digitos
- JWT con refresh tokens
- Roles basicos (owner/employee/viewer)
- Logout y revocacion de sesiones
### Excluido
- OAuth (Google, Facebook) - fase posterior
- 2FA via TOTP - fase posterior
- SSO empresarial
## Flujos de Usuario
### Registro Inicial
```
1. Usuario ingresa telefono
2. Se envia OTP via SMS/WhatsApp
3. Usuario verifica OTP
4. Usuario configura PIN de 4 digitos
5. Se crea tenant automaticamente (para owners)
6. Usuario accede al dashboard
```
### Login Subsecuente
```
1. Usuario ingresa telefono
2. Usuario ingresa PIN de 4 digitos
- O usa biometrico si esta configurado
3. JWT generado
4. Acceso al sistema
```
### Login por OTP (sin PIN)
```
1. Usuario selecciona "Olvide mi PIN"
2. Se envia OTP
3. Usuario verifica OTP
4. Puede reconfigurrar PIN
```
## Modelo de Datos
### Tablas (schema: auth)
- `users`: id, tenant_id, phone, email, password_hash, name, role, pin_hash, status
- `sessions`: id, user_id, token, device_info, expires_at, revoked_at
- `roles`: id, tenant_id, name, permissions (JSONB)
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /auth/register | Registro nuevo usuario |
| POST | /auth/send-otp | Enviar OTP a telefono |
| POST | /auth/verify-otp | Verificar OTP |
| POST | /auth/set-pin | Configurar PIN |
| POST | /auth/login | Login con telefono + PIN |
| POST | /auth/login-otp | Login solo con OTP |
| GET | /auth/me | Usuario actual |
| POST | /auth/refresh | Renovar JWT |
| POST | /auth/logout | Cerrar sesion |
| DELETE | /auth/sessions | Revocar todas las sesiones |
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL auth schema | Completado | `04-auth.sql` |
| auth.module.ts | Completado | `modules/auth/` |
| JwtStrategy | Completado | `strategies/jwt.strategy.ts` |
| Guards | Completado | `guards/` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
### Bloquea a
- MCH-003 (Productos)
- MCH-004 (POS)
- Todos los modulos que requieren auth
## Criterios de Aceptacion
- [x] Registro con telefono funcional
- [x] OTP se envia correctamente
- [x] PIN de 4 digitos funciona
- [x] JWT se genera y valida
- [x] Roles owner/employee/viewer funcionan
- [x] Sesiones se pueden revocar
## Configuracion
```typescript
// JWT Config
{
secret: process.env.JWT_SECRET,
expiresIn: '7d',
refreshExpiresIn: '30d'
}
// OTP Config
{
length: 6,
expiresIn: '5m',
maxAttempts: 3
}
```
---
**Ultima actualizacion:** 2026-01-07

133
docs/01-epicas/MCH-003-catalogo-productos.md Normal file
View File

@ -0,0 +1,133 @@
# MCH-003: Catalogo de Productos
## Metadata
- **Codigo:** MCH-003
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-05
- **Fecha fin:** 2026-01-06
## Descripcion
Sistema de gestion de catalogo de productos para micro-negocios: categorias jerarquicas, productos con variantes, codigos de barras, imagenes, y precios con costo para calcular margen.
## Objetivos
1. CRUD de categorias con jerarquia
2. CRUD de productos con atributos completos
3. Soporte para variantes de producto
4. Busqueda por codigo de barras
5. Calculo automatico de margen
## Alcance
### Incluido
- Categorias con parent_id (jerarquia)
- Productos con SKU, barcode, precio, costo
- Variantes de producto (tallas, colores)
- Imagenes de producto
- Busqueda por nombre, SKU, barcode
- Activar/desactivar productos
### Excluido
- Productos compuestos (kits) - fase posterior
- Precios por volumen - fase posterior
- Multiples listas de precios
## Modelo de Datos
### Tablas (schema: catalog)
**categories**
- id, tenant_id, name, parent_id, image_url, sort_order, active
**products**
- id, tenant_id, category_id, sku, name, description
- price, cost, tax_rate, image_url, barcode
- track_inventory, min_stock, status
**product_variants**
- id, product_id, name, sku, price, attributes (JSONB)
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /categories | Listar categorias |
| GET | /categories/:id | Obtener categoria |
| POST | /categories | Crear categoria |
| PUT | /categories/:id | Actualizar categoria |
| DELETE | /categories/:id | Eliminar categoria |
| GET | /products | Listar productos |
| GET | /products/:id | Obtener producto |
| POST | /products | Crear producto |
| PUT | /products/:id | Actualizar producto |
| DELETE | /products/:id | Eliminar producto |
| GET | /products/search | Buscar productos |
| GET | /products/barcode/:code | Buscar por barcode |
## Flujos de Usuario
### Crear Producto Rapido
```
1. Dueno abre "Nuevo Producto"
2. Ingresa nombre y precio
3. Opcionalmente: foto, categoria, costo
4. Guarda
5. Producto disponible en POS
```
### Escanear Codigo de Barras
```
1. Dueno escanea codigo con camara
2. Sistema busca en BD
3. Si existe: muestra producto
4. Si no existe: ofrece crear nuevo
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL catalog schema | Completado | `05-catalog.sql` |
| categories.module | Completado | `modules/categories/` |
| products.module | Completado | `modules/products/` |
| Components FE | Completado | `components/products/` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
### Bloquea a
- MCH-004 (POS)
- MCH-007 (Templates)
- MCH-009 (Predicciones)
## Criterios de Aceptacion
- [x] CRUD categorias funcional
- [x] CRUD productos funcional
- [x] Variantes de producto funcionan
- [x] Busqueda por barcode funciona
- [x] Imagenes se guardan correctamente
- [x] Margen se calcula (precio - costo)
## UI Components
### ProductList
- Tabla con: imagen, nombre, precio, stock, acciones
- Filtros por categoria, estado
- Busqueda por nombre/SKU
### ProductForm
- Campos: nombre, precio, costo, categoria
- Upload de imagen
- Codigo de barras (manual o escaner)
- Toggle track_inventory
---
**Ultima actualizacion:** 2026-01-07

159
docs/01-epicas/MCH-004-punto-venta.md Normal file
View File

@ -0,0 +1,159 @@
# MCH-004: Punto de Venta Basico
## Metadata
- **Codigo:** MCH-004
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-06
## Descripcion
Sistema de punto de venta (POS) optimizado para micro-negocios: interfaz tactil rapida, carrito de compra, multiples metodos de pago, generacion de tickets, y registro de ventas.
## Objetivos
1. Grid de productos tactil
2. Carrito con modificacion de cantidades
3. Multiples metodos de pago
4. Generacion de ticket/recibo
5. Historial de ventas del dia
## Alcance
### Incluido
- Grid de productos por categoria
- Carrito con +/- cantidad
- Descuentos por item o total
- Metodos: efectivo, tarjeta, fiado
- Ticket imprimible/compartible
- Reporte diario de ventas
### Excluido
- Ventas con factura fiscal - MCH-027
- Pagos parciales mixtos - fase posterior
- Mesas/comandas (restaurante) - vertical separada
## Modelo de Datos
### Tablas (schema: sales)
**sales**
- id, tenant_id, user_id, customer_id
- subtotal, tax, discount, total
- payment_method, payment_reference
- status (completed/voided), notes, created_at
**sale_items**
- id, sale_id, product_id, quantity
- unit_price, discount, total
**payment_methods**
- id, tenant_id, name, type, settings, active
**cash_registers**
- id, tenant_id, name, opening_balance, current_balance, status
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /sales | Listar ventas |
| GET | /sales/:id | Obtener venta |
| POST | /sales | Registrar venta |
| POST | /sales/:id/void | Cancelar venta |
| GET | /sales/daily-report | Reporte del dia |
| GET | /sales/by-date | Ventas por rango |
## Flujos de Usuario
### Venta Rapida
```
1. Empleado abre POS
2. Selecciona productos del grid
- O escanea codigo de barras
3. Ajusta cantidades si necesario
4. Aplica descuento (opcional)
5. Selecciona metodo de pago
6. Si efectivo: ingresa monto recibido
7. Sistema calcula cambio
8. Genera ticket
9. Venta registrada
```
### Venta a Credito (Fiado)
```
1. Empleado agrega productos
2. Selecciona cliente existente
3. Elige "Fiado" como pago
4. Sistema verifica limite de credito
5. Si aprobado: registra venta
6. Actualiza saldo del cliente
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL sales schema | Completado | `06-sales.sql` |
| sales.module | Completado | `modules/sales/` |
| POS.tsx | Completado | `pages/POS.tsx` |
| Cart component | Completado | `components/pos/Cart.tsx` |
| PaymentModal | Completado | `components/pos/PaymentModal.tsx` |
| ReceiptModal | Completado | `components/pos/ReceiptModal.tsx` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
- MCH-003 (Productos)
### Bloquea a
- MCH-005 (Pagos)
- MCH-008 (Fiados)
- MCH-009 (Predicciones)
## Criterios de Aceptacion
- [x] Grid de productos carga correctamente
- [x] Carrito funciona (agregar/quitar/cantidad)
- [x] Descuentos se aplican correctamente
- [x] Pago en efectivo con cambio
- [x] Ticket se genera con todos los datos
- [x] Historial de ventas funcional
## UI Components
### POS Page
- Grid de productos (izquierda)
- Carrito (derecha)
- Barra de busqueda/escaneo
### ProductGrid
- Productos como cards con imagen
- Categorias como tabs
- Click para agregar al carrito
### Cart
- Lista de items con cantidad
- Botones +/- por item
- Total, descuento, impuesto
- Boton "Cobrar"
### PaymentModal
- Metodos de pago disponibles
- Campo monto recibido (efectivo)
- Calculo de cambio
- Boton confirmar
### ReceiptModal
- Datos del negocio
- Lista de productos
- Totales
- Botones: imprimir, compartir, cerrar
---
**Ultima actualizacion:** 2026-01-07

170
docs/01-epicas/MCH-005-integraciones-pago.md Normal file
View File

@ -0,0 +1,170 @@
# MCH-005: Integraciones de Pago
## Metadata
- **Codigo:** MCH-005
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07
## Descripcion
Integracion con proveedores de pago populares en Mexico para aceptar pagos con tarjeta: Mercado Pago (lector bluetooth), Clip, y efectivo. Soporte para suscripciones via Stripe.
## Objetivos
1. Integracion Mercado Pago Point
2. Integracion Clip
3. Registro de pagos en efectivo
4. Stripe para suscripciones
5. Conciliacion de pagos
## Alcance
### Incluido
- Mercado Pago Point (lector bluetooth)
- Clip (terminal)
- Efectivo (registro manual)
- Stripe (suscripciones y OXXO)
- Webhooks para confirmacion
### Excluido
- CoDi/SPEI - MCH-024
- Pagos QR propios - fase posterior
- Terminales bancarias tradicionales
## Proveedores
### Mercado Pago
- **Uso:** Pagos con tarjeta en tienda
- **Hardware:** Point Bluetooth
- **Comision:** ~3.5%
- **Integracion:** SDK + Webhooks
### Clip
- **Uso:** Pagos con tarjeta en tienda
- **Hardware:** Terminal Clip
- **Comision:** ~3.6%
- **Integracion:** SDK + Webhooks
### Stripe
- **Uso:** Suscripciones, pagos en linea, OXXO
- **Comision:** ~3.6% + $3 MXN
- **Integracion:** API + Webhooks
### Efectivo
- **Uso:** Pagos en efectivo
- **Registro:** Manual en POS
- **Control:** Corte de caja
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /payments/intent | Crear intencion de pago |
| POST | /payments/confirm | Confirmar pago |
| GET | /payments/:id | Obtener pago |
| POST | /payments/webhook | Webhook de proveedores |
| GET | /payments/methods | Metodos disponibles |
## Flujos de Pago
### Pago con Tarjeta (MercadoPago/Clip)
```
1. Venta creada en POS
2. Empleado selecciona "Tarjeta"
3. Se envia monto a terminal
4. Cliente pasa tarjeta
5. Webhook confirma pago
6. Venta marcada como pagada
7. Ticket generado
```
### Pago en Efectivo
```
1. Venta creada en POS
2. Empleado selecciona "Efectivo"
3. Ingresa monto recibido
4. Sistema calcula cambio
5. Venta registrada
6. Actualiza caja
```
### Pago OXXO (Stripe)
```
1. Cliente solicita pago en OXXO
2. Sistema genera referencia Stripe
3. Se muestra codigo de barras
4. Cliente paga en OXXO
5. Webhook confirma (24-48h)
6. Pedido/suscripcion activada
```
## Modelo de Datos
### Tablas
**payments** (en sales schema)
- id, sale_id, provider, amount
- reference, status, metadata
- created_at, confirmed_at
**payment_methods** (por tenant)
- id, tenant_id, provider, credentials
- settings, active
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| payments.module | Completado | `modules/payments/` |
| stripe.provider | Completado | `providers/stripe.provider.ts` |
| mercadopago.provider | Completado | `providers/mercadopago.provider.ts` |
| PaymentModal | Completado | `components/pos/PaymentModal.tsx` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
- MCH-004 (POS)
### Bloquea a
- MCH-018 (Suscripciones)
- MCH-020 (Pagos online)
## Criterios de Aceptacion
- [x] Mercado Pago procesa pagos
- [x] Webhooks se reciben correctamente
- [x] Efectivo registra correctamente
- [x] Stripe funciona para suscripciones
- [x] Conciliacion de pagos funciona
## Configuracion por Tenant
```typescript
// tenant_integrations
{
provider: 'mercadopago',
credentials: {
access_token: 'encrypted...',
public_key: '...'
},
settings: {
point_device_id: '...'
}
}
```
## Seguridad
- Credenciales encriptadas en BD
- Webhooks verificados con firma
- Logs de todas las transacciones
- PCI compliance delegado a proveedores
---
**Ultima actualizacion:** 2026-01-07

144
docs/01-epicas/MCH-006-onboarding-inteligente.md Normal file
View File

@ -0,0 +1,144 @@
# MCH-006: Onboarding Inteligente
## Metadata
- **Codigo:** MCH-006
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 5-6
## Descripcion
Sistema de onboarding conversacional via WhatsApp que permite a los duenos configurar su negocio enviando fotos de productos, notas de voz con precios, y seleccionando templates pre-cargados de proveedores comunes.
## Objetivos
1. Onboarding conversacional via WhatsApp
2. Carga de productos via fotos
3. Precios via notas de voz
4. Templates de proveedores comunes
5. Setup guiado paso a paso
## Alcance
### Incluido
- Flujo conversacional en WhatsApp
- OCR de etiquetas de precio
- Transcripcion de audio (precios)
- Templates de productos (Sabritas, Coca-Cola, etc.)
- Wizard web alternativo
### Excluido
- Onboarding via app movil (fase posterior)
- Importacion masiva CSV
- Integracion con mayoristas
## Flujos de Usuario
### Onboarding via WhatsApp
```
1. Dueno recibe mensaje de bienvenida
2. Bot pregunta nombre del negocio
3. Bot pregunta giro (abarrotes, papeleria, etc.)
4. Bot sugiere template de productos
5. Dueno confirma o ajusta
6. Bot pide foto de productos adicionales
7. OCR extrae nombre/precio
8. Dueno confirma/corrige via audio
9. Productos agregados al catalogo
```
### Carga de Producto por Foto
```
1. Dueno envia foto de producto
2. OCR detecta:
- Nombre del producto
- Codigo de barras
- Precio en etiqueta
3. Bot muestra: "Coca-Cola 600ml - $18?"
4. Dueno responde "Si" o corrige
5. Producto creado
```
### Carga de Precio por Audio
```
1. Dueno envia nota de voz
2. Whisper transcribe: "Sabritas a 15, Coca a 18"
3. Bot interpreta y confirma
4. Productos actualizados
```
## Componentes Tecnicos
### OCR Pipeline
- Google Vision API / Tesseract
- Deteccion de codigos de barras
- Extraccion de texto de etiquetas
- Matching con catalogo de productos conocidos
### Transcripcion
- Whisper API
- NLU para extraer entidades (producto, precio)
- Confirmacion interactiva
### Templates
- Catalogos pre-cargados de:
- Sabritas (snacks)
- Coca-Cola/Pepsi (bebidas)
- Bimbo (pan)
- Marinela (galletas)
- Productos genericos por giro
## Modelo de Datos
### Tablas Adicionales
**onboarding_sessions**
- id, tenant_id, status, current_step
- started_at, completed_at, metadata
**product_templates**
- id, giro, provider, name, sku
- default_price, image_url, barcode
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| onboarding.module | Pendiente | `modules/onboarding/` |
| OCR service | Pendiente | `services/ocr.service.ts` |
| Whisper service | Pendiente | `services/whisper.service.ts` |
| Templates seed | Pendiente | `seeds/product-templates/` |
| WhatsApp flows | Pendiente | `whatsapp-service/flows/` |
## Dependencias
### Depende de
- MCH-002 (Auth)
- MCH-003 (Productos)
- MCH-007 (Templates)
- MCH-011 (WhatsApp Service)
### Bloquea a
- Ninguno (mejora de UX)
## Criterios de Aceptacion
- [ ] Flujo WhatsApp funciona end-to-end
- [ ] OCR detecta productos con >80% precision
- [ ] Audio se transcribe correctamente
- [ ] Templates se cargan rapidamente
- [ ] Dueno puede completar setup en <10 min
## Metricas de Exito
| Metrica | Objetivo |
|---------|----------|
| Tiempo de onboarding | < 10 minutos |
| Productos cargados | > 20 en primera sesion |
| Precision OCR | > 80% |
| Abandono | < 20% |
---
**Ultima actualizacion:** 2026-01-07

173
docs/01-epicas/MCH-007-templates-catalogos.md Normal file
View File

@ -0,0 +1,173 @@
# MCH-007: Templates y Catalogos
## Metadata
- **Codigo:** MCH-007
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-07
## Descripcion
Sistema de templates pre-cargados con productos de proveedores comunes en Mexico (Sabritas, Coca-Cola, Bimbo, etc.) organizados por giro de negocio para acelerar el setup inicial.
## Objetivos
1. Catalogos de productos por proveedor
2. Templates por giro de negocio
3. Precios sugeridos actualizados
4. Imagenes de productos
5. Codigos de barras correctos
## Alcance
### Incluido
- Catalogo Sabritas/PepsiCo
- Catalogo Coca-Cola FEMSA
- Catalogo Bimbo/Marinela
- Catalogo Gamesa
- Catalogo productos genericos
- Giros: abarrotes, papeleria, farmacia, ferreteria
### Excluido
- Integracion en tiempo real con mayoristas
- Precios automaticos (requiere acuerdo)
- Productos frescos/perecederos
## Estructura de Templates
### Por Proveedor
```
templates/
├── proveedores/
│ ├── sabritas/
│ │ ├── metadata.json
│ │ └── productos.json (150+ SKUs)
│ ├── coca-cola/
│ │ ├── metadata.json
│ │ └── productos.json (100+ SKUs)
│ ├── bimbo/
│ ├── marinela/
│ └── gamesa/
└── giros/
├── abarrotes.json
├── papeleria.json
├── farmacia.json
└── ferreteria.json
```
### Por Giro de Negocio
```json
// giros/abarrotes.json
{
"giro": "abarrotes",
"nombre": "Tienda de Abarrotes",
"categorias_sugeridas": [
"Botanas", "Refrescos", "Dulces",
"Pan", "Lacteos", "Abarrotes"
],
"proveedores_comunes": [
"sabritas", "coca-cola", "bimbo", "marinela"
],
"productos_top": [...]
}
```
## Modelo de Datos
### Tablas
**product_templates** (global, sin tenant)
- id, provider, giro, category
- sku, name, description, barcode
- suggested_price, image_url
- metadata (JSONB), active
**template_imports** (por tenant)
- id, tenant_id, template_id
- imported_at, products_count
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /templates/giros | Listar giros |
| GET | /templates/giros/:giro | Productos de un giro |
| GET | /templates/providers | Listar proveedores |
| GET | /templates/providers/:provider | Productos de proveedor |
| POST | /templates/import | Importar template a tenant |
| GET | /templates/search | Buscar en templates |
## Flujos de Usuario
### Seleccionar Template al Onboarding
```
1. Sistema detecta giro del negocio
2. Muestra templates sugeridos
3. Dueno selecciona proveedores
4. Productos se importan al catalogo
5. Dueno ajusta precios si necesario
```
### Agregar Producto desde Template
```
1. Dueno busca producto en POS
2. No existe en su catalogo
3. Sistema busca en templates
4. Muestra "Coca-Cola 600ml - Agregar?"
5. Dueno confirma
6. Producto agregado con imagen y barcode
```
## Datos de Templates
### Sabritas (ejemplo)
| SKU | Producto | Barcode | Precio Sugerido |
|-----|----------|---------|-----------------|
| SAB001 | Sabritas Original 45g | 7501011111111 | $18 |
| SAB002 | Doritos Nacho 62g | 7501011111112 | $22 |
| SAB003 | Cheetos Flamin Hot 52g | 7501011111113 | $20 |
| SAB004 | Ruffles Queso 50g | 7501011111114 | $20 |
### Coca-Cola (ejemplo)
| SKU | Producto | Barcode | Precio Sugerido |
|-----|----------|---------|-----------------|
| CC001 | Coca-Cola 600ml | 7501055300000 | $18 |
| CC002 | Coca-Cola 2L | 7501055300001 | $35 |
| CC003 | Sprite 600ml | 7501055300002 | $18 |
| CC004 | Fanta 600ml | 7501055300003 | $18 |
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| templates.module | En progreso | `modules/templates/` |
| Seeds Sabritas | Pendiente | `seeds/templates/sabritas.json` |
| Seeds Coca-Cola | Pendiente | `seeds/templates/coca-cola.json` |
| Seeds Bimbo | Pendiente | `seeds/templates/bimbo.json` |
## Dependencias
### Depende de
- MCH-003 (Productos)
### Bloquea a
- MCH-006 (Onboarding)
## Criterios de Aceptacion
- [ ] 500+ productos en templates
- [ ] Imagenes de alta calidad
- [ ] Barcodes correctos y verificados
- [ ] Precios actualizados (2026)
- [ ] Import rapido (<5 seg para 100 productos)
## Actualizacion de Precios
- Frecuencia: Trimestral
- Fuente: Precios de lista de proveedores
- Nota: Son precios sugeridos, dueno puede ajustar
---
**Ultima actualizacion:** 2026-01-07

165
docs/01-epicas/MCH-008-sistema-fiados.md Normal file
View File

@ -0,0 +1,165 @@
# MCH-008: Sistema de Fiados
## Metadata
- **Codigo:** MCH-008
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-07
## Descripcion
Sistema de credito informal ("fiados") tradicional en Mexico: permite a clientes frecuentes comprar a credito con limites personalizados, recordatorios automaticos de pago, y registro de abonos.
## Objetivos
1. Cuentas de credito por cliente
2. Limites de credito configurables
3. Registro de compras a credito
4. Registro de abonos/pagos
5. Recordatorios automaticos via WhatsApp
6. Reporte de cartera
## Alcance
### Incluido
- Habilitar credito por cliente
- Limite de credito configurable
- Ventas a credito desde POS
- Abonos parciales o totales
- Historial de movimientos
- Recordatorios via WhatsApp
- Bloqueo automatico por limite
### Excluido
- Intereses por mora
- Scoring crediticio
- Reportes a buro de credito
- Contratos formales
## Modelo de Datos
### Tablas (schema: customers)
**credit_accounts**
- id, customer_id, credit_limit
- current_balance, status (active/blocked/closed)
- created_at, last_payment_at
**credit_transactions**
- id, credit_account_id, type (charge/payment)
- amount, sale_id (si es cargo), notes
- created_at, created_by
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /customers/:id/credit | Estado de cuenta |
| POST | /customers/:id/credit/enable | Habilitar credito |
| PUT | /customers/:id/credit/limit | Ajustar limite |
| POST | /customers/:id/credit/payment | Registrar abono |
| GET | /customers/:id/credit/history | Historial |
| GET | /credit/portfolio | Cartera total |
| GET | /credit/overdue | Clientes con adeudo |
## Flujos de Usuario
### Habilitar Credito
```
1. Dueno abre ficha del cliente
2. Activa "Habilitar fiado"
3. Define limite (ej: $500)
4. Cliente puede comprar a credito
```
### Venta a Credito
```
1. Empleado crea venta en POS
2. Selecciona cliente con credito
3. Elige "Fiado" como pago
4. Sistema verifica:
- Credito habilitado
- Saldo + venta <= limite
5. Si OK: registra venta
6. Actualiza saldo del cliente
```
### Registrar Abono
```
1. Cliente llega a pagar
2. Dueno abre cuenta del cliente
3. Registra abono (monto)
4. Sistema actualiza saldo
5. Genera recibo de pago
```
### Recordatorio Automatico
```
1. Cron diario revisa cuentas
2. Identifica clientes con saldo > X dias
3. Envia WhatsApp:
"Hola [nombre], tienes un saldo de $X
en [negocio]. Pasa a ponerte al corriente!"
4. Registra envio de recordatorio
```
## UI Components
### CreditHistory
- Lista de movimientos (cargos/abonos)
- Saldo actual
- Grafica de historial
- Filtros por fecha
### CreditDashboard
- Total cartera
- Clientes con adeudo
- Promedio de dias de pago
- Alertas de limite
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL credit | Completado | `08-customers.sql` |
| fiados.module | En progreso | `modules/fiados/` |
| CreditHistory.tsx | En progreso | `components/customers/` |
| WhatsApp reminder | Pendiente | `whatsapp-service/` |
## Dependencias
### Depende de
- MCH-002 (Auth)
- MCH-004 (POS)
- MCH-014 (Clientes)
### Bloquea a
- MCH-017 (Notificaciones)
## Criterios de Aceptacion
- [ ] Credito se habilita/deshabilita por cliente
- [ ] Limite de credito funciona
- [ ] Ventas a credito descuentan del disponible
- [ ] Abonos se registran correctamente
- [ ] Recordatorios se envian via WhatsApp
- [ ] Reporte de cartera funciona
## Configuracion por Tenant
```typescript
{
fiados: {
enabled: true,
default_limit: 500,
max_limit: 5000,
reminder_days: [7, 14, 30],
auto_block_days: 60
}
}
```
---
**Ultima actualizacion:** 2026-01-07

177
docs/01-epicas/MCH-009-prediccion-inventario.md Normal file
View File

@ -0,0 +1,177 @@
# MCH-009: Prediccion de Inventario
## Metadata
- **Codigo:** MCH-009
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 6-7
## Descripcion
Sistema de prediccion de inventario basado en historico de ventas: alertas de stock bajo, sugerencias de reabastecimiento, prediccion de demanda, y deteccion de productos de lento movimiento.
## Objetivos
1. Alertas de stock bajo
2. Prediccion de demanda semanal
3. Sugerencias de pedido a proveedor
4. Deteccion de productos sin movimiento
5. Dias de inventario estimados
## Alcance
### Incluido
- Alerta cuando stock < min_stock
- Prediccion basada en promedio movil
- Calculo de punto de reorden
- Lista de sugerencias de compra
- Productos sin venta en X dias
### Excluido
- ML avanzado (LSTM, Prophet)
- Integracion automatica con proveedores
- Pedidos automaticos
## Algoritmos
### Prediccion de Demanda
```
Promedio Movil Ponderado (4 semanas)
- Semana -1: peso 0.4
- Semana -2: peso 0.3
- Semana -3: peso 0.2
- Semana -4: peso 0.1
Demanda_estimada = Σ(ventas_semana * peso)
```
### Punto de Reorden
```
Punto_reorden = (Demanda_diaria * Lead_time) + Stock_seguridad
Donde:
- Demanda_diaria = Demanda_semanal / 7
- Lead_time = dias para recibir pedido (default: 3)
- Stock_seguridad = Demanda_diaria * 2
```
### Dias de Inventario
```
Dias_inventario = Stock_actual / Demanda_diaria
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /inventory/low-stock | Productos bajo minimo |
| GET | /inventory/predictions | Predicciones de demanda |
| GET | /inventory/reorder-suggestions | Sugerencias de pedido |
| GET | /inventory/slow-moving | Productos sin movimiento |
| GET | /inventory/days-on-hand | Dias de inventario |
| GET | /inventory/analytics | Dashboard completo |
## Modelo de Datos
### Tablas Adicionales
**inventory_predictions** (cache)
- id, product_id, period_start, period_end
- predicted_demand, confidence
- calculated_at
**reorder_suggestions**
- id, tenant_id, product_id
- current_stock, suggested_quantity
- priority, status, created_at
## Flujos de Usuario
### Alerta de Stock Bajo
```
1. Sistema detecta stock < min_stock
2. Genera notificacion push
3. Muestra en dashboard
4. Dueno revisa y decide
```
### Ver Sugerencias de Pedido
```
1. Dueno abre "Sugerencias de compra"
2. Ve lista ordenada por prioridad
3. Cada item muestra:
- Producto
- Stock actual
- Cantidad sugerida
- Proveedor (si conocido)
4. Puede marcar como "Pedido"
```
### Reporte Semanal
```
1. Lunes a las 8am
2. Sistema genera reporte:
- Top 10 productos por venta
- Productos a reordenar
- Productos sin movimiento
3. Envia via WhatsApp al dueno
```
## UI Components
### InventoryDashboard
- Grafica de stock vs demanda
- Lista de alertas
- Indicadores clave
### ReorderList
- Tabla de sugerencias
- Filtros por categoria
- Accion: marcar como pedido
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| predictions.service | Pendiente | `services/predictions.service.ts` |
| inventory.analytics | Pendiente | `modules/inventory/analytics/` |
| Dashboard FE | Pendiente | `components/inventory/` |
| Cron jobs | Pendiente | `jobs/inventory.jobs.ts` |
## Dependencias
### Depende de
- MCH-003 (Productos)
- MCH-004 (POS) - historial de ventas
- MCH-007 (Inventory module base)
### Bloquea a
- MCH-012 (Chat LLM puede consultar predicciones)
## Criterios de Aceptacion
- [ ] Alertas de stock bajo funcionan
- [ ] Predicciones tienen precision >70%
- [ ] Sugerencias de reorden son utiles
- [ ] Productos sin movimiento se detectan
- [ ] Dashboard muestra info clara
## Configuracion por Tenant
```typescript
{
predictions: {
enabled: true,
low_stock_threshold: 5,
lead_time_days: 3,
safety_stock_days: 2,
slow_moving_days: 30,
weekly_report_enabled: true
}
}
```
---
**Ultima actualizacion:** 2026-01-07

226
docs/01-epicas/MCH-010-mcp-server.md Normal file
View File

@ -0,0 +1,226 @@
# MCH-010: MCP Server
## Metadata
- **Codigo:** MCH-010
- **Fase:** 3 - Asistente IA
- **Prioridad:** P0
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-06
## Descripcion
Gateway LLM agnostico usando el protocolo MCP (Model Context Protocol) de Anthropic. Permite conectar multiples proveedores de LLM (Claude, GPT-4, Llama) con tools especificos para el negocio.
## Objetivos
1. Gateway LLM agnostico (OpenRouter)
2. Tools MCP para operaciones del negocio
3. Contexto por tenant (productos, ventas)
4. Rate limiting por tokens
5. Logging de conversaciones
## Alcance
### Incluido
- MCP Server con TypeScript
- Tools para: productos, ventas, inventario, clientes
- Routing a multiples LLMs via OpenRouter
- Contexto del negocio en prompts
- Control de consumo de tokens
### Excluido
- Entrenamiento de modelos propios
- Fine-tuning
- Vision/imagenes (fase posterior)
## Arquitectura
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Mobile │ │ WhatsApp │ │ Web │
│ App │ │ Service │ │ Dashboard │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌──────▼──────┐
│ MCP Server │
│ (Gateway) │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌───▼───┐ ┌─────▼─────┐
│ OpenRouter │ │ Claude│ │ GPT-4 │
│ (Default) │ │ API │ │ API │
└─────────────┘ └───────┘ └───────────┘
```
## Tools MCP
### Products
```typescript
{
name: "search_products",
description: "Buscar productos en el catalogo",
parameters: {
query: string,
category?: string
}
}
{
name: "get_product_stock",
description: "Obtener stock de un producto",
parameters: {
product_id: string
}
}
{
name: "update_product_price",
description: "Actualizar precio de producto",
parameters: {
product_id: string,
new_price: number
}
}
```
### Sales
```typescript
{
name: "get_daily_sales",
description: "Obtener ventas del dia",
parameters: {
date?: string
}
}
{
name: "get_sales_report",
description: "Reporte de ventas por periodo",
parameters: {
start_date: string,
end_date: string
}
}
```
### Inventory
```typescript
{
name: "get_low_stock_products",
description: "Productos con stock bajo",
parameters: {}
}
{
name: "get_inventory_value",
description: "Valor total del inventario",
parameters: {}
}
```
### Customers
```typescript
{
name: "search_customers",
description: "Buscar clientes",
parameters: {
query: string
}
}
{
name: "get_customer_balance",
description: "Saldo de fiado de cliente",
parameters: {
customer_id: string
}
}
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /mcp/chat | Enviar mensaje al LLM |
| GET | /mcp/tools | Listar tools disponibles |
| GET | /mcp/history | Historial de conversacion |
| POST | /mcp/feedback | Feedback de respuesta |
## Modelo de Datos
### Tablas (schema: ai)
**conversations**
- id, tenant_id, user_id, channel
- started_at, last_message_at
**messages**
- id, conversation_id, role, content
- tokens_used, model, created_at
**tool_calls**
- id, message_id, tool_name
- parameters, result, duration_ms
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| MCP Server base | En progreso | `apps/mcp-server/` |
| Tools products | Pendiente | `tools/products.tool.ts` |
| Tools sales | Pendiente | `tools/sales.tool.ts` |
| Tools inventory | Pendiente | `tools/inventory.tool.ts` |
| OpenRouter client | En progreso | `clients/openrouter.ts` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth) - para context del tenant
- MCH-003 (Productos) - para tools
- MCH-004 (Sales) - para tools
### Bloquea a
- MCH-011 (WhatsApp usa MCP)
- MCH-012 (Chat dueno)
- MCH-013 (Chat cliente)
## Criterios de Aceptacion
- [ ] MCP Server responde correctamente
- [ ] Tools ejecutan operaciones reales
- [ ] Contexto del tenant se incluye
- [ ] Rate limiting por tokens funciona
- [ ] Logs de conversacion completos
## Configuracion
```typescript
// config/mcp.config.ts
{
defaultProvider: 'openrouter',
providers: {
openrouter: {
apiKey: process.env.OPENROUTER_API_KEY,
defaultModel: 'anthropic/claude-3-haiku'
},
anthropic: {
apiKey: process.env.ANTHROPIC_API_KEY
}
},
maxTokensPerRequest: 4000,
maxTokensPerDay: 50000
}
```
## Puerto
- **MCP Server:** 3142
---
**Ultima actualizacion:** 2026-01-07

219
docs/01-epicas/MCH-011-whatsapp-service.md Normal file
View File

@ -0,0 +1,219 @@
# MCH-011: WhatsApp Service
## Metadata
- **Codigo:** MCH-011
- **Fase:** 3 - Asistente IA
- **Prioridad:** P0
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-06
## Descripcion
Servicio de integracion con WhatsApp Business API de Meta. Permite a los negocios recibir y enviar mensajes, procesar pedidos, enviar notificaciones, y conectar con el asistente IA.
## Objetivos
1. Integracion Meta WhatsApp Business API
2. Webhooks para mensajes entrantes
3. Envio de mensajes/templates
4. Multi-numero por tenant
5. Conexion con MCP Server
## Alcance
### Incluido
- WhatsApp Business API (Cloud)
- Recepcion de mensajes (texto, audio, imagen)
- Envio de mensajes y templates
- Procesamiento via MCP Server
- Webhooks verificados
- Cola de mensajes (Redis)
### Excluido
- WhatsApp Web (no oficial)
- Grupos de WhatsApp
- Estados/historias
- Llamadas de voz/video
## Arquitectura
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Cliente │────▶│ Meta │────▶│ Webhook │
│ WhatsApp │◀────│ Cloud API │◀────│ Handler │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌──────▼──────┐
│ Redis │
│ (Queue) │
└──────┬──────┘
│
┌──────▼──────┐
│ Processor │
│ Worker │
└──────┬──────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
┌──────▼──────┐ ┌───────▼───────┐ ┌──────▼──────┐
│ MCP Server │ │ Backend │ │ Templates │
│ (Chat IA) │ │ API │ │ Service │
└─────────────┘ └───────────────┘ └─────────────┘
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /whatsapp/webhook | Webhook de Meta |
| GET | /whatsapp/webhook | Verificacion webhook |
| POST | /whatsapp/send | Enviar mensaje |
| POST | /whatsapp/template | Enviar template |
| GET | /whatsapp/conversations | Conversaciones |
| GET | /whatsapp/messages/:conversationId | Mensajes |
## Tipos de Mensaje
### Entrantes
- **text**: Mensaje de texto
- **audio**: Nota de voz (se transcribe)
- **image**: Imagen (OCR si aplica)
- **location**: Ubicacion (para entregas)
- **interactive**: Respuesta de botones/lista
### Salientes
- **text**: Mensaje de texto
- **template**: Mensaje pre-aprobado
- **interactive**: Botones o lista
- **media**: Imagen, documento, audio
## Templates Pre-aprobados
### Recordatorio de Pago
```
Hola {{1}}, te recordamos que tienes un saldo
pendiente de ${{2}} en {{3}}.
¿Cuando podrias pasar a liquidar?
```
### Confirmacion de Pedido
```
¡Pedido recibido! 🛒
{{1}}
Total: ${{2}}
Entrega estimada: {{3}}
¿Confirmas tu pedido?
[Si, confirmar] [Cancelar]
```
### Pedido Listo
```
¡Tu pedido esta listo! 📦
Puedes pasar a recogerlo a {{1}}
o lo enviamos a tu domicilio.
[Voy para alla] [Enviar a domicilio]
```
## Modelo de Datos
### Tablas (schema: messaging)
**conversations**
- id, tenant_id, customer_phone
- wa_conversation_id, status
- last_message_at, metadata
**messages**
- id, conversation_id, direction (in/out)
- type, content, status
- wa_message_id, created_at
## Flujos
### Mensaje Entrante
```
1. Meta envia POST a /webhook
2. Validamos firma del request
3. Extraemos mensaje y metadata
4. Encolamos en Redis
5. Worker procesa:
a. Identifica tenant por numero
b. Busca/crea conversacion
c. Si es texto: envia a MCP
d. Si es audio: transcribe, luego MCP
e. Si es imagen: OCR si necesario
6. MCP responde con accion
7. Enviamos respuesta al cliente
```
### Envio de Notificacion
```
1. Backend trigger (ej: recordatorio fiado)
2. Busca template apropiado
3. Llena variables
4. POST a Meta API
5. Registra en BD
6. Espera delivery report
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| WhatsApp Service | En progreso | `apps/whatsapp-service/` |
| Webhook handler | En progreso | `handlers/webhook.handler.ts` |
| Message processor | Pendiente | `workers/message.worker.ts` |
| Template service | Pendiente | `services/template.service.ts` |
## Dependencias
### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
- MCH-010 (MCP Server)
### Bloquea a
- MCH-006 (Onboarding via WhatsApp)
- MCH-012 (Chat dueno)
- MCH-013 (Chat cliente)
- MCH-015 (Pedidos via WhatsApp)
## Criterios de Aceptacion
- [ ] Webhook recibe mensajes correctamente
- [ ] Mensajes se procesan via MCP
- [ ] Templates se envian correctamente
- [ ] Multi-tenant funciona (routing por numero)
- [ ] Audio se transcribe correctamente
## Configuracion por Tenant
```typescript
// tenant_integrations
{
provider: 'whatsapp',
credentials: {
phone_number_id: '...',
access_token: 'encrypted...',
verify_token: '...'
},
settings: {
business_name: 'Mi Tiendita',
auto_reply: true,
ai_enabled: true
}
}
```
## Puerto
- **WhatsApp Service:** 3143
---
**Ultima actualizacion:** 2026-01-07

187
docs/01-epicas/MCH-012-chat-llm-dueno.md Normal file
View File

@ -0,0 +1,187 @@
# MCH-012: Chat LLM Dueno
## Metadata
- **Codigo:** MCH-012
- **Fase:** 3 - Asistente IA
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 7-8
## Descripcion
Asistente IA conversacional para duenos de negocio: consultas de ventas, inventario, clientes; generacion de reportes; sugerencias de negocio; todo via chat en la app o WhatsApp.
## Objetivos
1. Chat conversacional en app/WhatsApp
2. Consultas de ventas y metricas
3. Gestion de inventario via chat
4. Alertas y sugerencias proactivas
5. Generacion de reportes por voz
## Alcance
### Incluido
- "¿Cuanto vendi hoy/esta semana?"
- "¿Cuantas Cocas me quedan?"
- "Sube el precio de las Sabritas a $20"
- "¿Quien me debe mas?"
- "Dame el reporte de la semana"
- Alertas: stock bajo, pagos pendientes
### Excluido
- Operaciones bancarias
- Gestion de empleados avanzada
- Analisis financiero complejo
## Casos de Uso
### Consulta de Ventas
```
Dueno: "¿Cuanto vendi hoy?"
Bot: "Hoy llevas $3,450 en 23 ventas.
Top productos: Coca-Cola (15), Sabritas (12).
Comparado con ayer: +15% 📈"
```
### Consulta de Inventario
```
Dueno: "¿Tengo Coca de 600?"
Bot: "Te quedan 8 Coca-Cola 600ml.
Al ritmo actual, duraran ~2 dias.
¿Quieres que te recuerde hacer pedido?"
```
### Modificar Precio
```
Dueno: "Sube las Sabritas a 20 pesos"
Bot: "Actualizo precio de Sabritas Original
de $18 a $20. ¿Confirmas?"
Dueno: "Si"
Bot: "Listo, precio actualizado ✓"
```
### Consulta de Fiados
```
Dueno: "¿Quien me debe mas?"
Bot: "Tus clientes con mayor adeudo:
1. Juan Perez: $850 (15 dias)
2. Maria Lopez: $420 (7 dias)
3. Pedro Garcia: $380 (3 dias)
¿Quieres enviar recordatorio?"
```
### Reporte Semanal
```
Dueno: "Dame el reporte de la semana"
Bot: "📊 Reporte Semanal (Ene 1-7)
💰 Ventas: $24,350 (+8% vs anterior)
📦 Transacciones: 156
🎫 Ticket promedio: $156
Top 5 productos:
1. Coca-Cola 600ml - 89 unidades
2. Sabritas - 67 unidades
...
⚠️ 3 productos con stock bajo
💳 Cartera por cobrar: $2,150"
```
## Flujo Tecnico
```
1. Dueno envia mensaje (app o WhatsApp)
2. WhatsApp Service recibe
3. Identifica como chat de dueno
4. Envia a MCP Server con contexto:
- tenant_id
- user_role: "owner"
- tools: todos disponibles
5. MCP procesa con LLM
6. LLM decide tool calls necesarios
7. Ejecuta tools (consultas/acciones)
8. Genera respuesta natural
9. Envia respuesta al dueno
```
## Tools Especificos
```typescript
// Tools habilitados para dueno
const ownerTools = [
'search_products',
'get_product_stock',
'update_product_price',
'get_daily_sales',
'get_sales_report',
'get_low_stock_products',
'search_customers',
'get_customer_balance',
'send_payment_reminder',
'get_top_products',
'get_business_metrics'
];
```
## Alertas Proactivas
### Stock Bajo
```
Enviado: 9:00 AM
"🔔 Alerta de inventario
3 productos estan por agotarse:
- Coca-Cola 600ml (5 unidades)
- Pan Bimbo (3 unidades)
- Leche (4 unidades)
¿Quieres ver sugerencia de pedido?"
```
### Recordatorio de Cobro
```
Enviado: 10:00 AM Lunes
"💰 Tienes $2,150 en fiados pendientes.
5 clientes deben desde hace +7 dias.
¿Envio recordatorios automaticos?"
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Owner chat flow | Pendiente | `whatsapp-service/flows/owner.flow.ts` |
| MCP tools completos | Pendiente | `mcp-server/tools/` |
| Alert scheduler | Pendiente | `backend/jobs/alerts.job.ts` |
| App chat UI | Pendiente | `mobile/screens/Chat.tsx` |
## Dependencias
### Depende de
- MCH-010 (MCP Server)
- MCH-011 (WhatsApp Service)
- MCH-003, 004, 008, 009 (datos)
### Bloquea a
- Ninguno (mejora de UX)
## Criterios de Aceptacion
- [ ] Consultas de venta funcionan
- [ ] Consultas de inventario funcionan
- [ ] Modificacion de precios funciona
- [ ] Consultas de fiados funcionan
- [ ] Alertas proactivas se envian
- [ ] Reportes se generan correctamente
## Limites de Tokens
| Plan | Tokens/mes | Interacciones aprox |
|------|------------|---------------------|
| Changarrito | 500 | ~100 conversaciones |
| Tiendita | 2000 | ~400 conversaciones |
---
**Ultima actualizacion:** 2026-01-07

215
docs/01-epicas/MCH-013-chat-llm-cliente.md Normal file
View File

@ -0,0 +1,215 @@
# MCH-013: Chat LLM Cliente
## Metadata
- **Codigo:** MCH-013
- **Fase:** 3 - Asistente IA
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 8-9
## Descripcion
Asistente IA para clientes del negocio via WhatsApp: consulta de precios, disponibilidad de productos, hacer pedidos, consultar saldo de fiado, y recibir promociones.
## Objetivos
1. Consulta de precios y disponibilidad
2. Hacer pedidos via chat
3. Consultar saldo de fiado
4. Recibir catalogo de productos
5. Atender preguntas frecuentes
## Alcance
### Incluido
- "¿Tienen Coca de 2 litros?"
- "¿Cuanto cuesta el pan Bimbo?"
- "Quiero pedir 2 Cocas y unas Sabritas"
- "¿Cuanto debo?"
- "¿A que hora cierran?"
- Catalogo de productos (imagen)
### Excluido
- Pagos en linea (fase posterior)
- Tracking de entrega en tiempo real
- Cambios/devoluciones via chat
## Casos de Uso
### Consulta de Precio
```
Cliente: "¿Cuanto cuesta la Coca?"
Bot: "Tenemos Coca-Cola en varios tamaños:
- 355ml (lata): $15
- 600ml: $18
- 2L: $35
- 3L: $48
¿Cual te gustaria?"
```
### Consulta de Disponibilidad
```
Cliente: "¿Tienen pan Bimbo?"
Bot: "Si, tenemos:
✓ Pan Blanco Grande - $48
✓ Pan Integral - $52
✗ Pan Tostado - Agotado
¿Quieres agregar alguno a tu pedido?"
```
### Hacer Pedido
```
Cliente: "Quiero 2 Cocas de 600 y unas Sabritas"
Bot: "Tu pedido:
- 2x Coca-Cola 600ml = $36
- 1x Sabritas Original = $18
Total: $54
¿Lo confirmas?
[Confirmar] [Agregar mas] [Cancelar]"
Cliente: [Confirmar]
Bot: "¡Pedido confirmado! 🎉
Numero: #123
Estara listo en 10 minutos.
Te avisamos cuando puedas pasar."
```
### Consulta de Fiado
```
Cliente: "¿Cuanto debo?"
Bot: "Hola Juan, tu saldo actual es de $180.
Ultimo movimiento: $45 el 5 de enero.
Puedes pasar a abonar cuando gustes."
```
### Horarios y Ubicacion
```
Cliente: "¿A que hora abren?"
Bot: "Tiendita Don Jose 🏪
📍 Calle Principal #123
Horario:
Lun-Sab: 7am - 10pm
Dom: 8am - 8pm
¿Te puedo ayudar en algo mas?"
```
## Flujo Tecnico
```
1. Cliente envia mensaje a numero del negocio
2. WhatsApp Service recibe
3. Identifica como cliente (no dueno)
4. Envia a MCP Server con contexto:
- tenant_id
- customer_phone
- customer_id (si existe)
- tools: limitados para cliente
5. MCP procesa con LLM
6. Ejecuta tools (consultas/pedido)
7. Genera respuesta amigable
8. Envia respuesta al cliente
```
## Tools Limitados para Cliente
```typescript
// Tools habilitados para clientes
const customerTools = [
'search_products',
'get_product_price',
'check_availability',
'create_order',
'get_my_balance',
'get_business_info',
'get_promotions'
];
// Tools NO disponibles para clientes
// - update_product_price
// - get_sales_report
// - send_payment_reminder
// - etc.
```
## Intents del Cliente
| Intent | Ejemplo | Accion |
|--------|---------|--------|
| CONSULTA_PRECIO | "Cuanto cuesta..." | search_products |
| CONSULTA_DISPONIBILIDAD | "Tienen..." | check_availability |
| HACER_PEDIDO | "Quiero pedir..." | create_order |
| CONSULTA_SALDO | "Cuanto debo" | get_my_balance |
| HORARIOS | "A que hora..." | get_business_info |
| UBICACION | "Donde estan" | get_business_info |
| PROMOCIONES | "Que ofertas tienen" | get_promotions |
## Modelo de Datos
### Asociacion Cliente-Telefono
```typescript
// Al recibir mensaje de numero nuevo
1. Buscar en customers por phone
2. Si existe: asociar conversacion
3. Si no existe: crear customer temporal
4. Si hace pedido: pedir nombre
```
## Limites y Seguridad
- Clientes NO pueden ver info de otros clientes
- Clientes NO pueden modificar precios
- Clientes NO pueden ver reportes
- Rate limit: 20 mensajes/hora por cliente
- Tokens: descontados de cuota del tenant
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Customer chat flow | Pendiente | `whatsapp-service/flows/customer.flow.ts` |
| MCP tools (limited) | Pendiente | `mcp-server/tools/customer/` |
| Order creation | Pendiente | `backend/modules/orders/` |
| FAQ responses | Pendiente | `whatsapp-service/faq/` |
## Dependencias
### Depende de
- MCH-010 (MCP Server)
- MCH-011 (WhatsApp Service)
- MCH-014 (Gestion Clientes)
### Bloquea a
- MCH-015 (Pedidos via WhatsApp)
## Criterios de Aceptacion
- [ ] Consultas de precio funcionan
- [ ] Consultas de disponibilidad funcionan
- [ ] Pedidos se crean correctamente
- [ ] Saldo de fiado se muestra
- [ ] Info del negocio se muestra
- [ ] No hay fuga de informacion
## Personalizacion por Tenant
```typescript
// tenant_settings
{
whatsapp_bot: {
greeting: "¡Hola! Bienvenido a {{business_name}}",
farewell: "¡Gracias por tu preferencia!",
tone: "friendly", // formal, friendly, casual
auto_suggest_products: true,
show_promotions: true
}
}
```
---
**Ultima actualizacion:** 2026-01-07

197
docs/01-epicas/MCH-014-gestion-clientes.md Normal file
View File

@ -0,0 +1,197 @@
# MCH-014: Gestion de Clientes
## Metadata
- **Codigo:** MCH-014
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P1
- **Estado:** Completado
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07
## Descripcion
Sistema completo de gestion de clientes: registro, historial de compras, saldo de fiado, comunicacion via WhatsApp, y segmentacion basica.
## Objetivos
1. CRUD de clientes
2. Historial de compras por cliente
3. Integracion con sistema de fiados
4. Comunicacion via WhatsApp
5. Segmentacion basica (frecuencia, monto)
## Alcance
### Incluido
- Registro de clientes (nombre, telefono, direccion)
- Historial de compras
- Saldo de fiado integrado
- Envio de mensajes WhatsApp
- Tags/etiquetas para segmentacion
- Notas por cliente
### Excluido
- CRM avanzado
- Campanas de marketing automatizadas
- Programas de lealtad (fase posterior)
## Modelo de Datos
### Tablas (schema: customers)
**customers**
- id, tenant_id, name, phone
- email (opcional), address
- credit_enabled, credit_limit, balance
- tags (JSONB), notes, status
- first_purchase_at, last_purchase_at
- total_purchases, total_spent
**customer_purchases** (vista agregada)
- Derivado de sales por customer_id
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /customers | Listar clientes |
| GET | /customers/:id | Obtener cliente |
| POST | /customers | Crear cliente |
| PUT | /customers/:id | Actualizar cliente |
| DELETE | /customers/:id | Eliminar cliente |
| GET | /customers/:id/purchases | Historial compras |
| GET | /customers/:id/credit | Estado de fiado |
| POST | /customers/:id/message | Enviar WhatsApp |
| GET | /customers/segments | Segmentos |
## Flujos de Usuario
### Registrar Cliente Nuevo
```
1. Durante venta, empleado pregunta nombre
2. Ingresa telefono (obligatorio para fiado)
3. Cliente creado con datos basicos
4. Opcionalmente: direccion para entregas
```
### Ver Historial de Cliente
```
1. Dueno busca cliente por nombre/telefono
2. Abre ficha del cliente
3. Ve:
- Datos de contacto
- Total comprado historico
- Ultimas 10 compras
- Saldo de fiado
- Notas
```
### Enviar Mensaje WhatsApp
```
1. Dueno abre ficha de cliente
2. Click en "Enviar WhatsApp"
3. Selecciona template o escribe mensaje
4. Mensaje enviado via WhatsApp Service
```
### Segmentar Clientes
```
1. Dueno abre lista de clientes
2. Filtra por:
- Con/sin fiado
- Frecuencia (semanal, mensual, ocasional)
- Monto (alto, medio, bajo)
3. Puede asignar tags personalizados
```
## UI Components
### CustomerList
- Tabla con: nombre, telefono, total, fiado
- Busqueda por nombre/telefono
- Filtros por tags, estado
### CustomerForm
- Campos: nombre, telefono, email, direccion
- Toggle credito + limite
- Tags
- Notas
### CustomerDetail
- Info de contacto
- Metricas: total, # compras, promedio
- Historial de compras
- Historial de fiado
- Boton WhatsApp
### CreditHistory
- Lista de movimientos
- Grafica de saldo en el tiempo
- Botones: registrar abono, enviar recordatorio
## Segmentacion
### Por Frecuencia
| Segmento | Criterio |
|----------|----------|
| Frecuente | >= 4 compras/mes |
| Regular | 2-3 compras/mes |
| Ocasional | 1 compra/mes |
| Inactivo | 0 compras en 30 dias |
### Por Valor
| Segmento | Criterio |
|----------|----------|
| Alto valor | >= $2000/mes |
| Medio | $500-$2000/mes |
| Bajo | < $500/mes |
### Tags Personalizados
- Ejemplos: "vecino", "oficina", "escuela", "mayoreo"
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL customers | Completado | `08-customers.sql` |
| customers.module | Completado | `modules/customers/` |
| Customers.tsx | Completado | `pages/Customers.tsx` |
| CustomerList.tsx | Completado | `components/customers/` |
| CustomerForm.tsx | Completado | `components/customers/` |
## Dependencias
### Depende de
- MCH-002 (Auth)
- MCH-004 (Sales - para historial)
### Bloquea a
- MCH-008 (Fiados)
- MCH-013 (Chat cliente)
- MCH-015 (Pedidos WhatsApp)
## Criterios de Aceptacion
- [x] CRUD de clientes funciona
- [x] Historial de compras se muestra
- [x] Fiado integrado correctamente
- [x] Busqueda por nombre/telefono
- [x] Tags funcionan
- [x] Boton WhatsApp envia mensaje
## Metricas Calculadas
```typescript
// Se actualizan en cada venta
customer.total_purchases++
customer.total_spent += sale.total
customer.last_purchase_at = new Date()
// Calculo de segmento (batch job diario)
customer.frequency_segment = calculateFrequency(customer)
customer.value_segment = calculateValue(customer)
```
---
**Ultima actualizacion:** 2026-01-07

196
docs/01-epicas/MCH-015-pedidos-whatsapp.md Normal file
View File

@ -0,0 +1,196 @@
# MCH-015: Pedidos via WhatsApp
## Metadata
- **Codigo:** MCH-015
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 9-10
## Descripcion
Sistema completo de pedidos via WhatsApp: clientes pueden hacer pedidos conversando con el bot, el negocio recibe notificaciones, procesa el pedido, y confirma al cliente.
## Objetivos
1. Recepcion de pedidos via chat
2. Confirmacion automatica o manual
3. Notificacion al negocio
4. Estado del pedido en tiempo real
5. Historial de pedidos por cliente
## Alcance
### Incluido
- Pedidos via chat natural (NLU)
- Carrito conversacional
- Confirmacion de pedido
- Notificacion push/WhatsApp al dueno
- Estados: recibido, preparando, listo, entregado
- Cancelacion de pedido
### Excluido
- Pagos en linea dentro de WhatsApp
- Integracion con delivery apps (Rappi, Uber)
- Pedidos programados
## Flujo de Pedido
### Cliente Hace Pedido
```
Cliente: "Quiero pedir 2 Cocas y unas Sabritas"
Bot: "Perfecto! Tu pedido:
- 2x Coca-Cola 600ml = $36
- 1x Sabritas Original = $18
Total: $54
¿Lo confirmas?
[Confirmar] [Agregar mas] [Cancelar]"
Cliente: [Confirmar]
Bot: "¡Pedido #456 confirmado! 🎉
Te avisamos cuando este listo.
Tiempo estimado: 10-15 min"
```
### Negocio Recibe Notificacion
```
[Push + WhatsApp al dueno]
"🛒 Nuevo Pedido #456
Cliente: Juan Perez (5512345678)
- 2x Coca-Cola 600ml
- 1x Sabritas Original
Total: $54
[Ver pedido] [Aceptar] [Rechazar]"
```
### Actualizacion de Estado
```
[Dueno marca como "Listo"]
Bot -> Cliente:
"Tu pedido #456 esta listo! 📦
Puedes pasar a recogerlo.
Direccion: Calle Principal #123
Horario: Abierto hasta 10pm"
```
## Modelo de Datos
### Tablas (schema: orders)
**orders**
- id, tenant_id, customer_id, channel
- status (pending/confirmed/preparing/ready/delivered/cancelled)
- subtotal, delivery_fee, total
- delivery_type (pickup/delivery)
- delivery_address, scheduled_at
- notes, created_at, updated_at
**order_items**
- id, order_id, product_id
- quantity, unit_price, notes, total
**order_status_history**
- id, order_id, status, changed_by
- notes, created_at
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /orders | Listar pedidos |
| GET | /orders/:id | Obtener pedido |
| POST | /orders | Crear pedido |
| PUT | /orders/:id/status | Cambiar estado |
| POST | /orders/:id/cancel | Cancelar pedido |
| GET | /orders/pending | Pedidos pendientes |
| GET | /customers/:id/orders | Pedidos de cliente |
## Estados del Pedido
```
pending ──► confirmed ──► preparing ──► ready ──► delivered
│ │ │ │
└───────────┴─────────────┴───────────┴──► cancelled
```
| Estado | Descripcion | Notifica Cliente |
|--------|-------------|------------------|
| pending | Pedido recibido | Si |
| confirmed | Aceptado por negocio | Si |
| preparing | En preparacion | No |
| ready | Listo para recoger/enviar | Si |
| delivered | Entregado | Si |
| cancelled | Cancelado | Si |
## UI Components
### OrderList (Dashboard)
- Tabla de pedidos del dia
- Filtros por estado
- Acciones rapidas
### OrderDetail
- Info del cliente
- Items del pedido
- Cambio de estado
- Historial de estados
### OrderNotification (Mobile)
- Push notification
- Sonido distintivo
- Accion rapida: Aceptar/Rechazar
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| orders.module | Completado | `modules/orders/` |
| WhatsApp order flow | Pendiente | `whatsapp-service/flows/order.flow.ts` |
| Order notifications | Pendiente | `services/order-notification.service.ts` |
| Orders dashboard | Pendiente | `pages/Orders.tsx` |
## Dependencias
### Depende de
- MCH-011 (WhatsApp Service)
- MCH-013 (Chat cliente)
- MCH-014 (Gestion clientes)
### Bloquea a
- MCH-016 (Entregas a domicilio)
## Criterios de Aceptacion
- [ ] Pedidos se crean via WhatsApp
- [ ] Dueno recibe notificacion inmediata
- [ ] Estados se actualizan correctamente
- [ ] Cliente recibe confirmaciones
- [ ] Historial de pedidos funciona
## Configuracion por Tenant
```typescript
{
orders: {
enabled: true,
auto_confirm: false, // o true para confirmar automaticamente
estimated_time_minutes: 15,
channels: ['whatsapp', 'web'],
notifications: {
push: true,
whatsapp: true,
sound: 'order_received'
}
}
}
```
---
**Ultima actualizacion:** 2026-01-07

181
docs/01-epicas/MCH-016-entregas-domicilio.md Normal file
View File

@ -0,0 +1,181 @@
# MCH-016: Entregas a Domicilio
## Metadata
- **Codigo:** MCH-016
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 10-11
## Descripcion
Sistema de entregas a domicilio para micro-negocios: definicion de zonas de cobertura, costos de envio, asignacion de repartidores, y tracking basico del pedido.
## Objetivos
1. Definir zonas de cobertura
2. Configurar costos de envio
3. Asignar repartidores
4. Tracking basico de entrega
5. Confirmacion de entrega
## Alcance
### Incluido
- Zonas de cobertura (radio o colonias)
- Costo de envio fijo o por zona
- Asignacion manual de repartidor
- Estados: asignado, en camino, entregado
- Confirmacion con foto/firma
### Excluido
- GPS tracking en tiempo real
- Optimizacion de rutas
- Integracion con apps de delivery
- Repartidores externos (Rappi, Uber)
## Modelo de Datos
### Tablas Adicionales
**delivery_zones**
- id, tenant_id, name, type (radius/polygon)
- coordinates (JSONB), delivery_fee
- min_order, estimated_time, active
**deliveries**
- id, order_id, assigned_to (user_id)
- status, pickup_at, delivered_at
- delivery_address, notes
- proof_photo_url, signature_url
## Flujo de Entrega
### Cliente Solicita Delivery
```
Bot: "¿Como quieres recibir tu pedido?
[Paso a recoger] [Enviar a domicilio]"
Cliente: [Enviar a domicilio]
Bot: "¿A que direccion lo enviamos?"
Cliente: "Calle Hidalgo 45, Col. Centro"
Bot: "Perfecto! Envio a Col. Centro = $25
Total con envio: $79
Tiempo estimado: 30-45 min
¿Confirmas?
[Confirmar] [Cambiar direccion]"
```
### Asignacion de Repartidor
```
1. Pedido confirmado con delivery
2. Dueno ve pedido en dashboard
3. Asigna a repartidor (empleado)
4. Repartidor recibe notificacion
5. Cliente notificado: "Tu pedido va en camino"
```
### Confirmacion de Entrega
```
1. Repartidor llega a direccion
2. Entrega pedido
3. Toma foto de entrega (opcional)
4. Marca como entregado en app
5. Cliente recibe: "Pedido entregado!"
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /delivery/zones | Zonas de cobertura |
| POST | /delivery/zones | Crear zona |
| PUT | /delivery/zones/:id | Editar zona |
| DELETE | /delivery/zones/:id | Eliminar zona |
| POST | /delivery/check-coverage | Verificar cobertura |
| POST | /orders/:id/assign-delivery | Asignar repartidor |
| PUT | /deliveries/:id/status | Actualizar estado |
| POST | /deliveries/:id/confirm | Confirmar entrega |
## Configuracion de Zonas
### Por Radio
```typescript
{
type: 'radius',
center: { lat: 19.4326, lng: -99.1332 },
radius_km: 3,
delivery_fee: 25,
estimated_time: 30
}
```
### Por Colonias
```typescript
{
type: 'polygon',
name: 'Centro',
colonias: ['Centro', 'Roma Norte', 'Condesa'],
delivery_fee: 30,
estimated_time: 45
}
```
## UI Components
### DeliveryZonesMap
- Mapa con zonas definidas
- Edicion visual de poligonos
- Configuracion de tarifas
### DeliveryAssignment
- Lista de pedidos pendientes de asignar
- Dropdown de repartidores disponibles
- Boton asignar
### DeliveryTracking (Mobile - Repartidor)
- Lista de entregas asignadas
- Boton "En camino"
- Boton "Entregado" + foto
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| delivery.module | Pendiente | `modules/delivery/` |
| delivery_zones tabla | Pendiente | DDL |
| DeliveryZonesMap | Pendiente | `components/delivery/` |
| Mobile delivery screen | Pendiente | `mobile/screens/Delivery.tsx` |
## Dependencias
### Depende de
- MCH-015 (Pedidos WhatsApp)
- MCH-002 (Auth - para repartidores)
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] Zonas de cobertura se configuran
- [ ] Costo de envio se calcula correctamente
- [ ] Repartidor recibe notificacion
- [ ] Estados de entrega funcionan
- [ ] Confirmacion con foto funciona
## Roles
| Rol | Permisos |
|-----|----------|
| owner | Configurar zonas, ver todas las entregas |
| employee | Asignar entregas, ver entregas |
| delivery | Ver entregas asignadas, actualizar estado |
---
**Ultima actualizacion:** 2026-01-07

197
docs/01-epicas/MCH-017-notificaciones.md Normal file
View File

@ -0,0 +1,197 @@
# MCH-017: Notificaciones
## Metadata
- **Codigo:** MCH-017
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 8-9
## Descripcion
Sistema centralizado de notificaciones multi-canal: push notifications, WhatsApp, y SMS. Soporta notificaciones transaccionales, recordatorios, y alertas de negocio.
## Objetivos
1. Push notifications (Firebase)
2. Notificaciones WhatsApp
3. SMS como fallback
4. Configuracion por usuario
5. Historial de notificaciones
## Alcance
### Incluido
- Push via Firebase Cloud Messaging
- WhatsApp via MCH-011
- SMS via Twilio (fallback)
- Preferencias por usuario
- Templates de notificacion
- Programacion de envios
### Excluido
- Email (no prioritario para micro-negocios)
- Notificaciones in-app complejas
- Marketing automation
## Tipos de Notificacion
### Transaccionales (Inmediatas)
| Evento | Canal Default | Mensaje |
|--------|---------------|---------|
| Nuevo pedido | Push + WhatsApp | "Nuevo pedido #123" |
| Pedido listo | WhatsApp | "Tu pedido esta listo" |
| Pago recibido | Push | "Pago de $500 recibido" |
| Stock bajo | Push | "Coca-Cola: quedan 5" |
### Recordatorios (Programados)
| Tipo | Canal | Frecuencia |
|------|-------|------------|
| Fiado pendiente | WhatsApp | Segun config |
| Reporte semanal | WhatsApp | Lunes 8am |
| Cierre de caja | Push | Diario 9pm |
### Alertas de Negocio
| Alerta | Canal | Trigger |
|--------|-------|---------|
| Stock bajo | Push | stock < min_stock |
| Venta grande | Push | sale.total > threshold |
| Nuevo cliente | Push | customer.created |
## Modelo de Datos
### Tablas (schema: notifications)
**notification_templates**
- id, tenant_id, code, channel
- title, body, variables
- active
**notifications**
- id, tenant_id, user_id, type
- channel, title, body
- status (pending/sent/delivered/failed)
- scheduled_at, sent_at, read_at
**notification_preferences**
- id, user_id, channel
- enabled, quiet_hours_start, quiet_hours_end
**device_tokens**
- id, user_id, platform (ios/android/web)
- token, active, created_at
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /notifications/send | Enviar notificacion |
| GET | /notifications | Historial |
| PUT | /notifications/:id/read | Marcar como leida |
| GET | /notifications/preferences | Preferencias |
| PUT | /notifications/preferences | Actualizar prefs |
| POST | /notifications/register-device | Registrar token |
## Arquitectura
```
┌─────────────┐ ┌─────────────────┐
│ Trigger │────▶│ Notification │
│ (Event) │ │ Service │
└─────────────┘ └────────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌──────▼──────┐ ┌───────▼───────┐ ┌──────▼──────┐
│ Firebase │ │ WhatsApp │ │ Twilio │
│ FCM │ │ Service │ │ SMS │
└─────────────┘ └───────────────┘ └─────────────┘
```
## Templates de Notificacion
### Push - Nuevo Pedido
```json
{
"code": "new_order",
"channel": "push",
"title": "🛒 Nuevo Pedido",
"body": "Pedido #{{order_id}} de {{customer_name}} por ${{total}}"
}
```
### WhatsApp - Pedido Listo
```
¡Tu pedido #{{order_id}} esta listo! 📦
{{items_summary}}
Total: ${{total}}
Puedes pasar a recogerlo a:
{{business_address}}
```
### WhatsApp - Recordatorio Fiado
```
Hola {{customer_name}}, te recordamos que tienes
un saldo pendiente de ${{balance}} en {{business_name}}.
¿Cuando podrias pasar a liquidar?
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| notifications.module | Pendiente | `modules/notifications/` |
| Firebase integration | Pendiente | `providers/firebase.provider.ts` |
| Twilio integration | Pendiente | `providers/twilio.provider.ts` |
| Notification preferences UI | Pendiente | `components/settings/` |
## Dependencias
### Depende de
- MCH-011 (WhatsApp Service)
- MCH-002 (Auth - usuarios)
### Bloquea a
- MCH-008 (Recordatorios fiado)
- MCH-015 (Notificaciones pedido)
## Criterios de Aceptacion
- [ ] Push notifications funcionan (iOS/Android)
- [ ] WhatsApp notifications funcionan
- [ ] SMS fallback funciona
- [ ] Preferencias se respetan
- [ ] Historial se guarda correctamente
## Configuracion
### Firebase
```typescript
{
firebase: {
projectId: process.env.FIREBASE_PROJECT_ID,
privateKey: process.env.FIREBASE_PRIVATE_KEY,
clientEmail: process.env.FIREBASE_CLIENT_EMAIL
}
}
```
### Quiet Hours
```typescript
// Por usuario
{
quiet_hours: {
enabled: true,
start: '22:00',
end: '08:00'
}
}
```
---
**Ultima actualizacion:** 2026-01-07

225
docs/01-epicas/MCH-018-planes-suscripciones.md Normal file
View File

@ -0,0 +1,225 @@
# MCH-018: Planes y Suscripciones
## Metadata
- **Codigo:** MCH-018
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07
## Descripcion
Sistema de planes de suscripcion para monetizar MiChangarrito: dos planes principales (Changarrito y Tiendita), facturacion mensual, y gestion de ciclos de pago.
## Objetivos
1. Definir planes disponibles
2. Proceso de suscripcion
3. Facturacion recurrente
4. Gestion de ciclo de vida
5. Upgrade/downgrade de plan
## Alcance
### Incluido
- Plan Changarrito ($99/mes)
- Plan Tiendita ($199/mes)
- Trial de 14 dias
- Facturacion via Stripe
- Cancelacion y pausas
- Historial de facturacion
### Excluido
- Planes anuales (fase posterior)
- Planes enterprise personalizados
- Facturacion fiscal mexicana (MCH-027)
## Planes
### Plan Changarrito - $99/mes
```
✓ App movil completa
✓ Punto de venta basico
✓ Hasta 500 productos
✓ 1 usuario
✓ 500 tokens IA/mes
✓ Soporte por WhatsApp
✗ WhatsApp Business propio
✗ Predicciones de inventario
```
### Plan Tiendita - $199/mes
```
✓ Todo de Changarrito
✓ Productos ilimitados
✓ Hasta 5 usuarios
✓ 2,000 tokens IA/mes
✓ WhatsApp Business propio
✓ Predicciones de inventario
✓ Reportes avanzados
✓ Entregas a domicilio
✓ Soporte prioritario
```
## Modelo de Datos
### Tablas (schema: subscriptions)
**plans**
- id, name, code, price
- currency, interval (month/year)
- features (JSONB), token_quota
- max_products, max_users
- stripe_price_id, status
**subscriptions**
- id, tenant_id, plan_id
- status (trialing/active/past_due/cancelled)
- stripe_subscription_id
- current_period_start, current_period_end
- trial_end, cancelled_at
**invoices**
- id, subscription_id, amount
- status, stripe_invoice_id
- paid_at, pdf_url
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /subscriptions/plans | Listar planes |
| GET | /subscriptions/current | Suscripcion actual |
| POST | /subscriptions/subscribe | Suscribirse |
| POST | /subscriptions/cancel | Cancelar |
| POST | /subscriptions/resume | Reanudar |
| PUT | /subscriptions/change-plan | Cambiar plan |
| GET | /subscriptions/invoices | Historial facturas |
| POST | /subscriptions/webhook | Webhook Stripe |
## Flujos
### Nueva Suscripcion
```
1. Usuario selecciona plan
2. Ingresa metodo de pago (Stripe)
3. Se crea suscripcion con trial
4. Usuario tiene acceso inmediato
5. Al terminar trial, se cobra automaticamente
```
### Cancelacion
```
1. Usuario solicita cancelar
2. Confirmacion requerida
3. Suscripcion marcada para cancelar
4. Acceso hasta fin del periodo
5. Datos preservados 30 dias
```
### Upgrade
```
1. Usuario en Changarrito
2. Solicita upgrade a Tiendita
3. Se calcula prorateo
4. Pago de diferencia
5. Features activadas inmediatamente
```
## Estados de Suscripcion
```
trialing ──► active ──► past_due ──► cancelled
│ │
└───────────┴──► paused
```
| Estado | Descripcion | Acceso |
|--------|-------------|--------|
| trialing | En periodo de prueba | Completo |
| active | Pagando normalmente | Completo |
| past_due | Pago fallido (grace period) | Limitado |
| cancelled | Cancelada | Sin acceso |
| paused | Pausada temporalmente | Sin acceso |
## Integracion Stripe
### Subscription Billing
```typescript
const subscription = await stripe.subscriptions.create({
customer: customer.stripe_id,
items: [{ price: plan.stripe_price_id }],
trial_period_days: 14,
payment_behavior: 'default_incomplete',
expand: ['latest_invoice.payment_intent']
});
```
### Webhooks Manejados
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL subscriptions | Completado | `10-subscriptions.sql` |
| subscriptions.module | Completado | `modules/subscriptions/` |
| Stripe integration | Completado | `providers/stripe.provider.ts` |
| Plans UI | Pendiente | `pages/Plans.tsx` |
| Billing UI | Pendiente | `pages/Billing.tsx` |
## Dependencias
### Depende de
- MCH-005 (Stripe integration base)
- MCH-002 (Auth)
### Bloquea a
- MCH-019 (Tokens)
- MCH-020 (Pagos online)
## Criterios de Aceptacion
- [x] Planes se muestran correctamente
- [x] Suscripcion se crea en Stripe
- [x] Trial de 14 dias funciona
- [x] Cobro recurrente funciona
- [x] Cancelacion funciona
- [ ] Upgrade/downgrade funciona
## Configuracion
```typescript
// plans seed
[
{
name: 'Changarrito',
code: 'changarrito',
price: 99,
currency: 'MXN',
token_quota: 500,
max_products: 500,
max_users: 1,
stripe_price_id: 'price_xxx'
},
{
name: 'Tiendita',
code: 'tiendita',
price: 199,
currency: 'MXN',
token_quota: 2000,
max_products: null, // unlimited
max_users: 5,
stripe_price_id: 'price_yyy'
}
]
```
---
**Ultima actualizacion:** 2026-01-07

194
docs/01-epicas/MCH-019-tienda-tokens.md Normal file
View File

@ -0,0 +1,194 @@
# MCH-019: Tienda de Tokens
## Metadata
- **Codigo:** MCH-019
- **Fase:** 5 - Monetizacion
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 11-12
## Descripcion
Sistema de compra de tokens adicionales para funciones de IA: paquetes de tokens, saldo disponible, consumo por operacion, y alertas de saldo bajo.
## Objetivos
1. Paquetes de tokens disponibles
2. Compra via Stripe/OXXO
3. Saldo y consumo visible
4. Alertas de saldo bajo
5. Historial de consumo
## Alcance
### Incluido
- 4 paquetes de tokens
- Compra con tarjeta (Stripe)
- Compra en OXXO (Stripe)
- Saldo en tiempo real
- Consumo por operacion
- Alertas configurables
### Excluido
- Tokens como moneda interna
- Transferencia entre usuarios
- Venta de tokens a terceros
## Paquetes de Tokens
| Paquete | Tokens | Precio | Precio/Token |
|---------|--------|--------|--------------|
| Basico | 1,000 | $29 | $0.029 |
| Popular | 3,000 | $69 | $0.023 |
| Pro | 8,000 | $149 | $0.019 |
| Ultra | 20,000 | $299 | $0.015 |
## Modelo de Datos
### Tablas (schema: subscriptions)
**token_packages**
- id, name, tokens, price
- currency, stripe_price_id
- popular (boolean), active
**token_purchases**
- id, tenant_id, package_id
- tokens, amount, status
- stripe_payment_id, purchased_at
**token_usage**
- id, tenant_id, operation
- tokens_used, metadata (JSONB)
- created_at
**token_balances** (materialized view o cache)
- tenant_id, balance, last_updated
## Consumo de Tokens
### Operaciones y Costos
| Operacion | Tokens | Descripcion |
|-----------|--------|-------------|
| chat_message | 3-10 | Segun longitud |
| product_ocr | 5 | Reconocimiento de producto |
| audio_transcription | 8 | Transcripcion de audio |
| sales_report | 15 | Generacion de reporte |
| inventory_prediction | 20 | Prediccion de demanda |
### Calculo de Consumo
```typescript
// Basado en tokens del LLM
const tokensUsed = Math.ceil(
(inputTokens + outputTokens) / 100
);
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /tokens/packages | Paquetes disponibles |
| GET | /tokens/balance | Saldo actual |
| POST | /tokens/purchase | Comprar paquete |
| GET | /tokens/usage | Historial de consumo |
| GET | /tokens/usage/summary | Resumen de consumo |
## Flujos
### Compra de Tokens
```
1. Usuario ve que tiene saldo bajo
2. Abre tienda de tokens
3. Selecciona paquete
4. Paga con tarjeta o elige OXXO
5. Si tarjeta: tokens acreditados inmediatamente
6. Si OXXO: tokens acreditados al confirmar pago
```
### Consumo de Tokens
```
1. Usuario hace pregunta al chat IA
2. Sistema verifica saldo
3. Si suficiente: procesa pregunta
4. Descuenta tokens usados
5. Si bajo: alerta de saldo bajo
6. Si insuficiente: sugiere comprar mas
```
### Alerta de Saldo Bajo
```
[Push + WhatsApp]
"⚠️ Tu saldo de tokens esta bajo
Te quedan 45 tokens (~5 consultas).
Recarga para seguir usando el asistente IA.
[Comprar tokens]"
```
## UI Components
### TokenBalance (Header)
- Icono de moneda
- Saldo actual
- Click para ver tienda
### TokenShop
- Grid de paquetes
- Precio y ahorro
- Boton comprar
### TokenUsageHistory
- Tabla de operaciones
- Fecha, tipo, tokens
- Grafica de consumo
### TokenLowAlert
- Modal o banner
- Saldo actual
- CTA comprar
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| token_packages seed | Completado | `seeds/token-packages.sql` |
| tokens.service | Pendiente | `services/tokens.service.ts` |
| TokenShop UI | Pendiente | `components/tokens/TokenShop.tsx` |
| TokenBalance UI | Pendiente | `components/tokens/TokenBalance.tsx` |
## Dependencias
### Depende de
- MCH-018 (Suscripciones - Stripe setup)
- MCH-010 (MCP Server - consumo)
### Bloquea a
- MCH-012, MCH-013 (Uso de tokens en chats)
## Criterios de Aceptacion
- [ ] Paquetes se muestran correctamente
- [ ] Compra con tarjeta funciona
- [ ] Compra con OXXO funciona
- [ ] Saldo se actualiza en tiempo real
- [ ] Consumo se registra por operacion
- [ ] Alertas de saldo bajo funcionan
## Configuracion por Tenant
```typescript
// Umbrales de alerta
{
tokens: {
low_balance_threshold: 100,
critical_balance_threshold: 20,
alert_channels: ['push', 'whatsapp']
}
}
```
---
**Ultima actualizacion:** 2026-01-07

238
docs/01-epicas/MCH-020-pagos-suscripcion.md Normal file
View File

@ -0,0 +1,238 @@
# MCH-020: Pagos de Suscripcion
## Metadata
- **Codigo:** MCH-020
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-07
## Descripcion
Sistema completo de pagos para suscripciones y tokens: Stripe para tarjetas y OXXO, In-App Purchase para iOS/Android, y manejo de pagos fallidos.
## Objetivos
1. Pagos con tarjeta (Stripe)
2. Pagos en OXXO (Stripe)
3. In-App Purchase iOS
4. In-App Purchase Android
5. Manejo de pagos fallidos
## Alcance
### Incluido
- Stripe Checkout
- OXXO Pay (via Stripe)
- Apple In-App Purchase
- Google Play Billing
- Reintentos automaticos
- Recibos por email
### Excluido
- PayPal
- Transferencia bancaria manual
- Criptomonedas
## Metodos de Pago
### Stripe - Tarjeta
```
Comision: ~3.6% + $3 MXN
Confirmacion: Inmediata
Uso: Web y App (via Stripe SDK)
```
### Stripe - OXXO
```
Comision: ~$10-15 MXN fijo
Confirmacion: 24-72 horas
Uso: Cliente paga en OXXO
Vencimiento: 3 dias
```
### Apple In-App Purchase
```
Comision: 15-30%
Confirmacion: Inmediata
Uso: App iOS
Nota: Obligatorio para apps iOS
```
### Google Play Billing
```
Comision: 15%
Confirmacion: Inmediata
Uso: App Android
```
## Flujos de Pago
### Pago con Tarjeta
```
1. Usuario selecciona plan/tokens
2. Elige "Pagar con tarjeta"
3. Stripe Checkout se abre
4. Ingresa datos de tarjeta
5. Pago procesado
6. Redirige a app con confirmacion
7. Suscripcion/tokens activados
```
### Pago en OXXO
```
1. Usuario selecciona plan/tokens
2. Elige "Pagar en OXXO"
3. Se genera referencia OXXO
4. Se muestra:
- Monto a pagar
- Referencia/codigo de barras
- Fecha limite
5. Usuario va a OXXO y paga
6. Webhook confirma pago (horas despues)
7. Suscripcion/tokens activados
8. Notificacion al usuario
```
### In-App Purchase (iOS)
```
1. Usuario abre tienda en app
2. Selecciona producto
3. StoreKit muestra sheet de Apple
4. Usuario confirma con Face ID
5. Apple procesa pago
6. App recibe notificacion
7. Backend valida con Apple
8. Suscripcion/tokens activados
```
## Modelo de Datos
### Tablas Adicionales
**payment_methods**
- id, tenant_id, type (card/oxxo/iap)
- provider, last4, brand
- is_default, stripe_pm_id
**payments**
- id, tenant_id, type (subscription/tokens)
- amount, currency, status
- provider, provider_id
- metadata (JSONB)
**oxxo_vouchers**
- id, payment_id, reference
- barcode_url, expires_at
- status
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /payments/create-checkout | Crear sesion Stripe |
| POST | /payments/create-oxxo | Generar voucher OXXO |
| POST | /payments/verify-iap | Verificar IAP |
| GET | /payments/methods | Metodos guardados |
| POST | /payments/methods | Agregar metodo |
| DELETE | /payments/methods/:id | Eliminar metodo |
| POST | /payments/webhook/stripe | Webhook Stripe |
| POST | /payments/webhook/apple | Webhook Apple |
| POST | /payments/webhook/google | Webhook Google |
## Manejo de Pagos Fallidos
### Reintentos Automaticos
```
Dia 1: Primer intento fallido
Dia 3: Segundo intento
Dia 5: Tercer intento
Dia 7: Cuarto intento + alerta
Dia 10: Suspension de servicio
```
### Notificaciones
```
[Pago fallido - Dia 1]
"No pudimos procesar tu pago de $99.
Actualiza tu metodo de pago para
continuar usando MiChangarrito.
[Actualizar pago]"
[Ultimo aviso - Dia 7]
"⚠️ Tu suscripcion sera cancelada
en 3 dias si no actualizas tu pago.
[Actualizar pago ahora]"
```
## UI Components
### PaymentMethodSelector
- Radio buttons de metodos
- Tarjeta, OXXO, o guardados
- Agregar nueva tarjeta
### OXXOVoucher
- Codigo de barras
- Monto y referencia
- Instrucciones
- Boton compartir
### PaymentHistory
- Lista de pagos
- Estado y fecha
- Descargar recibo
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Stripe Checkout | En progreso | `services/stripe-checkout.service.ts` |
| OXXO Pay | Pendiente | `services/oxxo.service.ts` |
| Apple IAP | Pendiente | `services/apple-iap.service.ts` |
| Google Billing | Pendiente | `services/google-billing.service.ts` |
| Payment UI | Pendiente | `components/payments/` |
## Dependencias
### Depende de
- MCH-005 (Stripe base)
- MCH-018 (Suscripciones)
- MCH-019 (Tokens)
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] Pago con tarjeta funciona
- [ ] OXXO genera voucher correcto
- [ ] IAP iOS funciona
- [ ] IAP Android funciona
- [ ] Pagos fallidos se reintentan
- [ ] Notificaciones se envian
## Configuracion Stripe
```typescript
{
stripe: {
secretKey: process.env.STRIPE_SECRET_KEY,
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
oxxo: {
enabled: true,
expires_after_days: 3
},
retry: {
max_attempts: 4,
days_between: [0, 3, 5, 7]
}
}
}
```
---
**Ultima actualizacion:** 2026-01-07

200
docs/01-epicas/MCH-021-dashboard-web.md Normal file
View File

@ -0,0 +1,200 @@
# MCH-021: Dashboard Web
## Metadata
- **Codigo:** MCH-021
- **Fase:** 5 - Monetizacion
- **Prioridad:** P1
- **Estado:** En Progreso
- **Fecha inicio:** 2026-01-06
## Descripcion
Dashboard web completo para duenos de negocio: metricas de ventas, graficas, reportes exportables, configuracion del negocio, y administracion de usuarios.
## Objetivos
1. Metricas de ventas en tiempo real
2. Graficas interactivas
3. Reportes exportables (PDF/Excel)
4. Configuracion del negocio
5. Administracion de usuarios
## Alcance
### Incluido
- Dashboard principal con KPIs
- Graficas de ventas (dia/semana/mes)
- Top productos y categorias
- Reportes de corte de caja
- Configuracion de negocio
- Gestion de usuarios/roles
### Excluido
- BI avanzado (cubos OLAP)
- Predicciones ML en graficas
- Comparativos multi-sucursal
## Secciones del Dashboard
### Home / Resumen
```
┌─────────────────────────────────────────────────────────┐
│ DASHBOARD │
├─────────────┬─────────────┬─────────────┬──────────────┤
│ Ventas Hoy │ Transacc. │ Ticket Prom │ vs Ayer │
│ $3,450 │ 23 │ $150 │ +15% │
├─────────────┴─────────────┴─────────────┴──────────────┤
│ │
│ [Grafica de Ventas - Ultimos 7 dias] │
│ │
├───────────────────────────┬─────────────────────────────┤
│ Top 5 Productos │ Alertas │
│ 1. Coca-Cola 600ml │ ⚠️ Stock bajo (3) │
│ 2. Sabritas Original │ 💰 Fiados pendientes (5) │
│ 3. Pan Bimbo │ 📦 Pedidos nuevos (2) │
└───────────────────────────┴─────────────────────────────┘
```
### Ventas
- Tabla de ventas del periodo
- Filtros por fecha, empleado, metodo de pago
- Detalle de cada venta
- Exportar a Excel
### Productos
- CRUD de productos
- Inventario actual
- Historial de precios
- Importar/exportar
### Clientes
- Lista de clientes
- Historial de compras
- Saldos de fiado
- Segmentacion
### Reportes
- Corte de caja diario
- Ventas por periodo
- Productos mas vendidos
- Inventario valorizado
- Fiados por cobrar
### Configuracion
- Datos del negocio
- Metodos de pago
- Usuarios y roles
- Integraciones
- Suscripcion
## KPIs Principales
| KPI | Descripcion | Calculo |
|-----|-------------|---------|
| Ventas del dia | Total vendido hoy | SUM(sales.total) |
| Transacciones | Numero de ventas | COUNT(sales) |
| Ticket promedio | Venta promedio | AVG(sales.total) |
| Margen bruto | Ganancia | (precio - costo) / precio |
| Productos sin stock | Productos en 0 | COUNT(stock = 0) |
## Graficas
### Ventas por Dia (7 dias)
- Tipo: Barras o linea
- Eje X: Dias
- Eje Y: Total ventas
- Comparativo vs semana anterior
### Ventas por Hora
- Tipo: Linea
- Eje X: Horas (7am - 10pm)
- Eje Y: Ventas
- Identificar horas pico
### Top Productos (Pie)
- Top 5 productos por ingresos
- Porcentaje del total
### Metodos de Pago (Donut)
- Efectivo vs Tarjeta vs Fiado
- Porcentaje de cada uno
## Endpoints API (Existentes)
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /analytics/dashboard | KPIs principales |
| GET | /analytics/sales-by-day | Ventas por dia |
| GET | /analytics/sales-by-hour | Ventas por hora |
| GET | /analytics/top-products | Top productos |
| GET | /analytics/payment-methods | Por metodo pago |
| GET | /reports/daily-close | Corte de caja |
| GET | /reports/export | Exportar reporte |
## Componentes React
### Dashboard Page
- `pages/Dashboard.tsx`
- Grid de KPI cards
- Graficas con Recharts
- Alertas sidebar
### KPICard
- Valor principal
- Comparativo (% vs anterior)
- Icono y color
### SalesChart
- Recharts BarChart/LineChart
- Selector de periodo
- Tooltip interactivo
### TopProductsList
- Lista ordenada
- Cantidad y total
- Tendencia
### AlertsPanel
- Stock bajo
- Fiados pendientes
- Pedidos nuevos
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Dashboard.tsx | Completado | `pages/Dashboard.tsx` |
| analytics.module | En progreso | `modules/analytics/` |
| KPICard.tsx | Completado | `components/dashboard/` |
| SalesChart.tsx | En progreso | `components/dashboard/` |
| Reports export | Pendiente | `services/reports.service.ts` |
## Dependencias
### Depende de
- MCH-004 (Sales data)
- MCH-003 (Products data)
- MCH-014 (Customers data)
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [x] Dashboard muestra KPIs correctos
- [x] Graficas cargan datos reales
- [ ] Reportes se exportan a PDF/Excel
- [ ] Configuracion de negocio funciona
- [ ] Gestion de usuarios funciona
## Tecnologias
- **Framework:** React 18
- **Graficas:** Recharts
- **Tablas:** TanStack Table
- **Export PDF:** jsPDF
- **Export Excel:** SheetJS (xlsx)
---
**Ultima actualizacion:** 2026-01-07

207
docs/01-epicas/MCH-022-modo-offline.md Normal file
View File

@ -0,0 +1,207 @@
# MCH-022: Modo Offline
## Metadata
- **Codigo:** MCH-022
- **Fase:** 6 - Crecimiento
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 13-14
## Descripcion
Soporte offline completo para la app movil: SQLite local, sincronizacion inteligente, resolucion de conflictos, y funcionamiento sin conexion para operaciones criticas (ventas).
## Objetivos
1. Base de datos local (SQLite)
2. Sincronizacion bidireccional
3. Ventas sin conexion
4. Resolucion de conflictos
5. Indicador de estado de conexion
## Alcance
### Incluido
- SQLite para datos locales
- Sync de productos, clientes, ventas
- Cola de operaciones offline
- Resolucion automatica de conflictos
- Indicador visual de estado
### Excluido
- Offline para dashboard web
- Sync de imagenes pesadas
- Operaciones de pago offline (solo efectivo)
## Arquitectura
```
┌─────────────────────────────────────────────────────────┐
│ APP MOVIL │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ UI Layer │───▶│ Repository │───▶│ SQLite │ │
│ └─────────────┘ └──────┬──────┘ └────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Sync Queue │ │
│ └──────┬──────┘ │
│ │ │
└────────────────────────────┼────────────────────────────┘
│
┌──────▼──────┐
│ Backend │
│ API │
└─────────────┘
```
## Datos Sincronizados
### Alta Prioridad (Sync inmediato)
| Tabla | Direccion | Frecuencia |
|-------|-----------|------------|
| products | Server → Local | Al iniciar + cada 5 min |
| categories | Server → Local | Al iniciar |
| sales | Local → Server | Inmediato cuando hay conexion |
### Media Prioridad
| Tabla | Direccion | Frecuencia |
|-------|-----------|------------|
| customers | Bidireccional | Cada 15 min |
| inventory | Server → Local | Cada 30 min |
### Baja Prioridad
| Tabla | Direccion | Frecuencia |
|-------|-----------|------------|
| settings | Server → Local | Al iniciar |
| reports | No sync (solo online) | - |
## Flujo de Venta Offline
```
1. App detecta sin conexion
2. Usuario hace venta normal
3. Venta se guarda en SQLite
4. Se agrega a cola de sync
5. UI muestra "Venta guardada offline"
6. Cuando hay conexion:
a. Cola procesa ventas pendientes
b. Envia al servidor
c. Actualiza IDs locales
d. Marca como sincronizado
```
## Resolucion de Conflictos
### Estrategia: Last Write Wins + Merge
```typescript
// Para productos
if (local.updated_at > server.updated_at) {
// Local gana
sync.upload(local);
} else if (server.updated_at > local.updated_at) {
// Server gana
sync.download(server);
} else {
// Merge campos no conflictivos
sync.merge(local, server);
}
```
### Casos Especiales
**Venta offline con producto eliminado:**
```
1. Producto vendido offline
2. Producto eliminado en server
3. Al sync: venta se registra con producto_id
4. Se marca producto como "deleted" localmente
```
**Stock desactualizado:**
```
1. Venta offline reduce stock local
2. Otra venta online reduce stock
3. Al sync: stock negativo posible
4. Alerta al dueno para ajuste
```
## Modelo de Datos Local (SQLite)
### Tablas Adicionales
**sync_queue**
- id, operation (create/update/delete)
- table_name, record_id, payload
- status, attempts, created_at
**sync_status**
- table_name, last_sync_at
- records_count, pending_count
## UI Components
### ConnectionIndicator
- Icono en header
- Verde: online
- Amarillo: sync pendiente
- Rojo: offline
### OfflineBanner
- Banner visible cuando offline
- "Modo offline - cambios se sincronizaran"
### SyncProgress
- Modal de sincronizacion
- Progreso por tabla
- Errores si hay
## Tecnologias
- **SQLite:** react-native-sqlite-storage o expo-sqlite
- **Sync:** Custom sync engine o WatermelonDB
- **Network:** NetInfo para detectar conexion
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| SQLite setup | Pendiente | `mobile/database/` |
| Sync engine | Pendiente | `mobile/sync/` |
| Offline queue | Pendiente | `mobile/sync/queue.ts` |
| ConnectionIndicator | Pendiente | `mobile/components/` |
## Dependencias
### Depende de
- MCH-004 (Sales module)
- MCH-003 (Products module)
- App movil base
### Bloquea a
- Ninguno (mejora de UX)
## Criterios de Aceptacion
- [ ] App funciona sin conexion
- [ ] Ventas se guardan offline
- [ ] Sync funciona al reconectar
- [ ] Conflictos se resuelven
- [ ] Indicador de estado visible
## Limitaciones Offline
| Funcion | Disponible Offline |
|---------|-------------------|
| Ver productos | Si |
| Hacer venta (efectivo) | Si |
| Hacer venta (tarjeta) | No |
| Ver clientes | Si |
| Chat IA | No |
| Reportes | No |
| Configuracion | Solo lectura |
---
**Ultima actualizacion:** 2026-01-07

212
docs/01-epicas/MCH-023-programa-referidos.md Normal file
View File

@ -0,0 +1,212 @@
# MCH-023: Programa de Referidos
## Metadata
- **Codigo:** MCH-023
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 14-15
## Descripcion
Programa de referidos para crecimiento organico: codigos de referencia unicos, beneficios para referidor y referido, tracking de conversiones, y recompensas automaticas.
## Objetivos
1. Codigos de referido unicos
2. Beneficios para ambas partes
3. Tracking de conversiones
4. Recompensas automaticas
5. Dashboard de referidos
## Alcance
### Incluido
- Codigo unico por usuario
- Link compartible
- Beneficio: 1 mes gratis (referidor)
- Beneficio: 50% descuento primer mes (referido)
- Dashboard con estadisticas
- Notificaciones de conversion
### Excluido
- Comisiones en efectivo
- Multinivel (referidos de referidos)
- Programa de afiliados formal
## Mecanica del Programa
### Beneficios
| Rol | Beneficio | Condicion |
|-----|-----------|-----------|
| Referidor | 1 mes gratis de suscripcion | Por cada referido que pague |
| Referido | 50% descuento primer mes | Al registrarse con codigo |
### Flujo de Referido
```
1. Usuario A tiene codigo "TIENDAJUAN"
2. Comparte link: michangarrito.com/r/TIENDAJUAN
3. Usuario B se registra con codigo
4. Usuario B obtiene 50% descuento
5. Usuario B paga primer mes
6. Usuario A recibe notificacion
7. Usuario A obtiene 1 mes gratis acumulado
```
## Modelo de Datos
### Tablas
**referral_codes**
- id, tenant_id, code (unique)
- created_at, active
**referrals**
- id, referrer_tenant_id, referred_tenant_id
- code_used, status (pending/converted/expired)
- converted_at, reward_applied_at
**referral_rewards**
- id, tenant_id, type (free_month)
- months_earned, months_used
- expires_at
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /referrals/my-code | Mi codigo |
| POST | /referrals/generate-code | Generar nuevo codigo |
| GET | /referrals/stats | Estadisticas |
| GET | /referrals/list | Mis referidos |
| POST | /referrals/apply-code | Aplicar codigo (registro) |
| GET | /referrals/rewards | Mis recompensas |
## Estados del Referido
```
pending ──► converted ──► rewarded
│
└──► expired (si no paga en 30 dias)
```
| Estado | Descripcion |
|--------|-------------|
| pending | Referido registrado, no ha pagado |
| converted | Referido pago primer mes |
| rewarded | Recompensa aplicada al referidor |
| expired | Referido no pago en tiempo |
## UI Components
### ShareReferralCard
```
┌─────────────────────────────────┐
│ Invita amigos y gana │
│ │
│ Tu codigo: TIENDAJUAN │
│ │
│ [Copiar] [Compartir WhatsApp] │
│ │
│ Por cada amigo que se suscriba │
│ ganas 1 mes gratis! │
└─────────────────────────────────┘
```
### ReferralStats
```
┌─────────────────────────────────┐
│ Tus Referidos │
├─────────────────────────────────┤
│ 👥 Invitados: 8 │
│ ✅ Convertidos: 3 │
│ 🎁 Meses ganados: 3 │
│ 📅 Meses disponibles: 2 │
└─────────────────────────────────┘
```
### ReferralList
- Tabla de referidos
- Nombre, fecha, estado
- Recompensa aplicada
## Notificaciones
### Referido se Registra
```
[Push al referidor]
"🎉 Juan se registro con tu codigo!
Te avisaremos cuando active su suscripcion."
```
### Referido Paga
```
[Push + WhatsApp al referidor]
"🎁 Ganaste 1 mes gratis!
Juan activo su suscripcion.
Ya tienes 3 meses acumulados."
```
## Integracion con Suscripciones
```typescript
// Al procesar pago de suscripcion
async function processSubscriptionPayment(tenant, payment) {
// Verificar si tiene meses gratis disponibles
const rewards = await getReferralRewards(tenant.id);
if (rewards.months_available > 0) {
// Usar mes gratis en lugar de cobrar
await useReferralMonth(tenant.id);
return { charged: false, used_referral: true };
}
// Cobrar normalmente
return chargeSubscription(tenant, payment);
}
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| referrals.module | Pendiente | `modules/referrals/` |
| DDL referrals | Pendiente | `schemas/13-referrals.sql` |
| ShareReferralCard | Pendiente | `components/referrals/` |
| Deep linking | Pendiente | Mobile config |
## Dependencias
### Depende de
- MCH-018 (Suscripciones)
- MCH-017 (Notificaciones)
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] Codigo unico se genera
- [ ] Link compartible funciona
- [ ] Descuento se aplica al referido
- [ ] Mes gratis se acredita al referidor
- [ ] Dashboard muestra estadisticas
- [ ] Notificaciones se envian
## Configuracion
```typescript
{
referrals: {
enabled: true,
referrer_reward: { type: 'free_month', months: 1 },
referred_discount: { percent: 50, months: 1 },
code_prefix: 'MCH', // MCH-XXXXX
expiry_days: 30 // dias para que referido pague
}
}
```
---
**Ultima actualizacion:** 2026-01-07

211
docs/01-epicas/MCH-024-codi-spei.md Normal file
View File

@ -0,0 +1,211 @@
# MCH-024: CoDi y SPEI
## Metadata
- **Codigo:** MCH-024
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 15-16
## Descripcion
Integracion con CoDi (Cobro Digital) de Banxico y SPEI para pagos instantaneos sin comision: generacion de QR de cobro, CLABE virtual por negocio, y confirmacion automatica.
## Objetivos
1. Generacion de QR CoDi
2. CLABE virtual por tenant
3. Confirmacion automatica de pagos
4. Sin comisiones
5. Conciliacion automatica
## Alcance
### Incluido
- QR CoDi para cobro
- CLABE virtual (via proveedor)
- Webhook de confirmacion
- Registro de pagos en BD
- Notificacion al recibir pago
### Excluido
- Transferencias salientes
- Pagos programados
- Domiciliacion
## CoDi - Cobro Digital
### Que es CoDi
- Sistema de Banxico
- Pagos via QR desde app bancaria
- Sin comisiones
- Confirmacion en segundos
- Opera 24/7
### Flujo de Pago CoDi
```
1. Cliente quiere pagar
2. POS genera QR CoDi con monto
3. Cliente escanea con app de su banco
4. Cliente confirma pago
5. Dinero se transfiere instantaneamente
6. Webhook notifica a MiChangarrito
7. Venta marcada como pagada
```
## SPEI con CLABE Virtual
### Como Funciona
```
1. Tenant se registra
2. Se genera CLABE virtual unica
3. Clientes pueden transferir a esa CLABE
4. Pagos se concilian automaticamente
5. Ideal para pagos grandes o B2B
```
### Proveedores de CLABE Virtual
- STP (Sistema de Transferencias y Pagos)
- Arcus
- Conekta
- Openpay
## Modelo de Datos
### Tablas Adicionales
**codi_transactions**
- id, tenant_id, sale_id
- qr_data, amount, reference
- status, confirmed_at
**virtual_accounts**
- id, tenant_id, provider
- clabe, status, created_at
**spei_transactions**
- id, tenant_id, virtual_account_id
- amount, sender_clabe, sender_name
- reference, received_at
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /codi/generate-qr | Generar QR de cobro |
| GET | /codi/status/:id | Estado de transaccion |
| POST | /codi/webhook | Webhook de confirmacion |
| GET | /spei/clabe | Obtener CLABE virtual |
| POST | /spei/webhook | Webhook de SPEI |
| GET | /spei/transactions | Transacciones recibidas |
## Flujo Tecnico CoDi
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ POS │────▶│ Generate │────▶│ QR Image │
│ │ │ QR │ │ Displayed │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌──────▼──────┐
│ Customer │
│ Scans QR │
└──────┬──────┘
│
┌──────▼──────┐
│ Bank App │
│ Confirms │
└──────┬──────┘
│
┌─────────────┐ ┌─────────────┐ ┌──────▼──────┐
│ Update │◀────│ Webhook │◀────│ Banxico │
│ Sale │ │ Handler │ │ CoDi │
└─────────────┘ └─────────────┘ └─────────────┘
```
## UI Components
### CoDiPaymentOption
- Boton "Pagar con CoDi"
- Genera y muestra QR
- Timer de expiracion (5 min)
- Indicador de esperando pago
### QRCodeDisplay
- QR grande y claro
- Monto visible
- Instrucciones
- Boton "Ya pague"
### CLABEDisplay
- CLABE formateada
- Boton copiar
- Nombre del beneficiario
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| codi.service | Pendiente | `services/codi.service.ts` |
| spei.service | Pendiente | `services/spei.service.ts` |
| CoDi QR UI | Pendiente | `components/payments/CoDiQR.tsx` |
| Virtual account setup | Pendiente | Integracion proveedor |
## Dependencias
### Depende de
- MCH-004 (POS)
- MCH-005 (Payments base)
- Cuenta bancaria del negocio
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] QR CoDi se genera correctamente
- [ ] Pago CoDi se confirma automaticamente
- [ ] CLABE virtual se asigna
- [ ] SPEI se recibe y concilia
- [ ] Sin comisiones extra
## Limitaciones
| Aspecto | Limitacion |
|---------|------------|
| Monto minimo | $1 MXN |
| Monto maximo | $8,000 MXN (CoDi) |
| Horario | 24/7 |
| Bancos | 20+ bancos soportan CoDi |
## Configuracion por Tenant
```typescript
{
codi: {
enabled: true,
provider: 'banxico', // o agregador
merchant_id: '...',
qr_expiry_minutes: 5
},
spei: {
enabled: true,
provider: 'stp',
clabe: '646180123456789012',
auto_reconcile: true
}
}
```
## Beneficios vs Tarjeta
| Aspecto | Tarjeta | CoDi/SPEI |
|---------|---------|-----------|
| Comision | 3-4% | 0% |
| Confirmacion | Inmediata | Inmediata |
| Contracargos | Posible | No |
| Requiere terminal | Si | No |
---
**Ultima actualizacion:** 2026-01-07

230
docs/01-epicas/MCH-025-widgets-atajos.md Normal file
View File

@ -0,0 +1,230 @@
# MCH-025: Widgets y Atajos
## Metadata
- **Codigo:** MCH-025
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 16
## Descripcion
Widgets para pantalla de inicio (Android/iOS) y atajos rapidos: ver ventas del dia, acceso rapido al POS, alertas de stock, y notificaciones importantes sin abrir la app.
## Objetivos
1. Widget de ventas del dia
2. Widget de alertas
3. Atajos rapidos (Quick Actions)
4. Deep linking
5. Actualizacion en tiempo real
## Alcance
### Incluido
- Widget pequeno (ventas hoy)
- Widget mediano (ventas + alertas)
- Quick Actions iOS (3D Touch / Long Press)
- App Shortcuts Android
- Deep links a secciones
### Excluido
- Widget interactivo completo
- Widgets para Apple Watch
- Widgets para tablets
## Widgets
### Widget Pequeno (2x1)
```
┌─────────────────────┐
│ 💰 Ventas Hoy │
│ $3,450 │
│ 23 ventas │
└─────────────────────┘
```
### Widget Mediano (4x2)
```
┌─────────────────────────────────────┐
│ MiChangarrito │
├─────────────────────────────────────┤
│ 💰 Ventas: $3,450 | 📦 Stock: 3 │
│ 🛒 Pedidos: 2 | 💳 Fiados: 5 │
├─────────────────────────────────────┤
│ [Abrir POS] [Ver Pedidos] │
└─────────────────────────────────────┘
```
### Widget Grande (4x4) - Solo Android
```
┌─────────────────────────────────────┐
│ MiChangarrito Dashboard │
├─────────────────────────────────────┤
│ │
│ Ventas Hoy: $3,450 (+15%) │
│ ████████████░░░ 23 transacciones │
│ │
│ Alertas: │
│ ⚠️ Coca-Cola: 5 unidades │
│ ⚠️ Pan Bimbo: 3 unidades │
│ 💰 5 fiados pendientes │
│ │
│ [POS] [Productos] [Pedidos] │
└─────────────────────────────────────┘
```
## Quick Actions / App Shortcuts
### iOS (Long Press en icono)
```
┌─────────────────────┐
│ 🛒 Nueva Venta │
│ 📦 Ver Inventario │
│ 📊 Ventas de Hoy │
│ ➕ Agregar Producto │
└─────────────────────┘
```
### Android (Long Press en icono)
```
┌─────────────────────┐
│ Nueva Venta │
│ Escanear Producto │
│ Ver Pedidos │
│ Mi Saldo de Tokens │
└─────────────────────┘
```
## Deep Links
| Accion | Deep Link |
|--------|-----------|
| Abrir POS | `michangarrito://pos` |
| Nueva venta | `michangarrito://pos/new` |
| Ver producto | `michangarrito://products/:id` |
| Ver pedido | `michangarrito://orders/:id` |
| Dashboard | `michangarrito://dashboard` |
| Escanear | `michangarrito://scan` |
## Implementacion Tecnica
### iOS Widgets (WidgetKit)
```swift
struct SalesWidget: Widget {
var body: some WidgetConfiguration {
StaticConfiguration(
kind: "SalesWidget",
provider: SalesProvider()
) { entry in
SalesWidgetView(entry: entry)
}
.configurationDisplayName("Ventas del Día")
.description("Ve tus ventas en tiempo real")
.supportedFamilies([.systemSmall, .systemMedium])
}
}
```
### Android Widgets (Glance / AppWidget)
```kotlin
class SalesWidget : GlanceAppWidget() {
override suspend fun provideGlance(
context: Context,
id: GlanceId
) {
provideContent {
SalesWidgetContent(getSalesData())
}
}
}
```
### React Native Bridge
- expo-widgets (si disponible)
- react-native-widget-extension
- Codigo nativo para cada plataforma
## Actualizacion de Datos
### Estrategia
```
1. Widget se actualiza cada 15 minutos (sistema)
2. Push notification trigger refresh
3. Background fetch cuando app esta activa
4. Datos cacheados localmente
```
### API para Widgets
```typescript
// Endpoint liviano para widgets
GET /api/widget/summary
Response:
{
"sales_today": 3450,
"transactions_count": 23,
"pending_orders": 2,
"low_stock_count": 3,
"pending_credits": 5,
"updated_at": "2026-01-07T15:30:00Z"
}
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| iOS Widget | Pendiente | `ios/MiChangarritoWidget/` |
| Android Widget | Pendiente | `android/app/src/widget/` |
| Quick Actions | Pendiente | Configuracion nativa |
| Deep linking | Pendiente | `mobile/navigation/` |
| Widget API | Pendiente | `backend/controllers/widget.controller.ts` |
## Dependencias
### Depende de
- App movil base
- MCH-021 (Dashboard - datos)
- Push notifications configuradas
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] Widget pequeno funciona iOS
- [ ] Widget pequeno funciona Android
- [ ] Widget mediano funciona
- [ ] Quick Actions funcionan
- [ ] Deep links abren seccion correcta
- [ ] Datos se actualizan regularmente
## Configuracion de Usuario
```typescript
// Preferencias de widget
{
widget: {
show_sales: true,
show_orders: true,
show_stock_alerts: true,
show_credits: true,
refresh_interval: 15 // minutos
}
}
```
## Limitaciones por Plataforma
| Feature | iOS | Android |
|---------|-----|---------|
| Widget pequeno | Si | Si |
| Widget mediano | Si | Si |
| Widget grande | No | Si |
| Interactivo | Limitado | Si |
| Background refresh | 15 min min | Configurable |
---
**Ultima actualizacion:** 2026-01-07

242
docs/01-epicas/MCH-026-multi-idioma-latam.md Normal file
View File

@ -0,0 +1,242 @@
# MCH-026: Multi-idioma LATAM
## Metadata
- **Codigo:** MCH-026
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 18+
## Descripcion
Internacionalizacion (i18n) de la aplicacion para expansion a otros paises de Latinoamerica: soporte multi-idioma, localizacion de formatos (moneda, fecha), y adaptacion de terminologia por pais.
## Objetivos
1. Soporte multi-idioma (es-MX, es-CO, es-AR, pt-BR)
2. Localizacion de monedas y formatos
3. Terminologia adaptada por pais
4. Contenido de ayuda localizado
5. Deteccion automatica de region
## Alcance
### Incluido
- Espanol Mexico (es-MX) - default
- Espanol Colombia (es-CO)
- Espanol Argentina (es-AR)
- Portugues Brasil (pt-BR)
- Formatos de moneda locales
- Formatos de fecha locales
### Excluido
- Ingles (no es mercado objetivo inicial)
- Otros idiomas latinoamericanos
- Traduccion de contenido generado por usuario
## Paises Objetivo
| Pais | Codigo | Moneda | Formato Fecha |
|------|--------|--------|---------------|
| Mexico | es-MX | MXN ($) | DD/MM/YYYY |
| Colombia | es-CO | COP ($) | DD/MM/YYYY |
| Argentina | es-AR | ARS ($) | DD/MM/YYYY |
| Brasil | pt-BR | BRL (R$) | DD/MM/YYYY |
## Terminologia por Pais
| Concepto | Mexico | Colombia | Argentina | Brasil |
|----------|--------|----------|-----------|--------|
| Tienda | Changarro | Tienda | Almacen | Loja |
| Fiado | Fiado | Fiado | Cuenta | Fiado |
| Efectivo | Efectivo | Efectivo | Efectivo | Dinheiro |
| Codigo de barras | Codigo | Codigo | Codigo | Codigo de barras |
## Arquitectura i18n
### Estructura de Archivos
```
locales/
├── es-MX/
│ ├── common.json
│ ├── pos.json
│ ├── products.json
│ └── errors.json
├── es-CO/
│ └── ...
├── es-AR/
│ └── ...
└── pt-BR/
└── ...
```
### Ejemplo de Archivo
```json
// locales/es-MX/pos.json
{
"title": "Punto de Venta",
"cart": {
"empty": "Tu carrito esta vacio",
"total": "Total",
"checkout": "Cobrar"
},
"payment": {
"cash": "Efectivo",
"card": "Tarjeta",
"credit": "Fiado",
"change": "Cambio"
}
}
// locales/pt-BR/pos.json
{
"title": "Ponto de Venda",
"cart": {
"empty": "Seu carrinho esta vazio",
"total": "Total",
"checkout": "Finalizar"
},
"payment": {
"cash": "Dinheiro",
"card": "Cartao",
"credit": "Fiado",
"change": "Troco"
}
}
```
## Implementacion Tecnica
### Frontend (React)
```typescript
import { useTranslation } from 'react-i18next';
function POSPage() {
const { t } = useTranslation('pos');
return (
<div>
<h1>{t('title')}</h1>
<Cart
emptyMessage={t('cart.empty')}
totalLabel={t('cart.total')}
/>
</div>
);
}
```
### Mobile (React Native)
```typescript
import { useTranslation } from 'react-i18next';
// Mismo patron que web
```
### Backend
```typescript
// Mensajes de error localizados
throw new BadRequestException(
i18n.t('errors.product_not_found', { lang: user.locale })
);
```
## Formatos de Moneda
```typescript
// Formateo dinamico
const formatCurrency = (amount: number, locale: string) => {
const config = {
'es-MX': { currency: 'MXN', symbol: '$' },
'es-CO': { currency: 'COP', symbol: '$' },
'es-AR': { currency: 'ARS', symbol: '$' },
'pt-BR': { currency: 'BRL', symbol: 'R$' }
};
return new Intl.NumberFormat(locale, {
style: 'currency',
currency: config[locale].currency
}).format(amount);
};
// Resultados:
// es-MX: $1,234.56
// es-CO: $1.234,56
// es-AR: $1.234,56
// pt-BR: R$ 1.234,56
```
## Modelo de Datos
### Campos Adicionales
**tenants**
- locale: string (es-MX, es-CO, etc.)
- timezone: string
- currency: string
**users**
- locale: string (override de tenant)
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /locales | Idiomas disponibles |
| GET | /locales/:locale | Traducciones |
| PUT | /settings/locale | Cambiar idioma |
## Deteccion Automatica
```typescript
// Al registrarse
1. Detectar IP del usuario
2. Geolocalizar pais
3. Asignar locale default
4. Usuario puede cambiar en settings
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Archivos i18n es-MX | Pendiente | `locales/es-MX/` |
| Archivos i18n es-CO | Pendiente | `locales/es-CO/` |
| Archivos i18n es-AR | Pendiente | `locales/es-AR/` |
| Archivos i18n pt-BR | Pendiente | `locales/pt-BR/` |
| i18n setup React | Pendiente | `lib/i18n.ts` |
| Currency formatter | Pendiente | `utils/currency.ts` |
## Dependencias
### Depende de
- App completa y estable
- Expansion de negocio a otros paises
### Bloquea a
- Lanzamiento en Colombia, Argentina, Brasil
## Criterios de Aceptacion
- [ ] App funciona en es-MX (default)
- [ ] App funciona en es-CO
- [ ] App funciona en es-AR
- [ ] App funciona en pt-BR
- [ ] Monedas se formatean correctamente
- [ ] Usuario puede cambiar idioma
## Consideraciones
### Traduccion
- Usar servicio profesional para pt-BR
- Validar terminologia con usuarios locales
- No traducir nombres de productos
### Legal
- Adaptar terminos y condiciones por pais
- Politica de privacidad por region
- Cumplimiento normativo local
---
**Ultima actualizacion:** 2026-01-07

245
docs/01-epicas/MCH-027-integracion-sat.md Normal file
View File

@ -0,0 +1,245 @@
# MCH-027: Integracion SAT
## Metadata
- **Codigo:** MCH-027
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 19+
## Descripcion
Integracion con el SAT (Servicio de Administracion Tributaria) de Mexico para facturacion electronica simplificada (CFDI): emision de facturas a clientes, cancelacion, y reportes fiscales.
## Objetivos
1. Emision de CFDI (facturas)
2. Cancelacion de facturas
3. Envio automatico al cliente
4. Reportes para contabilidad
5. Cumplimiento normativo
## Alcance
### Incluido
- CFDI de Ingreso (factura de venta)
- CFDI de Egreso (nota de credito)
- Envio por email al cliente
- Descarga de XML y PDF
- Reporte mensual
### Excluido
- CFDI de Nomina
- CFDI de Pagos complejos
- Declaraciones automaticas
- Contabilidad electronica
## Tipos de Comprobante
| Tipo | Uso | Cuando |
|------|-----|--------|
| Ingreso | Factura de venta | Cliente solicita factura |
| Egreso | Nota de credito | Devolucion o descuento |
## Flujo de Facturacion
### Solicitud de Factura (Post-venta)
```
1. Cliente solicita factura via WhatsApp
"Necesito factura del ticket #123"
2. Bot responde:
"Para tu factura necesito:
- RFC
- Razon social
- Codigo postal
- Uso CFDI (ej: Gastos en general)"
3. Cliente proporciona datos
4. Sistema genera CFDI:
- Timbra con PAC
- Genera PDF
- Envia por email
- Guarda en historial
5. Bot confirma:
"Tu factura ha sido enviada a tu email"
```
### Factura desde POS
```
1. Al finalizar venta
2. Empleado pregunta: "¿Requiere factura?"
3. Si: captura datos fiscales
4. Se genera CFDI
5. Se entrega ticket + factura
```
## Modelo de Datos
### Tablas (schema: billing)
**invoices** (CFDI)
- id, tenant_id, sale_id, type (ingreso/egreso)
- uuid (folio fiscal), serie, folio
- customer_rfc, customer_name, customer_zip
- uso_cfdi, payment_method, payment_form
- subtotal, iva, total
- xml_url, pdf_url, status
- stamped_at, cancelled_at
**invoice_items**
- id, invoice_id, product_id
- clave_prod_serv, clave_unidad
- description, quantity, unit_price
- discount, iva, total
**tax_configs** (por tenant)
- id, tenant_id, rfc, razon_social
- regimen_fiscal, codigo_postal
- pac_provider, pac_credentials
## Claves SAT Requeridas
### Uso CFDI Comunes
| Clave | Descripcion |
|-------|-------------|
| G01 | Adquisicion de mercancias |
| G03 | Gastos en general |
| P01 | Por definir |
### Forma de Pago
| Clave | Descripcion |
|-------|-------------|
| 01 | Efectivo |
| 04 | Tarjeta de credito |
| 28 | Tarjeta de debito |
| 99 | Por definir |
### Metodo de Pago
| Clave | Descripcion |
|-------|-------------|
| PUE | Pago en una sola exhibicion |
| PPD | Pago en parcialidades |
## Integracion con PAC
### Proveedores PAC Recomendados
- Facturapi (simple, buena API)
- SW Sapien
- Finkok
### API Facturapi (Ejemplo)
```typescript
const facturapi = require('facturapi');
const invoice = await facturapi.invoices.create({
customer: {
legal_name: 'Juan Perez',
tax_id: 'XAXX010101000',
tax_system: '601',
address: { zip: '06600' }
},
items: [{
product: {
description: 'Coca-Cola 600ml',
product_key: '50202301', // Bebidas
price: 18,
tax_included: true
}
}],
payment_form: '01', // Efectivo
use: 'G03' // Gastos generales
});
```
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /invoices | Crear factura |
| GET | /invoices/:id | Obtener factura |
| GET | /invoices/:id/pdf | Descargar PDF |
| GET | /invoices/:id/xml | Descargar XML |
| POST | /invoices/:id/cancel | Cancelar factura |
| POST | /invoices/:id/send | Reenviar por email |
| GET | /invoices/report | Reporte mensual |
## UI Components
### InvoiceRequestForm
- RFC con validacion
- Razon social
- Codigo postal
- Uso CFDI (dropdown)
- Email para envio
### InvoiceHistory
- Lista de facturas emitidas
- Filtros por periodo
- Acciones: ver, descargar, cancelar
### InvoicePreview
- Vista previa del PDF
- Datos fiscales
- Botones: descargar, enviar
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| billing.module | Parcial | `modules/billing/` |
| PAC integration | Pendiente | `services/pac.service.ts` |
| Invoice PDF generator | Pendiente | `services/invoice-pdf.service.ts` |
| WhatsApp invoice flow | Pendiente | `whatsapp-service/flows/` |
| Invoice UI | Pendiente | `pages/Invoices.tsx` |
## Dependencias
### Depende de
- MCH-004 (Sales - datos de venta)
- MCH-014 (Customers - datos fiscales)
- Cuenta SAT del negocio (e.firma)
- Contrato con PAC
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] CFDI se genera correctamente
- [ ] XML cumple con esquema SAT
- [ ] PDF se genera legible
- [ ] Email se envia al cliente
- [ ] Cancelacion funciona
- [ ] Reporte mensual se genera
## Configuracion por Tenant
```typescript
{
billing: {
enabled: true,
pac_provider: 'facturapi',
pac_api_key: 'encrypted...',
rfc: 'XAXX010101000',
razon_social: 'Mi Tiendita SA de CV',
regimen_fiscal: '601',
codigo_postal: '06600',
serie: 'A',
auto_send_email: true
}
}
```
## Costos
| Concepto | Costo Estimado |
|----------|----------------|
| PAC por timbrado | ~$2-4 MXN/factura |
| Certificado e.firma | Gratis (SAT) |
---
**Ultima actualizacion:** 2026-01-07

223
docs/01-epicas/MCH-028-marketplace-proveedores.md Normal file
View File

@ -0,0 +1,223 @@
# MCH-028: Marketplace de Proveedores
## Metadata
- **Codigo:** MCH-028
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 20+
## Descripcion
Marketplace B2B que conecta micro-negocios con distribuidores y mayoristas: catalogo de proveedores, pedidos directos, comparacion de precios, y entregas coordinadas.
## Objetivos
1. Directorio de proveedores verificados
2. Catalogos de productos mayoreo
3. Pedidos B2B desde la app
4. Comparacion de precios
5. Tracking de pedidos a proveedor
## Alcance
### Incluido
- Directorio de distribuidores por zona
- Catalogo de productos de mayoreo
- Sistema de pedidos B2B
- Comparador de precios
- Historial de compras
### Excluido
- Pagos procesados por MiChangarrito
- Logistica propia
- Credito a negocios (lo da el proveedor)
- Exclusividad con proveedores
## Modelo de Negocio
### Para Tienditas
- Acceso gratuito al directorio
- Pedidos mas faciles
- Mejores precios por volumen
- Menos tiempo buscando proveedor
### Para Proveedores
- Acceso a base de clientes
- Comision por pedido (3-5%)
- Dashboard de ventas
- Promociones destacadas
### Revenue para MiChangarrito
- Comision por pedido confirmado
- Listados destacados (premium)
- Datos de mercado (anonimizados)
## Flujos de Usuario
### Tiendita Busca Proveedor
```
1. Dueno abre "Proveedores"
2. Filtra por categoria (bebidas, botanas)
3. Ve lista de proveedores en su zona
4. Compara precios de Coca-Cola
5. Selecciona proveedor con mejor precio
6. Hace pedido desde la app
7. Proveedor confirma y entrega
```
### Proveedor Recibe Pedido
```
1. Proveedor recibe notificacion
2. Ve pedido en su dashboard:
- Tienda: "Tiendita Don Jose"
- Productos: 10 cajas Coca-Cola
- Direccion: Calle X #123
3. Confirma disponibilidad
4. Programa entrega
5. Tienda recibe notificacion
```
## Modelo de Datos
### Tablas (schema: marketplace)
**suppliers**
- id, name, legal_name, rfc
- categories, coverage_zones
- contact_phone, contact_email
- logo_url, verified, rating
- status
**supplier_products**
- id, supplier_id, name, sku
- category, price_unit, min_order
- image_url, barcode, active
**supplier_orders**
- id, tenant_id, supplier_id
- status, subtotal, total
- delivery_address, delivery_date
- notes, created_at
**supplier_order_items**
- id, order_id, product_id
- quantity, unit_price, total
**supplier_reviews**
- id, tenant_id, supplier_id
- rating, comment, created_at
## Endpoints API
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /marketplace/suppliers | Listar proveedores |
| GET | /marketplace/suppliers/:id | Detalle proveedor |
| GET | /marketplace/suppliers/:id/products | Productos |
| POST | /marketplace/orders | Crear pedido |
| GET | /marketplace/orders | Mis pedidos |
| PUT | /marketplace/orders/:id/status | Actualizar estado |
| POST | /marketplace/reviews | Dejar resena |
## UI Components
### SupplierDirectory
- Lista de proveedores
- Filtros por categoria, zona
- Rating y resenas
- Productos destacados
### SupplierProfile
- Info del proveedor
- Catalogo de productos
- Precios y minimos
- Boton "Hacer pedido"
### SupplierOrderForm
- Seleccion de productos
- Cantidades
- Direccion de entrega
- Fecha preferida
- Notas
### OrderTracking
- Estado del pedido
- Fecha estimada
- Contacto del proveedor
## Proveedores Iniciales (Mexico)
### Categorias Prioritarias
1. **Bebidas:** Coca-Cola FEMSA, Pepsi, distribuidores locales
2. **Botanas:** Sabritas, Barcel
3. **Pan:** Bimbo, Grupo Bimbo
4. **Lacteos:** Lala, Alpura, distribuidores
5. **Abarrotes:** Mayoristas locales
### Onboarding de Proveedores
```
1. Proveedor se registra
2. Verifica RFC y datos fiscales
3. Sube catalogo de productos
4. Define zonas de cobertura
5. Configura minimos de pedido
6. Queda visible para tiendas
```
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| marketplace.module | Pendiente | `modules/marketplace/` |
| Supplier portal | Pendiente | App separada o seccion |
| SupplierDirectory | Pendiente | `pages/Marketplace.tsx` |
| Order system B2B | Pendiente | `services/supplier-orders.service.ts` |
## Dependencias
### Depende de
- MCH-003 (Productos - para matching)
- MCH-009 (Predicciones - sugerencias)
- Base de usuarios activos
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [ ] Proveedores pueden registrarse
- [ ] Tiendas pueden buscar proveedores
- [ ] Pedidos B2B funcionan
- [ ] Tracking de pedidos funciona
- [ ] Reviews funcionan
- [ ] Comisiones se calculan
## Metricas de Exito
| Metrica | Objetivo Inicial |
|---------|------------------|
| Proveedores registrados | 50 en zona metro |
| Pedidos mensuales | 100 |
| GMV mensual | $500,000 MXN |
| NPS proveedores | >50 |
## Riesgos
| Riesgo | Mitigacion |
|--------|------------|
| Proveedores no se registran | Onboarding personalizado |
| Calidad de servicio variable | Sistema de reviews |
| Precios no competitivos | Comparador visible |
| Entregas fallidas | Penalizacion a proveedor |
## Roadmap Interno
1. **MVP:** Directorio + pedidos manuales
2. **V2:** Pedidos automaticos desde inventario bajo
3. **V3:** Rutas optimizadas para proveedores
4. **V4:** Credito B2B (factoraje)
---
**Ultima actualizacion:** 2026-01-07

149
docs/_MAP.md Normal file
View File

@ -0,0 +1,149 @@
# MiChangarrito - Mapa de Documentacion
**Proyecto:** michangarrito
**Codigo:** MCH
**Fecha:** 2026-01-07
**Estado:** MVP Implementado, Documentacion en progreso
---
## Estructura de Documentacion
```
docs/
├── _MAP.md <- ESTE ARCHIVO
├── 00-vision-general/
│ ├── VISION-PROYECTO.md <- Vision y propuesta de valor
│ ├── REQUERIMIENTOS-FUNCIONALES.md <- Requisitos del sistema
│ └── ARQUITECTURA-TECNICA.md <- Stack y arquitectura
│
├── 01-epicas/
│ ├── _MAP.md <- Indice de epicas
│ ├── MCH-001-infraestructura/ <- FASE 1
│ ├── MCH-002-auth/
│ ├── MCH-003-productos/
│ ├── MCH-004-pos/
│ ├── MCH-005-pagos/
│ ├── MCH-006-onboarding/ <- FASE 2
│ ├── MCH-007-templates/
│ ├── MCH-008-fiados/
│ ├── MCH-009-predicciones/
│ ├── MCH-010-mcp-server/ <- FASE 3
│ ├── MCH-011-whatsapp/
│ ├── MCH-012-chat-llm/
│ ├── MCH-013-clientes/ <- FASE 4
│ ├── MCH-014-pedidos-whatsapp/
│ ├── MCH-015-entregas/
│ ├── MCH-016-suscripciones/ <- FASE 5
│ ├── MCH-017-tokens-ia/
│ ├── MCH-018-pagos-online/
│ ├── MCH-019-offline/ <- FASE 6
│ ├── MCH-020-referidos/
│ ├── MCH-021-codi/
│ ├── MCH-022-widgets/
│ └── ... hasta MCH-028
│
├── 02-especificaciones/
│ ├── CATALOGO-PRODUCTOS.md <- Gestion de catalogo
│ ├── TEMPLATE-PRODUCTOS.md <- Templates de productos
│ ├── POS-BASICO.md <- Punto de venta
│ ├── VENTAS-DIARIAS.md <- Registro de ventas
│ ├── CALCULADORA-CAMBIO.md <- Logica de cambio
│ └── INTEGRACIONES-PAGOS.md <- Mercado Pago, Clip, CoDi
│
└── 90-transversal/
├── arquitectura/
│ └── ARCHITECTURE.md <- Arquitectura del sistema
├── api/
└── deployment/
```
---
## Carpetas por Fase
### FASE 1 - MVP Core
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-001 | Infraestructura | Implementado |
| MCH-002 | Auth | Implementado |
| MCH-003 | Productos | Implementado |
| MCH-004 | POS | Implementado |
| MCH-005 | Pagos | Implementado |
### FASE 2 - Inteligencia
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-006 | Onboarding | Implementado |
| MCH-007 | Templates | Implementado |
| MCH-008 | Fiados | Implementado |
| MCH-009 | Predicciones | Implementado |
### FASE 3 - Asistente IA
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-010 | MCP Server | Implementado |
| MCH-011 | WhatsApp | Implementado |
| MCH-012 | Chat LLM | Implementado |
### FASE 4 - Pedidos
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-013 | Clientes | Pendiente |
| MCH-014 | Pedidos WhatsApp | Pendiente |
| MCH-015 | Entregas | Pendiente |
### FASE 5 - Monetizacion
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-016 | Suscripciones | Pendiente |
| MCH-017 | Tokens IA | Pendiente |
| MCH-018 | Pagos Online | Pendiente |
### FASE 6 - Crecimiento
| Epica | Nombre | Estado |
|-------|--------|--------|
| MCH-019 | Offline | Pendiente |
| MCH-020 | Referidos | Pendiente |
| MCH-021 | CoDi | Pendiente |
| MCH-022 | Widgets | Pendiente |
---
## Archivos Clave
| Archivo | Proposito | Ubicacion |
|---------|-----------|-----------|
| VISION-PROYECTO.md | Vision estrategica | 00-vision-general/ |
| REQUERIMIENTOS-FUNCIONALES.md | Requisitos | 00-vision-general/ |
| ARQUITECTURA-TECNICA.md | Stack tecnico | 00-vision-general/ |
| ARCHITECTURE.md | Arquitectura detallada | 90-transversal/arquitectura/ |
---
## Navegacion Rapida
### Por Componente
- **Backend:** Ver orchestration/inventarios/BACKEND_INVENTORY.yml
- **Frontend:** Ver orchestration/inventarios/FRONTEND_INVENTORY.yml
- **Database:** Ver orchestration/inventarios/DATABASE_INVENTORY.yml
- **Mobile:** Ver apps/mobile/README.md
- **MCP Server:** Ver apps/mcp-server/README.md
- **WhatsApp:** Ver apps/whatsapp-service/README.md
### Por Estado
- **Implementado:** Fases 1-3 (MCH-001 a MCH-012)
- **Pendiente:** Fases 4-6 (MCH-013 a MCH-022+)
---
## Referencias
- [CONTEXTO-PROYECTO.md](../orchestration/00-guidelines/CONTEXTO-PROYECTO.md)
- [PROXIMA-ACCION.md](../orchestration/PROXIMA-ACCION.md)
- [PROJECT-STATUS.md](../orchestration/PROJECT-STATUS.md)
---
**Ultima actualizacion:** 2026-01-07
**Version:** 1.0.0

423
orchestration/CONTEXT-MAP.yml Normal file
View File

@ -0,0 +1,423 @@
# CONTEXT-MAP: MICHANGARRITO
# Sistema: SIMCO - NEXUS v4.0
# Proposito: Mapear contexto automatico por nivel y tarea
# Version: 1.0.0
# Fecha: 2026-01-07
metadata:
proyecto: "michangarrito"
nivel: "STANDALONE"
version: "1.0.0"
ultima_actualizacion: "2026-01-07"
workspace_root: "/home/isem/workspace-v1"
project_root: "/home/isem/workspace-v1/projects/michangarrito"
codigo: "MCH"
# ===============================================================================
# VARIABLES DEL PROYECTO (PRE-RESUELTAS)
# ===============================================================================
variables:
# Identificacion
PROJECT: "michangarrito"
PROJECT_NAME: "MICHANGARRITO"
PROJECT_LEVEL: "STANDALONE"
PROJECT_CODE: "MCH"
# Base de datos
DB_NAME: "michangarrito"
DB_DDL_PATH: "/home/isem/workspace-v1/projects/michangarrito/database/schemas"
DB_SCRIPTS_PATH: "/home/isem/workspace-v1/projects/michangarrito/database"
DB_SEEDS_PATH: "/home/isem/workspace-v1/projects/michangarrito/database/seeds"
RECREATE_CMD: "drop-and-recreate-database.sh"
# Backend
BACKEND_ROOT: "/home/isem/workspace-v1/projects/michangarrito/apps/backend"
BACKEND_SRC: "/home/isem/workspace-v1/projects/michangarrito/apps/backend/src"
BACKEND_TESTS: "/home/isem/workspace-v1/projects/michangarrito/apps/backend/tests"
BACKEND_PORT: 3141
# Frontend Web
FRONTEND_ROOT: "/home/isem/workspace-v1/projects/michangarrito/apps/web"
FRONTEND_SRC: "/home/isem/workspace-v1/projects/michangarrito/apps/web/src"
FRONTEND_PORT: 3140
# Mobile
MOBILE_ROOT: "/home/isem/workspace-v1/projects/michangarrito/apps/mobile"
MOBILE_PORT: 8081
# MCP Server
MCP_SERVER_ROOT: "/home/isem/workspace-v1/projects/michangarrito/apps/mcp-server"
MCP_SERVER_PORT: 3142
# WhatsApp Service
WHATSAPP_ROOT: "/home/isem/workspace-v1/projects/michangarrito/apps/whatsapp-service"
WHATSAPP_PORT: 3143
# Documentacion
DOCS_PATH: "/home/isem/workspace-v1/projects/michangarrito/docs"
ORCHESTRATION_PATH: "/home/isem/workspace-v1/projects/michangarrito/orchestration"
# ===============================================================================
# ALIASES RESUELTOS
# ===============================================================================
aliases:
# Directivas globales
"@SIMCO": "/home/isem/workspace-v1/orchestration/directivas/simco"
"@PRINCIPIOS": "/home/isem/workspace-v1/orchestration/directivas/principios"
"@PERFILES": "/home/isem/workspace-v1/orchestration/agents/perfiles"
"@CATALOG": "/home/isem/workspace-v1/shared/catalog"
# Proyecto especifico
"@DDL": "/home/isem/workspace-v1/projects/michangarrito/database/schemas"
"@SEEDS": "/home/isem/workspace-v1/projects/michangarrito/database/seeds"
"@BACKEND": "/home/isem/workspace-v1/projects/michangarrito/apps/backend/src"
"@WEB": "/home/isem/workspace-v1/projects/michangarrito/apps/web/src"
"@MOBILE": "/home/isem/workspace-v1/projects/michangarrito/apps/mobile"
"@MCP": "/home/isem/workspace-v1/projects/michangarrito/apps/mcp-server"
"@WHATSAPP": "/home/isem/workspace-v1/projects/michangarrito/apps/whatsapp-service"
"@DOCS": "/home/isem/workspace-v1/projects/michangarrito/docs"
# Inventarios
"@INVENTORY": "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios"
"@INV_MASTER": "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/MASTER_INVENTORY.yml"
"@INV_DB": "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/DATABASE_INVENTORY.yml"
"@INV_BE": "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/BACKEND_INVENTORY.yml"
"@INV_FE": "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/FRONTEND_INVENTORY.yml"
# Trazas
"@TRAZA_DB": "/home/isem/workspace-v1/projects/michangarrito/orchestration/trazas/TRAZA-TAREAS-DATABASE.md"
"@TRAZA_BE": "/home/isem/workspace-v1/projects/michangarrito/orchestration/trazas/TRAZA-TAREAS-BACKEND.md"
"@TRAZA_FE": "/home/isem/workspace-v1/projects/michangarrito/orchestration/trazas/TRAZA-TAREAS-FRONTEND.md"
# ===============================================================================
# CONTEXTO POR NIVEL
# ===============================================================================
contexto_por_nivel:
L0_sistema:
descripcion: "Principios fundamentales y perfil de agente"
tokens_estimados: 4500
obligatorio: true
archivos:
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-CAPVED.md"
proposito: "Ciclo de vida de tareas"
tokens: 800
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md"
proposito: "Documentacion antes de codigo"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md"
proposito: "Verificar catalogo antes de crear"
tokens: 600
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md"
proposito: "Build/lint deben pasar"
tokens: 600
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md"
proposito: "Limites de contexto"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md"
proposito: "Preguntar si falta informacion"
tokens: 500
- path: "/home/isem/workspace-v1/orchestration/referencias/ALIASES.yml"
proposito: "Resolucion de @ALIAS"
tokens: 400
L1_proyecto:
descripcion: "Contexto especifico de MICHANGARRITO"
tokens_estimados: 3500
obligatorio: true
archivos:
- path: "/home/isem/workspace-v1/projects/michangarrito/orchestration/00-guidelines/CONTEXTO-PROYECTO.md"
proposito: "Variables y configuracion del proyecto"
tokens: 1500
- path: "/home/isem/workspace-v1/projects/michangarrito/orchestration/PROXIMA-ACCION.md"
proposito: "Estado actual y siguiente paso"
tokens: 500
- path: "/home/isem/workspace-v1/projects/michangarrito/orchestration/PROJECT-STATUS.md"
proposito: "Estado detallado del proyecto"
tokens: 1000
- path: "/home/isem/workspace-v1/projects/michangarrito/orchestration/PLAN-IMPLEMENTACION.md"
proposito: "Plan de fases del proyecto"
tokens: 500
L2_operacion:
descripcion: "SIMCO especificos segun operacion y dominio"
tokens_estimados: 2500
archivos_por_operacion:
CREAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-CREAR.md"
MODIFICAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-MODIFICAR.md"
VALIDAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-VALIDAR.md"
DELEGAR:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-DELEGACION.md"
archivos_por_dominio:
DDL:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-DDL.md"
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/DATABASE_INVENTORY.yml"
BACKEND:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-BACKEND.md"
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/BACKEND_INVENTORY.yml"
FRONTEND:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-FRONTEND.md"
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/inventarios/FRONTEND_INVENTORY.yml"
MOBILE:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-MOBILE.md"
MCP:
- "/home/isem/workspace-v1/orchestration/directivas/simco/SIMCO-MCP.md"
L3_tarea:
descripcion: "Contexto especifico de la tarea"
tokens_max: 8000
dinamico: true
# ===============================================================================
# INTEGRACION CON DOCUMENTACION (docs/)
# ===============================================================================
integracion_docs:
mapa_docs: "@DOCS/_MAP.md"
estructura:
vision: "@DOCS/00-vision-general/"
epicas: "@DOCS/01-epicas/"
especificaciones: "@DOCS/02-especificaciones/"
transversal: "@DOCS/90-transversal/"
epicas_por_fase:
fase1_mvp_core:
- MCH-001-infraestructura
- MCH-002-auth
- MCH-003-productos
- MCH-004-pos
- MCH-005-pagos
fase2_inteligencia:
- MCH-006-onboarding
- MCH-007-templates
- MCH-008-fiados
- MCH-009-predicciones
fase3_asistente_ia:
- MCH-010-mcp-server
- MCH-011-whatsapp
- MCH-012-chat-llm
fase4_pedidos:
- MCH-013-clientes
- MCH-014-pedidos-whatsapp
- MCH-015-entregas
fase5_monetizacion:
- MCH-016-suscripciones
- MCH-017-tokens-ia
- MCH-018-pagos-online
fase6_crecimiento:
- MCH-019-offline
- MCH-020-referidos
- MCH-021-codi
- MCH-022-widgets
# ===============================================================================
# MAPA TAREA -> ARCHIVOS (Especifico MICHANGARRITO)
# ===============================================================================
mapa_tarea_contexto:
database:
crear_tabla:
simco: ["SIMCO-CREAR.md", "SIMCO-DDL.md"]
inventario: "@INV_DB"
referencia: "@DDL/*.sql"
docs: "@DOCS/02-especificaciones/"
crear_schema:
simco: ["SIMCO-CREAR.md", "SIMCO-DDL.md"]
inventario: "@INV_DB"
referencia: "@DDL/*.sql"
backend:
crear_module:
simco: ["SIMCO-CREAR.md", "SIMCO-BACKEND.md"]
inventario: "@INV_BE"
referencia: "@BACKEND/modules/*/*.module.ts"
crear_entity:
simco: ["SIMCO-CREAR.md", "SIMCO-BACKEND.md"]
inventario: "@INV_BE"
referencia: "@BACKEND/modules/*/entities/*.entity.ts"
crear_service:
simco: ["SIMCO-CREAR.md", "SIMCO-BACKEND.md"]
inventario: "@INV_BE"
referencia: "@BACKEND/modules/*/services/*.service.ts"
crear_controller:
simco: ["SIMCO-CREAR.md", "SIMCO-BACKEND.md"]
inventario: "@INV_BE"
referencia: "@BACKEND/modules/*/controllers/*.controller.ts"
frontend:
crear_componente:
simco: ["SIMCO-CREAR.md", "SIMCO-FRONTEND.md"]
inventario: "@INV_FE"
referencia: "@WEB/components/**/*.tsx"
crear_pagina:
simco: ["SIMCO-CREAR.md", "SIMCO-FRONTEND.md"]
inventario: "@INV_FE"
referencia: "@WEB/pages/**/*.tsx"
mobile:
crear_screen:
simco: ["SIMCO-CREAR.md", "SIMCO-MOBILE.md"]
referencia: "@MOBILE/src/screens/*.tsx"
mcp:
crear_tool:
simco: ["SIMCO-CREAR.md", "SIMCO-MCP.md"]
referencia: "@MCP/src/tools/*.ts"
whatsapp:
crear_handler:
simco: ["SIMCO-CREAR.md", "SIMCO-BACKEND.md"]
referencia: "@WHATSAPP/src/handlers/*.ts"
# ===============================================================================
# INFORMACION ESPECIFICA DEL PROYECTO
# ===============================================================================
info_proyecto:
tipo: "SaaS - Punto de Venta + IA para Micro-negocios"
estado: "95% MVP Implementado"
version: "3.2.0"
stack:
backend: "NestJS"
frontend: "React + Vite + TailwindCSS"
mobile: "React Native (Expo)"
database: "PostgreSQL (multi-tenant)"
cache: "Redis"
mcp_server: "TypeScript + MCP SDK"
whatsapp: "NestJS + Meta API"
llm: "Agnostico (OpenRouter/OpenAI/Claude)"
apps:
- backend: "API NestJS"
- web: "Dashboard React"
- mobile: "App Expo"
- mcp-server: "Gateway LLM"
- whatsapp-service: "Bot WhatsApp"
schemas:
- tenant_management
- core_operations
- pos_system
- integrations
- subscription_system
- notifications
- analytics
- cache
- auth
- ai
modulos_backend:
implementados:
- auth
- tenants
- products
- categories
- sales
- payments
- customers
- templates
- fiados
- predictions
- integrations
- subscriptions
- notifications
- analytics
modelo_negocio:
planes:
- Changarrito: "$99/mes + 500 tokens IA"
- Tiendita: "$199/mes + 2000 tokens + WhatsApp propio"
tokens_adicionales:
- "$29 = 1,000 tokens"
- "$69 = 3,000 tokens"
- "$149 = 8,000 tokens"
- "$299 = 20,000 tokens"
# ===============================================================================
# VALIDACION DE TOKENS
# ===============================================================================
validacion_tokens:
limite_absoluto: 25000
limite_seguro: 18000
limite_alerta: 20000
presupuesto:
L0_sistema: 4500
L1_proyecto: 3500
L2_operacion: 2500
L3_tarea_max: 8000
total_base: 10500
disponible_tarea: 7500
# ===============================================================================
# HERENCIA
# ===============================================================================
herencia:
tipo: "STANDALONE"
hereda_de:
- "/home/isem/workspace-v1/orchestration/"
usa_catalog:
- payments (Stripe, Mercado Pago)
- notifications (WhatsApp, Push)
- auth (JWT)
- multi-tenancy (RLS)
# ===============================================================================
# INTEGRACIONES EXTERNAS
# ===============================================================================
integraciones:
whatsapp:
proveedor: "Meta WhatsApp Business API"
proposito: "Canal principal de comunicacion"
stripe:
proveedor: "Stripe"
proposito: "Suscripciones, pagos, OXXO"
mercado_pago:
proveedor: "Mercado Pago"
proposito: "Terminal de pago con tarjeta"
clip:
proveedor: "Clip"
proposito: "Terminal de pago con tarjeta"
codi:
proveedor: "CoDi (Banxico)"
proposito: "Pagos QR sin comision"
llm:
proveedor: "OpenRouter (agnostico)"
proposito: "Gateway LLM para IA"
firebase:
proveedor: "Firebase"
proposito: "Push notifications"
ocr:
proveedor: "Google Vision / Tesseract"
proposito: "OCR de imagenes"
whisper:
proveedor: "Whisper"
proposito: "Transcripcion de audio"
# ===============================================================================
# BUSQUEDA DE HISTORICO
# ===============================================================================
busqueda_historico:
habilitado: true
ubicaciones:
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/trazas/"
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/analisis/"
- "/home/isem/workspace-v1/projects/michangarrito/orchestration/reportes/"
- "/home/isem/workspace-v1/orchestration/errores/REGISTRO-ERRORES.yml"
- "/home/isem/workspace-v1/shared/knowledge-base/lessons-learned/"

135
orchestration/PROXIMA-ACCION.md Normal file
View File

@ -0,0 +1,135 @@
# PROXIMA ACCION - MiChangarrito
**Proyecto:** michangarrito
**Estado:** 95% MVP Implementado
**Fecha:** 2026-01-07
**Fase:** Consolidacion de Documentacion SIMCO
---
## RESUMEN DEL ESTADO ACTUAL
### Implementacion Tecnica: 95% COMPLETADA
| Componente | Estado | Detalles |
|------------|--------|----------|
| Database | 100% | 10 schemas, 29 tablas |
| Backend NestJS | 100% | 14 modulos |
| Frontend React | 100% | 7 paginas |
| Mobile Expo | 100% | 10 pantallas |
| MCP Server | 100% | 15 herramientas |
| WhatsApp Service | 100% | Multi-tenant |
### Documentacion SIMCO: INCOMPLETA
| Artefacto | Estado | Prioridad |
|-----------|--------|-----------|
| CONTEXTO-PROYECTO.md | EXISTE | - |
| PROJECT-STATUS.md | EXISTE | - |
| PLAN-IMPLEMENTACION.md | EXISTE | - |
| PROXIMA-ACCION.md | CREADO | P0 |
| docs/_MAP.md | FALTA | P0 |
| DATABASE_INVENTORY.yml | FALTA | P1 |
| BACKEND_INVENTORY.yml | FALTA | P1 |
| FRONTEND_INVENTORY.yml | FALTA | P1 |
| Epicas MCH-001 a MCH-028 | FALTA | P2 |
---
## PROXIMA ACCION INMEDIATA
### Tarea: Crear docs/_MAP.md
**Prioridad:** P0
**Estimacion:** 0.5 horas
**Responsable:** Agente Orquestador
**Descripcion:**
Crear el archivo de navegacion principal para la documentacion del proyecto.
**Contenido esperado:**
```markdown
# MiChangarrito - Mapa de Documentacion
## 00-vision-general/
- VISION-PROYECTO.md
- REQUERIMIENTOS-FUNCIONALES.md
- ARQUITECTURA-TECNICA.md
## 01-epicas/
- MCH-001 a MCH-028
## 02-especificaciones/
- CATALOGO-PRODUCTOS.md
- TEMPLATE-PRODUCTOS.md
- ...
```
---
## BACKLOG DE TAREAS
### Sprint 1: Documentacion Base (4h)
| # | Tarea | Prioridad | Horas |
|---|-------|-----------|-------|
| 1 | Crear docs/_MAP.md | P0 | 0.5 |
| 2 | Crear DATABASE_INVENTORY.yml | P1 | 1.5 |
| 3 | Crear BACKEND_INVENTORY.yml | P1 | 1.5 |
| 4 | Crear FRONTEND_INVENTORY.yml | P1 | 1 |
### Sprint 2: Trazas y Dependencias (4h)
| # | Tarea | Prioridad | Horas |
|---|-------|-----------|-------|
| 1 | Crear DEPENDENCIAS.yml | P1 | 1 |
| 2 | Crear TRAZA-TAREAS-DATABASE.md | P1 | 1 |
| 3 | Crear TRAZA-TAREAS-BACKEND.md | P1 | 1 |
| 4 | Crear TRAZA-TAREAS-FRONTEND.md | P1 | 1 |
### Sprint 3-5: Epicas MCH (42h)
| # | Tarea | Prioridad | Horas |
|---|-------|-----------|-------|
| 1-10 | Epicas MCH-001 a MCH-010 | P2 | 15 |
| 11-20 | Epicas MCH-011 a MCH-020 | P2 | 15 |
| 21-28 | Epicas MCH-021 a MCH-028 | P2 | 12 |
---
## DEPENDENCIAS
### De este proyecto:
- @SIMCO para directivas generales
- @CATALOG para funcionalidades reutilizables
- shared/catalog/payments (Stripe)
- shared/catalog/notifications (WhatsApp, Push)
### Hacia este proyecto:
- Ninguna (proyecto STANDALONE)
---
## METRICAS DE PROGRESO
| Metrica | Valor Actual | Objetivo |
|---------|--------------|----------|
| Archivos SIMCO | 4 de 40+ | 100% |
| Epicas documentadas | 0 de 28 | 100% |
| Inventarios | 1 (MASTER) | 4 |
| Trazas | 0 | 3 |
---
## NOTAS
- El proyecto tiene implementacion tecnica casi completa
- Falta documentacion formal SIMCO para trazabilidad
- Las epicas MCH-001 a MCH-028 deben seguir el template de gamilit
- Priorizar docs/_MAP.md para navegacion
---
**Ultima actualizacion:** 2026-01-07
**Autor:** Agente Orquestador Workspace
**Version:** 1.0.0

337
orchestration/inventarios/BACKEND_INVENTORY.yml Normal file
View File

@ -0,0 +1,337 @@
# BACKEND INVENTORY - MiChangarrito
# Version: 1.0.0
# Ultima actualizacion: 2026-01-07
# Sistema: SIMCO - NEXUS v4.0
metadata:
proyecto: "michangarrito"
componente: "backend"
framework: "NestJS"
lenguaje: "TypeScript"
puerto: 3141
estado: "100% modulos completados"
# ============================================================================
# RESUMEN
# ============================================================================
resumen:
total_modulos: 14
total_controllers: 14
total_services: 14
total_entities: 29
arquitectura: "modular"
orm: "TypeORM"
auth: "JWT"
# ============================================================================
# ESTRUCTURA DE CARPETAS
# ============================================================================
estructura:
root: "apps/backend"
src: "apps/backend/src"
modules: "apps/backend/src/modules"
shared: "apps/backend/src/shared"
config: "apps/backend/src/config"
# ============================================================================
# MODULOS
# ============================================================================
modulos:
- nombre: auth
ruta: "modules/auth"
descripcion: "Autenticacion JWT y sesiones"
estado: completado
archivos:
- auth.module.ts
- auth.controller.ts
- auth.service.ts
- strategies/jwt.strategy.ts
- guards/jwt-auth.guard.ts
- guards/roles.guard.ts
- dto/login.dto.ts
- dto/register.dto.ts
endpoints:
- POST /auth/login
- POST /auth/register
- POST /auth/logout
- GET /auth/me
- POST /auth/refresh
- nombre: billing
ruta: "modules/billing"
descripcion: "Facturacion y reportes fiscales"
estado: completado
archivos:
- billing.module.ts
- billing.controller.ts
- billing.service.ts
endpoints:
- GET /billing/invoices
- POST /billing/invoices
- GET /billing/reports
- nombre: categories
ruta: "modules/categories"
descripcion: "Categorias de productos"
estado: completado
archivos:
- categories.module.ts
- categories.controller.ts
- categories.service.ts
- entities/category.entity.ts
- dto/create-category.dto.ts
endpoints:
- GET /categories
- GET /categories/:id
- POST /categories
- PUT /categories/:id
- DELETE /categories/:id
- nombre: customers
ruta: "modules/customers"
descripcion: "Clientes y cuentas de credito"
estado: completado
archivos:
- customers.module.ts
- customers.controller.ts
- customers.service.ts
- entities/customer.entity.ts
- entities/credit-account.entity.ts
- dto/create-customer.dto.ts
endpoints:
- GET /customers
- GET /customers/:id
- POST /customers
- PUT /customers/:id
- DELETE /customers/:id
- GET /customers/:id/credit
- POST /customers/:id/credit/payment
- nombre: integrations
ruta: "modules/integrations"
descripcion: "Integraciones externas por tenant"
estado: completado
archivos:
- integrations.module.ts
- integrations.controller.ts
- integrations.service.ts
- entities/tenant-integration.entity.ts
- providers/whatsapp.provider.ts
- providers/llm.provider.ts
- providers/stripe.provider.ts
endpoints:
- GET /integrations
- GET /integrations/:provider
- POST /integrations/:provider/configure
- DELETE /integrations/:provider
- POST /integrations/:provider/test
- nombre: inventory
ruta: "modules/inventory"
descripcion: "Control de inventario"
estado: completado
archivos:
- inventory.module.ts
- inventory.controller.ts
- inventory.service.ts
- entities/stock-movement.entity.ts
- entities/inventory-count.entity.ts
- dto/stock-adjustment.dto.ts
endpoints:
- GET /inventory/products/:productId
- POST /inventory/adjust
- POST /inventory/count
- GET /inventory/movements
- GET /inventory/low-stock
- nombre: messaging
ruta: "modules/messaging"
descripcion: "Mensajeria WhatsApp"
estado: completado
archivos:
- messaging.module.ts
- messaging.controller.ts
- messaging.service.ts
- entities/conversation.entity.ts
- entities/message.entity.ts
- gateways/whatsapp.gateway.ts
endpoints:
- GET /messaging/conversations
- GET /messaging/conversations/:id
- POST /messaging/send
- POST /messaging/webhook
- nombre: orders
ruta: "modules/orders"
descripcion: "Pedidos"
estado: completado
archivos:
- orders.module.ts
- orders.controller.ts
- orders.service.ts
- entities/order.entity.ts
- entities/order-item.entity.ts
- dto/create-order.dto.ts
endpoints:
- GET /orders
- GET /orders/:id
- POST /orders
- PUT /orders/:id/status
- DELETE /orders/:id
- nombre: payments
ruta: "modules/payments"
descripcion: "Integracion con proveedores de pago"
estado: completado
archivos:
- payments.module.ts
- payments.controller.ts
- payments.service.ts
- providers/stripe.provider.ts
- providers/mercadopago.provider.ts
endpoints:
- POST /payments/intent
- POST /payments/confirm
- GET /payments/:id
- POST /payments/webhook
- nombre: products
ruta: "modules/products"
descripcion: "Catalogo de productos"
estado: completado
archivos:
- products.module.ts
- products.controller.ts
- products.service.ts
- entities/product.entity.ts
- entities/product-variant.entity.ts
- dto/create-product.dto.ts
endpoints:
- GET /products
- GET /products/:id
- POST /products
- PUT /products/:id
- DELETE /products/:id
- GET /products/search
- GET /products/barcode/:code
- nombre: sales
ruta: "modules/sales"
descripcion: "Punto de venta"
estado: completado
archivos:
- sales.module.ts
- sales.controller.ts
- sales.service.ts
- entities/sale.entity.ts
- entities/sale-item.entity.ts
- dto/create-sale.dto.ts
endpoints:
- GET /sales
- GET /sales/:id
- POST /sales
- POST /sales/:id/void
- GET /sales/daily-report
- GET /sales/by-date
- nombre: subscriptions
ruta: "modules/subscriptions"
descripcion: "Planes y suscripciones"
estado: completado
archivos:
- subscriptions.module.ts
- subscriptions.controller.ts
- subscriptions.service.ts
- entities/plan.entity.ts
- entities/subscription.entity.ts
- entities/token-usage.entity.ts
endpoints:
- GET /subscriptions/plans
- GET /subscriptions/current
- POST /subscriptions/subscribe
- POST /subscriptions/cancel
- GET /subscriptions/tokens
- POST /subscriptions/tokens/purchase
# ============================================================================
# SHARED
# ============================================================================
shared:
guards:
- jwt-auth.guard.ts
- roles.guard.ts
- tenant.guard.ts
decorators:
- current-user.decorator.ts
- current-tenant.decorator.ts
- roles.decorator.ts
interceptors:
- transform.interceptor.ts
- logging.interceptor.ts
- tenant.interceptor.ts
filters:
- http-exception.filter.ts
- validation.filter.ts
pipes:
- validation.pipe.ts
middleware:
- tenant.middleware.ts
- logger.middleware.ts
# ============================================================================
# CONFIGURACION
# ============================================================================
config:
database:
archivo: "config/database.config.ts"
tipo: "TypeORM"
jwt:
archivo: "config/jwt.config.ts"
expiracion: "7d"
redis:
archivo: "config/redis.config.ts"
db: 8
# ============================================================================
# COMANDOS
# ============================================================================
comandos:
build: "npm run build"
start_dev: "npm run start:dev"
lint: "npm run lint"
test: "npm run test"
# ============================================================================
# DEPENDENCIAS PRINCIPALES
# ============================================================================
dependencias:
nestjs: "^10.x"
typeorm: "^0.3.x"
passport: "^0.7.x"
passport-jwt: "^4.x"
class-validator: "^0.14.x"
class-transformer: "^0.5.x"
# ============================================================================
# NOTAS
# ============================================================================
notas:
- "Todos los endpoints requieren JWT excepto /auth/login y /auth/register"
- "Multi-tenant via header X-Tenant-ID o JWT claim"
- "Rate limiting configurado por tenant"
- "Swagger disponible en /api/docs"

331
orchestration/inventarios/DATABASE_INVENTORY.yml Normal file
View File

@ -0,0 +1,331 @@
# DATABASE INVENTORY - MiChangarrito
# Version: 1.0.0
# Ultima actualizacion: 2026-01-07
# Sistema: SIMCO - NEXUS v4.0
metadata:
proyecto: "michangarrito"
componente: "database"
db_name: "michangarrito_platform"
version_pg: "16+"
estado: "100% DDL completado"
# ============================================================================
# RESUMEN
# ============================================================================
resumen:
total_schemas: 10
total_tablas: 29
total_archivos_ddl: 13
rls_habilitado: true
multi_tenant: true
tenant_column: "tenant_id"
# ============================================================================
# ARCHIVOS DDL
# ============================================================================
archivos_ddl:
- archivo: "00-extensions.sql"
descripcion: "Extensiones PostgreSQL"
contenido:
- uuid-ossp
- pgcrypto
estado: completado
- archivo: "01-schemas.sql"
descripcion: "Creacion de schemas"
schemas_creados:
- public
- auth
- catalog
- sales
- inventory
- customers
- orders
- subscriptions
- messaging
- integrations
estado: completado
- archivo: "02-functions.sql"
descripcion: "Funciones utilitarias"
funciones:
- current_tenant_id()
- set_tenant_id(uuid)
- updated_at_trigger()
estado: completado
- archivo: "03-public.sql"
descripcion: "Schema public - tenants base"
tablas:
- tenants
- tenant_settings
estado: completado
- archivo: "04-auth.sql"
descripcion: "Autenticacion y usuarios"
tablas:
- users
- sessions
- roles
- permissions
estado: completado
- archivo: "05-catalog.sql"
descripcion: "Catalogo de productos"
tablas:
- categories
- products
- product_variants
estado: completado
- archivo: "06-sales.sql"
descripcion: "Punto de venta"
tablas:
- sales
- sale_items
- payment_methods
- cash_registers
estado: completado
- archivo: "07-inventory.sql"
descripcion: "Control de inventario"
tablas:
- stock_movements
- inventory_counts
estado: completado
- archivo: "08-customers.sql"
descripcion: "Clientes y fiados"
tablas:
- customers
- credit_accounts
- credit_transactions
estado: completado
- archivo: "09-orders.sql"
descripcion: "Pedidos"
tablas:
- orders
- order_items
estado: completado
- archivo: "10-subscriptions.sql"
descripcion: "Planes y suscripciones"
tablas:
- plans
- subscriptions
- token_packages
- token_usage
estado: completado
- archivo: "11-messaging.sql"
descripcion: "Mensajeria WhatsApp"
tablas:
- conversations
- messages
estado: completado
- archivo: "12-integrations.sql"
descripcion: "Integraciones por tenant"
tablas:
- tenant_integrations
- integration_logs
estado: completado
# ============================================================================
# SCHEMAS DETALLADOS
# ============================================================================
schemas:
public:
descripcion: "Datos globales y tenants"
tablas:
- nombre: tenants
columnas: [id, name, slug, settings, status, created_at]
rls: false
descripcion: "Organizaciones/negocios"
- nombre: tenant_settings
columnas: [id, tenant_id, key, value]
rls: true
descripcion: "Configuraciones por tenant"
auth:
descripcion: "Autenticacion y sesiones"
tablas:
- nombre: users
columnas: [id, tenant_id, phone, email, password_hash, name, role, status]
rls: true
descripcion: "Usuarios del sistema"
- nombre: sessions
columnas: [id, user_id, token, device_info, expires_at]
rls: true
descripcion: "Sesiones activas"
- nombre: roles
columnas: [id, tenant_id, name, permissions]
rls: true
descripcion: "Roles personalizados"
catalog:
descripcion: "Catalogo de productos"
tablas:
- nombre: categories
columnas: [id, tenant_id, name, parent_id, image_url, sort_order]
rls: true
descripcion: "Categorias de productos"
- nombre: products
columnas: [id, tenant_id, category_id, sku, name, description, price, cost, image_url, barcode, track_inventory, status]
rls: true
descripcion: "Productos"
- nombre: product_variants
columnas: [id, product_id, name, sku, price, attributes]
rls: true
descripcion: "Variantes de producto"
sales:
descripcion: "Punto de venta"
tablas:
- nombre: sales
columnas: [id, tenant_id, user_id, customer_id, subtotal, tax, discount, total, payment_method, status, notes]
rls: true
descripcion: "Ventas registradas"
- nombre: sale_items
columnas: [id, sale_id, product_id, quantity, unit_price, discount, total]
rls: true
descripcion: "Detalle de venta"
- nombre: payment_methods
columnas: [id, tenant_id, name, type, settings, active]
rls: true
descripcion: "Metodos de pago"
- nombre: cash_registers
columnas: [id, tenant_id, name, opening_balance, current_balance, status]
rls: true
descripcion: "Cajas registradoras"
inventory:
descripcion: "Control de inventario"
tablas:
- nombre: stock_movements
columnas: [id, tenant_id, product_id, type, quantity, reason, reference_id, user_id]
rls: true
descripcion: "Movimientos de stock"
- nombre: inventory_counts
columnas: [id, tenant_id, product_id, expected, counted, difference, user_id, status]
rls: true
descripcion: "Conteos de inventario"
customers:
descripcion: "Clientes y credito"
tablas:
- nombre: customers
columnas: [id, tenant_id, name, phone, email, address, credit_enabled, credit_limit, balance]
rls: true
descripcion: "Clientes"
- nombre: credit_accounts
columnas: [id, customer_id, limit, balance, status]
rls: true
descripcion: "Cuentas de credito (fiados)"
- nombre: credit_transactions
columnas: [id, credit_account_id, type, amount, sale_id, notes]
rls: true
descripcion: "Movimientos de credito"
orders:
descripcion: "Pedidos"
tablas:
- nombre: orders
columnas: [id, tenant_id, customer_id, channel, status, total, delivery_address, scheduled_at]
rls: true
descripcion: "Pedidos"
- nombre: order_items
columnas: [id, order_id, product_id, quantity, unit_price, notes]
rls: true
descripcion: "Detalle de pedido"
subscriptions:
descripcion: "Planes y tokens IA"
tablas:
- nombre: plans
columnas: [id, name, price, features, token_quota, status]
rls: false
descripcion: "Planes disponibles"
- nombre: subscriptions
columnas: [id, tenant_id, plan_id, status, current_period_start, current_period_end]
rls: true
descripcion: "Suscripciones activas"
- nombre: token_packages
columnas: [id, name, tokens, price]
rls: false
descripcion: "Paquetes de tokens"
- nombre: token_usage
columnas: [id, tenant_id, tokens_used, operation, metadata]
rls: true
descripcion: "Consumo de tokens"
messaging:
descripcion: "WhatsApp"
tablas:
- nombre: conversations
columnas: [id, tenant_id, customer_phone, status, last_message_at]
rls: true
descripcion: "Conversaciones"
- nombre: messages
columnas: [id, conversation_id, direction, type, content, status, wa_message_id]
rls: true
descripcion: "Mensajes"
integrations:
descripcion: "Integraciones externas"
tablas:
- nombre: tenant_integrations
columnas: [id, tenant_id, provider, credentials, settings, status]
rls: true
descripcion: "Integraciones por tenant"
- nombre: integration_logs
columnas: [id, integration_id, operation, request, response, status]
rls: true
descripcion: "Logs de integraciones"
# ============================================================================
# COMANDOS UTILES
# ============================================================================
comandos:
recrear_db: "./drop-and-recreate-database.sh"
conectar: "psql -d michangarrito_platform"
ejecutar_ddl: "psql -d michangarrito_platform -f database/schemas/*.sql"
# ============================================================================
# MIGRACIONES PENDIENTES
# ============================================================================
migraciones_pendientes: []
# ============================================================================
# NOTAS
# ============================================================================
notas:
- "RLS habilitado en todas las tablas excepto plans y token_packages"
- "Usar current_tenant_id() para obtener tenant del contexto"
- "Trigger updated_at automatico en todas las tablas"
- "Multi-tenant por columna tenant_id"

290
orchestration/inventarios/FRONTEND_INVENTORY.yml Normal file
View File

@ -0,0 +1,290 @@
# FRONTEND INVENTORY - MiChangarrito
# Version: 1.0.0
# Ultima actualizacion: 2026-01-07
# Sistema: SIMCO - NEXUS v4.0
metadata:
proyecto: "michangarrito"
componente: "frontend-web"
framework: "React 18"
bundler: "Vite"
styling: "TailwindCSS"
puerto: 3140
estado: "100% paginas completadas"
# ============================================================================
# RESUMEN
# ============================================================================
resumen:
total_paginas: 7
total_componentes: 15
total_contexts: 3
arquitectura: "SPA"
state_management: "Context API + React Query"
router: "React Router v6"
# ============================================================================
# ESTRUCTURA DE CARPETAS
# ============================================================================
estructura:
root: "apps/web"
src: "apps/web/src"
componentes: "apps/web/src/components"
paginas: "apps/web/src/pages"
contexts: "apps/web/src/contexts"
lib: "apps/web/src/lib"
assets: "apps/web/src/assets"
# ============================================================================
# PAGINAS
# ============================================================================
paginas:
- nombre: "Login"
ruta: "/login"
archivo: "pages/Login.tsx"
descripcion: "Inicio de sesion"
protegida: false
estado: completado
- nombre: "Dashboard"
ruta: "/"
archivo: "pages/Dashboard.tsx"
descripcion: "Panel principal con metricas"
protegida: true
estado: completado
- nombre: "POS"
ruta: "/pos"
archivo: "pages/POS.tsx"
descripcion: "Punto de venta"
protegida: true
estado: completado
- nombre: "Products"
ruta: "/products"
archivo: "pages/Products.tsx"
descripcion: "Gestion de productos"
protegida: true
estado: completado
- nombre: "Customers"
ruta: "/customers"
archivo: "pages/Customers.tsx"
descripcion: "Gestion de clientes"
protegida: true
estado: completado
- nombre: "Sales"
ruta: "/sales"
archivo: "pages/Sales.tsx"
descripcion: "Historial de ventas"
protegida: true
estado: completado
- nombre: "Settings"
ruta: "/settings"
archivo: "pages/Settings.tsx"
descripcion: "Configuracion del negocio"
protegida: true
estado: completado
# ============================================================================
# COMPONENTES
# ============================================================================
componentes:
layout:
- nombre: "Layout"
archivo: "components/Layout.tsx"
descripcion: "Layout principal con sidebar"
- nombre: "Sidebar"
archivo: "components/Sidebar.tsx"
descripcion: "Menu lateral de navegacion"
- nombre: "Header"
archivo: "components/Header.tsx"
descripcion: "Header con usuario y notificaciones"
pos:
- nombre: "ProductGrid"
archivo: "components/pos/ProductGrid.tsx"
descripcion: "Grid de productos para venta"
- nombre: "Cart"
archivo: "components/pos/Cart.tsx"
descripcion: "Carrito de compra"
- nombre: "PaymentModal"
archivo: "components/pos/PaymentModal.tsx"
descripcion: "Modal de pago"
- nombre: "ReceiptModal"
archivo: "components/pos/ReceiptModal.tsx"
descripcion: "Ticket de venta"
products:
- nombre: "ProductList"
archivo: "components/products/ProductList.tsx"
descripcion: "Tabla de productos"
- nombre: "ProductForm"
archivo: "components/products/ProductForm.tsx"
descripcion: "Formulario crear/editar producto"
- nombre: "CategorySelect"
archivo: "components/products/CategorySelect.tsx"
descripcion: "Selector de categoria"
customers:
- nombre: "CustomerList"
archivo: "components/customers/CustomerList.tsx"
descripcion: "Tabla de clientes"
- nombre: "CustomerForm"
archivo: "components/customers/CustomerForm.tsx"
descripcion: "Formulario de cliente"
- nombre: "CreditHistory"
archivo: "components/customers/CreditHistory.tsx"
descripcion: "Historial de fiados"
common:
- nombre: "Button"
archivo: "components/ui/Button.tsx"
descripcion: "Boton reutilizable"
- nombre: "Input"
archivo: "components/ui/Input.tsx"
descripcion: "Input con validacion"
- nombre: "Modal"
archivo: "components/ui/Modal.tsx"
descripcion: "Modal base"
- nombre: "Table"
archivo: "components/ui/Table.tsx"
descripcion: "Tabla con paginacion"
- nombre: "Card"
archivo: "components/ui/Card.tsx"
descripcion: "Card container"
# ============================================================================
# CONTEXTS
# ============================================================================
contexts:
- nombre: "AuthContext"
archivo: "contexts/AuthContext.tsx"
descripcion: "Estado de autenticacion"
provee:
- user
- token
- login()
- logout()
- isAuthenticated
- nombre: "CartContext"
archivo: "contexts/CartContext.tsx"
descripcion: "Estado del carrito POS"
provee:
- items
- addItem()
- removeItem()
- updateQuantity()
- clear()
- total
- nombre: "TenantContext"
archivo: "contexts/TenantContext.tsx"
descripcion: "Configuracion del tenant"
provee:
- tenant
- settings
- updateSettings()
# ============================================================================
# LIB / UTILIDADES
# ============================================================================
lib:
- nombre: "api"
archivo: "lib/api.ts"
descripcion: "Cliente HTTP con Axios"
- nombre: "auth"
archivo: "lib/auth.ts"
descripcion: "Funciones de autenticacion"
- nombre: "format"
archivo: "lib/format.ts"
descripcion: "Formateo de moneda, fechas"
- nombre: "storage"
archivo: "lib/storage.ts"
descripcion: "LocalStorage helpers"
# ============================================================================
# RUTAS
# ============================================================================
rutas:
publicas:
- /login
protegidas:
- /
- /pos
- /products
- /customers
- /sales
- /settings
por_rol:
owner:
- todas
employee:
- /
- /pos
- /sales
viewer:
- /
- /sales
# ============================================================================
# COMANDOS
# ============================================================================
comandos:
dev: "npm run dev"
build: "npm run build"
preview: "npm run preview"
lint: "npm run lint"
# ============================================================================
# DEPENDENCIAS PRINCIPALES
# ============================================================================
dependencias:
react: "^18.x"
react-router-dom: "^6.x"
axios: "^1.x"
react-query: "^5.x"
tailwindcss: "^3.x"
lucide-react: "^0.x"
react-hook-form: "^7.x"
zod: "^3.x"
# ============================================================================
# NOTAS
# ============================================================================
notas:
- "Responsive design para tablet y desktop"
- "Dark mode pendiente"
- "PWA pendiente"
- "Offline mode pendiente"

154
orchestration/trazas/TRAZA-TAREAS-DATABASE.md Normal file
View File

@ -0,0 +1,154 @@
# TRAZA DE TAREAS - DATABASE
**Proyecto:** michangarrito
**Capa:** Database (PostgreSQL)
**Version:** 1.0.0
---
## HISTORIAL
### [2026-01-04] MCH-DB-001
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Setup inicial de base de datos PostgreSQL con multi-tenant.
#### Archivos Creados
- `database/schemas/00-extensions.sql`
- `database/schemas/01-schemas.sql`
- `database/schemas/02-functions.sql`
#### Resultado
Extensiones uuid-ossp y pgcrypto habilitadas. Funcion current_tenant_id() creada.
---
### [2026-01-05] MCH-DB-002
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Schema public y auth implementados.
#### Archivos Creados
- `database/schemas/03-public.sql` (tenants, tenant_settings)
- `database/schemas/04-auth.sql` (users, sessions, roles)
#### Resultado
Tablas base con RLS configurado.
---
### [2026-01-05] MCH-DB-003
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Schema catalog para productos y categorias.
#### Archivos Creados
- `database/schemas/05-catalog.sql` (categories, products, product_variants)
#### Resultado
Catalogo con soporte para variantes y codigos de barras.
---
### [2026-01-06] MCH-DB-004
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Schema sales para punto de venta.
#### Archivos Creados
- `database/schemas/06-sales.sql` (sales, sale_items, payment_methods, cash_registers)
#### Resultado
POS completamente funcional con multiples metodos de pago.
---
### [2026-01-06] MCH-DB-005
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Schemas inventory y customers.
#### Archivos Creados
- `database/schemas/07-inventory.sql` (stock_movements, inventory_counts)
- `database/schemas/08-customers.sql` (customers, credit_accounts, credit_transactions)
#### Resultado
Control de inventario y sistema de fiados implementado.
---
### [2026-01-06] MCH-DB-006
**Estado:** completado
**Agente:** Database-Agent
#### Descripcion
Schemas orders, subscriptions, messaging, integrations.
#### Archivos Creados
- `database/schemas/09-orders.sql`
- `database/schemas/10-subscriptions.sql`
- `database/schemas/11-messaging.sql`
- `database/schemas/12-integrations.sql`
#### Resultado
29 tablas totales en 10 schemas. DDL 100% completado.
---
## ESTADISTICAS
| Metrica | Valor |
|---------|-------|
| Total Schemas | 10 |
| Total Tablas | 29 |
| Tablas con RLS | 27 |
| Archivos DDL | 13 |
| Estado | 100% Completado |
---
## TAREAS PENDIENTES
| ID | Tarea | Prioridad | Dependencias |
|----|-------|-----------|--------------|
| MCH-DB-007 | Seeds de datos demo | P2 | - |
| MCH-DB-008 | Indices de performance | P2 | MCH-DB-006 |
| MCH-DB-009 | Particionamiento sales | P3 | MCH-DB-008 |
---
## REFERENCIA RAPIDA
```
database/
├── schemas/
│ ├── 00-extensions.sql
│ ├── 01-schemas.sql
│ ├── 02-functions.sql
│ ├── 03-public.sql
│ ├── 04-auth.sql
│ ├── 05-catalog.sql
│ ├── 06-sales.sql
│ ├── 07-inventory.sql
│ ├── 08-customers.sql
│ ├── 09-orders.sql
│ ├── 10-subscriptions.sql
│ ├── 11-messaging.sql
│ └── 12-integrations.sql
├── seeds/
└── drop-and-recreate-database.sh
```
---
**Ultima actualizacion:** 2026-01-07

212
orchestration/trazas/TRAZA-TAREAS-FRONTEND.md Normal file
View File

@ -0,0 +1,212 @@
# TRAZA DE TAREAS - FRONTEND
**Proyecto:** michangarrito
**Capa:** Frontend Web (React + Vite)
**Version:** 1.0.0
---
## HISTORIAL
### [2026-01-04] MCH-FE-001
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Setup proyecto React con Vite y TailwindCSS.
#### Archivos Creados
- `apps/web/` (estructura base)
- `apps/web/tailwind.config.js`
- `apps/web/vite.config.ts`
#### Resultado
Proyecto configurado con React 18, Vite, TailwindCSS.
---
### [2026-01-05] MCH-FE-002
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Layout principal y componentes base UI.
#### Archivos Creados
- `apps/web/src/components/Layout.tsx`
- `apps/web/src/components/Sidebar.tsx`
- `apps/web/src/components/Header.tsx`
- `apps/web/src/components/ui/Button.tsx`
- `apps/web/src/components/ui/Input.tsx`
- `apps/web/src/components/ui/Modal.tsx`
- `apps/web/src/components/ui/Card.tsx`
- `apps/web/src/components/ui/Table.tsx`
#### Resultado
Sistema de componentes UI base implementado.
---
### [2026-01-05] MCH-FE-003
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Contexts de autenticacion y carrito.
#### Archivos Creados
- `apps/web/src/contexts/AuthContext.tsx`
- `apps/web/src/contexts/CartContext.tsx`
- `apps/web/src/contexts/TenantContext.tsx`
#### Resultado
State management con Context API configurado.
---
### [2026-01-06] MCH-FE-004
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Pagina de Login y Dashboard.
#### Archivos Creados
- `apps/web/src/pages/Login.tsx`
- `apps/web/src/pages/Dashboard.tsx`
#### Resultado
Login funcional con OTP. Dashboard con metricas.
---
### [2026-01-06] MCH-FE-005
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Pagina POS y componentes relacionados.
#### Archivos Creados
- `apps/web/src/pages/POS.tsx`
- `apps/web/src/components/pos/ProductGrid.tsx`
- `apps/web/src/components/pos/Cart.tsx`
- `apps/web/src/components/pos/PaymentModal.tsx`
- `apps/web/src/components/pos/ReceiptModal.tsx`
#### Resultado
Punto de venta completo con carrito y pago.
---
### [2026-01-06] MCH-FE-006
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Paginas Products y Customers.
#### Archivos Creados
- `apps/web/src/pages/Products.tsx`
- `apps/web/src/pages/Customers.tsx`
- `apps/web/src/components/products/ProductList.tsx`
- `apps/web/src/components/products/ProductForm.tsx`
- `apps/web/src/components/products/CategorySelect.tsx`
- `apps/web/src/components/customers/CustomerList.tsx`
- `apps/web/src/components/customers/CustomerForm.tsx`
- `apps/web/src/components/customers/CreditHistory.tsx`
#### Resultado
CRUD completo de productos y clientes.
---
### [2026-01-07] MCH-FE-007
**Estado:** completado
**Agente:** Frontend-Agent
#### Descripcion
Paginas Sales y Settings.
#### Archivos Creados
- `apps/web/src/pages/Sales.tsx`
- `apps/web/src/pages/Settings.tsx`
#### Resultado
Historial de ventas y configuracion del negocio.
---
## ESTADISTICAS
| Metrica | Valor |
|---------|-------|
| Total Paginas | 7 |
| Total Componentes | 15 |
| Contexts | 3 |
| Libs/Utils | 4 |
| Estado | 100% Completado |
---
## TAREAS PENDIENTES
| ID | Tarea | Prioridad | Dependencias |
|----|-------|-----------|--------------|
| MCH-FE-008 | Implementar Dark Mode | P2 | MCH-FE-006 |
| MCH-FE-009 | PWA y Service Worker | P1 | MCH-FE-007 |
| MCH-FE-010 | Modo Offline | P1 | MCH-FE-009 |
| MCH-FE-011 | Dashboard reportes avanzados | P2 | MCH-FE-007 |
| MCH-FE-012 | Integracion WebSocket | P2 | MCH-BE-010 |
---
## REFERENCIA RAPIDA
```
apps/web/src/
├── components/
│ ├── Layout.tsx
│ ├── Sidebar.tsx
│ ├── Header.tsx
│ ├── pos/
│ │ ├── ProductGrid.tsx
│ │ ├── Cart.tsx
│ │ ├── PaymentModal.tsx
│ │ └── ReceiptModal.tsx
│ ├── products/
│ │ ├── ProductList.tsx
│ │ ├── ProductForm.tsx
│ │ └── CategorySelect.tsx
│ ├── customers/
│ │ ├── CustomerList.tsx
│ │ ├── CustomerForm.tsx
│ │ └── CreditHistory.tsx
│ └── ui/
│ ├── Button.tsx
│ ├── Input.tsx
│ ├── Modal.tsx
│ ├── Card.tsx
│ └── Table.tsx
├── contexts/
│ ├── AuthContext.tsx
│ ├── CartContext.tsx
│ └── TenantContext.tsx
├── pages/
│ ├── Login.tsx
│ ├── Dashboard.tsx
│ ├── POS.tsx
│ ├── Products.tsx
│ ├── Customers.tsx
│ ├── Sales.tsx
│ └── Settings.tsx
└── lib/
├── api.ts
├── auth.ts
├── format.ts
└── storage.ts
```
---
**Ultima actualizacion:** 2026-01-07