From 6c0e366b03146707eba7247a923b75c87c6dd0c4 Mon Sep 17 00:00:00 2001 From: rafa Date: Sat, 27 Jun 2026 11:18:50 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20gu=C3=ADa=20de=20publicaci=C3=B3n=20de?= =?UTF-8?q?=20la=20carta=20semanal=20para=20Inma=20(REST=20API)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Guía para el asistente de Inma: conexión por REST API, modelo carta->portada, categorías, flujo de publicación y qué es automático. Co-Authored-By: Claude Opus 4.8 --- docs/guia-publicacion-carta-inma.md | 319 ++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 docs/guia-publicacion-carta-inma.md diff --git a/docs/guia-publicacion-carta-inma.md b/docs/guia-publicacion-carta-inma.md new file mode 100644 index 0000000..3c072e7 --- /dev/null +++ b/docs/guia-publicacion-carta-inma.md @@ -0,0 +1,319 @@ +# Guía para publicar la carta semanal en Fe Adulta (WordPress) + +> **Para quién es este documento:** para el asistente (Claude Code / Cowork) que ayuda a +> **Inma** a publicar la carta semanal y los artículos en el WordPress nuevo de Fe Adulta. +> +> **Reparto de responsabilidades:** +> - **Inma** aporta el contenido editorial: cómo se redacta y compone la carta y los artículos. +> - **Este documento** aporta la infraestructura y la estructura del sitio: cómo conectarse, +> dónde va cada cosa, qué categorías usar, qué se publica automáticamente y qué hay que +> hacer a mano. +> - **Inma sube siempre en ESPAÑOL.** Las traducciones (EN/FR/IT/PT) y el audio (TTS) los +> genera un proceso automático en el servidor (ver §7). No hay que traducir a mano. + +--- + +## 1. El sitio y cómo conectarse + +### 1.1 Entornos + +| Entorno | URL | Estado | +|---------|-----|--------| +| **Beta (actual)** | `https://wp-nuevo.feadulta.com` | Es donde se trabaja **ahora** | +| Producción final | `https://feadulta.com` | Tras el "cutover" de DNS (cambiará la URL base) | + +Mientras no se avise, **todo va a `wp-nuevo.feadulta.com`**. Cuando se haga el cambio de +dominio, solo hay que sustituir la URL base en los ejemplos de abajo. + +### 1.2 Acceso recomendado: API REST de WordPress + contraseña de aplicación + +No hace falta SSH ni tocar la base de datos. WordPress trae una API REST y un sistema de +**"Contraseñas de aplicación"** (Application Passwords) pensado exactamente para esto. + +**Cómo obtener la credencial (lo hace Inma una sola vez):** +Inma **ya tiene usuario con rol Editor** en el sitio (suficiente para crear, editar, +publicar y programar entradas). Con ese usuario: +1. Entrar en `https://wp-nuevo.feadulta.com/wp-admin`. +2. Ir a **Usuarios → Perfil** → bajar hasta **"Contraseñas de aplicación"**. +3. Escribir un nombre (p. ej. `cowork-cartas`) y pulsar **Añadir**. +4. WordPress muestra una contraseña de 24 caracteres con espacios + (formato `xxxx xxxx xxxx xxxx xxxx xxxx`). **Se copia y se guarda**: solo se ve una vez. + +**Cómo la usa el asistente:** autenticación HTTP Basic sobre HTTPS, con +`usuario:contraseña_de_aplicación`. Ejemplo de prueba (debe responder con los datos del +usuario): + +```bash +curl -s -u "USUARIO:xxxx xxxx xxxx xxxx xxxx xxxx" \ + https://wp-nuevo.feadulta.com/wp-json/wp/v2/users/me +``` + +Base de la API para todo lo demás: `https://wp-nuevo.feadulta.com/wp-json/wp/v2/` + +> **⚠️ Pendiente de configurar en Cloudflare (bloqueante).** Comprobado el **27/06/2026**: el +> sitio está tras Cloudflare y devuelve **403 "Attention Required"** a **cualquier** petición +> que no sea un navegador real con JavaScript — afecta a la API REST, a la home y a +> `wp-login.php`, incluso enviando un User-Agent de navegador. Es el reto de navegador de +> Cloudflare, **no** un problema de la credencial. +> +> Para que el asistente pueda usar la API hay que crear una **excepción en el panel de +> Cloudflare** (lo hace Inma). Opciones, de más simple a más limpia: +> 1. **Allowlist por IP de origen:** WAF → Tools → permitir la IP pública desde la que se +> conecta el asistente. Simple, pero requiere IP fija/conocida. +> 2. **Regla WAF con token secreto:** una Custom Rule que haga *Skip / Bypass* cuando la +> petición vaya a `/wp-json/*` **y** lleve una cabecera secreta (p. ej. +> `X-FEA-Key: `). El asistente añade esa cabecera en cada llamada. +> 3. **Subdominio "solo DNS"** (sin proxy naranja), p. ej. `api.feadulta.com`, apuntando al +> mismo origen para servir la API sin pasar por el reto de Cloudflare. +> +> Hasta que se aplique una de estas, las llamadas a la API fallarán con 403. Coordinar con +> Rafa/Inma cuál se elige. + +--- + +## 2. La idea clave: **la carta de la semana ES la portada** + +Esto es lo más importante de entender. La portada de Fe Adulta **no** muestra "los últimos +artículos por categoría". Muestra **exactamente lo que enlaza la carta de la semana actual**, +agrupado por las secciones internas de esa carta. + +Es decir: la carta semanal es un artículo largo en HTML, con secciones marcadas por +encabezados, y dentro de cada sección hay enlaces a otros artículos. La portada lee la carta +vigente, detecta esas secciones y coloca cada grupo de enlaces en su bloque correspondiente. + +**Consecuencia práctica:** para que la portada se rellene bien, la carta tiene que estar +escrita con unos **encabezados de sección concretos** (§5) y enlazar a artículos que ya +existan en el sitio (§4). + +--- + +## 3. Categorías del sitio + +Las categorías se asignan por su **ID numérico** vía API (campo `categories: [..]`). + +### 3.1 Categorías de la carta (estado de cada carta) + +| ID | Nombre | Slug | Significado | +|----|--------|------|-------------| +| **6** | Carta de la semana | `cartasemana` | La carta **vigente**. Debe estar solo la actual. | +| **22** | La semana pasada | `carta-semana-pasada` | La carta de la semana anterior. | +| **21** | Cartas de otras semanas | `cartas-de-otras-semanas` | Histórico (todas las anteriores). | + +### 3.2 Categorías temáticas (para los artículos de dentro de la carta) + +| ID | Nombre | Uso | +|----|--------|-----| +| 1645 | Lecturas bíblicas | Lecturas del domingo | +| 1646 | Comentario editorial | Comentario editorial de la semana | +| 1647 | Comentarios al evangelio | Artículos que comentan el evangelio | +| 1648 | Eucaristía | Material para la eucaristía | +| 1649 | Multimedia | Vídeos / audios / material multimedia | +| 1650 | Artículos | Artículos generales seleccionados | + +> Cada artículo de la semana va en su categoría temática. **La carta** (el texto largo) va +> en la categoría **6**. + +--- + +## 4. Cómo se publica una carta nueva (flujo completo) + +Una "carta" no es un solo artículo: es **un artículo-carta que enlaza a varios artículos**. +El orden correcto es: primero los artículos, luego la carta que los enlaza. + +### Paso 1 — Crear los artículos de la semana + +Cada pieza de contenido (cada comentario al evangelio, cada artículo seleccionado, etc.) es +un **post** propio. Se crean vía API y conviene crearlos primero **como borrador** y, cuando +estén listos, publicarlos. + +```bash +curl -s -u "USUARIO:APP_PASSWORD" \ + -X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Título del artículo", + "content": "

