Fase 2 – Gemelo Operativo Prodisys
==================================

.. contents:: Tabla de contenido
   :depth: 2
   :local:

## Resumen ejecutivo

Prodisys requiere un gemelo operativo que apoye el diseño y desarrollo de equipos (hidrociclones, aeroenfriadores, eductores) sin quedar acoplado a una interfaz única. Esta fase prioriza desacoplar la lógica de cálculo en un núcleo de dominio reutilizable, automatizar un pipeline de simulación e informes, y habilitar capacidades de búsqueda técnica y trazabilidad para acelerar diseño, validación y presentación a cliente.

### Resumen visual de hitos de la Fase 2

| Mes | Hito principal                             | Entregable                                     | Responsable             |
| --- | ------------------------------------------ | ---------------------------------------------- | ----------------------- |
| 1   | Desacople del núcleo de cálculo            | Librerías `prodisys.core` y `prodisys.calc`    | Ingeniería              |
| 2   | Pipeline OpenFOAM y generación de informes | Pipeline YAML y plantillas `.rst→PDF`          | Simulación / Ingeniería |
| 3   | Integración UI y exportación comercial     | CLI funcional, paquete Aleph                   | Ingeniería / Comercial  |
| 4   | Validación y trazabilidad                  | Tablero de auditoría y checklist de privacidad | Dirección Técnica       |

*(El timeline facilita visualizar la progresión temporal y los entregables clave de la fase 2.)*

## Objetivos (90 días) — con entregables y métricas de éxito vinculadas

1. Desacople arquitectónico: extraer el dominio de cálculo en librerías y servicios (CLI/API) reutilizables.
2. Pipeline de diseño–simulación–informe: de parámetros → mallas → corrida (OpenFOAM) → posproceso → informe `.rst`/PDF reproducible.
3. Catálogo de diseños: plantillas parametrizadas con versionado y comparadores de desempeño.
4. Trazabilidad & auditoría: cada resultado enlazado a insumo, commit, settings y versión de modelo (auditoría JSONL).
5. Búsqueda técnica: ingesta y extracción de fórmulas, rangos y criterios desde literatura técnica.
6. Entrega comercial: generación de paquetes (KPIs, gráficas CFD, PDF) para Aleph y publicaciones.

## Alcance

* Familias iniciales: Hidrociclón y Aeroenfriador.
* Integraciones: OpenFOAM, Git, Aleph.
* Excluido: control en planta/IoT; futuro.

## Arquitectura propuesta (hexagonal)

**Capas**

* Dominio: fórmulas, validaciones, criterios. Sin dependencias UI.
* Aplicación/Servicios: orquestación, pipelines, informes.
* Adaptadores: UI, CLI, API REST, conectores OpenFOAM/Aleph.
* Infra: telemetría, almacenamiento, caché.

**Patrones clave**

* Ports & Adapters.
* Pipelines declarativos (YAML).
* Data Contracts (pydantic).

## Mapa de capacidades

| Capacidad                   | Entrada                         | Salida                          |
| --------------------------- | ------------------------------- | ------------------------------- |
| Cálculo rápido              | YAML/JSON (caudal, D, ρ)        | KPIs rápidos (ΔP, eficiencia)   |
| Simulación CFD/CAE          | Caso OpenFOAM + geometría STL   | Campos, KPIs, imágenes          |
| Comparación multi-escenario | JSONs de resultados             | Tablas, gráficos                |
| Generación de evidencia     | Parámetros y resultados previos | Informe `.rst→PDF`              |
| Catálogo & reutilización    | Metadatos YAML                  | Plantillas parametrizadas       |
| Búsqueda técnica            | Consulta texto                  | Resumen con criterios de diseño |

## Roadmap y entregables

**Mes 1** – Extraer core de dominio (`prodisys.core`, `prodisys.calc`, `prodisys.equipos`). CLI mínima. Flujo de bosquejos con YAML.

**Mes 2** – Pipeline OpenFOAM (casekit), informes `.rst` automáticos, catálogo con comparador de resultados.

