> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 即時同步

> 本機優先應用程式，具備離線支援和自動背景同步。

## 運作方式

具有即時同步的應用程式在裝置上保留本機資料庫。讀取是即時的（本機），寫入在本機排隊，所有內容都在背景同步到伺服器。

```text theme={"theme":"material-theme-darker"}
使用者寫入 -> 本機資料庫 -> 上傳佇列 -> 伺服器 -> Postgres
                                                    |
使用者讀取  <- 本機資料庫 <- 同步複製 <---------+
```

結果：即時讀取、無載入動畫，以及在連線不佳或離線時仍能運作的應用程式。

## AI 設定的內容

要求 AI 建立即時應用程式。它會在存在合適的活躍資料庫時重複使用；否則會建立資料庫、啟用同步服務，並建立雙部分應用程式：

* **UI** - 具有本機資料庫、即時查詢和同步連接器的用戶端應用程式
* **Process** - 權杖端點、同步上傳路由和遷移執行器

認證儲存在[保管庫](/work/vault)中。AI 使用 `db` 工具將資料庫環境變數連接到流程元件。

在應用程式被視為就緒之前，資料庫必須顯示 `sync: ready`。如果同步未就緒，應用程式可能會呈現，但跨裝置即時資料將無法運作。

## 經驗法則

* 先在本機寫入。讓同步在背景上傳。
* 本機資料存在後，顯示空狀態，而不是載入動畫。
* 將使用者可見的狀態保留在同步表中，以便在重新整理和離線使用時保留。
* 將相關的本機寫入分組在一起，以便 UI 一次更新。
* 在完成即時應用程式之前驗證同步健康狀況。

## 離線應用程式殼層

UI 範本可以包含離線應用程式殼層，以便應用程式可以在首次造訪後無需網路即可重新開啟。應用程式殼層是靜態 HTML、JS、CSS 和圖示。

* **離線殼層**使應用程式無需網路即可開啟
* **同步**在離線時保持應用程式資料可用

結合：應用程式無需網路即可開啟、顯示最新同步資料、排隊新寫入，以及在連線恢復時同步。

## 何時使用即時同步

| 適合            | 過度設計        |
| ------------- | ----------- |
| 工作管理員和筆記應用程式  | 靜態行銷頁面      |
| 協作工具          | 一次性表單提交     |
| 連線不佳的現場應用程式   | 唯讀宣傳冊網站     |
| 任何應該感覺即時的應用程式 | 沒有離線價值的應用程式 |

## 平台變數

Kazzle 自動將一小組環境變數注入到每個應用程式流程中。這些與您自己的[保管庫機密](/work/vault)分開。

| 變數                                | 說明                       |
| --------------------------------- | ------------------------ |
| `PORT`                            | 您的流程應該監聽的連接埠             |
| `HOST`                            | 要繫結的主機名稱（通常為 `0.0.0.0`）  |
| `KAZZLE_API_URL`                  | Kazzle 執行階段協助程式使用的基底 URL |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | 同層元件的執行階段 URL            |

### 同層 URL

當應用程式有多個元件（例如 `web` UI 和 `server` 流程）時，Kazzle 可以注入同層元件的 URL：

```
# 在「web」部分中：
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# 在「server」部分中：
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

當同層已部署時，注入的值指向該已部署的元件。否則它指向該同層的目前開發位址。