project.linkedcorp.net/SPEC.md

# SPEC - project.linkedcorp.net

## Objetivo

Sistema interno para que una empresa de tamaño medio controle los proyectos y actividades de TI que
debe cumplir: qué proyectos hay, quién es responsable de qué, qué está atrasado y qué avance real
tiene cada cosa — sin que cargar la información sea tedioso para quien lo usa día a día.

## Problema que resuelve

- Hoy no hay un lugar único donde ver proyectos activos, actividades pendientes/vencidas y de quién
  es cada una. El Jefe de TI necesita esa foto al entrar, sin perseguir a cada persona.

## Usuarios o roles

| Rol | Alcance |
|---|---|
| Super Administrador | Todo lo de Administrador + configura el SMTP del sistema. Es el usuario más antiguo (bootstrap automático al registrarse el primero) |
| Administrador | Todo, incluida gestión de usuarios/roles/catálogos y aprobar/rechazar registros |
| Jefe de TI | Ve y gestiona todos los proyectos/actividades, aprueba; no administra usuarios |
| Coordinador / Líder de proyecto | Crea/edita los proyectos donde es responsable o miembro, gestiona sus actividades |
| Colaborador | Ve y actualiza lo asignado a él (actividades/tareas propias), comenta |
| Consultor | Solo lectura en todo |

## Modulos (MVP)

### 1. Seguridad
- Login/logout con JWT (`sub`, `sv`, `sid`) y fila activa por sesión en `user_sessions`.
  Mi cuenta muestra perfil, preferencias, seguridad y sesiones activas. Cada usuario puede cerrar
  una sesión propia o todas las demás; admin/superadmin pueden cerrar sesiones de usuarios desde
  Organización, pero solo superadmin puede hacerlo sobre otro superadmin. Cada cierre se audita.
- Usuarios: alta/edición directa por el Administrador (nombre, email, rol, departamento, cargo,
  activo/inactivo) **o** autorregistro público (`/registro`) con doble candado: el propio usuario
  confirma su correo (enlace de un solo uso, vence en 24h) y luego un Administrador/Super
  Administrador aprueba la cuenta (elige rol y departamento) o la rechaza. El primer usuario que
  exista en el sistema se vuelve Super Administrador automáticamente, sin correo ni aprobación.
- Recuperación de clave (`/olvide-clave` → `/restablecer-clave`): respuesta siempre genérica
  (no revela si el correo existe), enlace de un solo uso que vence en 1 hora.
- Correo saliente (verificación/recuperación): SMTP configurable desde Configuración por el Super
  Administrador; sin configurar, el sistema sigue funcionando en modo dev (el enlace se loguea en
  vez de enviarse por correo real).
- Auditoría central (`audit_log`): quién hizo qué, sobre qué entidad, cuándo.

### 2. Organización
- Departamentos (con sub-área opcional vía `parent_id`, ej. TI → Desarrollo).
- Usuarios pertenecen a un departamento y tienen un cargo (texto libre).

### 3. Proyectos
- Código autogenerado, nombre, descripción, objetivo, tipo, prioridad, estado, responsable,
  miembros del equipo, fechas (inicio, fin estimado, fin real), % avance (calculado desde las
  actividades), departamento solicitante y responsable, nivel de riesgo (bajo/medio/alto), notas.
- Estados: Planificado, En preparación, En ejecución, En pausa, Bloqueado, Completado, Cancelado.

### 4. Actividades
- Código, nombre, descripción, responsable, prioridad, estado, fecha inicio, fecha límite, fecha
  real de fin, % avance, marca de hito (`is_milestone`), horas estimadas, dependencias simples
  ("depende de" otra actividad del mismo proyecto).
- Estados: Pendiente, En progreso, En revisión, Bloqueada, En espera, Completada, Cancelada.

### 5. Tareas
- Checklist liviano dentro de una actividad: nombre, responsable opcional, hecho/no hecho, fecha
  límite opcional. Si una actividad tiene tareas, su avance se calcula solo desde ellas.

### 6. Dashboard
- KPIs: proyectos activos, proyectos atrasados, actividades pendientes/vencidas/para hoy, avance
  promedio. Lista de actividades vencidas y de hoy del usuario.

### 7. Calendario
- Menú propio de reuniones (v4.4.0): Mes/Semana/Día/Agenda, creación desde hueco o botón,
  detalle de lectura y edición de toda la serie. Título, descripción, inicio/fin, todo el día,
  ubicación, enlace de videollamada, proyecto opcional, recordatorio y recurrencia.
- Participantes internos (RSVP aceptar/rechazar/quizás) y hasta 50 correos externos sin RSVP.
  Solo organizador, admin y superadmin editan/cancelan. Lectura: organizador, participante o
  acceso al proyecto asociado. El módulo `calendar` se puede deshabilitar por usuario.
