feadulta/docs/guia-publicacion-carta-inma.md

# 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: <secreto>`). 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": "<p>Cuerpo en HTML…</p>",
    "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 href>`) 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": "<p>…cuerpo de la carta con sus secciones y enlaces…</p>",
    "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
<p>Texto editorial de introducción de la semana…</p>

<p><strong style="color:red">Evangelio y comentarios al Evangelio</strong></p>
<ul>
  <li><a href="https://wp-nuevo.feadulta.com/comentario-evangelio-domingo/">Comentario al evangelio</a></li>
</ul>

<p><strong style="color:red">Artículos seleccionados para la semana</strong></p>
<ul>
  <li><a href="https://wp-nuevo.feadulta.com/articulo-uno/">Primer artículo</a></li>
  <li><a href="https://wp-nuevo.feadulta.com/articulo-dos/">Segundo artículo</a></li>
</ul>

<p><strong style="color:red">Para unas eucaristías más participativas y actuales</strong></p>
<ul>
  <li><a href="https://wp-nuevo.feadulta.com/eucaristia-domingo/">Material para la eucaristía</a></li>
</ul>

<p><strong style="color:red">Material multimedia</strong></p>
<ul>
  <li><a href="https://wp-nuevo.feadulta.com/video-semana/">Vídeo de la semana</a></li>
</ul>
```

> 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).