# Protocolos y su jerarquía

## La jerarquía

Todo lo que capturas cuelga de un **contexto** que Neurologyca asigna a tu organización. Dentro de él, un **protocolo** dice qué se mide y cuándo: una lista ordenada de **posiciones**, y cada una ejecuta una **mecánica** (el guion de una captura) hecha de **steps**.

**El catálogo** (Lo publica Neurologyca. Inmutable una vez publicado.)

1. **Tu organización**: Tu organización en Engine. *↓ tiene asignado*
2. **Contexto** (`context`): Un caso de uso. Decide en qué protocolos puedes inscribir. No públicas: sus **reglas** pueden ofrecer una mecánica como microintervención tras una captura. *↓ comparte*
3. **Grupo de protocolos** (`protocol_group`): Una familia de protocolos. Puede estar en varios contextos. *↓ agrupa*
4. **Protocolo** (`protocol`): Qué se mide y con qué frecuencia. *↓ en orden*
5. **Posición** (`protocol_mechanic`): Un hueco del protocolo: su orden y sus relojes (cuándo se puede capturar). *↓ ejecuta*
6. **Mecánica** (`mechanic`): El guion de una captura. *↓ hecha de*
7. **Steps** (`step`): Cada uno con su `step_type`, media y fases, más las instrucciones.

**Tus datos** (Por persona. Lo creas tú con la API.)

1. **Usuario**: Una persona de tu aplicación. Uno por persona: su **baseline**, común a todos los protocolos.
2. **Inscripción** (`userProtocolId`), es de un protocolo: Una persona en un protocolo.
3. **Captura de una posición** (`userProtocolId` + `protocolMechanicId`), es de una posición: Lo que la persona hace en una posición. Opcional: al completarse, Engine puede lanzar: **Interrupción** (`interruptionId`) → captura de la microintervención.
4. **Resultados por step**, uno por step: Los indicadores de cada step capturado.

| Nivel (nombre en la API) | Qué es | Qué decide |
| --- | --- | --- |
| `context` | Un caso de uso asignado a tu organización | En qué protocolos puedes inscribir a las personas, y si las capturas se pueden interpretar |
| `protocol_group` | Una familia de protocolos; puede estar en más de un contexto | En qué se fija la interpretación |
| `protocol` | Qué se mide y con qué frecuencia | Sus posiciones, en orden |
| `protocol_mechanic` (una **posición**) | Un hueco del protocolo | Cuándo se puede capturar: fecha, franja horaria y separación |
| `mechanic` | El guion de una captura | Sus steps, fijos o libres, y las pantallas que se muestran entre ellos |
| `step` (`step_type`) | Un estímulo o una tarea | Su tipo, la duración sugerida y lo que se muestra |

El whitepaper llama a la mecánica *mechanism*; la API dice `mechanic`. Ves un protocolo si alguno de los contextos de su grupo está asignado a tu organización. Un protocolo hecho para una sola organización solo lo ve e inscribe esa: para cualquier otra no existe (`404`).

## Si ningún contexto encaja

Tu organización ve los contextos que Neurologyca le asigna, y el catálogo crece. Si ninguno encaja con tu caso, puedes encargar uno; para medir sin contexto, usa [Measurement](/docs/es/guides/measurement/).

### Encarga un contexto

Si ninguno encaja, Neurologyca puede crear uno para tu caso. Cuéntanos qué quieres entender, en qué situación y para quién es la lectura. A partir de ahí:

1. Partimos de la literatura publicada sobre el tema y de lo que la captura puede medir de verdad.
2. Diseñamos el protocolo y decidimos a quién va dirigida la lectura, y lo revisamos todo contigo.
3. Lo asignamos a tu organización y lo integras como cualquier otro.

Siempre dentro del uso responsable: la lectura está pensada para acompañar a la persona y nunca debe usarse por sí sola para decidir sobre ella.

Para encargarlo, escribe al soporte de Neurologyca o habla con tu contacto en Neurologyca.

### Context Maker (En desarrollo)

