Add runbook for order report margin and cost readiness

ucepsa/edge-oee-demo/docs/runbooks/080_order_report_margin_cost_readiness.md

@@ -0,0 +1,421 @@
+# Runbook — Order Report, Margin Intelligence y Cost Readiness Cockpit
+
+## 1. Propósito
+
+Este documento describe la capa de informes de ejecución de orden, Margin Intelligence y Cost Readiness Cockpit desarrollada para MESAVAULT Edge-OEE en UCEPSA.
+
+El objetivo de esta capa es unir datos de Odoo, máquina, paros, energía, materia prima e ingreso comercial para generar informes técnicos y económico-industriales por orden de fabricación.
+
+## 2. Componentes incluidos
+
+La fase incluye:
+
+- informe HTML por orden;
+- informe PDF por orden;
+- índice de órdenes;
+- Margin Intelligence;
+- Cost Readiness Cockpit;
+- vistas SQL de ejecución de orden;
+- vistas SQL de materia prima;
+- vistas SQL de margen;
+- vistas SQL de readiness económico;
+- microservicio FastAPI;
+- despliegue mediante Docker Compose.
+
+## 3. URLs operativas
+
+Servicio Order Report API:
+
+```text
+http://17.126.1.70:8090
+```
+
+Healthcheck:
+
+```text
+http://17.126.1.70:8090/health
+```
+
+Índice de órdenes:
+
+```text
+http://17.126.1.70:8090/orders.html
+```
+
+Cost Readiness Cockpit:
+
+```text
+http://17.126.1.70:8090/cost-readiness.html
+```
+
+Informe HTML de orden:
+
+```text
+http://17.126.1.70:8090/report.html?order_ref=WH%2FMO%2F00025
+```
+
+Informe PDF de orden:
+
+```text
+http://17.126.1.70:8090/report.pdf?order_ref=WH%2FMO%2F00025
+```
+
+## 4. Servicio Docker
+
+Contenedor:
+
+```text
+mv_ucepsa_order_report_api
+```
+
+Compose:
+
+```text
+docker-compose.order-report.yml
+```
+
+Arranque:
+
+```bash
+cd /srv/mesavault/edge-oee-ucepsa
+docker compose -f docker-compose.order-report.yml up -d --build
+```
+
+Parada:
+
+```bash
+cd /srv/mesavault/edge-oee-ucepsa
+docker compose -f docker-compose.order-report.yml down
+```
+
+Comprobación:
+
+```bash
+curl http://127.0.0.1:8090/health
+```
+
+Logs:
+
+```bash
+docker logs --tail=120 mv_ucepsa_order_report_api
+```
+
+## 5. Ubicación runtime
+
+Ruta runtime:
+
+```text
+/srv/mesavault/edge-oee-ucepsa/services/order-report-api
+```
+
+Archivos principales:
+
+```text
+services/order-report-api/Dockerfile
+services/order-report-api/requirements.txt
+services/order-report-api/app/main.py
+services/order-report-api/app/templates/order_report.html
+services/order-report-api/app/templates/orders_index.html
+services/order-report-api/app/templates/cost_readiness.html
+services/order-report-api/.env.local
+```
+
+El archivo `.env.local` contiene credenciales y no debe versionarse.
+
+## 6. Ubicación en Gitea
+
+Repositorio local:
+
+```text
+/srv/mesavault/40-clients
+```
+
+Ruta del proyecto:
+
+```text
+ucepsa/edge-oee-demo/
+```
+
+Archivos versionados relacionados:
+
+```text
+ucepsa/edge-oee-demo/services/order-report-api/
+ucepsa/edge-oee-demo/deploy/ucepsa-local/docker-compose.order-report.yml
+ucepsa/edge-oee-demo/sql/reports/070_order_execution_report_views.sql
+ucepsa/edge-oee-demo/sql/reports/080_margin_intelligence_cost_readiness.sql
+ucepsa/edge-oee-demo/docs/runbooks/080_order_report_margin_cost_readiness.md
+```
+
+## 7. Vistas SQL principales
+
+### 7.1. Informe técnico de orden
+
+```text
+mv_reports_ucepsa_demo.order_execution_report_v1
+mv_reports_ucepsa_demo.order_execution_stops_v1
+mv_reports_ucepsa_demo.order_execution_stop_causes_v1
+mv_reports_ucepsa_demo.order_execution_timeline_v1
+mv_reports_ucepsa_demo.order_execution_energy_timeseries_v1
+mv_reports_ucepsa_demo.order_execution_data_quality_v1
+mv_reports_ucepsa_demo.order_execution_report_full_v1
+```
+
+### 7.2. Margin Intelligence
+
+```text
+mv_edge_oee_ucepsa_demo.odoo_order_commercials
+mv_edge_oee_ucepsa_demo.margin_cost_parameters
+mv_edge_oee_ucepsa_demo.raw_material_cost_parameters
+mv_reports_ucepsa_demo.order_raw_material_costs_v1
+mv_reports_ucepsa_demo.order_raw_material_costs_summary_v1
+mv_reports_ucepsa_demo.order_margin_report_v1
+```
+
+### 7.3. Cost Readiness
+
+```text
+mv_reports_ucepsa_demo.cost_readiness_orders_v1
+mv_reports_ucepsa_demo.cost_readiness_raw_materials_v1
+mv_reports_ucepsa_demo.cost_readiness_summary_v1
+```
+
+## 8. Orden piloto validada
+
+Orden:
+
+```text
+WH/MO/00025
+```
+
+Pedido de venta:
+
+```text
+S00011
+```
+
+Cliente:
+
+```text
+FRAJUSEMA, S.L.
+```
+
+Producto:
+
+```text
+[220365] BOLSA BD DE 60x90 cms. G80 TRANSPARENTE
+```
+
+Resultado técnico validado:
+
+```text
+Duración: 35,83 min
+Tiempo en marcha: 33,48 min
+Tiempo parado: 2,35 min
+Energía: 0,029 kWh
+Ciclos reales: 63
+Paros: 2
+Coste paros: 1,41 €
+Calidad técnica: FIABLE
+```
+
+Resultado económico actual:
+
+```text
+Ingreso neto: 1154,80 €
+Materia prima: [120727] TUBO BD DE 60 cms. G80 TRANSPARENTE
+Cantidad consumida: 138 kg
+Coste materia prima: pendiente
+Margen estimado: no calculable todavía
+Motivo: falta coste €/kg de materia prima 120727
+```
+
+## 9. Criterio de margen
+
+El sistema no calcula margen final cuando falta coste de materia prima.
+
+Estados relevantes:
+
+```text
+REVENUE_LINKED
+NO_REVENUE_LINKED
+MISSING_RAW_MATERIAL_COST_PARAMETER
+PARTIAL_MARGIN_MISSING_RAW_MATERIAL_COST
+ESTIMATED_MARGIN_AVAILABLE
+```
+
+La decisión operativa actual es bloquear el margen estimado hasta que UCEPSA cargue costes reales de materia prima en Odoo o valide costes manuales por kg.
+
+## 10. Cost Readiness Cockpit
+
+El cockpit muestra:
+
+- órdenes con ingreso;
+- órdenes sin ingreso;
+- órdenes con materia prima;
+- órdenes sin materia prima;
+- órdenes con coste material pendiente;
+- materias primas que bloquean cálculo de margen;
+- clientes y pedidos afectados;
+- score de readiness económico.
+
+Bloqueo principal actual:
+
+```text
+Falta coste €/kg para 120727 - [120727] TUBO BD DE 60 cms. G80 TRANSPARENTE
+```
+
+## 11. Comandos de validación
+
+Resumen readiness:
+
+```bash
+docker exec -i mv_ucepsa_postgres_hot \
+  sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' <<'SQL'
+SELECT *
+FROM mv_reports_ucepsa_demo.cost_readiness_summary_v1;
+SQL
+```
+
+Readiness por orden:
+
+```bash
+docker exec -i mv_ucepsa_postgres_hot \
+  sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' <<'SQL'
+SELECT
+    odoo_order_ref,
+    sale_order_ref,
+    customer_name,
+    product_default_code,
+    revenue_net_eur,
+    cost_readiness_score,
+    cost_readiness_status,
+    cost_readiness_description
+FROM mv_reports_ucepsa_demo.cost_readiness_orders_v1
+ORDER BY cost_readiness_score ASC;
+SQL
+```
+
+Materias primas pendientes:
+
+```bash
+docker exec -i mv_ucepsa_postgres_hot \
+  sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' <<'SQL'
+SELECT
+    raw_product_default_code,
+    raw_product_name,
+    affected_orders,
+    affected_customers,
+    total_consumed_qty,
+    raw_material_readiness_status,
+    recommended_action
+FROM mv_reports_ucepsa_demo.cost_readiness_raw_materials_v1
+ORDER BY affected_order_count DESC;
+SQL
+```
+
+Informe de margen:
+
+```bash
+docker exec -i mv_ucepsa_postgres_hot \
+  sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' <<'SQL'
+SELECT
+    odoo_order_ref,
+    sale_order_ref,
+    customer_name,
+    revenue_net_eur,
+    raw_materials_summary,
+    material_cost_estimated_eur,
+    material_cost_source_status,
+    estimated_margin_eur,
+    estimated_margin_pct,
+    margin_status
+FROM mv_reports_ucepsa_demo.order_margin_report_v1
+WHERE odoo_order_ref = 'WH/MO/00025';
+SQL
+```
+
+## 12. Cómo activar margen estimado en el futuro
+
+Cuando UCEPSA tenga el coste real por kg del tubo `120727`, se podrá insertar en:
+
+```text
+mv_edge_oee_ucepsa_demo.raw_material_cost_parameters
+```
+
+Plantilla:
+
+```sql
+INSERT INTO mv_edge_oee_ucepsa_demo.raw_material_cost_parameters (
+    tenant,
+    site,
+    raw_product_default_code,
+    raw_product_name,
+    material_cost_eur_per_kg,
+    source,
+    notes
+)
+VALUES (
+    'ucepsa',
+    'ucepsa_test',
+    '120727',
+    '[120727] TUBO BD DE 60 cms. G80 TRANSPARENTE',
+    COSTE_REAL_EUR_KG,
+    'MANUAL_UCEPSA',
+    'Coste validado por UCEPSA para Margin Intelligence'
+);
+```
+
+Tras insertar ese coste, `order_margin_report_v1` empezará a calcular:
+
+```text
+material_cost_estimated_eur
+estimated_margin_eur
+estimated_margin_pct
+```
+
+## 13. Riesgos y advertencias
+
+No presentar `partial_margin_after_known_costs_eur` como margen real.
+
+No introducir costes aproximados sin fuente validada.
+
+No mezclar órdenes de prueba con datos productivos sin señalarlas.
+
+No usar informes bloqueados por falta de coste como base para pricing.
+
+No interpretar `qty_planned`, `qty_done` o ciclos como unidades comerciales hasta validar conversiones.
+
+## 14. Estado actual
+
+Estado funcional:
+
+```text
+Order Execution Report: operativo
+Informe HTML/PDF: operativo
+Margin Intelligence: operativo en modo parcial
+Cost Readiness Cockpit: operativo
+Margen estimado final: bloqueado hasta coste de materia prima
+```
+
+Snapshot recomendado:
+
+```text
+order-report-margin-cost-readiness-v01-ok
+```
+
+## 15. Accesos rápidos
+
+```text
+Orders:
+http://17.126.1.70:8090/orders.html
+
+Cost Readiness:
+http://17.126.1.70:8090/cost-readiness.html
+
+Informe HTML WH/MO/00025:
+http://17.126.1.70:8090/report.html?order_ref=WH%2FMO%2F00025
+
+Informe PDF WH/MO/00025:
+http://17.126.1.70:8090/report.pdf?order_ref=WH%2FMO%2F00025
+```
+