OASIS_MOBILE/docs/FRONTERA_UPSTREAM.md

# Frontera con upstream: que se puede tocar y que no

Las normas del dia a dia estan en [GUIA_DE_DESARROLLO.md](../GUIA_DE_DESARROLLO.md); esto
es la medicion de la que salen.

Medido el 19/10/2026 sobre el repositorio del dev (code.03c8.net/krakenslab/oasis),
de la release 1.0.1 (29/08) a la 1.3.3 (18/10), y comparado con la rama PRUEBAS.
Los scripts estan en el historial de la sesion; para repetirlo basta clonar upstream y
contar con `git log --numstat` por fichero.

## 1. Como trabaja el dev

- Una release casi cada dia: 39 entre la 1.0.1 y la 1.3.3, en siete semanas.
  Cada una es un solo commit ("Oasis release X.Y.Z"), sin historia intermedia: no
  hay forma de coger un cambio suelto, siempre llega todo junto.
- El backend crece sin parar: `backend.js` paso de ~9.900 a ~15.400 lineas y se
  toca en 34 de 39 releases. La cadena de middleware (el array `middleware` del final)
  ha ganado capas en este tiempo: contexto por peticion (`requestScope`), idioma de
  primera ejecucion, CSP, etc.
- Ya piensa en el movil: tiene su propio tema `OasisMobile.css`, usa la misma
  bandera `process.env.OASIS_MOBILE` que la rama y tiene workflows `activists` y
  `mobile`. Va en nuestra direccion; cuanto mas nos pisemos con el, peor.
- Las clases CSS cambian, pero poco a poco: de la 1.0.1 a la 1.2.0 aparecen 335
  clases y desaparecen 98; hasta la 1.3.1, +304 / -94; de la 1.3.1 a la 1.3.3, +47 / -8.
  Unas 100 clases muertas cada tres semanas, sobre ~2.200: un 5 %.

Ficheros que mas toca (releases que lo tocan de 39 / lineas movidas):

| Fichero | Releases | Lineas |
|---|---|---|
| `src/backend/backend.js` | 34 | 11.621 |
| `src/server/package.json` + lock | 34 | 22.700 |
| `src/client/assets/styles/style.css` | 32 | 2.522 |
| `translations/oasis_*.js` (los 11) | 31 cada uno | ~2.000 cada uno |
| `src/views/main_views.js` | 31 | 2.634 |
| `src/views/activity_view.js` | 27 | 1.183 |
| `src/views/tribes_view.js` | 23 | 2.675 |
| `src/client/assets/themes/OasisMobile.css` | 21 | 3.040 |
| `src/views/settings_view.js` | 17 | 849 |
| `src/views/vote_view.js` | 14 | 155 |
| `src/configs/config-manager.js` | 11 | 120 |
| `src/client/assets/styles/mobile.css` | 10 | 514 |
| `src/views/parliament_view.js` | 10 | 282 |
| `src/models/workflows_model.js` | 8 | 133 |
| `src/views/welcome_view.js` | 8 | 440 |
| `src/server/SSB_server.js` | 7 | 183 |
| `src/models/votes_model.js` | 4 | 33 |
| `src/backend/request_guards.js` (CSP) | 4 | 111 |

## 2. El mapa

### Rojo: no se toca

Cada linea nuestra aqui es un conflicto casi seguro en la siguiente release, y ademas
cambia el comportamiento de la red, no solo como se ve.

- `src/backend/backend.js`: rutas y, sobre todo, la cadena de `middleware`.
- `src/models/*` de upstream: lo que se publica en el log SSB y como se cuenta. Si dos
  nodos cuentan distinto (votos, tribus, gobierno), la red se rompe. Ejemplo: "quien
  crea una votacion no vota" es una regla de `votes_model.js`; cambiarla en la rama
  haria que nuestro movil y un escritorio dieran resultados distintos.
- `src/server/*` (arranque de SSB, `ssb_config`, `package.json` y dependencias).
- `src/backend/request_guards.js` (CSP: no hay estilos ni scripts en linea, y asi
  debe seguir).
- `translations/oasis_*.js`: se reescriben en 31 de 39 releases.
- `src/client/assets/styles/style.css` y `mobile.css`: son del dev.
- `src/client/assets/themes/*.css` de upstream, incluido `OasisMobile.css`.

### Ambar: solo un gancho de una linea, con la bandera de movil

Las vistas de upstream (`main_views.js`, `tribes_view.js`, `vote_view.js`,
`settings_view.js`...). Se reescriben a menudo, asi que lo que la rama necesite ahi va
como una llamada a una funcion nuestra, envuelta en
`process.env.OASIS_MOBILE === '1'`, y la logica vive en un fichero propio. Si el dev
reescribe la vista, se vuelve a poner una linea, no se reconstruye una funcion.

### Verde: nuestro, sin limite

- Hojas propias: `themes/Acampada.css`, `styles/mobile_base.css`,
  `styles/hive_acampada.css`, `styles/mobile_ux.css`.
- Vistas propias: `hive_views.js`, `mobile_icons.js`, `identities_view.js` y las
  `mobile_*.js`.
- El router propio `src/backend/fork_routes.js`: va justo antes del de upstream en la
  cadena y ve todas las peticiones. Puede atender rutas nuevas, o envolver una ruta de
  upstream (dejarla hacer y retocar la respuesta) sin editarla.
- Traducciones propias en `i18n_fork.js` (se mezclan encima de las de upstream).
- Modelo propio `fork_workflows.js`.
- Todo `android/`.

