docs: documentacion completa — README, guia de uso, instalacion, API POS

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/GUIA-DE-USO.md

@@ -0,0 +1,377 @@
+# Guia de Uso -- Nexus Autoparts POS
+
+Manual de usuario para el sistema de Punto de Venta Nexus Autoparts.
+
+---
+
+## 1. Acceso al sistema
+
+1. Abrir el navegador e ir a `http://[IP]:5001/pos/login`
+2. Se muestra la lista de empleados del tenant
+3. Seleccionar tu usuario
+4. Escribir tu PIN de 4 digitos
+5. El sistema te lleva al dashboard o al POS segun tu rol
+
+**Primer acceso:** El PIN del dueno se configura al crear el tenant. El dueno puede crear empleados desde Configuracion.
+
+**Seguridad:**
+- 5 intentos fallidos por minuto maximo
+- 10 intentos fallidos bloquean el dispositivo por 15 minutos
+- Cada sesion genera un token JWT con duracion de 8 horas
+
+---
+
+## 2. Navegacion
+
+- **Sidebar izquierdo**: contiene todas las secciones del sistema
+- **Toggle de tema**: icono de luna/sol en la parte superior del sidebar para cambiar entre tema Industrial (oscuro) y Moderno (claro)
+- **Logout**: boton en la parte inferior del sidebar
+- **Breadcrumbs**: en el catalogo, muestran la ruta de navegacion actual
+
+Las secciones visibles dependen del rol:
+| Seccion | Dueno | Admin | Cajero | Almacenista | Contador |
+|---------|-------|-------|--------|-------------|----------|
+| Dashboard | Si | Si | No | No | No |
+| Catalogo | Si | Si | Si | Si | Si |
+| POS | Si | Si | Si | No | No |
+| Inventario | Si | Si | No | Si | No |
+| Clientes | Si | Si | Si | No | Si |
+| Facturacion | Si | Si | No | No | Si |
+| Contabilidad | Si | No | No | No | Si |
+| Reportes | Si | Si | No | No | Si |
+| Configuracion | Si | Si | No | No | No |
+
+---
+
+## 3. Catalogo
+
+El catalogo conecta con la base de datos maestra TecDoc (1.5M+ partes OEM) y muestra stock local.
+
+### Navegacion por vehiculo
+
+1. **Marca** -- seleccionar marca del vehiculo (Toyota, Nissan, Ford, etc.)
+2. **Modelo** -- seleccionar modelo (Corolla, Sentra, F-150, etc.)
+3. **Ano** -- seleccionar ano del vehiculo
+4. **Motor** -- seleccionar motorizacion
+5. **Categoria** -- categoria de partes (Frenos, Motor, Suspension, etc.)
+6. **Subcategoria** -- grupo especifico (Pastillas, Discos, Balatas, etc.)
+7. **Partes** -- lista de partes con numero OEM, precio y stock
+
+### Busqueda inteligente
+
+- Escribir en la barra de busqueda un **numero de parte** (ej. "04465-02220") o **texto** (ej. "pastillas corolla")
+- El sistema busca en partes OEM, aftermarket y cross-references
+- Resultados muestran stock local y alternativas disponibles
+
+### Panel de detalle
+
+Al seleccionar una parte se abre un panel lateral con:
+- Numero de parte OEM y descripcion
+- **Stock local**: cantidad en la sucursal actual
+- **Stock en bodegas**: disponibilidad en otras sucursales
+- **Alternativas**: partes aftermarket equivalentes con precios
+- **Cross-references**: numeros alternos de otras marcas
+
+### Carrito
+
+- Hacer clic en "Agregar" para anadir partes al carrito
+- El carrito muestra cantidad, precio unitario y subtotal
+- Boton **"Ir a cobrar"** salta directamente al POS con las partes cargadas
+
+### Modo offline
+
+Cuando no hay conexion a internet:
+- Solo se muestra el inventario local (partes en la sucursal)
+- La navegacion TecDoc no esta disponible
+- Al restaurar la conexion, se sincronizan las operaciones pendientes
+
+---
+
+## 4. Punto de Venta (POS)
+
+Pantalla principal de cobro con atajos de teclado para operacion rapida.
+
+### Operacion basica
+
+1. **Buscar parte** (F1): escribir numero de parte o descripcion
+2. **Seleccionar cliente** (F2): buscar por nombre, RFC o telefono. Si no se selecciona, se vende a "Publico General"
+3. Las partes se agregan a la lista con cantidad, precio y descuento
+4. **Cobrar** (F3): abrir dialogo de pago
+
+### Metodos de pago
+
+| Metodo | Descripcion |
+|--------|-------------|
+| Efectivo | Calcula cambio automaticamente |
+| Transferencia | Registra referencia bancaria |
+| Tarjeta | Registra numero de autorizacion |
+| Mixto | Combina dos o mas metodos |
+
+### Tipos de operacion
+
+- **Venta directa** (F3): cobro inmediato, descuenta inventario
+- **Cotizacion** (F4): guarda sin cobrar, se puede convertir a venta despues
+- **Apartado**: reserva partes con pago parcial (enganche minimo configurable). El cliente hace pagos subsecuentes hasta completar
+- **Credito**: venta a cuenta del cliente (requiere cliente con credito autorizado y limite suficiente)
+
+### Atajos de teclado
+
+| Tecla | Accion |
+|-------|--------|
+| F1 | Buscar parte |
+| F2 | Seleccionar cliente |
+| F3 | Cobrar |
+| F4 | Cotizacion |
+| F5 | Apartado |
+| F6 | Ultimo ticket |
+| + / - | Aumentar/disminuir cantidad |
+| * | Editar cantidad directa |
+| Enter | Confirmar |
+| Delete | Eliminar linea |
+| Escape | Cancelar / cerrar dialogo |
+
+### Margen y costos
+
+- La columna de **costo** y **margen** solo es visible para roles Dueno y Admin
+- El cajero solo ve precio de venta
+
+---
+
+## 5. Inventario
+
+Gestion completa de productos y stock.
+
+### Tab Productos
+
+- **Ver**: lista paginada con busqueda por nombre, SKU o codigo de barras
+- **Crear**: nuevo producto con nombre, SKU, codigo de barras, costo, precios (mostrador/taller/mayoreo), stock minimo, stock maximo, ubicacion en almacen
+- **Editar**: modificar datos del producto
+
+### Tab Entradas (Compras)
+
+- Registrar compra a proveedor
+- Campos: proveedor, factura del proveedor, lista de productos con cantidad y costo
+- El stock se incrementa automaticamente
+- Se genera movimiento en el historial
+
+### Tab Ajustes
+
+- Ajuste manual de inventario (merma, error de conteo, dano, etc.)
+- **Requiere motivo**: el sistema no permite ajustes sin explicacion
+- Genera registro en auditoria con usuario, fecha y motivo
+
+### Tab Transferencias
+
+- Mover productos entre sucursales
+- Origen y destino, lista de productos con cantidad
+- Descuenta del origen y suma al destino
+- Rastrea estado: pendiente, en transito, recibida
+
+### Tab Toma Fisica
+
+1. **Iniciar conteo**: genera documento de toma fisica
+2. **Capturar conteos**: registrar cantidades fisicas por producto
+3. **Comparar**: el sistema muestra diferencias vs stock teorico
+4. **Aprobar**: aplica los ajustes automaticamente
+
+### Tab Alertas
+
+- **Stock en cero**: productos sin existencia
+- **Bajo minimo**: productos por debajo del punto de reorden
+- **Sobre maximo**: productos con sobreinventario
+
+### Tab Reportes de Inventario
+
+| Reporte | Descripcion |
+|---------|-------------|
+| Valorizacion | Valor total del inventario a costo y a precio de venta |
+| ABC | Clasificacion de productos por volumen de venta (A=80%, B=15%, C=5%) |
+| Sin movimiento | Productos sin venta en X dias |
+| Stock bajo | Productos por debajo del minimo |
+| Comparativo sucursales | Stock del mismo producto en todas las sucursales |
+
+---
+
+## 6. Clientes
+
+### Crear cliente
+
+Campos principales:
+- Nombre / Razon social
+- RFC (para facturacion)
+- Regimen fiscal SAT
+- Codigo postal fiscal
+- Uso de CFDI (ej. G03 Gastos en general)
+- Telefono, email
+- Direccion
+
+### Tiers de precio
+
+Cada cliente pertenece a un tier que determina el precio automatico:
+
+| Tier | Descripcion |
+|------|-------------|
+| Mostrador | Precio publico (default) |
+| Taller | Descuento para talleres mecanicos |
+| Mayoreo | Mejor precio para compradores de volumen |
+
+### Credito
+
+- Asignar limite de credito al cliente
+- El sistema valida que el saldo no exceda el limite al crear ventas a credito
+- **Estado de cuenta**: muestra compras, pagos y saldo pendiente
+- **Registrar pago**: abono parcial o total a la cuenta
+
+### Vehiculos
+
+- Asociar vehiculos al cliente (marca, modelo, ano, motor, placas, VIN)
+- Facilita la busqueda de partes en futuras visitas
+
+### Historial
+
+- Ver todas las compras del cliente con fecha, total y estatus
+
+---
+
+## 7. Facturacion CFDI
+
+### Generar factura
+
+1. Ir a Facturacion
+2. Seleccionar una venta completada
+3. Verificar datos fiscales del cliente (RFC, razon social, regimen, CP, uso CFDI)
+4. Generar factura -- se crea el XML CFDI 4.0
+
+### Tipos de comprobante
+
+| Tipo | Uso |
+|------|-----|
+| Ingreso | Factura de venta normal |
+| Egreso | Nota de credito (devolucion/cancelacion) |
+| Pago | Complemento de pago para ventas a credito (PPD) |
+
+### Cola de timbrado
+
+- Las facturas se encolan para envio al PAC (Horux)
+- El PAC firma el XML con el CSD del contribuyente
+- Estado: pendiente, timbrada, error, cancelada
+- Reintentar facturas con error
+
+### Cancelacion
+
+- Seleccionar factura a cancelar
+- Indicar motivo SAT:
+  - 01: Comprobante emitido con errores con relacion
+  - 02: Comprobante emitido con errores sin relacion
+  - 03: No se llevo a cabo la operacion
+  - 04: Operacion nominativa relacionada en una factura global
+- Si el motivo es 01, indicar el UUID de la factura sustituta
+
+### PDF
+
+- Descargar representacion impresa (PDF) de cualquier factura timbrada
+
+---
+
+## 8. Contabilidad
+
+### Polizas automaticas
+
+Cada venta genera automaticamente una poliza contable:
+- Cargo a Caja/Bancos (por el monto cobrado)
+- Abono a Ventas (por el subtotal)
+- Abono a IVA Trasladado (por el impuesto)
+- Cargo a Costo de Ventas / Abono a Inventario (por el costo)
+
+### Catalogo de cuentas
+
+- Basado en el catalogo SAT
+- Estructura jerarquica: Activo, Pasivo, Capital, Ingresos, Costos, Gastos
+- Cada cuenta tiene codigo SAT, nombre, tipo (deudora/acreedora), nivel
+
+### Reportes financieros
+
+| Reporte | Descripcion |
+|---------|-------------|
+| Balanza de comprobacion | Saldos iniciales + movimientos del periodo + saldos finales |
+| Estado de resultados | Ingresos - Costos - Gastos = Utilidad del periodo |
+| Balance general | Activo = Pasivo + Capital a una fecha |
+| Antiguedad de saldos | Cuentas por cobrar agrupadas por dias de atraso (0-30, 31-60, 61-90, 90+) |
+
+### Periodos fiscales
+
+- Ver periodos mensuales con estado (abierto/cerrado)
+- Cerrar periodo: bloquea movimientos en ese mes. Esta accion es irreversible.
+
+---
+
+## 9. Caja Registradora
+
+### Flujo diario
+
+1. **Abrir caja**: indicar numero de caja y fondo inicial en efectivo
+2. **Operar**: las ventas se registran automaticamente en la caja abierta
+3. **Movimientos**: registrar entradas (cobros externos, cambio) o salidas (gastos menores, compras) de efectivo con motivo
+4. **Corte X**: consulta de ventas y movimientos sin cerrar la caja
+5. **Corte Z**: cierre de caja con conteo final. El sistema calcula la diferencia entre lo esperado y lo contado
+
+### Multi-caja
+
+- Cada cajero abre su propia sesion de caja
+- Un empleado solo puede tener una caja abierta a la vez
+- El numero de caja identifica la caja fisica (1, 2, 3...)
+
+### Historial
+
+- Consultar cortes anteriores con detalle de ventas, movimientos y diferencias
+
+### Resumen diario
+
+- Vista consolidada de todas las cajas del dia
+
+---
+
+## 10. Dashboard (Dueno)
+
+Pantalla de resumen ejecutivo disponible solo para Dueno y Admin:
+
+- **Ventas del dia** vs meta configurada
+- **Cajas activas**: cuantas cajas estan abiertas y quien las opera
+- **Alertas**: productos sin stock, facturas con error, cajas sin cerrar
+- **Resumen semanal**: grafico de ventas de los ultimos 7 dias
+
+---
+
+## 11. Configuracion
+
+### Datos del negocio
+
+- Nombre, RFC, regimen fiscal, direccion, logo
+- Configuracion de CFDI (serie, folio, certificados)
+
+### Sucursales
+
+- Crear y editar sucursales
+- Nombre, direccion, telefono
+- Activar/desactivar sucursal
+
+### Empleados y roles
+
+- Crear empleados con nombre, telefono, email, PIN y rol
+- Roles disponibles:
+
+| Rol | Permisos principales |
+|-----|---------------------|
+| Dueno | Todo (no se puede eliminar) |
+| Admin | Todo excepto configuracion de tenant |
+| Cajero | POS, catalogo, clientes basico |
+| Almacenista | Inventario completo, catalogo |
+| Contador | Contabilidad, facturacion, reportes |
+
+- Cada rol tiene permisos granulares que se asignan automaticamente
+
+### Temas
+
+- **Industrial**: tema oscuro con tonos grafito y acentos naranja
+- **Moderno**: tema claro con tonos blancos y azul primario
+- El toggle esta en el sidebar y se aplica inmediatamente