> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodexlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurador
> Configura variantes de producto, árboles de opciones y listas de partes por pedido para manufactura de configuración bajo pedido.
## Resumen
El Configurador (Configurator) resuelve el problema de **configuración bajo pedido**. Dada una familia de productos con muchas combinaciones válidas de opciones (tipos de motor, tipos de techo, accesorios, acabados) le permite a un usuario (Usuario) (o a un agente de IA actuando en nombre del usuario) recorrer el árbol de opciones, hacer selecciones y resolver esas selecciones en una lista de partes plana y concreta para esa unidad específica.
Se sitúa entre dos tipos de objetos:
* **Plantillas (Templates) de Configuración**: el espacio de posibilidades (cada opción válida, cada combinación válida, todas las sub-opciones anidadas)
* **Configuraciones**: instantáneas (Snapshots) guardadas, una por cada pedido del mundo real, que capturan las selecciones específicas realizadas + la lista de partes resuelta
El Configurador es el proceso que va de la plantilla a la configuración. Admite dos modos: crear una nueva configuración desde cero y reconfigurar una configuración existente mediante una orden de cambio, cada una guardada como una nueva versión con un enlace al predecesor.
Un punto arquitectónico clave: esto es **asistido por agente por diseño**. El agente lee un documento de pedido (PDF, texto pegado, exportación de ERP), mapea su contenido a las clases de opción de la plantilla y propone selecciones con niveles de confianza y razonamiento. El usuario revisa, anula donde sea necesario y guarda. Las selecciones registran *quién* las eligió (usuario, agente o heredado) y el agente no sobrescribirá selecciones que pertenezcan al usuario.
## Conceptos clave
### Plantilla de Configuración
Una definición JSON del espacio completo de opciones para un producto configurable. Tiene un nombre, el `entity_id` de salida que produce, una descripción opcional y un arreglo `components` de bloques de construcción.
### Componentes
Cada elemento del arreglo `components` de una plantilla es de uno de dos tipos:
* **Material**: una parte fija que siempre se incluye, sin importar las selecciones. Tiene `entity_id`, `name`, `quantity`, `part_number`.
* **Clase de Opción**: un punto de decisión que el usuario debe resolver.
### Clases de Opción y Opciones
Una **Clase de Opción** es un grupo de opciones intercambiables, la unidad de decisión central del Configurador:
| Campo | Notas |
| ----------------- | ----------------------------------------------------------------- |
| `option_class_id` | Slug usado como la clave en las selecciones (p. ej., `roof-type`) |
| `name` | Etiqueta visible para el usuario (p. ej., *Roof Type*) |
| `selection_type` | Restricción sobre la cardinalidad de elección (ver abajo) |
| `options` | Arreglo de entradas de Opción |
**Tipos de selección:**
* **`select_one`**: exactamente una opción debe elegirse
* **`select_many`**: cero o más opciones pueden elegirse (ninguna es válida)
* **`select_at_least_one`**: una o más opciones deben elegirse (cero es inválido)
Una **Opción** es una sola elección dentro de una clase de opción: `option_id`, `name` y su propio arreglo `components`. Ese `components` anidado es recursivo: una opción puede contener materiales y clases de opción adicionales. Seleccionar "motor diésel" puede revelar una clase de opción anidada *Turbo Configuration* que no era visible hasta que se hizo la elección de motor.
### Configuraciones (Instantáneas Guardadas)
Una Configuración es un registro de solo lectura producido cuando se guarda una sesión del configurador. Campos:
| Campo | Notas |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID |
| `name` | Nombre de la configuración (p. ej., *Quote 58841: Time Manufacturing*) |
| `version` | Entero, comienza en 1, se auto-incrementa en cada reconfiguración |
| `title` | Etiqueta corta de versión (nulo para v1, generado por el agente para v2+, p. ej., *Rev A: Canopy + Remove Toolbox*) |
| `parent_id` | UUID del predecesor (nulo para v1), forma una cadena de versiones unidireccional |
| `template_slug` | Referencia hacia atrás a la plantilla origen |
| `selections` | Mapa de `option_class_id` → lista de `option_id` |
| `resolved_materials` | Lista plana: `entity_id`, `name`, `part_number`, `quantity` |
| `changes_summary` | Diferencia legible por humanos respecto al padre (nulo para v1) |
### Estado de Sesión
El documento de trabajo en vivo mientras una sesión de configurador está abierta. Se actualiza bidireccionalmente: por la interfaz cuando el usuario cambia una selección y por el agente cuando sugiere selecciones.
| Campo | Notas |
| --------------------------- | --------------------------------------------------------------- |
| `session_id` | UUID |
| `template_slug` | Plantilla activa |
| `source_configuration_slug` | No-nulo cuando se reconfigura una configuración existente |
| `status` | `draft`, `waiting_for_agent`, `reviewing`, o `saved` |
| `selections` | Mapa de `option_class_id` → registro de Selección (ver abajo) |
| `custom_items` | Partes agregadas por el usuario fuera del árbol de la plantilla |
| `parts_list` | Auto-resuelto a partir de las selecciones actuales |
Cada registro de **Selección** rastrea no solo *qué* se eligió, sino *quién* lo eligió y *por qué*:
* `choice`: arreglo de `option_id` seleccionados
* `origin`: `user`, `agent` o `inherited`
* `confidence`: `user`, `high`, `medium` o `low`
* `reasoning`: explicación del agente (nulo para selecciones de origen usuario)
El campo `origin` es el mecanismo de propiedad. La ruta de sugerencias del agente omite silenciosamente cualquier clase con `origin: "user"` (ver Errores comunes).
## Crear una nueva Configuración
1. Elige una Plantilla de Configuración
2. Sube un documento de pedido (PDF, hoja de especificaciones, correo del cliente) o pega el texto relevante
3. El agente lee las clases de opción de nivel superior de la plantilla, lee el pedido y planifica las selecciones, clase por clase
4. El agente descubre las clases de opción anidadas que se vuelven alcanzables tras las selecciones padre y las planifica también
5. El agente valida el conjunto completo de selecciones contra la plantilla: IDs desconocidos, violaciones de restricciones, selecciones inalcanzables todos fallan la validación
6. El agente confirma todas las sugerencias en una sola escritura, cada una etiquetada con confianza y razonamiento
7. El agente explica la configuración en el chat, llamando la atención sobre los elementos de confianza media y baja que necesitan revisión del usuario
8. El usuario revisa en la interfaz y anula donde sea necesario, las anulaciones se vuelven `origin: "user"`
9. El usuario guarda: se escribe un registro de Configuración en la versión 1
## Reconfigurar una Configuración existente
Cuando llega una solicitud de cambio contra una configuración guardada (pedido actualizado, correo del cliente, aviso de cambio de ingeniería) abre la configuración para iniciar una sesión de reconfiguración.
1. La sesión se pre-rellena desde la configuración origen. Todas las selecciones previas aparecen con `origin: "inherited"`
2. El agente lee el estado actual, la configuración origen y la plantilla
3. El agente analiza la solicitud de cambio y decide qué selecciones deben cambiar
4. El agente confirma solo las selecciones cambiadas, más una etiqueta corta de versión y un resumen no técnico de los cambios
5. El script fusiona los cambios, omitiendo cualquier selección que pertenezca al usuario, y vuelve a resolver la lista de partes
6. El usuario revisa y guarda: se crea una nueva Configuración con `version` incrementado, `parent_id` apuntando al predecesor y `changes_summary` poblado
La cadena de versiones es **unidireccional**: cada reconfiguración enlaza a su padre; no hay ramificación.
## El bucle de revisión
Después de las sugerencias iniciales, el usuario típicamente quiere anular algunas selecciones y pedirle al agente que vuelva a evaluar el resto:
1. El usuario cambia selecciones en la interfaz; las entradas afectadas pasan a `origin: "user"`
2. El usuario le pide al agente que vuelva a evaluar
3. El agente vuelve a leer el estado de sesión y ve las anulaciones del usuario
4. El agente confirma sugerencias solo para las clases de opción aún pertenecientes a `agent`/`inherited`/sin asignar
5. Si una anulación del usuario tiene implicaciones aguas abajo (p. ej., elegir un motor diferente revela una clase *Turbo Configuration* que antes no era alcanzable), el agente descubre y sugiere para las clases anidadas recién alcanzables
## Plantillas
Una plantilla es la fuente de verdad para lo que es configurable. Construir una bien es el trabajo de mayor apalancamiento en el Configurador: la forma del árbol de opciones determina lo que un constructor de cotizaciones puede responder.
Las plantillas se crean típicamente de dos maneras:
* **Desde cero**: para productos configurables genuinamente nuevos
* **Desde una exportación de ERP / tabla de configuración**: mediada por Pipeline, usando un [pipeline](/es/product/templates) para transformar datos tabulares en JSON de plantilla. Al ingerir desde datos de ERP, **los números de parte van en el campo dedicado `part_number`**, no en `name` ni en el slug de entidad. Los nombres deben ser legibles por humanos; los slugs deben derivarse de la descripción.
## Configuraciones
Las Configuraciones guardadas son de solo lectura. Cada una muestra:
* El mapa de selecciones: qué opción se eligió para cada clase de opción
* La lista de materiales resuelta: la lista plana de partes que se deriva de esas selecciones
* El linaje de versiones: cadena `parent_id`, `changes_summary` en cada paso
Para la última versión de una configuración, ordena por `version` y toma la más alta.
## Relación con otras funcionalidades
### BOMs estándar
La distinción más importante: **los BOMs estándar son recetas de producción planas**; **las Plantillas de Configuración definen un espacio de opciones**. Los BOMs alimentan directamente la [simulación](/es/product/simulation-modeling) y la [planificación](/es/product/planning); las plantillas no: producen Configuraciones guardadas, que llevan una lista de partes por pedido.
Si te encuentras queriendo usar una plantilla directamente en un modelo de planificación, esa es la señal de que realmente necesitas un BOM.
### Entidades
Una plantilla referencia entidades en dos lugares: la raíz de la plantilla (la familia de productos configurable) y los materiales dentro de cada opción (las partes específicas que cada selección trae). Las entidades también llevan los **atributos** que definen el espacio de configuración, el mismo sistema de atributos sobre el que operan las [condiciones de variante](/es/product/bom#variant-conditions) del BOM.
### Planificación
La lista de materiales resuelta de una Configuración guardada podría en principio alimentar órdenes de demanda de planificación: si sabes que un pedido específico necesita una lista de partes específica, eso informa la demanda de SKU. Hoy este enlace es **manual o mediado por pipeline**, no automático. Guardar una configuración no crea automáticamente una orden de demanda.
### Modelos de Simulación
Los modelos de simulación referencian BOMs estándar y entidades; no consumen Plantillas de Configuración ni Configuraciones directamente. Para simular un producto configurable, construye el BOM correspondiente y asegúrate de que los parámetros del modelo reflejen la configuración que te interesa.
## Errores comunes
**Las Plantillas de Configuración no son BOMs.** Una plantilla no puede referenciarse desde simulación o planificación. Si una funcionalidad que estás construyendo necesita alimentar al optimizador, construye un BOM estándar.
**Las selecciones del usuario son soberanas.** La ruta de sugerencias del agente omite silenciosamente cualquier clase de opción donde `origin: "user"`. Si un usuario ha elegido manualmente una opción y le pides al agente que sugiera algo diferente para esa clase, la sugerencia se descarta. El script informa qué clases se omitieron, pero puede sorprender a usuarios que esperan que el agente anule su elección.
**Las clases de opción anidadas son invisibles hasta que se hagan las selecciones padre.** Listar las clases de opción de una plantilla sin pasar las selecciones actuales solo retorna las clases de nivel superior. Las clases anidadas que viven dentro de una opción específica solo aparecen una vez que esa opción está en el conjunto de selección. Olvidar esto lleva a configuraciones incompletas.
Algunos más a tener en cuenta:
* `select_many` permite cero selecciones; `select_at_least_one` no. La validación al guardar detecta la diferencia, pero la restricción es fácil de malinterpretar al crear una plantilla.
* La ruta de sugerencia de reconfiguración requiere tanto un título corto de versión como un resumen de cambios. Olvidar cualquiera de los dos genera un error en el script.
* Las Configuraciones son de solo lectura una vez guardadas. Para "editar" una, recoanfigúrala (lo que produce una nueva versión con un enlace al padre), no hay edición en sitio.
* El anidamiento recursivo de opciones es poderoso pero fácil de sobre-complicar. La validación detecta errores estructurales, no diseño deficiente.
## Referencia
* **Esquema de plantilla**: entidad raíz, arreglo de componentes (materiales y clases de opción), anidamiento recursivo de opciones
* **Esquema de configuración**: `id`, `name`, `version`, `title`, `parent_id`, `template_slug`, `selections`, `resolved_materials`, `changes_summary`
* **Esquema de estado de sesión**: `session_id`, `template_slug`, `source_configuration_slug`, `status`, `selections`, `custom_items`, `parts_list`
* **Origen de selección**: `user`, `agent`, `inherited`
* **Tipos de selección**: `select_one`, `select_many`, `select_at_least_one`