[MCH-DOC-VAL] docs: Estandarizar épicas MCH-002 a MCH-005 con HU formales

- MCH-002: 4 HU (MCH-US-010 a MCH-US-013), 13 SP - MCH-003: 5 HU (MCH-US-020 a MCH-US-024), 8 SP - MCH-004: 6 HU (MCH-US-030 a MCH-US-035), 21 SP - MCH-005: 4 HU (MCH-US-040 a MCH-US-043), 13 SP Formato: Como/Quiero/Para + Criterios [CA-XXX-N] + Tareas [MCH-TT-XXX-NN] Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-17 04:25:14 -06:00 · 2026-01-17 04:25:14 -06:00 · 8a540b4e94
commit 8a540b4e94
parent e493017e86
4 changed files with 571 additions and 15 deletions
--- a/docs/01-epicas/MCH-002-autenticacion.md
+++ b/docs/01-epicas/MCH-002-autenticacion.md
@ -6,9 +6,10 @@ code: MCH-002
 status: Completado
 phase: 1
 priority: P0
+story_points: 13
 created_at: 2026-01-05
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
 dependencies:
  blocks: ["MCH-003", "MCH-004"]
  depends_on: ["MCH-001"]
@ -19,8 +20,9 @@ dependencies:
 ## Metadata
 - **Codigo:** MCH-002
 - **Fase:** 1 - MVP Core
- **Prioridad:** P0
+- **Prioridad:** P0 (Critica)
 - **Estado:** Completado
+- **Story Points:** 13
 - **Fecha inicio:** 2026-01-05
 - **Fecha fin:** 2026-01-06

@ -121,7 +123,7 @@ Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono
 - MCH-004 (POS)
 - Todos los modulos que requieren auth

-## Criterios de Aceptacion
+## Criterios de Aceptacion de Epica

 - [x] Registro con telefono funcional
 - [x] OTP se envia correctamente
@ -130,6 +132,131 @@ Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono
 - [x] Roles owner/employee/viewer funcionan
 - [x] Sesiones se pueden revocar

