project.linkedcorp.net/AGENTS.md

# AGENTS.md - project.linkedcorp.net

> **⚠️ ANTES DE ACTUAR, lee el orquestador del grupo:** `/home/mgonzalez/desarrollo/project-md-templates/leeme_primero.txt`
> Reglas globales (infra, secretos, UI/UX, Android, Git, versionado). Este archivo es solo el contexto especifico del proyecto.

## ⛔ AISLAMIENTO: SOLO ESTE PROYECTO

Regla dura del grupo (detalle en el orquestador, seccion "REGLA DE AISLAMIENTO ENTRE PROYECTOS"):

- Se trabaja SOLO sobre este proyecto. Los otros proyectos del grupo NO se tocan NI se leen.
- Leer otro proyecto: unicamente si el usuario lo pide TEXTUALMENTE en ese pedido.
- Modificar otro proyecto: NUNCA, ni aunque el usuario lo nombre.
- Recursos compartidos (puertos, NPM, systemd, BD, DNS): verificar en la fuente real que esten
  libres antes de ocuparlos; solo crear objetos nuevos de ESTE proyecto.

## Proposito

Contexto especifico del proyecto para el asistente de IA. No repite las reglas globales del grupo,
que estan en el orquestador `leeme_primero.txt`.

## Identidad del proyecto

- Nombre: `project.linkedcorp.net`
- Tipo: fullstack (gestión y seguimiento de proyectos/actividades TI)
- Estado: development
- Ruta raiz: `/home/mgonzalez/desarrollo/project.linkedcorp.net`

## Stack real del proyecto

### Frontend
- React + Vite
- UI: CSS propio por tokens (sin Tailwind) siguiendo la identidad `docs/UI-UX-WINDOWS.md` (Fluent/Windows 11)
- Iconos: `lucide-react`

### Backend
- Node.js + Express
- API base: `/api`

### Base de datos
- Motor: MariaDB
- Base principal: `project_linkedcorp`
- Host dev: `192.168.222.20` / Host prod: `192.168.222.32` (NO mezclar)
- La base ya existe: sí (creada en dev el 2026-09-03 con `crear-db-dev.sh`)

## Arquetipo de despliegue

**B — Dos servicios separados** (frontend y backend como procesos independientes).
- systemd: `project-linkedcorp-frontend` y `project-linkedcorp-backend` (a crear en el primer deploy).
- NPM: Proxy Host al frontend + Custom Location `/api` al backend.
- Puertos (registrados en `PORTS_INVENTORY.md` del grupo): frontend `5196`, backend `4019`.

## Identidad UI/UX — DECISIÓN DE ESTE PROYECTO (no es la identidad estándar del grupo)

Este proyecto usa `UI-UX-WINDOWS.md` / `UI-UX-WINDOWS.html` (Fluent Design / Windows 11:
NavigationView, clic derecho, Master-Detail, ContentDialog/InfoBar/Flyout/Toast) en vez de
`UI-UX-LINKEDCORP.md` (identidad web estándar del grupo). Fue decisión explícita del usuario al
arrancar el proyecto. Copia ajustada en `docs/UI-UX-WINDOWS.md`.

Adaptación web (no es una app empaquetada, corre en pestaña de navegador):
- SÍ: tokens de color, tipografía, NavigationView, ListView+clic derecho, Master-Detail,
  ContentDialog, InfoBar, Toast, Flyout, ComboBox/DatePicker propios, Expander, Treeview.
- NO: barra de título falsa con minimizar/maximizar/cerrar (no hay ventana de SO que controlar).
- Igual obligatorio: idioma es-EC/en-US + tema claro/oscuro + apariencia de botones, todo persistido.
- Set de íconos: Lucide (única opción usada en este proyecto).

## Estructura acordada

- `frontend/`
- `backend/`
- `docs/`

## Modulos principales (MVP — ver SPEC.md para el detalle y lo diferido a fase 2)

- Seguridad (usuarios, roles fijos, sesión, auditoría)
- Organización (departamentos con sub-áreas, usuarios)
- Proyectos (con miembros)
- Actividades + Tareas + dependencias simples
- Dashboard (KPIs)
- Agenda médica (citas, pacientes, bloqueos, horarios y tipos; v4.7.0)
- Calendario y Gantt de solo lectura
- Comentarios y adjuntos
- Notificaciones in-app
- Equipos (inventario TI alimentado por agentes GLPI — ver `docs/ARQUITECTURA-INVENTARIO.md`)
- Configuración (catálogos: estados, prioridades, tipos de proyecto)
- Conexiones externas: datos de otros sistemas vía conectores de solo lectura en el servidor origen
  (`data/conectores/`, FoxPro instalado en Exilaser), pacientes de SAGA y empleados de nómina —
  ver `docs/CONEXIONES-EXTERNAS.md`. Regla: datos de SAGA **solo por la API del conector** (nunca
  leer DBF por SSH); SSH al Windows solo para administrar el conector, con permiso.

