Entrada de lectura de documentos de requisitos en la página (visor)
Objetivo
Integrar en la interfaz del producto los documentos de requisitos ya existentes en el proyecto, permitiendo a los usuarios consultar la documentación correspondiente directamente en la página actual; al mismo tiempo, asegurar que la entrada no ralentice la carga inicial, no filtre contenido histórico ni exponga documentos internos accidentalmente en producción.
Límites con la redacción de documentos
- Este skill solo se encarga de implementar la entrada de lectura: ubicación de la entrada, mapeo de documentos, copia en compilación, renderizado, búsqueda, carga diferida, estados de error, superficies de exposición en producción, pruebas y revisión.
- El contenido de los documentos lo proporciona
prd-rule-authoringo cualquier otra fuente; este skill no dicta cómo deben escribirse los documentos ni exige que el proyecto useprd-rule-authoring. - Ambos son independientes: los proyectos sin entrada de lectura también deben generar documentos de requisitos; tener entrada de lectura no cambia las reglas de redacción.
- El único punto de acoplamiento es la convención de directorio de documentos + Markdown: rutas, títulos y sintaxis renderizable. La convención se define en la configuración del proyecto, no está fijada en el skill.
Cuándo usarlo
- Cuando producto, desarrollo o pruebas quieren ver las reglas directamente en la página actual para evitar consultar archivos MD en otra pantalla.
- Cuando ya existe un sistema de documentos de requisitos en Markdown y se necesita una vista de solo lectura.
- Cuando se necesita integrar documentos internos en demostraciones de entrega, pero controlando la visibilidad en producción.
No aplica: edición en línea / comentarios colaborativos, flujos de aprobación de documentos, servicio de búsqueda de texto completo, niveles de permisos de lectura (se puede extender más adelante, no está en la implementación mínima).
Orden de lectura
| Archivo | Cuándo leerlo |
|---|---|
references/integration-design.md | Al diseñar la entrada, compilación, mapeo y carga diferida |
references/rendering-and-search.md | Al renderizar Markdown restringido, filtrar secciones históricas y buscar |
references/acceptance-checklist.md | Durante pruebas, revisión y aceptación |
references/ops-and-governance.md | Al gestionar superficies de exposición en producción, actualización y publicación de documentos |
Lista de implementación mínima
- Entrada: Mostrar solo en páginas que tengan mapeo de documentos; sin mapeo no se renderiza (no dejar botones muertos); la entrada en sí no carga ningún documento.
- Fuente: La fuente del documento es Markdown dentro del repositorio (o archivos estáticos equivalentes); se copia al directorio de salida durante la compilación; en tiempo de compilación se realiza una validación bidireccional salida↔mapeo (falta/ huérfano resulta en fallo de compilación).
- Mapeo: El registro de ruta/página → ruta del documento es la única fuente de mapeo; el árbol de documentos se agrupa por módulo; los documentos a nivel de módulo se identifican individualmente.
- Carga: El documento se solicita solo después de abrir el cajón/panel; la primera apertura carga el documento actual; el índice de búsqueda se construye en segundo plano después de abrir; no precargar documentos al iniciar.
- Renderizado: Renderizado Markdown restringido (títulos, párrafos, listas, tablas, código, citas, divisores, enlaces); escape completo de HTML, solo se emiten etiquetas de lista blanca; codificación URL de nombres de archivo con caracteres chinos y paréntesis; adaptación a rutas de subdirectorio; los slugs de anclajes de título se sanitizan contra caracteres peligrosos en HTML/URL (
<>&"'), la generación de anclajes tiene una única salida (compartida por índice/contenido/búsqueda/navegación). - Reglas del lector: Mostrar solo la explicación más reciente — no renderizar las secciones de «registro de cambios / registro de actualizaciones» (incluyendo su contenido), el índice y la búsqueda los excluyen sincrónicamente; si el documento fuente contiene anotaciones de instantáneas históricas, se filtran según la convención del proyecto o el autor no las escribe.
- Interacción: Navegación por clic en el índice, las páginas de acción pueden sugerir una ubicación predeterminada por capítulo, búsqueda global de palabras clave (agrupada por documento, resultados de la página actual arriba, fragmentos sin ruido de Markdown) y salto, estados de error y reintento, cierre. Contexto de navegación de resultados de búsqueda: al hacer clic en un resultado, solo se cambia el contenido, sin borrar el término de búsqueda / la lista de resultados; se conserva la posición de desplazamiento de la lista de resultados; los elementos coincidentes se resaltan (clave estable que incluya al menos documento + anclaje + título, y si es necesario un fragmento para distinguir múltiples coincidencias en la misma sección); se proporciona un botón claro de «borrar búsqueda» para restaurar el árbol de documentos; al abrir un documento desde el árbol, se borra la búsqueda; no se reconstruye el índice. Línea roja: si el índice está fijado en la parte superior o la lista expandida está permanentemente sobre el contenido, el clic para navegar debe compensar el desplazamiento por la altura de superposición para evitar solapamiento; en automatización, usar aserciones de solapamiento (
toBeVisibleno detecta solapamiento). Detalles de formas avanzadas como índice plegable fijo, compensación de desplazamiento, etc., verreferences/integration-design.md§7. - Superficie de exposición en producción: El interruptor de la entrada solo controla el botón, no protege los documentos estáticos; en producción se debe elegir una de dos: excluir el directorio de documentos en la compilación, o agregar autenticación a las rutas de documentos (escribir en la puerta de acceso de producción).
- Pruebas: Integridad del mapeo, consistencia de los artefactos de compilación, secciones históricas no mostradas, carga diferida sin precarga, búsqueda y salto, mantenimiento del contexto de resultados de búsqueda (palabras clave / resultados / posición de desplazamiento retenidos, aciertos continuos, restauración del árbol al borrar, resaltado único, no reconstrucción del índice), estados de error; aserciones de solapamiento en índice/navegación (
toBeVisibleno detecta solapamiento); las aserciones de restauración de desplazamiento toleran clamp, no requieren igualdad absoluta de píxeles; revisión visual en navegador y archivo de evidencia (captura de pantalla consistente con el comportamiento final).
Límites
- No modificar el comportamiento de las páginas de negocio, los valores de negocio de menús/rutas ni los datos Mock; solo agregar la entrada de lectura y la cadena de activos de documentos.
- No introducir dependencias pesadas de renderizado MD de terceros; el renderizador debe ser restringido, testeable y con escape.
- No incluir «normas de redacción de documentos» en este skill; no incluir «detalles de implementación de la entrada» en el skill de redacción.
- Los permisos reales, el despliegue en producción y la autenticación se rigen por la puerta de acceso del proyecto; aprobar en Mock/demo no equivale a protección en producción.
Entregables
Ubicación de la entrada y condiciones de visibilidad, fuente de documentos y mapeo, copia y validación en compilación, renderizado y filtrado histórico, carga diferida y búsqueda, estados de error, manejo de superficies de exposición en producción, pruebas y evidencia de revisión, elementos no cubiertos.