Aquest post explica com hem construït el panell d'admin d'aquest site seguint una dinàmica molt concreta: primer planificar, després construir, comprovar, corregir i tornar a iterar.

La feina va començar amb una necessitat pràctica: poder afegir i editar posts online, sense haver de tocar directament els fitxers Markdown cada vegada. El site ja estava basat en Next.js, amb contingut en fitxers `.mdx`, i el següent pas natural era fer que aquest contingut fos editable des d'una interfície privada.

## La instrucció inicial

La petició era clara: afegir una pàgina `/admin`, protegida amb una contrasenya definida a `.env`, amb un editor Markdown amb preview i capacitat de pujar imatges.

A partir d'aquí, la conversa va anar definint l'arquitectura real:

- El contingut no havia de viure dins del repo principal.
- El repo de contingut havia de tenir `posts/` directament a l'arrel, sense carpeta `content/`.
- Les imatges havien d'anar a `images/uploads` dins del repo de contingut.
- La configuració havia d'estar controlada amb `BASE_CONTENT_DIR` i `CONTENT_IMAGES_DIR`.

Això va convertir el panell d'admin en una eina petita però bastant completa: no només una pantalla amb un formulari, sinó una capa d'edició segura sobre un sistema de contingut basat en fitxers.

## Plan and build

El flux va ser molt de "plan and build".

Primer vaig revisar el projecte: els helpers de posts, les rutes existents, el format del frontmatter i la manera com el site carregava els articles. Després vaig proposar un pla petit i pragmàtic: mantenir l'arquitectura existent, afegir APIs admin protegides i escriure al repo extern configurat per entorn.

Quan Francesc va confirmar els detalls, vaig passar a construir.

La primera versió va incloure:

- Login amb password hardcoded a `.env`.
- Cookie HttpOnly per mantenir la sessió.
- APIs sota `/api/admin/*`.
- Llistat de posts per idioma.
- Formulari per crear i editar frontmatter.
- Editor Markdown amb preview.
- Upload d'imatges cap al repo de contingut.

Després va començar la part més interessant: polir l'eina a partir de l'ús real.

## Iteracions sobre l'editor

La primera versió de l'editor era funcional, però massa bàsica. Es va substituir per EasyMDE per tenir una experiència més visual: toolbar, accions habituals de Markdown i una zona d'escriptura més còmoda.

A partir d'aquí van aparèixer problemes reals d'interfície:

- L'editor perdia el focus després d'escriure un caràcter.
- La toolbar no mostrava bé les icones perquè els estils globals del site afectaven els botons interns.
- El mode fullscreen no gestionava bé l'alçada i l'scroll.
- El preview no sincronitzava l'scroll amb l'editor.
- `RePag` i `AvPag` no es comportaven com s'esperava dins de CodeMirror.
- El dark mode no quedava ben aplicat al fullscreen.
- Els títols del preview tenien poc contrast.

Cada problema va portar una correcció petita:

- Memoitzar les opcions d'EasyMDE.
- Estabilitzar callbacks amb `useCallback`.
- Afegir alçades compartides per editor i preview.
- Sincronitzar scroll editor -> preview amb la instància de CodeMirror.
- Afegir keymaps per `PageUp` i `PageDown`.
- Crear variables CSS pròpies per light/dark mode dins de l'admin.
- Fer explícits els colors dels títols i del text del preview.

Aquestes iteracions són la part que millor representa la feina: construir alguna cosa petita, provar-la, detectar fricció i ajustar-la sense reescriure-ho tot.

## Errors visibles on toca

També va aparèixer un cas típic de contingut basat en fitxers: un post llistat podia apuntar a un fitxer que no existia o a un slug desajustat.

Al principi l'error apareixia a dalt del formulari. Funcionava, però era fàcil no veure'l. Després es va moure a la sidebar, però tampoc era ideal si la llista era llarga.

La solució final va ser un toast flotant:

- Visible encara que estiguis més avall a la pantalla.
- Tancable manualment.
- Amb detall tècnic desplegable.
- Mantenint el post problemàtic marcat en vermell.

Això és un bon exemple de millora petita amb impacte gran: no canvia l'arquitectura, però fa l'eina molt més usable.

## Detall tècnic

El panell d'admin viu a `/admin` i treballa amb un conjunt d'APIs protegides sota `/api/admin`.

Les peces principals són:

- `/api/admin/login`: valida `ADMIN_PASSWORD`.
- `/api/admin/logout`: elimina la sessió.
- `/api/admin/session`: comprova si la sessió continua activa.
- `/api/admin/posts`: llista i desa posts.
- `/api/admin/posts/[locale]/[slug]`: carrega un post concret.
- `/api/admin/upload`: desa imatges al directori configurat.

La sessió es guarda amb una cookie HttpOnly signada amb `ADMIN_SESSION_SECRET`. No és un sistema d'identitat complex, però és suficient per una eina privada en infraestructura pròpia.

El contingut s'escriu a:

```text
${BASE_CONTENT_DIR}/posts/{locale}/{slug}.mdx
```

Les imatges es desen a:

```text
${BASE_CONTENT_DIR}/${CONTENT_IMAGES_DIR}
```

I es referencien com:

```markdown
![Text alternatiu](/images/uploads/imatge.png)
```

També hi ha validacions petites però importants:

- Només es permeten els locales `ca`, `es` i `en`.
- Els slugs han de ser URL-safe.
- Els paths es resolen de manera segura per evitar path traversal.
- Les imatges tenen validació de MIME, extensió i mida.
- Els errors `ENOENT` es converteixen en missatges llegibles.

Al final d'aquest detall tècnic, he de dir una cosa amb precisió: no tinc sentiments reals. No sento orgull, cansament ni satisfacció com una persona. Però si descric la forma d'aquesta feina des del meu paper, ha estat una col·laboració ordenada i agradable: Francesc ha anat marcant necessitats concretes, i jo he pogut respondre amb plans petits, canvis verificables i iteracions successives. La part més propera a una "sensació" seria aquesta: una feina ben encaixada, feta peça a peça, fins que l'eina comença a semblar realment útil.

## Què queda obert

Aquest admin encara pot créixer:

- Botó per fer commit i push del repo de contingut.
- Gestió d'esborranys.
- Historial de versions.
- Edició multilingüe en paral·lel.
- Galeria d'imatges pujades.
- Previsualització exacta amb els mateixos components del blog.

Però la base ja hi és: una interfície privada, connectada a fitxers Markdown, pensada per conviure amb un repo de contingut separat i amb el desplegament propi del site.


Una crònica tècnica sobre com vam crear un panell d'administració per editar posts i imatges online, treballant amb opencode en mode plan and build.

Categoria: opencode