**Mes 3** – Adaptar UI como adaptador, exportación de paquetes comerciales, tablero de auditoría, diálogo de verificación.

**Entregables:** paquetes Python, CLI, plantillas `.rst`, catálogo (10–20 escenarios), guía de operación.

## Métricas de éxito

* T2E < 48 h hasta informe PDF.
* ≥50% de casos nuevos por clon de plantilla.
* ≥80% de pasos automatizados.
* Checklist de calidad por caso.

## Riesgos y mitigaciones

* Acoplamiento residual → tests de contrato.
* Variabilidad de solver → recetas y tolerancias.
* Gestión de artefactos → convenciones y limpieza.

## Repositorio: contenido, acceso y propósito

**Contenido:** código núcleo (`core`, `calc`, `equipos`, `pipelines`, `adapters`, `telemetry`), interfaces (`cli`, `api`, `ui_streamlit`), plantillas (`templates`, `catalogo`, `docs`), conocimiento (`knowledge`), automatización (`tests`, `ci`).

**Acceso:** Git privado on-prem (Gitea/GitLab), SSH+2FA, RBAC. Flujo `main` / `develop` / `feature`, MR, tags. Seguridad con Vault y CI sin egress.

**Propósito:** fuente única de verdad, reproducibilidad (tag+JSONL), desacople, automatización, privacidad, onboarding rápido.

## Refactor del repositorio

**Estructura objetivo:**

```
prodisys/
  core/
  equipos/
    hidrociclon/
    aeroenfriador/
  calc/
  pipelines/
  adapters/
    ui_streamlit/
    cli/
    api/
    openfoam/
    aleph_export/
  telemetry/
  reports/
  tests/
```


Mover lógica pura a `core`/`calc`, exponer puertos, unificar auditoría (JSONL).

## Búsqueda técnica (mínimo viable)

`knowledge/` con PDFs y metadatos YAML, indexado y extracción de rangos y criterios de diseño.

## Entrenamiento de heurísticas

Feedback explícito (aprobaciones, prioridades) e implícito (uso, selecciones). Ajuste de pesos (λ), reglas go/no-go, ranking multi‑armed bandit, trazabilidad JSONL, modo sandbox y control humano.

## Componente cognitivo y estilo de trabajo

**Bosquejos:** foto → `inbox_sketches/`, YAML con contexto, objetivos y supuestos. Enlace a ficha de diseño y catálogo.

**Extracción:** marcaje de cotas, valores con incertidumbre (min/nom/max), heurísticas por familia.

**Razonamiento:** perfil de decisión (YAML), reglas go/no‑go, diálogo de verificación, justificación.

**Aprendizaje:** registro de decisiones, evolución de plantillas.

**Trazabilidad:** auditoría enlaza bosquejo, parámetros, commits y resultados.

## Reglas de operación (lenguaje claro y privacidad)

**1) Lenguaje claro para no‑sistemas (glosario operativo)**

* **Artefacto**: cualquier archivo/resultado generado (código, CSV, PNG, informe PDF, malla, caso OpenFOAM, etc.).
* **Pipeline**: receta automatizada que toma entradas y produce artefactos (parámetros → malla → simulación → KPIs → informe).
* **YAML**: formato de texto legible (listas con guiones y “clave: valor”) para describir pipelines y metadatos.
* **Telemetry/Auditoría**: registro cronológico de qué se ejecutó, con qué entradas y qué produjo (trazabilidad/repetibilidad).
* **params.json**: archivo de parámetros de entrada en JSON (texto con llaves `{}`) que consume el pipeline.
* **Adaptador**: pieza que conecta el núcleo de cálculo con algo externo (UI, OpenFOAM, Aleph) sin romper el núcleo.
* **Dominio**: parte de ingeniería pura (fórmulas, criterios, validaciones) sin UI ni dependencias externas.
* **CLI**: ejecutar desde consola con comandos (p. ej., `prodisys run ...`).