+---
+
+## Historias de Usuario
+
+### MCH-US-010: Registro con Telefono y OTP
+
+**Como** propietario de un micro-negocio
+**Quiero** registrarme usando mi numero de telefono y verificar con OTP
+**Para** crear mi cuenta de forma sencilla sin necesidad de email
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-010-1] El usuario puede ingresar su numero de telefono mexicano (10 digitos)
+- [CA-010-2] Se envia OTP de 6 digitos via SMS o WhatsApp
+- [CA-010-3] OTP expira en 5 minutos
+- [CA-010-4] Maximo 3 intentos de verificacion antes de bloqueo temporal
+- [CA-010-5] Al verificar exitosamente, se crea el tenant automaticamente
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-010-01 | DDL tabla auth.users con campos phone, pin_hash | DDL | Completado |
+| MCH-TT-010-02 | Endpoint POST /auth/register | Backend | Completado |
+| MCH-TT-010-03 | Endpoint POST /auth/send-otp | Backend | Completado |
+| MCH-TT-010-04 | Endpoint POST /auth/verify-otp | Backend | Completado |
+| MCH-TT-010-05 | Servicio OTPService con integracion SMS | Backend | Completado |
+| MCH-TT-010-06 | Tests unitarios de registro | Test | Completado |
+
+---
+
+### MCH-US-011: Login con PIN de 4 Digitos
+
+**Como** usuario registrado
+**Quiero** acceder a mi cuenta usando un PIN de 4 digitos
+**Para** entrar rapidamente sin tener que esperar un OTP cada vez
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-011-1] Usuario puede configurar PIN de 4 digitos despues del registro
+- [CA-011-2] PIN se almacena hasheado (bcrypt)
+- [CA-011-3] Login exitoso con telefono + PIN genera JWT
+- [CA-011-4] 5 intentos fallidos bloquean la cuenta temporalmente (15 min)
+- [CA-011-5] Opcion "Olvide mi PIN" envia OTP para recuperacion
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-011-01 | Endpoint POST /auth/set-pin | Backend | Completado |
+| MCH-TT-011-02 | Endpoint POST /auth/login (telefono + PIN) | Backend | Completado |
+| MCH-TT-011-03 | Endpoint POST /auth/login-otp (recuperacion) | Backend | Completado |
+| MCH-TT-011-04 | Logica de bloqueo por intentos fallidos | Backend | Completado |
+| MCH-TT-011-05 | Tests unitarios de login | Test | Completado |
+
+---
+
+### MCH-US-012: Gestion de Sesiones JWT
+
+**Como** sistema de autenticacion
+**Quiero** manejar sesiones con JWT y refresh tokens
+**Para** mantener sesiones seguras y permitir logout remoto
+
+**Story Points:** 5
+
+**Criterios de Aceptacion:**
+- [CA-012-1] JWT access token con expiracion de 7 dias
+- [CA-012-2] Refresh token con expiracion de 30 dias
+- [CA-012-3] Endpoint GET /auth/me retorna usuario actual
+- [CA-012-4] Endpoint POST /auth/refresh renueva el JWT
+- [CA-012-5] Endpoint POST /auth/logout revoca sesion actual
+- [CA-012-6] Endpoint DELETE /auth/sessions revoca todas las sesiones
+- [CA-012-7] Sessions incluyen device_info para identificacion
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-012-01 | DDL tabla auth.sessions | DDL | Completado |
+| MCH-TT-012-02 | JwtStrategy con Passport | Backend | Completado |
+| MCH-TT-012-03 | Endpoint GET /auth/me | Backend | Completado |
+| MCH-TT-012-04 | Endpoint POST /auth/refresh | Backend | Completado |
+| MCH-TT-012-05 | Endpoint POST /auth/logout | Backend | Completado |
+| MCH-TT-012-06 | Endpoint DELETE /auth/sessions | Backend | Completado |
+| MCH-TT-012-07 | Tests de sesiones | Test | Completado |
+
+---
+
+### MCH-US-013: Sistema de Roles Basicos
+
+**Como** propietario del negocio
+**Quiero** asignar roles a mis empleados (owner, employee, viewer)
+**Para** controlar que acciones puede realizar cada persona
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-013-1] Rol owner tiene acceso completo al tenant
+- [CA-013-2] Rol employee puede operar POS y ver reportes basicos
+- [CA-013-3] Rol viewer solo puede consultar sin modificar
+- [CA-013-4] Roles se almacenan en tabla auth.roles con permisos JSONB
+- [CA-013-5] Guards validan permisos en cada endpoint protegido
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-013-01 | DDL tabla auth.roles | DDL | Completado |
+| MCH-TT-013-02 | RolesGuard para proteger endpoints | Backend | Completado |
+| MCH-TT-013-03 | Decorador @Roles() para controllers | Backend | Completado |
+| MCH-TT-013-04 | Seed de roles por defecto | Backend | Completado |
+| MCH-TT-013-05 | Tests de autorizacion | Test | Completado |
+
+---
+
+## Resumen de Story Points
+
+| Historia | SP | Estado |
+|----------|-----|--------|
+| MCH-US-010: Registro con Telefono y OTP | 3 | Completado |
+| MCH-US-011: Login con PIN de 4 Digitos | 3 | Completado |
+| MCH-US-012: Gestion de Sesiones JWT | 5 | Completado |
+| MCH-US-013: Sistema de Roles Basicos | 2 | Completado |
+| **TOTAL** | **13** | **Completado** |
+
+---
+
 ## Configuracion

 ```typescript
@ -150,4 +277,4 @@ Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono

 ---

-**Ultima actualizacion:** 2026-01-07
+**Ultima actualizacion:** 2026-01-17
--- a/docs/01-epicas/MCH-003-catalogo-productos.md
+++ b/docs/01-epicas/MCH-003-catalogo-productos.md
@ -6,9 +6,10 @@ code: MCH-003
 status: Completado
 phase: 1
 priority: P0
+story_points: 8
 created_at: 2026-01-05
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
 dependencies:
  blocks: ["MCH-004", "MCH-007", "MCH-009"]
  depends_on: ["MCH-001", "MCH-002"]
@ -21,6 +22,7 @@ dependencies:
 - **Fase:** 1 - MVP Core
 - **Prioridad:** P0
 - **Estado:** Completado
+- **Story Points:** 8
 - **Fecha inicio:** 2026-01-05
 - **Fecha fin:** 2026-01-06

@ -122,7 +124,7 @@ Sistema de gestion de catalogo de productos para micro-negocios: categorias jera
 - MCH-007 (Templates)
 - MCH-009 (Predicciones)

-## Criterios de Aceptacion
+## Criterios de Aceptacion de Epica

 - [x] CRUD categorias funcional
 - [x] CRUD productos funcional
@ -131,6 +133,150 @@ Sistema de gestion de catalogo de productos para micro-negocios: categorias jera
 - [x] Imagenes se guardan correctamente
 - [x] Margen se calcula (precio - costo)

+---
+
+## Historias de Usuario
+
+### MCH-US-020: Gestion de Categorias
+
+**Como** dueno de negocio
+**Quiero** crear y organizar categorias de productos en jerarquia
+**Para** mantener mi catalogo ordenado y facilitar la navegacion
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-020-1] CRUD completo de categorias
+- [CA-020-2] Soporte para categorias padre/hijo (jerarquia)
+- [CA-020-3] Imagen opcional por categoria
+- [CA-020-4] Orden personalizable (sort_order)
+- [CA-020-5] Activar/desactivar categorias
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-020-01 | DDL tabla categories en schema catalog | DDL | Completado |
+| MCH-TT-020-02 | Entity Category con relacion parent | Backend | Completado |
+| MCH-TT-020-03 | CategoriesService con CRUD | Backend | Completado |
+| MCH-TT-020-04 | CategoriesController con endpoints | Backend | Completado |
+| MCH-TT-020-05 | Componente CategoryList | Frontend | Completado |
+
+---
+
+### MCH-US-021: Gestion de Productos
+
+**Como** dueno de negocio
+**Quiero** registrar productos con sus atributos completos
+**Para** tener un catalogo detallado con precios y costos
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-021-1] CRUD completo de productos
+- [CA-021-2] Campos: SKU, nombre, descripcion, precio, costo
+- [CA-021-3] Asociacion a categoria
+- [CA-021-4] Imagen de producto
+- [CA-021-5] Estado activo/inactivo
+- [CA-021-6] Calculo automatico de margen (precio - costo)
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-021-01 | DDL tabla products en schema catalog | DDL | Completado |
+| MCH-TT-021-02 | Entity Product con relaciones | Backend | Completado |
+| MCH-TT-021-03 | ProductsService con CRUD | Backend | Completado |
+| MCH-TT-021-04 | ProductsController con endpoints | Backend | Completado |
+| MCH-TT-021-05 | Componente ProductForm | Frontend | Completado |
+| MCH-TT-021-06 | Componente ProductList | Frontend | Completado |
+
+---
+
+### MCH-US-022: Variantes de Producto
+
+**Como** dueno de negocio
+**Quiero** crear variantes de un producto (tallas, colores)
+**Para** manejar diferentes presentaciones del mismo articulo
+
+**Story Points:** 1
+
+**Criterios de Aceptacion:**
+- [CA-022-1] CRUD de variantes por producto
+- [CA-022-2] Atributos en formato JSONB (flexible)
+- [CA-022-3] SKU y precio independiente por variante
+- [CA-022-4] Nombre descriptivo de variante
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-022-01 | DDL tabla product_variants | DDL | Completado |
+| MCH-TT-022-02 | Entity ProductVariant | Backend | Completado |
+| MCH-TT-022-03 | Servicio de variantes integrado | Backend | Completado |
+| MCH-TT-022-04 | UI variantes en ProductForm | Frontend | Completado |
+
+---
+
+### MCH-US-023: Busqueda por Codigo de Barras
+
+**Como** dueno de negocio
+**Quiero** buscar productos escaneando codigo de barras
+**Para** encontrar productos rapidamente en el punto de venta
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-023-1] Campo barcode en productos
+- [CA-023-2] Endpoint de busqueda por barcode
+- [CA-023-3] Respuesta rapida (<100ms)
+- [CA-023-4] Si no existe, ofrecer crear nuevo producto
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-023-01 | Campo barcode con indice en DDL | DDL | Completado |
+| MCH-TT-023-02 | Endpoint GET /products/barcode/:code | Backend | Completado |
+| MCH-TT-023-03 | Logica de busqueda optimizada | Backend | Completado |
+| MCH-TT-023-04 | Componente BarcodeScanner | Frontend | Completado |
+
+---
+
+### MCH-US-024: Busqueda de Productos
+
+**Como** dueno de negocio
+**Quiero** buscar productos por nombre, SKU o categoria
+**Para** encontrar rapidamente lo que necesito
+
+**Story Points:** 1
+
+**Criterios de Aceptacion:**
+- [CA-024-1] Busqueda por nombre (parcial)
+- [CA-024-2] Busqueda por SKU (exacto)
+- [CA-024-3] Filtro por categoria
+- [CA-024-4] Filtro por estado (activo/inactivo)
+- [CA-024-5] Paginacion de resultados
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-024-01 | Endpoint GET /products/search | Backend | Completado |
+| MCH-TT-024-02 | Query builder con filtros | Backend | Completado |
+| MCH-TT-024-03 | UI de busqueda con filtros | Frontend | Completado |
+| MCH-TT-024-04 | Componente de paginacion | Frontend | Completado |
+
+---
+
+## Resumen de Story Points
+
+| Historia | SP | Estado |
+|----------|-----|--------|
+| MCH-US-020: Gestion de Categorias | 2 | Completado |
+| MCH-US-021: Gestion de Productos | 2 | Completado |
+| MCH-US-022: Variantes de Producto | 1 | Completado |
+| MCH-US-023: Busqueda por Codigo de Barras | 2 | Completado |
+| MCH-US-024: Busqueda de Productos | 1 | Completado |
+| **TOTAL** | **8** | **Completado** |
+
+---
+
 ## UI Components

 ### ProductList
@ -146,4 +292,4 @@ Sistema de gestion de catalogo de productos para micro-negocios: categorias jera

 ---

-**Ultima actualizacion:** 2026-01-07
+**Ultima actualizacion:** 2026-01-17
--- a/docs/01-epicas/MCH-004-punto-venta.md
+++ b/docs/01-epicas/MCH-004-punto-venta.md
@ -6,9 +6,10 @@ code: MCH-004
 status: Completado
 phase: 1
 priority: P0
+story_points: 21
 created_at: 2026-01-06
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
 dependencies:
  blocks: ["MCH-005", "MCH-008", "MCH-009"]
  depends_on: ["MCH-001", "MCH-002", "MCH-003"]
@ -21,6 +22,7 @@ dependencies:
 - **Fase:** 1 - MVP Core
 - **Prioridad:** P0
 - **Estado:** Completado
+- **Story Points:** 21
 - **Fecha inicio:** 2026-01-06
 - **Fecha fin:** 2026-01-06

@ -108,6 +110,168 @@ Sistema de punto de venta (POS) optimizado para micro-negocios: interfaz tactil
 6. Actualiza saldo del cliente
 ```

