cosmoSys » Issues

# Manual de Usuario de cosmoSys

## Datos del producto

- **Nombre del sistema:** cosmoSys

- **Version:** _Completar_

- **Fecha:** _Completar_

- **Responsable de la informacion:** _Completar_

## Vision general

cosmoSys esta implementado como un plugin de Redmine y añade varias capacidades:

- Representacion grafica de la estructura de items y sus relaciones (incluida una vista/editor de arbol y la vista MainReport) para entender dependencias y jerarquias de un vistazo y reorganizarlas con arrastrar/soltar.

- Visualizacion tipo libro: los proyectos pueden verse como un documento con capitulos (items) y subcapitulos (items dentro de items).

- Identificadores csID mas legibles y contextuales dentro de cada familia de proyecto para localizar items sin recurrir a IDs globales largos.

- Generacion de informes estructurados (DOCX/ODT/HTML) basados en MainReport, con tabla de contenidos viva, diagramas embebidos ajustados a pagina y plantillas personalizables.

- Importacion y exportacion enriquecida de items a hojas de calculo ODS con plantillas guiadas.

- Herramientas de administracion que automatizan la carga masiva de proyectos a partir de WBS.

- Plataforma para otros plugins especializados (p.ej., cosmoSys-Req para gestion profesional de requisitos, cosmoSys-PORIS como repositorio de modelos PORIS, cosmoSys-Git para sincronizar un repositorio Git espejo de un proyecto con las importaciones/exportaciones ODS, y otros).

- Referencias documentales mediante items csInfo/csRef y matrices de referencias en MainReport e informes exportados.

## Publico objetivo

Personal de una empresa de ingenieria con estructura matricial:

- Usuarios asignados a proyectos con roles específicos por proyecto (como en Redmine).

- Perfiles habituales: jefes de proyecto, responsables de disciplina, ingenieros de distintas especialidades y PMO.

- Nivel técnico: usuarios familiarizados con gestión de tareas/proyectos y uso básico de herramientas web.

- Dispositivos: uso principal en escritorio/portátil; acceso web.

## Requisitos previos

- Software necesario: Acceso a una instancia de cosmoSys configurada para la organizacion (adaptada a proyectos y familias).

- Accesos y permisos: Credenciales de usuario; permisos de creacion de proyectos otorgados por el administrador cuando aplique.

- Datos de prueba o entorno: _Completar_

## Conceptos clave

- **Item**: unidad base (equivalente a una "issue" en Redmine) que en cosmoSys se usa de forma generica para tareas, requisitos o nodos de modelos.

- **Relaciones**: enlaces entre items (padre-hijo, depende de, bloquea, duplicado, etc.).

- **Familia de proyecto**: conjunto de proyectos de un mismo arbol Redmine (proyecto raiz y todos sus subproyectos). Un proyecto raiz es aquel sin proyecto padre (relacion "parent" vacia). Los items comparten contexto e identificadores legibles dentro de esa familia.

- **csID (identificador legible)**: identificador propio de cosmoSys para cada item (formato `csID-proyecto` + guion + numero de 5 cifras). Es unico por familia y no cambia salvo accion explicita de administracion.

- **csInfo**: clase de item (tracker en Redmine) orientada a estructurar contenidos en arbol para transcribir a documentos (capitulos/secciones).

- **csRef**: clase de item (tracker en Redmine) para referencias documentales (wiki, documentos, URLs, ficheros, citas) clasificadas como documentos de referencia, aplicables o de conformidad.

- **Diagrama jerarquico**: diagrama que muestra items padres e hijos como cajas anidadas (analogas a nodos expandidos en el editor de arbol o a capitulos/subcapitulos del MainReport).

- **Diagrama de dependencias**: diagrama que muestra items como cajas y relaciones dirigidas (bloquea a, precede a, copiado de, relacionado con). "Relacionado con" es bidireccional; las demas se leen en ambos sentidos (p.ej., bloquea a / es bloqueado por).

