Seguimiento · todos los estados

Documento del Design System para el servicio público Seguimiento de documentos (repo follow-up, la consulta de trámite de Mesa de Partes). Equivale a «Verifica · todos los estados» y se apoya en el patrón común de servicios-publicos.md. Los mockups de este documento están en app/docs/mockups/seguimiento-estados.html (copia en follow-up/docs/mockups/): muestran cada estado en escritorio y móvil, claro y oscuro, con una demostración interactiva. Los ejemplos son de demostración; la aplicación real puede revisarse con datos de prueba (§7).

Estado de la integración (30/10/2026): la interfaz está lista para el backend. Lo que consume ya existe en follow-up/server (años, acceso con verificación, seguimiento) y se verificó con él; lo que se propone al servicio está marcado como Por acordar (§6). Los estados que solo existen con datos de prueba no se presentan como integrados.

1. Dos clases de estado: no se mezclan

Clase	Qué dice	Dónde se define
Estado de la consulta (técnico)	Qué pasó con la petición: verificando, no encontrado, límite de consultas, sin conexión…	Interfaz y respuesta HTTP del servicio. No dice nada del trámite.
Estado del trámite (administrativo)	Dónde está el documento en el flujo real del SGD.	Catálogos de la base (`MAE_TRAMIT_STATUS`, `TRS_DERIVATION.STATUS`, `TRD_DOCUMENT.STATUS`); el servicio entrega texto y color y la interfaz los muestra tal cual.

1.1 Estados del trámite (administrativos)

Conjunto	Estados que ve la persona	Origen en el SGD
Solicitud en Mesa de Partes	No leído · Recibido · Observado (ronda N) · Subsanado (con su constancia) · Atendido	`TRS_EXTERNAL_REQUEST.STATUS`: EN_REGISTROS, PARA_VERIFICAR, OBSERVADO, SUBSANADO, REGISTRADO; texto y color del catálogo. Los tres primeros se muestran con el estado equivalente del ciudadano. ANULADO no es público (responde «No encontrado»).
Derivación a una oficina	No leído · Recibido · Atendido · Archivado · Observado · Anulado · Externo	`TRS_DERIVATION.STATUS` (pending, received, attended, archived, observed, annulled); un destino externo no tiene estado propio. Sin catálogo en la base: la interfaz rotula por código.
Documento de la cadena	En proyecto · Pend. V°B° · Pend. firma · Emitido · Enviado · Concluido · Anulado	`TRD_DOCUMENT.STATUS` (draft, PENDING_VB, PENDING_SIGN, signed, sent, done, annulled). Los borradores y anulados no salen, salvo el documento raíz. Flujo del documento administrativo: borrador → para despacho → firma → emite (no es visto bueno).
Resumen del trámite	El del catálogo (p. ej. Atendido, Recibido)	`MAE_TRAMIT_STATUS` + `CFG_TRAMIT_STATUS_DETAIL`
Indicadores derivados	Vencido · Reservado · Usted está aquí · Último movimiento · Pendiente de atención	Plazo y vencimiento; `IS_RESERVED`; posición en la cadena. Siempre con texto.

Hallazgo con datos reales (30/10/2026): el catálogo devuelve «No leido» sin tilde y «En Proyecto» con mayúscula; la interfaz muestra lo que entrega el catálogo, por lo que la corrección es de datos (ver pendiente PV-S1).

2. Reglas comunes de la consulta

Un solo envío a la vez. Una guarda interna descarta el segundo clic o Intro; el botón queda aria-disabled y el campo readOnly (no disabled) para no perder el foco. El token de Turnstile es de un solo uso y se descarta tras cada consulta.
Consulta repetida. El mismo número con su resultado en pantalla no se vuelve a pedir durante 30 s (constante REPEAT_QUERY_MS).
Tiempo máximo. 20 s en el navegador (QUERY_TIMEOUT_MS) y 15 s en el proxy de la aplicación; al vencer se ofrece «Reintentar».
Límite. 429 con Retry-After: cuenta regresiva visible, aviso fijo para lectores de pantalla.
Lo escrito se conserva ante cualquier error técnico.
Privacidad. Nombres de personas ofuscados por el servicio; destinos externos solo por tipo; documentos reservados con tipo, número, fecha y oficina; sin enlaces a documentos ni anexos; las notas de la observación no salen.
Textos en tipo oración, trato de «usted» y sin nombrar productos de terceros (por ejemplo, el sistema de identidad).
Accesibilidad (WCAG 2.2 AA). Etiquetas persistentes, errores identificados y sugeridos (3.3.1, 3.3.3), estados anunciados de forma cortés (4.1.3), foco gestionado (2.4.3), objetivos ≥ 24 px (2.5.8), sin desplazamiento horizontal a 320 px (1.4.10), color nunca solo (1.4.1), movimiento reducido (2.3.3). Lo no probado con lector de pantalla real y con teléfono físico se declara en §8.

3. Escenarios

A. Antes de consultar: formulario y verificación

1. Inicio

Formulario · id inicio

