chore: import DH V2 D5.6.4 production baseline

2026-09-05 10:12:35 -03:00
commit 82213e72f5
757 changed files with 84218 additions and 0 deletions
@@ -0,0 +1,134 @@
+# 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.