planilla/README.md

# 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`.
    ```typescript
    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:
    ```javascript
    // 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.

```dotenv
# 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**
    ```bash
    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)
    ```bash
    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:
    ```bash
    npm run db:generate --workspace=@empresa/prisma-schema # o yarn workspace @empresa/prisma-schema db:generate
    ```
    O directamente desde el paquete:
    ```bash
    cd core/prisma
    npm run db:generate
    cd ../..
    ```
4.  **Construir y levantar contenedores Docker**
    ```bash
    docker compose up -d --build
    ```
5.  **Ver logs**
    ```bash
    docker compose logs -f api ui worker # Agrega otros servicios según sea necesario
    ```
6.  **Detener todo**
    ```bash
    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:
    ```bash
    npm run prisma:migrate:dev --workspace=@empresa/prisma-schema -- --name tu-nombre-de-migracion
    ```
    O directamente desde el paquete `core/prisma`:
    ```bash
    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:
    ```bash
    npm run prisma:deploy --workspace=@empresa/prisma-schema
    ```
    O desde `core/prisma`:
    ```bash
    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