- Recurrencia diaria, semanal por días o mensual por día del mes; hasta 365 ocurrencias y fin
  obligatorio por fecha o cantidad. Cancelación puntual con EXDATE; DELETE cancela lógicamente
  toda la serie. Invitaciones/cancelaciones iCalendar y recordatorios in-app.
- Los vencimientos de actividades se muestran en solo lectura y se pueden ocultar. La pestaña
  Calendario del proyecto muestra sus actividades y reuniones vinculadas.

### 8. Gantt
- Vista de solo lectura por proyecto: barras por actividad (inicio/fin/avance), sin edición directa
  desde el gráfico en el MVP.

### 9. Comentarios y adjuntos
- Hilo de comentarios por proyecto y por actividad.
- Adjuntar archivos (evidencias) a proyecto o actividad.

### 10. Notificaciones
- In-app (campana con contador): asignación de actividad, actividad vencida/por vencer (job diario),
  cambio de estado relevante.

### 11. Equipos (inventario TI, desde v2.15.0)
- Menú "Equipos" visible para `superadmin`, `admin` y `it_manager`. Inventario automático de
  hardware y software alimentado por el **agente GLPI oficial** instalado en cada equipo (sin
  servidor GLPI). Diseño en `docs/ARQUITECTURA-INVENTARIO.md`.
- Pestañas: Equipos (KPIs + listado + detalle General/Usuarios/Hardware/Red/Software/Historial),
  Software (transversal: en cuántos equipos está instalado) y Agentes (tokens de ingesta,
  solo `superadmin`/`admin`) y Compartir (da acceso de solo lectura a otros usuarios, `superadmin`/`admin`).
- Edición manual solo de: estado (activo/de baja), usuario asignado, departamento y notas; el
  resto lo manda el agente. Historial de cambios entre reportes.
- Fuera de este módulo (fase 2): tickets/helpdesk, despliegue remoto de software, panel de
  impresoras con tóner, export CSV.

### 12. Configuración
- Catálogos editables por el Administrador: estados de proyecto, estados de actividad, prioridades,
  tipos de proyecto, departamentos. Vienen con datos semilla — no requieren configuración inicial.
- Preferencias de interfaz: idioma es-EC/en-US, tema claro/oscuro, apariencia de botones.
- Correo (SMTP) — visible y editable **solo** por el Super Administrador: host, puerto, usuario,
  remitente y clave (la clave se guarda cifrada y nunca se vuelve a mostrar, solo se sabe si está
  "configurada" o no).

## Flujos clave

1. Administrador crea departamentos y usuarios (con rol y departamento).
2. Jefe de TI o Coordinador crea un proyecto, asigna miembros, define fechas y prioridad.
3. Se crean actividades dentro del proyecto (con responsable, fechas, dependencias si aplica).
4. Cada responsable actualiza el avance de sus actividades/tareas; el avance del proyecto se
   recalcula solo.
5. El Jefe de TI entra al Dashboard y ve de un vistazo activos/atrasados/pendientes/avance.
6. Vencimientos se marcan automáticamente (🟢 en tiempo / 🟡 próximo a vencer / 🔴 vencido) y generan
   notificación in-app al responsable.

## Reglas funcionales importantes

- El listado se ve primero; la creación se abre solo con el botón "Nuevo" (regla de UX del grupo).
- El % de avance de una actividad con tareas es automático (no editable a mano); sin tareas,
  es manual (0-100).
- El % de avance de un proyecto es el promedio del avance de sus actividades (no editable a mano).
- Una actividad no puede marcarse "Completada" si depende de otra que no lo está (aviso, no bloqueo
  duro en el MVP).
- Todo texto de interfaz sale de i18n (es-EC/en-US), nunca hardcodeado.

## Fuera de alcance por ahora (fase 2+)

- Riesgos e Incidencias como módulos propios (hoy: `risk_level`/notas en el proyecto).
- Solicitudes/requerimientos formales de otras áreas.
- Recursos (servidores/licencias/software), Proveedores, Presupuesto y costos.
- Registro de horas trabajadas detallado (bitácora diaria).
- Reportes exportables (PDF/Excel/CSV) y vista ejecutiva separada.
- Permisos por acción dentro de cada módulo (ver/crear/editar/borrar). El acceso por módulo y
  usuario ya existe (v3.1.0).
- Notificaciones por email/WhatsApp.
- Equipos de trabajo (personas) como entidad propia multi-proyecto (hoy: miembros por proyecto).

## Estado para produccion

- Completado: en desarrollo (MVP en construcción).
- Bloqueantes: ninguno conocido; deploy a producción pendiente de validación del MVP en local.