fix(tts): sync_audio_to_prod.py respeta fea_audio_skip (issue #190)

sync_one() solo comprobaba fea_audio_done, ignorando fea_audio_skip. El
guard de #190 se anadio a tts_produce.py (generacion) pero nunca a este
script (subida a prod), asi que cualquier post con audio local obsoleto
de antes del hotfix (ej. #18036, pagina de cuentas/donaciones) volvia a
publicarse en cuanto entrara en el cluster de una carta. Paso hoy con la
carta 741: sync_audio_to_prod.py --carta 56290 restauro el mp3 de 3h27
en produccion. Revertido manualmente; este commit cierra el hueco.

Tambien documenta el alcance correcto del TTS (solo ES, un mp3 por
articulo, nunca multimedia) en la guia de Inma.

Co-authored-by: rafa <rcalvotorrejon@gmail.com>
Signed-off-by: rafa <rcalvotorrejon@gmail.com>

README.md

@@ -32,8 +32,40 @@ scripts/      — scripts Python/PHP de migración, traducción, TTS y mantenimi
 | `translate_haiku.py` | Traducción automática vía Claude Haiku |
 | `tts_produce.py` | Generación de audio TTS (MiniMax) |
 | `sync_translations_to_prod.py` | Sincronizar traducciones local → producción |
+| `sync_audio_to_prod.py` | Sincronizar UN post/carta de audio TTS local → producción (sube el mp3, verifica SHA-256 remoto y persiste `fea_audio_sha256`) |
+| `sync_audio_bulk.sh` | Envoltorio de `sync_audio_to_prod.py` para lotes: para en el primer fallo, sin reintentos ciegos, resumen ok/skip |
 | `detect_untranslated.php` | Detectar posts sin traducir |
 
+## Sincronizar audio TTS a producción (local → prod)
+
+`sync_audio_to_prod.py` sube el mp3 de UN post/carta y, desde el #213, calcula y verifica el
+SHA-256 en cada subida (reproducción verificada automática, sin backfill manual — ver #212).
+
+Para lotes de varios posts, usar `sync_audio_bulk.sh`: es el envoltorio que añade "parar en el
+primer fallo" (el script Python no lo hace por sí solo, recorre toda la lista y acumula errores).
+Carga los IDs con `mapfile`/mediante array y redirige el stdin de cada invocación a `/dev/null` a
+propósito — un `while read id; do ...ssh...; done < fichero` sin esa precaución se rompe en
+silencio porque `ssh` se come el resto del fichero de IDs (ver
+`feedback-bash-while-read-ssh-stdin` en la memoria del proyecto).
+
+```bash
+export FEA_PROD_SSH_HOST="rafa@188.40.120.157"
+export FEA_PROD_DOCKER_CONTAINER="wordpress-r2ssjifwj0r0ghyoqd528uaa"
+
+# Dry-run primero, siempre
+scripts/sync_audio_bulk.sh --ids 55519,55520,822 --dry-run
+
+# Aplicar de verdad
+scripts/sync_audio_bulk.sh --ids 55519,55520,822
+
+# Desde un fichero (un ID por línea) o toda la cola de una carta
+scripts/sync_audio_bulk.sh --file /tmp/ids_pendientes.txt
+scripts/sync_audio_bulk.sh --carta 54254
+```
+
+Rollback de un post concreto: `python3 scripts/sync_audio_to_prod.py --rollback --ids <id>`
+(borra el meta en prod, no toca el mp3 local).
+
 ## Servidor local de desarrollo
 
 WordPress corre en Docker local, accesible vía Tailscale:

docs/guia-tts-traduccion-inma.md

@@ -87,6 +87,15 @@ FEA_TTS_CARTAS="<ID_CARTA>" python3 scripts/tts_produce.py
 Reanudable (no repite lo ya hecho, meta `fea_audio_done`) y con freno automático si la cuota de
 MiniMax se agota (para tras fallos seguidos, no se queda colgado).
 
+**Alcance del TTS — qué NO llevar a audio (confusión real en la carta 741, 2026-08-26):**
+- **Solo el artículo original en español.** Las traducciones (EN/FR/IT/PT) nunca llevan audio
+  propio — no meter los posts de traducción en la cola (`FEA_TTS_IDS`/`FEA_TTS_CARTAS`).
+- **Un audio por artículo, nunca uno combinado de toda la carta.** `tts_produce.py` es correcto
+  (genera un mp3 por post). No usar `scripts/tts_carta.py` (legacy, concatena todos los artículos
+  de la carta en un único audio) — no es el flujo que se usa hoy.
+- **Nunca la categoría `multimedia`** (término `multimedia`, id 1649 — ver
+  `scripts/aplicar_clasificacion_a_bd.py`). Esas piezas no se locutan.
+
 **Publicar el audio en prod** (el paso anterior solo escribe en el WordPress local):
 ```bash
 python3 scripts/sync_audio_to_prod.py --carta <ID_CARTA>

mu-plugins/fea-audio-player.php

@@ -13,11 +13,23 @@ function fea_audio_player_html(): string {
     $url = get_post_meta($id, 'fea_audio_url', true);
     if (!$url) return '';
     $voice = get_post_meta($id, 'fea_audio_voice', true) ?: 'NicoFeadulta2026';
-    return '<div class="fea-audio">'
-        . '<span class="fea-audio-label">'
+    $sha256 = get_post_meta($id, 'fea_audio_sha256', true);
+    $label = '<span class="fea-audio-label">'
         . '<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true" focusable="false">'
         . '<path fill="currentColor" d="M3 10v4h4l5 5V5L7 10H3zm13.5 2a4.5 4.5 0 0 0-2.5-4.03v8.06A4.5 4.5 0 0 0 16.5 12zM14 3.23v2.06a7 7 0 0 1 0 13.42v2.06a9 9 0 0 0 0-17.54z"/>'
-        . '</svg> Escucha</span>'
+        . '</svg> Escucha</span>';
+    // Para un asset con hash registrado, descarga y verifica el fichero completo
+    // antes de delegar playback al navegador. Evita que un stream Range mezclado
+    // por una caché reproduzca fragmentos de otro MP3.
+    if (preg_match('/^[a-f0-9]{64}$/i', $sha256)) {
+        return '<div class="fea-audio">' . $label
+            . '<button type="button" class="fea-audio-verified-play" data-fea-audio-verified-play'
+            . ' data-src="' . esc_url($url) . '" data-sha256="' . esc_attr(strtolower($sha256)) . '"'
+            . ' data-post-id="' . esc_attr($id) . '" data-voice="' . esc_attr($voice) . '">Reproducir audio</button>'
+            . '<audio controls preload="none" hidden data-fea-audio-track data-post-id="' . esc_attr($id) . '" data-voice="' . esc_attr($voice) . '"></audio>'
+            . '<span class="fea-audio-status" role="status" aria-live="polite"></span></div>';
+    }
+    return '<div class="fea-audio">' . $label
         . '<audio controls preload="none" src="' . esc_url($url) . '"'
         . ' data-fea-audio-track data-post-id="' . esc_attr($id) . '" data-voice="' . esc_attr($voice) . '"></audio>'
         . '</div>';
@@ -56,6 +68,9 @@ add_action('wp_head', function () {
     .fea-audio-label{display:inline-flex;align-items:center;gap:.35rem;font-size:.78rem;
         font-weight:600;color:#8b1a2e;white-space:nowrap;line-height:1}
     .fea-audio audio{height:32px;width:230px;max-width:44vw}
+    .fea-audio-verified-play{border:1px solid #8b1a2e;border-radius:6px;background:#fff;color:#8b1a2e;padding:.35rem .6rem;font:inherit;font-size:.82rem;font-weight:600;cursor:pointer}
+    .fea-audio-verified-play:disabled{opacity:.65;cursor:wait}
+    .fea-audio-status{font-size:.76rem;color:#6b5c60}
     @media(max-width:600px){
         .fea-audio{margin-left:0;width:100%;margin-top:.5rem}
         .fea-audio audio{flex:1 1 auto;width:auto;max-width:none}
@@ -73,6 +88,40 @@ add_action('wp_footer', function () {
     if (!get_post_meta(get_queried_object_id(), 'fea_audio_url', true)) return;
     ?>
     <script>
+    (function () {
+        function hex(buffer) {
+            return Array.from(new Uint8Array(buffer)).map(function (n) {
+                return n.toString(16).padStart(2, '0');
+            }).join('');
+        }
+        document.querySelectorAll('[data-fea-audio-verified-play]').forEach(function (button) {
+            button.addEventListener('click', async function () {
+                var wrap = button.closest('.fea-audio');
+                var audio = wrap.querySelector('audio[data-fea-audio-track]');
+                var status = wrap.querySelector('.fea-audio-status');
+                button.disabled = true;
+                status.textContent = 'Verificando audio…';
+                try {
+                    // Se descarga el objeto entero una vez y se valida su hash. Sólo
+                    // entonces se crea un blob local: el <audio> no hará Range contra
+                    // CDN y jamás podrá mezclar fragmentos de otro MP3.
+                    var response = await fetch(button.dataset.src, {cache: 'no-store'});
+                    if (!response.ok) throw new Error('HTTP ' + response.status);
+                    var bytes = await response.arrayBuffer();
+                    var digest = hex(await crypto.subtle.digest('SHA-256', bytes));
+                    if (digest !== button.dataset.sha256) throw new Error('La copia recibida no coincide con el audio verificado');
+                    audio.src = URL.createObjectURL(new Blob([bytes], {type: 'audio/mpeg'}));
+                    audio.hidden = false;
+                    button.hidden = true;
+                    status.textContent = '';
+                    await audio.play();
+                } catch (error) {
+                    status.textContent = 'No se pudo verificar el audio. Inténtalo de nuevo.';
+                    button.disabled = false;
+                    console.error('Fe Adulta audio verification failed:', error);
+                }
+            });
+        });
         document.querySelectorAll('audio[data-fea-audio-track]').forEach(function (audio) {
             var fired = false;
             audio.addEventListener('play', function () {
@@ -84,6 +133,7 @@ add_action('wp_footer', function () {
                 });
             });
         });
+    }());
     </script>
     <?php
 });

scripts/sync_audio_bulk.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# sync_audio_bulk.sh — Sincroniza a producción, uno por uno, un lote de posts con
+# audio TTS ya generado en local. Envoltorio de sync_audio_to_prod.py que añade
+# "parar en el primer fallo" (el script Python no lo hace: recorre toda la
+# lista y acumula errores, ver #212/#213).
+#
+# Motivo del wrapper en bash con mapfile: un `while read id; do ...; done <
+# fichero` normal comparte el file descriptor de stdin con cualquier `ssh`
+# lanzado dentro del bucle. sync_audio_to_prod.py llama a ssh internamente; si
+# el bucle no está protegido, ssh se come el resto del fichero de IDs y el
+# bucle termina "sin error" tras procesar solo el primero. Detectado y
+# documentado en memoria (feedback-bash-while-read-ssh-stdin) el 2026-08-24
+# tras un lote real que solo sincronizó 1 de 184 posts sin ningún error visible.
+#
+# Uso:
+#   scripts/sync_audio_bulk.sh --ids 55519,55520,822
+#   scripts/sync_audio_bulk.sh --file /tmp/ids.txt          # un ID por línea
+#   scripts/sync_audio_bulk.sh --carta 54254                # cola completa de la carta
+#   scripts/sync_audio_bulk.sh --ids 55519,55520 --dry-run  # solo plan, no toca prod
+#
+# Requiere las mismas variables de entorno que sync_audio_to_prod.py para
+# apuntar a producción (ver ese script): FEA_PROD_SSH_HOST,
+# FEA_PROD_DOCKER_CONTAINER. Ejemplo:
+#   export FEA_PROD_SSH_HOST="rafa@188.40.120.157"
+#   export FEA_PROD_DOCKER_CONTAINER="wordpress-r2ssjifwj0r0ghyoqd528uaa"
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SYNC_PY="$SCRIPT_DIR/sync_audio_to_prod.py"
+
+usage() {
+  echo "Uso: $0 (--ids id1,id2,... | --file ruta | --carta post_id) [--dry-run]" >&2
+  exit 2
+}
+
+ids_csv=""
+ids_file=""
+carta=""
+dry_run=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ids) ids_csv="$2"; shift 2 ;;
+    --file) ids_file="$2"; shift 2 ;;
+    --carta) carta="$2"; shift 2 ;;
+    --dry-run) dry_run="--dry-run"; shift ;;
+    *) usage ;;
+  esac
+done
+
+# Carga explícita de IDs en un array ANTES de cualquier llamada a ssh — es la
+# parte que evita el bug de stdin. No usar `while read ... < fichero`.
+ids=()
+if [ -n "$ids_csv" ]; then
+  IFS=',' read -r -a ids <<< "$ids_csv"
+elif [ -n "$ids_file" ]; then
+  mapfile -t ids < "$ids_file"
+elif [ -n "$carta" ]; then
+  # No usar `mapfile < <(cmd)`: la sustitución de procesos no deja comprobar
+  # de forma fiable el exit code de `cmd` (mapfile ve su propio $?, no el de
+  # la tubería). Si la consulta falla, un array vacío se confundiría con
+  # "la carta no tiene artículos" y el lote saldría "éxito" sin sincronizar
+  # nada. Se resuelve a fichero temporal y se comprueba el rc de python
+  # explícitamente antes de poblar el array.
+  carta_tmpfile="$(mktemp)"
+  python3 - "$carta" "$SCRIPT_DIR" > "$carta_tmpfile" <<'PYEOF'
+import sys
+sys.path.insert(0, sys.argv[2])
+from sync_audio_to_prod import carta_article_ids
+for pid in carta_article_ids(int(sys.argv[1])):
+    print(pid)
+PYEOF
+  py_rc=$?
+  if [ $py_rc -ne 0 ]; then
+    echo "ERROR: fallo consultando la cola de la carta $carta (exit $py_rc), no se sincroniza nada." >&2
+    rm -f "$carta_tmpfile"
+    exit 1
+  fi
+  mapfile -t ids < "$carta_tmpfile"
+  rm -f "$carta_tmpfile"
+else
+  usage
+fi
+
+total=${#ids[@]}
+if [ "$total" -eq 0 ]; then
+  echo "Nada que sincronizar (lista de IDs vacía)." >&2
+  exit 0
+fi
+
+ok=0
+skip=0
+n=0
+for id in "${ids[@]}"; do
+  id="$(echo "$id" | tr -d '[:space:]')"
+  [ -z "$id" ] && continue
+  n=$((n + 1))
+  # stdin del hijo explícitamente en /dev/null: cinturón y tirantes además del
+  # array en memoria, por si algún día se cambia el bucle.
+  out="$(python3 "$SYNC_PY" --ids "$id" $dry_run < /dev/null)"
+  rc=$?
+  echo "$out"
+  if [ $rc -ne 0 ]; then
+    echo "=== ABORT: fallo en #$id ($n/$total procesados, $ok ok). Deteniendo lote, sin reintentar. ==="
+    exit 1
+  fi
+  if echo "$out" | grep -q "PLAN: subiría\|#$id: ok"; then
+    ok=$((ok + 1))
+  else
+    skip=$((skip + 1))
+  fi
+done
+
+echo "=== FIN LOTE. ok=$ok skip=$skip de $total candidatos. ==="

scripts/sync_audio_to_prod.py

@@ -19,6 +19,7 @@ Rollback (despublica en prod lo que este script publicó):
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
 import subprocess
@@ -74,6 +75,8 @@ def local_meta(post_id: int, key: str) -> str:
         ["docker", "exec", WP_CONTAINER, "php", "/tmp/fea_post_io.php", "getmeta", str(post_id), key],
         capture_output=True, text=True, timeout=60,
     )
