Nodos de ciclo de vida y universo

Los nodos de ciclo de vida y universo de AQS exponen el modelo de componentes de AQE en el grafo visual de la estrategia. Permiten mantener modular el comportamiento de la estrategia sin editar manualmente el src/main.rs generado en proyectos .aqmeta.

Puedes seguir escribiendo esta lógica directamente en Rust. Los nodos sirven para organizar el código en módulos: responsabilidades separadas, una estructura de grafo más clara, archivos reutilizables y una configuración más sencilla en el editor.

Tipos de nodos

AQS proporciona cuatro tipos de nodos modulares para este flujo de trabajo:

• On Start Logic crea un componente OnStartLogic.
• On Init Logic crea un componente OnInitLogic.
• On Teardown Logic crea un componente OnTeardownLogic.
• Universe Model crea un componente UniverseModel.

Los archivos de lógica del ciclo de vida usan el sufijo .logic.rs. Los archivos de modelos de universo usan el sufijo .universe.rs.

Cómo los usan los proyectos generados

Cuando un proyecto tiene un archivo .aqmeta, AQS controla el grafo y regenera src/main.rs. No edites manualmente el src/main.rs generado para estos componentes. En su lugar, añade o edita el archivo del componente personalizado y actualiza la configuración del nodo.

La generación de código se encarga del registro:

• los nodos de lógica del ciclo de vida se convierten en envoltorios de ciclo de vida de AQE;
• los nodos de modelos de universo se convierten en envoltorios de modelos de universo de AQE;
• los argumentos del constructor se exponen como propiedades públicas del nodo;
• los campos privados de las estructuras pueden aparecer como propiedades de solo lectura o privadas en el panel;
• el orden de ejecución sigue la topología del grafo cuando los nodos están encadenados.

Momento de ejecución de los nodos de ciclo de vida

Los nodos de ciclo de vida permiten configurar cuándo se ejecutan:

• Before generated ejecuta el componente antes del cuerpo generado para ese método del ciclo de vida.
• After generated ejecuta el componente después del cuerpo generado para ese método del ciclo de vida.

Usa Before generated para requisitos previos y validación. Usa After generated cuando la lógica dependa de que el registro o la configuración generados ya estén completos.

Ejemplos:

• inicializar ctx.variables() antes de que lo lean los modelos alfa;
• validar las variables de entorno requeridas antes de que empiece la estrategia;
• inicializar metadatos específicos por símbolo después de conocer el activo;
• volcar los diagnósticos de ejecución después de la finalización.

Comportamiento ante fallos

Cada nodo tiene un ajuste can_fail.

• can_fail = false significa que un resultado no satisfactorio debe detener la ejecución.
• can_fail = true significa que AQE registra el fallo y continúa.

La lógica de arranque e inicialización normalmente debe ser estricta. La finalización normalmente puede fallar sin detener las demás tareas de limpieza.

Modelos de universo en el grafo

Los nodos Universe Model devuelven símbolos de forma programática. Son útiles cuando la lista estática del universo resulta demasiado limitada.

Usa un nodo Universe Model para:

• cargar una lista de seguimiento;
• filtrar símbolos por metadatos;
• elegir símbolos por fecha o régimen;
• seleccionar símbolos a partir de restricciones de cuenta, bróker o riesgo;
• compartir la misma lógica de selección del universo entre estrategias.

El universo final de AQE es la unión del universo estático devuelto por la estrategia generada y todos los modelos de universo conectados. Los símbolos duplicados se eliminan.

Esto significa que puedes mantener un nodo de universo estático sencillo y añadir un nodo Universe Model para incorporar símbolos de forma dinámica.

El código escrito directamente sigue siendo válido

El flujo de trabajo con nodos no es obligatorio. Para estrategias pequeñas, a menudo basta con escribir el código Rust directamente en los métodos de la estrategia:

• añade código de arranque directamente en on_start;
• añade configuración por activo directamente en init;
• devuelve símbolos directamente desde universe;
• añade limpieza directamente en on_teardown.

Usa nodos cuando el código merezca su propio archivo, deba ser visible en el grafo de AQS, necesite configuración en el panel de propiedades o vaya a reutilizarse.

Buenas prácticas

• Reserva los argumentos del constructor para ajustes configurables por el usuario.
• Coloca el estado exclusivo de la ejecución en ctx.variables() en lugar de en campos de estructuras.
• Usa nodos de ciclo de vida para configuración y limpieza, no para generar señales de trading.
• Mantén la generación de señales en los modelos alfa.
• Mantén la lógica de dimensionamiento, envío, cancelación, cierre y gestión en los pipes de insights.
• Encadena nodos de ciclo de vida cuando importe el orden exacto.
• Devuelve mensajes claros de LifecycleResult y UniverseResult para que los registros y las vistas de AQS resulten útiles.

Patrones habituales del grafo

Para el arranque:

1. Conecta On Start Logic al puerto de ciclo de vida de la estrategia.
2. Establece el momento de ejecución en Before generated si el registro generado de modelos alfa o pipes depende de ello.
3. Inicializa el estado compartido en ctx.variables().
4. Devuelve un LifecycleResult satisfactorio.

Para la inicialización por activo:

1. Conecta On Init Logic al puerto de inicialización del ciclo de vida.
2. Usa el argumento asset para inicializar el estado específico por símbolo.
3. Almacena ese estado bajo el nombre del componente y el símbolo del activo.

Para la finalización:

1. Conecta On Teardown Logic al puerto de finalización del ciclo de vida.
2. Establece can_fail = true salvo que el fallo deba invalidar la ejecución.
3. Guarda o resume los diagnósticos de ejecución.

Para la selección del universo:

1. Crea un nodo Universe Model.
2. Implementa UniverseModel::run(ctx) -> UniverseResult.
3. Devuelve únicamente los símbolos de los que sea responsable el modelo.
4. Deja que AQE combine esos símbolos con el universo estático y los demás modelos de universo.