- **Vista/Editor de arbol**: vista del proyecto que muestra los items como nodos jerarquicos. Permite reorganizar arrastrando y soltando nodos y navegar abriendo/cerrando subarboles.

- **MainReport**: vista del proyecto en formato documento; los items se muestran como capitulos y subcapitulos. Permite configurar que campos se muestran/ocultan, si se incluyen diagramas contextuales (diagramas jerarquicos y de dependencias centrados en el item), y filtrar items por tipo o valores de campos. Puede volcarse a DOCX/ODT/HTML.

## Identificador csID de los items

- Generacion y formato:

  - Prefijo de proyecto (configurable en la ficha del proyecto, sin guiones ni espacios) + `-` + numero de 5 cifras desde `00000` segun orden de creacion en ese proyecto. Ej.: `MPR-00000`.

  - Prefijo unico por familia (proyecto raiz y subproyectos); familias distintas pueden compartir prefijos sin conflicto.

- Busqueda:

  - El buscador de csID parte del proyecto actual, sube al raiz de la familia y recorre todos los subproyectos buscando el prefijo-numero.

  - Si hay coincidencia en proyecto e item, se prioriza el item; si no se encuentra, se informa que no existe en la familia y se sugiere verificar prefijo/numero.

- Movimientos e inmutabilidad:

  - Mover items dentro de la misma familia no cambia el csID.

  - Solo una accion administrativa explicita puede renombrar un csID; se desaconseja para no romper trazabilidad (ODS, informes, referencias externas).

  - Mover a otra familia implicaria cambiar prefijo para evitar conflicto; debe definirse politica (bloqueo o renumeracion controlada por admin).

- Integracion ODS:

  - Columnas basicas recomendadas: `csID`, `Proyecto`, `Resumen`, `Tipo`, `Padre csID`, `Depende de csID`.

  - Validaciones: `Proyecto` solo admite proyectos de la familia; relaciones solo aceptan csID existentes en la misma familia.

  - Al importar se crean/actualizan items por csID y luego se resuelven relaciones por csID; csID ausentes generan error.

- Buenas practicas de prefijos:

  - 3–5 letras, sin guiones ni espacios; evitar siglas ambiguas con otros proyectos de la familia.

  - Revisar prefijos existentes antes de crear nuevos proyectos para prevenir colisiones.

- Errores comunes:

  - Prefijo duplicado en la familia: bloquear creacion y solicitar cambio.

  - csID no encontrado en importacion ODS: verificar prefijo del proyecto y que se importa en la familia correcta.

  - Relaciones a csID de otra familia: marcar error; mover el item objetivo a la familia o usar el ID interno si procede.

## Plugins adicionales

- cosmoSys-Req: gestor profesional de requisitos; depende de cosmoSys y cosmoSys-Git.

- cosmoSys-PORIS: repositorio de modelos PORIS (comportamiento y configurabilidad); depende de cosmoSys y cosmoSys-Git.

- cosmoSys-Git: sincroniza un repositorio Git espejo de un proyecto para gestionar importaciones/exportaciones ODS y obtener instantaneas del proyecto; depende de cosmoSys.

## Diagramas

- Tipos:

  - Jerarquico: estructura padre-hijo como cajas dentro de cajas (equivalente a nodos expandidos en el arbol o capitulos/subcapitulos en MainReport/exportaciones).

  - Dependencias: relaciones dirigidas entre items (bloquea a / es bloqueado por, precede a / sucede a, copiado de / copiado en) y la relacion bidireccional "relacionado con" con flechas.

- Alcance:

  - Centrados en proyecto: desde el detalle del proyecto, un diagrama de cada tipo que incluye todos los items del proyecto, incluso los aislados sin padre o sin relaciones.

  - Centrados en un item: desde el detalle de un item, cada diagrama arranca en ese item y expande solo su entorno conectado; si no hay camino jerarquico o de relaciones hacia otro item, ese item y sus relaciones no se muestran.