+    if r.returncode != 0:
+        raise RuntimeError(f"docker exec {WP_CONTAINER} falló leyendo meta '{key}' de #{post_id} (rc={r.returncode}): {r.stderr.strip()[:300]}")
     return r.stdout.strip()
 
 
@@ -85,6 +88,8 @@ def carta_article_ids(carta_id: int) -> list[int]:
          DB_NAME, "-N", "-e", q],
         capture_output=True, text=True, timeout=60,
     )
+    if r.returncode != 0:
+        raise RuntimeError(f"consulta de _carta_id={carta_id} falló (rc={r.returncode}): {r.stderr.strip()[:300]}")
     return [int(x) for x in r.stdout.split() if x.isdigit()]
 
 
@@ -144,16 +149,21 @@ def prod_helper(subcmd: str, *args: str) -> str:
     return _ssh_text(_remote_wrap(inner), timeout=60)
 
 
-def prod_upload_mp3(post_id: int) -> None:
+def prod_upload_mp3(post_id: int) -> str:
     src = LOCAL_TTS_DIR / f"{post_id}.mp3"
     data = src.read_bytes()
+    local_sha256 = hashlib.sha256(data).hexdigest()
     remote_path = f"{PROD_UPLOADS_TTS}/{post_id}.mp3"
     _ssh_upload_bytes(data, remote_path)
