📑 Índice

• 🔐 Política de control de ramas
  • 📋 Reglas comunes (main y dev)
  • 🧽 Reglas específicas por rama
    • 🔸 Rama main
    • 🔸 Rama dev
  • 🧹 Convención para nombres de ramas - Proyecto Database
  • 🗘️ Estrategia recomendada para generar migraciones
• 🚀 Resumen
• 📄 Database Setup
  • 🚀 Requisitos
  • 📘️ Levantar la Base de Datos con Docker
  • 💄️ Si ya cuentas con una Base de Datos o Volumen creado

🔐 Política de control de ramas

Este repositorio implementa una estrategia de protección de ramas crítica (main y dev) orientada al control de acceso, trazabilidad y revisión colaborativa.

Las reglas se aplican mediante Branch Protection Rules y pueden reforzarse con GitHub Actions.

📋 Reglas comunes (main y dev)

• ❌ Push directo prohibido para todos los usuarios (incluyendo administradores).
• ⚙️ Activar Require linear history para mantener un historial limpio (sin merge commits).
• 🔧 Configurar Branch Protection Rules en GitHub para asegurar cumplimiento automático.
• 🤖 Automatización recomendada con GitHub Actions:
  • Cierre automático de PRs inválidos (por origen o falta de revisiones).
  • Validación de condiciones antes del merge.

🧽 Reglas específicas por rama

🔸 Rama main

• ✅ Solo acepta Pull Requests provenientes de la rama dev.
• 🔒 Solo el administrador o propietario del repositorio puede crear y hacer merge de PRs.
• ❗ No requiere revisión formal, pero el responsable del merge debe validarlo explícitamente.
• ❌ Cualquier PR hacia main desde otra rama debe ser cerrado automáticamente.

🔸 Rama dev

• ✅ Cualquier colaborador puede abrir Pull Requests hacia esta rama.
• 🔒 Solo el administrador o propietario puede hacer merge.
• ✅ Cada PR requiere al menos una aprobación de un líder técnico antes del merge.

🧹 Convención para nombres de ramas - Proyecto Database

Usamos una nomenclatura clara y estructurada para mantener un historial limpio y trazable en la gestión de cambios relacionados con entidades, migraciones y configuración de base de datos.

| Tipo de rama | Prefijo sugerido | Ejemplo | Propósito | |-----------------------|--------------------|----------------------------------------------|-------------------------------------------------------------| | Nueva entidad | entity/ | entity/create-user | Crear una nueva entidad en src/entities/ | | Actualización entidad| entity-update/ | entity-update/add-phone-to-user | Modificación o adición de campos a una entidad existente | | Nueva migración | migration/ | migration/initial-schema | Crear una nueva migración para reflejar cambios en la DB | | Refactorización DB | refactor-db/ | refactor-db/normalize-transaction-table | Cambios estructurales sin afectar funcionalidad | | Corrección migración | bugfix/migration/| bugfix/migration/fix-user-foreignkey | Corregir un problema en una migración existente | | Scripts CLI | script/ | script/add-revert-script | Crear o actualizar scripts para manejo de migraciones | | Configuración DB | config/ | config/update-datasource-file | Cambios en configuración (data-source.ts, .env, etc.) | | Documentación | docs/ | docs/add-migrations-guide | Mejoras o creación de documentación | | Experimentación | experiment/ | experiment/typeorm-seeding | Pruebas o prototipos no estables |

📌 Reglas

• Minúsculas.
• Palabras separadas por guiones (-).
• Nombres claros, cortos y específicos.
• Prefijos siempre en inglés para mantener consistencia técnica.
• Cuando se relacione a migraciones, reflejar la acción: create, update, delete, fix.

📌 Notas: Se recomienda acumular múltiples cambios estructurales relacionados antes de generar una migración. No es necesario que cada rama tenga su propia migración.

✅ Ejemplos reales para este proyecto

| Acción | Rama sugerida | |------------------------------------------------------------|--------------------------------------------------------| | Crear entidad AccountStatus | entity/create-account-status | | Agregar campo is_active a entidad User | entity-update/add-active | | Crear migración inicial del esquema | migration/initial-schema | | Corregir error en FK de tabla transactions | bugfix/migration/fix-transaction-foreign-key | | Añadir script para revertir migraciones | script/add-revert-script | | Documentar el proceso de migraciones | docs/add-migrations-readme | | Experimentar con seeders | experiment/typeorm-seeders |