Aspecto	Detalle
Qué lo activa	Entrar a la página, o «Nueva consulta» desde un resultado (se conserva el año y el foco va al campo del número).
Qué ve la persona	Texto de presentación, tarjeta «Consulte su trámite» (año, número, verificación de seguridad, botón apagado), enlace «¿Dónde encuentro el número?» y la banda «Cómo consultar» (solo en este estado).
Mensaje exacto	Texto de estado: «Escriba el número y elija el año.»
Acciones	Escribir el número; elegir el año; abrir la ayuda; pegar «0000014-2026» completo (el número y el año se separan solos).
Validaciones	El botón queda apagado hasta tener número y año (o una constancia completa) y la verificación de seguridad. Al salir del campo, «14» se completa a «0000014».
Recuperación	No aplica.
Respuesta esperada del servicio	`GET /api/public/seguimiento/years` → `200 { data: [2026] }` (60 por minuto por IP). Si falla, ver «Años no cargados».
Accesibilidad	Etiquetas persistentes sobre cada campo; el botón apagado se acompaña de un texto de estado que dice qué falta (3.3.2, 4.1.3).

2. Ayuda: ¿Dónde encuentro el número?

Formulario · id ayuda

Aspecto	Detalle
Qué lo activa	Pulsar el enlace «¿Dónde encuentro el número?».
Qué ve la persona	Diálogo del SGD (escritorio) u hoja inferior (celular) con una constancia de ejemplo y los dos datos marcados: la constancia (MP-000031-2026) y el número de emisión (0000014-2026). Tres pasos en texto.
Mensaje exacto	«¿Dónde encuentro el número?» · «Ejemplo ilustrativo: los datos de la hoja no corresponden a un documento real.»
Acciones	Cerrar con «Cerrar», la X o la tecla Esc; el foco vuelve al enlace.
Validaciones	No aplica.
Recuperación	No aplica.
Respuesta esperada del servicio	Ninguna.
Accesibilidad	Diálogo modal con foco atrapado y nombre accesible; la ilustración es decorativa (`aria-hidden`) y la explicación equivalente está en texto.

3. Constancia incompleta

Formulario · id incompleto

Aspecto	Detalle
Qué lo activa	Escribir una constancia («MP-0003») y salir del campo sin completarla.
Qué ve la persona	Campo con borde rojo, mensaje con icono bajo el campo y selector de año apagado (la constancia ya incluye el año). El botón sigue apagado.
Mensaje exacto	«La constancia está incompleta. Escríbala completa, como MP-000031-2026.»
Acciones	Completar la constancia.
Validaciones	Constancia válida: `MP`, guion opcional, de 1 a 10 dígitos, guion y año de 4 dígitos. El servicio también acepta «mp-31-2026» y «MP31-2026».
Recuperación	El mensaje desaparece al volver a escribir y reaparece al salir del campo si sigue incompleta.
Respuesta esperada del servicio	Ninguna: es una validación del navegador. Si el servicio rechaza el formato responde `400` (ver «Número no válido»).
Accesibilidad	`role="alert"`, `aria-invalid` y `aria-describedby` enlazan el error con el campo (3.3.1, 3.3.3). El rojo siempre va con icono y texto (1.4.1).

4. Caracteres no admitidos

Formulario · id formato

Aspecto	Detalle
Qué lo activa	Escribir letras en el número de emisión («12ab»), más de 7 dígitos, o símbolos distintos de MP, dígitos y guiones en una constancia.
Qué ve la persona	El campo conserva lo válido y aparece una nota bajo el campo que explica qué se descartó, en lugar de borrar en silencio.
Mensaje exacto	«El número de emisión solo lleva dígitos. Si es una constancia, escríbala como MP-000031-2026.» · «El número de emisión tiene como máximo 7 dígitos.» · «La constancia solo lleva las letras MP, dígitos y guiones: MP-000031-2026.»
Acciones	Seguir escribiendo; la nota se quita con la siguiente tecla válida.
Validaciones	Número de emisión: solo dígitos, hasta 7. Constancia (empieza con «M»): mayúsculas, dígitos y guiones, hasta 20 caracteres.
Recuperación	Automática al corregir.
Respuesta esperada del servicio	Ninguna.
Accesibilidad	`role="status"` (anuncio no interrumpe). La nota no pinta el campo como inválido: el valor que queda es correcto.

5. Verificación de seguridad pendiente

Estado de la consulta · id seguridad-pendiente

Aspecto	Detalle
Qué lo activa	Número y año completos, pero la verificación de Cloudflare Turnstile aún no termina.
Qué ve la persona	Botón apagado y texto de estado «Complete la verificación de seguridad para continuar.»
Mensaje exacto	«Complete la verificación de seguridad para continuar.»
Acciones	Completar la verificación (suele resolverse sola en instantes).
Validaciones	El envío exige un token vigente de Turnstile.
Recuperación	El botón se activa solo al llegar el token.
Respuesta esperada del servicio	Ninguna hasta el envío; el token viaja en `POST …/access` y el servicio lo valida con Cloudflare.
Accesibilidad	El texto de estado es `aria-live="polite"`. Pendiente de probar con lector de pantalla real y con el modo «interactivo» del widget (3.3.8).