Una herramienta que estamos desarrollando para crear un contexto a partir de tu caso. Contarás tu caso con tus palabras y te propondrá un contexto: qué medir, cómo pedírselo a la persona y para quién escribir la lectura, partiendo de la literatura publicada sobre el tema y de lo que la captura puede medir.

Si algo de lo que buscas todavía no se puede medir, te lo dirá y te propondrá qué puedes medir en su lugar.

También podrás pedir a Neurologyca que repase la propuesta contigo. Una propuesta no crea un contexto por sí sola: Neurologyca lo asigna, como cualquier otro.

## Catálogo y por persona

| Lo publica Neurologyca (catálogo) | Ocurre por persona (ejecución) |
| --- | --- |
| Contexto, grupo de protocolos, protocolo, posición, mecánica, step, media, instrucción | Usuario, baseline, inscripción, la captura de una posición, sus resultados |
| Las mecánicas que un contexto puede ofrecer como microintervenciones (las reglas que las ofrecen no son públicas) | Una interrupción (una oferta que ocurrió, anclada a la captura que la disparó) y la captura de su microintervención |

Del catálogo no defines nada: lo lees con `GET /catalog/*` e inscribes a las personas en él.

## Un protocolo de un vistazo

Un ejemplo sintético con tres posiciones y una microintervención. Abre una posición para ver sus steps. Si has iniciado sesión con un equipo, puedes cambiarlo por uno de los protocolos de tu organización: DevLab lo lee de tu catálogo, sin crear usuarios.

| Posición | Cuándo | Mecánica | Steps |
| --- | --- | --- | --- |
| 1 | En cualquier momento | Check-in | baseline_camera (duración libre), directed_question (duración libre), free_speech (opcional) |
| 2 | ≥ 24 h desde la captura anterior | Check-in | baseline_camera (duración libre), directed_question (duración libre), free_speech (opcional) |
| 3 | Día 7 ± 1 · 08:00–11:00 hora local | Check-in | baseline_camera (duración libre), directed_question (duración libre), free_speech (opcional) |

| Microintervención | Steps |
| --- | --- |
| Breathing reset | reset_breathing (duración libre · 3 ciclos) |

## Measurement, tal como lo devuelve Engine

El protocolo Measurement, desde `GET /user-protocols/{userProtocolId}/schema`: una posición, un step, en cualquier momento.

| Posición | Cuándo | Mecánica | Steps |
| --- | --- | --- | --- |
| 1 | En cualquier momento | Measurement | measurement_free (mín 6 s · sin máximo) |

## Qué ves en la API

| Quieres saber | Llamada |
| --- | --- |
| Tus contextos y protocolos | `GET /catalog/contexts`, `GET /catalog/protocols` |
| Las posiciones de una inscripción y cuál toca | `GET /user-protocols/{userProtocolId}` |
| El protocolo entero, con relojes y guiones | `GET /user-protocols/{userProtocolId}/schema` |
| El guion de una posición | `GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId}` |

```json
{
  "order": 1,
  "mechanic": {
    "name": "Measurement",
    "flowMode": "fixed",
    "steps": [
      {
        "order": 1,
        "type": "measurement_free",
        "minTimeSeconds": 6,
        "maxTimeSeconds": null,
        "optional": false
      }
    ]
  }
}
```

## Leer el catálogo

Tu backend lee el catálogo con tu key (el SDK de navegador nunca llama a estas rutas). Cada una devuelve solo lo asignado a tu organización, ordenado por `id`.

