erp-core/docs/01-analisis-referencias/gamilit/devops-automation.md

670 lines
17 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Scripts DevOps y Automatizacion - GAMILIT
**Documento:** Analisis de DevOps y Automatizacion
**Proyecto de Referencia:** GAMILIT
**Fecha:** 2025-11-23
**Analista:** Architecture-Analyst Agent
---
## 1. VISION GENERAL
GAMILIT implementa **scripts TypeScript de validacion y automatizacion** pero **carece de DevOps completo** (Docker, CI/CD, Kubernetes).
**Estado actual:**
-**Scripts de validacion:** 3 scripts TypeScript funcionales
-**Docker:** NO implementado
-**CI/CD:** NO implementado
-**Kubernetes:** NO implementado
-**Deployment scripts:** NO implementado
**Critica:** DevOps incompleto es un **GAP CRITICO**. NO copiar este anti-patron.
---
## 2. SCRIPTS DE VALIDACION IMPLEMENTADOS
### 2.1 Resumen de Scripts
| Script | LOC | Proposito | Estado | Aplicabilidad ERP |
|--------|-----|-----------|--------|-------------------|
| **sync-enums.ts** | 70 | Sincronizar ENUMs Backend → Frontend | ✅ Funcional | ⭐⭐⭐⭐⭐ MAXIMA |
| **validate-constants-usage.ts** | 642 | Detectar hardcoding (33 patrones) | ✅ Funcional | ⭐⭐⭐⭐⭐ MAXIMA |
| **validate-api-contract.ts** | ~150 | Validar Backend ↔ Frontend sync | ✅ Funcional | ⭐⭐⭐⭐ ALTA |
**Total:** ~860 lineas de codigo de validacion
### 2.2 Integracion en package.json
```json
{
"scripts": {
// ========== SINCRONIZACION ==========
"sync:enums": "ts-node devops/scripts/sync-enums.ts",
"postinstall": "npm run sync:enums",
// ========== VALIDACIONES ==========
"validate:constants": "ts-node devops/scripts/validate-constants-usage.ts",
"validate:api-contract": "ts-node devops/scripts/validate-api-contract.ts",
"validate:all": "npm run validate:constants && npm run validate:api-contract",
// ========== TESTING ==========
"test": "jest",
"test:cov": "jest --coverage",
"test:watch": "jest --watch",
// ========== LINTING ==========
"lint": "eslint . --ext .ts,.tsx",
"lint:fix": "eslint . --ext .ts,.tsx --fix",
"format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
// ========== BUILD ==========
"build": "npm run build:backend && npm run build:frontend",
"build:backend": "cd apps/backend && npm run build",
"build:frontend": "cd apps/frontend && npm run build",
// ========== START ==========
"dev": "concurrently \"npm run backend:dev\" \"npm run frontend:dev\"",
"backend:dev": "cd apps/backend && npm run dev",
"frontend:dev": "cd apps/frontend && npm run dev"
}
}
```
---
## 3. SCRIPT 1: sync-enums.ts
**Ya documentado en:** `ssot-system.md`
**Resumen:**
- ✅ Copia automatica Backend → Frontend
- ✅ Postinstall hook (automatico en npm install)
- ✅ Validacion de existencia de archivos
- ✅ Modificacion de headers JSDoc
- ✅ Error handling robusto
**Uso:**
```bash
npm run sync:enums
# o automatico en:
npm install
```
---
## 4. SCRIPT 2: validate-constants-usage.ts
**Ya documentado en:** `ssot-system.md`
**Resumen:**
- ✅ 33 patrones de deteccion de hardcoding
- ✅ Severidades: P0 (critico), P1 (importante), P2 (menor)
- ✅ Exclusiones configurables
- ✅ Reportes detallados con sugerencias
- ✅ Exit codes para CI/CD
- ✅ Escaneo de 1,500+ archivos
**Uso:**
```bash
npm run validate:constants
# Salida:
🔍 Validando uso de constantes (detectando hardcoding SSOT)...
📂 Escaneando 1,523 archivos...
❌ VIOLACIONES P0 (CRITICAS) - BLOQUEAN CI/CD: 3
1. 📄 backend/src/modules/auth/services/user.service.ts
🚨 Hardcoded schema "auth_management"
💡 Usa DB_SCHEMAS.AUTH en su lugar
📍 Lineas: 15, 23, 45
🔢 Total de ocurrencias: 3
⚠️ VIOLACIONES P1 (IMPORTANTES) - REVISAR: 5
VIOLACIONES P2 (MENORES) - INFORMATIVO: 12
❌ FALLO: Existen violaciones P0 que bloquean el CI/CD.
Exit code: 1
```
---
## 5. SCRIPT 3: validate-api-contract.ts (~150 lineas)
**Proposito:** Validar que endpoints de Backend coinciden con Frontend
**Logica:**
1. Leer `API_ROUTES` de Backend
2. Leer `API_ENDPOINTS` de Frontend
3. Comparar que todos los endpoints Frontend existen en Backend
4. Reportar discrepancias
**Pseudocodigo:**
```typescript
import { API_ROUTES as BACKEND_ROUTES } from '@backend/shared/constants';
import { API_ENDPOINTS as FRONTEND_ENDPOINTS } from '@frontend/shared/constants';
function validateApiContract() {
const backendEndpoints = extractAllEndpoints(BACKEND_ROUTES);
const frontendEndpoints = extractAllEndpoints(FRONTEND_ENDPOINTS);
const missing = frontendEndpoints.filter(
(endpoint) => !backendEndpoints.includes(endpoint)
);
if (missing.length > 0) {
console.error('❌ Endpoints en Frontend pero NO en Backend:');
missing.forEach((endpoint) => console.error(` - ${endpoint}`));
process.exit(1);
}
console.log('✅ Todos los endpoints Frontend existen en Backend');
}
validateApiContract();
```
**Uso:**
```bash
npm run validate:api-contract
# Salida:
✅ Todos los endpoints Frontend existen en Backend
✅ Contrato API validado correctamente
```
---
## 6. GAPS CRITICOS EN DEVOPS
### 6.1 Docker: NO IMPLEMENTADO ❌
**Faltante:**
- `Dockerfile` para Backend
- `Dockerfile` para Frontend
- `docker-compose.yml` para desarrollo local
- Imagenes multi-stage (optimizacion)
- Health checks
**Impacto:**
- Ambiente de desarrollo inconsistente
- Deployment manual propenso a errores
- No portable entre desarrolladores
- Dificil escalar
**Recomendacion para ERP:**
⭐⭐⭐⭐⭐ (MAXIMA)
**Decision:****IMPLEMENTAR DESDE EL INICIO**
**Ejemplo de estructura:**
```
docker/
├── backend/
│ ├── Dockerfile
│ └── .dockerignore
├── frontend/
│ ├── Dockerfile
│ └── .dockerignore
├── database/
│ └── Dockerfile (PostgreSQL custom)
├── docker-compose.yml # Desarrollo local
├── docker-compose.prod.yml # Produccion
└── .env.example # Variables de entorno
```
**docker-compose.yml ejemplo:**
```yaml
version: '3.8'
services:
database:
image: postgres:16-alpine
environment:
POSTGRES_DB: erp_generic
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/data
backend:
build:
context: ./backend
dockerfile: Dockerfile
environment:
DATABASE_URL: postgres://postgres:postgres@database:5432/erp_generic
NODE_ENV: development
ports:
- '3000:3000'
depends_on:
- database
volumes:
- ./backend:/app
- /app/node_modules
frontend:
build:
context: ./frontend
dockerfile: Dockerfile
environment:
VITE_API_URL: http://localhost:3000/api/v1
ports:
- '5173:5173'
depends_on:
- backend
volumes:
- ./frontend:/app
- /app/node_modules
volumes:
postgres_data:
```
### 6.2 CI/CD: NO IMPLEMENTADO ❌
**Faltante:**
- GitHub Actions workflows
- GitLab CI pipelines
- Automated testing en PR
- Automated deployment
- Environment management (dev, staging, prod)
- Rollback mechanisms
**Impacto:**
- Deployment manual lento
- Riesgo de errores humanos
- No hay validacion automatica
- Dificil hacer releases
**Recomendacion para ERP:**
⭐⭐⭐⭐⭐ (MAXIMA)
**Decision:****IMPLEMENTAR DESDE EL INICIO**
**Ejemplo GitHub Actions:**
```yaml
# .github/workflows/ci.yml
name: CI/CD Pipeline
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
jobs:
# ========== VALIDACIONES ==========
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Sync ENUMs
run: npm run sync:enums
- name: Validate constants
run: npm run validate:constants
- name: Validate API contract
run: npm run validate:api-contract
# ========== TESTS ==========
test:
runs-on: ubuntu-latest
needs: validate
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm run test:cov
- name: Upload coverage
uses: codecov/codecov-action@v3
# ========== BUILD ==========
build:
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v3
- name: Build Backend
run: |
cd backend
npm ci
npm run build
- name: Build Frontend
run: |
cd frontend
npm ci
npm run build
# ========== DEPLOY (solo en main) ==========
deploy:
runs-on: ubuntu-latest
needs: build
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v3
- name: Deploy to Production
run: |
# Deployment script
./deploy.sh production
```
### 6.3 Kubernetes: NO IMPLEMENTADO ❌
**Faltante:**
- Manifests de Kubernetes (Deployments, Services, Ingress)
- ConfigMaps y Secrets
- Helm charts
- Horizontal Pod Autoscaling
- Resource limits y requests
**Impacto:**
- No escalabilidad automatica
- Deployment manual
- Dificil alta disponibilidad
**Recomendacion para ERP:**
⭐⭐⭐⭐ (ALTA - P1)
**Decision:** 🔧 **IMPLEMENTAR EN FASE 2**
**Nota:** Kubernetes es importante pero no critico para MVP. Implementar despues de tener Docker y CI/CD.
### 6.4 Deployment Scripts: NO IMPLEMENTADOS ❌
**Faltante:**
- Scripts de deployment automatico
- Scripts de rollback
- Scripts de backup de base de datos
- Scripts de migracion de datos
- Scripts de health checks
**Recomendacion para ERP:**
⭐⭐⭐⭐⭐ (MAXIMA)
**Decision:****IMPLEMENTAR DESDE EL INICIO**
**Ejemplo de estructura:**
```
scripts/
├── deploy/
│ ├── deploy.sh # Deploy principal
│ ├── deploy-backend.sh # Deploy backend
│ ├── deploy-frontend.sh # Deploy frontend
│ └── rollback.sh # Rollback
├── database/
│ ├── backup.sh # Backup de DB
│ ├── restore.sh # Restore de DB
│ ├── migrate.sh # Migraciones
│ └── seed.sh # Seed de datos
└── health/
├── health-check.sh # Health checks
└── smoke-test.sh # Smoke tests
```
---
## 7. MATRIX DE DECISION: ADOPTAR / IMPLEMENTAR
### 7.1 ADOPTAR DE GAMILIT ✅
| Script/Tool | Descripcion | Aplicabilidad | Prioridad |
|-------------|-------------|---------------|-----------|
| **sync-enums.ts** | Sincronizar ENUMs Backend → Frontend | ⭐⭐⭐⭐⭐ MAXIMA | P0 |
| **validate-constants-usage.ts** | Detectar hardcoding (33 patrones) | ⭐⭐⭐⭐⭐ MAXIMA | P0 |
| **validate-api-contract.ts** | Validar Backend ↔ Frontend sync | ⭐⭐⭐⭐ ALTA | P1 |
| **Scripts NPM** | Automatizacion de tareas | ⭐⭐⭐⭐⭐ MAXIMA | P0 |
| **ESLint + Prettier** | Linting y formatting | ⭐⭐⭐⭐⭐ MAXIMA | P0 |
### 7.2 IMPLEMENTAR (NO EXISTE EN GAMILIT) ✅
| Componente | Descripcion | Urgencia | Prioridad |
|------------|-------------|----------|-----------|
| **Docker** | Containerizacion completa | CRITICO | P0 |
| **CI/CD** | GitHub Actions / GitLab CI | CRITICO | P0 |
| **Deployment Scripts** | Scripts de deploy, rollback, backup | CRITICO | P0 |
| **Pre-commit Hooks** | Validacion antes de commit | ALTA | P1 |
| **Monitoring** | Logs, metricas, alertas | ALTA | P1 |
| **Kubernetes** | Orquestacion de contenedores | MEDIA | P2 |
### 7.3 EVITAR ❌
| Anti-patron | Razon | Alternativa |
|-------------|-------|-------------|
| **Sin Docker** | Ambientes inconsistentes | Docker + docker-compose |
| **Sin CI/CD** | Deployment manual propenso a errores | GitHub Actions / GitLab CI |
| **Sin tests automatizados** | Bugs en produccion | Jest + Vitest + CI/CD |
| **Deployment manual** | Lento y riesgoso | Scripts automatizados |
---
## 8. PROPUESTA DE DEVOPS COMPLETO PARA ERP
### 8.1 Estructura Propuesta
```
projects/erp-generic/
├── .github/
│ └── workflows/
│ ├── ci.yml # CI/CD principal
│ ├── validate.yml # Validaciones
│ └── deploy.yml # Deployment
├── docker/
│ ├── backend/
│ │ ├── Dockerfile
│ │ ├── Dockerfile.dev
│ │ └── .dockerignore
│ ├── frontend/
│ │ ├── Dockerfile
│ │ ├── Dockerfile.dev
│ │ └── .dockerignore
│ ├── database/
│ │ └── Dockerfile
│ ├── docker-compose.yml # Desarrollo local
│ ├── docker-compose.prod.yml # Produccion
│ └── .env.example
├── scripts/
│ ├── devops/
│ │ ├── sync-enums.ts # De GAMILIT ✅
│ │ ├── validate-constants-usage.ts # De GAMILIT ✅
│ │ └── validate-api-contract.ts # De GAMILIT ✅
│ ├── deploy/
│ │ ├── deploy.sh
│ │ ├── rollback.sh
│ │ └── smoke-test.sh
│ ├── database/
│ │ ├── backup.sh
│ │ ├── restore.sh
│ │ └── migrate.sh
│ └── health/
│ └── health-check.sh
├── k8s/ # Kubernetes (P2)
│ ├── deployments/
│ ├── services/
│ ├── ingress/
│ └── configmaps/
└── .husky/ # Pre-commit hooks
├── pre-commit
└── pre-push
```
### 8.2 Scripts NPM Propuestos
```json
{
"scripts": {
// ========== VALIDACIONES ==========
"sync:enums": "ts-node scripts/devops/sync-enums.ts",
"validate:constants": "ts-node scripts/devops/validate-constants-usage.ts",
"validate:api-contract": "ts-node scripts/devops/validate-api-contract.ts",
"validate:all": "npm run validate:constants && npm run validate:api-contract",
// ========== TESTING ==========
"test": "jest",
"test:cov": "jest --coverage",
"test:watch": "jest --watch",
"test:e2e": "playwright test",
// ========== LINTING ==========
"lint": "eslint . --ext .ts,.tsx",
"lint:fix": "eslint . --ext .ts,.tsx --fix",
"format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
"format:check": "prettier --check \"**/*.{ts,tsx,json,md}\"",
// ========== BUILD ==========
"build": "npm run build:backend && npm run build:frontend",
"build:backend": "cd backend && npm run build",
"build:frontend": "cd frontend && npm run build",
// ========== DOCKER ==========
"docker:up": "docker-compose up -d",
"docker:down": "docker-compose down",
"docker:logs": "docker-compose logs -f",
"docker:build": "docker-compose build",
// ========== DATABASE ==========
"db:migrate": "bash scripts/database/migrate.sh",
"db:seed": "bash scripts/database/seed.sh",
"db:backup": "bash scripts/database/backup.sh",
"db:restore": "bash scripts/database/restore.sh",
// ========== DEPLOYMENT ==========
"deploy:dev": "bash scripts/deploy/deploy.sh dev",
"deploy:staging": "bash scripts/deploy/deploy.sh staging",
"deploy:prod": "bash scripts/deploy/deploy.sh prod",
"rollback": "bash scripts/deploy/rollback.sh",
// ========== HEALTH ==========
"health:check": "bash scripts/health/health-check.sh",
"smoke:test": "bash scripts/health/smoke-test.sh",
// ========== HOOKS ==========
"prepare": "husky install",
"postinstall": "npm run sync:enums"
}
}
```
### 8.3 Pre-commit Hooks (Husky)
**.husky/pre-commit:**
```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
# Validaciones antes de commit
npm run lint
npm run format:check
npm run validate:constants
npm run test
```
**.husky/pre-push:**
```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
# Validaciones antes de push
npm run validate:all
npm run test:cov
npm run build
```
---
## 9. CONCLUSION Y RECOMENDACIONES
### 9.1 Hallazgos Clave
1. **Scripts de validacion son EXCELENTES:** ⭐⭐⭐⭐⭐
- `sync-enums.ts` (70 lineas)
- `validate-constants-usage.ts` (642 lineas, 33 patrones)
- `validate-api-contract.ts` (~150 lineas)
2. **DevOps completo es GAP CRITICO:** ❌❌❌
- NO hay Docker
- NO hay CI/CD
- NO hay Kubernetes
- NO hay scripts de deployment
3. **Impacto en produccion:**
- Ambientes inconsistentes
- Deployment manual propenso a errores
- Dificil escalar
- NO copiar este anti-patron
### 9.2 Recomendaciones Finales
#### ADOPTAR DE GAMILIT ✅ (Prioridad P0)
1. Script `sync-enums.ts`
2. Script `validate-constants-usage.ts` (adaptar patrones a ERP)
3. Script `validate-api-contract.ts`
4. NPM scripts de validacion
5. ESLint + Prettier config
#### IMPLEMENTAR (NO EXISTE EN GAMILIT) ✅
**Prioridad P0 (CRITICO - Implementar ANTES del MVP):**
1. Docker + docker-compose
2. CI/CD (GitHub Actions o GitLab CI)
3. Scripts de deployment (deploy, rollback, backup)
4. Pre-commit hooks (Husky)
5. Health checks
**Prioridad P1 (ALTA - Implementar en Fase 1):**
6. Monitoring y logging (Prometheus + Grafana o similar)
7. E2E tests automatizados (Playwright o Cypress)
8. Smoke tests post-deployment
**Prioridad P2 (MEDIA - Implementar en Fase 2):**
9. Kubernetes manifests
10. Helm charts
11. Horizontal Pod Autoscaling
#### EVITAR ❌
1. Deployment manual
2. Ambientes sin Docker
3. Sin CI/CD
4. Sin validacion automatica
---
**Documento creado:** 2025-11-23
**Version:** 1.0
**Estado:** Completado
**Criticidad:** ⭐⭐⭐⭐⭐ MAXIMA (DevOps es critico para produccion)
**Proximo documento:** `ADOPTAR-ADAPTAR-EVITAR.md`