6. Verificación de seguridad vencida

Estado de la consulta · id seguridad-vencida

Aspecto	Detalle
Qué lo activa	El token de Turnstile vence antes de enviar (Cloudflare los vence a los 300 s).
Qué ve la persona	El widget muestra que venció, el botón vuelve a apagarse y el texto de estado lo dice.
Mensaje exacto	«La verificación de seguridad venció. Complétela de nuevo para continuar.»
Acciones	Completar de nuevo la verificación.
Validaciones	Un token vencido no se envía.
Recuperación	Turnstile renueva el widget; al llegar el nuevo token el botón se activa. Lo escrito se conserva.
Respuesta esperada del servicio	Ninguna (ocurre en el navegador).
Accesibilidad	Texto de estado anunciado de forma cortés (4.1.3). Tiempo suficiente para completar el formulario antes del vencimiento (2.2.1): se informa, no se pierde lo escrito.

7. Verificación de seguridad fallida

Estado de la consulta · id seguridad-fallida

Aspecto	Detalle
Qué lo activa	El widget de Turnstile falla o no carga (extensión que bloquea contenido, CSP, falta de clave), o el servicio responde `403` al validar el token.
Qué ve la persona	Alerta roja con título, causa probable y la acción «Reintentar verificación».
Mensaje exacto	«No se pudo completar la verificación de seguridad» · «Inténtelo otra vez. Si usa un bloqueador de contenido, desactívelo para este sitio.»
Acciones	«Reintentar verificación» reinicia el widget (el token es de un solo uso).
Validaciones	No se envía nada sin token válido.
Recuperación	Reiniciar el widget; si el bloqueo persiste, desactivar el bloqueador para este sitio.
Respuesta esperada del servicio	`POST /api/public/seguimiento/:number/access` con `{ turnstileToken }` (20 por minuto por IP). → `403` («No se pudo validar el captcha») cuando Cloudflare rechaza el token. Si el servicio de Cloudflare no responde, el servicio devuelve `502` y la interfaz lo trata como «Servicio no disponible».
Accesibilidad	`role="alert"`; el icono y el título nombran el problema sin depender del color.

8. Consulta en proceso y prevención de duplicados

Estado de la consulta · id proceso

Aspecto	Detalle
Qué lo activa	Enviar la consulta con todo válido.
Qué ve la persona	Botón «Consultando…» apagado, campo de solo lectura, esqueleto decorativo de la respuesta y texto de estado. No se muestran instrucciones ni errores.
Mensaje exacto	«Estamos buscando el recorrido. No cierre esta página.»
Acciones	Esperar. No hay botón de cancelar.
Validaciones	Un solo envío a la vez: una guarda interna descarta el segundo clic o Intro. El botón queda `aria-disabled` (no `disabled`) y el campo `readOnly`, para no perder el foco. El token se descarta después de cada consulta.
Recuperación	Si pasan 20 s sin respuesta, ver «Tiempo agotado».
Respuesta esperada del servicio	`POST /api/public/seguimiento/:number/access` con `{ turnstileToken }` (20 por minuto por IP). y luego `GET /api/public/seguimiento/:number?access=…` (60 por minuto por IP). Tiempo máximo: 20 s en el navegador y 15 s en el proxy de la aplicación.
Accesibilidad	El esqueleto es `aria-hidden`; el aviso «Consultando…» lo lee la tecnología de apoyo. Animación detenida con movimiento reducido (2.3.3).

9. Consulta repetida con el resultado en pantalla

Estado de la consulta · id repetida

Aspecto	Detalle
Qué lo activa	Enviar el mismo número mientras su resultado sigue visible, dentro de los 30 s siguientes.
Qué ve la persona	No se hace otra petición: el texto de estado avisa que ya está viendo ese seguimiento y el foco va al título del resultado.
Mensaje exacto	«Ya está viendo el seguimiento de este número. Podrá consultarlo de nuevo en unos segundos.»
Acciones	Esperar 30 s y volver a consultar para actualizar, o usar «Nueva consulta».
Validaciones	Misma consulta normalizada (número y año, o constancia) en menos de 30 s. Pasado el tiempo se vuelve a consultar, porque el trámite pudo cambiar.
Recuperación	No aplica.
Respuesta esperada del servicio	Ninguna. La protección real contra abuso es el límite del servicio (ver «Límite de consultas»).
Accesibilidad	Estado anunciado de forma cortés y foco al resultado (2.4.3, 4.1.3).

B. Resultado: estados del trámite y de la cadena de documentos

10. Trámite encontrado: recorrido completo

Estado del trámite · id encontrado

