Mantener sincronizados el backend y el frontend de una app de generación mediante OpenAPI

## Regenerar los tipos y clientes de OpenAPI tras cada cambio en la API del backend Después de cada cambio en una API del backend, ejecuta el comando de actualización de OpenAPI del repositorio. Trata el schema generado y los tipos del frontend como parte del mismo cambio, no como una limpieza posterior. El código del frontend debe llamar a los endpoints del backend mediante el cliente OpenAPI generado. No añadas envoltorios service escritos a mano que dupliquen los contratos generados de solicitud y respuesta. Mantén una separación estricta de las responsabilidades del backend: - la capa API analiza la entrada, realiza la autenticación y la autorización, y organiza las respuestas; - la capa service es responsable de las reglas de negocio, las transiciones de estado y la coordinación de datos. Coloca los contratos de generación que cruzan capas, incluidos los DTO de entrada y salida y la configuración de proveedores, en un módulo contracts compartido. Los módulos task deben contener el envoltorio, la asignación y la coordinación de la ejecución de tareas, no definiciones de DTO compartidos. Los módulos integration pueden depender de los contracts compartidos, pero no deben depender de módulos de tipos internos de task. Cuando cambie una API, un tipo o un modelo de estado, actualiza conjuntamente la implementación del backend, el documento OpenAPI, los tipos generados del frontend, el uso del cliente y la documentación directamente relacionada. ## Comentar cada función y separar en la documentación los hechos actuales de los planes futuros Cuando un estilo del frontend se repita más de una vez, prioriza un componente reutilizable o una estructura de estilos compartida en lugar de otra copia. Cada función, clase o bloque de código equivalente necesita un comentario que explique qué hace y por qué existe. La lógica compleja también debe documentar los parámetros pertinentes, el comportamiento del valor devuelto y las decisiones internas esenciales. Mantén los comentarios sincronizados con la implementación. Clasifica la documentación antes de escribirla: - `guide` explica cómo realizar una tarea o integrar una capacidad; - `architecture` registra el sistema implementado actualmente; - `plans` registra el trabajo futuro, las tareas por etapas y los cambios propuestos; - `reference` contiene hechos estables destinados a consulta; - `blog` contiene las notas de la versión. Incluye los límites actuales, las transiciones de estado implementadas y el comportamiento real en la documentación de architecture. Incluye en plans el trabajo que todavía se diseña o ejecuta. Incluye en guide los procedimientos operativos y los flujos de desarrollo. No mezcles hechos actuales e intenciones futuras en un mismo documento how-to. Sepáralos entre architecture y plans aunque traten el mismo tema. No modifiques una nota histórica de versión ya finalizada salvo que la tarea lo exija de forma explícita. ## Mantener ligero el centro de tareas y dar a cada pantalla del flujo su propia tarea Divide el flujo principal del usuario en superficies con responsabilidades claras: - una página de preparación extrae datos del dominio, confirma candidatos, corrige información básica y lleva el elemento a `ready`; - un espacio de generación comprueba la preparación de la salida, gestiona los recursos y parámetros clave, inicia la generación y presenta los resultados; - un centro de tareas muestra únicamente información ligera y genérica, como estado, progreso, éxito, fallo, cancelación y un enlace de regreso. No coloques resúmenes específicos del dominio, contexto de depuración de prompts, correspondencias de recursos ni otros detalles pesados en el centro de tareas genérico. Consérvalos en el panel correspondiente de preparación, generación, ejecución o diagnóstico. Si las herramientas de extracción siguen disponibles en el espacio de generación, ofrécelas solo como accesos directos o herramientas de diagnóstico. No deben sustituir a la página de preparación como superficie principal de confirmación. Cuando cambie un límite de responsabilidad, actualiza tanto la UI relacionada como la documentación de architecture. El rediseño del centro de tareas no debe convertirlo en una nueva página de detalles de negocio. ## Usar el estado del elemento solo para la confirmación, no para el progreso de la generación Usa el estado principal del elemento del dominio únicamente para el estado de confirmación de información: - `pending` significa que aún queda trabajo de extracción o confirmación; - `ready` significa que la información necesaria está confirmada y puede comenzar la preparación posterior. No uses ese estado para representar la generación en tiempo de ejecución. Los valores como `generating` pertenecen al sistema de tareas y al runtime summary. Representa la preparación de la salida como una dimensión independiente. Que un elemento esté `ready` para la preparación posterior no garantiza que cumpla todas las condiciones necesarias para generar. Cada interfaz de usuario debe distinguir: 1. el estado de confirmación de información; 2. el estado de la tarea en tiempo de ejecución; 3. la preparación para generar la salida. Cuando cambie la semántica de los estados, sincroniza el comportamiento del backend, OpenAPI, los tipos generados del frontend, las etiquetas de estado, las condiciones de navegación y la documentación de desarrollo. ## Llevar al usuario de la página de preparación al espacio de generación tras confirmar El flujo estándar es: 1. extraer elementos de trabajo del contenido de origen; 2. confirmar y corregir en la página de preparación los recursos, diálogos u otra información necesaria que se haya extraído; 3. pasar al espacio de generación para revisar los recursos clave, el material de referencia, los parámetros de salida y la preparación; 4. iniciar la generación desde el espacio de generación; 5. revisar los resultados en el espacio del dominio y usar el centro de tareas únicamente para el progreso genérico. La página de preparación es responsable de la extracción, la confirmación y la corrección. El espacio de generación es responsable de preparar y ejecutar la generación y de revisar los resultados. Después de completar la preparación, dirige claramente al usuario al espacio de generación. Si el espacio detecta que un elemento no está `ready`, devuelve al usuario a la preparación con una explicación clara. Prioriza este flujo al modificar las interacciones. Los accesos directos de conveniencia no deben ocultar el siguiente paso canónico ni fusionar la preparación y la generación en una superficie ambigua. ## Actualizar la documentación de architecture con cada cambio y dar pasos de migración utilizables en las notas de versión La documentación de architecture contiene únicamente comportamiento vigente. Plans contiene trabajo en curso, tareas por etapas, prioridades y rutas de ejecución futuras. Cuando cambien el comportamiento del código, la semántica de los estados o las responsabilidades de una página, actualiza la documentación de architecture en el mismo trabajo. Cuando cambien el alcance, la prioridad o el orden de un plan, actualiza plans. Un plan ya implementado debe pasar a architecture o convertirse en una nota de versión. Considera incompleto cualquier trabajo que deje obsoleta la documentación de architecture o plans. Las notas de versión deben incluir frontmatter para `title`, `date`, `description`, `tags` y `authors`. Usa un orden estable de secciones y omite solo las que no correspondan: 1. Aspectos destacados; 2. Añadido, cambiado y corregido; 3. Cambios incompatibles y elementos obsoletos; 4. Seguridad y problemas conocidos; 5. Guía de migración e instrucciones de reversión; 6. Matriz de compatibilidad, comandos de validación y lista de actualización; 7. Referencias, notas para contribuidores y agradecimientos. Redacta las notas con voz de responsable de mantenimiento: presenta primero las conclusiones y la información ejecutable, usa párrafos cortos y listas, y mantén una terminología estable. Separa claramente las capacidades nuevas, los cambios de comportamiento, los riesgos de compatibilidad y los problemas conocidos. Los pasos de migración, los pasos de reversión y los comandos de validación deben poder usarse directamente, sin ambigüedad. ## Terminar solo cuando los tipos generados y la documentación coincidan con el código El trabajo solo está terminado cuando se cumplen todas las condiciones aplicables: 1. la implementación está presente y no quedan marcadores provisionales evidentes ni código de compatibilidad obsoleto; 2. las funciones y clases nuevas o modificadas tienen comentarios precisos y útiles; 3. los cambios de API han actualizado OpenAPI, los tipos generados del frontend y el uso del cliente generado; 4. el comportamiento actual está reflejado en la documentación de architecture y el trabajo futuro en plans; 5. las responsabilidades de preparación, generación y centro de tareas siguen separadas; 6. los cambios del frontend superan la comprobación TypeScript sin emisión del repositorio; 7. los cambios del backend superan las pruebas pertinentes o, como mínimo, las comprobaciones documentadas de sintaxis e import; 8. el informe de finalización indica qué cambió y qué validaciones se superaron; 9. el trabajo restante o las recomendaciones posteriores se enumeran por separado. No declares el trabajo terminado mientras el código, los contratos, los tipos generados, la documentación, la semántica de estados o las superficies del flujo sean incoherentes.