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

Clonar repo

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

Instalar dependencias de workspaces (desde la raíz del monorepo)
```
npm install # o yarn install / pnpm install
```

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 ../..

Construir y levantar contenedores Docker
```
docker compose up -d --build
```

Ver logs

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

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.

Modificar el schema: Edita core/prisma/schema.prisma.

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/.

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
```
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`)

build: construye imágenes planilla, planilla-api, planilla-ui, taggea con SHA y latest.
push: envía imágenes al registry gitea.interno.com.
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

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

📄 Licencia

Languages

Vue 46.5%

JavaScript 45.2%

TypeScript 5.5%

CSS 0.8%

PLpgSQL 0.5%

Other 1.4%

README.md Unescape Escape

Planilla

📂 Estructura del proyecto

Workspaces and Shared Packages

@empresa/prisma-schema (core/prisma)