Aspecto	Detalle
Qué lo activa	Consulta con un número existente (aquí, la constancia de una subsanación).
Qué ve la persona	Tarjeta con número de emisión y estado del catálogo, resumen (recibido, oficina de recepción, estado del trámite, dónde se encuentra) y tres vistas: «Recorrido», «Relaciones entre documentos» y «Tabla» (solo en pantallas anchas). Botón «Nueva consulta» en la tarjeta.
Mensaje exacto	Aviso: «La constancia MP-000052-2026 es de una subsanación de este documento: se mantiene el número de emisión 0000014-2026.»
Acciones	Cambiar de vista con las flechas, Inicio y Fin; mostrar los destinos restantes; «Nueva consulta» (vacía el número, conserva el año y lleva el foco al campo).
Validaciones	Nombres de personas ya ofuscados por el servicio («J* P* R***»); destinos externos solo por tipo; sin enlaces a documentos ni anexos.
Recuperación	No aplica.
Respuesta esperada del servicio	`GET /api/public/seguimiento/:number?access=…` (60 por minuto por IP). → `200 { data: Tracking }` con `stages`, `nodes`, `status` y colores del catálogo.
Accesibilidad	Al aparecer, el foco va al título del resultado y se desplaza a la vista. Pestañas WAI-ARIA. Cada color va con texto.

11. Recién recibido: aún sin movimientos

Estado del trámite · id recien-recibido

Aspecto	Detalle
Qué lo activa	El trámite existe pero Mesa de Partes todavía no lo registra ni lo deriva (estado del catálogo «No leído»/«Recibido», sin etapa «Registrado»).
Qué ve la persona	Solo la etapa de recepción y un aviso informativo (no es un error ni una demora). No se dibuja el bloque «En el ministerio».
Mensaje exacto	«Su documento fue recibido y aún no tiene movimientos en el ministerio» · «El recorrido aparecerá aquí cuando Mesa de Partes lo registre y lo derive. Puede volver a consultar más tarde con el mismo número.»
Acciones	Volver a consultar más tarde con el mismo número.
Validaciones	Se decide con los datos: etapas sin «Registrado» y sin observación pendiente.
Recuperación	Volver a consultar.
Respuesta esperada del servicio	`200` con `stages: [received]` y un solo `node` raíz sin `recipients` (es el caso real del servicio: el documento raíz aparece como «En proyecto»; ver pendiente PV-S2).
Accesibilidad	Aviso de texto con icono; no depende del color.

12. Observado: espera su subsanación

Estado del trámite · id observado

Aspecto	Detalle
Qué lo activa	Mesa de Partes observó la solicitud (estado «Observado»).
Qué ve la persona	Etapas hasta «Observado» con su ronda, la indicación de que las observaciones se ven en la casilla y una línea que explica que el número de emisión se mantiene al subsanar.
Mensaje exacto	«Las observaciones las ve en su casilla electrónica, con sesión.» · «La solicitud espera su subsanación; al presentarla se mantiene el mismo número de emisión.»
Acciones	Ir a la casilla electrónica (con sesión) para ver las observaciones.
Validaciones	Las notas de la observación nunca salen por esta consulta pública.
Recuperación	Subsanar desde la casilla; la nueva constancia lleva al mismo trámite.
Respuesta esperada del servicio	`200` con etapas `received`, `verifying` y `observed` (`round`); sin notas.
Accesibilidad	Texto con la causa y el siguiente paso; el color amarillo acompaña a la palabra «Observado».

13. Registrado, sin derivaciones todavía

Estado del trámite · id sin-derivaciones

Aspecto	Detalle
Qué lo activa	La solicitud ya fue registrada pero ninguna oficina la recibió (sin `recipients`).
Qué ve la persona	Historial de Mesa de Partes y, en «En el ministerio», el documento raíz con la línea «Este documento todavía no tiene derivaciones.» También en la vista «Tabla» y en el detalle del documento.
Mensaje exacto	«Este documento todavía no tiene derivaciones.»
Acciones	Cambiar de vista; volver a consultar más tarde.
Validaciones	Historial vacío no es error: se dice lo que falta.
Recuperación	No aplica.
Respuesta esperada del servicio	`200` con `stages` hasta `registered` y un `node` raíz con `recipients: []`.
Accesibilidad	Texto plano, sin depender de iconos.

14. Muchas derivaciones, documentos reservados y cadena recortada

Estado del trámite · id muchas-derivaciones

Aspecto	Detalle
Qué lo activa	Un documento se deriva a muchas oficinas, la cadena incluye documentos reservados o supera el tope de 300 documentos.
Qué ve la persona	Se muestran 5 destinos con «Mostrar los N restantes»; en el detalle, filtro por estado y filas que se expanden. Los reservados conservan su lugar con tipo, número, fecha y oficina. La cadena recortada se avisa.
Mensaje exacto	«Algunos documentos de la cadena son reservados: se muestra su lugar con tipo, número, fecha y oficina.» · «Se muestran los movimientos más recientes de la cadena.»
Acciones	Mostrar los restantes; filtrar por estado; expandir o contraer todo.
Validaciones	Un documento reservado nunca muestra asunto, autor, expediente, destinatarios, vistos buenos ni citas. El documento raíz no puede ser reservado (se responde «No encontrado»).
Recuperación	No aplica.
Respuesta esperada del servicio	`200` con `truncated: true` y nodos con `restricted: true` (campos sensibles vacíos).
Accesibilidad	«Mostrar los N restantes» es un botón con el texto completo; los destinos se expanden con `aria-expanded`.

