Saltar a contenido

2. Documentación técnica

Stack tecnológico (según pom.xml y package.json)

Capa Tecnología
Lenguaje Java 21
Framework Spring Boot 4.0.7 · Spring Framework 7 (Web MVC, Data JPA, Validation, Security, Mail)
ORM Hibernate 7.2 (ddl-auto=update en dev, validate en prod); los boolean son BOOLEAN nativo de Oracle 23
Base de datos Oracle Database 23 Free (Docker gvenzl/oracle-free:23-slim, servicio FREEPDB1, puerto 1522)
Seguridad Spring Security como OAuth2 Resource Server (spring-boot-starter-security-oauth2-resource-server) + Keycloak 26.8 con su propio Postgres 17 (Docker, puerto 38080)
Documentación API springdoc-openapi 3.0.2, OpenAPI 3.1 (Swagger UI en /swagger-ui.html)
JSON Jackson 3 (tools.jackson), con su configuración por defecto
Otras OpenPDF 1.3.32, Lombok, driver ojdbc11; H2 incluido como dependencia (sin perfil configurado)
Frontend Angular 22 (standalone, signals, zoneless), en bomerp-frontend
Íconos Trazos SVG de línea en ICONOS (menu.ts) y el componente <app-icono>; basados en Feather Icons (MIT, © Cole Bemis) y Lucide (ISC, © Lucide Contributors), varios tomados o adaptados de ellos. Licencias en bomerp-frontend/LICENCIAS-TERCEROS.md

Migración a Spring Boot 4.0.7 (22/10/2026)

De 3.3.4 a 4.0.7 (Spring Framework 7, Hibernate 7.2, Jackson 3, Spring Security 7), la versión de la guía del curso (ADR-003). Qué cambió y por qué:

Cambio Motivo
spring-boot-starter-web → -webmvc; -oauth2-resource-server → -security-oauth2-resource-server; -test → -webmvc-test + -data-jpa-test Boot 4 divide los starters por módulo
springdoc 2.6.0 → 3.0.2 La línea 2.x no funciona con Boot 4; Swagger pasa a OpenAPI 3.1
SecurityConfig y ConsultaRucClientDecolecta usan tools.jackson Boot 4 configura Jackson 3. Jackson 2 sigue en el classpath solo porque lo trae springdoc, así que compilaba pero fallaba al ejecutar
texto() de Decolecta lee solo valores simples En Jackson 3, asText()/asString() lanza excepción sobre un objeto (en Jackson 2 devolvía "")
Jackson 3 con su configuración por defecto Solo cambia el orden de algunos campos del JSON (ahora alfabético); los datos son los mismos y la SPA lee los campos por nombre
migracion_boot4_booleanos.sql: los 4 boolean (productos.visible_en_catalogo, mantenimientos.alerta_enviada, proformas.enviado_correo y enviado_whatsapp) pasan de NUMBER(1) + CHECK a BOOLEAN Es el tipo que Hibernate 7 usa en Oracle 23; sin el script, intentaba convertirlos en cada arranque y Oracle lo rechazaba. Conserva los valores; datos_demo.sql sigue funcionando porque Oracle acepta 1/0 en BOOLEAN
Venta.estado: length = 20 en vez de columnDefinition El columnDefinition solo servía para agregar la columna con DEFAULT (ya existe); en Hibernate 7 provocaba un ALTER en cada arranque
Se quitó spring.jpa.database-platform Hibernate 7 detecta el dialecto solo

Después de la migración (23-24/10/2026):

Cambio Motivo
spring.jpa.open-in-view=false Con el valor por defecto, la sesión de Hibernate quedaba abierta hasta escribir el JSON y escondía cargas perezosas fuera de la transacción. Al apagarlo aparecieron 6 endpoints con LazyInitializationException
Los services devuelven DTO (VentaService, ProformaService, FacturacionService; nuevos ComprobanteResponseDTO y NotaCreditoResponseDTO) y se arman dentro del @Transactional Regla de la S3: el controller no toca entidades. Se quitaron las anotaciones de Jackson de Comprobante, NotaCredito, Mantenimiento, DetalleVenta y DetalleCompra
Filtros y orden de GET /ventas y GET /proformas pasan del controller al service (listar(...), readOnly) El controller queda delgado
Proforma, Compra y el diálogo "Registrar cobro" de Cobranza con formularios reactivos (FormArray tipado), como Venta Mismo patrón de la S9 en las cuatro pantallas transaccionales: cada línea trae su validación (en Cobranza, el abono no supera el saldo de su venta) y el total sale del formulario
ProformaRequest: @NotEmpty en ítems y @Min(1) en cantidad Antes se podía guardar una proforma sin productos o con cantidad 0; ahora responde 400 con mensaje

Verificado de nuevo con open-in-view=false: recorrido completo por API como Lisandro (90/90) y como Lucy (84/84), 0 LazyInitializationException y 0 ERROR en el registro, y los mismos estilos en la SPA a 1280 y 375 px.

Sin configuraciones que fuercen comportamiento antiguo: Hibernate arranca sin ejecutar ningún DDL. Verificado: las respuestas de los GET traen los mismos datos que con 3.3.4, los errores 400/401/403/404 tienen el mismo formato, la matriz de seguridad da 14 de 14, PKCE funciona, los 60 valores booleanos se conservaron, las pruebas de venta (contado, crédito, stock insuficiente, anulación) pasan con rollback y se recorrió la SPA como ADMIN y como ASISTENTE.

Arquitectura de software

Monolito modular: un solo proyecto Maven y un solo ejecutable Spring Boot. Cada módulo es un paquete bajo com.bomerp con capas internas:

  1. Controllers: endpoints REST (/api/v1/admin/..., /api/v1/publico/...).
  2. Services: reglas de negocio y transacciones (@Transactional).
  3. Repositories: interfaces Spring Data JPA.
  4. Integrations: clientes hacia servicios externos detrás de interfaces (ConsultaRucClient, OseClient, NotificadorCorreo, NotificadorWhatsApp).

Errores: GlobalExceptionHandler traduce excepciones a 400 (validación), 404 (RecursoNoEncontradoException), 409 (ReglaNegocioException, StockInsuficienteException) y 500 sin filtrar detalles.

Facturación electrónica: envío directo a SUNAT (06/11/2026)

SGE-JD emite directamente ante SUNAT con las credenciales de JD (SEE - Del Contribuyente), sin OSE intermedio. Se activa con app.facturacion.modo=sunat; sin esa propiedad el envío es simulado (como antes).

Venta registrada ──► comprobante PENDIENTE (serie y correlativo) ──► se confirma la venta
      └─► cola de envíos (uno a la vez, con pausa) ──► XML UBL 2.1 (xbuilder) ──► firma con el certificado
            └─► ZIP ──► SUNAT billService (sendBill, usuario SOL) ──► CDR: código y mensaje
