旅遊助手

已上線：https://ing0001000-jpg.github.io/kyushu-2026/

手機用 Safari／Chrome 開上面的網址 →「加入主畫面」，桌面會出現⛩️圖示，點開是全螢幕、沒有網址列，離線也能用。

家人朋友出國用的手機 App。純 HTML／CSS／JS，沒有任何外部依賴（不載入 CDN、不載入網路字型），所以在國外沒訊號時也能用。

一個 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」才上線。 新行程還沒有專屬插畫時會退回通用場景，不會壞掉。

五個分頁

分頁	內容
今天	出發前：倒數 ＋ 待辦／打包進度。旅途中：最上面跟著時間走（現在在做什麼、在哪裡、接下來往哪，例如「小阿姨團 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 分鐘生效。記得同時把 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。

兩種版本

1. 專案版（index.html） — 完整 PWA。用 http/https 開啟時會註冊 Service Worker，把全部檔案 precache 起來，之後真正離線也能開。放到任何靜態主機（Netlify、Vercel、GitHub Pages）都可以直接用。

2. 單檔版（dist/kyushu.html） — 所有 CSS／JS／資料／圖示 inline 成一個檔案。

node tools/build-single.js

單檔版沒有 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 天行程的每個時間軸項目（新增／刪除／上下移）、航班、租車、住宿、費用、收藏地點（改備註、換分區、刪除）、打包清單、行前待辦、指南的美食景點。

兩段式儲存，這點很重要：

1. 改了就存成草稿 — 只在你這台裝置生效，其他人看到的還是舊的。App 畫面會立刻套用，可以先自己確認。
2. 按「發布到 GitHub」 — 才會寫回 repo，約 1 分鐘後全團拿到新版。

發布會一併把 sw.js 的快取版本號 +1，團員手機的舊快取才會失效 — 這是手動改檔案時最容易忘記的一步。

「丟棄草稿」會把這台裝置還原成線上版。注意：密碼也是存在草稿裡的，設完密碼沒發布就丟棄草稿，密碼會一起消失。設完密碼請立刻發布。

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 的欄位清空，再 push。

匯入 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）：

• trips/<行程>/trip.js — 每天行程、航班、租車、住宿、費用、regions[]。map 欄位放當地地名，導航鈕用 Google Maps 搜尋 URL 帶入，所以不需要經緯度。
• trips/<行程>/guide.js — 地區美食景點、實用資訊、常用會話
• trips/<行程>/packing.js — 打包清單（window.PACKING）與行前待辦（window.TODOS）
• trips/<行程>/places.js — 從 Google 地圖收藏匯入的地點，由 tools/import-places.js 或後台產生
• data/site.js — 密碼雜湊、GitHub repo 設定與行程索引，由後台產生
• data/art/_core.js、data/art/<包>.js — 城市印象插畫與線性圖示，全部是內嵌 SVG，零外部請求

regions：地區的單一真相

TRIP.regions[] 同時決定四件事，以前這份清單散在四個檔案裡：

{ id: 'fukuoka', name: '福岡',
  art: 'jp-kyushu/fukuoka',        // 用哪張插畫（跨旅行共用的圖庫 key）
  anchor: '33.59,130.40',           // import-places 分區用
  keywords: ['博多', '天神'],
  palette: { rb, sky, far, mid, near, pop, pale } }   // UI 與插畫共用的 6 色

色盤由 app.js 開機時注入 <style id="hz-palette">，所以換一趟旅行不必動 app.css。 後台的地區下拉、dayRegion、指南分區也都認同一組 id。

城市印象插畫

每座城市一張，不是地標拼貼：先整理該城市 5–8 個有辨識度的旅行印象（地形季節、建築街道交通、食物植物動物、色彩氣候、實際會遇到的生活場景），再挑其中 3–5 個最能代表城市氣質的，簡化幾何化之後重新構圖。例如福岡是「中洲屋台的暖光 × 河 × 被壓扁的都市天際線 × 放大的紅燈籠」，別府是「屋瓦之間升起的八道湯煙 × 地獄的朱紅與鈷藍」。

風格是 modern folk illustration／editorial travel poster／naive art：大面積平面色塊、明確視覺焦點、前中後景分層、刻意留白，辨識度來自輪廓色彩與象徵物而不是寫實描繪，並且刻意做了比例變化（放大的燈籠與稻穗、縮小成模型的鳥居與辻馬車）。