15. Datos parciales y textos extensos

Estado del trámite · id parcial

Aspecto	Detalle
Qué lo activa	El servicio entrega campos vacíos (oficina, fechas, estado del trámite) o textos muy largos (asunto, oficinas, motivos).
Qué ve la persona	Los datos ausentes se muestran como «—» y la tecnología de apoyo lee «Sin dato». Los textos largos se parten en varias líneas sin ensanchar la página. En las filas del árbol, el texto cortado muestra el completo en su ayuda.
Mensaje exacto	«Sin dato» (solo para lectores de pantalla) · «—» (visible).
Acciones	Leer el detalle del documento para ver los textos completos.
Validaciones	Ningún campo ausente rompe la tarjeta; la interfaz no inventa valores.
Recuperación	No aplica.
Respuesta esperada del servicio	`200` con cadenas vacías u omitidas (`omitempty`) en fechas y nombres.
Accesibilidad	El guion no es el único aviso: `sr-only` «Sin dato». Sin desplazamiento horizontal a 320 px (1.4.10).

16. Detalle de un documento y retorno a la cadena

Estado de la consulta · id detalle

Aspecto	Detalle
Qué lo activa	En «Relaciones entre documentos», elegir un documento de la cadena.
Qué ve la persona	Escritorio: cadena a la izquierda y detalle a la derecha. Celular: el detalle reemplaza a la cadena y arriba aparece «← Volver a la cadena». Un documento reservado solo muestra tipo, número, fecha y oficina.
Mensaje exacto	«Volver a la cadena» · «Algunos documentos de la cadena son reservados: se muestra su lugar con tipo, número, fecha y oficina.»
Acciones	Elegir documentos; «Volver a la cadena» (celular); «Usted está aquí» y «Último» saltan a esos documentos; «Nueva consulta» en la tarjeta del resultado.
Validaciones	El foco pasa al detalle al elegir (celular) y regresa al documento elegido al volver; nunca queda en un elemento oculto.
Recuperación	No aplica.
Respuesta esperada del servicio	Ninguna: usa los datos de la consulta ya recibida.
Accesibilidad	Región «Detalle del documento» con foco programático; botón de 36 px mínimo (objetivo ≥ 24 px, 2.5.8); orden de foco coherente (2.4.3).

17. Trámite concluido

Estado del trámite · id concluido

Aspecto	Detalle
Qué lo activa	El documento fue atendido y archivado (documento «Concluido», derivación «Archivado», con fecha de cierre).
Qué ve la persona	Recorrido completo con la derivación archivada y el último movimiento; el estado del trámite en el resumen.
Mensaje exacto	Estados con el texto y el color del catálogo («Atendido», «Archivado», «Concluido»).
Acciones	Revisar el recorrido; «Nueva consulta».
Validaciones	El estado «Anulado» de la solicitud no es público: responde «No encontrado».
Recuperación	No aplica.
Respuesta esperada del servicio	`200` con `closedAt` y derivaciones `archived`.
Accesibilidad	Cada estado con texto; el punto de color es decorativo.

C. Problemas de la consulta: errores, límites y recuperación

18. Documento no encontrado

Estado de la consulta · id no-encontrado

Aspecto	Detalle
Qué lo activa	El servicio responde `404`.
Qué ve la persona	Alerta roja con título, tres cosas que revisar y la acción «Corregir el número»; campo marcado como no válido. Se ocultan la ilustración y «Cómo consultar».
Mensaje exacto	«No encontramos un documento con ese número» · «Revise estos datos e inténtelo otra vez:» · «Que el año elegido sea el del cargo de Mesa de Partes.» · «Que escribió el número de emisión (por ejemplo 0000014) o la constancia completa (MP-000031-2026).» · «Solo se pueden consultar los documentos presentados en Mesa de Partes.»
Acciones	«Corregir el número» (lleva el foco al campo).
Validaciones	A propósito no se distingue entre número inexistente, documento no ingresado por Mesa de Partes, reservado, eliminado o solicitud anulada: así no se revela su existencia.
Recuperación	Corregir el número o el año y volver a consultar.
Respuesta esperada del servicio	`POST /api/public/seguimiento/:number/access` con `{ turnstileToken }` (20 por minuto por IP). → `404` «Documento no encontrado».
Accesibilidad	`role="alert"`, `aria-invalid` y descripción enlazada al campo; el borde rojo va con icono y texto.

19. Número no válido (respuesta del servicio)

Estado de la consulta · id invalido

Aspecto	Detalle
Qué lo activa	El servicio responde `400` (el formato que pasó la validación del navegador no lo acepta).
Qué ve la persona	Alerta roja «El número no es válido» con un ejemplo de cada formato y «Corregir el número».
Mensaje exacto	«El número no es válido» · «Use el número de emisión (0000014) con su año o una constancia como MP-000031-2026.»
Acciones	«Corregir el número».
Validaciones	El servicio es la autoridad del formato (`NormalizeQuery`).
Recuperación	Corregir y volver a consultar.
Respuesta esperada del servicio	`POST /api/public/seguimiento/:number/access` con `{ turnstileToken }` (20 por minuto por IP). → `400` «Número de emisión o constancia no válido».
Accesibilidad	Igual que «No encontrado».