Cuerpo en HTML…

", + "status": "draft", + "categories": [1647] + }' +``` + +De la respuesta JSON interesan dos campos: +- `id` → identificador del post. +- `link` → la **URL pública** del artículo. **Guardar esta URL**: es la que se usa para + enlazar desde la carta. + +Repetir para cada artículo, usando la categoría temática que corresponda (§3.2). + +### Paso 2 — Componer el artículo-carta + +La carta es un post HTML con: +1. Texto editorial libre (introducción). +2. Una sección por cada bloque, **encabezada con una de las frases exactas de §5**. +3. Dentro de cada sección, **enlaces (``) a las URLs** de los artículos del Paso 1. + +Ver §5 para el formato exacto de los encabezados y un ejemplo completo. + +### Paso 3 — Publicar (o programar) la carta + +La carta va en la categoría **6** (`cartasemana`). + +- **Publicar ya:** `"status": "publish"`. +- **Programar:** `"status": "future"` + `"date"` con la fecha/hora local del sitio en + formato ISO 8601, p. ej. `"2026-06-29T08:00:00"`. WordPress la publicará sola a esa hora. + +```bash +curl -s -u "USUARIO:APP_PASSWORD" \ + -X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Carta de la semana — 29 de junio", + "content": "

…cuerpo de la carta con sus secciones y enlaces…

