Autoparts-DB/docs/plans/2026-03-02-pos-cuentas-design.md

Punto de Venta + Cuentas por Cobrar — Diseño

Resumen

Sistema de punto de venta integrado al catálogo Nexus Autoparts con:

• Ventas de partes OEM y aftermarket
• Facturación con datos fiscales (RFC, IVA, folio consecutivo)
• Cuentas a crédito para clientes frecuentes
• Pagos: abonos parciales y pago al corte
• Precios calculados por costo + margen configurable

Tablas nuevas

customers

Columna	Tipo	Descripción
id_customer	SERIAL PK
name	VARCHAR(200)	Nombre del cliente
rfc	VARCHAR(13)	RFC fiscal
business_name	VARCHAR(300)	Razón social
email	VARCHAR(200)
phone	VARCHAR(20)
address	TEXT	Dirección fiscal
credit_limit	DECIMAL(12,2)	Límite de crédito
balance	DECIMAL(12,2) DEFAULT 0	Saldo actual (lo que debe)
payment_terms	INTEGER DEFAULT 30	Días de crédito
active	BOOLEAN DEFAULT TRUE
created_at	TIMESTAMP DEFAULT NOW()

invoices

Columna	Tipo	Descripción
id_invoice	SERIAL PK
customer_id	INTEGER FK customers
folio	VARCHAR(20) UNIQUE	Folio consecutivo (ej: NX-000001)
date_issued	TIMESTAMP DEFAULT NOW()	Fecha emisión
subtotal	DECIMAL(12,2)	Sin IVA
tax_rate	DECIMAL(5,4) DEFAULT 0.16	Tasa IVA
tax_amount	DECIMAL(12,2)	Monto IVA
total	DECIMAL(12,2)	Total con IVA
amount_paid	DECIMAL(12,2) DEFAULT 0	Total abonado
status	VARCHAR(20) DEFAULT 'pending'	pending/partial/paid/cancelled
notes	TEXT
created_at	TIMESTAMP DEFAULT NOW()

invoice_items

Columna	Tipo	Descripción
id_invoice_item	SERIAL PK
invoice_id	INTEGER FK invoices
part_id	INTEGER FK parts (nullable)	Pieza OEM
aftermarket_id	INTEGER FK aftermarket_parts (nullable)	Pieza aftermarket
description	VARCHAR(500)	Descripción de la línea
quantity	INTEGER DEFAULT 1
unit_cost	DECIMAL(12,2)	Costo unitario
margin_pct	DECIMAL(5,2)	Margen % aplicado
unit_price	DECIMAL(12,2)	Precio de venta unitario
line_total	DECIMAL(12,2)	quantity * unit_price

payments

Columna	Tipo	Descripción
id_payment	SERIAL PK
customer_id	INTEGER FK customers
invoice_id	INTEGER FK invoices (nullable)	Si aplica a factura específica
amount	DECIMAL(12,2)	Monto del pago
payment_method	VARCHAR(20)	efectivo/transferencia/cheque/tarjeta
reference	VARCHAR(100)	# referencia del pago
date_payment	TIMESTAMP DEFAULT NOW()
notes	TEXT
created_at	TIMESTAMP DEFAULT NOW()

Columnas nuevas en tablas existentes

parts

• cost_usd DECIMAL(12,2) — costo de la pieza

aftermarket_parts

• cost_usd DECIMAL(12,2) — costo de la pieza aftermarket

Configuración

• Margen default: 30% (configurable)
• IVA: 16%
• Folio format: NX-XXXXXX (consecutivo)

Páginas web nuevas

/pos — Punto de Venta

• Selector de cliente (buscador + crear nuevo)
• Buscador de partes (OEM y aftermarket)
• Carrito con líneas editables (costo, margen, precio)
• Botón facturar → genera factura con folio

/cuentas — Cuentas por Cobrar

• Lista de clientes con saldos
• Detalle de cliente: facturas pendientes, historial pagos
• Registrar pago/abono
• Estado de cuenta imprimible

Endpoints API nuevos

Clientes

• GET /api/pos/customers — listar clientes
• GET /api/pos/customers/:id — detalle cliente con saldo
• POST /api/pos/customers — crear cliente
• PUT /api/pos/customers/:id — editar cliente

Facturas

• GET /api/pos/invoices — listar facturas (filtros: cliente, status, fecha)
• GET /api/pos/invoices/:id — detalle factura con líneas
• POST /api/pos/invoices — crear factura (con líneas)
• PUT /api/pos/invoices/:id/cancel — cancelar factura

Pagos

• GET /api/pos/payments — listar pagos
• POST /api/pos/payments — registrar pago/abono
• GET /api/pos/customers/:id/statement — estado de cuenta

Flujos

Venta

1. Seleccionar/crear cliente
2. Buscar partes → agregar al carrito
3. Ajustar margen si necesario
4. Facturar → se crea invoice + items, se suma al balance del cliente

Pago

1. Buscar cliente → ver saldo y facturas pendientes
2. Registrar pago (monto, método, referencia)
3. Se aplica a factura o como abono general
4. Se actualiza balance del cliente