🗘️ Estrategia recomendada para generar migraciones

Para evitar contaminación de migraciones innecesarias y tener un historial limpio, se recomienda:

✅ Acumular cambios relacionados

Es válido realizar múltiples cambios estructurales (crear entidades, agregar o modificar columnas) en varias ramas, sin generar migraciones en cada una.

La generación de migración se debe hacer cuando:

• Los cambios de estructura estén completos y revisados.
• Los cambios estén validados funcionalmente.
• Los cambios afecten el mismo contexto o módulo.

Ejemplo de flujo recomendado:

1. En la rama entity/create-user se crea la entidad User.
2. En la rama entity-update/add-phone-to-user se agrega un campo phone.
3. Una vez aprobados ambos PRs, se genera una sola migración en una rama como:

migration/add-user-entity

Que contenga ambos cambios.

❗️ Evitar migraciones innecesarias

No se recomienda generar migraciones cada vez que:

• Se haga un cambio pequeño o aislado.
• Estés en desarrollo activo de las entidades y sabes que cambiarán pronto.
• Haya cambios que pueden ser agrupados lógicamente.

✅ Casos donde sí debes generar la migración inmediatamente

• Cambios urgentes o críticos que deban aplicarse en producción.
• Cuando un cambio impacta otro microservicio que depende de la estructura.
• Cuando es un cambio probado, versionado y que no dependerá de otros.

🚀 Resumen

| Situación | Recomendación | |---------------------------------------------------------------|---------------------------------------------------| | Cambios pequeños o múltiples en proceso | Esperar y agrupar migración. | | Cambio crítico, urgente o listo para producción | Generar migración inmediatamente. | | Cambios dependientes de otros cambios | Aguardar a que todos estén listos y generar una sola migración. |

📄 Database Setup

Repositorio dedicado a la administración de la base de datos para el ecosistema Yapsi, utilizando PostgreSQL, TypeORM, NestJS y migraciones controladas.

🚀 Requisitos

Para correr este proyecto, asegúrate de tener instalado:

• Docker & Docker Compose
• Node.js y npm o Yarn

Instalación de dependencias:

yarn install 

📘️ Levantar la Base de Datos con Docker

Este proyecto incluye un script automatizado para asegurar que la base de datos se encuentre disponible en un contenedor compartido con el nombre yapsi_db_docker_container.

🔧 Ejecutar el script de setup

⚠️ Advertencia: Este comando debe ejecutarse desde una consola o terminal compatible con Bash (por ejemplo: Git Bash en Windows, terminal de Linux o macOS).

Ejecuta el comando una vez para dar permisos de ejecución:

chmod +x setup_wallet_db.sh

Ejecuta el archivo con el comando:

./setup_wallet_db.sh

Este script hace lo siguiente:

• Verifica si existe el contenedor yapsi_db_docker_container
• Si no existe, lo crea con PostgreSQL y la base yapsi_db
• Si ya existe pero está detenido, lo levanta
• Verifica si existe la base wallet_db y la crea si no existe
• Usa las variables del archivo .env para configurar conexión

✅ Este script garantiza que ambas bases estén disponibles sin duplicar contenedores PostgreSQL.

🗄️ Si ya cuentas con una Base de Datos o Volumen creado

Si ya tienes una base de datos existente o un volumen previamente creado:

Primero, dentro del contenedor, crea la base de datos con el nombre deseado si no existe.

Luego, en tu proyecto, ejecuta:

yarn migration:run

Este comando ejecutará las migraciones definidas en el proyecto para cargar la estructura de las entidades.

📌 Nota: Asegúrate de que el nombre de la base de datos coincida exactamente para evitar inconsistencias o errores.

⚠️ Advertencia: Este proceso es compatible con entornos controlados por migraciones. Si estás trabajando sin ellas, considera usar synchronize: true únicamente en desarrollo.

📁 Uso del archivo .env

El archivo .env se utiliza tanto para:

• Configurar la ejecución del script setup_wallet_db.sh
• Definir credenciales de conexión para el data-source.ts de TypeORM y ejecutar migraciones de forma consistente

Ejemplo:

DB_USERNAME=postgres
DB_PASSWORD=admin
DB_PORT=5432
DB_DATABASE=wallet_db
DB_YAPSI_DATABASE=yapsi_db

🗘️ Esta política y guía pueden adaptarse según el contexto del proyecto y el tamaño del equipo.