# Pich2Pich Web（網頁版，離線優先）

整個 App 的網頁版 UI。**完全離線**靠 WebRTC（用代碼互貼連線，免伺服器、免網路），有網路時可再開「中繼」做遠距/跨平台。

## 為什麼有兩個 HTML？
- `../tools/tuner.html`：**參數調校工具**（拉桿產生設定值），不是 App 本體。
- `web/index.html`：**App 本體**（地圖＋對講＋聊天＋安全路線＋連線）。

## 四個分頁
- **對講機**：在線的人、樓層、距離警報、`按住說話`（即時語音）、要求通話。
- **聊天室（LINE 式）**：上方對話切換（群組／各夥伴），可**群組廣播**或**指定單人**傳訊；文字／照片／語音；
  **永久保存**在本機，**每次開啟會插入「連線分隔線」**清楚區分不同次的對話。
- **安全路線**：畫路線、緊急聯絡人、偏航門檻、啟用守護（30s→每分鐘提醒；30 分未回應或無視逾 1 小時 → 緊急通報）。
- **連線**：顯示我的代碼；用 WebRTC 邀請碼/回應碼互貼即可離線連線。

## 三種連線方式
### A. 代碼互貼（完全離線、免伺服器）
同一個 Wi-Fi/區網下，**不需要網路、不需要伺服器**：
1. A 在「連線」→「建立邀請碼」→ 複製給 B。
2. B 貼到「對方邀請碼」→「產生回應碼」→ 複製給 A。
3. A 貼到「對方回應碼」→「完成連線」。

### B. QR 掃描（兩支手機最快）
- A 按「顯示 QR」→ B 按「掃描 QR」對準 A 畫面（用瀏覽器內建 BarcodeDetector）→ 自動帶入。
- B 產生回應碼後按「顯示 QR」→ A「掃描 QR」→ 自動完成連線。
- 代碼用 deflate 壓縮，QR 較小好掃；不支援掃描的瀏覽器（如 iOS Safari）改用相機 App 掃後貼上。

### C. 用代碼自動連線（免手貼，需中繼）
- 雙方都連到**同一個中繼**（可在區網用筆電跑 `../server/`，**免網際網路**）。
- 中繼會列出**線上夥伴**，點一下即自動連線；或在最上方輸入對方 6 碼代碼按「連線」。
- 伺服器以代碼**定向**轉送信令（非廣播），比舊版穩定。
> 純瀏覽器無法做區網 UDP 廣播自動發現，這是最接近「免手貼」且離線可行（LAN 本機中繼）的做法。

## 跨網路 / 沒有網路怎麼辦？
- **跨不同網路**：需要公網中繼（`../server/` 放 Oracle）＋ **TURN**（coturn）。在「設定 → 跨網路 TURN」填 TURN URL/帳密即可。
- **完全沒有網路**：①一支手機開 **Wi-Fi 熱點**，其他人連上 → 用代碼/QR 互貼（零伺服器）或在筆電跑中繼做免手貼；②改用 **Android 原生版 Wi-Fi Direct**；③**LoRa/Meshtastic** 硬體（公里級文字/位置）。
- **要不要蓋 Oracle**：同網/熱點離線不用；要跨網路任意上線才需要（中繼 + TURN 一台 Always Free 即可）。

> 多人：彼此兩兩配對連線即可，訊息會經 mesh（去重 + ttl）自動接力轉傳。

## 即時語音（跨平台標準格式）
`按住說話` 走 **WebRTC 音訊軌（標準 Opus）**，是真正的即時串流，與任何 WebRTC 端點相容。

## 安全路線：實際 A→B 道路規劃
- 安全分頁 →「規劃 A→B 道路路線」→ 地圖點起點 A 再點終點 B（或先按「起點=目前位置」）。
- **有網路**：用 OSRM 路網計算**沿實際道路**的路線當作守護路線。
- **完全離線**：退回 A→B 直線。要**離線也走實際道路**：在區網跑一台 OSRM/Valhalla（Docker），到「設定 → 路網規劃服務 URL」指向它（如 `http://192.168.x.x:5000`）即可離線道路規劃。
- 也可繼續用「手動編輯」逐點描繪。路線已存在本機，先在有網路時規劃好、離線仍可使用。

## 背景通知（離線）
- 純瀏覽器無法「關閉 App 仍推播」（需 VAPID 推播伺服器）。替代：
  - 安裝成 PWA；啟用「安全路線守護」時會自動申請 **Screen Wake Lock** 讓畫面亮著時持續判斷（最適合安全情境）。
  - 要真正背景常駐（鎖屏/關畫面仍運作），請用 **Android 原生版前景服務**。

## 離線地圖
OpenFreeMap 只有上線才有街道/地形。要完全離線請用 **PMTiles 本機圖磚**：
1. 用 `../tools/make_pmtiles.py` 把某區域下載成 MBTiles，再 `pmtiles convert` 成 `region.pmtiles`（見 `web/map/README.md`，注意圖磚來源使用政策）。
2. 把 `region.pmtiles` 放進 `web/map/`。
3. 設定 → 地圖來源 → 離線本機圖磚，路徑填 `map/region.pmtiles`（或用檔案選擇器）→ 套用。

## PWA（可安裝、離線開啟、通知）
含 `manifest.webmanifest` + `sw.js`。用瀏覽器「加入主畫面／安裝」即可像 App 開啟；
service worker 會快取 App 與地圖程式庫，之後可離線啟動。
> 真正的「關閉後背景推播」需要推播伺服器(VAPID)，離線情境不支援；App 開著或 PWA 執行中時通知可運作。

## 完全無網路使用（已內建）
- 程式庫已**全部下載到 `web/vendor/`**（maplibre-gl、pmtiles、qrcode），HTML 直接引用本機檔，**第一次開也不需網路**。
- 地圖三選一（設定 → 地圖來源）：
  1. 線上街道（OpenFreeMap，需網路）
  2. 離線本機圖磚（放 `web/map/region.pmtiles`）
  3. **無底圖純定位（完全免網路）**：只畫背景＋彼此位置/路線標記，零網路可用。
- 若選了「線上街道」但偵測不到網路，會**自動退回無底圖模式**，定位照常運作。

## 執行（離線情境）— 一鍵啟動
- macOS / Linux：`./start.sh`（或 `bash start.sh`）
- Windows：雙擊 `start.bat`

會自動開伺服器並印出「本機」與「同網裝置」兩個網址（含區網 IP），手機連同一 Wi-Fi/熱點開「同網裝置」網址即可。
手機建議**安裝成 PWA**（先用一次後即快取，之後可離線啟動）。

📖 **完整離線教學（含手機當伺服器、純熱點、Termux 步驟）見 [`OFFLINE-GUIDE.md`](OFFLINE-GUIDE.md)。**

> 真正零基礎建設：一支手機開熱點＋當伺服器，其他人連上即形成區網，用代碼/QR 互貼即可**完全離線**對講、聊天、看位置與樓層。

## 與 Android App 互通（需網路）
設定填**相同中繼 URL + 房間**（見 `../server/`，可部署於 Oracle Cloud Always Free）：
- ✅ 文字／照片／位置／通話請求互通。
- ⚠️ 語音：即時 WebRTC 語音是網頁端之間；與 Android 的自有 Opus 分幀不直接互通（跨平台即時語音需雙方都走 WebRTC）。