## Restricciones tecnicas

- No romper estructura existente.
- Mantener frontend y backend separados (arquetipo B).
- Variables de entorno, nunca secretos en código.
- Empresa asumida como única (single-company): no hay tabla `companies` en el MVP.
- Permisos por rol codificados en backend (`backend/src/middleware/auth.js`), no configurables por
  UI en el MVP — ver tabla de roles en SPEC.md.

## Arquitectura esperada

### Backend
- `routes -> controller -> service -> repository -> db`
- Un directorio por módulo en `backend/src/modules/<modulo>/`

### Frontend
- `src/components` (UI base Windows: NavigationView, ContentDialog, InfoBar, Toast, Flyout, ListView, ComboBox, DatePicker, Treeview, Field, Button)
- `src/pages` (Login, Dashboard, Organizacion, Proyectos, Configuracion)
- `src/services` (cliente API por módulo)
- `src/context` (auth, ui: tema/idioma/dialog/toast)
- `src/i18n`

## Seguridad (proyecto con auth/usuarios)

- Permisos validados SIEMPRE en el backend, nunca solo en el frontend.
- Cambio de correo con aprobación (v4.6.0): reautenticación, aprobador según rol y confirmación en el correo nuevo; sesiones revocadas solo al aplicar (migración 035).
- Autorregistro con doble candado (decisión posterior al MVP inicial, ver `SPEC.md`): el usuario
  se crea a sí mismo pero queda `pending_verification` → confirma su correo (token de un solo uso,
  24h) → `pending_approval` → un `admin`/`superadmin` aprueba (elige rol/departamento) o rechaza
  (se borra). Solo el usuario más antiguo del sistema es `superadmin` automático (bootstrap, sin
  correo ni aprobación — no hay quién lo apruebe). El admin sigue pudiendo crear usuarios
  directamente (ya activos, sin pasar por este flujo) desde Organización → Usuarios.
- `401` o JWT vencido (detectado también sin peticiones y al volver a la pestaña) → el frontend corta la sesión, va a login con aviso y, tras entrar el mismo usuario, vuelve a la ruta/pestaña/edición donde estaba (ver `docs/SESION-Y-BORRADORES.md`).
- Cierre de sesión por expiración de JWT.
- Cada JWT lleva un `sid` ligado a `user_sessions`; se puede consultar y revocar cada sesión desde Mi cuenta o por un administrador.
- Auditoría en BD (`audit_log`): usuario, acción, entidad, fecha/hora, detalle.
- Credenciales/secretos solo en `.env` (nunca en código); `.env.example` sí se versiona. Excepción:
  el SMTP del sistema NO vive en `.env` — lo carga el `superadmin` desde Configuración → Correo
  (SMTP), queda en `system_settings` con la clave cifrada (AES-256-GCM, `ENCRYPTION_KEY`).
- Cifrado: bcrypt para contraseñas; AES-256-GCM (`backend/src/utils/crypto.js`) para secretos de
  terceros guardados en BD (hoy: la clave SMTP).
- Revalidar `is_active` del usuario en cada request (un JWT firmado no basta); el login además
  revisa `status` (`pending_verification`/`pending_approval` dan un mensaje especifico, no login).
- SQL siempre parametrizado. Uploads: validar MIME/tamaño, ruta de archivo generada por el servidor.
- `forgot-password` responde SIEMPRE genérico (exista o no el correo); el envío de correo nunca
  debe poder tumbar ni cambiar la respuesta de un endpoint (`sendMail` atrapa sus propios errores).
- Ingesta de Equipos (`POST /api/inventory`): sin JWT, autenticada por token de instalación
  (`inventory_tokens`: hash para validar + copia cifrada AES-256-GCM, revelable solo a admin/superadmin con auditoría); cuerpo crudo con límite de tamaño e inflado.
- Sin SMTP configurado, el sistema degrada a modo dev: los correos de verificación/recuperación se
  loguean en la consola del backend en vez de enviarse (nunca rompe el flujo).


## Regla de UX para pantallas

- No mezclar listado y formulario de creación en la vista inicial de un módulo.
- Primero el listado; botón "Nuevo" abre creación.
- Detalle abre en modo lectura; "Editar" habilita campos; "Cancelar" vuelve a lectura sin guardar;
  guardar solo si hubo cambios reales.
