diff --git a/docs/01-epicas/MCH-001-infraestructura-base.md b/docs/01-epicas/MCH-001-infraestructura-base.md new file mode 100644 index 000000000..d726c8f7c --- /dev/null +++ b/docs/01-epicas/MCH-001-infraestructura-base.md @@ -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 diff --git a/docs/01-epicas/MCH-002-autenticacion.md b/docs/01-epicas/MCH-002-autenticacion.md new file mode 100644 index 000000000..d0b2dfc3e --- /dev/null +++ b/docs/01-epicas/MCH-002-autenticacion.md @@ -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 diff --git a/docs/01-epicas/MCH-003-catalogo-productos.md b/docs/01-epicas/MCH-003-catalogo-productos.md new file mode 100644 index 000000000..d7f333333 --- /dev/null +++ b/docs/01-epicas/MCH-003-catalogo-productos.md @@ -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 diff --git a/docs/01-epicas/MCH-004-punto-venta.md b/docs/01-epicas/MCH-004-punto-venta.md new file mode 100644 index 000000000..965d69291 --- /dev/null +++ b/docs/01-epicas/MCH-004-punto-venta.md @@ -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 diff --git a/docs/01-epicas/MCH-005-integraciones-pago.md b/docs/01-epicas/MCH-005-integraciones-pago.md new file mode 100644 index 000000000..92185fa7b --- /dev/null +++ b/docs/01-epicas/MCH-005-integraciones-pago.md @@ -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 diff --git a/docs/01-epicas/MCH-006-onboarding-inteligente.md b/docs/01-epicas/MCH-006-onboarding-inteligente.md new file mode 100644 index 000000000..58dc0a713 --- /dev/null +++ b/docs/01-epicas/MCH-006-onboarding-inteligente.md @@ -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 diff --git a/docs/01-epicas/MCH-007-templates-catalogos.md b/docs/01-epicas/MCH-007-templates-catalogos.md new file mode 100644 index 000000000..d1485a467 --- /dev/null +++ b/docs/01-epicas/MCH-007-templates-catalogos.md @@ -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 diff --git a/docs/01-epicas/MCH-008-sistema-fiados.md b/docs/01-epicas/MCH-008-sistema-fiados.md new file mode 100644 index 000000000..17e5d1046 --- /dev/null +++ b/docs/01-epicas/MCH-008-sistema-fiados.md @@ -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 diff --git a/docs/01-epicas/MCH-009-prediccion-inventario.md b/docs/01-epicas/MCH-009-prediccion-inventario.md new file mode 100644 index 000000000..468d96de2 --- /dev/null +++ b/docs/01-epicas/MCH-009-prediccion-inventario.md @@ -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 diff --git a/docs/01-epicas/MCH-010-mcp-server.md b/docs/01-epicas/MCH-010-mcp-server.md new file mode 100644 index 000000000..5f48df01d --- /dev/null +++ b/docs/01-epicas/MCH-010-mcp-server.md @@ -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 diff --git a/docs/01-epicas/MCH-011-whatsapp-service.md b/docs/01-epicas/MCH-011-whatsapp-service.md new file mode 100644 index 000000000..a8c153ea4 --- /dev/null +++ b/docs/01-epicas/MCH-011-whatsapp-service.md @@ -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 diff --git a/docs/01-epicas/MCH-012-chat-llm-dueno.md b/docs/01-epicas/MCH-012-chat-llm-dueno.md new file mode 100644 index 000000000..31f963202 --- /dev/null +++ b/docs/01-epicas/MCH-012-chat-llm-dueno.md @@ -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 diff --git a/docs/01-epicas/MCH-013-chat-llm-cliente.md b/docs/01-epicas/MCH-013-chat-llm-cliente.md new file mode 100644 index 000000000..9fc93aaf5 --- /dev/null +++ b/docs/01-epicas/MCH-013-chat-llm-cliente.md @@ -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 diff --git a/docs/01-epicas/MCH-014-gestion-clientes.md b/docs/01-epicas/MCH-014-gestion-clientes.md new file mode 100644 index 000000000..e2288027d --- /dev/null +++ b/docs/01-epicas/MCH-014-gestion-clientes.md @@ -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 diff --git a/docs/01-epicas/MCH-015-pedidos-whatsapp.md b/docs/01-epicas/MCH-015-pedidos-whatsapp.md new file mode 100644 index 000000000..9cead872d --- /dev/null +++ b/docs/01-epicas/MCH-015-pedidos-whatsapp.md @@ -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 diff --git a/docs/01-epicas/MCH-016-entregas-domicilio.md b/docs/01-epicas/MCH-016-entregas-domicilio.md new file mode 100644 index 000000000..07f0eebd1 --- /dev/null +++ b/docs/01-epicas/MCH-016-entregas-domicilio.md @@ -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 diff --git a/docs/01-epicas/MCH-017-notificaciones.md b/docs/01-epicas/MCH-017-notificaciones.md new file mode 100644 index 000000000..c519960bb --- /dev/null +++ b/docs/01-epicas/MCH-017-notificaciones.md @@ -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 diff --git a/docs/01-epicas/MCH-018-planes-suscripciones.md b/docs/01-epicas/MCH-018-planes-suscripciones.md new file mode 100644 index 000000000..e31b99754 --- /dev/null +++ b/docs/01-epicas/MCH-018-planes-suscripciones.md @@ -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 diff --git a/docs/01-epicas/MCH-019-tienda-tokens.md b/docs/01-epicas/MCH-019-tienda-tokens.md new file mode 100644 index 000000000..018079517 --- /dev/null +++ b/docs/01-epicas/MCH-019-tienda-tokens.md @@ -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 diff --git a/docs/01-epicas/MCH-020-pagos-suscripcion.md b/docs/01-epicas/MCH-020-pagos-suscripcion.md new file mode 100644 index 000000000..0c591d75d --- /dev/null +++ b/docs/01-epicas/MCH-020-pagos-suscripcion.md @@ -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 diff --git a/docs/01-epicas/MCH-021-dashboard-web.md b/docs/01-epicas/MCH-021-dashboard-web.md new file mode 100644 index 000000000..3dd503f6c --- /dev/null +++ b/docs/01-epicas/MCH-021-dashboard-web.md @@ -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 diff --git a/docs/01-epicas/MCH-022-modo-offline.md b/docs/01-epicas/MCH-022-modo-offline.md new file mode 100644 index 000000000..6a277b4f4 --- /dev/null +++ b/docs/01-epicas/MCH-022-modo-offline.md @@ -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 diff --git a/docs/01-epicas/MCH-023-programa-referidos.md b/docs/01-epicas/MCH-023-programa-referidos.md new file mode 100644 index 000000000..33e1eb097 --- /dev/null +++ b/docs/01-epicas/MCH-023-programa-referidos.md @@ -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 diff --git a/docs/01-epicas/MCH-024-codi-spei.md b/docs/01-epicas/MCH-024-codi-spei.md new file mode 100644 index 000000000..cc74bfcb4 --- /dev/null +++ b/docs/01-epicas/MCH-024-codi-spei.md @@ -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 diff --git a/docs/01-epicas/MCH-025-widgets-atajos.md b/docs/01-epicas/MCH-025-widgets-atajos.md new file mode 100644 index 000000000..86065547f --- /dev/null +++ b/docs/01-epicas/MCH-025-widgets-atajos.md @@ -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 diff --git a/docs/01-epicas/MCH-026-multi-idioma-latam.md b/docs/01-epicas/MCH-026-multi-idioma-latam.md new file mode 100644 index 000000000..769586bf6 --- /dev/null +++ b/docs/01-epicas/MCH-026-multi-idioma-latam.md @@ -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 ( +
+

{t('title')}

+ +
+ ); +} +``` + +### 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 diff --git a/docs/01-epicas/MCH-027-integracion-sat.md b/docs/01-epicas/MCH-027-integracion-sat.md new file mode 100644 index 000000000..1d1af3fea --- /dev/null +++ b/docs/01-epicas/MCH-027-integracion-sat.md @@ -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 diff --git a/docs/01-epicas/MCH-028-marketplace-proveedores.md b/docs/01-epicas/MCH-028-marketplace-proveedores.md new file mode 100644 index 000000000..e3d5406fa --- /dev/null +++ b/docs/01-epicas/MCH-028-marketplace-proveedores.md @@ -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 diff --git a/docs/_MAP.md b/docs/_MAP.md new file mode 100644 index 000000000..2a2210c37 --- /dev/null +++ b/docs/_MAP.md @@ -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 diff --git a/orchestration/CONTEXT-MAP.yml b/orchestration/CONTEXT-MAP.yml new file mode 100644 index 000000000..97efd155a --- /dev/null +++ b/orchestration/CONTEXT-MAP.yml @@ -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/" diff --git a/orchestration/PROXIMA-ACCION.md b/orchestration/PROXIMA-ACCION.md new file mode 100644 index 000000000..1c89ffc59 --- /dev/null +++ b/orchestration/PROXIMA-ACCION.md @@ -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 diff --git a/orchestration/inventarios/BACKEND_INVENTORY.yml b/orchestration/inventarios/BACKEND_INVENTORY.yml new file mode 100644 index 000000000..b7af2faf8 --- /dev/null +++ b/orchestration/inventarios/BACKEND_INVENTORY.yml @@ -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" diff --git a/orchestration/inventarios/DATABASE_INVENTORY.yml b/orchestration/inventarios/DATABASE_INVENTORY.yml new file mode 100644 index 000000000..9f51333ce --- /dev/null +++ b/orchestration/inventarios/DATABASE_INVENTORY.yml @@ -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" diff --git a/orchestration/inventarios/FRONTEND_INVENTORY.yml b/orchestration/inventarios/FRONTEND_INVENTORY.yml new file mode 100644 index 000000000..50cbf3e88 --- /dev/null +++ b/orchestration/inventarios/FRONTEND_INVENTORY.yml @@ -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" diff --git a/orchestration/trazas/TRAZA-TAREAS-DATABASE.md b/orchestration/trazas/TRAZA-TAREAS-DATABASE.md new file mode 100644 index 000000000..273e22634 --- /dev/null +++ b/orchestration/trazas/TRAZA-TAREAS-DATABASE.md @@ -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 diff --git a/orchestration/trazas/TRAZA-TAREAS-FRONTEND.md b/orchestration/trazas/TRAZA-TAREAS-FRONTEND.md new file mode 100644 index 000000000..0d6c80064 --- /dev/null +++ b/orchestration/trazas/TRAZA-TAREAS-FRONTEND.md @@ -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