michangarrito/docs/01-epicas/MCH-004-punto-venta.md

id	type	title	code	status	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-004	Epic	MCH-004: Punto de Venta Basico	MCH-004	Completado	1	P0	21	2026-01-06	2026-01-17	4.0.1	blocks depends_on MCH-005 MCH-008 MCH-009 MCH-001 MCH-002 MCH-003

MCH-004: Punto de Venta Basico

Metadata

• Codigo: MCH-004
• Fase: 1 - MVP Core
• Prioridad: P0
• Estado: Completado
• Story Points: 21
• 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

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
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

• Grid de productos carga correctamente
• Carrito funciona (agregar/quitar/cantidad)
• Descuentos se aplican correctamente
• Pago en efectivo con cambio
• Ticket se genera con todos los datos
• 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-17