Guía de procesos

Este documento describe, en formato de guías paso a paso (How-to), los procesos más comunes en el equipo de desarrollo. El objetivo es garantizar consistencia, facilitar el onboarding de nuevos integrantes y servir como referencia para auditorías.

---

1. Preparación del entorno de desarrollo

• Cómo clonar el repositorio.

  git clone https://gitlab.com/queavos/unae_app.git

• Instalación de dependencias (backend y frontend).

  cd unae_app
  composer install
  npm install

• Configuración de variables de entorno (.env).

  cp .envExample .env

• Arranque de servicios locales (Laravel, React, PostgreSQL).

  cd unae_app
  php artisan serve
  npm run dev

2. Flujo de control de versiones (Git)

• Convenciones de ramas (prod, development, development2, test).

• Convenciones de mensajes de commit (Conventional Commits).

  Nota

  El flujo de control de versiones es el siguiente:

  1. prod es la rama principal, donde se encuentra el código fuente de producción.
  2. development es la rama de desarrollo perteneciente a desarrollador x.
  3. development2 es la rama de desarrollo perteneciente a desarrollador y.
  4. test es la rama de test, donde se realizan los merge de las ramas development y development2 y se hacen las pruebas antes de subir los cambios a producción.
  5. En caso de ser necesario se crean mas ramas para el desarrollo de nuevas funcionalidades.

3. Migraciones y base de datos

• Cómo crear migraciones en Laravel.

  php artisan make:migration create_table_name

• Cómo aplicar migraciones en entornos locales y remotos.

  php artisan migrate

• Estrategia de rollback de migraciones.

  php artisan migrate:rollback

• Carga de datos iniciales (seeders).

  php artisan db:seed

4. Gestión de dependencias

• Actualización de paquetes en Composer (PHP) y NPM/PNPM (JS).

  composer update
  npm update

• Validación de compatibilidad al actualizar dependencias.
• Uso de lock files (composer.lock, package-lock.json, pnpm-lock.yaml).

5. Despliegue (Deploy)

• Flujo de despliegue: dev → test → producción.
  • Una vez que se han realizado los cambios en las ramas development2y development, se debe fusionar con test y prod, probar en entorno de test todas las nuevas features y corregir posibles errores.

  git checkout test
  git pull origin test
  git checkout prod
  git pull origin prod
  git checkout development
  git pull origin development
  git checkout development2
  git pull origin development2
  git checkout test
  git merge prod
  git merge development2
  git merge development
  git push origin test

  (Nota: si hay conflictos, resolverlos y volver a ejecutar el merge)
  • Una vez que se han realizado los cambios en la rama test, se debe fusionar con prod y desplegar.

  git checkout prod
  git pull origin prod
  git checkout test
  git merge prod
  git push origin prod

  • Despliegue en producción.
    • Conectarse via ssh a la máquina de producción.

    ssh usuario@ip

    • Actualizar el repositorio.

    git pull origin prod

    • Compilar React y limpiar cachés en Laravel.

    node new_version.js 'YYYYMMDD'
    php artisan cache:clear
    php artisan view:clear
    php artisan config:clear

    (Nota: no se compila directamente con el comando run prod ya que se implementó una forma de eliminar todos los archivos de la carpeta public/js y evitar tener problemas de caché; El parametro que recibe es la fecha actual en formato YYYYMMDD, por ejemplo: node new_version.js '20250902')

6. Monitoreo y logs

• Revisión de logs en Laravel (storage/logs/).
  • Actualmente no se tiene una forma de monitorear los logs en tiempo real. Pero se está trabajando en eso
• Revisión de auditorías (laravel-audits).
  • Actualmente no se tiene una forma de monitorear las auditorías en tiempo real. Pero los registros de auditoría se guardan en la base de datos y se pueden consultar a través de sql
• Monitoreo de errores en frontend.
  • Actualmente no se tiene una forma de monitorear los errores en tiempo real. Pero se planea la implementación a futuro de un sistema de monitoreo de errores.

7. Gestión de roles y permisos

El sistema utiliza el paquete spatie/laravel-permission para manejar roles y permisos.

• Cómo crear un rol nuevo

  1. Abrir RoleTableSeeder.php.

  2. Agregar:

  Role::firstOrCreate(['role_name'=>'nombre-del-rol']);

  3. Ejecutar:

  php artisan db:seed --class=RoleTableSeeder

  4. Confirmar que el rol existe en la tabla roles.

• Cómo asignar permisos a un rol o usuario

  1. Abrir PermissionTableSeeder.php:

  Permission::firstOrCreate(['name' => 'nuevo-permiso']);

  2. Asignar permiso al rol:
  • Ejecutar tinker:

  php artisan tinker

  • Ejecutar:

  use Spatie\Permission\Models\Role;
  
  $role = Role::findByName('nombre-del-rol');
  $role->givePermissionTo('nuevo-permiso');

  3. Asignar rol al usuario:

  use App\Models\User;
  
  $user->assignRole('nombre-del-rol');

  4. También se puede asignar permisos directamente a usuarios:

  use App\Models\User;
  
  $user->givePermissionTo('nuevo-permiso');

