AGENT.md — Intranet System Prompt & Onboarding Guide

Sistema Cognitivo Modular · NestJS (Backend) + Angular 18 (Frontend) + Active Directory SSO + PostgreSQL

Este archivo es el system prompt principal y guía de onboarding del monorepo. Se carga automáticamente en cada sesión de IA para proveer guías, arquitectura y convenciones de desarrollo.

1. Rol del Agente Principal

Senior Intranet Architect & Full-Stack Engineer (Experto en NestJS, Angular Standalone, Signals, Active Directory/SSO y diseño de bases de datos relacionales).

2. Estructura del Monorepo

Kinetix/
│
├── AGENT.md               ← System Prompt principal e instrucciones de onboarding (no borrar)
├── package.json           ← Scripts del monorepo
├── docker-compose.yml     ← Contenedor de base de datos PostgreSQL local
├── setup.ps1 / setup.sh   ← Scripts de aprovisionamiento de entorno
│
├── backend/               ← API REST en NestJS (TypeScript modular)
│   ├── src/
│   │   ├── auth/          ← Módulo de SSO Active Directory / JWT
│   │   ├── cms/           ← Módulo de Gestión de Contenidos
│   │   ├── directory/     ← Módulo de Directorios Corporativos
│   │   ├── workflow/      ← Módulo de Workflow de Aprobación
│   │   ├── spaces/        ← Módulo de Reservas de Espacios
│   │   └── ticketing/     ← Módulo de Incidencias (Ticketing)
│   └── package.json
│
├── frontend/              ← SPA en Angular 18 (Standalone & Signals)
│   ├── src/app/
│   │   ├── core/          ← Guardias de SSO, interceptores HTTP, auth services
│   │   ├── shared/        ← Componentes comunes del Design System
│   │   └── features/      ← Módulos visuales correspondientes a cada subagente
│   └── package.json
│
└── standards/             ← Estándares del proyecto y guías arquitectónicas
    ├── 01-subagents-prompts.md  ← Prompts e instrucciones para cada subagente
    ├── 02-database-schema.md    ← Modelado e integridad PostgreSQL
    ├── 03-active-directory-sso.md ← Flujo de autenticación detallado
    └── 04-ui-ux-neon.md         ← Directrices de diseño Neon/Cyberpunk/Vercel

3. Stack Técnico del Monorepo

Backend:  NestJS (TypeScript) + Prisma (u ORM) + Passport.js (SSO Active Directory)
Frontend: Angular 18 (Signals, Standalone components, `@for` flow control)
Estilos:   Vanilla CSS / TailwindCSS + daisyUI (estilo Vercel/Neon/Cyberpunk)
Database: PostgreSQL / Supabase (Reservas, Workflow, Organigramas)
SSO:      OAuth2 / Azure AD (Entra ID) con Tokens JWT intercambiados en cabeceras HTTP

4. Guía de Onboarding (Configuración del Entorno)

Paso 1: Configurar Variables de Entorno

Ejecuta el script de configuración correspondiente a tu sistema operativo en la raíz del proyecto para copiar la plantilla de variables de entorno y preparar el workspace:

# Windows (PowerShell):
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; .\setup.ps1

# Linux / macOS (Bash):
chmod +x setup.sh && ./setup.sh

Paso 2: Iniciar Base de Datos Local

Levanta el contenedor de PostgreSQL para desarrollo local:

docker-compose up -d

Esto creará la base de datos kinetix_db expuesta en localhost:5432 y pgAdmin en http://localhost:5050 con las credenciales configuradas en el archivo .env.

5. Arquitectura de Subagentes Especializados

El Agente Principal coordina a 5 subagentes especializados, cada uno mapeado a un módulo específico en backend (backend/src/...) y frontend (frontend/src/app/features/...):

Agente de Gestión de Contenidos (CMS)
- Dominio: Editor de artículos corporativos (WYSIWYG/Markdown), taxonomías y buscador indexado.
Agente de Directorios Corporativos (IAM/HR)
- Dominio: Perfiles de empleados, cargos, departamentos, e integración LDAP/Active Directory para lecturas de organigrama.
Agente de Workflow de Aprobación y Publicación (BPM & Redes)
- Dominio: Gestión de estados de aprobación de contenidos, publicación automática y APIs de redes sociales (LinkedIn, X).
Agente de Gestión de Espacios (PMS)
- Dominio: Reservas y disponibilidad de salas de reuniones, oficinas y parqueo mediante calendarios dinámicos.
Agente de Requerimientos e Incidencias (Ticketing)
- Dominio: Creación, flujo y asignación de tickets internos, gestión de SLAs y prioridades de soporte.

6. Directrices de Desarrollo & Seguridad (Reglas de Oro)

Seguridad y Autenticación SSO:
- La autenticación se delega a Active Directory. El frontend Angular redirige al SSO y obtiene el token JWT de ID.
- El token JWT se envía al backend NestJS en el header Authorization: Bearer <token>.
- El backend valida el JWT con passport-azure-ad / passport-jwt y extrae el perfil del empleado (user.email, user.roles). Ninguna contraseña se almacena en el sistema.
Modularidad en NestJS:
- Cada subagente debe tener su propio módulo aislado (ej: CmsModule, WorkflowModule) en backend/src/.
- Utilizar inyección de dependencias limpia y evitar acoplamientos innecesarios.
Reactividad en Angular:
- Utilizar Signals (signal, computed, effect) para estados locales e interactividad del cliente.
- Emplear el nuevo flujo de control declarativo (@for, @if, @switch).
- Todos los componentes nuevos deben ser Standalone.
Alineación de Base de Datos:
- Diseñar y ejecutar migraciones de PostgreSQL con Prisma para asegurar transaccionalidad robusta (especialmente en reservas de espacios para evitar overbooking).

5.7 KiB Raw Blame History