OASIS_MOBILE/GUIA_DE_DESARROLLO.md

# Guía de desarrollo

Notas para quien vaya a meter mano en la rama del móvil. Leedlas antes de empezar,
que nos ahorramos disgustos.

Esta rama va encima de Oasis, que es de epsylon. Él saca versión casi cada día
(39 entre la 1.0.1 y la 1.3.3, en siete semanas) y cada versión llega en un solo
commit. Si metemos cosas en sus ficheros, en cada integración hay que volver a
pelearse con ellas. Por eso la idea es sencilla: lo de Oasis lo cambia él; nosotros
cambiamos cómo se ve y se usa en el móvil, y lo hacemos en ficheros nuestros.

Los números y de dónde salen están en `docs/FRONTERA_UPSTREAM.md`.


## Lo que no se toca

- `src/backend/backend.js`. Cambia en 34 de cada 39 versiones. Ni rutas nuevas, ni
  middleware, ni envolver funciones suyas como `checkMod`.
- La cadena de middleware del final de `backend.js`. Crece en cada versión.
- Los modelos de `src/models/`, salvo el nuestro (`fork_workflows.js`). Ahí se decide qué se publica en la red y cómo se cuenta.
  Si lo cambiamos, nuestro móvil cuenta distinto que el escritorio de al lado. Un
  ejemplo real: quien crea una votación no puede votar en ella. No nos gusta, pero
  es una regla del modelo, así que se explica en pantalla y punto.
- `src/server/` (arranque de SSB, `ssb_config.js`, `package.json`).
- `src/backend/request_guards.js`, que lleva la CSP. Nada de `style=""` ni de
  `<script>` en la página.
- Las traducciones del dev, `translations/oasis_*.js`. Se reescriben casi en cada
  versión.
- `styles/style.css` y `styles/mobile.css`.
- Los temas del dev: Dark, Clear, Purple, Matrix y también `OasisMobile.css`, que
  aunque parezca nuestro es suyo (lo toca en 21 de 39 versiones).


## Las vistas del dev: una línea y ya

`src/views/*_view.js` y `main_views.js` son del dev y las reescribe a menudo
(`tribes_view.js` en 23 versiones, `main_views.js` en 31). Si en una pantalla suya
hace falta otro HTML en el móvil, el código va en `src/views/mobile_ui.js` y en la
vista solo queda la llamada:

```js
const mobileUi = require('./mobile_ui');
// ...
if (mobileUi.isMobile()) return mobileUi.tribeTabs(tribe, section, sections);
```

Cuando el dev reescribe la vista, se vuelve a poner esa línea y listo. En escritorio
no cambia nada porque la bandera `OASIS_MOBILE` solo la pone `main.js` en el móvil.

Ahora mismo hay enganches en `main_views.js`, `tribes_view.js`, `vote_view.js`,
`settings_view.js` y `welcome_view.js`. Para verlos: `grep -n mobileUi src/views/*.js`.


## Llamadas: las del dev

La rama tuvo un módulo de salas y llamadas propio (Karvan). Se quitó el 19/10/2026
porque el dev ya trae Teléfono y Salas. En Android el sonido y la cámara pasan por un
puente nativo de la app (`.audio_bridge`, ficheros `src/server/phone_*_android.js`,
que son del dev). La APK oficial lo trae; nuestra app Android todavía no, y es lo
que falta para que las llamadas suenen. Si falta algo en las llamadas, se arregla en
ese puente o se le pide al dev, no se monta otro módulo.

Ojo al comparar con el dev: para el móvil la referencia es el `nodejs-project` de su
APK oficial, no su repositorio git. Hay ficheros, como `SSB_server.js` o
`phone_module.js`, cuya versión de móvil solo está en la APK.

Lo mismo vale para cualquier módulo: antes de hacer uno propio, mirad si el dev ya lo
tiene o lo está haciendo.


## Lo que es nuestro

Aquí se puede hacer lo que haga falta.

- `src/client/assets/styles/mobile_base.css`: la maqueta del móvil (lanzador, barras,
  tarjetas, formularios). Se carga siempre en el móvil, antes del skin.
- `src/client/assets/styles/mobile_ux.css`: márgenes, letra, botones y todas las
  piezas nuevas. Vale para los dos skins de móvil.
- `src/client/assets/themes/Acampada.css` y `styles/hive_acampada.css`: el skin
  Acampada.
- `src/views/mobile_ui.js`: lo que se enchufa en vistas del dev.
- `src/views/mobile_modules_view.js`, `identities_view.js`: pantallas propias.
- `src/views/hive_views.js`: lanzador y barras de arriba y abajo.
- `src/views/mobile_icons.js`: los iconos.
- `src/backend/fork_routes.js`: nuestro router. Va justo delante del del dev.
- `src/backend/mobile_layer.js`: lo que el móvil necesita del backend (rutas que se
  cortan, módulos que no van, avatar y lanzador, retoques del HTML, descargas de la
  copia de seguridad). La monta `fork_routes.js`.
- `src/models/fork_workflows.js`: nuestros workflows.
- `src/client/assets/translations/i18n_fork.js`: nuestros textos.
- `src/client/assets/images/ux-*.svg`: nuestras imágenes.
- `android/`.


## Cómo hacer cada cosa