• Validación de accesos en endpoints

  En controladores:

  public function index()
  {
      $this->authorize('nuevo-permiso');
      // ...
  }

  Con middlewares:

  Route::get('/reportes', 'ReportController@index')->middleware('permission:nuevo-permiso');

  En vistas (Blade):

  @can('nuevo-permiso')
    <a href="/reportes">Ver reportes</a>
  @endcan

8. Backups y restauración

• Procedimiento para generar un backup de la base de datos.
  • Se cuenta con un script automatizado que ejecuta backup de la base de datos diariamente y los almacena en una carpeta privada de google drive.
• Procedimiento para restaurar un backup.
  • Se descarga el backup desde google drive y se restaura en la base de datos utilizando las herramientas de restauración de dbeaver.
• Pruebas de restauración.

9. Seguridad

• Gestión de llaves y secretos

  • Todas las claves (DB, JWT, API externas, etc.) deben estar en .env.
  • Nunca subir .env a git.
  • Para producción, usar un gestor de secretos (ej. Vault, AWS Secrets Manager o equivalente).

• Rotación de contraseñas y tokens

  • Las contraseñas de servicios deben rotarse cada 90 días (recomendación estándar).
  • Los tokens de API deben tener expiración configurable y renovarse automáticamente cuando sea posible.

• Procedimiento en caso de incidente

  • Identificar y aislar el sistema afectado.
  • Revocar todas las llaves y tokens comprometidos.
  • Analizar logs para determinar alcance del incidente.
  • Informar al equipo y documentar acciones tomadas.
  • Aplicar parches o configuraciones necesarias antes de reactivar servicios.

10. Testing

Pruebas unitarias en Laravel

• Se ejecutan con:

  php artisan test

• Ubicación: tests/Unit/

• Buenas prácticas: probar lógica de negocio aislada (servicios, helpers, modelos).

Pruebas de integración

• Ubicación: tests/Feature/

• Verifican interacción entre controladores, rutas, DB y servicios.

• Ejemplo:

  public function test_usuario_puede_crear_inscripcion()
  {
      $user = User::factory()->create();
      $this->actingAs($user)
           ->post('/inscripciones', [...])
           ->assertStatus(201);
  }

Tests de frontend (React)

• Framework sugerido: Jest + React Testing Library.

• Ejemplo básico:

  import { render, screen } from '@testing-library/react';
  import Inscripciones from './Inscripciones';
  
  test('renderiza título de inscripciones', () => {
    render(<Inscripciones />);
    expect(screen.getByText(/Inscripciones/)).toBeInTheDocument();
  });

Reportes de cobertura

• Backend:

  php artisan test --coverage

• Frontend:

  npm run test -- --coverage

• Resultado debe integrarse en CI/CD para ver métricas de calidad.

11. Documentación

Nota: revisar Guia de estilo de escritura

12. Estándares de código

• Convenciones de nombres para archivos, variables, clases y funciones.
• Uso de linters (ESLint/Biome para JS, PHP_CodeSniffer para PHP).
• Uso de formatters (Prettier/Biome, PHP-CS-Fixer).

13. Reuniones y flujos internos

(Nota: El equipo no suele realizar reuniones)

14. Release management

Nota: actualmente no se tiene un sistema de releases, pero se planea implementar en el futuro. Se optará por CalVer (Calendar Versioning)

• Posible estrategia a implementar

• Formato sugerido: YYYY.MM.MINOR

  • YYYY → año (ej. 2025)
  • MM → mes (ej. 09)
  • MINOR → número incremental dentro del mismo mes (.0, .1, .2 …)
  • Ejemplo: 2025.09.0, 2025.09.1, 2025.10.0

• Ventajas

• Refleja fácilmente cuándo salió la versión → útil para equipos que siguen ciclos académicos/financieros.

• Evita discusiones sobre compatibilidad o nivel de cambio (SemVer).

• Facilita auditorías y trazabilidad: se puede ver de inmediato en qué mes/año se desplegó cierta release.

• Changelog

• Se recomienda usar Conventional Commits para que cada release pueda generar automáticamente un changelog.

• Herramientas posibles:

  • git-cliff
  • standard-version

• Releases en Git

• Cada release se etiqueta con el formato CalVer (git tag 2025.09.0).

• Publicar release en GitLab/GitHub con changelog y artefactos asociados (ej. dump de DB, binarios).

• Deploy por ambiente

1. Dev → pruebas iniciales de integración.
2. Test → validación con usuarios internos.
3. Prod → deploy definitivo.

Cada release debe pasar en orden y documentarse qué cambió en cada ambiente.

• Rollback plan

Nota: revisar Guia de rollback