專案目的與想解決的問題 結合數位神諭與雲端香火，落實傳統文化的數位轉型、推廣廟宇觀光，也是舒緩生活壓力的最佳工具。 專案落實未來之都的傳統文化數位轉型，並扣合 SDGs 永續城鄉、氣候行動。
核心功能摘要
- 數位神諭：結合程式數據與千年籤詩智慧，一鍵擲筊求籤，立即獲得最貼近您職涯、愛情、生活的指引。
- 雲端香火：壓力山大、時間寶貴時，您可線上選擇廟宇進行拜拜，是舒緩生活壓力的最佳選擇。
Demo Screenshot / GIF
| 功能 | 說明 | 截圖 |
|---|---|---|
| 歡迎頁面 | 這邊我們有做一點小巧思，讓背景有一個 流光 效果，給人一種香火鼎盛的感覺。 |  |
| 搖一搖抽籤 | 透過加速度感應的方式，以搖動手機模擬實際抽籤的動作，觸發抽籤動畫。 |  |
| 搖一搖擲筊（聖筊） | 這裡也是可以透過搖動觸發擲筊，特別的是，我們有設定不同的加速度軸向，必須是用擲筊動作才能觸發，而不是隨意的晃動就行了。 |  |
| 搖一搖擲筊（笑筊） | 如果擲出的不是聖筊，就得回頭重抽一支籤。 |  |
| 解籤 | 我們使用廟宇常見的 六十甲子籤 作為籤詩集，並透過 AI 進行翻譯與解籤，使用者會隨機取得其中一支籤。 |  |
| 推薦宮廟 | 在抽籤的最後會推薦一間台北市的廟宇，同時提供周遭的觀光景點資訊，這些資料來源都是台北市觀光局的即時 API。 |  |
| 誠心奉香 | 在拜拜的環節，使用者選擇廟宇後，同樣可以透過拜拜的動作觸發動畫。 |  |
| 獻貢 | 最後可以擺放水果到供桌上，我們可以從從容容地放置供品，也可以匆匆忙忙地把...希望我們不會被吉。 |  |
架構圖
graph TD
subgraph Client [Flutter App Client]
subgraph UI [UI Layer]
Welcome[歡迎頁面]
TempleSel[宮廟選擇]
Ritual["祭祀互動 (奉香/獻貢)"]
Drawing[抽籤/擲筊]
Result[解籤結果]
Rec[推薦宮廟]
end
subgraph Logic [Business Logic Layer]
SensorCtrl["感測器控制器 (加速度計)"]
TempleSvc[Temple Service]
AttractionSvc[Attraction Service]
AISvc[AI Interpretation Service]
end
subgraph Data [Data Layer]
Assets["靜態資源 (JSON/CSV/Images)"]
end
end
subgraph External [External Services]
TaipeiAPI[臺北市政府開放資料 API]
TourismAPI[台北旅遊網 API]
AIModel["AI 模型 (LLM)"]
end
User((使用者)) --> UI
TempleSel --> TempleSvc
Ritual --> SensorCtrl
Drawing --> SensorCtrl
Result --> AISvc
Rec --> AttractionSvc
TempleSvc --> Assets
AttractionSvc --> TourismAPI
AISvc --> AIModel
TempleSvc -.-> TaipeiAPI
狀態圖
任何狀態都能回到主畫面
flowchart LR
%% 定義節點 (Nodes)
Main[主頁面]
%% 上方路徑：拜拜流程 (已修改順序)
SelectTemple[選擇寺廟]
Offerings[放供品]
ShakePhoneWorship["拜神明(搖手機)"]
%% 下方路徑：抽籤流程
DrawLotFunc[抽籤功能]
CastBlocks["擲筊(搖手機)"]
ShakePhoneLot["抽籤(搖手機)"]
ShowResult[顯示籤內容]
Interpret[解籤]
%% 新增節點
Info[寺廟介紹與<br>周遭景點]
%% 連線關係 (Connections)
%% 主頁面分流
Main --> SelectTemple
Main --> DrawLotFunc
%% 拜拜流程連線 (修改後：選擇 -> 拜拜 -> 放供品)
SelectTemple --> ShakePhoneWorship
ShakePhoneWorship --> Offerings
Offerings --> Main
%% 抽籤流程連線
DrawLotFunc --> ShakePhoneLot
ShakePhoneLot --> CastBlocks
%% 擲筊邏輯
CastBlocks -- 非聖筊 --> ShakePhoneLot
CastBlocks -- 聖筊 --> ShowResult
%% 顯示結果後的路徑 (修改後：解籤 -> 介紹 -> 主頁)
ShowResult --> Interpret
Interpret --> Info
Info --> Main
使用到的主要技術堆疊（Tech Stack）
| 類別 | 使用技術/版本 | 備註 |
|---|---|---|
| 前端框架 | Flutter (Dart SDK >=3.3.0 <4.0.0) | 使用原生介面、重力加速度感測模擬祭祀流程、幾何轉換動畫 |
| 後端框架 | - | 本專案主要為客戶端應用，直接整合開放資料 API |
| 資料儲存 | JSON / CSV Assets | 用於儲存籤詩、解籤內容與廟宇位置等靜態資料 |
| 外部 API | 旅遊資訊 API | https://www.travel.taipei/open-api/swagger/docs/V1 |
| 外部 API | 臺北市寺廟一覽 | https://data.taipei/dataset/detail?id=b5f043ce-00be-4404-b975-02e29fe10f51 |
本地端執行方式
執行本專案前，請確認您的環境已安裝以下必要組件：
- FVM (Flutter Version Management)
- Xcode (若要執行 iOS 模擬器)
- Android Studio (若要執行 Android 模擬器)
步驟說明：
- 複製專案庫：
git clone [email protected]:taipei-doit/townpass2025-cloud-temple.git
- 進入專案目錄：
cd townpass2025-cloud-temple - 安裝依賴套件 (建議使用 FVM)：
# 若尚未安裝 fvm dart pub global activate fvm # 安裝專案指定 Flutter 版本 fvm install # 安裝依賴 fvm flutter pub get
- 啟動服務：
fvm flutter run
需要設定的環境參數（.env example）
本專案為純 Client-side 服務，無需設定環境變數。同時使用到的觀光局 API 為公開 API，無需 API Key。
| 功能編號 | 功能名稱 | 簡述 | 資料來源描述 |
|---|---|---|---|
| 4.1 | 數位神諭 | 結合程式數據與千年籤詩智慧，提供一鍵擲筊求籤功能。 | 內部籤詩資料庫 / 演算法 |
| 4.2 | 雲端香火 | 提供線上選擇廟宇進行拜拜的互動體驗，包含重力感測模擬。 | 內部互動邏輯 |
| 4.3 | 廟宇資訊整合 | 整合政府觀光資料，提供臺北市寺廟資訊查詢。 | 臺北市寺廟一覽、旅遊資訊 API |
- GPT-5.1
- Gemini 2.5 Pro
- Claude Sonnet 4.5
- 其他 SaaS 服務（無法得知具體模型，於下方說明使用情境）
程式碼架構理解：
- 在開發初期快速釐清 townpass 的程式架構，以及我們該如何加入自己的程式。
程式碼產生：
- 主要用於複雜的動畫與特效，至於程式架構與流程、核心業務邏輯，則由開發者掌控。
UI/UX 設計協助：
- 使用 Stitch 進行初步的畫面設計與靈感啟發，後續由開發者補全細節，並使顏色符合 townpass 的規範。
圖片生成
- 使用 GPT 5.1 與 Gemini 2.5 Pro 產生部分示意圖。後遇到細節不符需求，改由開發者使用 Inkscape 與 GIMP 補足。
文字生成：
- 將公開無著作權的詩籤透過 AI 進行解籤與白話文翻譯。
- 明確限制 AI 協作範圍：盡可能讓 AI 只參與非核心邏輯的部分。即動畫、特效、UI 設計靈感、圖片生成與文字翻譯等。狀態機、業務邏輯、資料處理等核心程式碼皆由開發者撰寫。
- 人工 Code Review：所有 AI 產生的程式碼都經過人工審查，確保邏輯正確。
- 文本正確性檢查：對於 AI 解籤，所有生成的文本皆有由開發者人工確認內容正確且敘述無異常。
- AI 產出後 Refactor：整合進現有框架時經過重構。
- 幻覺 (Hallucination)：對 AI 產生的資訊進行人工雙重確認。
- 安全性：已盡力在核心邏輯上進行人工審查。