# Guía de desarrollo de OASIS_MOBILE

**Léela antes de tocar nada.** Esta rama vive encima de Oasis, que desarrolla
epsylon (el dev) y que saca una versión casi cada día. Todo lo que añadimos tiene
que sobrevivir a la siguiente versión sin reescribirlo. Esta guía dice qué se puede
tocar, qué no y cómo hacer cada tipo de cambio.

Las cifras y el razonamiento están en
[docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md). Aquí solo van las reglas.

---

## 1. La regla de oro

> **Oasis lo cambia el dev. Nosotros cambiamos cómo se ve en el móvil.**
>
> Lo que la rama añade va en **ficheros nuestros**. En un fichero del dev, como mucho,
> **una línea que llama a un fichero nuestro**, y solo en el móvil.

¿Por qué? Entre la 1.0.1 y la 1.3.3 (siete semanas) el dev publicó 39 versiones, cada
una en un único commit. `backend.js` cambió en 34 de ellas, `main_views.js` en 31,
las traducciones en 31. Cada línea nuestra en esos ficheros es un conflicto casi
seguro en la próxima integración. Y si tocamos cómo se publica o se cuenta algo en la
red, nuestro móvil deja de entenderse con los demás nodos.

---

## 2. El semáforo

### ROJO: no se toca

| Qué | Dónde | Por qué |
|---|---|---|
| El backend del dev | `src/backend/backend.js` | Cambia en 34/39 versiones. Rutas, middleware, todo. |
| La cadena de middleware | el array `middleware` al final de `backend.js` | Crece en cada versión (contexto por petición, idioma, CSP...). |
| Los modelos del dev | `src/models/*` salvo los nuestros (ver verde) | Definen qué se publica en el log SSB y cómo se cuenta. Cambiarlos rompe la red. |
| El arranque de SSB | `src/server/*` (`SSB_server.js`, `ssb_config.js`, `package.json`) | Dependencias y conexión con la red. |
| La política de seguridad | `src/backend/request_guards.js` | La CSP: sin `style=""` ni `<script>` en línea. Así se queda. |
| Las traducciones del dev | `src/client/assets/translations/oasis_*.js` | Se reescriben en 31/39 versiones. |
| Las hojas del dev | `styles/style.css`, `styles/mobile.css` | Cambian en 32/39 y 10/39. |
| Los temas del dev | `themes/Dark-SNH.css`, `Clear-SNH.css`, `Purple-SNH.css`, `Matrix-SNH.css`, **`OasisMobile.css`** | `OasisMobile.css` es **del dev** (21/39), no nuestro. |

Ejemplos de lo que **no** se hace:
- Cambiar una regla de un modelo, aunque parezca mala. "Quien crea una votación no
  vota" está en `votes_model.js`: se explica en pantalla, no se cambia.
- Añadir una ruta o un middleware a `backend.js`.
- Envolver o reescribir una función del backend (`checkMod`, `getConfig`...).
- Editar `oasis_es.js` para cambiar un texto.
- Meter estilos en línea o `<script>` en una vista.

### ÁMBAR: una línea de enganche y nada más

Las **vistas del dev** (`src/views/*_view.js`, `main_views.js`). Se reescriben a
menudo (`tribes_view.js` en 23/39, `main_views.js` en 31/39), así que:

- La lógica va en `src/views/mobile_ui.js` (o en otro `mobile_*.js` nuestro).
- En la vista del dev queda **una llamada**, siempre detrás de la bandera:

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

- Si el dev reescribe la vista, se vuelve a poner esa línea. No hay que reconstruir
  una función entera.
- En escritorio (sin `OASIS_MOBILE`) la vista del dev funciona igual que en el
  original.

Enganches que hay hoy: `main_views.js` (6), `tribes_view.js` (6), `vote_view.js` (4),
`settings_view.js` (3), `welcome_view.js` (3). Para encontrarlos:
`grep -n mobileUi src/views/*.js`.

### VERDE: nuestro, se toca libremente

| Para qué | Fichero |
|---|---|
| Aspecto de los dos skins de móvil (márgenes, letra, botones, piezas nuevas) | `src/client/assets/styles/mobile_ux.css` |
| Colores y formas del skin Acampada | `src/client/assets/themes/Acampada.css`, `styles/hive_acampada.css` |
| Estilos de Karvan | `styles/karvan.css` |
| Piezas de interfaz que se enchufan en vistas del dev | `src/views/mobile_ui.js` |
| Pantallas enteras propias | `src/views/mobile_modules_view.js`, `karvan_view.js`, `identities_view.js` |
| Lanzador, barra de abajo, barra de arriba | `src/views/hive_views.js` |
| Iconos | `src/views/mobile_icons.js` |
| Rutas propias y retoques a respuestas del dev | `src/backend/karvan_routes.js` (el router propio) |
| Workflows propios | `src/models/fork_workflows.js` |
| Modelos propios | `src/models/karvan_model.js` |
| JavaScript de cliente propio | `src/client/public/js/karvan.js` |
| Textos nuevos | `src/client/assets/translations/i18n_fork.js` |
| Imágenes propias | `src/client/assets/images/ux-*.svg` |
| La app Android | `android/` |

---

## 3. Cómo se hace cada cosa

### Cambiar cómo se ve algo
1. Busca la clase en el HTML (servidor local + inspector, ver sección 6).
2. Escribe la regla en `mobile_ux.css`. Los colores, siempre con los tokens `--ux-*`
   (`--ux-bg`, `--ux-fg`, `--ux-accent`, `--ux-muted`, `--ux-line`, `--ux-danger`...):
   así sale bien en Acampada y en OasisMobile.
