From abae8132a48b8672e79c9522f6f8a66f606b2124 Mon Sep 17 00:00:00 2001
From: SITO <sito@ransomsito.ransomsito>
Date: Mon, 19 Oct 2026 13:16:27 +0200
Subject: [PATCH] docs: guia de desarrollo con lo que se toca y lo que no

GUIA_DE_DESARROLLO.md en la raiz: la regla de oro, el semaforo (rojo:
backend, middleware, modelos, server, CSP, traducciones y hojas del dev;
ambar: una linea de enganche en las vistas del dev; verde: hojas, vistas,
router, workflows y textos propios), como hacer cada tipo de cambio, lo que
hay que comprobar antes de cada commit, como integrar una version nueva del
dev, como probar y la deuda que queda. Enlazada al principio del README.
---
 GUIA_DE_DESARROLLO.md     | 218 ++++++++++++++++++++++++++++++++++++++
 README.md                 |  15 +++
 docs/FRONTERA_UPSTREAM.md |   3 +
 3 files changed, 236 insertions(+)
 create mode 100644 GUIA_DE_DESARROLLO.md

diff --git a/GUIA_DE_DESARROLLO.md b/GUIA_DE_DESARROLLO.md
new file mode 100644
index 0000000..c1fb8b1
--- /dev/null
+++ b/GUIA_DE_DESARROLLO.md
@@ -0,0 +1,218 @@
+# 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).
diff --git a/README.md b/README.md
index f58b1bb..ab73b85 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,13 @@
 >
 > **Los fallos de esta rama se reportan aquí, nunca a epsylon.**
 
+> ## Para desarrollar: lee primero la [GUÍA DE DESARROLLO](GUIA_DE_DESARROLLO.md)
+>
+> Qué se puede tocar y qué no. Resumen: **el backend, el middleware, los modelos y
+> las traducciones son del dev y no se tocan**; lo nuestro va en hojas de estilo,
+> vistas y rutas propias, y en las vistas del dev como mucho una línea de enganche.
+> El porqué, con cifras: [docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md).
+
 Versión base: **Oasis 1.3.3** · Rama: `PRUEBAS` ·
 [Documentación completa](https://gitea.laenre.net/hacklab/OASIS_MOBILE/wiki) ·
 [Versión de escritorio](https://gitea.laenre.net/hacklab/OASIS_LINUX)
@@ -193,6 +200,14 @@ OASIS_APK_BASE=/ruta/oasis-v1.3.3.apk ./scripts/release.sh   # compila, verifica
 
 ## Documentación
 
+Para desarrollar en la rama, en el propio repositorio:
+
+| | |
+|---|---|
+| [GUIA_DE_DESARROLLO.md](GUIA_DE_DESARROLLO.md) | Qué se toca y qué no, cómo hacer cada tipo de cambio, comprobaciones antes de cada commit |
+| [docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md) | Cómo cambia el dev cada versión, medido, y el plan para sanear la rama |
+| [docs/USABILIDAD_PAD.txt](docs/USABILIDAD_PAD.txt) | Pruebas de usabilidad en el móvil: lo arreglado y lo pendiente |
+
 Todo lo de arriba, en detalle, está en la
 **[wiki](https://gitea.laenre.net/hacklab/OASIS_MOBILE/wiki)**:
 
diff --git a/docs/FRONTERA_UPSTREAM.md b/docs/FRONTERA_UPSTREAM.md
index 04e15c4..e51cbdb 100644
--- a/docs/FRONTERA_UPSTREAM.md
+++ b/docs/FRONTERA_UPSTREAM.md
@@ -1,5 +1,8 @@
 # Frontera con upstream: que se puede tocar y que no
 
+> Las reglas para el dia a dia estan en [GUIA_DE_DESARROLLO.md](../GUIA_DE_DESARROLLO.md).
+> Este documento es la medicion que las justifica.
+
 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