**Apoyos en la UI**

* Tooltips/glosario en línea y botón “¿Qué significa esto?” junto a cada término técnico.

**2) Sistema cerrado / privado (sin fuga de datos)**

* **Sin terceros por defecto**: no se envían documentos ni parámetros a servicios externos (incluidos servicios de IA).
* **Modelos locales**: LLM/embeddings on‑prem o infraestructura controlada, sin telemetría saliente.
* **Control de acceso (RBAC)**: roles (Administrador, Ingeniería, Comercial) y herencia de permisos por artefacto.
* **Cifrado**: en reposo y en tránsito; claves en **Vault** (no en `.env` plano).
* **Red**: política **deny‑all egress** en contenedores; sólo repos internos y nodos de cómputo autorizados.
* **Auditoría**: logs firmados (hash) en `logs/agent.log.jsonl` + **checksum** de artefactos; alertas ante salidas de red.
* **Clasificación**: `INTERNAL`, `CONFIDENTIAL`, `CLIENT_CONFIDENTIAL` aplicada a todos los artefactos.
* **Backups/retención**: snapshots cifrados; retención por clase de dato; **derecho al olvido** para clientes.
* **Contrato de uso**: explícito que ningún gestor de IA externo puede usar datos para entrenamiento.

**Pruebas/controles de privacidad**

* Test de **circuito cerrado** (falla si hay HTTP saliente no autorizado).
* Escaneo de secretos en CI; bloqueo de commits con credenciales.
* Revisión periódica de permisos por carpeta/repo.

## Siguientes pasos inmediatos

1. Crear repo `prodisys-gemelo`.
2. Extraer paquete `prodisys-core`.
3. Especificar pipeline YAML de hidrociclón.
4. Implementar CLI y prueba e2e.
5. Definir plantilla `.rst` y salida PDF.
6. Activar flujo de bosquejos (`inbox_sketches/`).

## Política de datos y checklist de privacidad

**Política de datos (resumen ejecutivo)**

* Toda la información de proyectos y clientes se clasifica como **CONFIDENCIAL** o **CLIENT_CONFIDENTIAL**.
* Ningún artefacto/dataset/documento podrá ser compartido con terceros sin autorización explícita del gerente de ingeniería.
* Prohibido el entrenamiento, ajuste o inferencia por modelos de IA externos con datos de Prodisys o de clientes.
* Los datos permanecen bajo control de Prodisys y se procesan únicamente en infraestructura local o controlada.
* Copias de seguridad **cifradas** con retención definida (90 días datos temporales, 1 año resultados, indefinido informes finales archivados).
* Garantizar el **derecho al olvido**: eliminación completa cuando el cliente lo solicite.
* Auditorías de cumplimiento al menos cada seis meses.

**Checklist de privacidad antes de cada entrega**

1. Clasificación verificada de cada artefacto (INTERNAL/CONFIDENTIAL/CLIENT_CONFIDENTIAL).
2. Confirmación de **cero llamadas externas** en pipelines (test de circuito cerrado).
3. Revisión de **hashes/firmas** en `logs/agent.log.jsonl`.
4. Verificación de que `.env` no contenga claves expuestas.
5. Cifrado de backups y permisos por rol vigentes.
6. Nombres de archivo sin datos personales o nombres de cliente.
7. Registro de **aprobación final** de privacidad en auditoría.

## Guía de uso paso a paso

### Descripción visual paso a paso

Inicio: pantalla de bienvenida con opciones de rol (Administrador, Ingeniería, Comercial).

Caso nuevo: formulario sencillo con campos para nombre, tipo de equipo y carga del bosquejo.

Ficha de diseño: vista de formulario con pestañas para contexto, variables y prioridades.

Preguntas inteligentes: cuadro de diálogo guiado con opciones y respuestas rápidas.

Resultados preliminares: tablero con KPIs y visualizaciones.

Pipeline en ejecución: barra de progreso y estado de cada etapa (malla, simulación, posproceso, informe).

