Planilla

ESTE REPOSITORIO ES UNA COPIA DEL DE GITEA. EL PRINCIPAL ES EL DE GITEA Sistema de gestión de planillas compuesto por:

• Base de datos: PostgreSQL
• API: Express + Node.js (módulo api)
• Interfaz de usuario: Vue 3 + Vite (módulo ui)
• Orquestación: Docker Compose
• Proxy y SSL: nginx-proxy-manager (red principal)

---

📂 Estructura del proyecto

El proyecto ahora está organizado como un monorepo utilizando workspaces (npm/yarn/pnpm).

planilla/
├─ .gitea/workflows/build.yml    # CI/CD: build + push + deploy
├─ agent/                        # Servicio Agent (Node.js)
│   ├─ Dockerfile
│   └─ package.json
├─ api/                          # Servicio API (Node.js + Express)
│   ├─ Dockerfile
│   ├─ jsconfig.json
│   ├─ package.json
│   └─ server.js
├─ core/
│   └─ prisma/                   # Paquete compartido para el schema y cliente Prisma
│       ├─ package.json
│       ├─ tsconfig.json
│       ├─ schema.prisma
│       ├─ index.ts              # Exporta tipos de Prisma
│       └─ client.ts             # Exporta PrismaClient
├─ mcp/                          # Servicio MCP (Node.js)
│   ├─ Dockerfile
│   └─ package.json
├─ ui/                           # Frontend Vue 3 + Vite
│   ├─ Dockerfile
│   ├─ tsconfig.json
│   ├─ package.json
│   ├─ index.html
│   ├─ src/
│   └─ vite.config.js
├─ worker/                       # Servicio Worker (Node.js)
│   ├─ Dockerfile
│   ├─ jsconfig.json
│   └─ package.json
├─ package.json                  # package.json raíz para workspaces
├─ tsconfig.base.json            # Configuración base de TypeScript para todo el monorepo
├─ docker-compose.yml            # Orquestación de todos los servicios
└─ README.md                     # Este documento

---

Workspaces and Shared Packages

Este monorepo utiliza workspaces para gestionar múltiples paquetes/servicios. La configuración de workspaces se encuentra en el package.json raíz.

@empresa/prisma-schema (core/prisma)

Este es un paquete compartido que centraliza la definición del schema de Prisma y la configuración del cliente.

• Schema: core/prisma/schema.prisma
• Generación del Cliente: El cliente Prisma se genera dentro de este paquete.
• Consumo de Tipos: Otros servicios (UI, workers, etc.) deben importar los tipos generados por Prisma desde @empresa/prisma-schema.

  import type { Employee, OtherModel } from '@empresa/prisma-schema';
  

• Consumo del Cliente Prisma (PrismaClient): La instancia de PrismaClient solo debe ser utilizada por el servicio api. Se importa de la siguiente manera:

  // En api/server.js o similar
  import { PrismaClient } from '@empresa/prisma-schema/client';
  const prisma = new PrismaClient();
  

  Otros servicios no deben importar ni instanciar PrismaClient directamente. Deben interactuar con la base de datos a través de la API.

TypeScript Configuration

• Un tsconfig.base.json en la raíz define configuraciones comunes de TypeScript, incluyendo alias de path para @empresa/prisma-schema.
• Cada servicio/paquete que utiliza TypeScript tiene su propio tsconfig.json (o jsconfig.json para proyectos JavaScript) que extiende la configuración base.
• El paquete core/prisma compila su salida (cliente Prisma y tipos) a su directorio dist/.

---

📝 Requisitos

• Docker (v20+)
• Docker Compose (v2+)
• Node.js (v18+) y npm (o yarn/pnpm) para desarrollo local y gestión de workspaces.
• Acceso a red app-net y principal en Docker

---

⚙️ Variables de entorno

Las variables de entorno relevantes para cada servicio se pueden encontrar en sus respectivos Dockerfiles o en docker-compose.yml. La variable DATABASE_URL para la conexión a PostgreSQL es utilizada por el paquete core/prisma (y por ende, por la api que lo consume) y debe estar configurada para que la api funcione correctamente.

# Ejemplo de variables en .env o docker-compose.yml
COMPOSE_PROJECT_NAME=planilla
POSTGRES_USER=usuario
POSTGRES_PASSWORD=clave
POSTGRES_DB=midb
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?schema=public"

---

🚀 Levantando los servicios

