12. Buenas prácticas y errores comunes

Este tutorial no introduce conceptos nuevos: reúne, en un solo lugar, las reglas y los errores reales que los tutoriales anteriores fueron citando por separado — la mayoría, encontrados por el equipo de FINORA LVE ejecutando código real contra un servidor de desarrollo, no supuestos en abstracto.

Regla 1: nunca se modifica el core

Es la regla absoluta del proyecto (finora-lve/AGENTS.md, regla 1): todo cambio es un plugin OSGi, un 2Pack, un event handler, una fábrica, un reporte Jasper o un parámetro de configuración. Cualquier excepción exige una decisión de arquitectura (ADR) aprobada explícitamente. Esto no es solo disciplina — es lo que permite actualizar iDempiere sin heredar un fork propio que hay que fusionar a mano en cada versión.

Regla 2: resolver por UUID, Value o nombre — nunca por ID numérico

Un AD_Table_ID, AD_Column_ID o cualquier otro ID numérico no es el mismo número en desarrollo, en el servidor de DC GEEKS y en el de un cliente — cada base de datos asigna sus propios IDs (ver Tutorial 8). El código de FINORA LVE tiene prohibido usar un AD_*_ID literal (finora-lve/packout/README.md, regla 3); todo objeto se busca por su UUID, por su Value (código de negocio) o por el nombre de tabla/columna.

Regla 3: transacciones — y sus trampas de runtime reales

Trampas encontradas en desarrollo (finora-lve/docs/ARCHITECTURE.md, §4.3)

• Una tabla de core sin clase Doc_ propia (por ejemplo HR_Process, que el core define pero no contabiliza) falla con “Doc Class invalid” si CLIENT_ACCOUNTING=I y el documento se completa normalmente: DocumentEngine intenta contabilizarlo. La salida es marcar DocumentEngine.DOCUMENT_POST_IMMEDIATE_AFTER_COMPLETE=false antes de processIt y marcar el propio documento Posted=Y, si la contabilización la hace un motor propio (ver ADR-LVE-012 sobre el GL_Journal nativo de nómina).
• Las líneas de GL_Journal rechazan cuentas IsDocControlled=Y. El setup de un tenant debe mapear, para asientos manuales, solo cuentas que no estén controladas por otro tipo de documento.
• Completar un documento actualiza el contacto asociado (AD_User.LastContact) con el usuario de la sesión si no se especifica otro — operar como un usuario de otro tenant dispara “Cross tenant PO writing” (ver Tutorial 4 y Tutorial 10).
• Una tasa de cambio aprobada y ya usada por un documento es inmutable: una corrección nunca “desaprueba” la tasa existente, siempre crea una tasa nueva — de lo contrario, un documento ya contabilizado con la tasa vieja quedaría inconsistente con el nuevo valor.
• Un proceso de servidor que genera un Jasper dentro de su propia transacción debe llamar ServerProcessCtl.process(pi, trx, false) — el último argumento (managedTrx=false) le dice al core que el proceso, no el motor de procesos, decide cuándo hacer commit o rollback de esa transacción. Con managedTrx=true (o sin pasar el argumento), el core haría commit de la transacción del proceso en cuanto termine, incluso si el reporte todavía no terminó de leer los datos dentro de ella — la auditoría de buenas prácticas confirmó que FINORA aplica esta lección correctamente en los tres lugares donde imprime un reporte fiscal desde su propia transacción (ver más abajo).

Regla 4: seguridad multi-tenant, tanto en código como en configuración de REST

• Nunca se asume que el usuario de sesión pertenece al tenant que se está modificando: cualquier operación de escritura debe validar o fijar explícitamente el AD_Client_ID/AD_Org_ID esperado.
• Por defecto, cualquier rol autenticado puede leer casi cualquier tabla por REST salvo que exista una exclusión explícita en AD_Table_Access (ver Tutorial 10). Para una integración real, esto exige un rol de integración dedicado con exclusiones configuradas, no el rol de administrador general.
• Los parámetros de configuración de un tenant nunca van en AD_SysConfig desde el propio plugin de localización — ese camino ni siquiera está disponible por REST para un rol de tenant. FINORA LVE los guarda en su propia tabla FVE_Config (ver Tutorial 4).

Regla 5: trampas conocidas de PostgreSQL al aplicar un 2Pack

finora-lve/packout/README.md, regla 6

• No nombrar un índice <Tabla>_Key: iDempiere ya usa ese nombre exacto para la restricción de clave primaria; Pack In falla con “cannot drop index … constraint requires it” y PostgreSQL revierte toda la importación de esa versión, no solo el índice conflictivo.
• Las filas de datos no van en el mismo 2Pack que crea su tabla. MSequence.getNextID lee el AD_Sequence nuevo fuera de la transacción del pack-in, y falla con “No record found” si la tabla se creó en la misma versión. La convención de FINORA es: diccionario en x.y.0, datos en x.y.1.
• Una tabla con vigencia por fecha (ValidFrom) se consulta siempre por la fecha del hecho de negocio, nunca por “la fila activa hoy” — de lo contrario, reconstruir un período pasado (una factura vieja, una declaración) usaría parámetros vigentes hoy en vez de los vigentes cuando ocurrió el hecho.

Regla 6: marcar lo no verificado, en vez de inventarlo