+## Historias de Usuario
+
+### MCH-US-030: Grid de Productos Tactil
+
+**Como** empleado del negocio
+**Quiero** ver un grid de productos organizado por categorias con interfaz tactil
+**Para** seleccionar rapidamente los productos que el cliente desea comprar
+
+**Story Points:** 5
+
+**Criterios de Aceptacion:**
+- [CA-030-1] El grid muestra productos como cards con imagen, nombre y precio
+- [CA-030-2] Los productos se organizan en tabs por categoria
+- [CA-030-3] Click/tap en producto lo agrega al carrito automaticamente
+- [CA-030-4] Existe barra de busqueda para filtrar productos
+- [CA-030-5] Soporte para escaneo de codigo de barras
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-030-01 | Crear componente ProductGrid | Frontend | Completado |
+| MCH-TT-030-02 | Implementar tabs de categorias | Frontend | Completado |
+| MCH-TT-030-03 | Integrar barra de busqueda | Frontend | Completado |
+| MCH-TT-030-04 | Agregar soporte para codigo de barras | Frontend | Completado |
+
+---
+
+### MCH-US-031: Carrito de Compras Interactivo
+
+**Como** empleado del negocio
+**Quiero** gestionar un carrito de compras con modificacion de cantidades
+**Para** ajustar los items antes de procesar la venta
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-031-1] Lista de items muestra producto, cantidad, precio unitario y subtotal
+- [CA-031-2] Botones +/- permiten modificar cantidad de cada item
+- [CA-031-3] Posibilidad de eliminar items del carrito
+- [CA-031-4] Muestra subtotal, descuento, impuesto y total
+- [CA-031-5] Boton "Cobrar" visible y accesible
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-031-01 | Crear componente Cart.tsx | Frontend | Completado |
+| MCH-TT-031-02 | Implementar logica de cantidades | Frontend | Completado |
+| MCH-TT-031-03 | Calcular totales dinamicamente | Frontend | Completado |
+
+---
+
+### MCH-US-032: Procesamiento de Pagos Multiples
+
+**Como** empleado del negocio
+**Quiero** procesar pagos con diferentes metodos (efectivo, tarjeta, fiado)
+**Para** ofrecer flexibilidad a los clientes en su forma de pago
+
+**Story Points:** 5
+
+**Criterios de Aceptacion:**
+- [CA-032-1] Modal muestra metodos de pago disponibles para el tenant
+- [CA-032-2] Pago en efectivo permite ingresar monto recibido
+- [CA-032-3] Sistema calcula y muestra el cambio automaticamente
+- [CA-032-4] Pago fiado requiere seleccionar cliente y verifica limite de credito
+- [CA-032-5] Confirmacion de pago registra la venta
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-032-01 | Crear DDL tabla payment_methods | DDL | Completado |
+| MCH-TT-032-02 | Implementar PaymentModal.tsx | Frontend | Completado |
+| MCH-TT-032-03 | Crear endpoint POST /sales | Backend | Completado |
+| MCH-TT-032-04 | Integrar verificacion de credito | Backend | Completado |
+
+---
+
+### MCH-US-033: Generacion de Tickets
+
+**Como** empleado del negocio
+**Quiero** generar tickets/recibos de venta
+**Para** entregar comprobante al cliente y mantener registro
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-033-1] Ticket muestra datos del negocio (nombre, direccion, telefono)
+- [CA-033-2] Lista detallada de productos con cantidades y precios
+- [CA-033-3] Muestra subtotal, descuentos, impuestos y total
+- [CA-033-4] Opcion para imprimir ticket
+- [CA-033-5] Opcion para compartir ticket (WhatsApp, email)
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-033-01 | Crear componente ReceiptModal.tsx | Frontend | Completado |
+| MCH-TT-033-02 | Implementar formato de impresion | Frontend | Completado |
+| MCH-TT-033-03 | Agregar funcionalidad de compartir | Frontend | Completado |
+
+---
+
+### MCH-US-034: Historial de Ventas
+
+**Como** dueno del negocio
+**Quiero** ver el historial de ventas del dia
+**Para** monitorear el desempeno y tomar decisiones
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-034-1] Lista de ventas del dia con hora, total y metodo de pago
+- [CA-034-2] Detalle de cada venta al hacer click
+- [CA-034-3] Filtro por rango de fechas disponible
+- [CA-034-4] Reporte diario con totales por metodo de pago
+- [CA-034-5] Posibilidad de anular ventas con autorizacion
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-034-01 | Crear endpoint GET /sales/daily-report | Backend | Completado |
+| MCH-TT-034-02 | Crear endpoint GET /sales/by-date | Backend | Completado |
+| MCH-TT-034-03 | Implementar vista de historial | Frontend | Completado |
+| MCH-TT-034-04 | Crear endpoint POST /sales/:id/void | Backend | Completado |
+
+---
+
+### MCH-US-035: Gestion de Caja Registradora
+
+**Como** administrador del negocio
+**Quiero** gestionar la caja registradora con apertura y cierre
+**Para** controlar el efectivo y cuadrar al final del dia
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-035-1] Apertura de caja con saldo inicial
+- [CA-035-2] Seguimiento de saldo actual durante el dia
+- [CA-035-3] Cierre de caja con cuadre de efectivo
+- [CA-035-4] Registro de cajas por sucursal/punto de venta
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-035-01 | Crear DDL tabla cash_registers | DDL | Completado |
+| MCH-TT-035-02 | Implementar servicio de caja | Backend | Completado |
+| MCH-TT-035-03 | Integrar caja con flujo de POS | Frontend | Completado |
+
+---
+
+## Resumen de Story Points
+
+| Historia | Descripcion | Story Points |
+|----------|-------------|--------------|
+| MCH-US-030 | Grid de Productos Tactil | 5 |
+| MCH-US-031 | Carrito de Compras Interactivo | 3 |
+| MCH-US-032 | Procesamiento de Pagos Multiples | 5 |
+| MCH-US-033 | Generacion de Tickets | 3 |
+| MCH-US-034 | Historial de Ventas | 3 |
+| MCH-US-035 | Gestion de Caja Registradora | 2 |
+| **TOTAL** | **Epica MCH-004** | **21** |
+
+---
+
 ## Entregables

 | Entregable | Estado | Archivo |