20. Acceso vencido

Estado de la consulta · id acceso-vencido

Aspecto	Detalle
Qué lo activa	El servicio responde `403` al leer el seguimiento: el token de acceso (vigencia de 30 minutos) venció o no corresponde al número.
Qué ve la persona	Alerta ámbar «La consulta venció» con «Consultar de nuevo»; el número sigue escrito.
Mensaje exacto	«La consulta venció» · «Por seguridad, el acceso al seguimiento dura poco tiempo. Su número sigue escrito: vuelva a consultar.»
Acciones	«Consultar de nuevo»: renueva la verificación y reenvía la consulta sola.
Validaciones	El token se pide por número y se usa de inmediato; en el flujo actual este caso es poco probable y se cubre por si cambia la vigencia o hay un reloj desfasado.
Recuperación	Un clic.
Respuesta esperada del servicio	`GET /api/public/seguimiento/:number?access=…` (60 por minuto por IP). → `403` «Acceso no autorizado o vencido».
Accesibilidad	`role="alert"`; texto de estado «Reintentando en cuanto termine la verificación de seguridad.» durante el reintento.

21. Límite de consultas

Estado de la consulta · id limite

Aspecto	Detalle
Qué lo activa	El servicio responde `429` (20 consultas por minuto por conexión al canjear el acceso; 60 al leer).
Qué ve la persona	Alerta ámbar con cuenta regresiva visible y el botón apagado hasta que termine; sin acción, se resuelve esperando. Al terminar el texto de estado dice que ya puede consultar y el botón se activa.
Mensaje exacto	«Hay muchas consultas desde su conexión» · «Espere un momento e inténtelo de nuevo. Su número sigue escrito.» · «Podrá consultar de nuevo en N s.» · estado: «Podrá consultar de nuevo cuando termine la espera.» y luego «Ya puede consultar de nuevo.»
Acciones	Esperar; después, «Consultar seguimiento».
Validaciones	La espera sale del encabezado `Retry-After` (si no llega, 30 s; máximo 120 s). El conteo es visual: la tecnología de apoyo recibe un aviso fijo, no uno por segundo.
Recuperación	Automática al terminar la espera. El número y el año se conservan.
Respuesta esperada del servicio	`429` con cuerpo de texto «Too Many Requests» y `Retry-After: N` (comprobado el 30/10/2026). La aplicación reenvía `Retry-After` al navegador.
Accesibilidad	El tiempo de espera es informativo y no expira la sesión (2.2.1); el aviso cortés evita saturar al lector de pantalla.

22. Servicio no disponible

Estado de la consulta · id no-disponible

Aspecto	Detalle
Qué lo activa	El servicio responde `5xx` (incluido `502` por la verificación) o no se puede llegar a él.
Qué ve la persona	Alerta ámbar «El servicio de seguimiento no está disponible por ahora» con «Reintentar». Aclara que no depende del número y lo conserva.
Mensaje exacto	«El servicio de seguimiento no está disponible por ahora» · «Esto no depende del número que ingresó, que sigue escrito. Inténtelo de nuevo en unos minutos.»
Acciones	«Reintentar»: reutiliza la verificación vigente o espera la siguiente y consulta sola.
Validaciones	No se culpa a la persona: el mensaje dice que el problema no es del número.
Recuperación	Reintentar ahora o más tarde.
Respuesta esperada del servicio	Cualquier `5xx`. La aplicación responde `503` con `{ error: { message } }` si el servicio no contesta.
Accesibilidad	`role="alert"`; icono, título y texto nombran el problema.

23. Tiempo agotado

Estado de la consulta · id tiempo-agotado

Aspecto	Detalle
Qué lo activa	El navegador espera más de 20 s, o el servicio (o el proxy, a los 15 s) responde `504`.
Qué ve la persona	Alerta ámbar «La consulta tardó más de lo esperado» con «Reintentar».
Mensaje exacto	«La consulta tardó más de lo esperado» · «No pudimos obtener la respuesta a tiempo. Su número sigue escrito: puede reintentar.»
Acciones	«Reintentar».
Validaciones	La consulta en curso se cancela al vencer el tiempo.
Recuperación	Reintentar con un clic.
Respuesta esperada del servicio	`504` del proxy o corte de la conexión.
Accesibilidad	Igual que «Servicio no disponible».

24. Sin conexión a internet

Estado de la consulta · id sin-conexion

Aspecto	Detalle
Qué lo activa	El navegador no tiene red al enviar (`navigator.onLine` es falso).
Qué ve la persona	Alerta ámbar «No hay conexión a internet» con «Reintentar». Al volver la red, el aviso se quita y el texto de estado dice «Se restableció la conexión. Puede volver a consultar.».
Mensaje exacto	«No hay conexión a internet» · «Revise su conexión. Cuando vuelva, podrá reintentar; su número sigue escrito.» · al volver: «Se restableció la conexión. Puede volver a consultar.»
Acciones	«Reintentar» o esperar a que vuelva la red.
Validaciones	Lo escrito se conserva.
Recuperación	Automática: el evento `online` limpia el aviso.
Respuesta esperada del servicio	Ninguna (la petición no sale del navegador).
Accesibilidad	El aviso de red restablecida es un estado cortés (4.1.3).

