Modifica un framework web con seguridad de tipos y separa el código de base de datos en tres capas

## Entra en el entorno de desarrollo fijado del repositorio y localiza el paquete responsable Entra en el entorno de desarrollo mediante el gestor de entornos declarado por el repositorio, en vez de depender de herramientas instaladas globalmente. ### Configuración del entorno - Empieza desde la raíz del repositorio y activa el intérprete de comandos de desarrollo aprobado. - Usa la ruta de ejecución almacenada en caché del entorno cuando esté disponible para acelerar los comandos repetidos. - Confirma que el compilador, el gestor de paquetes, las herramientas de base de datos y las herramientas de documentación procedan del entorno con versiones fijadas. - Usa la versión del entorno de ejecución declarada por el paquete o la configuración de documentación correspondientes. - Activa el registro de depuración solo cuando sea necesario para el diagnóstico local y no trates el modo de depuración como valor predeterminado de producción. ### Contexto de trabajo En un repositorio multipaquete, identifica el paquete responsable del cambio antes de ejecutar comandos. Localiza su directorio de código fuente, punto de entrada de pruebas, artefactos generados, módulos públicos e instrucciones locales, en vez de suponer que todos los paquetes comparten un único flujo de trabajo. ## Comprueba primero los tipos rápidamente y después ejecuta todas las pruebas Usa el ciclo de retroalimentación fiable más rápido durante las iteraciones y después ejecuta la validación oficial más amplia necesaria para la entrega. ### Iteración centrada - Prefiere un compilador interactivo, un verificador de tipos o un cargador de módulos para obtener rápidamente información sobre los tipos cuando compilar todo el entorno resulte costoso. - Durante las primeras iteraciones, carga solo el módulo modificado o el punto de entrada de pruebas específico. - Las herramientas interactivas que leen la entrada estándar deben recibir comandos y una ruta de salida explícita; de lo contrario, podrían esperar indefinidamente. - Cuando una sesión interactiva admita la recarga, reutilízala después de las modificaciones en vez de recompilar repetidamente todo el entorno. ### Registro de pruebas - Añade las pruebas nuevas al agregador de pruebas oficial del paquete o a su configuración de descubrimiento. - Confirma que la prueba específica se ejecute realmente a través de ese punto de entrada. - Ejecuta la validación completa del repositorio cuando el cambio esté listo o cuando afecte al comportamiento compartido, la configuración de compilación o los límites entre paquetes. - No presentes una comprobación de compilación específica como prueba de que toda la suite de pruebas pasa. ### Servidor de desarrollo Inicia los servicios locales únicamente desde el entorno aprobado y el directorio de trabajo correcto. Cuando el servidor de desarrollo dependa de una aplicación anfitriona o de un directorio superior, establece ese contexto explícitamente antes de invocar su punto de entrada. ## Da a cada paquete su propia función y expón solo módulos públicos mínimos Asigna responsabilidades antes de cambiar el código, especialmente en un repositorio que combina entorno de ejecución, herramientas de desarrollo, plantillas, migraciones, sincronización, interfaces de programación de aplicaciones, pruebas e integraciones opcionales. ### Mapa de responsabilidades - Mantén separados el inicio del servidor y el middleware de la configuración del framework. - Mantén el enrutamiento y la generación de URL con seguridad de tipos, y aíslalos del manejo de solicitudes. - Separa por responsabilidad los modelos, la validación, la autenticación, el trabajo en segundo plano, el almacenamiento, el correo y las actualizaciones en tiempo real. - Mantén la generación de código, el diseño del esquema y el comportamiento del servidor de desarrollo fuera del paquete principal de ejecución cuando la arquitectura los defina como herramientas. - Trata las integraciones opcionales y los componentes del servidor como paquetes separados, en vez de filtrar sus dependencias al núcleo. ### Interfaz pública Expón la menor superficie estable de módulos que necesiten los consumidores. Mantén privadas las sentencias sin procesar, la composición interna, los preámbulos auxiliares y los módulos de implementación para que puedan evolucionar sin romper a quienes los llaman. Añade la documentación de API estándar del proyecto a los módulos y funciones públicos. ### Convenciones del lenguaje Sigue los modismos establecidos del código base para valores puros, parámetros contextuales, acceso a campos, plantillas, enrutamiento a nivel de tipos y tipos de modelos. Prefiere la convención que ya usa el proyecto a una forma equivalente que aumente la incoherencia. ## No metas valores en el texto de la consulta y expón solo la capa de sesión Organiza el acceso a la base de datos en capas de sentencias, transacciones y sesiones, con una responsabilidad explícita sobre la codificación, la atomicidad y las conexiones. ### Capa de sentencias - Mantén las consultas parametrizadas sin procesar junto con sus codificadores de entrada y decodificadores de resultados. - Usa marcadores de posición para todos los valores del entorno de ejecución, en vez de interpolar valores en el texto de la consulta. - Codifica de forma explícita la nulabilidad y los tipos de la base de datos. - Elige un decodificador que coincida con la cardinalidad esperada: una fila opcional, una fila obligatoria o varias filas. - Mantén las decisiones de almacenamiento en caché de sentencias junto a la definición de la sentencia. ### Capa de transacciones - Combina sentencias para formar operaciones de negocio que requieran atomicidad. - Mantén dentro de la transacción las reglas de ramificación, las comprobaciones de existencia y las decisiones de creación cuando deban observar un único estado coherente. - Haz explícitos los resultados idempotentes para que quienes llaman puedan distinguir un registro existente de uno recién creado. - Usa una composición independiente o selectiva solo cuando las operaciones sean verdaderamente independientes y conserven la semántica prevista de la transacción. ### Capa de sesiones - Presenta la capa de sesiones como la interfaz pública de la base de datos. - Deja que las sesiones se encarguen de ejecutar las conexiones y delimitar las transacciones, mientras ocultan las sentencias sin procesar y las transacciones internas. - Usa una transacción explícita para operaciones de varias sentencias y la ejecución directa de una sentencia para una única consulta independiente. ## Ajusta el nivel de aislamiento y el tipo de resultado a cada operación de base de datos Ajusta el aislamiento, la cardinalidad y los tipos de resultado a la semántica de la operación, en vez de aplicar el mismo patrón en todas partes. ### Opciones de aislamiento - Usa una transacción de escritura fuerte para operaciones críticas cuya corrección dependa de la serialización. - Usa un nivel de aislamiento de lectura apropiado para consultas en las que la concurrencia sea relevante y se acepte un aislamiento más débil. - Documenta toda operación cuya corrección dependa de un modo de aislamiento específico. ### Convenciones de resultados - Representa los resultados de cero o una fila mediante un valor opcional. - Representa los resultados de varias filas mediante el tipo de secuencia estándar del proyecto. - Usa tuplas para pequeños resultados internos de varias columnas cuando los envoltorios con nombre no aporten ningún límite útil. - Devuelve un indicador de éxito explícito cuando una actualización o eliminación pueda no afectar a ninguna fila. - En operaciones idempotentes, devuelve tanto si se realizó el trabajo como el valor resultante. ### Composición de códecs Cuando una biblioteca de codificadores componga pares anidados, adapta deliberadamente las tuplas de entrada planas y mantén la asignación junto a la sentencia. Combina los decodificadores de forma que conserven el orden de las columnas, la nulabilidad y la cardinalidad de las filas. Añade pruebas específicas para los desajustes que podrían asignar silenciosamente valores al campo equivocado. ## Añade dependencias solo donde se usan y nunca hagas force-push Mantén los cambios compatibles, revisables y recuperables. ### Código y dependencias - Usa las formas del lenguaje preferidas por el proyecto cuando mejoren la claridad para quienes contribuyen. - Documenta las interfaces públicas con el sistema de documentación estándar del repositorio. - Respeta las extensiones de lenguaje habilitadas en el código base y no introduzcas extensiones nuevas sin una necesidad concreta. - Añade dependencias únicamente al paquete que las utiliza. - Declara límites inferiores y superiores de compatibilidad adecuados para el ecosistema compatible. - Trata las dependencias experimentales como un riesgo explícito y aíslalas detrás de interfaces estrechas. ### Seguridad de Git - Nunca uses `force-push`, incluido `force-with-lease`. - Si la rama remota ha avanzado, ejecuta `fetch` y aplica `rebase` o `merge` sobre el historial actualizado, resuelve los conflictos, valida y ejecuta un `push` normal. - No ocultes un `push` rechazado reescribiendo el historial compartido. - Mantén fuera del commit los archivos generados no relacionados, los cambios del archivo de bloqueo y los ajustes locales de rendimiento. ## Deja las sustituciones locales fuera de los commits y publica la documentación por el proceso de publicación Usa sustituciones locales de rendimiento y dependencias durante el desarrollo sin permitir que se filtren al control de código fuente compartido. ### Sustituciones locales de rendimiento - Se pueden activar indicadores temporales de compilación rápida para las iteraciones locales cuando el proyecto los admita. - No incluyas en un commit un cambio de rendimiento exclusivamente local. - Antes de la entrega, examina el diff real en vez de confiar únicamente en indicadores del índice que puedan ocultar modificaciones. ### Desarrollo local de dependencias Al desarrollar conjuntamente un framework y una aplicación que lo consume: 1. Coloca la copia local del framework en una ubicación de desarrollo elegida deliberadamente. 2. Dirige la dependencia de la aplicación a esa ruta local mediante el mecanismo de sustitución compatible. 3. Activa el entorno necesario y actualiza el estado de las dependencias. 4. Prueba la aplicación con el framework local. 5. Retira o documenta intencionadamente la sustitución antes de preparar los cambios compartidos. ### Documentación y publicación - Previsualiza la documentación localmente desde su entorno designado. - Cuando la documentación publicada se mantenga por separado, actualiza su dependencia del framework o de la documentación mediante el flujo de trabajo aprobado del repositorio. - Incluye en el commit solo los cambios del archivo de bloqueo o del código fuente que requiera esa actualización. - Despliega la documentación o la infraestructura únicamente mediante el proceso de publicación designado, respetando el orden exigido entre la actualización de dependencias, el estado confirmado y el despliegue. - Cuando una versión del framework requiera sincronizar la documentación dependiente, incluye ese paso en la lista de comprobación de publicación en vez de confiar en la memoria.