Yun Taichi App - 雲林太極 App

雲林縣楊家老架太極武藝協會官方 App

專案資訊

• 專案名稱: yun_taichi_app
• 版本: 1.0.0
• 開發環境: Firebase Studio (Project IDX)
• 框架: Flutter 3.0+
• 目標平台: Android / iOS

功能特色

第一階段（已實作）

• ✅ WebView 載入雲林太極網站
• ✅ 下拉重新整理
• ✅ 網路狀態偵測
• ✅ 離線提示頁面
• ✅ 啟動畫面
• ✅ 返回鍵處理（網頁導航）
• ✅ Google OAuth2 登入支援
• ✅ Cookie 自動管理

第二階段（規劃中）

• ⏳ 多層快取機制
• ⏳ 離線瀏覽已快取內容
• ⏳ 背景資料同步
• ⏳ 圖片快取
• ⏳ 資料預載入

快速開始

在 Firebase Studio 中建立專案

1. 前往 Firebase Studio

   • 訪問 https://idx.google.com 或 https://firebase.google.com/studio
   • 使用 Google 帳號登入

2. 建立新專案

   • 點擊 "New Project"
   • 選擇 "Flutter" 模板
   • 專案名稱輸入: yun_taichi_app
   • 等待環境初始化（約 2-3 分鐘）

3. 複製程式碼檔案

   • 將本目錄下的所有檔案複製到 Firebase Studio 專案中
   • 確保目錄結構正確對應

4. 安裝依賴套件

   flutter pub get

5. 執行 App

   # Web 預覽（最快，推薦測試使用）
   flutter run -d chrome
   
   # Android 模擬器
   flutter run -d android
   
   # iOS 模擬器（需要 macOS）
   flutter run -d ios

專案結構

yun_taichi_app/
├── lib/
│   ├── main.dart                           # App 入口
│   ├── core/
│   │   ├── constants/
│   │   │   └── app_constants.dart          # 全域常數
│   │   ├── cache/                          # 快取模組（第二階段）
│   │   └── services/                       # 服務層（第二階段）
│   ├── screens/
│   │   ├── splash_screen.dart              # 啟動畫面
│   │   ├── webview_screen.dart             # 主 WebView
│   │   └── offline_screen.dart             # 離線頁面
│   └── widgets/                            # UI 組件
├── assets/
│   └── images/
│       ├── logo.png                        # App Logo
│       ├── splash_bg.png                   # 啟動背景
│       └── offline_icon.png                # 離線圖示
├── android/                                # Android 設定
├── ios/                                    # iOS 設定
├── pubspec.yaml                            # 套件依賴
└── README.md                               # 本文件

重要設定

修改網站 URL

編輯 lib/core/constants/app_constants.dart:

// 開發環境
static const String baseUrl = 'http://localhost:3000';

// 正式環境（發布前修改）
// static const String baseUrl = 'https://yun-taichi.com';

Android 設定

確認 android/app/src/main/AndroidManifest.xml 中的權限設定：

<!-- 網路權限（必要） -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 網路狀態檢測 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

資源檔案

將以下圖片放入 assets/images/ 目錄：

• logo.png - App Logo（建議 512x512 px）
• splash_bg.png - 啟動背景（可選）
• offline_icon.png - 離線圖示（可選）

開發指令

套件管理

# 安裝依賴
flutter pub get

# 更新依賴
flutter pub upgrade

# 清理快取
flutter clean

執行與測試

# 查看可用裝置
flutter devices

# 執行 (Web)
flutter run -d chrome

# 執行 (Android)
flutter run -d android

# 熱重載
# 在執行中按 'r' 鍵

# 完整重啟
# 在執行中按 'R' 鍵

建置

# 建置 Android APK
flutter build apk --release

# 建置 Android App Bundle (推薦用於 Play Store)
flutter build appbundle --release

# 建置 iOS (需要 macOS)
flutter build ios --release

除錯

# 分析程式碼
flutter analyze

# 執行測試
flutter test

# 查看日誌
flutter logs

與網站整合

後端設定（Rails）

在您的 Rails 專案中，需要設定 CORS（如果使用原生 HTTP 請求）：

# Gemfile
gem 'rack-cors'

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'app://yun-taichi'
    resource '*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete],
      credentials: true
  end
end

前端整合（Vue）

在 Vue app 中加入 WebView 橋接：

// 檢測是否在 App 中
const isInApp = () => {
  return window.flutter_inappwebview !== undefined
}

// 監聽 App 準備完成
window.addEventListener('flutterInAppWebViewPlatformReady', () => {
  console.log('App WebView 已準備好')
})

常見問題

Q: Firebase Studio 中找不到 Android 模擬器？

A: 在終端機執行：

flutter emulators
flutter emulators --launch <emulator_id>

Q: WebView 無法載入網站？

A: 檢查：

1. 網路權限是否設定
2. URL 是否正確
3. 開發環境網站是否運行中

Q: 如何更換 App 圖示？

A: 使用 flutter_launcher_icons 套件：

# 安裝套件
flutter pub add flutter_launcher_icons --dev

# 在 pubspec.yaml 中設定
# 執行生成指令
flutter pub run flutter_launcher_icons

Q: 如何在實體裝置上測試？

A:

1. 啟用 Android 開發者選項和 USB 偵錯
2. 連接裝置到電腦
3. 執行 flutter devices 確認裝置
4. 執行 flutter run

效能優化建議

1. 首次載入優化

   • 使用啟動畫面掩蓋載入時間
   • 預載入重要資源

2. 記憶體管理

   • 定期清理過期快取
   • 限制快取容量上限

3. 網路優化

   • 啟用 HTTP 快取
   • 圖片懶載入

發布準備

Android

1. 產生簽署金鑰

   keytool -genkey -v -keystore ~/upload-keystore.jks \
     -keyalg RSA -keysize 2048 -validity 10000 \
     -alias upload

2. 設定簽署設定

   • 建立 android/key.properties
   • 更新 android/app/build.gradle

3. 建置 App Bundle

   flutter build appbundle --release

4. 上傳到 Google Play Console

iOS

1. 需要 Apple Developer 帳號
2. 在 Xcode 中設定簽署
3. 建置並上傳到 App Store Connect

技術支援

• 詳細規劃文件: docs/yun_taichi_app_plan.md
• Flutter 官方文件: https://flutter.dev/docs
• Firebase Studio 文件: https://firebase.google.com/docs/studio

授權

Copyright © 2025 雲林縣楊家老架太極武藝協會

---

版本: 1.0.0 最後更新: 2025-01-20 維護者: Claude Code