Toda regla fiscal o laboral cita su norma exacta (ley, providencia, artículo, Gaceta) tanto en el spec como en un comentario del código (finora-lve/AGENTS.md, regla 3). Lo que no se pudo confirmar contra la norma o un servidor real se marca explícitamente — en FINORA LVE, con [UNCERTAIN] o [DEV-UNVERIFIED] en la documentación técnica; en esta Academy, con el aside Por verificar que verás en varios tutoriales de esta sección. Tratar una suposición como un hecho confirmado es, en la práctica de este proyecto, el error más caro de corregir después — sobre todo en reglas fiscales, donde una fecha de vigencia mal asumida puede invalidar meses de documentos ya emitidos.

La auditoría independiente: ¿la forma de extender iDempiere es correcta?

Agent 01 (investigación técnica de iDempiere en FINORA) hizo, el 24 de septiembre de 2026, una auditoría de solo lectura de cómo FINORA LVE y FINORA ERP Experience extienden iDempiere 13, comparando cada práctica contra el wiki oficial, el código del core (release-13 @ 0bbc4fa) y el foro de la comunidad (finora-erp-experience/research/IDEMPIERE_BEST_PRACTICES_AUDIT.md). No se cambió ni una línea de código para hacerla — es evaluación, no un plan de trabajo ejecutado.

Veredicto general: sí, la forma de extender iDempiere es correcta — 8,1/10. Ninguno de los hallazgos pide rediseñar nada; los pendientes son trabajo acotado (3 a 4 días-persona para los más urgentes).

Dimensión auditada	Veredicto	Nota
a. Sin cambios de core y fronteras OSGi	Alineado	9,0
b. Diccionario: 2Pack incremental	Mejor que lo habitual (con un pendiente)	8,5
c. Lógica de negocio y transacciones	Alineado	8,5
d. Configuración por REST, setup de tenant	Alineado, con una desviación justificada	8,0
e. Reportes Jasper	Alineado	8,5
f. Extensión de la UI ZK	Alineado en LVE / parcial en el menú de ERP Experience	7,5
g. Pruebas, multi-tenant, seguridad, rendimiento	Parcial (las pruebas: mejor que lo habitual)	7,5
h. Ruta a iDempiere 14 y distribución	Parcial, con desviación justificada	7,0

Lo que la auditoría confirma que FINORA hace mejor que la práctica habitual

• 2Pack inmutable por herramienta: el candado sha256 por bundle y la regla de “versión quemada” (ver Tutorial 8) los hace cumplir el build y el despliegue, no solo la convención — casi ningún proyecto de la comunidad lo automatiza así.
• UUID determinísticos (uuid5) generados desde specs: regenerar el 2Pack no cambia identidades, y el XML resultante se puede revisar en un diff antes de publicarlo.
• Orden de pack-in entre bundles (LvePackActivator, ADR-LVE-014): el core de iDempiere no resuelve esto — cada bundle instala su 2Pack en el pool de hilos sin esperar a los demás — así que el mecanismo de FINORA podría proponerse como mejora a la comunidad.
• Retiro limpio y verificable: un uninstall-dictionary.sql generado de los mismos 2Pack, con ensayo por defecto en una transacción revertida, y una paridad de base de datos que exige cero diferencias entre desarrollo y una instalación limpia.
• Dominio hexagonal sin servidor: las reglas fiscales y laborales se prueban en segundos, con goldens que citan la norma legal exacta — aislado de los cambios de API entre versiones de iDempiere.

Lo que la auditoría deja como pendiente real (no como error de diseño)

Cuatro huecos reales, según la auditoría — ninguno pide rediseñar

1. El orden de pack-in (ADR-LVE-014) está bien diseñado (sin interbloqueo con el lock del core, sin agotar el pool de hilos) pero todavía le falta su propia evidencia de aceptación: cinco instalaciones limpias seguidas sin advertencias graves.
2. El endurecimiento de acceso REST por recurso (ADR-005) está aceptado como decisión pero no aplicado: la tabla que limita qué puede leer cada rol por REST sigue vacía, así que hoy “cualquier rol autenticado puede leer casi cualquier tabla” (Regla 4 de este tutorial) es la situación real, no solo un caso límite teórico.
3. En FINORA ERP Experience, el menú y sus 94 entradas se aplicaron con SQL directo y un tipo de entidad de personalización (U) en vez de viajar en un 2Pack propio — funciona en el servidor de DC GEEKS, pero no se instalaría solo con el plugin en un servidor de un tercero.
4. Deuda menor de código: un lector de configuración que no usa la caché central, y algunas consultas SQL que comparan directamente contra columnas _UU, un patrón que dejará de funcionar tal cual cuando iDempiere 14 cambie esas columnas de texto a un tipo UUID nativo de PostgreSQL.

Estos cuatro puntos no contradicen ninguna regla de este tutorial — son, más bien, la prueba de que “marcar lo no verificado” (Regla 6) también aplica puertas adentro: la auditoría existe precisamente para que estos pendientes queden escritos y priorizados, no descubiertos en producción.

Fuentes

• finora-erp-experience/research/IDEMPIERE_BEST_PRACTICES_AUDIT.md (Agent 01, 2026-09-26; commits b8c7efd y 35d4007) — auditoría completa, con evidencia de código y wiki citada punto por punto
• finora-lve/AGENTS.md (reglas 1, 3 y 7)
• finora-lve/docs/ARCHITECTURE.md, §4.3 (trampas de runtime comprobadas en desarrollo)
• finora-lve/packout/README.md, reglas 3 y 6 (UUID estables, trampas de PostgreSQL en 2Pack)
• finora-erp-experience/idempiere/API_MAP.md, §6.2 y §7.2 (Cross tenant PO writing, permisos por defecto en REST)