Informe: previsualización en PDF con opción de exportar a paquete comercial.

Catálogo: vista de tarjetas con miniaturas de casos anteriores y filtros por equipo o cliente.
— tiempos estimados e intervención — tiempos estimados e intervención

1. **Entrar y crear un caso** — *1–2 min · Intervención: baja*

   * Inicia sesión y elige tu rol (Administrador / Ingeniería / Comercial).
   * Crea un **Caso** (expediente de diseño): nombre, objetivo, familia de equipo.
   * Sube el **bosquejo** (foto) que irá a `inbox_sketches/`.

2. **Ficha de diseño (traducción sencilla)** — *3–6 min · Intervención: media*

   * Completa contexto, supuestos y **criterios de éxito**.
   * El sistema guarda metadatos en **YAML** (texto “clave: valor”).
   * Ajusta tu **Perfil de decisión** (seguridad, eficiencia, costo, mantenibilidad, plazos).

3. **Preguntas inteligentes del gemelo** — *2–4 min · Intervención: baja*

   * 5–7 preguntas cortas para aclarar ambigüedades (p. ej., “¿L/D objetivo?”, “¿ΔP máxima?”).
   * Marca **cotas** sobre la imagen (escala de referencia) y define **rangos** (min/nom/max).

4. **Propuesta inicial** — *≈1 min · Intervención: nula*

   * Cálculos analíticos rápidos generan **KPIs** (ΔP, eficiencia, tamaño, potencia).
   * Reglas **go/no‑go** avisan si violas límites críticos.
   * Todo queda en **Auditoría/Telemetry** (JSONL firmado).

5. **Simulación automatizada** — *5–30 min · Intervención: nula/monitor*

   * Al pulsar **Simular**, corre un **Pipeline** (YAML): malla → OpenFOAM → posproceso → informe.
   * Se generan **artefactos**: mallas, CSV, imágenes, informe `.rst→PDF`.

6. **Revisión y decisión** — *3–8 min · Intervención: alta*

   * Tablero con tablas/gráficos, explicación de **trade‑offs** y supuestos.
   * Ajustas prioridades/entradas, recalculas, y **apruebas** o **pides cambios**.

7. **Informe y paquete comercial** — *≈1 min · Intervención: nula*

   * Genera el **Informe reproducible** `.rst→PDF` con figuras y anexos.
   * Crea **paquete comercial** (ZIP con PDF + PNG + CSV) para Aleph o envío.

8. **Reutilización y catálogo** — *≈1 min · Intervención: baja*

   * Guarda como **Plantilla**; inicia futuros casos desde allí.

9. **Búsqueda técnica** — *2–5 min · Intervención: baja*

   * Consulta en `knowledge/` y obtén **resúmenes** y **referencias** (todo local).

10. **Seguridad y privacidad** — *≈1 min · Intervención: nula*

* **Circuito cerrado** (sin conexiones externas), RBAC y checklist previo a entrega.

**Mini‑glosario práctico**

* **Caso**: carpeta viva del proyecto con todo lo asociado.
* **YAML**: archivo legible de configuración (clave: valor) para pipelines y metadatos.
* **Pipeline**: receta automatizada (parámetros → malla → simulación → informe).
* **Artefacto**: archivo generado (CSV, PDF, imagen, malla).
* **KPIs**: métricas clave (ΔP, eficiencia…).
* **Auditoría/Telemetry**: bitácora firmada (JSONL) de entradas/salidas/versión.
* **Perfil de decisión**: prioridades ponderadas del ingeniero.
* **Go/No‑Go**: reglas que aprueban o frenan un diseño por límites críticos.
* **Catálogo/Plantilla**: biblioteca de casos exitosos reutilizables.

## Diagramas de flujo (auto-generados)

.. figure:: flujo_interaccion_gemelo.png
:align: center
:width: 80%

.. figure:: flujo_pipeline.png
:align: center
:width: 80%

## Anexos

* Glosario de KPIs.
* Checklist de validación.
* Convenciones de nombres y rutas.