| Ruta | Devuelve |
| --- | --- |
| `GET /catalog/contexts` | Los contextos asignados a tu organización: los temas que agrupan tus protocolos |
| `GET /catalog/protocol_group` | Los grupos de protocolos de tus contextos, más el grupo del protocolo de baseline, que tienen todos. Ese grupo llega hoy con `interpreted: true`, pero no inscribes a nadie en él y no se interpreta por sí solo (ver [Baseline](/docs/es/concepts/baseline/)) |
| `GET /catalog/protocols` | Los protocolos en los que puedes inscribir personas; `hasSchedule: true` quiere decir que solo puede empezar por su primera posición, e `interpreted: false`, que `POST /analyze` responde `409 PROTOCOL_NOT_ANALYSED` (como con Measurement). Baseline también aparece, con `interpreted: true`, pero no inscribes personas en él |
| `GET /catalog/protocol_mechanic` | Las posiciones de cada protocolo (qué mecánica, en qué orden) con sus tres relojes |
| `GET /catalog/mechanics` | Las mecánicas de tus protocolos y las microintervenciones que pueden ofrecer tus contextos, cada una con `constellationSubcontextId` (su subcontexto de análisis, o `null`) |
| `GET /catalog/mechanics/{pid}` | Una mecánica con su guion completo, para una microintervención que tu propia app decide ofrecer |
| `GET /catalog/mechanic_step` | Qué tipo de step, en qué orden, forma cada mecánica |
| `GET /catalog/step_types` | Los tipos de step, con `minTimeSeconds` y `maxTimeSeconds`: los dos extremos de cada ventana de respuesta. Varios pueden compartir `type`: `current: true` marca el que está en uso |
| `GET /catalog/media` | Los textos, imágenes y vídeos de esos tipos de step |
| `GET /catalog/step_type_media` | Qué media va con cada tipo de step |

`@neurologyca/capture-server` lee seis de ellas a la vez con `listProtocolLibrary()`.

## Las posiciones y sus relojes

Una posición puede declarar tres relojes independientes; está disponible donde se solapan:

- **Fecha**: un día contado desde la primera captura completada del protocolo (o un día de la semana), con una tolerancia antes y después. Cuando esa ventana se cierra, la posición se pierde.
- **Franja horaria**: ventanas en el huso horario local de la persona (el `timezone` del usuario; si no tiene, uno por defecto del entorno).
- **Separación** (`timeBetweenSessionsSeconds`): un tiempo mínimo desde la captura anterior. Cuando los relojes se aplican, Engine mantiene además una separación mínima entre dos capturas del mismo protocolo, aunque la posición no declare ninguna; ese mínimo es un ajuste del entorno.

Un protocolo con `hasSchedule: true` declara una fecha o una franja horaria en al menos una posición, y hay que empezarlo por la posición 1. La separación no activa `hasSchedule` ni obliga al orden. Engine declara estos relojes y los comprueba al abrir una captura; que un fallo rechace la captura o solo quede registrado depende del entorno. [Sesiones, inscripciones e interrupciones](/docs/es/concepts/sessions/) muestra las respuestas.

## Steps, media e instrucciones

- `minTimeSeconds` y `maxTimeSeconds` son una guía para tu interfaz: Engine no los aplica, y a menudo vienen `null`.
- `presentationSeconds`, cuando viene, dice cuánto está pensada para mostrarse la pregunta del step; el visualizador lo pinta como «se muestra N s». También es una guía: el SDK te lo da (`PlanStep.presentationSeconds`) y no lo aplica.
- `media[]` lista lo que se puede mostrar en un step. Cuando muestras uno, envía su `pid` como `mediaId` con los lotes de ese step.
- `instructions[]` son pantallas que se muestran pero no se miden: `beforeStep` (con `step`) o `atEnd`.
- Un step `optional` se puede saltar. Un step cíclico (`rounds`, `phases`) sigue siendo una sola captura.
- `targetConstellationHciId` nombra en qué se fija la interpretación en ese step. El SDK lo llama igual, `PlanStep.targetConstellationHciId`.

## Microintervenciones

Un contexto también puede definir mecánicas cortas que Engine puede **ofrecer tras una captura completada**, como un ejercicio de respiración. No son posiciones de tu protocolo: la oferta llega como una **interrupción** de la captura que la disparó. Ver [Sesiones, inscripciones e interrupciones](/docs/es/concepts/sessions/#interrupciones-y-microintervenciones).

## Versiones

Los protocolos publicados nunca cambian: una edición crea una versión nueva. Un protocolo archivado se puede seguir inscribiendo, con un `protocolNotice` que apunta a su sustituto; uno obsoleto no admite inscripciones ni capturas nuevas.
