dh-inspeccion-v2/docs/PHASE_D5_4.md

Fase D5.4 · Hallazgos aplicables al Inventario

Objetivo

Hacer que el catálogo de hallazgos deje de ser una lista universal y pase a responder al elemento concreto que se inspecciona, sin perder compatibilidad con el funcionamiento actual ni alterar hallazgos históricos.

D5.4 incorpora tres niveles separados:

1. catálogo institucional de hallazgos;
2. aplicabilidad por tipo técnico de Inventario;
3. excepción explícita por registro concreto del Inventario.

También separa la gravedad sugerida por catálogo de la gravedad real observada en una inspección y formaliza OTROS como propuesta administrable desde oficina.

Compatibilidad controlada

Un tipo técnico que todavía no tenga una configuración explícita continúa viendo todos los ítems activos del catálogo. El API informa que ese tipo está configured: false para que oficina pueda distinguir el estado transitorio.

En cuanto oficina guarda la primera configuración del tipo, sólo quedan habilitados los ítems seleccionados para ese tipo. Las excepciones por registro concreto se aplican encima de esa selección.

De este modo el despliegue no deja a la APK o a la web sin catálogo mientras Hidrocarburos completa la parametrización inicial.

Aplicabilidad por tipo técnico

Nuevas estructuras:

• finding_catalog_asset_type_profiles: marca que un tipo técnico ya fue configurado y conserva el motivo de la última decisión;
• finding_catalog_item_asset_types: relación entre cada ítem de catálogo y los tipos técnicos para los que resulta aplicable.

Administración:

• GET /api/v3/finding-catalog/asset-types/:assetTypeId/selection
• PUT /api/v3/finding-catalog/asset-types/:assetTypeId/selection

El cambio requiere finding_catalog.manage y queda auditado.

Excepciones por objeto concreto

Nueva tabla finding_catalog_asset_overrides.

Sólo guarda diferencias respecto de la regla del tipo técnico. Un registro concreto puede habilitar un hallazgo normalmente deshabilitado para su tipo o excluir uno normalmente habilitado.

Administración:

• GET /api/v3/finding-catalog/assets/:assetId/selection
• PUT /api/v3/finding-catalog/assets/:assetId/selection

La ficha de Inventario incorpora la pestaña Hallazgos aplicables con la regla heredada del tipo y las excepciones del objeto.

Catálogo aplicable en campo

Nuevo endpoint:

• GET /api/v3/finding-catalog/applicable/:assetId

Devuelve solamente categorías e ítems habilitados para el objeto concreto, junto con el estado de configuración del tipo y la opción OTROS.

La misma regla se valida al crear el hallazgo. Aunque un cliente antiguo intente enviar manualmente un catalogItemId no habilitado para ese objeto, el servidor responde FINDING_CATALOG_ITEM_NOT_APPLICABLE.

Si durante la edición de un hallazgo abierto se cambia el objeto inspeccionado, el servidor vuelve a validar la aplicabilidad del ítem de catálogo para el nuevo objeto.

Gravedad sugerida y gravedad real

finding_catalog_items.suggested_severity define una recomendación opcional de 1 a 10.

Cada inspection_findings conserva dos valores independientes:

• suggested_severity: copia congelada de la sugerencia vigente al momento de crear el hallazgo;
• severity: gravedad real asignada al hallazgo, también entre 1 y 10.

Si el inspector no indica una gravedad real al crear un hallazgo de catálogo, se usa la sugerida como valor inicial. El inspector puede corregirla mientras el acta siga editable.

Cambios posteriores en la gravedad sugerida del catálogo no modifican hallazgos anteriores. La gravedad queda incluida en las versiones del hallazgo, la instantánea congelada del acta y el Word automático del informe.

OTROS y propuestas de catálogo

Un hallazgo personalizado continúa permitido cuando el inspector encuentra una situación que no existe en el catálogo.

D5.4 crea automáticamente una fila en finding_catalog_proposals vinculada al hallazgo original, al objeto y al tipo técnico. La propuesta conserva:

• título propuesto;
• fundamento legal informado;
• gravedad propuesta;
• descripción;
• estado de revisión;
• decisión y usuario de oficina.

Estados:

• PENDING
• MATCHED
• REJECTED

Administración:

• GET /api/v3/finding-catalog/proposals
• PATCH /api/v3/finding-catalog/proposals/:id/review

Al marcar una propuesta como MATCHED, oficina la vincula a un ítem existente del catálogo. Si el tipo técnico ya estaba configurado, ese ítem se habilita para el tipo hacia adelante.

La decisión nunca modifica inspection_findings.catalog_item_id del hallazgo histórico que originó la propuesta. Ese hallazgo conserva exactamente la identidad con la que fue registrado en campo.

Backfill

La migración crea propuestas PENDING para hallazgos personalizados existentes que no tenían catalog_item_id.

No se infiere gravedad ni aplicabilidad histórica cuando no existe evidencia persistida para hacerlo.

Web de oficina

El Catálogo de Hallazgos incorpora:

• gravedad sugerida por ítem;
• configuración de aplicabilidad por tipo técnico;
• bandeja de propuestas OTROS pendientes.

El Maestro de Inventario incorpora:

• pestaña Hallazgos aplicables;
• visualización del default del tipo;
• excepción del objeto;
• motivo obligatorio para guardar cambios.

La ficha del hallazgo muestra gravedad real y gravedad sugerida.

Reglas preservadas

• Una visita = una Acta.
• El catálogo sigue versionado por revisiones.
• Hallazgos históricos no se reescriben por cambios de catálogo.
• Actas cerradas e informes congelados conservan su snapshot.
• Las verificaciones de D5.3.25 siguen siendo append-only.
• La primera respuesta de empresa continúa inmutable.
• SMTP puede continuar pendiente sin bloquear esta fase.