Spec — Descomponer class-admin.php de Publisher¶

Estado: planificado, no ejecutado. Escrito antes de tocar código, como manda la casa.

1. La situación, medida¶

convoca-publisher/includes/class-admin.php:

Los diez métodos más grandes son casi todos de pintado:

2. La red que ya existe¶

Esto no es terreno virgen, y conviene decirlo antes de que alguien lo dé por hecho:

51 casos tocan esta clase. Es la red que hace posible partirla; sin ella, no se toca.

3. Objetivo¶

Que class-admin.php quede como controlador: registrar el menú, decidir qué pantalla se pinta y delegar. Las pantallas (HTML) y los manejadores (guardado) salen a sus propios ficheros.

No se cambia ni una etiqueta, ni un id, ni un name de formulario: la captura de HTML antes y después tiene que ser idéntica.

4. Instrumento de verificación¶

Aquí no valen las rutas: lo que se compara es el HTML de cada pantalla.

Ya está construido y probado (paso 0 de la spec):

• Script: ~/.hermes/scripts/capturar-pantallas-publisher.php.
• Captura las siete pestañas (channels, queue, settings, templates, test, moderation, guide) y la pantalla de un canal (canal=fb), normalizando los nonces.
• Línea base guardada: ~/.hermes/cache/convoca-publisher-html/antes-2026-11-02.json.

Es estable: dos ejecuciones seguidas dan los ocho hashes idénticos. Si dos capturas no coinciden sin haber tocado código, el instrumento está roto y el trozo no se juzga con él.

Dos trampas que costaron encontrarlo, para no repetirlas:

1. el administrador no tiene el mismo id en cada sitio: el arnés lo busca por rol (administrator), no por número. En la demo el 2 es admin; en Lugg no lo era, y la primera captura salió con las ocho pantallas vacías. Un arnés con el usuario clavado miente en el segundo sitio donde se usa;
2. convoca_publisher() vive en el namespace ConvocaPublisher: buscarla en el global da «no existe» y hace pensar en un plugin mal cargado que está perfectamente bien.

Tras cada trozo: misma captura y diff por pantalla contra la línea base. Un diff que no sea vacío se revisa a mano antes de dar el trozo por bueno.

5. Trozos, en este orden¶

De menor a mayor riesgo. Cada trozo es un commit y un despliegue verificable por separado.

Los handle_* no se mueven en esta pasada: son los que escriben, y moverlos sin una prueba de integración por formulario sería cambiar dónde está el riesgo, no quitarlo.

6. Criterio de parada¶

Se para cuando class-admin.php baje de ~800 líneas y no quede ningún render_* de más de 40. Si un trozo no deja el diff de HTML vacío y no se puede explicar por qué, se revierte y se queda para otra sesión. No se acumula deuda nueva para llegar a una cifra.

7. Estado: trozo 1 hecho, el resto pendiente¶

Trozo 1, hecho y verificado. render_guide_tab() (168 líneas de HTML puro, sin una sola llamada a self::, Plugin:: o al contenedor) pasó a Vista_Guia::render().

• class-admin.php: 2.817 → 2.649 líneas.
• 477 pruebas / 1.507 aserciones, PHPCS 29/29, PHPStan [OK].
• CI verde en 22d4672, desplegado en demo y Lugg como 1.22.16.
• HTML de las ocho pantallas byte a byte idéntico a la captura previa.

Trozo 2, hecho y verificado. render_log_page() (195 líneas) y render_moderation_tab() (72) a Vista_Registro. class-admin.php: 2.649 → 2.396.

• 477 pruebas / 1.509 aserciones, PHPCS 30/30, PHPStan [OK].
• CI verde en 7bc9e37; desplegado como 1.22.17 en demo y Lugg.
• HTML de las ocho pantallas otra vez idéntico.

render_templates_tab() se queda para el trozo 3: depende de render_template_tools() y test_candidates(), y moverla sola obligaría a dejar medio método atrás.

Trozo 3, hecho y verificado. Plantillas con sus dos ayudantes a Vista_Plantillas. class-admin.php: 2.396 → 2.264 líneas (2.817 al empezar), 59 funciones.

• 477 pruebas / 1.511 aserciones, PHPCS 31/31, PHPStan [OK].
• CI verde en 32f3e40; desplegado como 1.22.18.
• HTML de las ocho pantallas idéntico, una vez más.

Lo que la herramienta cazó en este trozo, y que no se ve en pantalla: un delegado que ya nadie llamaba y llamaba a un método privado de otra clase, un docblock huérfano que se pegó al método siguiente, y un @return con tipo que se quedó en el delegado en vez de en quien tiene la lógica. Los tres los denunció PHPStan.

Trozo 4, hecho y verificado. Los nueve métodos de canales (577 líneas) a Vista_Canales. class-admin.php: 2.264 → 1.764. Los siete públicos conservan delegado con su misma firma.

Trozo 5, hecho con un cambio de alcance. render_settings_tab() a Vista_Ajustes, pero register_settings() y los cinco saneadores se quedan: registran los callbacks con los que WordPress guarda cada opción, y moverlos cambia dónde engancha el sitio con sus datos. 1.764 → 1.650.

Estado final de esta pasada¶

Lo que queda, medido¶

• 18 render_* todavía dentro; los mayores son render_test_tab (104) y render_queue_tab (103), atados a los ocho métodos queue_* (~300 líneas entre todos).
• 12 handle_*, deliberadamente quietos: son los que escriben. La cola tiene ya su propia spec, con el grafo de llamadas y las cuatro pruebas de integración que hacen falta antes de mover los manejadores.
• register_settings (129), que no se mueve por lo dicho.

El criterio de parada de la spec era bajar de ~800 líneas; no se ha llegado, y no se ha forzado: los trozos que quedan son la cola (una unidad con sus ocho ayudantes) y los manejadores, que necesitan pruebas de integración por formulario antes de moverse.