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

• Cambio de correo (v4.6.0): desde Mi cuenta, correo nuevo y clave actual. Admin/superadmin aprueban solicitudes de usuarios comunes; solo superadmin aprueba admins; un superadmin se autoaprueba mediante enlace enviado a su correo actual. El nuevo correo se confirma por enlace de un solo uso. Solo entonces se actualiza users.email y se cierran todas las sesiones; solicitudes abiertas vencen a los 7 días y enlaces a las 24 horas. El usuario puede cancelar hasta aplicar.

• 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.
• Calendario personal (v4.5.0), igual para todos los roles (un admin no ve lo de los demás): reuniones que organizo o a las que me invitaron; proyectos donde soy dueño o miembro (inicio y fin estimado); actividades y tareas donde soy responsable; tareas recurrentes que creé o de las que soy responsable. Lo compartido aparece en el calendario de ambos: participantes de una reunión y responsable de una tarea recurrente (este la ve en solo lectura, porque el menú Tareas recurrentes solo la muestra al creador/admin).
• Filtros persistidos: Ver (Todo / Solo lo mío / Compartido conmigo) y Mostrar (lista con casillas: Todo, Reuniones, Proyectos, Mis actividades, Mis tareas, Tareas recurrentes). Compartido conmigo = lo creó u organiza otra persona y me incluye (reunión: organizador; proyecto: dueño; actividad y recurrente: creador; tarea: creador de su actividad, porque tasks no guarda creador).
• Cada tipo con color propio y leyenda; vencido en rojo, cerrado tachado, compartido con franja a la izquierda.
• La pestaña Calendario del proyecto muestra todas sus actividades y todas las reuniones vinculadas al proyecto (requiere acceso de lectura al proyecto).

7 bis. Agenda médica (v4.7.0)

• clinic se habilita explícitamente por usuario (desactivado por defecto; superadmin siempre tiene el módulo). Además exige una fila activa en clinic_staff: all permite a recepción ver/agendar con todos los médicos, gestionar pacientes y bloqueos; own permite a un médico ver su agenda, gestionar sus bloqueos y marcar atendida/no asistió. No crea citas. Los médicos conservan el resto de sus módulos y no se crea un rol del sistema.
• Admin/superadmin con acceso a clinic y fila de staff configuran personal, horarios por tramos y tipos de cita desde la pestaña Configuración de agenda.
• Vistas (v4.8.0; desde v4.8.1 abre en Mes con la barra del Calendario; la elegida se recuerda): Día con una columna por médico; Semana como calendario de 7 días con las citas de todos los médicos filtrados, coloreadas por médico; Mes como calendario mensual (hasta 5 entradas por día + "N más" que lleva al día; desde v4.9.0 clic en un día u hora libre abre la cita nueva con esa fecha); Lista con citas y bloqueos. Leyenda de colores por médico en Semana y Mes. Crear cita desde un hueco precarga médico/hora; el tipo fija la duración por defecto.
• Formularios (desde la refactorización posterior a v4.10.0) con el modelo de "Nueva reunión" de Calendario: campos en pares, fecha + hora con DateTimeEditor, notas a lo ancho. Pacientes y Bloqueos son listados (ListView); Configuración (personal, tipos, horario) son listados con popup en lectura → Editar. El detalle de un paciente muestra su historial de citas.
• "Nuevo paciente" desde la cita abre el formulario del paciente encima (precarga la cédula si lo buscado es numérico); guardar, cancelar o cerrar vuelve a la cita. Cada cita nueva abre limpia.
• Aviso, no bloqueo: al elegir el paciente de una cita, si tiene citas futuras agendadas o confirmadas (cualquier fecha y médico, sin contar la que se edita) se listan como advertencia y se puede agendar igual. Sin citas futuras no se muestra nada.
• Una cita no cancelada solo cabe si está completa dentro de un tramo de atención y no cruza otra cita del médico, un bloqueo suyo (también recurrente) ni otra cita del paciente con cualquier médico. Son errores 409 bloqueantes; la validación se repite bajo bloqueo de filas en una transacción para evitar reservas simultáneas del mismo hueco.
• Crear/editar un bloqueo que cruce citas devuelve las citas afectadas; solo se guarda tras confirmAffected=true. No cancela las citas: recepción debe reprogramarlas.
• Datos de paciente mínimos, sin historia clínica; cambios auditados sin incluir datos sensibles en el detalle. DATETIME representa hora civil America/Guayaquil.
• El calendario personal muestra al médico sus citas activas y bloqueos en la capa Citas médicas.

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.