La combinacion genera cuatro vistas: jerarquico del proyecto, dependencias del proyecto, jerarquico del item y dependencias del item.

## Flujo principal

1. _Acceso a cosmoSys y seleccion de un proyecto activo: Completar_

2. _Busqueda (campo csID) o creacion de un item con csID dentro del proyecto/familia: Completar_

3. _Exploracion en diagramas (jerarquico/dependencias), en la vista/editor de arbol o en MainReport para revisar y, si aplica, reorganizar la jerarquia y ajustar la visibilidad de campos: Completar_

## Roles y permisos

cosmoSys hereda el sistema de roles de Redmine y se adapta a la organizacion. Los nombres Manager, Colaborador y Lector son ejemplos tipicos de la configuracion base; las organizaciones suelen copiarlos, renombrarlos y ajustarlos (p.ej., "jefe de departamento", "jefe de proyecto" a partir de Manager; "ingeniero informatico", "ingeniero de sistemas", "tecnico de laboratorio" a partir de Colaborador; "interesado", "supervisor", "cliente" a partir de Lector).

| Ejemplo de rol | Que puede hacer | Restricciones |

| --- | ---------------- | ------------- |

| Manager de proyecto | Crear proyecto (si tiene permiso), configurar el equipo seleccionando usuarios y asignandoles roles (heredables si se define en configuracion), crear/editar items, ver la vista grafica completa | Solo en proyectos donde es manager; permisos de creacion otorgados por administrador |

| Colaborador | Actualizar items asignados, comentar, seguir relaciones en la vista | No modifica configuraciones de proyecto ni permisos |

| Lector | Ver items y relaciones | Sin edicion |

> Los roles son apilables: un usuario puede tener varios roles en un proyecto y sus permisos se suman. Puede haber varios usuarios con el mismo rol (incluido varios managers) o ninguno; si no hay manager, el administrador de cosmoSys/Redmine configura el equipo. Los equipos se definen por proyecto; pueden heredarse segun la configuracion que establezca el manager.

## Tareas frecuentes

Instrucciones paso a paso para las acciones mas comunes. Incluye capturas o comandos cuando apliquen.

### Reorganizar la jerarquia en la vista/editor de arbol

1. Accede al proyecto activo y abre la vista/editor de arbol.

2. Expande los subarboles necesarios para localizar el item a mover.

3. Arrastra el nodo y suelta sobre el nuevo padre o posicion permitida.

4. Verifica que la jerarquia se actualiza y que las relaciones esperadas se mantienen.

### Usar la vista MainReport

1. Accede al proyecto activo y abre la vista MainReport.

2. Configura los campos visibles y decide si mostrar los diagramas contextuales de cada item.

3. Aplica filtros para ocultar items por tipo o por valores de campos.

4. Navega el documento como capitulos/subcapitulos para revisar el contenido estructurado.

### Exportar MainReport a DOCX/ODT/HTML

1. Prepara la vista MainReport con campos y diagramas segun necesidad.

2. Elige el formato de salida (DOCX, ODT o HTML).

3. Selecciona la plantilla del informe (puedes usar las plantillas patron de cosmoBots o una propia adaptada a tu organizacion).

4. Genera el documento: se creara una tabla de contenidos viva, se incrustaran las imagenes/diagramas ajustados para no salir de pagina y se autogeneraran los capitulos de referencias (documentos de referencia, aplicables y de conformidad) con sus matrices.

## Referencias documentales (csInfo/csRef)

- Items csInfo sirven para estructurar contenidos en arbol (capitulos/secciones) arrastrando otros items dentro (p.ej., un csInfo "Bugs pendientes" conteniendo bugs abiertos). Son clases de item (trackers) pensadas para visualizar el proyecto como un libro.

- Items csRef apuntan a referencias bibliograficas o documentales (wiki, documentos, URLs, ficheros, citas) y se clasifican como documentos de referencia, aplicables o de conformidad.

