cosmoSys

{{>toc}}

# Guía funcional de cosmoSys

Esta guía explica cómo entiende cosmoSys un proyecto y qué función cumple cada una de sus herramientas. No es un tutorial de botones ni una referencia de administración: su propósito es que el usuario pueda interpretar correctamente árboles, relaciones, diagramas, informes, transferencias y copias antes de utilizarlos.

cosmoSys se construye sobre [Redmine](https://www.redmine.org/). Conserva su modelo de proyectos, usuarios, roles, permisos, workflows, documentos, wikis y colaboración, y añade una capa de ingeniería para estructurar, relacionar, analizar y publicar la información.

## 1. El modelo fundamental

### Proyectos e ítems

El espacio de trabajo se divide en proyectos. Un proyecto puede contener otros proyectos, de modo que una instancia forma un bosque de árboles independientes.

Dentro de cada proyecto viven los **ítems**. Técnicamente se apoyan en las *issues* de Redmine, pero cosmoSys utiliza el término ítem porque no todos representan incidencias o tareas: también pueden ser capítulos, requisitos, datos del proyecto u otros objetos de ingeniería.

Cada proyecto delimita un ámbito manejable, con sus miembros, permisos y contenido. El árbol completo permite conservar una visión común de programas grandes sin obligar a todos los participantes a trabajar sobre una lista única e inabarcable.

### Jerarquía y relaciones

La jerarquía responde a una pregunta: **¿dónde está contenido o presentado este ítem?** Un hijo puede formar parte de un capítulo, una descomposición de trabajo o una sección documental.

Las relaciones responden a preguntas diferentes: **¿de qué depende?, ¿qué bloquea?, ¿qué precede?, ¿con qué está relacionado?** Dos ítems pueden estar muy próximos en el árbol y no depender entre sí, o pertenecer a proyectos distintos y mantener una relación esencial.

cosmoSys conserva esta separación en todo el sistema. Los diagramas combinados pueden presentar ambas dimensiones a la vez, pero no las confunden.

### El árbol de proyectos como ámbito de identidad

Los proyectos que comparten una raíz forman un espacio de ingeniería común. Dentro de ese árbol se comprueba la unicidad de los códigos de proyecto y de los identificadores de los ítems. También es el ámbito habitual para resolver referencias, datos compartidos y relaciones entre proyectos.

Mover un ítem dentro del mismo árbol puede conservar su identidad. Moverlo a otro árbol supondría trasladarlo a otro espacio de identidad y no es una operación ordinaria.

## 2. Identidades y numeración

### CSID

Cada ítem recibe un **CSID** legible, como `M2-0027`. El prefijo procede del código del proyecto que lo creó y el número se obtiene de un contador monotónico: los huecos no se reciclan.

El CSID es identidad, no posición. Permanece estable aunque el ítem cambie de padre, de capítulo o de proyecto dentro del mismo árbol. Puede utilizarse para buscarlo, citarlo y crear enlaces Markdown como `#M2-0027`.

Redmine mantiene además su ID numérico interno. Ambos identificadores son útiles, pero cumplen funciones diferentes: el ID de Redmine garantiza la identidad técnica dentro de la instancia; el CSID ofrece una identidad de ingeniería comprensible dentro del árbol.

### Capítulos

El número de capítulo se calcula a partir de la posición jerárquica vigente. Si un usuario mueve una sección, su capítulo y los de sus descendientes pueden cambiar sin que cambien sus CSID.

Esta distinción permite reorganizar el documento con seguridad: las citas estables siguen apuntando al mismo objeto mientras la presentación refleja la nueva estructura.

## 3. Perfiles: adaptar sin acoplar

### Item profiles

Un **item profile** describe capacidades de dominio. Puede determinar, por ejemplo:

- si el ítem puede tener hijos y qué perfiles son compatibles;

- si aparece en el árbol, los diagramas o el informe;

- qué metadatos presenta;

- qué tipo de referencia prefiere mostrar;

- si actúa como marcador de un capítulo autogenerado;

- si admite datos del proyecto o validaciones específicas.

El código de cosmoSys trabaja sobre perfiles, no sobre nombres de trackers. Esto permite que los trackers suministrados sean reemplazables y que una organización cree otros sin romper la semántica del sistema.

### Trackers

Un tracker es la configuración concreta que Redmine ofrece al usuario al crear un ítem. Puede asignarse a un item profile y añadir su propio workflow o selección de campos.

Varios trackers pueden consumir el mismo perfil. Si desaparece un tracker suministrado inicialmente, otro compatible puede ocupar su lugar. Por eso la funcionalidad no debe depender de nombres como `csInfo`, `csDatum` o `csRq`, aunque éstos resulten cómodos como configuración inicial.

### Project profiles

Un **project profile** prepara un proyecto para una finalidad. Define una combinación coherente de módulos, trackers, columnas, plantillas y preferencias. Un proyecto de tareas y otro de requisitos pueden compartir instancia y relaciones sin verse obligados a mostrar los mismos campos.

Los perfiles no sustituyen a la configuración de Redmine. Roles, permisos, workflows y campos personalizados continúan disponibles para adaptar el entorno a cada organización.

## 4. El árbol de ítems

La vista Tree presenta el contenido como una estructura navegable y reordenable. Los movimientos respetan el ámbito del árbol de proyectos y las compatibilidades declaradas por los item profiles.

El orden entre hermanos se guarda como una posición interna. Los capítulos visibles se calculan a partir de ese orden, sin convertirlos en identificadores permanentes.

Al crear un subítem, cosmoSys puede sugerir débilmente un perfil adecuado. Si existe un tracker compatible, lo preselecciona; si no existe, permite escoger otro tracker válido en lugar de bloquear innecesariamente el formulario.

Algunos perfiles no pueden contener hijos. Esta regla no se expresa mediante excepciones por nombre, sino mediante la lista de perfiles compatibles. Una lista vacía significa que el ítem es una hoja.

## 5. Relaciones y trazabilidad

cosmoSys utiliza las relaciones nativas de Redmine y les proporciona representaciones y recorridos adecuados al modelo de ingeniería.

- **Blocks** expresa que un ítem bloquea a otro. Puede representar dependencia técnica o causal.

- **Precedes** expresa precedencia temporal con la semántica habitual de Redmine.

- **Relates** conecta elementos sin imponer dirección causal.

- La relación padre-hijo pertenece a la jerarquía y no sustituye a ninguna de las anteriores.

Una relación puede cruzar proyectos cuando los permisos y el ámbito lo permiten. El usuario que sólo ve uno de los extremos no debe recibir información que no tiene autorización para consultar.

Las relaciones aparecen desde ambos extremos. Por ello una copia coordinada puede reconstruir una conexión cuando materializa el extremo que conserva la evidencia necesaria, aunque las operaciones entre árboles distintos requieren políticas explícitas de identidad.

## 6. Diagramas

### Diagrama jerárquico

Muestra la estructura de contención. Los ítems capaces de agrupar contenido se representan como clusters y los descendientes aparecen dentro de ellos.

Sirve para comprender la arquitectura editorial o funcional del proyecto, no para expresar por sí solo causalidad.

### Diagrama de dependencias

Muestra relaciones seleccionadas y permite recorrerlas hacia delante o hacia atrás. El usuario puede activar capas como bloqueos, precedencias o relaciones genéricas.

Los elementos aislados pueden omitirse cuando no aportan información a la vista. Los ítems conectados mediante referencias documentales se consideran parte del contexto pertinente cuando esa capa está activa.

### Diagrama combinado

Integra jerarquía y relaciones. Un elemento descubierto por una relación conserva su contexto jerárquico, aunque pertenezca a otro proyecto. De esta forma, una caja externa no aparece flotando sin explicar en qué capítulo se encuentra.

Los elementos que no pertenecen al proyecto protagonista se distinguen visualmente. El recorrido entre proyectos puede detenerse en la frontera o continuar, según las opciones elegidas.

### Protagonista y señales visuales

Cuando el diagrama se genera desde un ítem, éste actúa como protagonista y recibe un énfasis especial. Si el ítem es inconsistente, el énfasis adopta el rojo de la inconsistencia en lugar de ocultarlo bajo el color normal de selección.

Los colores y bordes ayudan a interpretar el modelo, pero no sustituyen los mensajes explicativos de la vista.

### Caché

Los diagramas se identifican mediante una firma de su contenido, opciones y variante de renderizado. Si esa firma no cambia, cosmoSys puede reutilizar el resultado; cuando cambia un dato relevante, la versión anterior queda obsoleta.

## 7. Matriz DSM

La DSM representa los ítems simultáneamente en filas y columnas. Una marca en el cruce indica una dependencia entre ambos.

El orden de los elementos divide visualmente la matriz alrededor de la diagonal. Las relaciones que apuntan hacia atrás aparecen por encima y ayudan a detectar una secuencia incompatible o un ciclo.

Reordenar la DSM no cambia por sí solo las relaciones. Permite explorar órdenes posibles y observar inmediatamente cuáles respetan la red de dependencias.

Los ciclos no siempre son errores: fabricación y metrología pueden formar una realimentación deliberada. La DSM ayuda a distinguir esos bucles inevitables de dependencias accidentales capaces de provocar grandes retrabajos.

## 8. Datos del proyecto

Un ítem del perfil de datos define una clave, un nombre legible y un valor. En la configuración suministrada se presenta mediante el tracker `csDatum`.

- `${Clave}` muestra el nombre legible.

- `${Clave.value}` muestra el valor.

- Si no existe nombre legible, la propia clave actúa como nombre.

- Si no se puede resolver la clave, la expresión permanece visible.

El diccionario se consulta dentro del árbol de proyectos. Las claves deben ser únicas en ese ámbito visible para evitar resoluciones ambiguas.

La resolución se realiza bajo demanda. Durante una presentación se conserva en memoria lo ya consultado para no buscar repetidamente el mismo dato. El ledger registra qué claves se utilizaron realmente.

En un informe, ese ledger puede alimentar una tabla de metadatos. La tabla representa los datos que participaron en el texto generado, no necesariamente todos los datos existentes en el árbol.

cosmoSys no ofrece todavía un motor de magnitudes o fórmulas. Los valores son texto enriquecido y pueden incluir unidades, porcentajes o Markdown.

## 9. Documentos y referencias

### Documentos

Los documentos son los objetos nativos de [Redmine](https://www.redmine.org/), ampliados con metadatos como código externo, fecha y versión. Conservan categorías, descripción y ficheros adjuntos.

### Catálogo

Un documento puede participar en tres familias:

- `RD.n`: documento de referencia;

- `AD.n`: documento aplicable;

- `CD.n`: documento de cumplimiento.

La etiqueta depende de la familia y del orden actual. No es una identidad permanente.

### Referencias desde ítems

Una referencia une un ítem con una entrada documental y puede añadir:

- **sentido**, para explicar por qué se utiliza;

- **localización**, para indicar capítulo, página, cláusula, tabla o anexo.

El mismo documento puede citarse varias veces con contextos diferentes.

Dentro del Markdown se utiliza un marcador estable como `document:di5`. Al presentarlo, cosmoSys calcula la etiqueta vigente y crea el enlace. Reordenar el catálogo modifica `RD.n`, pero no el marcador ni el destino.

La visibilidad se comprueba al presentar la referencia. Un usuario no debe obtener el título ni los metadatos de un documento al que no tiene acceso.

## 10. Informes

### Vista HTML

El informe HTML permite revisar el proyecto como documento antes de exportarlo. Utiliza la misma jerarquía y los mismos textos, tablas, referencias y diagramas del modelo vivo.

Los perfiles determinan qué campos se incorporan y si aparecen como metadatos compactos o como apartados del cuerpo.

### Capítulos autogenerados

Algunos ítems estructurales actúan como marcadores. Su posición en el árbol decide dónde se insertará una tabla generada, por ejemplo:

- catálogo de documentos de referencia, aplicables o de cumplimiento;

- datos utilizados por el informe;

- elementos cerrados negativamente que deban conservarse como trazabilidad.

El marcador mantiene su título y capítulo, pero sustituye el contenido ordinario por la vista correspondiente.

### Diagramas en el informe

Cada ítem puede escoger el diagrama que mejor lo explica o decidir que no necesita ninguno. Las preferencias globales completan los casos sin elección individual.

La exportación calcula el espacio disponible en la plantilla. Si una figura quedaría demasiado reducida y existe una página donante con orientación opuesta, puede trasladarla allí cuando esa alternativa mejora realmente su escala.

### Plantillas y formatos

Las plantillas ODT controlan estilos, portada, cabeceras, pies, logos, tablas y propiedades. Pueden definirse por perfil y sustituirse en proyectos concretos, con herencia controlada entre proyectos compatibles.

La salida principal es ODT y puede convertirse a DOCX o PDF mediante LibreOffice. La vista HTML sigue siendo la previsualización funcional del contenido, pero el usuario debe revisar también el artefacto final.

## 11. Exportación e importación ODS

La exportación ODS crea un libro abierto con ítems, metadatos y hojas auxiliares. Puede abarcar el proyecto actual o incluir descendientes según la operación.

El manifiesto oculto conserva formato, proyecto, `export_id`, identidades de fila y valores base necesarios para reconciliar los cambios.

Al importar, cosmoSys realiza primero un análisis:

- identifica altas y modificaciones;

- reconoce filas ya materializadas;

- valida jerarquía, relaciones y referencias;

- detecta cambios concurrentes entre Redmine y el ODS;

- presenta incidencias y conflictos;

- exige confirmación antes de aplicar.

Si el mismo campo cambió de forma distinta en ambos lados, la primera política segura puede conservar el valor de Redmine, aplicar otros cambios no conflictivos e informar de lo omitido.

El resultado ofrece un ODS reconciliado donde las identidades provisionales han sido sustituidas por las persistentes. Ése es el punto recomendado para continuar el trabajo fuera de línea.

## 12. Snapshots

Un snapshot es una captura inmutable de uno o varios proyectos seleccionados dentro del mismo árbol. El manifiesto contiene el estado soportado de proyectos, ítems, jerarquía, relaciones, documentos, referencias y adjuntos, además de otros componentes que el contrato va incorporando por fases.

La descarga genera un paquete `.csys`, que es un ZIP con:

- manifiesto JSON canónico;

- ficheros binarios organizados por su SHA-256;

- una sola copia de cada contenido idéntico dentro del paquete.

El snapshot no incluye el historial de actividad ni pretende replicar cada tabla interna de Redmine. Es un contrato de contenido, no una copia física de la base de datos.

Antes de materializarlo, el preflight comprueba esquema, plugins declarados, perfiles, trackers, identidades, ficheros y destino. Una materialización confirmada crea proyectos nuevos; no mezcla silenciosamente el contenido con un proyecto vivo existente.

## 13. Copias fieles y limpias

La política de estado y la política de identidad son decisiones distintas.

### Copia fiel

Conserva el estado material vigente y las evidencias que forman parte de él. Puede preservar los CSID si el árbol de destino no contiene colisiones.

Es útil como baseline navegable o como réplica controlada de un proyecto.

### Copia limpia

Reinicia estados de trabajo, progreso y otras evidencias de ejecución según el contrato del perfil. Normalmente genera nuevas identidades.

Es adecuada para utilizar un proyecto patrón como plantilla.

### Copia de árboles

Una operación puede seleccionar varios proyectos relacionados. Primero crea sus estructuras de destino e ítems, construye un mapa global de identidades y después restaura jerarquías y relaciones. Así puede reconstruir conexiones entre proyectos incluso cuando se generan CSID nuevos.

Los proyectos seleccionados deben pertenecer al mismo árbol y tener una colocación de destino no ambigua.

## 14. Permisos y visibilidad

cosmoSys consume los permisos de [Redmine](https://www.redmine.org/) en lugar de crear una vía paralela de acceso.

Un diagrama, informe, selector o búsqueda debe respetar lo que puede ver el usuario. El hecho de que una relación o un dato exista no autoriza a revelar el extremo oculto.

Algunas resoluciones de presentación pueden utilizar información de sistema para mantener estable un texto compartido, pero eso no implica que el usuario pueda navegar hasta el objeto protegido ni consultar sus metadatos.

Roles y workflows controlan quién puede editar o realizar transiciones. La condición de administrador no sustituye automáticamente un workflow si éste no ofrece la transición correspondiente.

## 15. cosmoSys-Req y otras extensiones

[[csys-req:cosmoSys-Req]] añade el dominio de requisitos sobre esta base. Reutiliza proyectos, ítems, identidades, relaciones, datos, documentos, diagramas, informes, ODS, snapshots y permisos.

Su lógica específica —tipos y niveles de requisito, derivación, verificación, cumplimiento, madurez y evidencia aprobada— permanece en el plugin de requisitos.

Esta separación permite que cosmoSys siga siendo útil para tareas y otros dominios, y que futuras extensiones incorporen reglas propias sin duplicar la infraestructura común.

## 16. Límites y responsabilidad

cosmoSys puede impedir identidades duplicadas, validar estructuras, detectar referencias rotas y hacer visibles determinadas inconsistencias. No puede decidir si una relación causal es correcta, si una planificación es realista o si un texto expresa adecuadamente una necesidad.

El contenido es colaborativo y puede cambiar entre la visualización y la descarga de un informe. La herramienta aporta evidencias y avisos, pero no promete una congelación transaccional de toda la instancia durante cada lectura.

Un documento generado debe revisarse antes de entregarse. La automatización reduce tareas mecánicas y hace visibles muchos errores; no sustituye la responsabilidad técnica.

## Para seguir

- [[cosmoSys]] — presentación general del producto.

- [[csys-req:cosmoSys-Req]] — gestión de requisitos sobre cosmoSys.

- [[csys-req:Guía funcional de cosmoSys-Req]] — conceptos y comportamiento específicos de requisitos.

- [Cosmobots](https://cosmobots.eu/) — la asociación sin ánimo de lucro que impulsa el proyecto.