1. Clonar repo

   git clone [https://gitea.interno.com/nucleo000/planilla.git](https://gitea.interno.com/nucleo000/planilla.git)
   cd planilla
   

2. Instalar dependencias de workspaces (desde la raíz del monorepo)

   npm install # o yarn install / pnpm install
   

3. Generar cliente Prisma (necesario después de instalar o si cambias el schema) Desde la raíz del monorepo:

   npm run db:generate --workspace=@empresa/prisma-schema # o yarn workspace @empresa/prisma-schema db:generate
   

   O directamente desde el paquete:

   cd core/prisma
   npm run db:generate
   cd ../..
   

4. Construir y levantar contenedores Docker

   docker compose up -d --build
   

5. Ver logs

   docker compose logs -f api ui worker # Agrega otros servicios según sea necesario
   

6. Detener todo

   docker compose down --remove-orphans
   

---

📡 Acceso a la aplicación

• La UI (ui service) no expone puertos en el host. En Nginx Proxy Manager (red principal):

  • Domino: planilla.midominio.com (o el que configures)
  • Scheme: http
  • Forward Hostname: planilla-ui (o el nombre de contenedor que uses en docker-compose.yml)
  • Forward Port: 80 (o el puerto que exponga el contenedor de la UI, si es diferente) Posteriormente, puedes habilitar SSL Let’s Encrypt desde la pestaña SSL en Nginx Proxy Manager.

• La API (api service) corre internamente, por defecto en el puerto 4000, y no se expone directamente al exterior. La UI u otros servicios internos pueden accederla por su nombre de servicio y puerto (e.g., http://api:4000).

---

🗄️ Detalles de cada servicio

Base de datos (db)

• Imagen: postgres:15
• Volumen persistente: db_data
• Credenciales y configuración en docker-compose.yml y/o archivo .env.
• El schema es gestionado por Prisma en core/prisma/schema.prisma. Las migraciones se aplican a través de los comandos de Prisma CLI.

API (api)

• Framework: Express
• Utiliza el cliente Prisma desde @empresa/prisma-schema/client para interactuar con la base de datos.
• Las definiciones de tipos (ej. para cuerpos de request/response) pueden ser importadas desde @empresa/prisma-schema.
• Arranca en el puerto 4000 internamente (configurable).
• Código principal en api/server.js.

UI (ui)

• Framework: Vue 3 + Vite
• Importa tipos de datos (ej. Employee) desde @empresa/prisma-schema para type-safety en el frontend.
• Consume datos de la API (api service).
• Arranca en el puerto 80 internamente (configurable a través de vite.config.js y Dockerfile).
• Código fuente en ui/src/.

Worker (worker)

• Servicio Node.js para tareas en segundo plano o programadas.
• Puede importar tipos desde @empresa/prisma-schema.
• Debe interactuar con la base de datos a través de la API, no directamente.

Agent (agent) y MCP (mcp)

• Otros servicios Node.js.
• Pueden importar tipos desde @empresa/prisma-schema si necesitan interactuar con estructuras de datos alineadas con la base de datos.
• Deben interactuar con la base de datos a través de la API.

---

Prisma Migrations

Las migraciones de la base de datos se gestionan con Prisma CLI desde el paquete core/prisma.

1. Modificar el schema: Edita core/prisma/schema.prisma.
2. Crear una nueva migración: Desde la raíz del monorepo:

   npm run prisma:migrate:dev --workspace=@empresa/prisma-schema -- --name tu-nombre-de-migracion
   

   O directamente desde el paquete core/prisma:

   cd core/prisma
   npx prisma migrate dev --name tu-nombre-de-migracion
   cd ../..
   

   Esto generará los archivos SQL de migración en core/prisma/migrations/.
3. Aplicar migraciones (generalmente manejado por el entrypoint.sh de la API o un script de despliegue): Desde la raíz:

   npm run prisma:deploy --workspace=@empresa/prisma-schema
   

   O desde core/prisma:

   npx prisma migrate deploy
   

4. Generar cliente Prisma (después de cambios en el schema o migraciones): Esto se hace con el comando db:generate ya mencionado en la sección de levantamiento.

---

📦 CI/CD (.gitea/workflows/build.yml)

1. build: construye imágenes planilla, planilla-api, planilla-ui, taggea con SHA y latest.
2. push: envía imágenes al registry gitea.interno.com.
3. deploy: conecta al registry, baja imágenes y hace docker compose up -d --build.

Asegurate de usar las credenciales correctas en el workflow.

---

💡 Buenas prácticas

• Aísla tu red interna (app-net) para que sólo los contenedores hablen entre sí.
• Exponé servicios al exterior sólo vía nginx-proxy-manager en la red principal.
• Versioná tu build.yml y mantén secretos fuera del repo (ideal: secrets.GITEA_PASSWORD).
• Usa nombres de contenedor explícitos (container_name) para identificar fácilmente.

---

🤝 Contribuciones

1. Hacé un fork y trabajá en una rama nueva.
2. Abrí PR describiendo cambios.
3. Chequeá que el CI pase y la app funcione.

---

📄 Licencia

MIT © 2025 Equipo Planilla