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.