Subir archivos a "docs"

docs/DATA_DICTIONARY.md

@@ -0,0 +1,232 @@
+# Diccionario de Datos
+
+Este documento resume los archivos principales que consume y genera Cloud Conversion. Los formatos no se cambian desde la documentacion; se describen para que otros arquitectos puedan preparar inventarios y leer resultados.
+
+## Inventarios de entrada
+
+Formatos soportados:
+
+- CSV
+- XLS
+- XLSX
+
+Ubicaciones:
+
+| Ruta | Uso |
+| --- | --- |
+| `input/` | Inventarios disponibles para CLI y GUI. |
+| `input/gui_uploads/` | Inventarios subidos desde Streamlit. |
+| `input/done/` | Inventarios archivados manualmente en GUI o automaticamente por CLI. |
+
+Columnas locales esperadas cuando existen:
+
+| Campo normalizado | Columna local | Descripcion |
+| --- | --- | --- |
+| `quantity` | `Cantidad` | Cantidad de servidores o instancias equivalentes. |
+| `cpu` | `vCPU` | vCPU por servidor. |
+| `memory_gb` | `Memoria` | Memoria por servidor en GB. |
+| `storage_gb` | `Block Storage` | Storage por servidor en GB. |
+| `os` | `Nombre` | Sistema operativo o plataforma. |
+| `environment` | `Ambiente` | Ambiente: PRD, QA, DEV, UAT, DR, etc. |
+| `notes` | `Tipo` | Tipo, rol, workload o descripcion. |
+
+El proyecto tambien tiene fallback para nombres comunes como `VM`, `CPUs`, `RAM`, `storage`, `OS according to the VMware Tools`, `environment`, `hostname` y equivalentes.
+
+## Inventario normalizado
+
+Los matchers transforman cada fila a campos comunes:
+
+| Columna | Descripcion |
+| --- | --- |
+| `server_name` | Nombre de servidor, VM o grupo. |
+| `quantity` | Cantidad final usada para multiplicar costos. |
+| `source_cpu` | CPU/vCPU por unidad. |
+| `source_memory_gb` | Memoria por unidad en GB. |
+| `source_storage_gb` | Storage por unidad en GB. |
+| `source_total_cpu` | CPU total para AWS. |
+| `source_total_vcpu` | vCPU total para OCI output. |
+| `source_ocpu` | OCPU calculado para OCI. |
+| `source_total_ocpu` | OCPU total para OCI. |
+| `source_total_memory_gb` | Memoria total. |
+| `source_total_storage_gb` | Storage total. |
+| `os` | OS detectado o mapeado. |
+| `environment` | Ambiente. |
+| `notes` | Notas o rol del workload. |
+
+## Catalogo AWS
+
+Ruta:
+
+```text
+data/catalog/aws/aws_ec2_catalog.csv
+```
+
+Origen:
+
+```text
+data/raw/aws/index.json
+```
+
+Columnas actuales:
+
+| Columna | Descripcion |
+| --- | --- |
+| `sku` | SKU AWS Pricing. |
+| `regionCode` | Codigo de region AWS. |
+| `location` | Nombre de ubicacion. |
+| `instanceType` | Tipo de instancia, por ejemplo `m7a.xlarge`. |
+| `instanceFamily` | Familia comercial. |
+| `vcpu` | vCPU del shape. |
+| `memory` | Memoria textual del offer. |
+| `currentGeneration` | Si es generacion actual. |
+| `processorArchitecture` | Arquitectura de CPU. |
+| `networkPerformance` | Descripcion de red. |
+| `operatingSystem` | OS del precio. |
+| `tenancy` | Tenancy, por ejemplo `Shared`. |
+| `preInstalledSw` | Software preinstalado. |
+| `capacitystatus` | Estado de capacidad, normalmente `Used`. |
+| `unit` | Unidad de precio, normalmente `Hrs`. |
+| `price_usd` | Precio USD por hora. |
+| `description` | Descripcion AWS. |
+
+## Salida AWS Match
+
+Ruta:
+
+```text
+data/match/aws/MATCH-AWS-<inventario>.csv
+```
+
+Columnas principales:
+
+| Columna | Descripcion |
+| --- | --- |
+| `server_name` | Servidor o grupo origen. |
+| `quantity` | Cantidad origen. |
+| `source_cpu` | CPU origen por unidad. |
+| `source_memory_gb` | Memoria origen por unidad. |
+| `source_storage_gb` | Storage origen por unidad. |
+| `workload_type` | Clasificacion de workload usada para ranking. |
+| `aws_sku` | SKU recomendado. |
+| `aws_region_code` | Region AWS seleccionada. |
+| `aws_location` | Ubicacion AWS. |
+| `aws_instance_type` | Shape recomendado. |
+| `aws_instance_family` | Familia del shape recomendado. |
+| `aws_vcpu` | vCPU del shape recomendado. |
+| `aws_memory_gb` | Memoria del shape recomendado. |
+| `aws_price_usd_per_hr` | Precio unitario por hora. |
+| `aws_total_instances` | Instancias recomendadas. |
+| `aws_total_price_usd_per_hr` | Costo total por hora. |
+| `aws_monthly_price_usd_730h` | Costo mensual usando 730 horas. |
+| `aws_operating_system` | OS del precio usado. |
+| `aws_match_status` | `MATCH`, `NO_MATCH` o status de error de datos. |
+| `aws_candidate_group_selected` | Grupo de candidatos usado para ranking. |
+| `aws_recommendation_reason` | Explicacion de seleccion. |
+| `aws_preferred_m_family` | Familia M preferida configurada. |
+| `aws_m_max_cpu_ratio` | Ratio CPU maximo configurado. |
+| `aws_preferred_m_rejection_reason` | Razon de rechazo si la M preferida no aplica. |
+
+## Catalogo OCI
+
+Ruta:
+
+```text
+data/catalog/oci/oci_price_list.csv
+```
+
+Origen:
+
+```text
+data/raw/oci/products.json
+```
+
+Columnas:
+
+| Columna | Descripcion |
+| --- | --- |
+| `partNumber` | SKU o parte OCI. |
+| `displayName` | Nombre comercial. |
+| `serviceCategory` | Categoria de servicio. |
+| `metricName` | Metrica de precio. |
+| `currencyCode` | Moneda, normalmente USD. |
+| `prices_model` | Modelo de precio. |
+| `prices_value` | Valor del precio. |
+
+## Salida OCI Match
+
+Ruta:
+
+```text
+data/match/oci/MATCH-OCI-<inventario>.csv
+```
+
+Columnas:
+
+| Columna | Descripcion |
+| --- | --- |
+| `row_type` | `DETAIL`, `BOM` o `SUMMARY`. |
+| `server_name` | Servidor o grupo origen. |
+| `quantity` | Cantidad origen. |
+| `source_cpu` | vCPU origen. |
+| `source_ocpu` | OCPU origen calculado. |
+| `source_memory_gb` | Memoria por unidad. |
+| `source_storage_gb` | Storage por unidad. |
+| `source_total_vcpu` | vCPU total. |
+| `source_total_ocpu` | OCPU total. |
+| `source_total_memory_gb` | Memoria total. |
+| `source_total_storage_gb` | Storage total. |
+| `os` | OS origen. |
+| `environment` | Ambiente origen. |
+| `notes` | Notas origen. |
+| `oci_pricing_profile` | Perfil de precio OCI, por ejemplo Linux o Windows. |
+| `oci_line_item` | Linea BOM o resumen. |
+| `oci_sku` | SKU OCI. |
+| `oci_display_name` | Nombre OCI. |
+| `oci_service_category` | Categoria OCI. |
+| `oci_metric_name` | Metrica OCI. |
+| `oci_currency_code` | Moneda. |
+| `oci_prices_model` | Modelo de precio. |
+| `oci_quantity` | Cantidad cotizada. |
+| `oci_unit_price_usd_per_hr` | Precio unitario por hora. |
+| `oci_hours_per_month` | Horas mensuales usadas. |
+| `oci_monthly_price_usd` | Precio mensual calculado. |
+| `oci_match_status` | Status de matching. |
+| `oci_recommendation_reason` | Explicacion de BOM. |
+| `oci_compute_generation` | Generacion compute seleccionada. |
+
+## Dashboard
+
+La GUI lee los ultimos `MATCH-AWS-*.csv` y `MATCH-OCI-*.csv` por fecha de modificacion.
+
+Metricas:
+
+| Metrica | Calculo |
+| --- | --- |
+| AWS mensual | Suma de `aws_monthly_price_usd_730h` para filas `aws_match_status == MATCH`. |
+| OCI mensual | Fila `SUMMARY` de grand total, o suma de filas `BOM`. |
+| Ahorro | `(AWS - OCI) / AWS * 100`. |
+| Cobertura | Filas AWS con `MATCH` sobre total de filas AWS. |
+
+## Logs
+
+Ruta:
+
+```text
+logs/log_cloud_conversion_YYYYMMDD.txt
+```
+
+Cada linea incluye timestamp, prefijo de script y mensaje. Prefijos comunes:
+
+| Prefijo | Origen |
+| --- | --- |
+| `>> AWS_fetch_offer>>` | Descarga AWS. |
+| `>> AWS_eda>>` | EDA AWS. |
+| `>> AWS_match>>` | Matching AWS. |
+| `>> OCI_fetch_offer>>` | Descarga OCI. |
+| `>> OCI_match>>` | Matching OCI. |
+| `>> cloud_chat>>` | Cloud Chat CLI. |
+| `>> cloud_chat_runtime>>` | Runtime WhatsApp/Cloud Chat. |
+| `>> whatsapp_chatbot>>` | Webhook WhatsApp. |
+
+Los logs estan ignorados por Git y no deben compartirse sin revision.
+