• 配色：每座城市一組 6 色的有限色盤，定義在 app.css 的 [data-reg="…"]：--c-sky（紙／天空）、--c-far（遠景）、--c-mid（中景）、--c-near（近景墨色）、--c-pop（整張畫唯一的高彩度點綴）、--c-pale（光／霧／白牆），另外 --rb 是這個地區在 UI 上的主色。深色主題會把同一組色盤換算成「夜間版海報」：紙色壓暗、點綴色反而更亮，構圖不變。
• 質感：ART.defs 裡有兩個手繪抖動濾鏡（hz-hand 給大色塊、hz-hand2 給細節）讓邊緣像剪紙或蠟筆塗出來的，再加一層 hz-grain 顆粒疊在畫面上；整個介面的底也墊了一張紙纖維（--fiber）。濾鏡由 ART.mount() 在啟動時塞進文件裡，全站共用一份。
• 畫布：400 × 132（旅遊海報橫幅比例）。焦點要放在 x 140–260，因為指南分頁的小圖章會裁切成中央的正方形。
• 校稿：tools/art-preview.html 會把 9 張並排出來（?cols=2&only=aso,yufuin 可放大看指定幾張、?dark=1 看夜間版）。

注意：打包清單的勾選狀態用 群組id:項目id 當 key 存在 localStorage。改文字沒關係，但改 id 會讓已勾選的項目變回未勾選。

改版後記得把 sw.js 裡的 CACHE 版本號 +1，否則使用者的舊快取不會更新。

其他

• tools/make-icons.js — 用 Node 內建 zlib 產生鳥居圖示 PNG，不需要 npm install
• tools/art-preview.html — 插畫校稿板，開 http://localhost:4173/tools/art-preview.html
• 唯一的外部資源是 Google Fonts 的 Archivo Black（只用在數字與英文標籤，Latin 子集）。離線或載入失敗時自動退回系統字型，不影響任何功能；中文一律使用系統字型，刻意不載 CJK 網頁字型（那會是好幾 MB，離線就毀了）
• 打包勾選、自己加的打包項目、匯率、深淺色偏好存在各自手機的 localStorage，不會在團員之間同步（換手機或清除瀏覽器資料就會不見）
• 行程內容則是全團共用的（存在 repo 裡），透過後台發布同步
• 深淺色會跟隨系統，右上角按鈕可手動切換

資料來源與正確性

行程、時間、價格、住宿名稱全部擷取自 2026九州行程0927~1005.xls，未經改寫。

• 飯店地址與電話為網路查證結果，出發前建議再和訂房確認信核對。
• 飯店卡片的插畫是手繪 SVG，不是實際照片 — Artifact 平台的 CSP 會擋掉所有外部圖片，飯店官方宣傳照也有版權。要看真實照片請點卡片上的「地圖・照片」（Google 地圖相簿）或「官方網站」。
• 長崎住宿除了 JPY 29,486，另有一筆 TWD 7,228（4 人），原始表格沒寫明對應哪一間房。
• 「指南」分頁的景點與美食是一般旅遊建議，不是已排定的行程。
• 營業時間、票價與活動舉辦與否，請以官方即時公告為準。

今天頁怎麼知道「現在」

• 每一項照 time 排上時間軸：08:00–11:20 有頭有尾、10:00 只有開始、～22:00 只有結束；沒寫時間的平均塞在前後兩個有寫的時間之間（上午從 9:00、下午從 12:00、晚上從 18:00 起算，晚上排到 22:00），所以「約 13:30」這種是估的。
• 標籤裡有航班號（BR／IT…）的會被認成航班，顯示「〇〇團 搭機中 ✈」和抵達時間。同一時間有兩件事（例如第 9 天一團在飛、一團還在機場）會列在「同一時間」。
• 「在哪裡」讀的是每個時段的 where（在 trips/<行程>/trip.js 每個 block 上，例如 "where": "佐世保 → 長崎"）。後台改行程不會動到它；要改的話直接改那個欄位。
• 用手機的時間。每分鐘、以及從背景切回來時自動更新。
• 預覽某個時間點：網址加 ?now=2026-09-28T07:30。

App 圖示

原稿是 tools/icon.html（跟插畫同一套手繪濾鏡、紙張顆粒與「出發」色盤：阿蘇般的平頂火山、太陽、海中的朱紅鳥居）。改完用 Chrome headless 截圖成三個尺寸：

CH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
for n in 512 192 180; do "$CH" --headless=new --hide-scrollbars --default-background-color=00000000 --window-size=$n,$n --screenshot=icons/icon-$n.png "http://127.0.0.1:4173/tools/icon.html?size=$n"; done
mv icons/icon-180.png icons/apple-touch-icon.png

Chrome 截完圖有時候不會自己結束，檔案出來之後按 Ctrl+C 就好。已經加到主畫面的手機要刪掉重新加入，才會換成新圖示。