- Cada item puede tener un listado de csRef asociados en esas tres categorias.

- MainReport y los informes exportados generan automaticamente los capitulos de referencias y las matrices que relacionan los documentos de referencia con los items.

## Casos de uso ampliados

Historias de usuario o escenarios completos con inicio y fin. _Completar_

## Personalizacion y configuracion

Opciones de ajustes, plantillas y preferencias. _Completar_

## Integraciones

### Importacion/exportacion ODS de items

- Plantillas ODS (cosmoBots provee ejemplos) preparadas para crear/revisar items con:

  - Desplegables para seleccionar relaciones de dependencia y campos no libres.

  - Vistas de revision tipo DSM (Design Structure Matrix) o diagrama de bloques.

  - Refuerzos semanticos para resaltar la jerarquia de nodos.

  - Reglas de validacion (p.ej., columna "Asignado a" solo permite miembros del proyecto).

- Pestana `Dict` define los terminos y listas usadas en validaciones.

- Pestana adicional para que el usuario agregue nombres de columnas extra a importar/exportar.

- Plantilla troncal disponible; se pueden aportar plantillas propias adaptadas.

### Herramientas de administracion y automatizacion

- Script de carga masiva que toma una WBS (paquetes de trabajo) de uno o varios proyectos grandes y genera la arquitectura en una o varias familias de proyecto.

- Hoja de carga con refuerzos visuales/semanticos para definir equipos, entregables y responsables de cada proyecto y entregable.

- El script crea tareas de kick-off, desarrollo y cierre, enlazadas con dependencias fin-inicio y asignadas a sus responsables.

- Script de carga de tareas desde plantilla: a partir de una tabla con tareas, estimaciones, asignados y relaciones, permite que el equipo revise dependencias, reorganice y vea carga de trabajo en la propia hoja. Luego crea las tareas en el proyecto, asigna, categoriza y aplica relaciones.

- Estas dos herramientas (hojas de calculo semanticas + scripts) facilitan levantar estructuras de proyectos o cargar un proyecto consensuado desde hojas de calculo.

## Resolucion de problemas

- Sintoma: _Completar_ → Solucion: _Completar_

- Sintoma: _Completar_ → Solucion: _Completar_

## Preguntas frecuentes

- _Pregunta frecuente_ → _Respuesta_

## Referencia rapida

| Accion | Donde | Notas |

| --- | --- | --- |

| Crear csID | Nueva issue/item en el proyecto | Asigna siguiente numero de la secuencia del proyecto (prefijo-configurado). |

| Buscar csID | Buscador de csID en vista de proyecto/item | Recorre toda la familia; mensaje claro si no se encuentra. |

| Mover item | Arrastrar en vista de arbol | csID no cambia dentro de la familia. |

| Renombrar csID | Solo admin (accion especial) | Evitar salvo causa mayor; documentar cambios. |

## Seguridad y buenas practicas

- cosmoBots no asume responsabilidad sobre la seguridad del servidor cosmoSys ni de su contenido: se recomienda instalarlo en intranet o bajo VPN de la organizacion y combinarlo con una politica de respaldos.

- La organizacion debe decidir el equilibrio entre proteccion y facilidad de acceso para su equipo.

- Existen terceros (normalmente empresas) que pueden ofrecer alojamiento y mantenimiento con garantias de seguridad; evalue esas opciones si no hay infraestructura propia.

## Soporte y escalamiento

- Instancia publica para tickets de cosmoSys (bugs y desarrollo): https://support.csys.cosmobots.eu/projects/csys-issues/issues

- Canales de reporte: chat de soporte en Telegram; email de soporte de cosmoBots; o solicitud de usuario para reportar directamente en la instancia.

- _Completar con horarios/SLA/contactos especificos si aplican._

## Bitacora de cambios

- Version _X.Y_: _Resumen de cambios_

## Apendices

Material extra: glosario, formatos de archivo, plantillas de ejemplo. _Completar_