- Secciones de una misma entidad (Proyecto: Info/Actividades/Gantt/Calendario/Comentarios/Documentos)
  van en pestañas reales, nunca apiladas ni navegando a otra pantalla.
- **Formularios en popup = modelo "Nueva reunión" de Calendario** (`pages/Calendario/CalendarioPage.jsx`):
  rejilla de 2 columnas (campos cortos en pares, texto largo a lo ancho), fecha + hora con
  `DateTimeEditor`, botones al pie. Cualquier formulario nuevo o existente que no siga esto se
  ajusta a ese modelo.
- Un popup "Nuevo …" abre limpio con el contexto del clic (día, hora, médico): nada de la apertura
  anterior (búsquedas, selecciones) se arrastra. Solo vuelve lo que el usuario dejó como borrador
  ("Dejar pendiente"), con el aviso de borrador recuperado.

## Delegar a Codex (u otro agente) en este proyecto

Además de la regla del orquestador: Claude escribe en el encargo las reglas que aplican (no "lee los
md") y nombra **solo** los archivos/secciones necesarios de esta lista, según la tarea:

| Si la tarea toca… | Nombrar |
|---|---|
| Pantallas/formularios | `docs/UI-UX-WINDOWS.md` (sección del componente) + pantalla modelo (formularios: `pages/Calendario/CalendarioPage.jsx`, listados: `pages/Organizacion/UsersPanel.jsx`) |
| Formularios con edición | `docs/SESION-Y-BORRADORES.md` § Comportamiento (`useDraftForm`) |
| Backend / permisos | `docs/SEGURIDAD-Y-CALIDAD.md` (sección aplicable), `API.md` § del módulo |
| Base de datos | `BASE_DE_DATOS.md` § del módulo + última migración |

Reglas fijas que siempre van escritas en el encargo: rejilla de 2 columnas como "Nueva reunión";
listado primero y popup en lectura → Editar; nada se arrastra entre aperturas de un popup; textos en
`i18n/messages.js` (es y en); reutilizar componentes de `src/components` sin crear variantes.
Si necesita herramientas, se le dicen en el encargo (build: `npx vite build` en `frontend/`; navegador:
Playwright global del orquestador; usuarios de prueba de dev: ver `ESTADO.md`).
Codex desarrolla y **Claude revisa y prueba siempre** lo que entregue (diff contra estas reglas, build,
navegador si cambia pantalla) antes de darlo por bueno.

## Flujos criticos

1. Login → Dashboard con KPIs del usuario.
2. Crear proyecto → asignar miembros → crear actividades → crear tareas → avance se recalcula solo.
3. Actividad vencida o por vencer → notificación in-app al responsable.

## Entorno operativo

- Desarrollo: `npm run dev` en `backend/` (puerto 4019) y `frontend/` (puerto 5196, proxy `/api`).
- Producción: operativo en `https://project.linkedcorp.net` (servidor `192.168.222.3`, arquetipo B,
  ver `PRODUCCION.md` y `DEPLOY_WEB.md`).
- Docker por defecto: no.

## Regla de versionado

- Versionado `X.Y.Z` (ver VERSIONADO.md).
- Antes de producción, validar si corresponde subir versión.
- Toda versión nueva se refleja en `VERSION` y `CHANGELOG.md`.

## Documentacion relacionada

- `README.md`, `SPEC.md`, `BASE_DE_DATOS.md`, `CONFIGURACION.md`, `API.md`, `VERSIONADO.md`
- `PRODUCCION.md`, `DEPLOY_WEB.md` (topología y flujo de deploy — arquetipo B, en producción)
- `docs/UI-UX-WINDOWS.md`, `docs/SEGURIDAD-Y-CALIDAD.md`, `docs/ARQUITECTURA-INVENTARIO.md`
- `docs/SESION-Y-BORRADORES.md` (vencimiento de sesión, retorno al contexto, borradores y avisos al salir; usar `useDraftForm` en todo formulario nuevo)
- `docs/CONEXIONES-EXTERNAS.md` (requisitos y diseño de datos externos) y `data/conectores/README.md` (contrato v1 de conectores)
- `ESTADO.md` (handoff — leer siempre al retomar el proyecto) y `DECISIONES.md` (decisiones acordadas)

## Pendientes para quedar listo

- Fase 2: riesgos/incidencias como módulos propios, solicitudes formales, recursos/proveedores,
  presupuesto y costos, registro de horas detallado, reportes exportables (PDF/Excel/CSV),
  permisos por acción dentro de cada módulo (el acceso por módulo y usuario ya existe, v3.1.0),
  integración IA, notificaciones por email.
- Limpiar `.md` del source en producción (`find ... -iname '*.md' -delete`) — pendiente, ver
  `ESTADO.md`.