135 lines
5.7 KiB
Markdown
135 lines
5.7 KiB
Markdown
# 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.
|