# Guia Tecnica Catalogo Runtime

Documento tecnico para modelar catalogos reutilizables en Medusa sin atarlos a ISP.

Objetivo:
- resolver planes, servicios u ofertas segun criterios del flujo
- separar datos variables de reglas conversacionales
- permitir reutilizacion en ISP, turnero u otros verticales

Complementa:
- [FLOW_STANDARD_V1.md](/c:/Apache24/htdocs/sidelink/backend/IA/FLOW_STANDARD_V1.md)
- [GUIA_TECNICA_FLOW_STANDARD_V1.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_TECNICA_FLOW_STANDARD_V1.md)
- [GUIA_PARA_IA_GENERAR_PAQUETE_MODULAR.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_PARA_IA_GENERAR_PAQUETE_MODULAR.md)

## Problema que resuelve

En areas como ventas no alcanza con prompts y flujos.

Hace falta resolver datos variables segun contexto:
- planes por localidad
- factibilidad por direccion
- cobertura por zona
- turnos por sede
- servicios por especialidad

Eso no debe vivir:
- ni en `prompt_base`
- ni en `prompt_area`
- ni como lista fija adentro de un flujo

Debe vivir en una capa aparte:
- catalogo runtime

## Separacion correcta de responsabilidades

### Prompt

Va aca:
- tono
- criterio comercial
- reglas de lenguaje
- que no debe inventar GPT

No va aca:
- lista completa de planes
- lista completa de turnos
- reglas de elegibilidad

### Flujo

Va aca:
- que datos pedir
- que accion disparar
- en que orden avanzar
- cuando derivar

No va aca:
- el catalogo completo
- copy final fijo de ofertas

### Catalogo runtime

Va aca:
- items disponibles
- atributos variables
- reglas de filtrado
- elegibilidad
- disponibilidad

## Concepto general

No modelar "planes ISP" duro.

Modelar algo mas general:
- `catalog_items`

Un `catalog_item` puede ser:
- un plan de internet
- un tipo de turno
- un servicio
- una opcion comercial

## Modelo general recomendado

### Catalogo

```json
{
  "catalog_id": "ofertas_principales",
  "kind": "service_offers",
  "tenant": "medusa",
  "items": []
}
```

### Item

```json
{
  "id": "plan_300_ftth_vm",
  "nombre": "Plan 300 MB",
  "categoria": "ftth",
  "estado": "activo",
  "atributos": {},
  "restricciones": {},
  "presentacion": {}
}
```

## Campos recomendados de un item

### `id`

Identificador tecnico unico del item.

### `nombre`

Nombre visible del item.

### `categoria`

Agrupa el item.

Ejemplos:
- `ftth`
- `wireless`
- `turno_general`
- `turno_especialista`

### `estado`

Ejemplos:
- `activo`
- `inactivo`

### `atributos`

Datos propios del item.

Ejemplos en ISP:
- velocidad
- precio
- facturacion
- tecnologia

Ejemplos en turnero:
- duracion
- sede
- especialidad
- obra_social

### `restricciones`

Condiciones que deben cumplirse para que el item aplique.

Ejemplos:
- localidad
- zona
- requiere_factibilidad
- sede
- profesional

### `presentacion`

Datos opcionales para mostrar mejor el item.

Ejemplos:
- resumen corto
- detalle
- orden de aparicion

## Ejemplo ISP

```json
{
  "catalog_id": "planes_internet",
  "kind": "service_offers",
  "tenant": "medusa",
  "items": [
    {
      "id": "plan_300_vm_ftth",
      "nombre": "Plan 300 MB",
      "categoria": "ftth",
      "estado": "activo",
      "atributos": {
        "velocidad": 300,
        "precio": 25000,
        "facturacion": "mensual",
        "tecnologia": "ftth"
      },
      "restricciones": {
        "localidad": ["villa_mercedes"],
        "zona": ["casco_urbano"],
        "factibilidad": ["aprobada"]
      },
      "presentacion": {
        "resumen": "300 MB por fibra optica"
      }
    }
  ]
}
```