@ -172,4 +336,4 @@ Sistema de punto de venta (POS) optimizado para micro-negocios: interfaz tactil

 ---

-**Ultima actualizacion:** 2026-01-07
+**Ultima actualizacion:** 2026-01-17
--- a/docs/01-epicas/MCH-005-integraciones-pago.md
+++ b/docs/01-epicas/MCH-005-integraciones-pago.md
@ -6,9 +6,10 @@ code: MCH-005
 status: Completado
 phase: 1
 priority: P0
+story_points: 13
 created_at: 2026-01-06
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
 dependencies:
  blocks: ["MCH-018", "MCH-020"]
  depends_on: ["MCH-001", "MCH-002", "MCH-004"]
@ -21,6 +22,7 @@ dependencies:
 - **Fase:** 1 - MVP Core
 - **Prioridad:** P0
 - **Estado:** Completado
+- **Story Points:** 13
 - **Fecha inicio:** 2026-01-06
 - **Fecha fin:** 2026-01-07

@ -183,4 +185,121 @@ Integracion con proveedores de pago populares en Mexico para aceptar pagos con t

 ---

-**Ultima actualizacion:** 2026-01-07
+## Historias de Usuario
+
+### MCH-US-040: Integracion Mercado Pago Point
+
+**Como** empleado de tienda
+**Quiero** procesar pagos con tarjeta usando el lector Mercado Pago Point
+**Para** ofrecer una opcion de pago rapida y segura a los clientes
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-040-1] ✅ Configuracion de credenciales Mercado Pago por tenant
+- [CA-040-2] ✅ Conexion bluetooth con dispositivo Point establecida
+- [CA-040-3] ✅ Monto enviado correctamente a terminal
+- [CA-040-4] ✅ Webhook de confirmacion procesado en <5 segundos
+- [CA-040-5] ✅ Venta marcada como pagada automaticamente
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-040-01 | Configurar SDK Mercado Pago | Backend | Completado |
+| MCH-TT-040-02 | Implementar MercadoPagoProvider | Backend | Completado |
+| MCH-TT-040-03 | Endpoint webhook MercadoPago | Backend | Completado |
+| MCH-TT-040-04 | UI seleccion Mercado Pago en POS | Frontend | Completado |
+| MCH-TT-040-05 | Tests de integracion | Test | Completado |
+
+---
+
+### MCH-US-041: Integracion Clip
+
+**Como** empleado de tienda
+**Quiero** procesar pagos con tarjeta usando terminal Clip
+**Para** tener una alternativa de pago con tarjeta
+
+**Story Points:** 3
+
+**Criterios de Aceptacion:**
+- [CA-041-1] ✅ Configuracion de credenciales Clip por tenant
+- [CA-041-2] ✅ Envio de monto a terminal Clip
+- [CA-041-3] ✅ Recepcion de webhook de confirmacion
+- [CA-041-4] ✅ Manejo de errores y rechazos de tarjeta
+- [CA-041-5] ✅ Registro de transaccion en base de datos
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-041-01 | Implementar ClipProvider | Backend | Completado |
+| MCH-TT-041-02 | Endpoint webhook Clip | Backend | Completado |
+| MCH-TT-041-03 | UI seleccion Clip en POS | Frontend | Completado |
+| MCH-TT-041-04 | Manejo de errores de pago | Backend | Completado |
+
+---
+
+### MCH-US-042: Registro de Pagos en Efectivo
+
+**Como** empleado de tienda
+**Quiero** registrar pagos en efectivo con calculo automatico de cambio
+**Para** mantener control preciso de la caja
+
+**Story Points:** 2
+
+**Criterios de Aceptacion:**
+- [CA-042-1] ✅ Seleccion de metodo de pago "Efectivo" en POS
+- [CA-042-2] ✅ Input para monto recibido del cliente
+- [CA-042-3] ✅ Calculo automatico de cambio a devolver
+- [CA-042-4] ✅ Actualizacion de saldo en caja
+- [CA-042-5] ✅ Venta registrada con metodo efectivo
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-042-01 | Logica de calculo de cambio | Backend | Completado |
+| MCH-TT-042-02 | UI pago efectivo en PaymentModal | Frontend | Completado |
+| MCH-TT-042-03 | Integracion con corte de caja | Backend | Completado |
+
+---
+
+### MCH-US-043: Stripe para Suscripciones y OXXO
+
+**Como** sistema
+**Quiero** procesar pagos de suscripciones y OXXO via Stripe
+**Para** habilitar cobros recurrentes y pago en tiendas de conveniencia
+
+**Story Points:** 5
+
+**Criterios de Aceptacion:**
+- [CA-043-1] ✅ Configuracion de Stripe API keys por ambiente
+- [CA-043-2] ✅ Creacion de intenciones de pago (PaymentIntent)
+- [CA-043-3] ✅ Generacion de referencias OXXO con codigo de barras
+- [CA-043-4] ✅ Procesamiento de webhooks Stripe (payment_intent.succeeded)
+- [CA-043-5] ✅ Soporte para pagos recurrentes de suscripciones
+- [CA-043-6] ✅ Confirmacion de pago OXXO en 24-48h via webhook
+
+**Tareas:**
+| ID | Tarea | Tipo | Estado |
+|----|-------|------|--------|
+| MCH-TT-043-01 | Implementar StripeProvider | Backend | Completado |
+| MCH-TT-043-02 | Endpoint crear PaymentIntent | Backend | Completado |
+| MCH-TT-043-03 | Endpoint generar referencia OXXO | Backend | Completado |
+| MCH-TT-043-04 | Webhook Stripe multiproposito | Backend | Completado |
+| MCH-TT-043-05 | Integracion con modulo suscripciones | Backend | Completado |
+| MCH-TT-043-06 | Tests unitarios Stripe | Test | Completado |
+
+---
+
+## Resumen de Story Points
+
+| Historia | SP | Estado |
+|----------|-----|--------|
+| MCH-US-040: Integracion Mercado Pago Point | 3 | Completado |
+| MCH-US-041: Integracion Clip | 3 | Completado |
+| MCH-US-042: Registro de Pagos en Efectivo | 2 | Completado |
+| MCH-US-043: Stripe para Suscripciones y OXXO | 5 | Completado |
+| **TOTAL** | **13** | **100%** |
+
+---
+
+**Ultima actualizacion:** 2026-01-17