25. Reintento en curso

Estado de la consulta · id reintentando

Aspecto	Detalle
Qué lo activa	Pulsar «Reintentar» (o «Consultar de nuevo») cuando aún no hay una verificación vigente.
Qué ve la persona	El aviso de error se quita, el widget se renueva y el texto de estado dice que se reintentará en cuanto termine la verificación; al llegar el token la consulta se envía sola.
Mensaje exacto	«Reintentando en cuanto termine la verificación de seguridad.»
Acciones	Esperar.
Validaciones	Un único reintento pendiente; no se envía si el número dejó de ser válido.
Recuperación	Si falla otra vez, vuelve el aviso que corresponda.
Respuesta esperada del servicio	Ver «Consulta en proceso».
Accesibilidad	Estado cortés; el foco no se mueve.

26. Años no cargados

Estado de la consulta · id anios

Aspecto	Detalle
Qué lo activa	Falla la carga del selector de años al abrir la página.
Qué ve la persona	Mensaje bajo el campo con el botón «Reintentar»; la constancia (que ya incluye el año) sigue siendo utilizable.
Mensaje exacto	«No se pudieron cargar los años. Reintentar»
Acciones	«Reintentar» vuelve a pedir los años.
Validaciones	Sin años no se puede enviar un número de emisión.
Recuperación	Reintentar o usar la constancia.
Respuesta esperada del servicio	`GET /api/public/seguimiento/years` → `200 { data: [2026] }` (60 por minuto por IP). → `5xx`.
Accesibilidad	`role="alert"`; botón con texto visible.

4. Componentes y archivos

Pieza	Archivo (`follow-up/app/src/`)
Pantalla y flujo de la consulta	`components/seguimiento/seguimiento-app.tsx`
Mensajes técnicos, de campo, de estado y de resultado	`features/seguimiento/messages.ts`
Cliente de la API con errores tipados (`RateLimitError`, `AccessExpiredError`, `ServiceUnavailableError`, `QueryTimeoutError`, `OfflineError`)	`features/seguimiento/api.ts`
Constantes (modo de prueba, tiempos)	`features/seguimiento/config.ts`
Resultado, recorrido y cadena	`components/seguimiento/{tracking-result,route-timeline,tracking-tree,derivations-table}.tsx`
Proxy con `Retry-After` y errores 503/504	`app/api/public/seguimiento/[...path]/route.ts`
Datos y herramientas de prueba	`features/seguimiento/mock/fixtures.mock.ts`, `components/seguimiento/mock-tools.tsx`

Se reutilizan los componentes del Design System (cabecera de 80 px, campos de 52 px con sgd-field-focus, Select, diálogo y hoja inferior, insignias Pill/StatusBadge); no se crearon controles nuevos fuera de mock-tools.tsx, que solo existe en modo de prueba.

5. Sustento normativo

Regla general de AGENTS.md («Sustento normativo de requerimientos y formularios»): se cita solo lo verificado; el resto queda como pendiente.

Tema	Norma y artículo	Qué exige	Estado
Acceso del administrado a conocer su trámite	TUO de la Ley 27444 (DS 004-2019-JUS), art. 171.1	Acceso al expediente en cualquier momento de su trámite	Fuente secundaria (citado en resoluciones del TTAIP); contrastar con el texto oficial
Derecho a ser informado del estado (art. 66)	TUO de la Ley 27444, art. 66	—	No verificado el 30/10/2026: no se cita hasta leer el texto oficial
Documentos reservados o confidenciales	TUO de la Ley 27806 (DS 021-2019-JUS), excepciones al acceso	Información reservada o confidencial no se entrega	Oficial (ver documento central); artículo exacto por precisar con OGAJ
Datos personales mínimos (nombres ofuscados, sin domicilio ni documento)	Ley 29733 (principios de finalidad y proporcionalidad) y DS 016-2024-JUS	Tratar solo lo necesario para la finalidad	Por contrastar en texto oficial; criterio funcional vigente
Mensajes de estado, errores, foco y objetivos	WCAG 2.2: 1.4.1, 1.4.10, 2.2.1, 2.3.3, 2.4.3, 2.5.8, 3.3.1, 3.3.2, 3.3.3, 3.3.8, 4.1.3	Nivel A y AA obligatorio (estándar institucional)	Oficial (W3C); verificación con tecnología de apoyo real pendiente

Tipos: los textos y la estructura de cada estado son UX y funcionales; solo la reserva de documentos y la protección de datos tienen sustento legal, y su alcance exacto en una consulta pública sin identificación es una interpretación pendiente (§8, PV-S3).

6. Contrato con el servicio

Resumen de lo que la interfaz consume y espera. El detalle está en docs/normativa/consultas/CONTRATO-API-FRONTEND-CASILLA-VERIFICA.md (§5).

