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

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

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