primer commit

references/calidad.md

@@ -0,0 +1,96 @@
+# Lista de comprobaciones pre-entrega
+
+Ejecutar este checklist completo antes de declarar el manual terminado. Si falla cualquier punto, corregir y volver a generar el PDF.
+
+## 1. Contenido
+
+- [ ] El título de la portada coincide exactamente con el nombre de la aplicación.
+- [ ] El índice lista todos los capítulos y secciones presentes en el cuerpo.
+- [ ] Cada capítulo tiene al menos un objetivo explícito en un callout `info`.
+- [ ] Cada proceso termina con un callout `tip` "Resultado final".
+- [ ] La sección "Solución de problemas" existe y cubre al menos los tres errores más comunes.
+- [ ] Los nombres de los botones, campos y menús son idénticos a los de la UI.
+- [ ] Las acciones irreversibles están acompañadas de un callout `warning` o `danger`.
+
+## 2. Capturas de pantalla
+
+- [ ] Cada paso crítico tiene al menos una captura.
+- [ ] Las capturas están en `artifacts/` con nombres `NN-slug.png`.
+- [ ] Ninguna captura contiene contraseñas, tokens, datos personales reales o identificadores confidenciales.
+- [ ] Los banners de cookies, tooltips de onboarding y notificaciones están cerrados.
+- [ ] Las anotaciones numeradas coinciden con el orden de los pasos en el texto.
+- [ ] Las capturas se ven nítidas en la página impresa (probar zoom 100% en el lector de PDF).
+
+## 3. Estilo y formato
+
+- [ ] Todos los callouts tienen modificador correcto (`info`, `warning`, `danger`, `tip`, `note`).
+- [ ] Ningún párrafo excede 4 líneas en pantalla.
+- [ ] No hay cursivas decorativas; las negritas se usan solo para destacar UI ("Haga clic en **Guardar**").
+- [ ] No hay colores fuera de la paleta autorizada (ver `estilo.md`).
+- [ ] No hay tipografías distintas a Inter y JetBrains Mono.
+- [ ] Los bloques de código usan `pre code` y no se parten a la mitad de página.
+
+## 4. Numeración y referencias
+
+- [ ] Los pasos siguen numeración global sin reiniciar.
+- [ ] Las figuras se enumeran automáticamente y el caption coincide con el contenido de la imagen.
+- [ ] Las referencias cruzadas (por ejemplo, "ver paso 4") son correctas.
+- [ ] El índice generado automáticamente coincide con los encabezados reales.
+
+## 5. Impresión y paginación
+
+- [ ] Cada capítulo (`h1`) empieza en página nueva.
+- [ ] Ningún heading queda al final de página sin contenido después.
+- [ ] Ningún `.step-block`, `.callout` o `figure` se parte a la mitad.
+- [ ] La cabecera muestra el nombre del capítulo actual.
+- [ ] El pie muestra "Página X de Y" coherente (X nunca excede Y, Y es el total real).
+- [ ] La portada y la página de aviso de propiedad no muestran cabecera ni pie.
+- [ ] El aviso de propiedad menciona explícitamente a "FactorPesca S.A. de C.V." como titular del documento.
+- [ ] La portada usa sangrado completo (el fondo navy llega al borde de la hoja).
+- [ ] Las imágenes no pierden color ni contraste al imprimir (`-webkit-print-color-adjust: exact`).
+
+## 6. PDF final
+
+- [ ] El PDF se abre sin errores en al menos dos visores (Chromium y un lector externo como Preview o Acrobat).
+- [ ] El tamaño del PDF es razonable (menos de 25 MB para manuales de hasta 60 páginas; reducir peso si supera).
+- [ ] Los marcadores de navegación del PDF están generados para cada capítulo.
+- [ ] El archivo de salida se llama `manual-{aplicacion}-v{X.Y.Z}.pdf` y se entrega en `dist/`.
+
+## 7. Procedimiento de revisión
+
+1. Generar el PDF.
+2. Recorrer el manual página a página. Marcar cualquier desviación.
+3. Corregir el HTML/CSS/JS fuente (nunca el PDF).
+4. Volver a generar.
+5. Repetir hasta que el checklist esté completo.
+6. Marcar el manual como `released` en el changelog del proyecto.
+
+## 8. Errores frecuentes
+
+- **PDF sin color de fondo**: falta `-webkit-print-color-adjust: exact`. Revisar `manual.css`.
+- **TOC vacío**: los headings no tienen `data-toc` o están dentro de contenedores excluidos. Revisar `manual.js`.
+- **Anotaciones mal posicionadas**: las coordenadas no están en porcentaje. Revisar `data-annotations`.
+- **Pasos partiéndose a la mitad**: falta `break-inside: avoid` o el contenido del paso es demasiado alto. Dividir el paso.
+- **Saltos de página inconsistentes**: la cabecera/pie no están en `@page`. Revisar `manual.css` sección `@page`.
+
+## 9. Limitaciones técnicas conocidas
+
+- **Números de página en el índice automático**: el script `manual.js` no
+  puede conocer el número de página final de cada sección en el momento de
+  renderizar el PDF, porque Chromium solo expone esos números después de
+  paginar. Por eso las entradas del TOC muestran `—` como número. Tres
+  opciones para resolverlo:
+
+  1. **Aceptar la limitación**: dejar el guion y añadir a mano los números
+     tras la primera generación, editando `templates/manual.html` y usando
+     `data-toc-label` con la numeración correcta.
+  2. **Hacer un build en dos pasadas**: generar el PDF una vez, leer los
+     números de página reales del PDF resultante y volver a renderizar con
+     los números ya conocidos. Requiere un parser de PDF.
+  3. **Quitar los números del TOC**: ocultar la columna derecha de cada
+     fila del índice con CSS y dejar solo el nombre del capítulo/sección
+     con sus líderes de puntos. Es la opción más limpia visualmente.
+
+- **Named pages en Chromium**: el uso de `@page cover` y `@page copyright` está
+  soportado pero requiere que la sección use exactamente la clase CSS
+  correspondiente (`cover`, `copyright-page`, etc.) sin selectores anidados.