-    # Verificación de tamaño: no fiarse ciegamente del rc=0 de ssh. `wc -c` debe
-    # correr (y resolver la redirección) DENTRO del contenedor — ver _remote_wrap.
+    # Verificación de tamaño+contenido: un rc=0 de ssh no acredita que el asset
+    # sea el mismo. El hash se persiste como meta y permite playback verificado.
     remote_size = int(_ssh_text(_remote_wrap(f"wc -c < {remote_path}")).strip())
     if remote_size != len(data):
         raise RuntimeError(f"tamaño no coincide tras subir #{post_id}: local={len(data)} remoto={remote_size}")
+    remote_sha256 = _ssh_text(_remote_wrap(f"sha256sum {remote_path} | cut -d' ' -f1")).strip()
+    if remote_sha256 != local_sha256:
+        raise RuntimeError(f"SHA-256 no coincide tras subir #{post_id}: local={local_sha256} remoto={remote_sha256}")
+    return local_sha256
 
 
 def prod_remove_mp3(post_id: int) -> None:
@@ -177,6 +187,13 @@ def save_state(state: dict) -> None:
 
 # ── Sync ─────────────────────────────────────────────────────────────────────
 def sync_one(post_id: int, state: dict, *, dry_run: bool) -> str:
+    # issue #190: páginas de cuentas/donaciones (ej. #18036 "numeros") llevan
+    # fea_audio_skip=1 desde el hotfix del 3-ago, pero pueden conservar un
+    # fea_audio_done=1 y un mp3 locales obsoletos de antes del guard. Sin este
+    # chequeo, cualquier --carta cuyo cluster las incluya vuelve a publicar el
+    # audio improcedente en prod (nos pasó el 26-ago con la carta 741).
+    if local_meta(post_id, "fea_audio_skip") == "1":
+        return "excluido (fea_audio_skip)"
     if local_meta(post_id, "fea_audio_done") != "1":
         return "sin-audio-local"
     if not (LOCAL_TTS_DIR / f"{post_id}.mp3").exists():
@@ -185,8 +202,9 @@ def sync_one(post_id: int, state: dict, *, dry_run: bool) -> str:
         return "PLAN: subiría mp3 + setaudio"
 
     voice = local_meta(post_id, "fea_audio_voice") or "NicoFeadulta2026"
-    prod_upload_mp3(post_id)
+    sha256 = prod_upload_mp3(post_id)
     prod_helper("setaudio", str(post_id), f"/wp-content/uploads/tts/{post_id}.mp3", voice)
+    prod_helper("setflag", str(post_id), "fea_audio_sha256", sha256)
     if post_id not in state["synced"]:
         state["synced"].append(post_id)
         save_state(state)