## 3. Como esta la rama hoy

43 ficheros de upstream modificados y 22 propios. Lo que mas pesa:

| Fichero de upstream | Lineas distintas | Riesgo |
|---|---|---|
| `themes/OasisMobile.css` | 4.873 | Alto: es casi otro fichero. El dev lo toca en 21/39 releases y cada vez hay que elegir entre su version y la nuestra. |
| `views/main_views.js` | 173 | Alto (31/39) |
| `backend/backend.js` | 133 (21 trozos) | Alto (34/39) |
| `configs/oasis-config.json` | 135 | Medio: es la config de serie del movil |
| `backend/blobHandler.js` | 190 | Medio (limpieza de fotos) |
| `backend/updater.js` | 133 | Bajo (3/39) |
| `views/modules_view.js` | 91 | Bajo (5/39) |
| `views/parliament_view.js`, `settings_view.js`, `vote_view.js`, `tribes_view.js` | 50-75 cada una | Medio-alto |
| `models/workflows_model.js` | 31 | Medio: redefine el workflow `activists` del dev |
| `server/ssb_config.js`, `SSB_server.js` | 40 | Medio (multicuenta) |

Las hojas propias y `OasisMobile.css` llevan selectores a clases que ya no pinta nadie:
61 en `OasisMobile.css`, 29 en `hive_acampada.css`, 5 en `Acampada.css`. No rompen
nada, pero son peso muerto y confunden.

## 4. Reglas para cada cambio

1. Primero CSS. Si se arregla con una hoja propia, se arregla ahi.
2. Si hace falta HTML distinto: funcion en un fichero propio + una linea en la vista
   de upstream, con la bandera de movil.
3. Si hace falta una ruta o retocar una respuesta: en el router propio. Nunca una
   ruta nueva ni un middleware en `backend.js`.
4. Nunca cambiar lo que se publica ni como se cuenta (modelos de upstream).
5. Textos nuevos en `i18n_fork.js`, en los 11 idiomas.
6. Nada en linea: la CSP no deja `style=""` ni `<script>` en la pagina.
7. Antes de integrar una release, repetir esta medicion y mirar si alguna clase de la
   que dependemos ha desaparecido.

## 5. Plan para sanear la rama

- Fase A (hecha el 19/10): lo del 19/10 que se metio en ficheros del dev sale a
  ficheros propios. Ver la seccion 6.
- Fase B (hecha el 19/10): `OasisMobile.css` vuelve a ser la del dev, identica a la
  1.3.3. Nuestra maqueta esta en `styles/mobile_base.css`, que el movil carga siempre
  antes del skin. Con el skin OasisMobile se ve el tema del dev encima de la maqueta.
- Fase C (hecha el 19/10): de los 20 trozos de `backend.js` quedan 9 (21 lineas).
  El resto (rutas cortadas en el movil, modulos que no van, avatar, lanzador,
  retoques del HTML, descargas de la copia de seguridad, cambio de tema) esta en
  `backend/mobile_layer.js` y en `fork_routes.js`. Los que quedan no se pueden
  hacer desde fuera: expresiones regulares para Node 18, no abrir el navegador, fotos
  duplicadas, modo chats y el montaje del router.
- Fase D (hecha el 19/10): `activists` vuelve a ser el del dev. Karvan y el workflow
  `acampada` se registran desde `models/fork_workflows.js`. La config de serie del
  movil coincide con `acampada`. Queda en `workflows_model.js` la logica de skins del
  movil.
- Correccion (19/10, noche): para el movil la referencia buena es el nodejs-project de
  la APK oficial, no el git del dev. Parte de lo que la fase C saco de backend.js era
  codigo de movil del propio dev; backend.js vuelve a ser su version de movil mas dos
  lineas (montar nuestro router), y modules_view.js su version de movil. Contra la APK
  oficial la rama cambia 17 ficheros y 561 lineas; la lista esta en la guia.
- Fuera Karvan (19/10): el dev ya trae Telefono y Salas, asi que se quita el modulo
  propio de salas y llamadas (modelo, vista, JS, CSS, router, pruebas, textos).
  `Clear-SNH.css` y `modules_view.js` vuelven a ser identicos a los del dev y la linea
  de `SSB_server.js` que enchufaba el audio de Android pasa a `main.js`, usando los
  `setAudioFactory`, `setVideoFactory` y `setStreamFactory` que el propio dev exporta.
- Fase E (hecha el 19/10): fuera 153 selectores muertos de `mobile_base.css`,
  `hive_acampada.css` y `Acampada.css` (287 lineas). Comparado pixel a pixel en 14
  pantallas: identicas.

## 6. Fase A: lo que se ha movido

| Antes (en ficheros del dev) | Ahora |
|---|---|
| `backend.js`: `checkMod` envuelto para recordar la seccion apagada | El router propio mira las redirecciones a `/modules` de vuelta |
| `backend.js`: ruta `POST /modules/enable` y `?saved=1` tras guardar | Router propio |
| `modules_view.js`: vista de Modulos del movil | `views/mobile_modules_view.js`, servida por el router propio |
| `workflows_model.js`: cuatro modulos mas en `activists` | Workflow propio `acampada` registrado desde `models/fork_workflows.js` |
| `vote_view.js`, `tribes_view.js`, `settings_view.js`, `main_views.js`, `welcome_view.js`: funciones nuevas | Funciones en `views/mobile_ui.js`; en la vista de upstream queda la llamada |