Modificar un repositorio full stack con sus propios comandos y pruebas

## Leer primero la documentación y trabajar en una rama con pull request Antes de planificar un cambio, lea las directrices generales del repositorio, la documentación de los subsistemas, los manifiestos de paquetes y las implementaciones cercanas. Identifique todas las áreas afectadas, incluidos el frontend, la API, el SDK, la CLI, la base de datos, los contenedores y la documentación. Trate la rama predeterminada protegida como de solo lectura para el desarrollo directo. Cree una rama con un nombre descriptivo, haga commits significativos y abra una solicitud de incorporación para su revisión. No reescriba el historial compartido modificando un commit existente y no fusione su propia solicitud cuando el flujo de trabajo asigne esa decisión a un revisor. Mantenga la rama centrada en el comportamiento solicitado. Separe las tareas de limpieza no relacionadas y conserve los patrones establecidos, salvo que la tarea requiera un cambio deliberado. ## Usar los comandos del repositorio y las versiones fijadas del entorno Antes de ejecutar nada, localice los comandos documentados de desarrollo, formato, lint, pruebas, migraciones e inicio. Utilice el comando administrado por el paquete afectado en lugar de sustituirlo por una herramienta que abarque toda la raíz. Respete las versiones fijadas del entorno de ejecución y los entornos existentes; una versión principal más reciente no es compatible de forma automática. Instale dependencias únicamente cuando falten. No inicie la pila completa de la aplicación, los contenedores ni servidores de larga duración, salvo que la tarea o la verificación pertinente los requiera. Ejecute los formateadores y linters sobre los archivos modificados con los modos documentados. Comience con un selector compatible para una sola prueba y amplíe únicamente al conjunto directamente afectado. Cuando un subsistema importe un paquete SDK instalado en lugar de su árbol de código fuente, vuelva a instalar ese SDK después de editarlo y reinicie el proceso que lo utiliza. Compruebe los puertos y requisitos previos antes de iniciar procesos de desarrollo combinados. ## Mantener separado el papel de la interfaz, la API, los servicios y las migraciones Distribuya las responsabilidades antes de editar: - la interfaz de usuario se encarga de la presentación y del estado del cliente; - la API se encarga de validar solicitudes y de los aspectos de transporte; - los módulos de servicio se encargan de la lógica de negocio; - los paquetes SDK y CLI se encargan de sus contratos de interfaz pública; - las migraciones se encargan de la evolución de la base de datos. Lea la documentación del subsistema que va a modificar e inspeccione archivos similares existentes antes de introducir un patrón nuevo. Cuando un cambio atraviese varias capas, avance en pasos pequeños: defina tipos o esquemas, implemente la lógica del servicio, exponga el contrato de la API, actualice el cliente y, por último, construya la interfaz. Instale cada dependencia en el paquete que la utiliza. Cuando añada un paquete al espacio de trabajo, actualice todos los manifiestos de compilación de contenedores de producción y locales que copien metadatos de paquetes antes de instalar las dependencias. ## Seguir las reglas de TypeScript, Python y la base de datos Utilice tipos estrictos de TypeScript, evite tipos sin límites, defina claramente los contratos de componentes y API y siga los patrones establecidos de componentes y gestión del estado del repositorio. Prefiera componentes funcionales y acciones de estado explícitas a pasar propiedades por muchas capas. En código Python, proporcione indicaciones de tipo en cada límite de función, utilice modelos de validación para la serialización y mantenga la lógica de negocio en los servicios, no en los routers de transporte. Los routers deben validar solicitudes, llamar a servicios y dar forma a las respuestas. Siga las reglas existentes de tablas y migraciones, incluida cualquier prohibición de claves foráneas. Mantenga las operaciones de base de datos portables entre todos los motores compatibles. Utilice el auxiliar UTC del repositorio para los campos de fecha y hora, en lugar de la hora local, API obsoletas o conversiones creadas manualmente. Respete la decisión del repositorio sobre el almacenamiento en el sistema de archivos o en la base de datos. No traslade a una base de datos los datos sincronizados del clúster solo por comodidad. ## Probar cada cambio en la capa y el conjunto de pruebas que le corresponden Utilice el sistema de pruebas realmente configurado para cada subsistema. Si el frontend no dispone de un marco de pruebas unitarias, cubra su comportamiento con el conjunto designado de pruebas de extremo a extremo en lugar de introducir un ejecutor no compatible. Coloque las pruebas unitarias y de servicio del backend en su árbol establecido y ejecute el conjunto de pruebas de la CLI después de modificar su código fuente. Simule el almacenamiento externo, los proveedores de cómputo y las interacciones con el sistema de archivos para que las pruebas sean rápidas y deterministas. Prefiera pruebas directas del servicio para las reglas de negocio que no necesiten toda la pila de la API. Ejecute primero una prueba específica y después el conjunto del subsistema pertinente. Haga que las ejecuciones repetidas sean seguras con datos existentes, utilice selectores estables y permita tiempos de espera realistas para trabajos en cola o transiciones de estado. No afirme que una operación tuvo éxito basándose únicamente en el nombre de un comando. Confirme que se descubrieron los archivos de prueba previstos y que el resultado ejercita el comportamiento modificado. ## Revisar las páginas cambiadas en el navegador y probar las API con inicio de sesión Utilice la herramienta de navegador interactiva aprobada por el repositorio para la inspección visual. Reserve los scripts automatizados de extremo a extremo para el conjunto de pruebas mantenido o para una solicitud explícita. Inicie solo la aplicación de prueba necesaria, visite las páginas modificadas y las directamente relacionadas, capture evidencias y corrija las regresiones visibles. Prefiera selectores por rol, texto exacto y marcador de posición. Procese los datos de prueba repetidos sin suponer que la base de datos está vacía. Es posible que el contenido representado por un emulador de terminal no exista en el DOM; cuando sea necesario, verifíquelo mediante la API subyacente. Para comprobar una API autenticada, utilice la identidad de prueba y el flujo de autenticación documentados. Proporcione los encabezados necesarios del ámbito de cuenta o inquilino, distinga entre endpoints protegidos y no protegidos y nunca incluya credenciales reutilizables en el código fuente, los registros ni la documentación resultante. ## Añadir dependencias con cuidado y no dejar contraseñas en los registros Revise los manifiestos de paquetes antes de añadir dependencias y utilice el flujo de instalación del repositorio. Mantenga activos los hooks de formato y lint previos al commit cuando el proyecto dependa de ellos. Trate las anulaciones de dependencias como controles de seguridad temporales, no como decoración permanente. Al actualizar un paquete superior, compruebe si puede retirar la anulación, ejecute el análisis de vulnerabilidades pertinente y consérvela si la dependencia resuelta sigue sin ser segura. No amplíe la exposición de credenciales durante las pruebas de integraciones. Simule los proveedores externos cuando su comportamiento real no sea el objeto de la prueba y mantenga los registros libres de tokens, contraseñas e identificadores personales. ## Revisar los cambios e informar de las evidencias antes de terminar Lea antes de planificar, realice la implementación coherente más pequeña y verifique cada límite afectado antes de ampliar el alcance. Para cambios más grandes, mantenga la secuencia explícita y revisable, en lugar de mezclar el backend, la API, el cliente y la interfaz en un único paso opaco. Antes de informar que ha terminado, inspeccione las diferencias y ejecute el formateador, el linter, la comprobación de tipos, las pruebas, las comprobaciones de migración y la verificación visual que requieran las áreas modificadas. No añada una compilación completa ni un conjunto no relacionado solo para aparentar exhaustividad. Informe qué cambió, qué comprobaciones se ejecutaron, qué verificaciones más amplias quedaron deliberadamente fuera del alcance y qué riesgos residuales existen. La finalización requiere evidencias procedentes del comportamiento modificado, no solo una edición satisfactoria.