hacklab/OASIS_MOBILE
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions 1
OASIS_MOBILE/GUIA_DE_DESARROLLO.md
SITO abae8132a4 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.
2026-10-19 13:16:27 +02:00

218 lines
9.9 KiB
Markdown
Raw Blame History

# 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).
Reference in a new issue View git blame Copy permalink