Cambiar cómo se ve algo. Se busca la clase en el HTML (servidor local e inspector) y
se escribe la regla en `mobile_ux.css`. Para los colores usad las variables `--ux-*`
(`--ux-bg`, `--ux-fg`, `--ux-accent`, `--ux-muted`, `--ux-line`, `--ux-danger`), que
tiran de Acampada si está y si no de la paleta de OasisMobile. Si la regla no gana,
es que `mobile.css` o `Acampada.css` mandan con `!important` y selectores largos:
hay que subir la especificidad y poner `!important` también. Ojo con una trampa:
`Acampada.css` quita el borde a todos los `div`, así que para ponérselo a uno hace
falta `.main-column div.la-clase`.

Letra: Anton para títulos y para el botón negro principal de cada pantalla
(`.create-button`). Lo demás, letra del sistema en negrita.

Márgenes: 14 px a cada lado y ya. Los contenedores de en medio sin relleno, que
antes se iban sumando y una ficha perdía 74 px por lado.

Cambiar el HTML de una pantalla del dev. Función en `mobile_ui.js` y una línea en la
vista, como arriba.

Una pantalla o una ruta nueva. En `fork_routes.js`. Lo que no atiende nuestro
router pasa al del dev con `next()`:

```js
.get('/modules', async (ctx, next) => {
  if (!isMobile()) return next();   // escritorio: la del dev
  ctx.body = mobileModulesView({ ... });
})
```

Retocar lo que contesta el dev. También en `fork_routes.js`, en `wrapUpstream`: deja
que el dev conteste y luego mira la respuesta. Así sabemos a qué sección apagada se
quería entrar (el dev solo manda a `/modules`) o añadimos `?saved=1` al guardar.

Textos. En `i18n_fork.js` y en los 11 idiomas (en, es, fr, eu, de, it, pt, zh, ar,
hi, ru). Antes, mirad que la clave no exista ya en `oasis_en.js`, porque si existe la
estaríais cambiando también en escritorio. En el código siempre con texto de reserva:
`i18n.miClave || 'My text'`.

Un workflow. En `fork_workflows.js`, que lo mete en las listas que exporta el modelo
del dev. No se toca `workflows_model.js`.

Un icono. En `mobile_icons.js`, trazo de 2 px sobre rejilla de 24 y `currentColor`. El
nombre es el de la ruta: `/tribes` es `tribes`.


## Antes de hacer commit

- Que `git diff --stat` no toque nada de la lista de lo que no se toca. En las vistas
  del dev, solo líneas de enganche.
- `node --check` en los `.js` que hayáis cambiado.
- Arrancar en local y ver que `/activity`, `/tribes`, `/modules`, `/settings`,
  `/votes`, `/phone`, `/rooms` e `/inbox` cargan.
- Mirarlo a 412 px de ancho, y a 360 si es algo ancho.
- Los textos nuevos, en los 11 idiomas.
- Nada en línea, que la CSP lo bloquea.
- Commit en castellano, sin coautorías de herramientas.
- Sin claves, contraseñas ni nada de `.ssb`.


## Cuando sale versión nueva del dev

1. Lo suyo se coge tal cual.
2. En sus vistas se vuelven a poner los enganches. El `grep -n mobileUi` sobre la
   versión anterior de la rama dice dónde iban.
3. Se repite la medición de `docs/FRONTERA_UPSTREAM.md`: qué ha tocado y si ha
   desaparecido alguna clase que usen nuestras hojas.
4. Se repasan a 412 px las pantallas de la lista de arriba.
5. Se compila la APK con la oficial de esa misma versión como base
   (`android/scripts/release.sh` con `OASIS_APK_BASE`).


## Probar en local

```sh
HOME=/tmp/oasis-prueba OASIS_NETWORK_PAUSED=1 node main.js
```

Y en el navegador `http://localhost:3000` con el inspector en modo móvil a 412x915.
Va con una identidad de usar y tirar y con la red parada.

Cosas que pasan:
- `src/server/node_modules` no está en git. Sirve el de la APK base.
- Si al reiniciar sale "Another Oasis instance is already running", el anterior sigue
  vivo y estáis viendo código viejo. Matadlo primero.
- Al arrancar desaparecen `src/configs/banking-eco-history.json` y
  `fediverse-accounts.json`. Antes del commit, `git checkout -- src/configs/`.

En el emulador (`Pixel_9_API_36` de Android Studio), la APK de depuración deja
inspeccionar la WebView desde `chrome://inspect`.


## Lo que todavía está mal

Cosas de antes de estas normas que aún no las cumplen, por orden de lo que más
duele:

1. En `backend.js` quedan 9 trozos pequeños (21 líneas) que no se pueden sacar desde
   fuera: tres expresiones regulares que con el Node 18 de Android tumbaban el
   arranque (esto habría que contárselo al dev), no abrir el navegador al arrancar,
   no repetir fotos ya limpiadas, el modo chats y la línea que monta nuestro router.
   Lo demás ya está en `src/backend/mobile_layer.js`.
2. En `workflows_model.js` queda la logica de skins del movil (`themeOf`, `sameTheme`):
   `settings_view.js` coge `currentWorkflow` al cargar y no se puede envolver desde
   fuera sin tocar esa vista. Es poco, pero es del dev.
3. `src/server/phone_module.js` escribe el estado de la llamada en
   `.phone_state.json` para que la app Android enseñe la notificación (9 líneas). El
   módulo del dev no avisa hacia fuera de los cambios de estado; habría que pedírselo.
4. `src/server/SSB_server.js` quita la publicación de la dirección del banco al
   arrancar. Hay que mirar por qué se quitó y si sigue haciendo falta.