Saltar a contenido

3. Manual de usuario

📄 Antes de usarlo con clientes reales, leer Qué hace hoy y qué todavía no: facturación, WhatsApp y correo simulados o sin configurar, respaldos y decisiones pendientes.

Requisitos de entorno

  • Encender con iniciar_sgejd.bat y apagar con detener_sgejd.bat (ver Uso diario en la sección 2).
  • Navegador actualizado (Chrome, Firefox o Edge).
  • Internet para la consulta de RUC/DNI, el envío de correos y la facturación electrónica real (hoy simulada). Sin internet se puede activar CONSULTA_DOCUMENTOS_SIMULADO=true.

Acceso al sistema

⚠️ Credenciales solo de desarrollo. No deben usarse ni documentarse así en un ambiente real.

  • Usuarios de Keycloak (realm bomerp): lisandro (ADMIN) y lucy (ASISTENTE) (contraseñas en bomerp-backend/.env). Se crean al importar keycloak/realm-bomerp.json o con python keycloak/configurar_realm.py.
  • Consola de Keycloak: http://localhost:38080 (usuario admin, contraseña KC_ADMIN_PASSWORD de .env). La antigua tabla USUARIOS se borró el 07/11/2026 (migracion_quitar_usuarios.sql).

Flujos de operación

  • Iniciar sesión: en la SPA (http://localhost:4200) pulsar "Iniciar sesión" (o abrir cualquier pantalla): se abre la pantalla de Keycloak, se entra con lisandro o lucy y se vuelve a la pantalla pedida. La sesión sobrevive un F5 en la misma pestaña y el token se renueva solo; "Salir" la cierra también en Keycloak. Junto al nombre se muestra el rol, y el ADMIN ve además "+ Producto" en el menú.
  • Acceso denegado: si un usuario abre una pantalla de su rol no permitido (por ejemplo, Lucy en Nuevo producto), la SPA muestra "Acceso denegado"; aunque la saltara, el backend respondería 403.
  • Registrar proveedor: Proveedores → "+ Nuevo Proveedor" → elegir empresa o persona natural → escribir el RUC o DNI → "Buscar en SUNAT/RENIEC" (llena nombre y dirección; avisa si ya está registrado) → completar teléfono, correo y contacto → Guardar.
  • Registrar cliente: Clientes → "+ Nuevo Cliente" → empresa (RUC) o persona natural (DNI) → "Buscar en SUNAT/RENIEC" (llena nombre y dirección; avisa si ya está registrado) → completar teléfono y correo → Guardar. Si aparece "servicio ocupado", esperar unos segundos (apis.net.pe limita las consultas seguidas).
  • Venta directa: Ventas → Nueva venta → elegir cliente y forma de pago → (si se registra tarde) poner la fecha de la venta: hasta 30 días atrás, solo el administrador o quien tenga el permiso "Ventas con fecha pasada"; el crédito y el tipo de cambio se toman de ese día y la factura sale con fecha de hoy → agregar líneas buscando el producto por nombre (muestra precio y stock) → si se negoció, escribir el descuento % de la línea (hasta el tope del usuario) → si el producto se compró más caro, la línea lo avisa ("Última compra: …"); el administrador o quien tenga el permiso "Editar precio en la venta" pulsa Editar precio, escribe el nuevo precio (solo puede subir; para bajarlo está el descuento) y el motivo. El catálogo no cambia; la venta guarda el precio de catálogo, el cobrado, quién y por qué, y el historial de cambios lo registra → revisar subtotal, IGV y total → Registrar y confirmar el resumen.
  • Proformas: "+ Nueva Proforma" → cliente, moneda y líneas (con descuento % opcional) → Guardar. En la lista: "📤 Enviar" muestra si salió el correo y si el cliente no tiene teléfono o correo; ✓ acepta; ✗ rechaza (pide confirmación). Una proforma convertida muestra "Venta #N".
  • Convertir proforma en venta: la proforma debe estar ACEPTADA. Un diálogo muestra el resumen (cliente, subtotal, IGV, total, tipo de cambio de la proforma) y pide la forma de pago: contado (queda PAGADA) o crédito con días entre 1 y 365 (queda PENDIENTE con fecha límite). Con el permiso, también la fecha real de la venta (hasta 30 días atrás). Al confirmar, el sistema descuenta stock, programa mantenimientos y genera el comprobante; si algo falla (falta stock, ya convertida, no aceptada) se muestra el motivo en el mismo diálogo.
  • Reporte de ventas: Ventas → filtros por estado y rango de fechas (botón "Buscar"); muestra totales por moneda, ticket promedio y el detalle de cada venta.
  • Anular una venta: en el reporte, botón "Anular" (solo en ventas REGISTRADAS) → escribir el motivo (al menos 5 caracteres) → "Anular venta"; la venta queda como "Anulada el … por …: motivo". El stock de los materiales se restaura. Si el cliente ya había pagado (al contado o con abonos), el aviso muestra cuánto: ese monto queda como devolución pendiente en Cobranza › Devoluciones.
  • Reportes financieros (API): /api/v1/admin/reportes/ventas-resumen, /cobranza y /proformas-pendientes.
  • Moneda y tipo de cambio: al vender o cotizar se elige soles o dólares; el tipo de cambio de SUNAT del día se carga solo y se puede cambiar si se negoció otro. Los productos en la otra moneda se convierten; el tipo de cambio queda guardado en la venta y sale en la factura.
  • Exportar a Excel: Ventas y Compras tienen "⬇ Exportar a Excel": descarga un .xlsx con los filtros de la pantalla, con una hoja de cabeceras (cliente/proveedor con RUC, pago, estado, comprobante, totales por moneda) y otra con el detalle línea por línea.
  • Descargar comprobante: en el reporte de ventas, el botón "PDF" descarga la factura o boleta de esa venta.
  • Historial: en Clientes y Proveedores, el botón "Historial" muestra todas sus ventas o compras, los totales por moneda y lo pendiente de pago, exportable a Excel.
  • Kardex: en Productos, el botón "Kardex" lista las entradas (compras), salidas (ventas) y devoluciones (anulaciones) con el saldo de stock después de cada movimiento, con filtro por fechas y exportable a Excel.
  • Órdenes de trabajo: menú Servicios › Órdenes de trabajo → "+ Nueva orden": tipo (instalación, mantenimiento, reparación o visita), cliente, sede, venta de origen, equipo, fecha, técnico y trabajo a realizar (la dirección sale de la sede o del cliente). En la orden: "Cerrar orden" registra la fecha, lo hecho, quién lo recibió y los materiales usados (descuentan stock); si es una instalación, también los equipos instalados con su serie, garantía y frecuencia de mantenimiento. Ya realizada, "Facturar servicio" crea la venta con la mano de obra. Cancelar una orden es solo del administrador.
  • Sedes: en la ficha del cliente (Editar), tarjeta "Sedes" → "+ Agregar sede" con nombre, dirección, contacto y teléfono. En la misma ficha, una empresa se marca como "Agente de retención del IGV".
  • Equipos instalados: menú Servicios › Equipos instalados → filtros por cliente, estado y garantía; "+ Registrar equipo" para los instalados antes del sistema; "Editar" cambia sede, serie, ubicación, garantía o frecuencia (las visitas pendientes se reprograman); "Retirar" (administrador) lo da de baja y cancela sus visitas.
  • Contratos: menú Servicios › Contratos → "+ Nuevo contrato" (administrador): cliente, sede, inicio y fin, cada cuánto se visita y monto por visita; muestra cuántas visitas tendrá antes de guardarlo. Sus visitas aparecen en Postventa.
  • Postventa: menú Servicios › Postventa → pestañas Vencidos / Próximos (7 a 90 días) / Realizados / Todos, con filtro por cliente. Cada visita dice si viene de una venta, del plan de un equipo o de un contrato; "Orden" programa la visita con técnico (al cerrar la orden queda realizada). Cada fila muestra cuántos días faltan, el teléfono (con enlace de WhatsApp para coordinar), la dirección y los equipos. "✓ Realizado" registra la fecha de la visita y el trabajo hecho; "Reprogramar" mueve la fecha a pedido del cliente. Además, el sistema envía a diario, a las 8:00 a. m., un correo con los clientes de los próximos 7 días (requiere CORREO_OFICINA).
  • Detracción y retención: si una venta tiene detracción o retención, la lista de ventas y Cobranza muestran el monto y el neto que paga el cliente. En Cobranza, el botón "Detracción" (o "Retención") abre el cobro con la constancia de depósito (o el comprobante de retención) por lo pendiente: se escribe su N° y se registra; el resto se cobra como siempre.
  • Cobranza: menú Cobranza (o "Cobrar" en una venta pendiente) → arriba, cuatro indicadores que llevan a su pestaña (por cobrar, ya vencido, cobrado este mes y por devolver) y la antigüedad de saldos (al día, 1–30, 31–60 y más de 60 días de atraso) → lista de ventas a crédito con buscador (cliente, N° de venta o comprobante), filtro "Solo vencidas", barra de lo ya cobrado, saldo y días de atraso → "Recordar" abre WhatsApp con el recordatorio de pago ya escrito (lo revisa y lo envía la persona; el sistema no manda nada solo; se desactiva si el cliente no tiene teléfono) → "Registrar cobro": se abonan uno o varios montos (botón "todo" para el saldo completo) a las ventas del cliente en esa moneda, con fecha, método (transferencia, depósito, efectivo, Yape/Plin, cheque) y N° de operación. Al cubrir el saldo, la venta pasa a PAGADO. La pestaña "Historial de cobros" lista los pagos recibidos (con quién los registró), con filtro por fechas y método y el total del periodo. Si un cobro se registró mal, el administrador pulsa "Anular", escribe el motivo y confirma: el cobro queda tachado como anulado y su monto vuelve al saldo de la venta. Si al registrar un cobro sale "ese N° de operación ya se registró", el pago ya estaba ingresado: revise el historial antes de volver a cobrarlo. La pestaña "Devoluciones" lista el dinero por devolver de ventas anuladas; el administrador pulsa "Registrar devolución" e indica fecha, método y N° de operación.
  • Compras: los precios se escriben tal como figuran en la factura del proveedor, con IGV; el formulario y la lista muestran el subtotal sin IGV y el IGV (crédito fiscal), y el Excel los trae en columnas. Cada compra deja en el producto su último costo sin IGV (se ve en el formulario del producto); el precio de venta no cambia solo. El N° de factura del proveedor es obligatorio (formato SERIE-NÚMERO, p. ej. F001-123). Si esa factura del mismo proveedor ya se ingresó, el sistema lo avisa y no vuelve a subir el stock.
  • Tema claro u oscuro: el botón sol/luna de la barra superior cambia entre claro y oscuro. En Configuración › Preferencias › Tema se elige también "Como el sistema" (sigue al modo de Windows). Se recuerda en esa computadora.
  • Dar permisos a un asistente (administrador): menú del avatar o Configuración › "Usuarios y permisos" → en la tarjeta del asistente, encender lo que se le permite (anular ventas, anular cobros, registrar devoluciones, editar el catálogo, eliminar clientes y proveedores, administrar servicios, descuento del administrador) → "Guardar permisos". El asistente lo ve en 5 minutos como máximo o al volver a entrar; para quitarlo, apagar y guardar. En Configuración, cada asistente ve sus "Permisos adicionales".
  • Historial de cambios (administrador): menú del avatar o Configuración › "Historial de cambios". Pestaña Cambios: quién hizo qué y cuándo (registrar, modificar, anular, eliminar), con filtros por usuario, módulo, resultado y fechas; las filas marcadas en rojo son intentos sin permiso. Al pulsar una fila se ve el detalle (motivo de un rechazo, permisos que quedaron, IP). Pestaña Inicios de sesión: entradas, contraseñas erradas y salidas de los últimos 7 días.
  • Topes de descuento (administrador): Configuración › Topes de descuento → el máximo % por línea del administrador (también para quien tenga "Descuento ampliado") y el del asistente → "Guardar topes". Rigen desde la próxima proforma o venta; nadie más puede cambiarlos (403) y el cambio queda en el historial con los valores de antes y después.
  • Compra a crédito: en Nueva compra, "Pago al proveedor" → "A crédito" y los días. La lista de Compras muestra "Debe …" y la fecha de vencimiento.
  • Cuentas por pagar: menú Inventario › Cuentas por pagar → arriba, lo que se debe por moneda (vencido y lo que vence en 7 días) → "Pagar" en la compra: fecha, monto (por defecto el saldo), método y N° de operación → Registrar. Pestaña "Pagos realizados": historial con filtros; "Anular" (administrador) pide el motivo y devuelve el monto al saldo.
  • Ajustes de inventario: menú Inventario › Ajustes de inventario. "+ Conteo físico": elegir el material y escribir cuántas unidades hay; el sistema muestra cómo queda el stock y registra la diferencia. "Merma, dañado u otro": entrada o salida, cantidad, motivo y una observación que explique qué pasó. Los ajustes salen en el kardex del producto.
  • Rentabilidad (administrador): menú Comercial › Rentabilidad → periodo (este mes, trimestre, año o fechas) → pestañas por venta, cliente, producto, categoría y técnico, con lo vendido sin IGV, el costo y la ganancia. En ámbar, lo que deja menos de 10 %.
  • Agenda de técnicos: menú Servicios › Agenda → semana actual con una fila por técnico; flechas para otras semanas. Clic en una visita abre la orden; "+" en un día libre programa una orden para ese técnico. Al programar una orden, escribir la hora y la duración: si el técnico ya tiene otra visita que se cruza, el sistema lo avisa y no la guarda.
  • Respaldo automático: una sola vez, programar_respaldo.bat -Destino "<carpeta fuera de la PC>" (por ejemplo un USB o la carpeta de OneDrive). Desde entonces Windows respalda todos los días a las 18:30 y deja los últimos 14. Revisar de vez en cuando C:\SGE-JD\respaldos\respaldo_automatico.log.

Preguntas frecuentes

  • "El cliente no recibió el correo": en Ventas, "Entrega del comprobante" dice si se entregó al servidor de correo, si falló (con el mensaje del servidor) o si quedó por confirmar; "Historial de intentos" muestra cada intento. Verificar el correo del cliente (errores como .con), las credenciales SMTP (MAIL_USERNAME/MAIL_PASSWORD), la salida al puerto 587 y la carpeta de spam del cliente; después, Reenviar por correo.
  • "No me deja vender por stock": los materiales no admiten stock negativo (409 "Stock insuficiente"); registre una compra o ajuste la cantidad. Los equipos no controlan stock.
  • "El backend no arranca: Network Adapter could not establish the connection": Oracle no está encendido; use iniciar_sgejd.bat (enciende Docker y Oracle antes que el backend).
  • "Le di un permiso a Lucy y todavía no le aparece": la sesión se renueva cada 5 minutos; que espere o cierre sesión y vuelva a entrar.
  • "Usuarios y permisos dice que no se pudo consultar Keycloak": Keycloak está apagado o falta KC_BACKEND_SECRET en .env/application-local.properties; ejecutar python keycloak/configurar_realm.py con Keycloak encendido.
  • "¿Cómo guardo una copia de la información?": respaldar_sgejd.bat, al menos una vez por semana, y copiar el archivo de C:\SGE-JD\respaldos fuera de la PC.
  • Soporte técnico: equipo de desarrollo estudiantil (ver 4. Equipo y responsables).