", + "status": "future", + "date": "2026-06-29T08:00:00", + "categories": [6] + }' +``` + +### Paso 4 — Rotar la carta anterior (IMPORTANTE, manual) + +Al entrar una carta nueva en la categoría **6**, hay que **degradar la anterior** para que la +categoría "Carta de la semana" contenga **solo una** carta: + +1. A la carta que **dejaba** de ser actual: quitarle la categoría **6** y ponerle la **22** + ("La semana pasada"). +2. A la que estaba en **22**: pasarla a la **21** ("Cartas de otras semanas"). + +Vía API se actualiza el array `categories` del post (sustituye al anterior): + +```bash +curl -s -u "USUARIO:APP_PASSWORD" \ + -X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts/ID_DE_LA_CARTA_VIEJA \ + -H "Content-Type: application/json" \ + -d '{"categories": [22]}' +``` + +> Si se programa la carta nueva con `future`, esta rotación puede hacerse el mismo día en que +> se publique. Si surge duda sobre qué carta está en qué categoría, consultar: +> `GET /wp-json/wp/v2/posts?categories=6` (debe devolver solo una). + +--- + +## 5. Formato de la carta para que la portada la "entienda" + +La portada parsea el HTML de la carta buscando **encabezados con estas frases** (no distingue +mayúsculas/acentos, pero el texto debe coincidir). Cada encabezado abre una sección; todos los +enlaces que vayan **después** de ese encabezado (hasta el siguiente) se muestran en el bloque +de portada indicado: + +| Frase del encabezado en la carta | Bloque de portada | +|----------------------------------|-------------------| +| **Evangelio y comentarios al Evangelio** | Evangelio | +| **Artículos seleccionados para la semana** | Artículos de la semana | +| **Para unas eucaristías más participativas y actuales** | Eucaristía | +| **Material multimedia** | Multimedia | +| **Escuela EFFA** | EFFA | + +**Reglas:** +- Los encabezados se suelen marcar en rojo/negrita (es el estilo histórico), pero lo que + importa es que **el texto coincida** con la frase de la tabla. +- Los enlaces dentro de cada sección deben apuntar a **artículos que existan** en el sitio + (las URLs del Paso 1). Enlaces a páginas externas se ignoran. +- Si una sección no tiene enlaces, ese bloque de la portada queda vacío. + +**Ejemplo mínimo de cuerpo de carta:** + +```html +

Texto editorial de introducción de la semana…

+ +

Evangelio y comentarios al Evangelio

+ + +

Artículos seleccionados para la semana

+ + +

Para unas eucaristías más participativas y actuales

+ + +

Material multimedia

+ +``` + +> La portada cachea el resultado **15 minutos**. Al guardar/editar la carta se refresca sola, +> pero si un cambio no se ve al momento, esperar unos minutos. + +--- + +## 6. Qué es automático y qué hay que tocar a mano + +### Automático — NO hay que hacer nada + +- **Portada (home):** se construye sola a partir de la carta vigente (la más reciente en la + categoría 6) y sus secciones (§5). +- **Página "Carta de la semana"** (`/carta-de-la-semana/`): redirige automáticamente a la + carta más reciente de la categoría 6. +- **Página "La semana pasada"** (`/la-semana-pasada/`): redirige a la carta más reciente de la + categoría 22. +- **Menús, avatares de autores, multiidioma, etc.:** gestionados por el tema/plugins. +- **Traducciones (EN/FR/IT/PT) y audio (TTS):** las genera el proceso del servidor (§7). + +### Manual — lo que hace Inma / su asistente + +- Crear los **artículos** de la semana (§4, Paso 1). +- Componer y **publicar/programar la carta** (§4, Pasos 2-3). +- **Rotar** la carta anterior de categoría (§4, Paso 4). +- Subir **imagen destacada** del artículo si se quiere (campo `featured_media` con el ID de + un adjunto previamente subido a la biblioteca de medios). + +--- + +## 7. Traducción y audio automáticos (lado servidor — informativo) + +**Inma no tiene que traducir ni generar audio.** En el servidor hay (o habrá) un proceso +programado (cron) que: + +1. Detecta cartas y artículos nuevos publicados **en español** sin traducción. +2. Los **traduce** a EN/FR/IT/PT y los enlaza como traducciones (Polylang). +3. Genera el **audio TTS** (voz, MiniMax) de la carta y sus artículos. + +Por eso es importante: **subir siempre el contenido en español** y dejar que el proceso haga +el resto. Si una carta urgente necesita traducción inmediata, avisar a Rafa. + +> *Este punto es responsabilidad de Rafa (infraestructura). Se incluye aquí solo para que el +> asistente de Inma sepa que no debe duplicar ese trabajo.* + +--- + +## 8. Resumen rápido (checklist por carta) + +- [ ] Crear cada artículo de la semana (borrador → publicado). Guardar su URL. +- [ ] Componer la carta en HTML con los **encabezados exactos** de §5 y los enlaces a esos artículos. +- [ ] Publicar o programar la carta en la categoría **6**. +- [ ] Rotar la carta anterior: 6 → 22, y la de 22 → 21. +- [ ] Comprobar que la portada muestra las secciones (esperar hasta 15 min si hace falta). +- [ ] No traducir ni generar audio: lo hace el servidor. + +--- + +## 9. Referencia rápida de la API + +| Acción | Método y endpoint | +|--------|-------------------| +| Probar credencial | `GET /wp-json/wp/v2/users/me` | +| Listar categorías | `GET /wp-json/wp/v2/categories?per_page=100` | +| Crear artículo/carta | `POST /wp-json/wp/v2/posts` | +| Editar artículo/carta | `POST /wp-json/wp/v2/posts/{id}` | +| Ver carta vigente | `GET /wp-json/wp/v2/posts?categories=6` | +| Subir imagen | `POST /wp-json/wp/v2/media` (cabecera `Content-Disposition`) | + +Campos útiles del post: `title`, `content` (HTML), `status` (`draft`/`publish`/`future`), +`date` (ISO 8601 para programar), `categories` (array de IDs), `featured_media` (ID de adjunto).