OASIS_MOBILE/docs/FRONTERA_UPSTREAM.md

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

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/hive_acampada.css`,
  `styles/mobile_ux.css`, `styles/karvan.css`.
- Vistas propias: `hive_views.js`, `mobile_icons.js`, `karvan_view.js`,
  `identities_view.js` y las que se creen (`mobile_*.js`).
- El router propio `src/backend/karvan_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).
- Modelos propios (`karvan_model.js`) y JS de cliente propio (`public/js/karvan.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: `OasisMobile.css`.** Devolverle la version del dev y llevar nuestra maqueta
  a una hoja propia (`styles/mobile_base.css`) que carguen Acampada y el skin
  OasisMobile de la rama. Es el mayor foco de conflictos.
- **Fase C: los 21 trozos antiguos de `backend.js`** (exportar copia de seguridad,
  avatar de la topbar, `#t=0.1` en los videos, filtro del lanzador...) pasan al router
  propio como envoltorios.
- **Fase D: workflows.** Devolver `activists` al del dev y registrar los nuestros
  (`acampada`) desde un fichero propio, empujandolos a los arrays que exporta
  `workflows_model.js`.
- **Fase E: limpieza** de selectores muertos en las hojas propias.

## 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 |