diff --git a/docs/design/pantallas-pos.md b/docs/design/pantallas-pos.md new file mode 100644 index 0000000..f7c52d6 --- /dev/null +++ b/docs/design/pantallas-pos.md @@ -0,0 +1,647 @@ +# Nexus POS — Guia de Pantallas para Equipo de Diseno + +**Fecha:** 2026-03-27 +**Proyecto:** Nexus Autoparts — Modulo POS + Inventario +**Tech:** PWA instalable (HTML/CSS/JS) con CSS custom properties para theming + +--- + +## Resumen + +- **10 pantallas** a disenar (7 existentes + 3 pendientes) +- **15 componentes reutilizables** +- **6 estados/variantes** por pantalla +- **Sistema de temas** via CSS variables (cada cliente puede tener su propio tema) + +--- + +## 1. Pantallas Existentes (redisenar) + +### 1.1 Login (PIN Pad) + +**Archivo:** `login.html` +**Usuarios:** Todos los empleados +**Dispositivo:** Desktop + tablet + +**Descripcion:** Pantalla de entrada al sistema. El empleado ingresa un PIN de 4 digitos para identificarse. No hay usuario/contrasena — solo PIN. + +**Elementos:** +- Logo del negocio (configurable por tenant) +- Titulo "Nexus POS" (o nombre del negocio) +- Subtitulo "Ingresa tu PIN" +- 4 dots de progreso (se llenan al ingresar digitos) +- Teclado numerico 3x4: [1-9], [Borrar], [0], [OK] +- Area de mensaje de error ("PIN incorrecto", "Dispositivo bloqueado") +- Los botones deben ser grandes (72px minimo) para uso tactil + +**Interacciones:** +- Auto-submit al ingresar 4 digitos +- Soporte de teclado fisico (0-9, Backspace, Enter) +- Animacion al llenar cada dot +- Shake animation en error + +**Estados:** +- Default (vacio) +- Ingresando (1-3 dots llenos) +- Verificando (spinner o loading) +- Error (mensaje + shake) +- Bloqueado (mensaje de cooldown 15 min) + +--- + +### 1.2 Catalogo + +**Archivo:** `catalog.html` +**Usuarios:** Cajero, Admin, Dueno +**Dispositivo:** Desktop (landscape) + tablet + +**Descripcion:** El inventario del negocio presentado como catalogo navegable. El cajero busca partes aqui y las agrega al carrito. Al terminar, salta al POS para cobrar. + +**Layout:** +``` ++------------------------------------------+--------+ +| [Buscar parte...] [Filtros] [Carrito 3]| | ++------------------------------------------+ | +| Categorias | Marcas | CARRITO | +| | | SIDEBAR | +| +--------+ +--------+ +--------+ | +| | Balatas| | Discos | | Bujias | Item 1 | +| | Bosch | | Brembo | | NGK | Item 2 | +| | $385 | | $720 | | $85 | Item 3 | +| | Stock:8| | Stock:3| | Stock:0| | +| |[+Cart] | |[+Cart] | |[Agot.] | Total | +| +--------+ +--------+ +--------+ [Cobrar]| ++------------------------------------------+--------+ +``` + +**Elementos:** +- Barra de busqueda con icono de barcode scanner +- Chips de filtro: Categoria, Marca (fabricante), Solo en stock +- Grid de tarjetas de producto: + - Imagen (placeholder si no hay) + - Nombre de la parte + - Numero de parte (font mono) + - Marca/fabricante + - Precio (segun tier del empleado) + - Badge de stock: verde (OK), amarillo (bajo minimo), rojo (agotado) + - Boton "Agregar al carrito" +- Paginacion +- Carrito sidebar (slide-in desde la derecha): + - Lista de items con cantidad editable + - Subtotal por item + - Subtotal, IVA, Total + - Boton "Ir a cobrar" (prominente) + - Boton "Vaciar carrito" +- Seccion "Buscar en bodegas" (cuando hay internet): + - Disponibilidad externa con precio y bodega + +**Interacciones:** +- F1 enfoca busqueda +- Enter en resultado agrega al carrito +- Barcode scanner: detecta entrada rapida + Enter +- Click en tarjeta abre detalle, doble-click agrega + +--- + +### 1.3 Punto de Venta (POS) + +**Archivo:** `pos.html` +**Usuarios:** Cajero, Admin, Dueno +**Dispositivo:** Desktop (landscape) — pantalla principal de trabajo + +**Descripcion:** La pantalla de cobro. Aqui se procesan ventas, cotizaciones y apartados. Optimizada para velocidad — todo operable por teclado. + +**Layout:** +``` ++----------------------------+-----------------------------+ +| [F1 Buscar parte...] | Cliente: Taller Juarez | +| [F2 Buscar cliente...] | RFC: TAJJ850101XXX | +| | Credito: $15,000 disp. | +| Resultados de busqueda: | Vehiculo: Suburban 2018 | +| - Balatas Bosch $385 [+] | Ult. compra: filtro 3 meses | +| - Balatas TRW $310 [+] |-----------------------------| +| | # Parte Cant Precio ST| +| | 1 Balatas 2 $385 $770| +| | 2 Discos 1 $720 $720| +| | 3 Liquido 1 $95 $95| +| |-----------------------------| +| | Subtotal: $1,585.00| +| | Descuento (5%): -$79.25| +| | IVA 16%: $241.12| +| | TOTAL: $1,746.87| +| |-----------------------------| +| Si tiene permiso: | [F3 Cobrar] [F4 Cotizacion] | +| Costo: $220 Margen: 43% | [Apartado] [Credito] | ++----------------------------+-----------------------------+ +``` + +**Elementos principales:** +- Panel izquierdo: + - Busqueda de partes (F1) + - Busqueda de cliente (F2) con autocompletado + - Lista de resultados con boton agregar +- Panel derecho: + - Banner de cliente (nombre, RFC, credito disponible, vehiculo, ultima compra) + - Tabla de items de la venta: + - Numero de parte + - Nombre + - Cantidad (editable inline) + - Precio unitario + - Descuento % (editable, valida contra maximo del empleado) + - Subtotal + - **Si tiene permiso pos.view_cost:** columnas de Costo y Margen% (ocultas para cajeros) + - Barra de totales: Subtotal, Descuento, IVA, TOTAL (fuente grande mono) + - Botones de accion: + - [F3] Cobrar (primario, prominente) + - [F4] Cotizacion + - Apartado + - Credito + - [F5] Ultima venta + - [F6] Abrir cajon + +**Modal de pago (al presionar F3):** +``` ++--------------------------------+ +| COBRAR — Total: $1,746.87 | +|--------------------------------| +| [Efectivo] [Transfer] [Tarjeta] [Mixto] | +| | +| Efectivo: | +| Recibido: [$ 2,000.00] | +| Cambio: $253.13 | +| | +| [ ] Facturar (CFDI) | +| | +| [Confirmar pago] | ++--------------------------------+ +``` + +- Tab Efectivo: campo de monto recibido, calculo automatico de cambio +- Tab Transferencia: campo de referencia bancaria +- Tab Tarjeta: campo de referencia de terminal +- Tab Mixto: multiples campos (ej: $1,000 efectivo + $746.87 transferencia) +- Checkbox "Facturar" (genera CFDI) + +**Preview de ticket (despues de cobrar):** +- Layout termico 58/80mm +- Datos del negocio (RFC, direccion) +- Folio de venta +- Items con cantidad, precio, subtotal +- Totales +- Forma de pago +- Fecha y hora +- Boton imprimir / PDF + +**Atajos de teclado (mostrar en footer o tooltip):** +``` +F1=Buscar F2=Cliente F3=Cobrar F4=Cotizacion +F5=Ult.Venta F6=Cajon +/-=Cantidad *=Descuento +Enter=Agregar Delete=Quitar Esc=Cerrar modal +Flechas=Navegar items +``` + +--- + +### 1.4 Inventario + +**Archivo:** `inventory.html` +**Usuarios:** Almacenista, Admin, Dueno +**Dispositivo:** Desktop + tablet + +**Descripcion:** Gestion completa del inventario. Tabs para cada operacion. + +**Tabs:** + +**Tab 1 — Productos:** +- Tabla: parte#, nombre, marca, stock, costo, precio1/2/3, ubicacion +- Busqueda por nombre/numero +- Boton "Nuevo producto" (abre modal) +- Click en row abre detalle/edicion +- Badge de stock por colores + +**Tab 2 — Entradas (Compras):** +- Formulario: seleccionar producto, cantidad, costo unitario, # factura proveedor +- Tabla de entradas recientes + +**Tab 3 — Ajustes:** +- Formulario: seleccionar producto, cantidad (+/-), razon (obligatorio) +- Tabla de ajustes recientes + +**Tab 4 — Transferencias:** +- Formulario: producto, sucursal origen, sucursal destino, cantidad +- Tabla de transferencias recientes + +**Tab 5 — Toma Fisica:** +- Dos fases: + 1. Captura: tabla editable (producto → cantidad contada) + 2. Revision: comparar esperado vs contado, mostrar diferencias + 3. Boton "Aprobar ajustes" + +**Tab 6 — Alertas:** +- Lista con severidad: + - Rojo: stock en cero + - Amarillo: bajo minimo + - Azul: sobre maximo + +**Tab 7 — Reportes:** +- Botones para cada reporte: + - Inventario valorizado + - Clasificacion ABC + - Sin movimiento (>60 dias) + - Stock bajo minimo + - Comparativo sucursales + +**Modal Crear/Editar Producto:** +- Numero de parte (obligatorio) +- Nombre (obligatorio) +- Marca/fabricante +- Unidad (PZA, JGO, LT, etc.) +- Costo +- Precio 1 (mostrador), Precio 2 (taller), Precio 3 (mayoreo) +- Tasa de impuesto (default 16%) +- Stock minimo y maximo +- Ubicacion en almacen (ej: "Pasillo 3, Anaquel B") +- Codigo de barras (auto-generado o manual) +- Imagen +- Stock inicial + +--- + +### 1.5 Clientes + +**Archivo:** `customers.html` +**Usuarios:** Admin, Dueno, Contador +**Dispositivo:** Desktop + +**Descripcion:** Gestion de clientes con informacion fiscal, credito y vehiculos. + +**Layout:** +``` ++---------------------------+-------------------------+ +| [Buscar cliente...] | | +| [+ Nuevo] | PANEL DE DETALLE | +| | (slide-in) | +| Nombre RFC Tier | | +| Taller J. TAJJ... Taller | Nombre: Taller Juarez | +| Mech.Exp MEEX... Mostrad| RFC: TAJJ850101XXX | +| AutoServ AUTO... Mayoreo| Credito: $10,000 | +| | Saldo: $3,200 | +| | Disponible: $6,800 | +| | | +| | Vehiculos: | +| | - Suburban 2018 | +| | - Tsuru 2015 | +| | | +| | Compras recientes: | +| | - Balatas $770 (3d) | +| | - Filtro $120 (30d) | +| | | +| | [Estado de cuenta] | ++---------------------------+-------------------------+ +``` + +**Modal Estado de Cuenta:** +``` ++----------------------------------------------+ +| Estado de Cuenta — Taller Juarez | +|----------------------------------------------| +| Fecha | Concepto | Cargo | Abono | Saldo | +| 01-abr | Factura | 5,800 | | 5,800 | +| 08-abr | Pago | | 3,000 | 2,800 | +| 15-abr | Factura | 2,300 | | 5,100 | +|----------------------------------------------| +| Saldo actual: $5,100 | ++----------------------------------------------+ +``` + +**Modal Crear/Editar Cliente:** +- Nombre (obligatorio) +- RFC (13 caracteres) +- Razon social +- Regimen fiscal (catalogo SAT) +- Uso CFDI (catalogo SAT) +- Codigo postal +- Email, telefono, direccion +- Tier de precio: Mostrador (1), Taller (2), Mayoreo (3) +- Limite de credito +- Vehiculos (JSON array): marca, modelo, ano, VIN, placas + +--- + +### 1.6 Facturacion + +**Archivo:** `invoicing.html` +**Usuarios:** Admin, Dueno, Contador +**Dispositivo:** Desktop + +**Descripcion:** Cola de facturacion electronica (CFDI). Muestra el status de cada factura y permite procesar, cancelar, y ver XML. + +**Elementos:** +- Tarjetas de resumen: Pendientes, Timbradas, Fallidas, Canceladas +- Filtros: status, fecha +- Tabla de cola CFDI: + - Folio provisional + - Tipo (Ingreso/Egreso/Pago) + - Cliente + - Total + - Status badge: + - Azul: Pending + - Amarillo: Sending + - Verde: Stamped + - Rojo: Failed + - Gris: Cancelled + - UUID fiscal (si timbrada) + - Acciones: Ver detalle, Cancelar +- Boton "Procesar cola" (prominente) + +**Modal Detalle CFDI:** +- XML preview (syntax highlighted) +- Datos del comprobante +- UUID, sello, cadena original (si timbrado) + +**Modal Cancelacion:** +- Motivo SAT (selector): + - 01: Con errores con relacion + - 02: Con errores sin relacion + - 03: No se llevo a cabo + - 04: Operacion nominativa +- Campo UUID de sustitucion (solo si motivo 01) +- Boton confirmar cancelacion + +--- + +### 1.7 Contabilidad + +**Archivo:** `accounting.html` +**Usuarios:** Contador, Dueno +**Dispositivo:** Desktop + +**Descripcion:** Modulo contable con catalogo de cuentas, polizas automaticas, y reportes financieros. + +**Tabs:** + +**Tab 1 — Catalogo de Cuentas:** +- Arbol colapsable con indentacion: + ``` + v 100 Activo + v 110 Caja + v 111 Bancos + v 120 Clientes + v 130 Inventarios + v 200 Pasivo + v 210 Proveedores + v 220 IVA Trasladado + ``` +- Cada cuenta muestra: codigo, nombre, saldo actual +- Boton "Nueva subcuenta" +- Cuentas de sistema (is_system) no editables + +**Tab 2 — Polizas:** +- Filtros: fecha desde/hasta, tipo (ingreso/egreso/diario) +- Tabla: #poliza, fecha, tipo, descripcion, cargo total, abono total +- Click en poliza abre detalle con lineas +- Boton "Nueva poliza manual" +- Badge "Auto" para polizas generadas automaticamente + +**Tab 3 — Balanza de Comprobacion:** +- Selector: ano + mes +- Tabla: cuenta, saldo inicial, cargos, abonos, saldo final +- Totales al fondo (deben cuadrar) + +**Tab 4 — Estado de Resultados:** +- Selector de periodo +- Ingresos (ventas) +- (-) Costo de ventas +- = Utilidad bruta +- (-) Gastos operativos +- = Utilidad operativa + +**Tab 5 — Balance General:** +- Activos (bancos, clientes, inventarios) +- Pasivos (proveedores, IVA) +- Capital (capital social + resultado del ejercicio) +- Activo = Pasivo + Capital (debe cuadrar) + +**Tab 6 — Antiguedad de Saldos:** +- Tabla por cliente: + - Cliente, Corriente, 1-30 dias, 31-60 dias, 61-90 dias, 90+ dias +- Highlight en rojo si >90 dias + +**Tab 7 — Periodos Fiscales:** +- Tabla: ano, mes, status (abierto/cerrado), cerrado por, fecha cierre +- Boton "Cerrar periodo" (solo dueno) +- Confirmacion antes de cerrar + +--- + +## 2. Pantallas Pendientes (por construir) + +### 2.1 Dashboard del Dueno + +**Archivo:** `dashboard.html` +**Usuarios:** Dueno +**Dispositivo:** **Movil (primary)** + Desktop + +**Descripcion:** Vista ejecutiva del negocio. El dueno lo ve en su celular. + +**Elementos movil:** +``` ++-------------------------+ +| Refaccionaria Lopez | +| Hoy, 15 abril 2026 | +|-------------------------| +| Ventas hoy | +| $45,200 +12% vs ayer | +| [===========----] 75% | +| Meta: $60,000 | +|-------------------------| +| Cajas activas | +| Caja 1 — Maria | +| 23 ventas | $28,400 | +| Margen: 34% | +| | +| Caja 2 — Pedro | +| 15 ventas | $16,800 | +| Margen: 29% ⚠ | +|-------------------------| +| Alertas (3) | +| ! Descuento $500 Maria | +| ! Bujias NGK: stock 3 | +| ! Balatas: agotado | +|-------------------------| +| Esta semana | +| L M M J V S D | +| 42 38 45 45 - - - | +| (miles) | ++-------------------------+ +``` + +**Para multi-sucursal:** +- Toggle entre sucursales o vista consolidada +- Comparativo entre sucursales + +--- + +### 2.2 Configuracion + +**Archivo:** `config.html` +**Usuarios:** Dueno, Admin +**Dispositivo:** Desktop + +**Tabs:** + +**Tab 1 — Datos del Negocio:** +- Nombre, RFC, razon social, regimen fiscal +- Direccion, codigo postal +- Logo +- Link a Horux para CSD (credenciales SAT) + +**Tab 2 — Sucursales:** +- Lista de sucursales (nombre, direccion, telefono) +- Crear/editar sucursal + +**Tab 3 — Empleados:** +- Lista: nombre, email, rol, sucursal, descuento max, activo +- Crear/editar empleado con asignacion de rol y permisos +- Roles: Dueno, Admin, Cajero, Almacenista, Contador + +**Tab 4 — Tema:** +- Selector de tema predefinido +- Preview en vivo +- (Los temas los define el equipo de diseno) + +--- + +### 2.3 Reportes + +**Archivo:** `reports.html` +**Usuarios:** Dueno, Admin, Contador +**Dispositivo:** Desktop + +**Secciones:** + +**Ventas:** +- Ventas por periodo (dia/semana/mes/ano) con grafica +- Ventas por empleado +- Ventas por categoria +- Ventas por cliente +- Ticket promedio y tendencia + +**Inventario:** +- Inventario valorizado +- Clasificacion ABC +- Productos sin movimiento +- Stock bajo minimo +- Comparativo entre sucursales + +**Financieros:** +- (Links a Contabilidad: balanza, estado de resultados, balance) +- Flujo de efectivo +- Cortes de caja historicos + +--- + +## 3. Componentes Reutilizables + +El equipo de diseno debe crear estos componentes como sistema de diseno: + +| # | Componente | Usado en | Notas | +|---|-----------|----------|-------| +| 1 | **PIN Pad** | Login | Teclado 3x4, dots de progreso, botones grandes | +| 2 | **Barra de busqueda** | Catalogo, POS, Inventario, Clientes | Con icono scanner, debounce 300ms | +| 3 | **Carrito sidebar** | Catalogo | Slide-in derecha, items con qty editable | +| 4 | **Modal de pago** | POS | 4 tabs: Efectivo, Transferencia, Tarjeta, Mixto | +| 5 | **Selector de cliente** | POS | Autocompletado dropdown, banner con vehiculo | +| 6 | **Badge de stock** | Catalogo, Inventario | Verde=OK, Amarillo=bajo, Rojo=agotado | +| 7 | **Badge de status CFDI** | Facturacion | 5 colores segun estado | +| 8 | **Tabla paginada** | Todas | Header sticky, rows hover, paginacion, busqueda | +| 9 | **Modal generico** | Todas | Header, body scrollable, footer con acciones | +| 10 | **Panel deslizante** | Clientes | Slide-in lateral, cierra con Esc o click fuera | +| 11 | **Ticket termico** | POS | Layout 58/80mm, monospaciado, logo arriba | +| 12 | **Arbol colapsable** | Contabilidad | Indentacion, expand/collapse, iconos | +| 13 | **Tabs de navegacion** | Inventario, Contabilidad | Horizontal, badge con conteo | +| 14 | **Chips de filtro** | Catalogo | Toggle on/off, multiples activos | +| 15 | **Toast/notificacion** | Todas | Exito (verde), Error (rojo), Info (azul), Warning (amarillo) | +| 16 | **Tarjeta de metrica** | Dashboard | Numero grande, label, tendencia (flecha up/down) | +| 17 | **Grafica de barras** | Dashboard, Reportes | Barras verticales con labels | +| 18 | **Calculadora de cambio** | Modal de pago | Input monto, muestra cambio en tiempo real | +| 19 | **Selector de periodo** | Contabilidad, Reportes | Ano + Mes dropdowns | +| 20 | **Etiqueta codigo barras** | Inventario | Formato imprimible para impresora de etiquetas | + +--- + +## 4. Estados y Variantes + +Cada pantalla debe disenarse en estos estados: + +| Estado | Visual | Donde | +|--------|--------|-------| +| **Default** | Contenido normal | Todas | +| **Vacio** | Ilustracion + texto "No hay datos" + CTA | Catalogo, Clientes, Inventario | +| **Cargando** | Skeleton placeholders o spinner | Tablas, listas, reportes | +| **Error** | Toast rojo con mensaje + retry | Fallas de API | +| **Sin conexion** | Banner amarillo "Modo offline — funciones limitadas" | Header global | +| **Exito** | Toast verde "Venta completada" / "Pago registrado" | Post-accion | +| **Confirmacion** | Modal "Estas seguro?" con motivo | Cancelar venta, cerrar caja, ajustar stock | +| **Permiso denegado** | Seccion oculta o deshabilitada | Costos/margen para cajeros, precios para almacenistas | + +--- + +## 5. Sistema de Temas (CSS Variables) + +Cada tenant puede tener su propio tema. El equipo de diseno define los valores: + +```css +:root[data-theme="default"] { + /* Colores principales */ + --color-primary: #1a73e8; + --color-secondary: #5f6368; + --color-accent: #ff6b35; + + /* Fondos */ + --color-bg: #ffffff; + --color-surface: #f8f9fa; + --color-surface-hover: #e8eaed; + + /* Texto */ + --color-text: #202124; + --color-text-secondary: #5f6368; + --color-text-muted: #9aa0a6; + + /* Bordes */ + --color-border: #dadce0; + + /* Semanticos */ + --color-success: #34a853; + --color-warning: #f9ab00; + --color-error: #ea4335; + --color-info: #4285f4; + + /* Tipografia */ + --font-display: 'Sora', sans-serif; + --font-body: 'Plus Jakarta Sans', sans-serif; + --font-mono: 'JetBrains Mono', monospace; + + /* Forma */ + --radius: 8px; + --radius-lg: 12px; + --shadow: 0 1px 3px rgba(0,0,0,0.12); + --shadow-lg: 0 4px 12px rgba(0,0,0,0.15); +} +``` + +**Variantes sugeridas a disenar:** +- Light (default) +- Dark +- High contrast (accesibilidad) + +--- + +## 6. Notas Tecnicas para el Equipo + +- **Responsive:** Desktop-first. POS y Catalogo en landscape. Dashboard movil-first. +- **Impresion:** Ticket termico necesita CSS `@media print` especifico para 58mm y 80mm. +- **Offline:** Mostrar indicador visual cuando no hay conexion. Ocultar features que requieren internet (buscar en bodegas). +- **Permisos:** Algunas columnas/secciones se ocultan segun el rol del empleado. Disenar con y sin esas columnas. +- **F-keys:** El POS es operable 100% por teclado. Los shortcuts deben ser visibles pero no intrusivos (tooltips o footer). +- **Barcode scanner:** El scanner USB escribe caracteres rapido + Enter. No requiere UI especial, solo que el campo de busqueda este enfocado.