# Progressive Web App (PWA) Guide (ქართული)

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

---

OmniRoute ვრცელდება, როგორც სრულად ინსტალირებადი პროგრესული ვებაპლიკაცია. როდესაც მართვის პანელს ნებისმიერი მობილური ბრაუზერიდან — Android-ზე (Chrome) ან iOS-ზე (Safari) — ხსნით, შეგიძლიათ აირჩიოთ „მთავარ ეკრანზე დამატება“ და მიიღოთ ნატიური აპლიკაციის მსგავსი გამოცდილება აპლიკაციების მაღაზიის გარეშე.

## რა არის PWA?

პროგრესული ვებაპლიკაცია 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 მოიცავს სერვის-ვორკერს (`sw.js`), რომელიც ინტელექტუალურ კეშირებას უზრუნველყოფს:

| რესურსის ტიპი                                                           | სტრატეგია                         | ქცევა                                                                                                     |
| ----------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **აპლიკაციის გარსი**                                                    | ჯერ კეში                          | `/`, `/offline`, მანიფესტი და ხატულები ინსტალაციისას წინასწარ კეშირდება                                   |
| **სტატიკური რესურსები** (CSS, JS, სურათები, შრიფტები)                   | ჯერ ქსელი, შემდეგ კეში            | ახალ ვერსიას ქსელიდან იღებს; ინტერნეტის გარეშე კეშზე გადადის                                              |
| **Next.js-ის პაკეტები** (`/_next/`)                                     | ჯერ ქსელი, კეშის განახლებით       | ქსელიდან იღებს და კეშს აახლებს; ინტერნეტის გარეშე კეშირებულ ვერსიას იყენებს                               |
| **ნავიგაციის მოთხოვნები**                                               | გვერდის ავლა (არასოდეს მუშავდება) | HTTP/3→HTTP/2-ზე გადართვას ბრაუზერი მართავს; გათიშული QUIC სოკეტი არ უნდა გადაიქცეს `Response.error()`-ად |
| **API-ის / მართვის პანელის მარშრუტები** (`/api/`, `/a2a`, `/dashboard`) | გვერდის ავლა (არასოდეს კეშირდება) | ყოველთვის პირდაპირ სერვერზე იგზავნება — სერვის-ვორკერი მას არასოდეს ამუშავებს                             |

### ინტერნეტის გარეშე მუშაობის გვერდი

როდესაც ქსელი მიუწვდომელია და მომხმარებელი ახალ გვერდზე გადადის, სერვის-ვორკერი აჩვენებს სპეციალურ `/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`          | მრავალი ზომა      | მოძველებული ბრაუზერები                             |

### ავტომატური რეგისტრაცია

სერვის-ვორკერი ავტომატურად რეგისტრირდება ძირეულ განლაგებაში არსებული `<PwaRegister />` კომპონენტის მეშვეობით. მომხმარებლისგან არანაირი მოქმედება არ არის საჭირო — აპლიკაციის ინსტალაცია შესაძლებელი ხდება, როგორც კი ბრაუზერი მოქმედ მანიფესტსა და სერვის-ვორკერს აღმოაჩენს.

## ტექნიკური არქიტექტურა

### ვებაპლიკაციის მანიფესტი (`manifest.webmanifest`)

გენერირდება Next.js-ის მიერ `src/app/manifest.ts`-ის მეშვეობით:

```json
{
  "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` Android Chrome-ისთვის
- `theme-color: #0b0f1a`
- `viewport-fit: cover` კიდიდან კიდემდე რენდერისთვის

### კომპონენტი: `PwaRegister`

მდებარეობს `src/shared/components/PwaRegister.tsx`-ში. ეს კლიენტის კომპონენტი:

1. ეშვება დამონტაჟებისას (მხოლოდ კლიენტის მხარეს)
2. ბრაუზერში ამოწმებს `serviceWorker`-ის მხარდაჭერას
3. უხმაუროდ არეგისტრირებს `/sw.js`-ს (შეცდომები იგნორირდება, რათა აპლიკაციის მუშაობა არ შეფერხდეს)
4. არაფერს არ არენდერებს (`return null`) — ეს კომპონენტი მხოლოდ გვერდითი ეფექტისთვისაა განკუთვნილი

## Termux-თან გამოყენება (Android)

Android-ზე Termux-ის მეშვეობით OmniRoute-ის გაშვებისას 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-ს სათაური ითვალისწინებს **Instance Name** პარამეტრს `Dashboard → Settings`-დან. თუ თქვენს ინსტანციას „My AI Gateway“-ად გადაარქმევთ, დაინსტალირებული PWA ამ სახელს აჩვენებს.

### მორგებული ფავიკონი

თუ `Dashboard → Settings`-ის მეშვეობით მორგებულ ფავიკონს ატვირთავთ, დესკტოპზე PWA-ს ხატულა ამ მორგებულ ხატულას ასახავს. მობილური მოწყობილობის მთავარ ეკრანზე განთავსებული ხატულებისთვის გამოიყენება წინასწარ შექმნილი `icon-512.png` და `apple-touch-icon.png` ფაილები.

## შეზღუდვები

- **Push-შეტყობინებები არ არის** — Service worker-ს Push API არ აქვს იმპლემენტირებული. ამის ნაცვლად, შეტყობინებებს Electron აპი ამუშავებს.
- **ფონური სინქრონიზაცია არ არის** — ოფლაინ მოქმედებები მოგვიანებით ხელახლა შესასრულებლად რიგში არ ინახება. PWA ძირითადად მონიტორინგის პანელის სანახავადაა განკუთვნილი.
- **iOS-ის შეზღუდვები** — iOS-ზე Safari-ს PWA-ს ყველა ფუნქციის მხარდაჭერა არ აქვს (მაგალითად, ინსტალაციის მოთხოვნები ხელით უნდა შესრულდეს, ხოლო ფონური service worker-ები შეზღუდულია).
- **ქეშის ზომა** — Service worker მხოლოდ სტატიკურ რესურსებს აქეშავს. `/api/` მარშრუტებიდან მიღებული დიდი პასუხები არასოდეს ქეშირდება.
- **მორგებული ხატულები მობილურზე** — პარამეტრებში favicon-ის შეცვლა მობილურზე მთავარი ეკრანის ხატულას არ აახლებს (ამისთვის PWA-ს ხატულების ხელახლა გენერირებაა საჭირო).

## ფაილების ცნობარი

| ფაილი                                   | დანიშნულება                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Next.js-ის manifest-ის მარშრუტი (აგენერირებს `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`                   | 512×512 PNG ხატულა (Android, ჩატვირთვის ეკრანი)                              |
| `public/apple-touch-icon.png`           | 180×180 PNG ხატულა (iOS-ის მთავარი ეკრანი)                                   |
| `public/icon-192.svg`                   | 192×192 SVG ხატულა (Android-ის ადაპტიური ხატულა)                             |
| `public/apple-touch-icon.svg`           | 180×180 SVG ხატულა (Apple-ის სარეზერვო ვარიანტი)                             |