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

---
id: EPIC-MCH-004
type: Epic
title: "MCH-004: Punto de Venta Basico"
code: MCH-004
status: Completado
phase: 1
priority: P0
story_points: 21
created_at: 2026-01-06
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"]
---

# 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

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