Subir archivos a "docs"

docs/UI_GUIDE.md

@@ -0,0 +1,153 @@
+# Guia de la Interfaz Grafica
+
+La interfaz grafica de Cloud Conversion es una aplicacion Streamlit multipagina. Es la ruta recomendada para arquitectos porque permite operar el pipeline completo desde una consola local.
+
+## Iniciar
+
+Desde la raiz del proyecto:
+
+```bash
+source .venv/bin/activate
+streamlit run cloud_conversion_ui/Home.py
+```
+
+Entrada principal:
+
+```text
+cloud_conversion_ui/Home.py
+```
+
+Paginas:
+
+```text
+cloud_conversion_ui/pages/01_Inventario.py
+cloud_conversion_ui/pages/02_Catalogos.py
+cloud_conversion_ui/pages/03_Ejecucion.py
+cloud_conversion_ui/pages/04_Dashboard.py
+cloud_conversion_ui/pages/05_Logs_Artefactos.py
+```
+
+## Home
+
+Muestra resumen de los ultimos artefactos disponibles:
+
+- Total mensual AWS.
+- Total mensual OCI.
+- Porcentaje de ahorro.
+- Cobertura de matching.
+- Accesos a artefactos recientes.
+
+Si no existen salidas recientes, los indicadores pueden aparecer en cero.
+
+## Inventario
+
+Permite dos formas de seleccionar inventario:
+
+- Subir archivo CSV, XLS o XLSX.
+- Elegir un archivo existente en `input/`.
+
+Los uploads se guardan en:
+
+```text
+input/gui_uploads/
+```
+
+El nombre se normaliza y recibe timestamp, por ejemplo:
+
+```text
+input/gui_uploads/20260602_002922_inventario-sbc1.xlsx
+```
+
+El inventario activo queda en `st.session_state["selected_inventory_path"]`. Si quieres archivarlo despues de usarlo, usa `Archivar en input/done`.
+
+## Catalogos
+
+Muestra estado de catalogos y permite actualizar precios:
+
+| Boton | Resultado |
+| --- | --- |
+| `AWS Fetch` | Descarga el offer AWS EC2 en `data/raw/aws/index.json`. |
+| `AWS EDA` | Genera `data/catalog/aws/aws_ec2_catalog.csv` y reporte Markdown en `data/eda/aws/`. |
+| `OCI Fetch` | Descarga productos OCI y genera `data/catalog/oci/oci_price_list.csv`. |
+
+Requiere acceso de red para descargar precios.
+
+## Ejecucion
+
+Ejecuta los pipelines sobre el inventario activo.
+
+### Parametros AWS
+
+- Region AWS, default `us-east-1`.
+- Sistema operativo global opcional.
+- Tenancy, default `Shared`.
+- Unidad, default `Hrs`.
+- Modelo LLM, default `llama3.1:8b`.
+- `Skip LLM` para evitar Ollama.
+- `Force LLM` para forzar mapeo por LLM.
+- Incluir generaciones anteriores.
+- Incluir capacidad no usada.
+- Prioridad de familia y familia M preferida.
+- Max CPU ratio para familia M.
+
+### Parametros OCI
+
+- Modelo LLM, default `llama3.1:8b`.
+- `Skip LLM` para evitar Ollama.
+- `Force LLM` para forzar mapeo por LLM.
+- Compute series, default `E`.
+- Compute generation fija opcional.
+- Horas por mes, default `730`.
+
+### Diferencia importante contra CLI
+
+La GUI llama `aws_match.run(...)` y `oci_match.run(...)` con:
+
+```python
+move_to_done=False
+```
+
+Esto evita mover el inventario despues de AWS Match y permite ejecutar OCI Match sobre el mismo archivo. En CLI, los scripts pueden mover inventarios exitosos a `input/done/` por default.
+
+## Dashboard
+
+Lee los ultimos CSVs `MATCH-AWS-*.csv` y `MATCH-OCI-*.csv` para mostrar:
+
+- Costo mensual AWS.
+- Costo mensual OCI.
+- Ahorro porcentual.
+- Cobertura de filas AWS con status `MATCH`.
+- Tabla de recomendaciones AWS.
+- Resumen BOM OCI.
+
+El dashboard toma los ultimos artefactos por fecha de modificacion. Si necesitas comparar un inventario especifico, genera primero ambos `MATCH-*` desde la pagina `Ejecucion`.
+
+## Logs y Artefactos
+
+Muestra:
+
+- Ultimas lineas del log diario `logs/log_cloud_conversion_YYYYMMDD.txt`.
+- CSVs AWS Match.
+- CSVs OCI Match.
+- Reportes AWS EDA.
+- Logs descargables.
+
+Los botones `Descargar` entregan el archivo generado desde disco local.
+
+## Servicios internos de la GUI
+
+| Modulo | Responsabilidad |
+| --- | --- |
+| `cloud_conversion_ui/services/inventory_files.py` | Listar, subir y archivar inventarios. |
+| `cloud_conversion_ui/services/pipeline_runner.py` | Ejecutar pasos AWS/OCI y capturar stdout/stderr. |
+| `cloud_conversion_ui/services/dashboard_data.py` | Leer CSVs y calcular metricas comparativas. |
+| `cloud_conversion_ui/services/artifacts.py` | Encontrar artefactos recientes y logs. |
+
+## Recomendaciones de uso
+
+- Ejecuta AWS Match y OCI Match sobre el mismo inventario antes de revisar el dashboard.
+- Usa `Skip LLM` si no tienes Ollama instalado.
+- Actualiza catalogos solo cuando necesites precios recientes; AWS raw puede ser grande.
+- Descarga los artefactos desde `Logs y Artefactos` para compartir resultados.
+- No expongas Streamlit publicamente sin controles de red o autenticacion externa.
+