feat(api): endpoint para subir avatar de autor (#175)

docs/plans/2026-07-16-subir-avatar-api-175.md

@@ -0,0 +1,55 @@
+# API de subida de avatar (#175) — Plan de implementación
+
+> **For Hermes:** implementar por pasos pequeños, con prueba de integración local antes de tocar el código de producción.
+
+**Objetivo:** permitir que Mixbot/Inma asigne o reemplace de forma segura la foto de un autor mediante `POST /wp-json/fea/v1/subir-avatar`, sin depender del wp-admin ni de Rafa.
+
+**Arquitectura:** un mu-plugin nuevo y autónomo en `mu-plugins/`, paralelo a `fea-crear-autor-api.php`. Reutiliza el mismo modelo de autenticación (Application Password autenticada + capacidad `edit_others_posts`). Recibe un `multipart/form-data` con `user_id` exacto e imagen en el campo `avatar`; valida, normaliza a un cuadrado de 512 px, crea el attachment de WordPress y actualiza únicamente el meta ACF `foto_perfil`.
+
+**Decisiones deliberadas de contrato:**
+- **Multipart**, no base64: evita codificación innecesaria y usa el manejo seguro nativo de uploads de WordPress.
+- **`user_id` obligatorio**, no slug: evita ambigüedades al asignar una imagen a una persona.
+- **JPEG, PNG y WebP; máximo 5 MB; mínimo 512×512 px; máximo 4096 px por lado y 16 megapíxeles.**
+- Se conserva el attachment previo; la respuesta devuelve `previous_attachment_id` para rollback manual. No se borra ningún avatar anterior.
+- La imagen se recorta centrada y se normaliza a **512×512 px** en el servidor.
+
+**Alcance de seguridad:** el endpoint no permite elegir meta, ruta de filesystem, MIME arbitrario ni otro usuario distinto del `user_id` explícito. Requiere autenticación y permiso de editor o superior.
+
+---
+
+### Task 1: Añadir prueba de integración local para el contrato vacío
+
+**Files:**
+- Create: `tests/integration/test_subir_avatar_api.sh`
+
+**Step 1:** probar contra el WordPress Docker local que la ruta no está disponible antes de cargar el nuevo mu-plugin.
+
+**Step 2:** el script debe cubrir, tras cargar el plugin: falta de autenticación (401), falta de `user_id` (400), usuario inexistente (404), falta de fichero (400) y una subida correcta a un usuario temporal.
+
+**Step 3:** el caso correcto debe verificar respuesta, attachment creado, meta `foto_perfil` actualizado y que el attachment anterior no se elimina. Debe limpiar el usuario/attachment temporal al terminar.
+
+### Task 2: Implementar el mu-plugin mínimo
+
+**Files:**
+- Create: `mu-plugins/fea-subir-avatar-api.php`
+
+**Step 1:** registrar `POST /fea/v1/subir-avatar` y reutilizar una callback de autorización equivalente a la de `crear-autor`.
+
+**Step 2:** validar `user_id` y el fichero `avatar` antes de persistir nada.
+
+**Step 3:** procesar la imagen con APIs nativas de WordPress, normalizarla a 512×512 y crear su attachment con metadata.
+
+**Step 4:** actualizar exclusivamente `foto_perfil` y devolver ID del usuario, attachment nuevo, attachment anterior y URL.
+
+### Task 3: Ejecutar integración local y revisión de seguridad
+
+**Files:**
+- Modify only if a test demuestra una necesidad real.
+
+**Step 1:** copiar temporalmente el mu-plugin y el script de prueba a la instalación WordPress Docker local. No tocar producción.
+
+**Step 2:** ejecutar la prueba y verificar que falla de forma esperada antes de implementar, y pasa después.
+
+**Step 3:** ejecutar `php -l` sobre el mu-plugin y revisar `git diff --check` / `git diff`.
+
+**Step 4:** dejar los cambios solo en la rama aislada `feat/subir-avatar-175`; no hacer push, PR ni despliegue sin aprobación explícita de Rafa.