有點旅譜
已上線：https://ing0001000-jpg.github.io/kyushu-2026/
手機用 Safari／Chrome 開上面的網址 →「加入主畫面」，桌面會出現⛩️圖示（名稱「有點旅譜」，諧音「有點離譜」，也是「旅行的譜」），點開是全螢幕、沒有網址列，離線也能用。
家人朋友出國用的手機 App。純 HTML／CSS／JS，沒有 CDN 或套件依賴，唯一的外部資源是 Archivo Black 網路字型（載不到時自動退回系統字型），所以在國外沒訊號時也能用。
一個 App，多趟旅行
引擎（app.js / app.css / admin.js）與行程資料是分開的：
data/site.js 站台設定 + 行程索引（只有選單需要的欄位）
data/art/_core.js 繪圖工具、圖示、通用場景
data/art/jp-kyushu.js 插畫包：九州 8 城（跨旅行共用，再去同一城市直接指回來）
trips/kyushu-2026/ 這趟的 trip / guide / places / packing
- 網址帶行程代號：
#/kyushu-2026/today、#/kyushu-2026/day/3，可以直接分享給旅伴
- 進 App 後在標題列點行程名（或
#/trips）切換行程；舊書籤 #/today 會自動導到上次看的那趟
- 只有點進去的那趟才會載入資料，Service Worker 第一次瀏覽時自動把它收進離線快取，新增行程不必改
sw.js
- 行程選單裡，封存的行程收在最下面的「已封存」；沒指定要看哪趟時也不會自動挑封存的
- 打包勾選、自訂項目、匯率是每趟各一份（
hz:<行程>:state）；深淺色主題與入口密碼是全站共用
- 入口密碼一組，過了就看得到所有行程 —— 只是擋路人與搜尋引擎，不是資安機制
新增、複製、封存、刪除
都在後台 →「設定與發布」：
- 新增空白行程：填代號／名稱／起訖日／主色。會產生一份骨架存成這台裝置的草稿（天數自動依日期展開），編輯完按「發布到 GitHub」才上線。
- 複製這趟當範本：把目前編輯的這趟（每日行程、指南、打包清單、收藏地點）整份複製成新的一趟，天數不變、日期從新的出發日重排。預設會清空航班、租車、住宿與費用，勾選才保留。一樣先存成草稿。
- 封存：收到行程選單最下面，資料都還在，可以隨時取消封存。要發布之後團員的選單才會跟著變。
- 刪除：會立刻用一個 commit 從 GitHub 拿掉
trips/<代號>/ 底下所有檔案，並更新 data/site.js。要先設好權杖，還要輸入代號確認；至少要留一趟。要救回來只能到 GitHub 上 revert 那個 commit。
新行程還沒有專屬插畫時會退回通用場景，不會壞掉。
五個分頁
| 分頁 | 內容 |
|---|
| 今天 | 出發前：倒數 ＋ 待辦／打包進度。旅途中：最上面跟著時間走（現在在做什麼、在哪裡、接下來往哪，例如「小阿姨團 4 人搭機中 ✈」「現在在福岡，下午往佐世保出發」），下面是接下來 3 項、時間軸（標出進行中與已過去）、今晚住宿、該區美食。結束後：全程回顧。 |
| 行程 | 9 天列表 → 單日詳情，每個地點一顆 Google Maps 導航鈕 |
| 打包 | 6 大類 41 項，加上每個人自己輸入的「我自己要帶的」；勾選狀態與自訂項目都存在自己手機的瀏覽器裡 |
| 指南 | 8 個地區的美食／景點、日本自駕、溫泉禮儀、免稅、天氣穿搭、緊急聯絡、常用日文 |
| 資訊 | 4 段航班、租車取還、6 筆訂房（含地址電話）、費用總表、日幣換算 |
另有 #/admin 後台（入口在「資訊」分頁最下方），可直接編輯行程並發布到 GitHub。
部署
已部署在 GitHub Pages（公開 repo，這是免費帳號開 Pages 的唯一方式）。已加 robots.txt 與 noindex meta 擋搜尋引擎收錄，但 repo 本身在 GitHub 個人頁面上是看得到的 — 網址別貼到公開社群。
改完內容後重新上線：
cd "/Users/shelby/AI開發專案/旅遊助手APP" && git add -A && git commit -m "更新行程" && git push
推上去後約 1 分鐘生效。
- 只改了
trips/ 或 data/site.js：團員下次打開 App 就會拿到新資料（Service Worker 對行程資料是 network-first）。想讓開著的 App 也自動更新，要把 data/site.js 裡那趟的 rev 改成現在的時間（後台發布會自動做）。
- 改了引擎（
app.js、app.css、admin.js、index.html、圖示、插畫）：記得把 sw.js 裡的 CACHE 版本號 +1，否則團員手機上的舊快取不會更新。
怎麼跑（本機開發）
cd "/Users/shelby/AI開發專案/旅遊助手APP" && node tools/dev-server.js
然後瀏覽器開 http://localhost:4173。這支伺服器一律送 Cache-Control: no-store，改完檔案重整就看得到新版；用 python3 -m http.server 的話瀏覽器會死抓舊的 JS 不放。
手機要連同一個 Wi-Fi 的話，把 localhost 換成電腦的區網 IP。注意：http://192.168.… 不是安全來源，瀏覽器不提供 SHA-256，入口與後台密碼都會一律判定錯誤（後台草稿只存在各自裝置，也沒辦法從電腦幫手機關掉）。手機上要測請用線上的 https 網址，本機開發就在電腦上用 localhost。
兩種版本
1. 專案版（index.html） — 完整 PWA。用 http/https 開啟時會註冊 Service Worker，把全部檔案 precache 起來，之後真正離線也能開。放到任何靜態主機（Netlify、Vercel、GitHub Pages）都可以直接用。
2. 單檔版（dist/<行程>.html，例如 dist/kyushu-2026.html） — 一趟行程的所有 CSS／JS／資料／圖示 inline 成一個檔案。
node tools/build-single.js [行程代號] # 預設 kyushu-2026
單檔版沒有 Service Worker（Artifact 平台的外層 <head> 由平台產生，無法註冊 SW），是「載入後靠瀏覽器快取」的準離線。功能與「加入主畫面」都正常。
Service Worker 的註冊只在真實瀏覽器裡有效，開發用的內嵌瀏覽器會擋掉 SW 腳本抓取。要驗證離線，請用 Safari／Chrome 開專案版，載入一次後開飛航模式重整。
加到手機主畫面
- iPhone：Safari 開連結 → 分享 → 加入主畫面
- Android：Chrome 開連結 → 選單 → 安裝應用程式／加到主畫面
密碼門檻
第一次打開會要求填名字和進入密碼，通過後記在該台裝置，之後不再問。名字只存在自己手機上，不會回傳給任何人。
密碼在後台的「設定與發布」裡自己設，data/site.js 只存 SHA-256 雜湊，看不到密碼原文。要設兩組：
| 給誰 | 用途 |
|---|
| 進入密碼 | 全團 6 人 | 打開 App 要輸入 |
| 後台密碼 | 只有你 | 進 #/admin 要輸入 |
這是「擋一下」，不是資安機制。 repo 是公開的（免費帳號開 GitHub Pages 的唯一方式），行程、住宿、電話都以明文放在 data/*.js 裡。會看網頁原始碼的人可以完全繞過這道門看到全部內容。它擋得住的是路過隨手點開連結的人，擋不住有心人。網址仍然不要貼到公開社群。
真正要防的話得把資料加密後才上傳（沒有密碼連原始碼都看不出內容），那是另一種做法，需要時再說。
後台管理
入口：「資訊」分頁滑到最下面的「後台管理」，或直接開 #/admin。
可以改：9 天行程的每個時間軸項目（新增／刪除／上下移）、航班、租車、住宿、費用、收藏地點（改備註、換分區、刪除）、打包清單、行前待辦、指南的美食景點。
兩段式儲存，這點很重要：
- 改了就存成草稿 — 一打字就自動存，只在你這台裝置生效，其他人看到的還是舊的。App 畫面會立刻套用，可以先自己確認。
- 按「儲存並發布」 — 每一頁最下面都有一條固定的發布列，左邊顯示狀態（「已存成草稿，還沒發布」／「與線上版一致」／發布成功或失敗的原因），右邊是按鈕。按下去才會寫回 repo，團員開著的 App 大約 1–2 分鐘內自動換成新版（見下一節）。
發布會把這趟的 4 個資料檔、data/site.js、sw.js（快取版本號 +1）包成一個 commit，GitHub Pages 只部署一次，團員不會抓到一半新一半舊的資料。
「丟棄草稿」會把這趟的行程資料還原成線上版。密碼、封存、行程清單這些站台設定存在另一份草稿裡，不會被丟掉，但一樣要發布之後其他裝置才會生效。設完密碼請記得發布。
團員怎麼收到更新
不用重開 App，也不用另外申請任何服務：
- 發布時，
data/site.js 裡那趟的 rev 會設成發布時間。
- 團員的 App 開著時，每 30 秒（以及從背景切回來、恢復網路時）抓一次
data/site.js，只有約 1 KB。
- 看到正在看的那趟
rev 變了，就重抓這趟資料、原地重畫（捲動位置不變），底部跳出「行程已更新（10/30 11:15 發布）」。
所以從按下發布到團員畫面換掉，大約是 GitHub Pages 部署時間（約 1 分鐘）加上最多 30 秒。
- 正在輸入文字時只換資料、不重畫，免得打斷打字。在後台頁面時不檢查，免得蓋掉正在改的東西。
- 有站台草稿的裝置（也就是你自己的編輯手機）以草稿為準，不會被線上的行程清單蓋掉。
- 沒網路時什麼都不做，照樣用離線快取；網路很慢時，4 秒內沒回應就先用快取顯示。
- 單檔版（
dist/*.html）沒有這個功能，資料是建置當下的版本。
記住後台密碼
登入時預設勾著「在這個瀏覽器記住我」，之後同一個瀏覽器開後台就不用再輸入。存的是密碼的雜湊（data/site.js 裡本來就公開的那一串），不是密碼本身；後台密碼一換，所有記住的登入都會自動失效。共用的電腦請取消勾選（只記到關掉分頁為止），或用後台最下面的「登出後台」。
GitHub 權杖
發布需要一組 GitHub 存取權杖，在後台「設定與發布」裡填，存在你這台瀏覽器的 localStorage。
建議用 Fine-grained personal access token：
- Repository access：只勾
kyushu-2026 這一個
- Permissions → Repository permissions → Contents: Read and write
- 設一個到期日
那組權杖等於這個 repo 的鑰匙。手機借人、遺失或換機時，記得到 GitHub 設定頁把它撤銷。
忘記後台密碼（密碼只存雜湊，原文救不回來，只能重設）：
- 在電腦上把
data/site.js 的 gate.admin 改成 "" 並 push。進入密碼不用動，團員不受影響。
- 手機開
#/admin，如果還在問舊密碼（發布過的裝置會留一份站台草稿），按「忘記密碼？」。只會丟掉這台的站台草稿，GitHub 權杖和行程草稿都留著。
- 出現「第一次進後台」就設新密碼，然後到「設定與發布」按一次發布。
從清空到設好新密碼之間，別人開 #/admin 也能設一組，但只存在他自己的裝置上，沒有你的權杖什麼都發布不了。
匯入 Google 地圖收藏
trips/<行程>/places.js 是從 Google 地圖的「已儲存清單」匯入的，顯示在「指南」每一區的「我的收藏」，每筆都用座標導航。
node tools/import-places.js <匯出檔.csv|.json|.geojson|.kml> [--trip=kyushu-2026] [--resolve]
- 吃 Google 地圖清單匯出的 CSV、Takeout 的 GeoJSON、我的地圖的 KML
- 分區錨點與關鍵字從
trips/<行程>/trip.js 的 regions[] 讀（anchor、keywords），讀不到才用工具內建的九州預設值
- 用座標判斷屬於哪一區（離錨點最近且 40 公里內），沒座標就退回名稱關鍵字比對，都判不出來的丟進「未分區」
- CSV 匯出常常只有短網址沒座標，加
--resolve 會連網展開後再判斷
- 會整個覆蓋
trips/<行程>/places.js，在後台改過的收藏地點會被蓋掉
改內容
日常改行程建議直接用後台（上一節）。要在電腦上改檔案的話，改完重整就生效（改單檔版要重跑 node tools/build-single.js）：
This is the beginning of the README. Read the rest at the original. Read the full README ↗