Llamada	Respuestas que la interfaz maneja
`GET /api/public/seguimiento/years` (60/min)	`200 { data: number[] }`; cualquier otra → «Años no cargados»
`POST /api/public/seguimiento/:number/access` (20/min)	`200 { data: { accessToken, expiresAt } }`; `400` número no válido; `403` verificación rechazada; `404` no encontrado; `429` + `Retry-After`; `502` y `5xx` no disponible; `504` tiempo agotado
`GET /api/public/seguimiento/:number?access=…` (60/min)	`200 { data: Tracking }`; `403` acceso vencido; `404` no encontrado; `429`; `5xx`; `504`

Por acordar con el servicio (no existe hoy; la interfaz ya funciona sin ello):

Cuerpo JSON uniforme en el 429 ({ error: { message, retryAfter } }); hoy es texto plano con Retry-After.
Un campo opcional partial o unavailableSections en Tracking si alguna parte del recorrido no se puede leer (hoy se deduce de los datos).
Corregir el texto de los catálogos («No leido», «En Proyecto») en la base.

7. Datos de prueba

NEXT_PUBLIC_SEGUIMIENTO_MOCK=true cambia la aplicación así: no llama al servicio ni a Cloudflare, muestra la franja «Datos de prueba», usa un captcha simulado (con «Simular vencimiento» y «Simular fallo») y lista los casos. Nunca se enciende en producción y no se presenta como integración.

Número de prueba	Caso	Debe verse
`0000014-2026`	Recorrido completo	Observación y subsanación, dos destinos, un documento reservado y uno vencido.
`MP-000052-2026`	Constancia de subsanación	Mismo trámite; aviso de que la constancia es de una subsanación.
`0000015-2026`	Recién recibido	Solo «Recibido»; aviso de que aún no hay movimientos en el ministerio.
`0000016-2026`	Observado	La solicitud espera su subsanación; las observaciones se ven en la casilla.
`0000017-2026`	Registrado sin derivaciones	Recorrido en el ministerio sin destinos todavía.
`0000018-2026`	Muchos destinos y reservados	Nueve destinos con filtro, documentos reservados y cadena recortada.
`0000019-2026`	Datos parciales y textos extensos	Campos sin dato con «—», asunto y nombres largos sin romper el diseño.
`0000020-2026`	Trámite concluido	Derivación archivada y fecha de cierre.
`0000404-2026`	No encontrado	Mensaje «No encontramos un documento…» con la lista de revisión.
`0000400-2026`	Número no válido (servicio)	Mensaje «El número no es válido».
`0000403-2026`	Verificación rechazada	«No se pudo completar la verificación de seguridad».
`0000401-2026`	Acceso vencido	«La consulta venció»; vuelve a consultar.
`0000429-2026`	Límite de consultas	«Hay muchas consultas…» con espera de 15 s.
`0000503-2026`	Servicio no disponible	Aviso ámbar con «Reintentar»; el número se conserva.
`0000504-2026`	Tiempo agotado	«La consulta tardó más de lo esperado».
`0000505-2026`	Sin conexión	«No hay conexión a internet».
`0000500-2026`	Falla y se recupera	La primera consulta falla; «Reintentar» muestra el recorrido.

8. Verificación y pendientes

Verificado el 30/10/2026: compilación de tipos y ESLint sin errores nuevos; en modo de prueba, cada caso de §7 con su mensaje, el reintento con un clic (0000500), la cuenta regresiva del límite, la guarda contra el doble envío, la consulta repetida, el foco al resultado, a «Volver a la cadena» y a «Nueva consulta», y la ausencia de desplazamiento horizontal a 375 px con textos extensos. Contra el servicio real (puerto 8087): años, acceso, seguimiento, 404 y 429 con Retry-After (la respuesta es texto plano).

No probado: lector de pantalla real (NVDA, JAWS, VoiceOver, TalkBack); teléfono físico; el widget real de Turnstile en modo interactivo (3.3.8); contraste medido con herramienta en los seis temas; capturas de pantalla (la ventana de revisión estaba minimizada, se comprobó por DOM).

ID	Pendiente de validación	Área
PV-S1	Corregir en el catálogo «No leido» → «No leído» y «En Proyecto» → «En proyecto» (tipo oración).	OGTI/ODSI (datos)
PV-S2	Si la persona debe ver «En proyecto» en el documento raíz de una solicitud recién recibida (hoy es el estado real de la hoja de envío). Propuesta: mostrar solo el estado de la solicitud mientras no se registre.	OGAC / Mesa de Partes
PV-S3	Alcance de lo que se muestra sin identificar a la persona (oficinas, motivos, plazos): ¿equivale al acceso al expediente del art. 171 o es información general del trámite? Leer el texto oficial del TUO (arts. 66 y 171) y del TUO de la Ley 27806.	OGAJ / Oficial de Datos Personales
PV-S4	Vigencia del token de acceso (30 min) y límites por conexión (20 y 60 por minuto) frente al uso real.	OGTI
PV-S5	Cuerpo uniforme del `429` y señal de datos parciales (§6).	Backend (Miguel)