3. Si no gana: `mobile.css` y `Acampada.css` usan `!important` y selectores largos.
   Sube la especificidad (`.main-column div.x`, `label.x input.y[type="checkbox"]`) y
   pon `!important`. Ojo: `Acampada.css` quita el borde a **todos** los `div`; para
   ponerle borde a uno, `.main-column div.mi-clase`.
4. Letra: **Anton solo en títulos y en el botón principal negro** (`.create-button`).
   Todo lo demás, en la letra del sistema en negrita.
5. Márgenes: uno solo, de 14 px a cada lado. No añadas rellenos a contenedores
   intermedios.

### Cambiar el HTML de una pantalla del dev
1. Función nueva en `mobile_ui.js`, que reciba lo que necesite como parámetro.
2. Una línea en la vista del dev: `mobileUi.isMobile() ? mobileUi.miPieza(...) : lo_de_antes`.
3. Los textos, por `i18n` (ver "Textos").

### Una pantalla entera nueva, o una ruta nueva
En el router propio, `src/backend/karvan_routes.js`. Va justo **antes** del router
del dev en la cadena: lo que no atiende pasa al del dev con `next()`.

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

### Retocar lo que responde el dev, sin editarlo
El envoltorio `wrapUpstream` de `karvan_routes.js` deja actuar al dev y después mira
la respuesta. Así se sabe a qué sección apagada se quería entrar (el dev solo
redirige a `/modules`) o se añade `?saved=1` tras guardar. Este es el sitio para eso,
nunca `backend.js`.

### Textos
- Siempre en `i18n_fork.js`, **en los 11 idiomas** (en, es, fr, eu, de, it, pt, zh,
  ar, hi, ru).
- Comprueba que la clave no existe ya en `oasis_en.js`: si existe, se pisaría también
  en escritorio.
- En el código, siempre con texto de reserva en inglés: `i18n.miClave || 'My text'`.

### Un workflow nuevo
En `fork_workflows.js`. Se registra empujándolo a los arrays que exporta el modelo
del dev. No se edita `workflows_model.js` ni se redefine un workflow del dev.

### Un icono
En `mobile_icons.js`: trazo de 2 px en rejilla de 24, `currentColor`. La clave es la
ruta (`/tribes` → `tribes`).

### Algo que solo pasa en el móvil
Siempre detrás de `process.env.OASIS_MOBILE === '1'` (o `mobileUi.isMobile()`).
`main.js` la pone; el escritorio no la tiene.

---

## 4. Antes de cada commit

- [ ] `git diff --stat` no toca nada rojo. Si toca una vista del dev, son líneas de
      enganche, no funciones.
- [ ] `node --check` en cada `.js` cambiado.
- [ ] El servidor local arranca y responde 200 en `/activity`, `/tribes`, `/modules`,
      `/settings`, `/votes`, `/karvan`, `/inbox`.
- [ ] Mirado a 412 px de ancho (y a 360 si es una pieza ancha).
- [ ] Textos nuevos en los 11 idiomas.
- [ ] Nada en línea (`style=""`, `<script>`): la CSP lo bloquea.
- [ ] Commit en castellano, sin rastro de herramientas ni coautorías automáticas.
- [ ] Ninguna clave, contraseña ni `.ssb` en el commit.

---

## 5. Cuando sale una versión nueva del dev

1. Coge su código tal cual para todo lo rojo.
2. En las vistas del dev, vuelve a poner los enganches (`grep -n mobileUi`
   en la versión anterior de la rama te dice dónde estaban).
3. Repite la medición de [docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md):
   qué ficheros ha tocado y si ha desaparecido alguna clase de la que tiran nuestras
   hojas.
4. Revisa a 412 px las pantallas de la sección 4.
5. Compila la APK con la oficial de **esa misma versión** como base
   (`android/scripts/release.sh`, variable `OASIS_APK_BASE`).

---

## 6. Cómo probar

**Servidor local** (con una identidad de usar y tirar y la red en pausa):

```sh
HOME=/tmp/oasis-prueba OASIS_NETWORK_PAUSED=1 node main.js
# http://localhost:3000, con el inspector del navegador en modo movil, 412x915
```

- `src/server/node_modules` no está en git: hace falta uno (el de la APK base vale).
- Si al reiniciar sale "Another Oasis instance is already running", el anterior sigue
  vivo y estás viendo código viejo: mátalo antes.
- Al arrancar se borran `src/configs/banking-eco-history.json` y
  `fediverse-accounts.json`: `git checkout -- src/configs/` antes de hacer commit.

**En el emulador** (Android Studio, `Pixel_9_API_36`): la APK de depuración deja
inspeccionar la WebView con `chrome://inspect` o con
`adb forward tcp:9333 localabstract:webview_devtools_remote_<pid>`.

---

## 7. Deuda que queda (por orden)

Cosas de antes de esta guía que todavía la incumplen. Ver la sección 5 de
[docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md).

1. **`OasisMobile.css`** difiere en 4.873 líneas de la del dev. Hay que devolverle la
   suya y llevar nuestra maqueta a una hoja propia.
2. **21 trozos antiguos en `backend.js`** (14 con la bandera de móvil): exportar copia
   de seguridad, avatar de la barra de arriba, vídeos, filtro del lanzador... Pasan al
   router propio.
3. **El workflow "activists"** sigue redefinido en `workflows_model.js`: devolver el del
   dev (ya existe el nuestro, "acampada").
4. **Selectores muertos** en `OasisMobile.css` (61), `hive_acampada.css` (29) y
   `Acampada.css` (5).