Skip to content

PWA_GUIDE.md

Latest commit

 

History

History
195 lines (139 loc) · 19.3 KB

PWA_GUIDE.md

File metadata and controls

195 lines (139 loc) · 19.3 KB
Raw

Progressive Web App (PWA) Guide (Српски)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

OmniRoute се испоручује као Progressive Web App која се може у потпуности инсталирати. Када приступите контролној табли из било ког мобилног прегледача — Android (Chrome) или iOS (Safari) — можете да изаберете „Додај на почетни екран“ и добијете искуство налик изворној апликацији, без потребе за продавницом апликација.

Шта је PWA?

Progressive Web App претвара OmniRoute веб-контролну таблу у нешто што изгледа и функционише као изворна мобилна апликација. Након инсталације, она:

  • Покреће се са почетног екрана помоћу сопствене иконе
  • Отвара се преко целог екрана — без адресне траке прегледача или корисничког интерфејса картица
  • Ради ван мреже помоћу наменске странице за повезивање
  • Кешира статичке ресурсе ради бржег учитавања
  • Подржава и усправну и положену оријентацију

Инсталација

Android (Chrome)

  1. Отворите OmniRoute контролну таблу у Chrome-у: http://YOUR_IP:20128
  2. Chrome ће аутоматски приказати банер „Додај OmniRoute на почетни екран“, или:
    • Додирните мени ⋮ (три тачке) → „Додај на почетни екран“ или „Инсталирај апликацију“
  3. Потврдите упит
  4. OmniRoute ће се појавити на почетном екрану као самостална апликација

iOS (Safari)

  1. Отворите OmniRoute контролну таблу у Safari-ју: http://YOUR_IP:20128
  2. Додирните дугме Дели (оквир са стрелицом)
  3. Померите се надоле и додирните „Додај на почетни екран“
  4. Унесите назив (подразумевано је „OmniRoute“) и додирните Додај
  5. OmniRoute ће се појавити на почетном екрану са иконом апликације

Десктоп (Chrome / Edge)

  1. Отворите OmniRoute контролну таблу
  2. Кликните на икону за инсталацију у адресној траци (или ⋮ → „Инсталирај OmniRoute...“)
  3. Потврдите упит
  4. OmniRoute ће се отворити као самосталан прозор — без картица и адресне траке

Функционалности

Приказ преко целог екрана

Манифест је конфигурисан помоћу display: "fullscreen", што значи да инсталирана апликација користи цео екран — без интерфејса прегледача и без преклапања са статусном траком. Захваљујући томе, контролна табла заиста оставља утисак изворне апликације.

Подршка за рад ван мреже

OmniRoute обухвата service worker (sw.js) који обезбеђује интелигентно кеширање:

Тип ресурса Стратегија Понашање
Оквир апликације Прво кеш /, /offline, манифест и иконе унапред се кеширају приликом инсталације
Статички ресурси (CSS, JS, слике, фонтови) Прво мрежа, уз резервни кеш Преузима свежу верзију са мреже; користи кеш ако нема мрежне везе
Next.js пакети (/_next/) Прво мрежа, уз ажурирање кеша Преузима са мреже и ажурира кеш; користи кеширану верзију ако нема мрежне везе
Навигациони захтеви Заобилажење (никада се не пресрећу) Прегледач управља преласком са HTTP/3 на HTTP/2; неактиван QUIC сокет не сме да постане Response.error()
API / руте контролне табле (/api/, /a2a, /dashboard) Заобилажење (никада се не кеширају) Увек иду директно ка серверу — service worker их никада не пресреће

Страница за рад ван мреже

Када мрежа није доступна, а корисник пређе на нову страницу, service worker приказује наменску страницу /offline која:

  • Приказује јасну поруку „Проблем са везом“
  • Приказује живи индикатор статуса мрежне везе који се ажурира у реалном времену
  • Садржи дугме „Покушај поново да се повежеш“ за поновно учитавање када се веза успостави
  • Садржи везу до странице статуса ради дијагностике

Иконе апликације

OmniRoute обезбеђује иконе оптимизоване за сваку платформу:

Датотека Величина Користи се за
icon-512.png 512×512 Android упит за инсталацију, уводни екран
apple-touch-icon.png 180×180 Икона на iOS почетном екрану
icon-192.svg 192×192 (векторска) Android прилагодљива икона
apple-touch-icon.svg 180×180 (векторска) Резервна икона за Apple
favicon.svg Векторска Картице прегледача
favicon.ico Више величина Старији прегледачи

Аутоматска регистрација

Service worker се аутоматски региструје преко компоненте <PwaRegister /> у основном распореду. Корисник не мора ништа да предузима — апликација постаје доступна за инсталацију чим прегледач открије важећи манифест и service worker.

Техничка архитектура

Манифест веб-апликације (manifest.webmanifest)

Генерише га Next.js преко src/app/manifest.ts:

{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "OmniRoute is an AI gateway for multi-provider LLMs. One endpoint for all your AI providers.",
  "start_url": "/",
  "scope": "/",
  "display": "fullscreen",
  "orientation": "any",
  "background_color": "#0b0f1a",
  "theme_color": "#0b0f1a",
  "icons": [
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    },
    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
  ]
}

Service Worker (public/sw.js)

Стандардни service worker (без зависности од радних оквира) са следећим функцијама:

  • Фаза инсталације: Унапред кешира основу апликације (корену страницу, страницу за рад ван мреже, манифест и иконе)
  • Фаза активације: Уклања старе верзије кеша и преузима контролу над свим клијентима
  • Фаза добављања: Интелигентно усмеравање на основу типа захтева (навигација, статички ресурс, API)
  • Верзионисање кеша: omniroute-pwa-v3 — повећајте ову верзију да бисте принудно направили нови кеш након ажурирања

Метаподаци распореда (src/app/layout.tsx)

Корени распоред обезбеђује све метаознаке потребне за усклађеност са PWA стандардом:

  • manifest веза ка /manifest.webmanifest
  • apple-web-app-capable: true за самостални режим на iOS-у
  • apple-web-app-status-bar-style: black-translucent
  • mobile-web-app-capable: yes за Chrome на Android-у
  • theme-color: #0b0f1a
  • viewport-fit: cover за приказ од ивице до ивице

Компонента: PwaRegister

Налази се у src/shared/components/PwaRegister.tsx; ова клијентска компонента:

  1. Покреће се при монтирању (само на клијентској страни)
  2. Проверава подршку за serviceWorker у прегледачу
  3. Неприметно региструје /sw.js (грешке се занемарују како не би блокирале апликацију)
  4. Не приказује ништа (return null) — компонента служи искључиво за споредни ефекат

Коришћење са Termux-ом (Android)

Када се OmniRoute покреће на Android-у преко Termux-а, PWA ради без потешкоћа:

  1. Покрените OmniRoute у Termux-у: npx omniroute
  2. Отворите Chrome на истом телефону: http://localhost:20128
  3. Инсталирајте PWA преко опције „Додај на почетни екран“
  4. PWA се повезује са локалним Termux сервером — све се извршава на самом уређају

Ова комбинација значи да је ваш Android телефон истовремено и сервер (Termux) и клијент (PWA) — потпуно самосталан AI мрежни пролаз.

Коришћење са других уређаја

Инсталирајте PWA на било ком уређају који преко прегледача има приступ вашем OmniRoute серверу:

  • Други телефон/таблет: Идите на http://PHONE_IP:20128 и инсталирајте PWA
  • Лаптоп: Отворите Chrome/Edge и инсталирајте га као PWA за рачунар
  • Паметни телевизор са прегледачем: Приступите контролној табли преко целог екрана

Прилагођавање

Назив инстанце

Наслов PWA апликације поштује подешавање Назив инстанце у одељку Контролна табла → Подешавања. Ако инстанцу преименујете у „Мој AI мрежни пролаз“, инсталирани PWA ће приказивати тај назив.

Прилагођени фавикон

Ако отпремите прилагођени фавикон преко одељка Контролна табла → Подешавања, PWA икона на рачунару ће приказивати прилагођену икону. Иконе на почетном екрану мобилних уређаја користе унапред припремљене датотеке icon-512.png и apple-touch-icon.png.

Ограничења

  • Нема push обавештења — Service worker не имплементира Push API. Уместо тога, обавештењима управља Electron апликација.
  • Нема синхронизације у позадини — Радње извршене ван мреже не стављају се у ред за накнадно понављање. PWA је првенствено намењена за преглед контролне табле.
  • Ограничења на iOS-у — Safari на iOS-у не подржава све PWA функције (нпр. упити за инсталацију су ручни, а service worker-и у позадини су ограничени).
  • Величина кеша — Service worker кешира само статичке ресурсе. Велики садржаји одговора са /api/ рута никада се не кеширају.
  • Прилагођене иконе на мобилним уређајима — Промена favicon-а у подешавањима не ажурира икону на почетном екрану мобилног уређаја (за то је потребно поново генерисати PWA иконе).

Преглед датотека

Датотека Намена
src/app/manifest.ts Next.js рута манифеста (генерише manifest.webmanifest)
public/sw.js Service worker са логиком кеширања
src/shared/components/PwaRegister.tsx Клијентска компонента која региструје service worker
src/app/offline/page.tsx Резервна страница за рад ван мреже са индикатором статуса у реалном времену
src/app/layout.tsx Коренски распоред са PWA метаподацима (apple-web-app, theme-color итд.)
public/icon-512.png PNG икона величине 512×512 (Android, уводни екран)
public/apple-touch-icon.png PNG икона величине 180×180 (почетни екран на iOS-у)
public/icon-192.svg SVG икона величине 192×192 (прилагодљива икона за Android)
public/apple-touch-icon.svg SVG икона величине 180×180 (резервна опција за Apple)