Código de SUNAT Estado en SGE-JD
0 ACEPTADO
4000 o más OBSERVADO (válido; la observación queda guardada)
2000-3999 (rechazo con CDR) y 1032 RECHAZADO definitivo: no es válido y su número ya quedó usado; se emite un comprobante de reemplazo
Demás excepciones (p. ej. 0100-1999 con dato mal enviado) RECHAZADO "no recibido": SUNAT no lo registró; se corrige el dato y se reenvía con el mismo número
0100-0199, HTTP 401/5xx o sin respuesta PENDIENTE: se reintenta solo cada 3 minutos (hasta 20 intentos), mientras esté en plazo
Sin registrar en SUNAT pasados 3 días desde la emisión Fuera de plazo: ya no se envía ni se reenvía; se emite un comprobante de reemplazo
1033 (ya registrado en un envío anterior) PENDIENTE "por confirmar": sin validez, fuera del reintento automático y con el aviso de verificarlo en SUNAT
  • Fuera de la transacción de la venta: la venta no espera a SUNAT (responde en ~1 s) ni se deshace si SUNAT está caída.
  • Una cola, de uno en uno: la beta de SUNAT responde HTTP 401 al tercer envío seguido en menos de un segundo.
  • Respaldo: por cada comprobante y nota de crédito se guardan el XML firmado, el CDR (constancia de SUNAT), el código, el mensaje y los intentos (migracion_envio_sunat.sql).
  • Nota de crédito: se crea al anular la venta y sale cuando SUNAT aceptó el original. Si el original fue rechazado, no se anula (no tenía validez).
  • Plazo de envío de 3 días (informe de rechazos SUNAT D-6, 07/11/2026): SUNAT recibe facturas y boletas hasta 3 días calendario contados desde el día siguiente a la emisión (RS 003-2023/SUNAT): emitida el 7, hasta el 10 inclusive. Lo que llega después no tiene validez aunque SUNAT lo reciba. Un comprobante que SUNAT todavía no registró (pendiente o excepción) muestra en Ventas "Enviar a SUNAT a más tardar el dd/mm" y, pasado el plazo, "Fuera de plazo: no es válido": el envío automático y el reintento lo dejan (sin llamar a SUNAT), Reenviar responde 409 y se ofrece Emitir comprobante de reemplazo, con número nuevo y fecha de hoy. La campana avisa los que vencen hoy o mañana y los que ya vencieron (GET /facturacion/plazo-envio). No aplica a lo que SUNAT ya tiene (aceptado, rechazado con CDR o por confirmar) ni a las notas de crédito.
  • Reintentos sin trabas (revisión externa F-02, 07/11/2026): el límite de 20 intentos se filtra en la consulta a Oracle, antes de tomar los 20 primeros pendientes; antes, 20 agotados al principio de la lista tapaban para siempre a los siguientes.
  • Correo al cliente solo con validez (revisión externa F-01, 07/11/2026): "Su Factura ... ha sido emitida" sale solo si SUNAT la aceptó (o la observó). Un comprobante pendiente, rechazado, del modo simulado o aceptado por la beta de SUNAT (que devuelve XML y CDR como la real, pero sin validez; informe D-12) no se envía: el botón responde 409 con el motivo.
  • Usuario o clave SOL rechazados (informe D-9, 07/11/2026): SUNAT responde 0101-0106 (encabezado de seguridad, usuario o clave incorrectos, usuario inexistente, inactivo o no válido). Antes se reintentaba 20 veces por comprobante como si SUNAT estuviera caída, con riesgo de bloquear la cuenta SOL. Ahora el primer rechazo detiene todos los envíos: ni la cola, ni el reintento automático, ni el botón Reenviar (409) vuelven a llamar a SUNAT, y los comprobantes siguientes quedan pendientes sin gastar intentos. La campana muestra "Envíos a SUNAT detenidos". Se corrigen SUNAT_USUARIO y SUNAT_CLAVE y se reinicia el backend.
  • Tipo de comprobante y cliente (informe D-11, 07/11/2026): al pasar un cliente a persona natural, Clientes borra su RUC. Reenviar una factura que SUNAT no recibió tomaba los datos actuales y salía una factura con DNI, que SUNAT rechaza. Ahora ese reenvío responde 409 y se ofrece el comprobante de reemplazo, que sale del tipo que corresponde (boleta para persona natural, factura para empresa). Si el cambio en Clientes fue un error, se corrige y se reenvía el mismo.
  • El reenvío espera la confirmación (informe D-13): el botón Reenviar pone el comprobante en la cola recién cuando se confirma la transacción, como el envío normal.
  • El 1033 no se da por aceptado (informe de rechazos SUNAT D-1, 07/11/2026): SUNAT responde 1033 cuando ya tiene ese número por un envío anterior, sin CDR y sin decir si fue aceptado o rechazado (p. ej. un rechazado que se reenvió con el mismo número). Antes quedaba ACEPTADO y salía el correo "ha sido emitida"; ahora queda pendiente por confirmar, no se envía al cliente, el reintento automático no lo repite y en Ventas aparece "Por confirmar en SUNAT" sin el botón Reenviar.
  • Comprobante de reemplazo (informe de rechazos SUNAT D-2 y D-4, 07/11/2026): un rechazo con CDR (2000-3999, o 1032) deja el comprobante sin validez y su número usado; reenviarlo con el mismo número solo devolvía 1033. Ahora el botón Reenviar no aparece (y la API responde 409) y en su lugar está Emitir comprobante de reemplazo: emite otro comprobante, con número nuevo de la misma serie y los datos actuales del cliente, para la misma venta. La venta, el stock, el cobro y los mantenimientos no cambian. El rechazado queda marcado como reemplazado, con su constancia, y el nuevo apunta a él. Oracle admite un solo comprobante vigente (no reemplazado) por venta (índice UX_COMPROBANTE_VIGENTE_VENTA). No se reemplaza un comprobante válido, uno de una venta anulada, ni el mismo rechazado dos veces.
  • Historial de envíos (D-3): cada respuesta de SUNAT (intento, fecha, resultado, código, mensaje, XML y CDR) se guarda en ENVIOS_SUNAT sin pisar las anteriores: un reenvío ya no borra la constancia del rechazo, que SUNAT exige conservar. En Ventas, el botón Envíos de cada comprobante o nota muestra los intentos y descarga el XML y el CDR de cada uno.
  • Datos fijos al emitir (D-5): el comprobante guarda el tipo y número de documento, el nombre y la dirección del receptor, y cada línea de la venta guarda la descripción del producto. Editar el cliente o el producto después ya no cambia el XML ni el PDF de un comprobante emitido. Solo un reenvío por excepción (SUNAT no lo recibió) vuelve a tomar los datos del cliente, para que salga el dato corregido.
  • Ninguna factura de una venta anulada sale sola (auditoría M10, 07/11/2026): antes de enviar un comprobante se revisa su venta. Si está anulada y no tiene nota de crédito (pasó con la venta #285, anulada antes de que la nota se creara también para comprobantes pendientes), la nota se crea en ese momento y sale después de la factura. Si no se puede crear, el comprobante no se envía y el motivo queda en su registro de envío.
  • Detracción sin cuenta configurada (D-6, 07/11/2026): SUNAT rechaza una factura con detracción que no lleva la cuenta de JD en el Banco de la Nación (3034). Antes la factura tomaba número y esperaba PENDIENTE mientras corría su plazo de 3 días. Ahora la venta se guarda por emitir, sin comprobante: no usa número ni corre plazo. En Ventas dice "SUNAT: por emitir" con el motivo (sin botón PDF) y la campana la avisa. Al arrancar con CUENTA_DETRACCIONES configurada, la emisión automática (cada 3 minutos) le da su comprobante con fecha de ese día. Una venta por emitir que se anula no necesita nota de crédito. Lo decide OseClient.motivoParaNoEmitir antes de pedir el correlativo; los comprobantes que ya tenían número desde antes siguen sin enviarse hasta que se configure la cuenta.
  • El correo con el comprobante sale recién cuando SUNAT lo acepta.
  • En pantalla (Ventas): bajo el estado de cada venta, una etiqueta "SUNAT: aceptado / observado / rechazado / pendiente / simulado"; en el detalle, una línea por comprobante y nota de crédito con el código y el mensaje de SUNAT, las descargas del XML firmado y del CDR, el botón Reenviar (no recibidos por SUNAT ya corregidos, o pendientes con aviso), Emitir comprobante de reemplazo (rechazados con CDR) y Envíos (historial). Los comprobantes reemplazados siguen debajo, tachados, como historial. Los comprobantes emitidos antes del envío real se muestran como Simulado (sin envío a SUNAT): no tienen validez tributaria.
  • API: GET /api/v1/admin/facturacion/estados?ventaIds=1,2, POST /facturacion/{id}/reenviar (409 si ya fue aceptado, si fue rechazado con CDR o si fue reemplazado), POST /facturacion/{id}/reemplazar (409 si no es un rechazo definitivo ni está fuera de plazo), GET /facturacion/plazo-envio (por vencer y fuera de plazo, para la campana), GET /facturacion/{id}/xml y /cdr, GET /facturacion/{id}/envios (historial), GET /facturacion/envios/{envioId}/xml y /cdr, y lo mismo bajo /facturacion/notas-credito/{id}/....
  • Ambiente beta (pruebas, sin efecto tributario): SUNAT_AMBIENTE=BETA (en desarrollo, app.sunat.ambiente=BETA en application-local.properties), usuario MODDATOS y un certificado de prueba propio (certificados/beta-prueba.p12, fuera de git). SunatBetaTest hace el envío real con SUNAT_BETA=1.
  • Paso a producción (qué hace JD y cómo se configura): FACTURACION_SUNAT.md. En resumen: poner SUNAT_AMBIENTE=PRODUCCION y SUNAT_URL en https://e-factura.sunat.gob.pe/ol-ti-itcpfegem/billService (el ambiente es obligatorio y tiene que corresponder a la dirección oficial; si no, el backend no arranca), SUNAT_USUARIO/SUNAT_CLAVE por el usuario SOL secundario de JD y SUNAT_CERT_RUTA/SUNAT_CERT_CLAVE por su Certificado Digital Tributario. Nada de eso va en el código.

Stock y operaciones simultáneas (05/11/2026)

Dos personas pueden registrar a la vez operaciones sobre el mismo producto, venta, compra o proforma. Para que el resultado sea el mismo que si se hubieran hecho una tras otra:

  • Un solo lugar mueve el stock: ProductoService.descontarStock y sumarStock. Ventas, conversión de proformas, anulaciones, compras, órdenes de trabajo y ajustes pasan por ahí. Editar un producto ya no cambia su stock (en el formulario queda de solo lectura): el stock cambia solo con movimientos que salen en el kardex.
  • Cantidades sumadas por producto: si una venta trae el mismo material en varias líneas, se suman antes de validar (con stock 10, dos líneas de 6 se rechazan: piden 12).
  • Bloqueo de filas (SELECT … FOR UPDATE, PESSIMISTIC_WRITE): los productos se releen bloqueados y en orden de id (sin interbloqueos); la proforma se bloquea al convertirla; la venta, al registrar un cobro; la compra, al registrar un pago a proveedor. La segunda operación espera a que termine la primera y valida con el dato ya actualizado. Si espera más de 10 s responde 409 ("otro usuario está registrando…").
  • Todo o nada: se valida el stock de todas las líneas antes de descontar; si algo falla después, la transacción devuelve el stock.
  • Respaldo en la base: índice único UX_VENTAS_PROFORMA sobre ventas.proforma_id (migracion_proforma_unica.sql): aunque falle todo lo anterior, una proforma no genera dos ventas.

Probado contra el sistema real con peticiones en paralelo: 8 ventas simultáneas de 1 unidad con stock 4 → 4 aceptadas, 4 rechazadas (409), stock final 0; dos conversiones simultáneas de la misma proforma → una venta; dos cobros simultáneos por el saldo completo → uno aceptado y el otro rechazado ("ya está PAGADA").

Límites entre módulos (ADR-002, verificado con Spring Modulith)

Cada paquete directo de com.bomerp es un módulo. Un módulo solo puede usar de otro su API: los paquetes service, entity, dto y event (marcados con @NamedInterface en su package-info.java) y las piezas compartidas de config (empresa, exportacion, tipocambio) y de seguridad (descuento). Sus repository y controller son internos. Tampoco se permiten ciclos entre módulos.

ModularityTests lo verifica en cada mvn test con Spring Modulith 2.0.7: si alguien usa el repositorio de otro módulo o crea un ciclo, la prueba falla y dice qué clase lo hizo. Al activarlo (31/10/2026) había 1 143 avisos; se resolvieron así:

  • Eventos en vez de llamadas directas: al registrar una venta, VentaService publica VentaRegistradaEvent y Facturación (emite el comprobante) y Postventa (programa los mantenimientos) reaccionan; al anularla, VentaAnuladaEvent lo escuchan Postventa (cancela visitas), Facturación (nota de crédito) y Cobranza (devolución). Corren en la misma transacción: si un oyente falla, la venta no se guarda (igual que antes).
  • Inversión de dependencias: el reporte de ventas necesita el número de comprobante; Ventas define la interfaz ComprobantesDeVenta y Facturación la implementa, así Ventas no depende de Facturación.
  • Fachadas en vez de repositorios ajenos: Facturación, Reportes y Rentabilidad piden los datos a VentaService, ProformaService y OrdenTrabajoService (registradasEntre, pendientesVencidasAl, lineasVendidas, pendientes, realizadasEntre, asignarComprobante).
  • Cada cosa en su módulo: la detracción pasó de config a ventas/tributos, y la seguridad (SecurityConfig, permisos, tope de descuento e historial de cambios) a un módulo nuevo seguridad. config quedó como infraestructura compartida que no depende de nadie.
  • API de cada módulo: 73 package-info.java con @NamedInterface.

Dependencias entre módulos (generado por ModularityTests en target/spring-modulith-docs/, junto con los diagramas PlantUML de Spring Modulith):

flowchart LR
    catalogo --> config
    clientes --> config
    cobranza --> clientes
    cobranza --> config
    cobranza --> facturacion
    cobranza --> ventas
    compras --> catalogo
    compras --> config
    compras --> proveedores
    facturacion --> catalogo
    facturacion --> clientes
    facturacion --> config
    facturacion --> notificaciones
    facturacion --> ventas
    inventario --> catalogo
    inventario --> clientes
    inventario --> compras
    inventario --> config
    inventario --> notificaciones
    inventario --> proveedores
    inventario --> servicios
    inventario --> ventas
    postventa --> catalogo
    postventa --> clientes
    postventa --> config
    postventa --> notificaciones
    postventa --> ventas
    proformas --> catalogo
    proformas --> clientes
    proformas --> config
    proformas --> notificaciones
    proformas --> seguridad
    proveedores --> clientes
    proveedores --> config
    reportes --> catalogo
    reportes --> clientes
    reportes --> cobranza
    reportes --> config
    reportes --> proformas
    reportes --> servicios
    reportes --> ventas
    seguridad --> config
    servicios --> catalogo
    servicios --> clientes
    servicios --> config
    servicios --> postventa
    servicios --> ventas
    ventas --> catalogo
    ventas --> clientes
    ventas --> config
    ventas --> proformas
    ventas --> seguridad

Estructura del código

src/main/java/com/bomerp/
├── BomerpApplication.java
├── catalogo/        categoria/, producto/, productocatalogo/ (catálogo público, DTO sin costo ni margen)
├── clientes/        cliente/, consultaruc/ (RUC/DNI), general/ (entidad Cliente)
├── cobranza/        cobro/: Cobro–DetalleCobro, saldos y abonos · devolucion/: devoluciones de ventas anuladas
├── compras/         compra/, detallecompra/, pago/ (cuentas por pagar)
├── config/          infraestructura compartida: GlobalExceptionHandler, excepciones, empresa/ (datos de JD), tipocambio/, exportacion/ (Excel)
├── proformas/       proforma/, itemproforma/, proformarequest/, pdf/ (antes cotizaciones/)
├── facturacion/     comprobante/, facturacion/, nubefact/, ose/, pdf/, serie/ (correlativo por serie)
├── inventario/      alertas de stock mínimo, kardex/, ajuste/ (ajustes de inventario)
├── postventa/       mantenimiento/ (programación y alertas), equipo/ (equipos instalados), contrato/
├── notificaciones/  correo (real) y WhatsApp (simulado)
├── proveedores/     proveedor/
├── reportes/        reportes/ (resúmenes de ventas, cobranza y proformas), rentabilidad/
├── seguridad/       SecurityConfig (JWT de Keycloak + CORS), PerfilController, permisos/ (delegables, Keycloak), descuento/ (tope por rol), auditoria/ (historial de cambios)
├── servicios/       orden/: órdenes de trabajo y agenda de técnicos
└── ventas/          venta/ (event/: VentaRegistradaEvent y VentaAnuladaEvent), detalleventa/, tributos/ (detracción y retención), reporte/

Fuera de src/: docs/ (esta documentación y LIMITACIONES.md), sitio/ (el sitio MkDocs), scripts/ (arranque, respaldo, restauración y base limpia), keycloak/ (realm y configurar_realm.py), pruebas-seguridad/ (matriz de permisos), los migracion_*.sql, migracion_bd2/ (lo que el curso de BD2 llevó a la base: tablespace, CHECK, PL/SQL, auditoría, índices, roles y JD_APP, redo; ver su README) y .github/workflows/ (docs.yml publica esta documentación y backend.yml es la integración continua).

Modelo de datos (tablas reales, esquema JDREFRIGERACION)

Tabla Campos clave
PRODUCTOS id, nombre, categoria_id (FK → CATEGORIAS), sector (incluye SERVICIO, mano de obra), costo_base, margen_porcentaje, moneda, stock_actual, stock_minimo, visible_en_catalogo, ultimo_costo_compra y fecha_ultima_compra (sin IGV, en la moneda del producto; los pone cada compra, auditoría M1)
CATEGORIAS id, nombre, descripcion (una categoría con productos no se puede eliminar: 409)
CLIENTES / PROVEEDORES id, tipo (empresa/natural), ruc, dni, correo, teléfono; en clientes, agente_retencion
SEDES_CLIENTE id, cliente_id, nombre (único por cliente), direccion, contacto, telefono
PROFORMAS / ITEMS_PROFORMA cabecera-detalle de proforma; la cabecera guarda moneda, tipo_cambio, estado (PENDIENTE, ACEPTADA, RECHAZADA, VENCIDA, CONVERTIDA) y venta_id; cada ítem su precio ya convertido y su descuento_porcentaje
VENTAS id, cliente_id, proforma_id, fecha_venta, tipo_pago, dias_credito, fecha_limite_pago, estado (REGISTRADA/ANULADA), fecha_anulacion, anulado_por, motivo_anulacion (migracion_venta_anulacion.sql), estado_pago, moneda, tipo_cambio, comprobante_id, tipo_deduccion (NINGUNA/DETRACCION/RETENCION), porcentaje_deduccion, monto_deduccion
DETALLE_VENTA id, venta_id, producto_id, cantidad, precio_unitario, descuento_porcentaje, descripcion (nombre del producto al vender), costo_unitario, precio_catalogo, precio_editado_por, motivo_precio (precio editado al registrar, auditoría M1; vacíos = precio de catálogo). ITEMS_PROFORMA tiene las mismas tres columnas
COMPROBANTES.AMBIENTE_EMISION ambiente de SUNAT en que se aceptó (PRODUCCION, BETA, SIMULADO, NO_REGISTRADO): fijo una vez registrado (disparador TRG_COMPROBANTE_AMBIENTE); solo PRODUCCION se envía por correo. ENVIOS_SUNAT.AMBIENTE: el de cada envío (migracion_ambiente_emision.sql)
ENVIOS_CORREO / INTENTOS_CORREO entrega del comprobante por correo: comprobante_id, destinatario, tipo (AUTOMATICO/MANUAL), estado (PENDIENTE, EN_PROCESO, ENVIADO, FALLIDO, INCIERTO), intentos, último error, message_id, próximo intento; y cada intento con su resultado y los adjuntos (nombre, tamaño, SHA-256). Índice único UX_ENVIO_CORREO_AUTOMATICO: un solo envío automático por comprobante (migracion_envio_correo.sql)
TOPES_DESCUENTO una sola fila (id = 1): tope_admin, tope_asistente, actualizado_por, fecha_actualizacion. Vacía = los de application.properties
COMPRAS / DETALLE_COMPRA cabecera-detalle de compra; numero_factura normalizado (F001-00000123), total calculado por el servidor con IGV incluido (los precios de compra se escriben tal como se pagaron) y separado en subtotal e igv (total ÷ 1.18, auditoría M2)
DEVOLUCIONES dinero por devolver de una venta anulada que ya estaba pagada: venta_id (único), cliente_id, moneda, monto, estado (PENDIENTE/DEVUELTA), fecha_anulacion, fecha_devolucion, metodo_pago, referencia, notas (migracion_devoluciones.sql)
COBROS / DETALLE_COBRO pago de un cliente (fecha_cobro, moneda, metodo_pago, referencia, monto_total, estado VIGENTE/ANULADO, registrado_por, fecha_anulacion, motivo_anulacion, anulado_por) y su reparto por venta (venta_id, monto); solo los VIGENTES cuentan en el saldo (migracion_cobros_anulacion.sql)
COMPROBANTES comprobante electrónico (factura o boleta); (serie, número) único; estado_sunat, código, mensaje, XML y CDR del último envío; datos del receptor al emitir (receptor_tipo_doc, receptor_num_doc, receptor_nombre, receptor_direccion); reemplazado y reemplaza_a_id: una venta tiene un solo comprobante vigente y, si SUNAT rechazó alguno, los reemplazados (migracion_comprobante_reemplazo.sql)
ENVIOS_SUNAT historial de envíos: comprobante_id o nota_credito_id (exactamente uno), intento, fecha, resultado, codigo, mensaje, xml, cdr
NOTAS_CREDITO id, serie (FC01/BC01), numero (correlativo por serie), motivo, total, estado_sunat, comprobante_id (FK único → COMPROBANTES)
VENTA_AUDITORIA una fila por cada INSERT, UPDATE o DELETE de una venta (trigger TRG_VENTA_AUDITORIA): estados antes y después, quién anuló y por qué, usuario Oracle y programa (el MODULE de la conexión: "SGE-JD ventas"). Particionada por mes; sin FK, para que sobreviva a un DELETE. TRG_VENTA_ESTADO_BU: una venta ANULADA no vuelve atrás y anular exige motivo y quién (migracion_bd2/03)
LOG_ERRORES errores del motor PL/SQL (SP_REGISTRAR_VENTA, FN_TOTAL_VENTA), escritos en su propia transacción (migracion_bd2/02)
SERIES_COMPROBANTE serie (PK: F001, B001, FC01, BC01), ultimo_numero — contador del correlativo SUNAT
MANTENIMIENTOS id, cliente_id, venta_id, equipo_id, contrato_id (cada visita viene de uno de los tres: CHECK), fecha_programada, estado, alerta_enviada, fecha_realizada, tecnico, orden_trabajo_id, notas
EQUIPOS_INSTALADOS id, cliente_id, sede_id, producto_id, numero_serie, ubicacion, fecha_instalacion, meses_garantia, frecuencia_meses, estado (ACTIVO/RETIRADO), venta_id, orden_trabajo_id, notas
CONTRATOS_MANTENIMIENTO id, cliente_id, sede_id, fecha_inicio, fecha_fin, frecuencia_meses, monto_visita, moneda, descripcion, estado (VIGENTE/CANCELADO), registrado_por, motivo_cancelacion
ORDENES_TRABAJO / MATERIALES_ORDEN orden (tipo, estado, cliente, sede, venta, mantenimiento, equipo, fecha, técnico, dirección, descripción; al cerrar: fecha_realizada, trabajo_realizado, recibido_por; venta_facturada_id) y sus materiales (producto_id, cantidad, costo_unitario, moneda)

Diagrama de clases del dominio (UML)

Entidades JPA principales (@Entity) con sus atributos y operaciones de negocio clave. Se omiten ids, getters y setters. Cardinalidades tal como están en el código (@ManyToOne, @OneToMany).

classDiagram
    direction LR
    class Categoria {
        nombre
    }
    class Producto {
        nombre
        sector : Sector
        costoBase : BigDecimal
        margenPorcentaje : BigDecimal
        moneda : Moneda
        stockActual : int
        stockMinimo : int
        calcularPrecioVenta() BigDecimal
        controlaStock() boolean
        esEquipo() boolean
        esServicio() boolean
    }
    class Sector {
        <<enumeration>>
        CLIMATIZACION
        REFRIGERACION
        VENTILACION_FORZADA
        MATERIAL_SERVICIO
        SERVICIO
    }
    class Cliente {
        nombreORazonSocial
        ruc
        dni
        agenteRetencion
    }
    class SedeCliente {
        nombre
        direccion
    }
    class Proveedor {
        nombreORazonSocial
        ruc
    }
    class Proforma {
        fecha
        moneda
        estado
        tipoCambio
    }
    class ItemProforma {
        cantidad
        precioUnitario
        descuentoPorcentaje
    }
    class Venta {
        fechaVenta
        tipoPago : CONTADO/CREDITO
        estado : REGISTRADA/ANULADA
        estadoPago : PENDIENTE/PAGADO
        moneda; tipoCambio
        tipoDeduccion; montoDeduccion
        calcularSubtotal() BigDecimal
        calcularTotal() BigDecimal
        agregarDetalle(DetalleVenta)
    }
    class DetalleVenta {
        cantidad
        precioUnitario
        descuentoPorcentaje
        costoUnitario
        calcularSubtotalDetalle()
    }
    class Comprobante {
        serie
        numero
        tipo
    }
    class NotaCredito {
        serie
        numero
        motivo
    }
    class Cobro {
        fecha
        metodoPago
        referencia
        montoTotal
        estado : VIGENTE/ANULADO
    }
    class DetalleCobro {
        monto
    }
    class Devolucion {
        monto
        estado
    }
    class Compra {
        fechaCompra
        numeroFactura
        total
        tipoPago
        fechaVencimiento
        estadoPago
    }
    class DetalleCompra {
        cantidad
        precioUnitarioCompra
    }
    class PagoProveedor {
        fechaPago
        monto
        metodo
        numeroOperacion
        estado
    }
    class AjusteInventario {
        fecha
        tipo : ENTRADA/SALIDA
        cantidad
        motivo
        stockAnterior
        stockNuevo
    }
    class OrdenTrabajo {
        tipo
        estado
        fechaProgramada
        horaInicio
        duracionMinutos
        tecnico
        minutoInicio()
    }
    class MaterialOrden {
        cantidad
        costoUnitario
    }
    class EquipoInstalado {
        numeroSerie
        mesesGarantia
        frecuenciaMeses
        estado
    }
    class ContratoMantenimiento {
        inicio
        fin
        frecuenciaMeses
        montoPorVisita
        estado
    }
    class Mantenimiento {
        fechaProgramada
        estado
        origen
    }
    class RegistroCambio {
        fechaHora
        usuario
        accion
        resultado
    }

    Categoria "1" <-- "*" Producto
    Producto ..> Sector
    Cliente "1" <-- "*" SedeCliente
    Cliente "1" <-- "*" Proforma
    Proforma "1" *-- "1..*" ItemProforma
    ItemProforma "*" --> "1" Producto
    Proforma "0..1" <-- "0..1" Venta : origen
    Cliente "1" <-- "*" Venta
    Venta "1" *-- "1..*" DetalleVenta
    DetalleVenta "*" --> "1" Producto
    Venta "1" <-- "0..1" Comprobante
    Comprobante "1" <-- "0..1" NotaCredito
    Cliente "1" <-- "*" Cobro
    Cobro "1" *-- "1..*" DetalleCobro
    DetalleCobro "*" --> "1" Venta
    Venta "1" <-- "0..1" Devolucion
    Proveedor "1" <-- "*" Compra
    Compra "1" *-- "1..*" DetalleCompra
    DetalleCompra "*" --> "1" Producto
    Compra "1" <-- "*" PagoProveedor
    Producto "1" <-- "*" AjusteInventario
    Cliente "1" <-- "*" OrdenTrabajo
    OrdenTrabajo "*" --> "0..1" SedeCliente
    OrdenTrabajo "*" --> "0..1" EquipoInstalado
    OrdenTrabajo "1" *-- "*" MaterialOrden
    MaterialOrden "*" --> "1" Producto
    EquipoInstalado "*" --> "1" Producto
    EquipoInstalado "*" --> "0..1" SedeCliente
    ContratoMantenimiento "*" --> "1" Cliente
    Mantenimiento "*" --> "0..1" Venta
    Mantenimiento "*" --> "0..1" EquipoInstalado
    Mantenimiento "*" --> "0..1" ContratoMantenimiento

Patrones visibles en el diagrama: cabecera-detalle con composición (Venta–DetalleVenta, Compra–DetalleCompra, Cobro–DetalleCobro, OrdenTrabajo–MaterialOrden); muchos a muchos resueltos con una entidad intermedia que guarda datos propios (ver la sección siguiente); y anulación lógica en lugar de borrado (Venta.estado, Cobro.estado, PagoProveedor.estado), para que el historial no pierda nada.

Relaciones muchos a muchos

Una venta lleva varios productos y un mismo producto aparece en varias ventas: eso es una relación muchos a muchos (N:M). En una base relacional no se guarda directo (una fila de VENTAS no puede tener "una lista de productos"), así que se pone una tabla intermedia donde cada fila es una línea: esta venta + este producto + sus datos propios. El N:M queda partido en dos relaciones uno a muchos.

erDiagram
  VENTAS ||--|{ DETALLE_VENTA : "tiene líneas"
  PRODUCTOS ||--o{ DETALLE_VENTA : "aparece en"
  DETALLE_VENTA {
    number venta_id FK
    number producto_id FK
    number cantidad
    number precio_unitario
    number descuento_porcentaje
  }

Ejemplo (dos ventas y dos productos):

DETALLE_VENTA venta_id producto cantidad precio_unitario descuento %
línea 1 110 Tubería de cobre 1/4 3 52.00 30
línea 2 110 Split inverter 12 000 BTU 1 1,406.25 0
línea 3 111 Tubería de cobre 1/4 2 52.00 5

La venta 110 sale dos veces (llevó dos productos) y la tubería también (está en dos ventas).

Por qué una entidad intermedia y no @ManyToMany: la unión tiene datos propios (cantidad, precio, descuento, monto), que no son ni de la venta ni del producto. @ManyToMany solo crea una tabla con los dos ids. Además el precio se copia en la línea al vender: si mañana sube el producto, la venta de hoy conserva su precio. En código es una entidad con dos @ManyToOne, y la cabecera la lista con @OneToMany(mappedBy = ..., cascade = ALL, orphanRemoval = true), de modo que cabecera y líneas se graban en una sola transacción.

Integrante Lado A Tabla del medio Lado B Dato propio
Yoel PROFORMAS ITEMS_PROFORMA PRODUCTOS cantidad, precio, descuento
Yoel VENTAS DETALLE_VENTA PRODUCTOS cantidad, precio, descuento
Wilson COMPRAS DETALLE_COMPRA PRODUCTOS cantidad, precio de compra
Aron COBROS DETALLE_COBRO VENTAS monto abonado
Servicios ORDENES_TRABAJO MATERIALES_ORDEN PRODUCTOS cantidad, costo del material

DETALLE_COBRO une cobros con ventas: un cobro puede pagar varias ventas (una transferencia por dos facturas) y una venta puede recibir varios cobros (paga en partes). El saldo de una venta es su total menos la suma de sus filas en DETALLE_COBRO.

En la SPA cada fila de la tabla intermedia es una fila del FormArray: "Agregar línea" en Proforma, Venta y Compra, y las filas de abono del diálogo "Registrar cobro".

Sectores del producto

Cada producto tiene uno de 5 sectores fijos. A diferencia de la categoría (libre, solo para ordenar el catálogo), el sector decide qué reglas le aplica el sistema:

Sector Ejemplos ¿Controla stock? ¿Programa mantenimientos al venderse?
CLIMATIZACION aires split, cassette, piso-techo No Si el vendedor elige una rutina (botón "Implementar rutinas de mantenimiento")
REFRIGERACION cámaras frigoríficas, condensadoras No Igual que climatización
VENTILACION_FORZADA extractores, inyectores No No
MATERIAL_SERVICIO tubería de cobre, gas, manómetros Sí No
SERVICIO instalación, mantenimiento, reparación (mano de obra) No No (la venta lleva detracción si supera S/ 700)

Los equipos se compran por proyecto y no se almacenan (acuerdo con el cliente), por eso no llevan stock: en la lista de productos su stock se ve como "—", una compra no lo sube y una venta no lo exige; en el kardex figuran sin saldo. Solo los materiales suben con las compras, bajan con las ventas, vuelven al anular y generan alertas de stock mínimo (Producto.controlaStock()). Si la venta incluye al menos un equipo de climatización o refrigeración, aparece el botón "Implementar rutinas de mantenimiento": el vendedor elige la frecuencia, las visitas y la primera fecha, y Postventa las programa (VentaService.validarRutina, MantenimientoService.programarParaVenta).

El precio de venta que muestra el catálogo (sin IGV) es costo_base × (1 + margen_porcentaje / 100), en la moneda del producto. Comprar no lo cambia: la compra guarda en el producto su último costo de compra (sin IGV) y, si supera el costo del catálogo, Ventas y Proformas lo avisan en la línea; quien tenga permiso puede editar el precio de esa línea (solo subirlo, con motivo) y la rentabilidad usa ese último costo (auditoría M1, 08/11/2026). El precio de compra de cada factura (lo que se le pagó al proveedor) se guarda aparte, en DETALLE_COMPRA, y es el que aparece como "c/u" en el historial del proveedor.

API REST (v1)

Recurso Endpoints
Autenticación Token: POST http://localhost:38080/realms/bomerp/protocol/openid-connect/token (Keycloak) · GET /api/v1/auth/perfil (sub, usuario, correo y roles leídos del JWT) · Swagger: botón Authorize con el access_token
Tipo de cambio GET /api/v1/admin/tipo-cambio?fecha= (SUNAT vía apis.net.pe; compra y venta, S/ por US$)
Catálogo público GET /api/v1/publico/catalogo (sin login, sin costo ni margen)
Categorías GET, POST /categorias · GET, PUT, DELETE /categorias/{id}
Productos GET /productos?categoriaId= · GET /productos/{id} · POST /productos · PUT /productos/{id} · DELETE /productos/{id} (409 si ya se usó en ventas, proformas o compras)
Clientes CRUD /clientes (GET, GET /{id}, POST, PUT, DELETE → 409 si tiene proformas o ventas) · GET /clientes/autocompletar/ruc/{ruc} · GET /clientes/autocompletar/dni/{dni}
Proveedores GET, POST /proveedores · GET, PUT, DELETE /proveedores/{id} · autocompletar RUC/DNI
Proformas GET /proformas?estado=&clienteId= · POST /proformas (ítems con descuentoPorcentaje) · POST /proformas/{id}/aceptar · /rechazar · /enviar (devuelve qué canal salió) · POST /proformas/marcar-vencidas (vencimiento manual; corre solo cada día)
Ventas GET /ventas?estado=&desde=&hasta=&clienteId= · GET /ventas/exportar (Excel, mismos filtros) · GET /ventas/historial-cliente/{clienteId} · POST /ventas/directa · POST /ventas/desde-proforma/{id} · GET /ventas/pagos-atrasados · PATCH /ventas/{id}/anular
Compras GET /compras?desde=&hasta=&proveedorId= · GET /compras/exportar (Excel) · GET /compras/historial-proveedor/{proveedorId} · GET /compras/{id} · POST /compras (sube el stock solo de materiales; 400 si cantidad < 1, precio ≤ 0, fecha futura o N° de factura sin formato SERIE-NÚMERO; 409 si esa factura del proveedor ya existe)
Cobranza GET /cobranza/por-cobrar?clienteId= (saldo por venta) · GET /cobranza/cobros?clienteId=&ventaId= · POST /cobranza/cobros · POST /cobranza/cobros/{id}/anular (solo ADMIN; body {motivo}) · GET /cobranza/ventas/{ventaId}/pagado (lo que se devolvería al anular) · GET /cobranza/devoluciones?estado=&clienteId= · POST /cobranza/devoluciones/{id}/registrar (solo ADMIN)
Descuentos GET /descuentos/tope (tope % del usuario actual)
Inventario GET /inventario/alertas · GET /inventario/kardex/{productoId}?desde=&hasta= · GET /inventario/kardex/{productoId}/exportar (Excel)
Servicios GET/POST /clientes/{id}/sedes · PUT/DELETE /clientes/{id}/sedes/{sedeId} (eliminar: ADMIN) · GET /equipos?clienteId=&sedeId=&estado=&enGarantia= · POST /equipos · PUT /equipos/{id} · POST /equipos/{id}/retirar (ADMIN) · GET /contratos?clienteId=&estado= · POST /contratos (ADMIN) · POST /contratos/{id}/cancelar (ADMIN) · GET /ordenes?estado=&clienteId=&tecnico=&desde=&hasta= · GET /ordenes/tecnicos · POST /ordenes · PUT /ordenes/{id} · POST /ordenes/{id}/cerrar · POST /ordenes/{id}/cancelar (ADMIN) · POST /ordenes/{id}/facturar
Postventa GET /mantenimientos?vista=VENCIDOS|PROXIMOS|REALIZADOS|TODOS&dias=&clienteId= · GET /mantenimientos/resumen · PATCH /mantenimientos/{id}/realizado · PATCH /mantenimientos/{id}/reprogramar · POST /mantenimientos/simular-alerta
Facturación POST /facturacion/emitir/{ventaId} · POST /facturacion/{id}/enviar · GET /facturacion/ventas/{ventaId}/pdf (descarga el comprobante) · GET /facturacion/notas-credito
Consultas (transitorio, por mover a ventas, cobranza y proformas) GET /reportes/ventas-resumen?desde=&hasta= · GET /reportes/cobranza · GET /reportes/proformas-pendientes

(Todas las rutas sin prefijo van bajo /api/v1/admin.)

Pruebas automáticas (JUnit 5 + Mockito)

mvn test corre 215 pruebas (08/11/2026). Las de reglas de negocio son unitarias: usan repositorios simulados (Mockito) y no necesitan Oracle, Keycloak ni Docker, así que tardan segundos. Las marcadas (Oracle) son de integración y necesitan la base encendida; todas deshacen lo que guardan. La trazabilidad de cada requisito con su prueba está en RTM.md.

Clase de prueba Qué protege Pruebas
CobranzaServiceTest Abono parcial y total, saldo, voucher duplicado, fechas, venta anulada; anular un cobro (motivo, dos veces, devoluciones) 9
CuentasPorPagarServiceTest Pagos a proveedores: saldo, contado, fechas, N° de operación, duplicado, compra PAGADA, anulación 8
AjusteInventarioServiceTest Conteo físico, merma, stock negativo, equipos, observación obligatoria 7
AuditoriaServiceTest Acción en palabras, "Intentó…" en lo denegado, módulo, resultado; nunca tumba la operación 6
PermisosServiceTest Permisos delegables: diferencia de roles, no a uno mismo ni a un ADMIN, permiso desconocido 6
AgendaHorarioTest Cruces de horario del técnico, bordes exactos, sin hora, medianoche, rango de la agenda 6
CompraServiceTest N° de factura, factura duplicada, stock solo de materiales, contado/crédito y vencimiento; subtotal e IGV de la compra y último costo del producto 5
AmbienteSunatTest El ambiente de SUNAT se declara y se comprueba contra la dirección oficial: producción y beta con sus direcciones; ambiente obligatorio; ambiente que no corresponde; 9 direcciones no oficiales bloqueadas (intermediario, http, imitación del servidor, otro puerto, parámetros…); el cliente no se construye con una configuración inválida 5
ReglasCorreoComprobanteTest Correo del comprobante: solo aceptados u observados en el ambiente de PRODUCCION registrado en el comprobante (no pendientes, rechazados, simulados, reemplazados, de la beta ni sin ambiente registrado) y el ambiente no cambia; destinatario válido; esperas entre reintentos; el XML leído con un analizador seguro (número, tipo, RUC del emisor, fecha, moneda, total y firma; rechaza DOCTYPE/XXE; no toca los bytes; lo que una búsqueda de texto aceptaba por error); nombres de SUNAT; plantilla HTML 14
NotificadorCorreoRealTest Contra un servidor SMTP de prueba en la misma PC: el PDF y el XML llegan con sus bytes exactos (en base64), se respeta el Message-ID; si el servidor rechaza, no responde o no está configurado, se informa el error 5
EntregaComprobanteIntegracionTest (Oracle) De punta a punta con SUNAT y SMTP simulados: aceptado → ENVIADO con PDF y XML del mismo comprobante; beta (aunque después el servidor pase a producción) y cliente sin correo no se envían; SMTP caído → FALLIDO y reintento; reinicio con pendientes; PDF que falla; XML ajeno; evento repetido; dos trabajadores a la vez; reenvío que pide confirmación; caída entre SMTP y Oracle → INCIERTO; conciliación de aceptados sin envío (respeta margen, ventana y correo); el ambiente no se cambia ni desde SQL; sin duplicados entre automático y manual (el reenvío cancela el reintento programado, un reintento no sale si otro envío ya se entregó, ni la conciliación ni el evento tardío duplican un envío manual) 17
PrecioDeLineaTest Auditoría M1 y M2: el precio de una línea solo sube, con permiso y motivo de 5 a 200 caracteres; texto del historial; la compra separa el IGV; el producto guarda el costo de la compra más reciente 5
TopeDescuentoServiceTest Topes de descuento: los iniciales, los que fija el administrador (rigen enseguida) y los rechazados (fuera de 0–100 o asistente mayor que administrador) 3
PrecioEditadoIntegracionTest (Oracle) La compra separa el IGV y deja el último costo sin tocar el precio; la venta usa ese costo; con permiso sube el precio y guarda las dos cifras; sin permiso, para bajarlo o sin motivo no se registra; el precio editado en la proforma pasa a la venta 4
DeduccionTributariaServiceTest Detracción 12 % (soles enteros), retención 3 %, umbral S/ 700, dólares con tipo de cambio 5
FechaVentaYAnulacionTest Auditoría M3 y M4: sin fecha o con la de hoy no pide permiso; con permiso hasta 30 días atrás; nunca futura; sin permiso, 403; anular sin motivo o con menos de 5 caracteres no toca la venta 5
VentaFechaPasadaIntegracionTest (Oracle) Venta con fecha de hace 10 días: el crédito corre desde ese día y la factura sale hoy; la asistente necesita el permiso; al anular, la venta guarda quién y por qué 3
VentaDirectaValidacionTest Auditoría B9: POST /ventas/directa sin forma de pago, sin cliente, sin productos o con una línea sin producto o con cantidad 0 responde 400 con el campo y el motivo, sin registrar nada (antes, sin tipoPago quedaba como contado) 3
VentaCostoTest Costo guardado en cada línea y su conversión de moneda; subtotal, IGV y total 5
RentabilidadServiceTest Ganancia en soles, líneas sin costo, rentabilidad por técnico 4
StockProductoTest Stock: suma de líneas repetidas, todo o nada, bloqueo en orden de id, equipos sin stock, editar un producto no cambia su stock 6
ModularityTests (Spring Modulith) Límites entre módulos y ausencia de ciclos (ADR-002); genera el diagrama de módulos 2
ProductoCrudTest (integración, Oracle) Guardar, buscar y actualizar un producto 3
FlujoCompletoEndToEndTest (punta a punta, Oracle) S14: producto → proforma → venta con rutina → comprobante → visitas → reporte paginado = suma manual → cobros → 401/403 → anulación → auditoría, sin mocks 1
RutinaMantenimientoIntegracionTest (Oracle) Venta real: con rutina se programan sus visitas, sin rutina ninguna 2
RutinaMantenimientoTest Rutina de mantenimiento: solo con equipos, rangos, primera fecha 5
ClasificacionCodigosSunatTest Qué hace SGE-JD con cada código de SUNAT (incluido 0101-0106: usuario o clave SOL) y lectura de faultcode 20
DetraccionSinCuentaTest Sin la cuenta de detracciones, una venta con detracción no puede emitirse todavía; con cuenta, o sin detracción, sí; solo la SUNAT de producción da validez, la beta no 3
EnvioSunatServiceTest Envío a SUNAT: aceptado, observado, rechazado, sin respuesta, "ya registrado" (1033) sin validez, nota de crédito, reintentos y reenvío; cada respuesta queda en el historial sin pisar la anterior; un rechazo con CDR o un comprobante reemplazado no se reenvía; plazo de 3 días (cuándo vence, a qué estados aplica) y lo que pasó el plazo no se envía ni se reenvía; usuario o clave SOL rechazados detienen todos los envíos; una factura no se reenvía si el cliente ya no tiene RUC; el comprobante de una venta anulada no sale sin su nota. Cada prueba espera a que su cola de envíos termine (auditoría B10) 25
CorreoComprobanteTest Al cliente solo se le envía por correo un comprobante aceptado por SUNAT; nunca uno pendiente, rechazado, del modo simulado ni aceptado por la beta 5
ReintentoSunatIntegracionTest (Oracle) 25 comprobantes con los intentos agotados al principio de la lista no tapan al siguiente pendiente; uno por confirmar (1033) o fuera de plazo no se reintenta, y uno emitido hace justo 3 días sí 1
ComprobanteReemplazoIntegracionTest (Oracle) Reemplazo de un rechazado: número nuevo para la misma venta sin tocar stock, cobro ni mantenimientos; solo rechazos definitivos, no dos veces, no en ventas anuladas; Oracle admite un solo comprobante vigente por venta; receptor y descripción quedan como se emitieron; una excepción reenviada toma el dato corregido; un pendiente fuera de plazo se reemplaza y la campana lo avisa; si el cliente cambió de tipo, no se reenvía y el reemplazo sale del tipo correcto 9
VentaPorEmitirIntegracionTest (Oracle) Venta con detracción sin cuenta: se guarda sin comprobante ni número, Ventas y la campana la muestran por emitir, emitirla a mano responde 409; al configurar la cuenta se emite sola con fecha de hoy; anulada, ya no se emite 2
VentaAnuladaSinNotaIntegracionTest (Oracle) El caso de la venta #285: venta anulada sin nota → la nota se crea antes de enviar la factura; una anulación normal no la duplica 2
OrdenTest Orden por columna: texto en español, números, vacíos al final, dólares en soles 4
SunatBetaTest (beta real de SUNAT) Factura, boleta y nota aceptadas y un rechazo real; solo corre con SUNAT_BETA=1 0 por defecto

La seguridad por rol y permiso se prueba además de punta a punta con pruebas-seguridad/05_matriz.ps1 (14 casos, con Keycloak y el backend encendidos).

Integración continua (GitHub Actions, 07/11/2026)

Cada git push prueba el código solo, sin depender de que alguien corra la suite a mano. El resultado se ve en GitHub, pestaña Actions (en verde o en rojo, con el resumen de cada clase de prueba).

Flujo Rama Qué hace
Backend (.github/workflows/backend.yml) master Java 21: compila y corre las 171 pruebas que no necesitan Oracle (~20 s). Si falla, guarda los informes de Surefire
Frontend (.github/workflows/frontend.yml, en la rama frontend) frontend Node 24: npm ci, npm audit --omit=dev --audit-level=high (falla con una vulnerabilidad alta), npm run build:prod (con la verificación de la CSP) y las 33 pruebas del frontend
Documentación (docs.yml) master Publica este sitio (solo si cambia docs/ o sitio/)

Pruebas del frontend (Vitest, npx ng test --watch=false): las reglas de pantalla del comprobante electrónico viven en funciones puras para poder probarlas solas. sunat-documento.spec.ts (16): etiquetas (aceptado, simulado, rechazo con CDR frente a "no recibido", 1033 por confirmar, fuera de plazo, reemplazado), cuándo se ofrece Reenviar o el reemplazo y por qué, el aviso del plazo con la fecha local y el orden de las líneas de la venta. avisos-facturacion.spec.ts (5): los avisos de la campana por vencer, fuera de plazo, envíos detenidos y ventas por emitir. fecha-venta.spec.ts (3): la fecha real de la venta (hoy, hasta 30 días atrás, nunca futura, en hora local). precio-editado.spec.ts (3): el precio editado (solo sube, con motivo), su texto y el aviso de la última compra. entrega-correo.spec.ts (5): el estado del correo (distinto del de SUNAT), el ambiente en que se aceptó, cuándo se ofrece reenviar y la confirmación cuando ya se envió o quedó por confirmar.

Las 10 clases marcadas @Tag("oracle") (las de integración y la punta a punta, 44 pruebas) usan la base de desarrollo con sus datos, que no existe en GitHub: la integración continua las salta (-DexcludedGroups=oracle) y se corren en la PC con mvn test, que sigue corriendo las 215. Las pruebas leen además src/test/resources/config/application.properties, que apaga las tareas programadas (reintento a SUNAT y revisión de correos) para que un contexto de Spring que queda vivo no envíe nada a la beta por su cuenta. Los cambios solo de documentación (docs/, *.md) no disparan las pruebas.

Guía de instalación

  1. Instalar JDK 21, Maven y Docker Desktop.
  2. Base de datos Oracle en Docker (desde la carpeta que contiene docker-compose.yml):
  3. Primera vez: docker volume create sge-jd-oracle-data y luego docker compose up -d.
  4. Si el contenedor ya existe: docker start SGE-JD.
  5. Esperar a que docker logs SGE-JD muestre DATABASE IS READY TO USE!.
  6. Credenciales locales: copiar src/main/resources/application-local.properties.example como application-local.properties (está en .gitignore) y completar al menos:
    spring.datasource.password=<APP_USER_PASSWORD del docker-compose>
    
    También se aceptan variables de entorno: DB_URL, DB_USERNAME, DB_PASSWORD, MAIL_USERNAME, MAIL_PASSWORD, DECOLECTA_TOKEN, CORREO_OFICINA, CORS_ALLOWED_ORIGINS, EMPRESA_TELEFONO, EMPRESA_CORREO, EMPRESA_WEB y, para SUNAT, FACTURACION_MODO, SUNAT_AMBIENTE (obligatorio en modo sunat), SUNAT_URL, SUNAT_USUARIO, SUNAT_CLAVE, SUNAT_CERT_RUTA, SUNAT_CERT_CLAVE.
  7. Ejecutar mvn spring-boot:run (puerto 8080). Swagger: http://localhost:8080/swagger-ui.html.
  8. Probar la API en Swagger: sin token todo responde 401. Para tener uno:

    1. En PowerShell, desde bomerp-backend\pruebas-seguridad, ejecutar . .\comun.ps1; Get-Token lisandro | Set-Clipboard. Toma la clave de .env y copia el token al portapapeles sin mostrarlo; con lucy se prueba como asistente.
    2. En Swagger, botón Authorize → pegar el token en Value (solo el token: Swagger agrega Bearer) → Authorize → Close.
    3. En cualquier endpoint: Try it out → Execute.

    El token dura 5 minutos: cuando vuelvan los 401, repetir el paso 1. Swagger solo existe en dev; en el perfil prod está apagado (/swagger-ui responde 404). - Identidad (Keycloak): docker compose up -d keycloak-db keycloak (desde bomerp-backend). Antes, copiar .env.example como .env (no se versiona) y poner las contraseñas: las usan docker compose, configurar_realm.py y pruebas-seguridad/. La primera vez Keycloak importa keycloak/realm-bomerp.json (realm, roles, clientes y usuarios, sin contraseñas); después ejecutar python keycloak/configurar_realm.py, que pone las contraseñas de .env (y crea el realm si no existe), los roles de permiso PERM_* y el cliente confidencial sgejd-backend (cuenta de servicio con view-users, manage-users, view-realm y view-events, secreto KC_BACKEND_SECRET de .env, que el backend lee como app.keycloak.admin.client-secret): con él el backend cambia los permisos delegados y lee los eventos de sesión. Historial de cambios: tabla HISTORIAL_CAMBIOS (migracion_historial_cambios.sql), escrita por AuditoriaFilter dentro de la cadena de seguridad, después de leer el token y antes de autorizar, para registrar también los 403. Consola: http://localhost:38080 (usuario admin, contraseña KC_ADMIN_PASSWORD de .env). Usuarios: lisandro (ADMIN) y lucy (ASISTENTE). Pruebas: pruebas-seguridad/05_matriz.ps1. - Bases creadas antes del 08/11/2026, tercera migración (ambiente de emisión): ejecutar una vez migracion_ambiente_emision.sql, después de la de correo (columna AMBIENTE_EMISION en COMPROBANTES con su restricción y el disparador que impide cambiarla, y AMBIENTE en ENVIOS_SUNAT; los ya aceptados quedan SIMULADO si no tienen XML y NO_REGISTRADO si lo tienen; solo agrega, se puede ejecutar varias veces). - Bases creadas antes del 08/11/2026, segunda migración (entrega del comprobante por correo): ejecutar una vez migracion_envio_correo.sql (tablas ENVIOS_CORREO e INTENTOS_CORREO y sus índices; solo crea, no borra nada; se puede ejecutar varias veces). - Bases creadas antes del 08/11/2026 (IGV de compras, último costo, precio editado y topes): ejecutar una vez migracion_costos_precios.sql (subtotal e IGV en COMPRAS, calculados para las ya registradas; último costo de compra en PRODUCTOS, tomado de la compra más reciente en su moneda; precio de catálogo, quién y por qué en DETALLE_VENTA e ITEMS_PROFORMA; tabla TOPES_DESCUENTO; se puede ejecutar varias veces). Después, python keycloak/configurar_realm.py (con --prod en producción) crea el permiso PERM_EDITAR_PRECIO. - Bases creadas antes del 07/11/2026 (quién anuló una venta): ejecutar una vez migracion_venta_anulacion.sql (columnas ANULADO_POR y MOTIVO_ANULACION en VENTAS; en las ya anuladas, quién lo hizo sale del historial de cambios; se puede ejecutar varias veces). Después, python keycloak/configurar_realm.py (con --prod en producción) crea el permiso PERM_VENTA_FECHA_PASADA. - Bases con la tabla USUARIOS (anteriores al 07/11/2026): ejecutar una vez migracion_quitar_usuarios.sql (la borra solo si está vacía; se puede ejecutar varias veces). - Bases creadas antes del 07/11/2026 (comprobante de reemplazo): ejecutar una vez migracion_comprobante_reemplazo.sql (datos del receptor y estado de reemplazo en COMPROBANTES, descripción en DETALLE_VENTA, tabla ENVIOS_SUNAT con el último envío de cada documento ya guardado; los comprobantes emitidos toman el receptor de los datos actuales del cliente; se puede ejecutar varias veces). - Bases creadas antes del 28/10/2026 (servicios): ejecutar una vez migracion_servicios.sql, después de migracion_cobros_anulacion.sql (sector SERVICIO, agente de retención, deducción de las ventas, métodos DETRACCION/RETENCION, sedes, órdenes de trabajo, equipos instalados, contratos y las columnas nuevas de MANTENIMIENTOS; se puede ejecutar varias veces). - Bases creadas antes del 28/10/2026: ejecutar una vez migracion_cobros_anulacion.sql (columnas de anulación y registrado_por en COBROS; los cobros existentes quedan VIGENTES; se puede ejecutar varias veces). - Bases creadas antes del 25/10/2026: ejecutar una vez migracion_devoluciones.sql (crea la tabla DEVOLUCIONES; se puede ejecutar varias veces). - Bases creadas antes del 15/10/2026: después de arrancar el backend nuevo una vez, ejecutar migracion_auditoria_altos.sql (permite el estado CONVERTIDA de las proformas; sin él, convertir una proforma falla con ORA-02290). Se puede ejecutar varias veces. - Datos de demostración (opcional, 11/11/2026): scripts\datos_demo.bat deja la base de desarrollo como nueva. Pide escribir BORRAR, saca un respaldo y ejecuta: - datos_demo.sql: borra todos los datos de negocio de todos los módulos, reinicia los ID y carga 8 categorías, 30 productos, 7 proveedores y 8 clientes (empresas reales verificadas en SUNAT; relación comercial ficticia); - datos_demo_ventas.sql: 20 ventas por año (2024, 2025 y 2026), cada una con su factura F001 aceptada (simulado). Dos de cada tres son al contado; las de crédito tienen sus cobros, salvo una atrasada y una con abono parcial en 2026. Una de cada cuatro viene de una proforma, hay una anulada por año con su nota de crédito, y los equipos tienen sus visitas de mantenimiento. El stock lo dan las compras de enero de cada año.

    No toca los usuarios (Keycloak). Necesita el backend iniciado al menos una vez, para que existan las tablas.

    .\scripts\datos_demo.bat
    
    5. Frontend: en bomerp-frontend, npm install y npm start (puerto 4200).

Uso diario: encender, apagar, respaldar y limpiar (scripts/)

Ya instalado (pasos 1 a 5 hechos una vez), todo se maneja con doble clic en bomerp-backend/scripts/. Suponen que bomerp-backend y bomerp-frontend están en la misma carpeta (si no, -Frontend <ruta>).

Archivo Qué hace
iniciar_sgejd.bat Enciende Docker Desktop si hace falta, Oracle (SGE-JD), Keycloak (keycloak-db keycloak), el backend y el frontend en dos ventanas propias; espera a que cada uno responda y abre http://localhost:4200. Lo que ya está encendido lo deja como está. Desde cero tarda unos 85 s
detener_sgejd.bat Apaga frontend, backend, Keycloak y Oracle; los datos quedan. -Simular muestra qué apagaría; -DejarBaseDatos deja Oracle y Keycloak
respaldar_sgejd.bat Respaldo completo del esquema con Data Pump (expdp) en C:\SGE-JD\respaldos\sgejd_AAAAMMDD_HHMM.dmp (fuera de los repositorios)
programar_respaldo.bat [-Destino <carpeta>] [-Hora 18:30] [-Conservar 14] Crea la tarea de Windows "SGE-JD respaldo diario" que ejecuta respaldo_automatico.ps1: respaldo, copia a -Destino (fuera de la PC) y borra los más antiguos. La tarea respalda solo producción (sge-jd-oracle-prod); si ese día está apagada lo anota como aviso (-Contenedor SGE-JD o auto solo para probarla en desarrollo). Los archivos se llaman sgejd_diario_prod_… o sgejd_diario_dev_… y solo esos se rotan (los manuales, como sgejd_antes_de_…, nunca se borran solos). -Quitar la elimina. Registro en respaldos\respaldo_automatico.log
base_limpia.bat Borra los datos marcados [Prueba] y todo lo que cuelga de ellos (proformas, ventas, comprobantes, cobros, compras, mantenimientos) y devuelve al stock lo que movieron. Primero hace un ensayo con ROLLBACK que muestra cuántas filas borraría, pide escribir BORRAR y saca un respaldo; si algo falla, Oracle deshace todo
base_limpia.bat -Entrega Deja la base para el cliente: borra todos los movimientos y lo marcado [Prueba], reinicia las series de comprobantes y los contadores de id de los movimientos. Conserva catálogo, clientes y proveedores reales; el stock se ajusta después con el inventario físico
base_limpia.bat -SoloEnsayo Solo el ensayo, sin cambiar nada (también con -Entrega)
datos_demo.bat Solo desarrollo: deja la base como nueva con datos de demostración (catálogo, clientes, proveedores y 20 ventas por año de 2024 a 2026). Pide escribir BORRAR y respalda antes
restaurar_sgejd.bat <archivo.dmp> Vuelve la base al estado de un respaldo: reemplaza las tablas de JDREFRIGERACION por las del archivo (pide escribir RESTAURAR y antes saca un respaldo de lo actual). Apagar antes el backend. En producción: -Contenedor sge-jd-oracle-prod

Probado (25/10/2026): un respaldo restaurado en un esquema aparte (-Esquema) trajo las 17 tablas con los mismos conteos.