## Ejemplo Turnero

```json
{
  "catalog_id": "turnos_disponibles",
  "kind": "appointments",
  "tenant": "turnero_demo",
  "items": [
    {
      "id": "turno_clinica_vm_30",
      "nombre": "Consulta clinica general",
      "categoria": "consulta_medica",
      "estado": "activo",
      "atributos": {
        "duracion_minutos": 30,
        "sede": "villa_mercedes"
      },
      "restricciones": {
        "especialidad": ["clinica_general"],
        "obra_social": ["particular", "osde"]
      },
      "presentacion": {
        "resumen": "Consulta presencial de 30 minutos"
      }
    }
  ]
}
```

## Contexto de resolucion

El runtime necesita un contexto para filtrar el catalogo.

Ese contexto no sale del catalogo.
Sale de:
- slots del flujo
- backend_facts
- datos backend complementarios

Ejemplo:

```json
{
  "localidad": "villa_mercedes",
  "zona": "casco_urbano",
  "factibilidad": "aprobada",
  "tecnologia": "ftth"
}
```

En turnero:

```json
{
  "sede": "villa_mercedes",
  "especialidad": "clinica_general",
  "obra_social": "osde"
}
```

## Runtime esperado

El runtime del catalogo deberia hacer esto:

1. recibir un `catalog_id`
2. recibir un `resolution_context`
3. filtrar items por restricciones
4. devolver:
   - `items_disponibles`
   - `items_rechazados` opcional
   - `motivo_sin_resultados` opcional

Formato esperado:

```json
{
  "catalog_id": "planes_internet",
  "matched_count": 2,
  "items": []
}
```

## Relacion con el flujo

Hoy V1 no tiene una estructura nativa de catalogo linkeable.

Entonces la propuesta futura es:
- agregar una extension al runtime, no meter el catalogo directo en el flujo

Direccion recomendada:
- el flujo pide criterios
- el backend resuelve catalogo
- GPT presenta solo los items filtrados

## Regla de modelado importante

No hacer esto:
- poner todos los planes dentro de `prompt_ventas`
- poner todos los planes dentro de `flujo_ventas`

Hacer esto:
- `prompt_ventas`: reglas comerciales
- `flujo_ventas`: secuencia
- `catalogo`: datos variables
- `runtime`: filtrado

## Posible extension futura del flujo

Sin implementarlo todavia, un flujo podria llegar a referenciar catalogo asi:

```json
{
  "id": "resolver_planes",
  "type": "action",
  "action": "resolver_catalogo",
  "requires": ["localidad", "zona"],
  "params": {
    "catalog_id": "planes_internet",
    "context_map": {
      "localidad": "localidad",
      "zona": "zona"
    }
  },
  "on_success": "ofrecer_planes",
  "on_failure": "sin_planes"
}
```

Esto no esta implementado hoy.
Es una direccion de diseño.

## Cómo presentar resultados a GPT

GPT no deberia recibir todo el catalogo.

Solo deberia recibir:
- items filtrados
- atributos relevantes
- instrucciones de presentacion

Ejemplo:

```json
{
  "planes_disponibles": [
    {
      "nombre": "Plan 300 MB",
      "velocidad": 300,
      "precio": 25000,
      "facturacion": "mensual"
    }
  ]
}
```

## Beneficio de esta abstraccion

Con este modelo, lo mismo sirve para:
- ISP
- turnero
- inmobiliaria
- salud
- soporte con catalogo de servicios

Se reutiliza:
- flujo
- runtime
- editor visual

Solo cambia:
- el catalogo
- el resolvedor
- algunos prompts de area

## Checklist para saber si algo es catalogo

Si un dato:
- cambia por tenant
- cambia seguido
- tiene muchos items
- depende de criterios de elegibilidad
- no deberia memorizarse en un prompt

Entonces probablemente deba vivir en catalogo runtime.