部署指南

建置指令

Flutter 支援從同一程式碼庫建置多個平台的應用程式。以下是各平台的建置指令：

# Android APK（通用）
flutter build apk

# Android App Bundle（Play Store 推薦）
flutter build appbundle

# iOS（需要 macOS + Xcode）
flutter build ios

# Web
flutter build web

# macOS（需要 macOS + Xcode）
flutter build macos

# Windows
flutter build windows

Android 部署

APK 建置

# 產生 release APK
flutter build apk --release

# 輸出位置：
# build/app/outputs/flutter-apk/app-release.apk

App Bundle 建置（Play Store）

# 產生 AAB（Google Play 推薦格式）
flutter build appbundle --release

# 輸出位置：
# build/app/outputs/bundle/release/app-release.aab

Play Store 上架步驟

1. 在 Google Play Console 建立應用程式
2. 設定簽名金鑰（keystore）
3. 上傳 AAB 檔案
4. 填寫商店資訊、螢幕截圖、內容分級
5. 提交審核

Android 建置與部署（完整指南）

把你的 Flutter App 送進 Android 手機——比想像中簡單，前提是你的 USB 線不是只能充電的那種。

前置需求

flutter doctor

確認 Flutter、Android toolchain、Connected device 三項都打勾。

一、手機開啟開發者模式

1. 進入 設定 → 關於手機
2. 連續點擊 版本號碼 7 次 → 出現「您已成為開發者」
3. 回到 設定 → 系統 → 開發者選項
4. 開啟 USB 偵錯 (USB Debugging)
5. USB 連接電腦後，手機會彈出「允許 USB 偵錯」→ 點 允許

二、確認手機已連接

flutter devices

應該看到你的 Android 裝置：

Pixel 7 (mobile) • abc12345 • android-arm64 • Android 14

三、Debug 模式直接運行

# 自動選擇裝置
flutter run

# 指定裝置（多裝置時）
flutter run -d abc12345

支援 Hot Reload，改一行存一下就能看到效果——工程師的即時滿足感。

四、建置 Release APK

方法 A：APK（通用，可直接傳輸安裝）

flutter build apk --release
# 產出：build/app/outputs/flutter-apk/app-release.apk

方法 B：App Bundle（上架 Google Play）

flutter build appbundle --release
# 產出：build/app/outputs/bundle/release/app-release.aab

五、安裝 APK 到手機

# 方法 1：adb 安裝
flutter build apk --release
adb install build/app/outputs/flutter-apk/app-release.apk

# 已有舊版本？加 -r 覆蓋
adb install -r build/app/outputs/flutter-apk/app-release.apk

# 方法 2：flutter 直接安裝
flutter install --release

方法 3：手動傳檔 — 把 APK 傳到手機（USB/雲端/LINE），手機上點開安裝。系統提示「允許安裝未知來源」就允許。

六、一行指令：建置 + 安裝

flutter build apk --release && adb install -r build/app/outputs/flutter-apk/app-release.apk

複製貼上，去泡杯咖啡，回來就好了。

七、簽署 APK（正式發布用）

Debug 版本用預設簽署金鑰，正式發布需要你自己的。

1. 產生 Keystore

keytool -genkey -v -keystore ~/idempiere-release.jks 
  -keyalias idempiere -keyalg RSA -keysize 2048 -validity 10000

請妥善保管此檔案和密碼。丟了就像忘了保險箱密碼——裡面的東西還在，但你再也打不開。

2. 建立 key.properties

在 android/ 目錄下建立（不要加入版本控制）：

storePassword=你的密碼
keyPassword=你的密碼
keyAlias=idempiere
storeFile=/Users/你/idempiere-release.jks

3. 修改 android/app/build.gradle.kts

在 android { 區塊前加入：

val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}

在 android { 區塊內加入 signingConfigs 並修改 buildTypes：

signingConfigs {
    create("release") {
        keyAlias = keystoreProperties["keyAlias"] as String
        keyPassword = keystoreProperties["keyPassword"] as String
        storeFile = file(keystoreProperties["storeFile"] as String)
        storePassword = keystoreProperties["storePassword"] as String
    }
}
buildTypes {
    release {
        signingConfig = signingConfigs.getByName("release")
    }
}

4. 建置已簽署的 APK

flutter build apk --release

Android 常見問題

iOS 部署

建置步驟

# 建置 iOS release
flutter build ios --release

# 開啟 Xcode 進行 archive
open ios/Runner.xcworkspace

App Store 上架步驟

1. 在 Xcode 中選擇 Product → Archive
2. 在 Organizer 中選擇 Distribute App
3. 選擇 App Store Connect
4. 在 App Store Connect 填寫應用資訊
5. 提交審核

Web 部署

# 建置 Web 版本
flutter build web

# 輸出位置：
# build/web/

# 部署至任何靜態檔案伺服器
# 例如 Nginx、Apache、Firebase Hosting、GitHub Pages

Web 版本產生的是靜態檔案（HTML、CSS、JS），可以部署到任何支援靜態檔案的伺服器。

Nginx 設定範例

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/idempiere-mobile/build/web;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

macOS / Windows 部署

# macOS
flutter build macos --release
# 輸出: build/macos/Build/Products/Release/

# Windows
flutter build windows --release
# 輸出: build/windows/x64/runner/Release/

白牌設定（White-Label）

iDempiere Mobile 支援透過伺服器端的 AD_SysConfig 設定項進行白牌客製化，無需修改 App 程式碼：

這些設定由 BrandingConfig 在登入後從伺服器載入，自動套用到 App 的外觀和功能開關。

Material 3 色彩種子

MOBILE_SEED_COLOR 使用 hex 色碼（不含 #），Flutter 的 ColorScheme.fromSeed() 會自動產生完整的色彩方案。例如：

• 2196F3 — 藍色（預設）
• 4CAF50 — 綠色
• FF5722 — 橘紅色
• 9C27B0 — 紫色

API Key 安全設定

為強化 iDempiere Mobile App 的安全性，支援透過 Nginx 反向代理實施 API Key 驗證機制。只有持有正確 Key 的用戶端才能存取 iDempiere 後端 API。

運作原理

啟用 API Key 功能後，App 會在每個 API 請求中自動注入 HTTP 標頭：

X-API-KEY: <your-secret-key>

Nginx 伺服器設定

在 Nginx 設定檔中加入 API Key 驗證區塊：

server {
    listen 443 ssl;
    server_name erp.example.com;

    # ... SSL 設定 ...

    location /api/ {
        # 1. 定義密鑰（避免特殊字元）
        set $api_secret "your-secret-key-here";

        # 2. 檢查 Header
        if ($http_x_api_key != $api_secret) {
            return 403; # 拒絕存取
        }

        # 3. 轉發至 iDempiere
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

產生安全金鑰

# 方法 A：OpenSSL（推薦）— 產生 32 字元隨機 hex 字串
openssl rand -hex 16
# 範例輸出：8a4c2b9d3e5f1a7b8c9d0e1f2a3b4c5d

# 方法 B：Python
python3 -c "import secrets; print(secrets.token_urlsafe(24))"

Smart Scan QR Code 快速設定

App 登入畫面支援「Smart Scan」功能，掃描 QR Code 即可自動設定伺服器 URL 和 API Key，支援兩種格式：

Format A：JSON 格式（推薦）

同時設定伺服器 URL 和 API Key：

{
  "url": "https://erp.example.com",
  "key": "your-secret-api-key-123"
}

• url：自動加入伺服器清單並選取
• key：自動填入 API Key 欄位並啟用開關

Format B：純文字（僅 Key）

QR Code 內容為純字串時，僅設定 API Key，不變更伺服器 URL：

your-secret-api-key-123

使用者操作步驟

1. 開啟 App，進入登入畫面
2. 點擊右上角 設定齒輪 圖示
3. 下捲至 Nginx API Key 區塊
4. 勾選 啟用 核取方塊
5. 點擊輸入欄旁的 QR Code 圖示
6. 掃描管理員提供的設定 QR Code
7. 伺服器 URL 和 API Key 自動填入完成

Firebase Cloud Messaging (FCM) 完整設定

推播通知功能（聊天訊息、簽核提醒）需要 Firebase Cloud Messaging (FCM)。App 在缺少 Firebase 設定時仍可正常運作 — FCM 功能會優雅地停用。

架構

┌─────────────┐     FCM HTTP v1 API     ┌───────────┐     APNs / FCM     ┌─────────────┐
│  iDempiere   │ ──────────────────────→ │  Google    │ ────────────────→ │  Flutter App │
│  Server      │   OAuth2 + JSON         │  FCM       │                   │  (iOS/Android)│
│              │                         └───────────┘                   └─────────────┘
│ tw.idempiere.firebase plugin                                           │
│  ├─ WorkflowFcmEventHandler (DS)                                      │ FCM token
│  ├─ FcmService (OAuth2 + send)                                        │ registration
│  └─ FcmTokenServlet (WAB)  ←──────────────────────────────────────────┘ POST /fcm/token
└─────────────┘

伺服器端：tw.idempiere.firebase OSGi 插件使用 WAB（Web Application Bundle）模式提供 /fcm/token endpoint。WorkflowFcmEventHandler 監聽 workflow 狀態變更事件，觸發 FcmService 透過 FCM HTTP v1 API + OAuth2 認證發送推播。

用戶端：Flutter App 在登入時透過 POST /fcm/token 註冊裝置 token。前景通知使用 flutter_local_notifications 顯示，背景和終止狀態的通知由 Firebase SDK 處理。

步驟一：建立 Firebase 專案

1. 前往 Firebase Console
2. 點擊 「Add project」
3. 命名（例如 idempiere-mobile）
4. Google Analytics 可選擇停用
5. 點擊 「Create project」

步驟二：新增 Android App

1. Firebase Console → Project Overview → Add app → Android
2. Package name：tw.idempiere.app（或您的 applicationId）
3. 下載 google-services.json
4. 放置於 android/app/google-services.json

步驟三：新增 iOS App

1. Firebase Console → Project Overview → Add app → iOS
2. Bundle ID：tw.idempiere.app（須與 Xcode bundle identifier 一致）
3. 下載 GoogleService-Info.plist
4. 放置於 ios/Runner/GoogleService-Info.plist
5. 重要：上傳 APNs Authentication Key（.p8 檔案）至 Firebase Console → Project Settings → Cloud Messaging → Apple app configuration

APNs Authentication Key 詳細步驟

APNs Key 是 iOS 推播通知的靈魂。沒有它，你的 APP 在 iOS 上就是個不會說話的啞巴。

1. 前往 Apple Developer → Certificates, Identifiers & Profiles → Keys
2. 點擊 + 建立新 Key，勾選 Apple Push Notifications service (APNs)
3. 選擇環境：Sandbox（開發）vs Production（App Store/TestFlight）
4. 下載 .p8 檔案 — 只能下載一次！丟了就只能重新建立。跟你的初戀日記一樣重要。
5. 記下 Key ID（10 位字元，例如 ABC123DEF4）
6. 在 Firebase Console → Cloud Messaging → Apple app configuration：上傳 .p8、填入 Key ID + Team ID

小撇步：同一把 .p8 Key 可同時用於 Sandbox 和 Production slot。

iOS Entitlements 設定

在 ios/Runner/Runner.entitlements 中加入：

<key>aps-environment</key>
<string>development</string>

正式發布改為 production。在 Xcode → Runner target → Signing & Capabilities → 加入 Push Notifications。

沒做這一步，你的 App 會像個不舉手的學生——老師（APNs）永遠不會點到他。

步驟四：產生 Firebase Options

方法 A — FlutterFire CLI（推薦）：

dart pub global activate flutterfire_cli
flutterfire configure

方法 B — 手動設定：

若 CLI 無法使用，可手動建立 lib/firebase_options.dart，從 google-services.json 和 GoogleService-Info.plist 中取得所需參數值。

步驟五：取得 Service Account Key

Service Account JSON 已內嵌在 tw.idempiere.firebase 插件的 resources/firebase-service-account.json 中。所有部署共用同一個 Firebase 專案（App 發布者的專案）。

若需重新產生/替換 key：

1. 前往 Google Cloud Console → IAM & Admin → Service Accounts
2. 選擇 firebase-adminsdk service account
3. 指派以下角色（缺一不可，少一個就寄不出推播）：
   • Editor — FCM v1 API 存取權限
   • Service Account Token Creator — JWT/OAuth2 token 產生權限
4. 點擊 Keys 標籤 → Add Key → Create new key → JSON
5. 用下載的檔案替換插件中的 resources/firebase-service-account.json
6. 重新建置插件 bundle

技術細節：FcmService 使用 OAuth2 scope https://www.googleapis.com/auth/cloud-platform。Service account 簽署 JWT，交換為 access token，再用它呼叫 FCM HTTP v1 API。FcmService 直接從內嵌的 JSON 讀取 project_id 和認證資訊 — 不需要 AD_SysConfig 設定。

步驟六：設定 iDempiere

執行 SQL：執行 tw.idempiere.firebase plugin 中的 sql/create_tables.sql 建立 TW_FCM_Token 資料表。

Plugin Bundle 結構

插件使用 WAB（Web Application Bundle）模式——跟一般的 OSGi bundle 不同，WAB 自帶 web.xml 可以直接當 servlet 用：

tw.idempiere.firebase/
├── META-INF/MANIFEST.MF        # Web-ContextPath: fcm, Jetty-Environment: ee8
├── WEB-INF/web.xml              # Maps FcmTokenServlet to /*
├── OSGI-INF/
│   ├── process_factory.xml
│   └── workflow_fcm_event_handler.xml
├── resources/
│   └── firebase-service-account.json
└── src/tw/idempiere/firebase/
    ├── ChatActivator.java           # OSGi activator（chat servlet, WebSocket）
    ├── FcmService.java              # OAuth2 + FCM HTTP v1 API 發送器
    ├── FcmTokenServlet.java         # POST/DELETE /fcm/token（WAB servlet）
    ├── TokenUtil.java               # JWT token 解碼
    ├── WorkflowFcmEventHandler.java # DS 組件，監聽 workflow 事件
    └── WorkflowFcmValidator.java    # 驗證哪些事件需觸發 FCM

關鍵 MANIFEST.MF headers：

• Web-ContextPath: fcm — endpoint 路徑為 /fcm/*
• Jetty-Environment: ee8 — 讓 iDempiere 的 Jetty 識別並載入此 WAB

部署 Plugin：將 tw.idempiere.firebase OSGi bundle 部署至 iDempiere 並重啟（或 hot-deploy）。

步驟七：驗證

1. 登入 Flutter App — 在 debug console 確認出現 [FCM] Token registered with server
2. 查詢 TW_FCM_Token 資料表確認裝置 token 已儲存
3. 從其他使用者發送聊天訊息（App 處於背景）
4. 確認系統通知列出現推播通知
5. 點擊通知 → App 開啟並導向正確畫面

FCM 疑難排解

FCM Token 管理

// ApiClient 提供 FCM token 註冊/取消註冊：
await api.registerFcmToken(token);
await api.unregisterFcmToken(token);

通知偏好設定（TW_NotificationPref）

使用者可在 設定 → 通知偏好 中控制各類推播通知的開關。偏好儲存於 iDempiere 自訂表 TW_NotificationPref，每位使用者一筆記錄。

建表 SQL

CREATE TABLE TW_NotificationPref (
    TW_NotificationPref_ID   NUMERIC(10,0)   NOT NULL,
    TW_NotificationPref_UU   VARCHAR(36)     DEFAULT uuid_generate_v4(),
    AD_Client_ID             NUMERIC(10,0)   NOT NULL,
    AD_Org_ID                NUMERIC(10,0)   NOT NULL,
    IsActive                 CHAR(1)         DEFAULT 'Y' NOT NULL,
    Created                  TIMESTAMP       DEFAULT statement_timestamp() NOT NULL,
    CreatedBy                NUMERIC(10,0)   NOT NULL,
    Updated                  TIMESTAMP       DEFAULT statement_timestamp() NOT NULL,
    UpdatedBy                NUMERIC(10,0)   NOT NULL,
    AD_User_ID               NUMERIC(10,0)   NOT NULL,
    IsApprovalEnabled        CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsAnnouncementEnabled    CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsRequestEnabled         CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsPollEnabled            CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsBadgeEnabled           CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsMissionEnabled         CHAR(1)         DEFAULT 'Y' NOT NULL,
    IsBirthdayEnabled        CHAR(1)         DEFAULT 'N' NOT NULL,
    CONSTRAINT tw_notificationpref_pkey PRIMARY KEY (TW_NotificationPref_ID)
);

CREATE UNIQUE INDEX tw_notificationpref_user_uk
    ON TW_NotificationPref (AD_Client_ID, AD_User_ID);

欄位說明

容錯機制：若 TW_NotificationPref 表尚未建立，APP 會 catch HTTP 404 並使用內建預設值（全部開啟，生日除外），不會當機。

iDempiere AD 註冊

1. Table and Column 視窗 → 新增 Table Name TW_NotificationPref，勾選 REST API Access
2. 點選 Create Columns from DB 自動從實體表建立欄位
3. AD_User_ID 欄位 Reference 設為 Table Direct
4. 所有 Is* 欄位 Reference 設為 Yes-No

簽核模組增強功能

簽核模組在基礎的核准/駁回操作之上，提供四項增強功能：

1. 滑動手勢（Swipe Gestures）

使用 flutter_slidable 套件，在待簽核清單的每個項目上加入滑動操作：

• 右滑：綠色核准按鈕 + 完整滑動直接核准
• 左滑：橘色轉簽 + 紅色駁回
• 多選模式下自動停用

2. 工作流程進度條（Workflow Stepper）

垂直進度條呈現工作流程各節點狀態，資料來自 workflowDiagramProvider：

• 依 Transition SeqNo 排序節點（處理循環）
• 節點類型圖示：UserChoice = person、DocAction = settings
• 狀態顏色：CC = 綠色 ✓、OS = 藍色 ●、AB = 紅色 ✕、未處理 = 灰色 ○

3. 每日簽核提醒（Daily Reminder）

使用 flutter_local_notifications 的 zonedSchedule 排程每日 09:00 本機通知：

• 啟用/停用偏好存於 SharedPreferences，不依賴伺服器表
• 有待簽核項目時排程通知，無待簽核時取消
• 登出時自動取消排程
• 通知 payload {"type":"approval"} 路由至簽核畫面

4. 工作流程確認（Workflow Acknowledge）

呼叫 PUT /api/v1/workflow/acknowledge/{AD_WF_Activity_ID} 執行確認動作：

• 與 approve/reject 遵循相同的 pattern：ApprovalResultType.acknowledged
• 特殊處理 HTTP 304（伺服器回傳「無法確認」）轉換為 AppException
• 操作成功後顯示 SnackBar 並刷新列表

可重複使用 UI 元件

下列元件設計為 table-agnostic，可在不同模組中重複使用：

AttachmentSection

通用附件管理區塊（attachment_section.dart），接收 tableName 和 recordId 參數：

• 顯示附件數量標題、上傳（檔案選擇器/相機）、下載預覽、刪除
• 使用處：Window 記錄詳情、R_Request 詳情
• 用法：AttachmentSection(tableName: 'R_Request', recordId: id, isReadWrite: true)

TimelineTab

通用變更歷程/評論時間軸（timeline_tab.dart），接收 tableName 和 recordId 參數：

• 從 AD_ChangeLog 與 ChatMessage API 合併取得欄位變更及評論紀錄
• 依時間倒序排列，欄位變更顯示 old→new，評論以對話泡泡呈現
• 底部提供評論輸入列

動態必填邏輯（Dynamic Mandatory Logic）

Window 模組的編輯表單支援動態必填邏輯，語法與 DisplayLogic 相同：

@ColumnName@='value' & @OtherColumn@!='X' | @Flag@='Y'

• FieldInfo.mandatoryLogic 從 AD_Column MandatoryLogic 欄位載入
• effectiveMandatory 結合靜態 isMandatory 與動態 evaluateLogic()
• 必填時：標籤加星號、validator 檢查非空
• evaluateLogic() 支援 =、!=、&（AND）、|（OR）運算子

記錄表格檢視（Record Grid View）

記錄列表支援清單/表格兩種檢視模式切換：

• RecordGridView widget 使用 DataTable，支援欄位排序與水平捲動
• 最多顯示 8 個可見欄位，依使用者欄位偏好排列
• 切換按鈕位於 AppBar 工具列（表格/清單圖示）

報表頁面導覽（Report Page Navigation）

PDF 報表檢視器支援完整頁面導覽：

• 導覽列：首頁 → 上頁 → 頁碼指示器 → 下頁 → 末頁
• 點擊頁碼指示器彈出跳頁對話框，驗證頁碼範圍
• _pdfController!.setPage(pageIndex) 執行跳頁

疑難排解

R&D 網路存取限制（部署端）

本功能限制研發 (R&D) 模組僅能在公司網路環境下使用，以保護研發機密資料。採用雙層防護架構：APP 端偵測 WiFi IP 提供 UX 提示，Nginx 端設定 IP 白名單進行安全強制。

完整功能說明（含 APP 端操作、運作流程、常見問題）請參閱使用手冊（Page 616）。本節僅說明系統管理員需執行的伺服器端部署步驟。

步驟一：iDempiere SysConfig 設定

在 iDempiere 後台的 System Admin → General Rules → System Rules → System Configurator 新增兩筆設定：

CIDR 格式說明：

• 192.168.1.0/24 — 192.168.1.x（C 類子網）
• 10.0.0.0/8 — 10.x.x.x（A 類子網）
• 192.168.1.100/32 — 僅允許單一 IP

若未設定或 Value 為空，則不啟用任何網路限制。AD_Client_ID 和 AD_Org_ID 通常設為 0（全系統適用）。

步驟二：Nginx 反向代理 IP 限制

對 R&D API 路徑設定 IP 白名單。此 location 區塊必須放在一般 API location 之前（Nginx 以先匹配的 regex 為準）：

# R&D API 路徑 — IP 限制（放在一般 API proxy 之前）
location ~ ^/api/v1/models/RND_ {
    # 公司網路 IP 範圍 — 需與 SysConfig RND_ALLOWED_IP_RANGES 一致
    allow 192.168.1.0/24;
    allow 10.10.0.0/16;
    # 如有 VPN，加入 VPN 網段
    # allow 172.16.0.0/12;
    deny all;

    proxy_pass http://idempiere_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# 其他 API 路徑 — 不受限
location /api/v1/ {
    proxy_pass http://idempiere_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

設定完成後執行：

# 測試設定語法
sudo nginx -t

# 重新載入
sudo nginx -s reload

重要：Nginx 的 allow 指令和 iDempiere SysConfig 的 RND_ALLOWED_IP_RANGES 必須手動保持一致。修改任一邊時，記得同步更新另一邊。

步驟三：APP 部署注意事項

驗證

# 從公司網路測試 — 應回傳 200
curl -I https://your-server/api/v1/models/RND_Project

# 從外部網路測試 — 應回傳 403
curl -I https://your-server/api/v1/models/RND_Project

安全層級

運作方式

看完部署步驟，你可能在想：「所以資料到底怎麼流的？」以下用流程圖回答你，省得你自己畫在白板上然後拍照傳 LINE 群組。

登入流程

使用者登入
  ↓
選擇 Client → Role → Org
  ↓
認證成功
  ↓
自動從 iDempiere 取得 SysConfig
（RND_ALLOWED_IP_RANGES + RND_RESTRICTED_ROUTES）
  ↓
偵測目前 WiFi IP
  ↓
比對 IP 是否在允許的網段內
  ↓
更新 APP 內部狀態

模組存取流程

使用者點擊 R&D 模組
  ↓
APP 檢查是否在公司網路
  ├─ 是 → 正常進入模組
  └─ 否 → 導向「需要公司網路」畫面
            ├─ [重新偵測網路] → 重新檢查 WiFi IP
            └─ [我知道了] → 返回首頁

重新偵測時機

• APP 從背景回到前景時自動重新偵測
• 使用者在鎖定畫面點擊「重新偵測網路」
• 當 Nginx 回傳 403 時自動更新狀態

常見問題（FAQ）

以下集結了開發者和管理員最常問的七個問題。如果你的問題不在裡面，恭喜你發現了新的邊界案例。

Nginx 反向代理補充設定

前面的步驟二已設定基本 IP 白名單。這裡補充進階設定。

目的

阻擋公司外部請求存取 R&D API endpoints。

location ~ ^/api/v1/models/RND_ {
    allow 192.168.1.0/24;
    allow 10.10.0.0/16;
    deny all;
    proxy_pass http://idempiere_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

# 公司網路（預期 200）
curl -s -o /dev/null -w "%{http_code}" https://your-server/api/v1/models/RND_Project
# 外部網路（預期 403）
curl -s -o /dev/null -w "%{http_code}" https://your-server/api/v1/models/RND_Project

macOS 桌面版安全性

macOS Keychain 需要 Apple Developer 簽名。不想每年花 $99 USD？我們有替代方案。

加密策略

• 敏感欄位（access_token、refresh_token、password）：AES-256 加密後存入 SharedPreferences
• Encryption Key：由 tw.idempiere.mobile 衍生
• 非敏感欄位：維持明文儲存

Shake-to-Report 回饋機制

搖一搖手機就能回報 Bug——比起在 LINE 群組裡打一大段「那個功能怪怪的」，這個方式顯然更有建設性。

架構

MaterialApp.router
  └── builder:
        └── ShakeFeedbackWrapper          ← Screenshot + ShakeDetector
              └── _OfflineBannerWrapper
                    └── Navigator (GoRouter)

ShakeFeedbackWrapper 位於 MaterialApp.router 的 builder callback 內，確保可存取 Localizations、Navigator 和 Theme。

檔案結構

lib/features/feedback/
├── data/
│   ├── device_info_collector.dart       # 靜態工具：收集裝置/App 資訊
│   └── feedback_repository.dart         # 建立 R_Request + 上傳截圖
├── domain/
│   └── feedback_notifier.dart           # FeedbackState + FeedbackNotifier
├── presentation/
│   └── feedback_sheet.dart              # Modal BottomSheet UI
└── shake/
    ├── shake_feedback_settings.dart     # 偏好開關（SharedPreferences）
    └── shake_feedback_wrapper.dart      # App 層級 wrapper

資料流程

User shakes phone
    │
    ▼
ShakeDetector.onPhoneShake
    │  ← check: enabled? cooldown? sheet open?
    ▼
ScreenshotController.capture()
    │
    ▼
DeviceInfoCollector.collect()
    │  ← device model, OS, app version, route, locale
    ▼
FeedbackSheet.show()
    │  ← user fills: problem type + description
    ▼
FeedbackNotifier.submitFeedback()
    │
    ▼
FeedbackRepository.submitFeedback()
    ├── ApiClient.createRecord('R_Request', data)
    └── UploadApi.uploadAndAttach(screenshot.png)

R_Request 欄位對應

搖晃行為參數

套件依賴

錯誤處理

flutter devices
# Expected: Pixel 7 (mobile) • abc12345 • android-arm64 • Android 14

flutter run              # Auto-select device
flutter run -d abc12345  # Specify device

# APK (universal, direct install)
flutter build apk --release

# App Bundle (Google Play)
flutter build appbundle --release

adb install -r build/app/outputs/flutter-apk/app-release.apk
# Or: flutter install --release

flutter build apk --release && adb install -r build/app/outputs/flutter-apk/app-release.apk

# Generate keystore
keytool -genkey -v -keystore ~/idempiere-release.jks 
  -keyalias idempiere -keyalg RSA -keysize 2048 -validity 10000

MaterialApp.router
  └── builder:
        └── ShakeFeedbackWrapper          ← Screenshot + ShakeDetector
              └── _OfflineBannerWrapper
                    └── Navigator (GoRouter)

User shakes phone → ShakeDetector → ScreenshotController.capture()
→ DeviceInfoCollector.collect() → FeedbackSheet.show()
→ FeedbackNotifier.submitFeedback()
→ FeedbackRepository: createRecord('R_Request') + uploadAndAttach(screenshot)

flutter build apk          # Android APK
flutter build appbundle     # Android AAB (Play Store)
flutter build ios           # iOS (requires macOS + Xcode)
flutter build web           # Web (static files)
flutter build macos         # macOS
flutter build windows       # Windows

┌─────────────┐     FCM HTTP v1 API     ┌───────────┐     APNs / FCM     ┌─────────────┐
│  iDempiere   │ ──────────────────────→ │  Google    │ ────────────────→ │  Flutter App │
│  Server      │   OAuth2 + JSON         │  FCM       │                   │  (iOS/Android)│
│              │                         └───────────┘                   └─────────────┘
│ tw.idempiere.firebase plugin                                           │
│  ├─ WorkflowFcmEventHandler (DS)                                      │ FCM token
│  ├─ FcmService (OAuth2 + send)                                        │ registration
│  └─ FcmTokenServlet (WAB)  ←──────────────────────────────────────────┘ POST /fcm/token
└─────────────┘

<key>aps-environment</key>
<string>development</string>

tw.idempiere.firebase/
├── META-INF/MANIFEST.MF        # Web-ContextPath: fcm, Jetty-Environment: ee8
├── WEB-INF/web.xml              # Maps FcmTokenServlet to /*
├── OSGI-INF/
│   ├── process_factory.xml
│   └── workflow_fcm_event_handler.xml
├── resources/
│   └── firebase-service-account.json
└── src/tw/idempiere/firebase/
    ├── ChatActivator.java           # OSGi activator (chat servlet, WebSocket)
    ├── FcmService.java              # OAuth2 + FCM HTTP v1 API sender
    ├── FcmTokenServlet.java         # POST/DELETE /fcm/token (WAB servlet)
    ├── TokenUtil.java               # JWT token decoding
    ├── WorkflowFcmEventHandler.java # DS component, listens for workflow events
    └── WorkflowFcmValidator.java    # Validates which events trigger FCM

Login → Fetch SysConfig → Detect WiFi IP → Match CIDRs → Update state

User taps R&D module → Check network
  ├─ Yes → Enter module
  └─ No  → "Company network required" screen

flutter devices

flutter run

flutter build apk --release    # APK（汎用）
flutter build appbundle --release  # App Bundle（Google Play）

adb install -r build/app/outputs/flutter-apk/app-release.apk

flutter build apk --release && adb install -r build/app/outputs/flutter-apk/app-release.apk

keytool -genkey -v -keystore ~/idempiere-release.jks 
  -keyalias idempiere -keyalg RSA -keysize 2048 -validity 10000

MaterialApp.router
  └── builder:
        └── ShakeFeedbackWrapper          ← Screenshot + ShakeDetector
              └── _OfflineBannerWrapper
                    └── Navigator (GoRouter)

端末を振る → ShakeDetector → ScreenshotController.capture()
→ DeviceInfoCollector.collect() → FeedbackSheet.show()
→ FeedbackNotifier.submitFeedback()
→ FeedbackRepository: createRecord('R_Request') + uploadAndAttach(screenshot)

flutter build apk          # Android APK
flutter build appbundle     # Android AAB（Play Store 向け）
flutter build ios           # iOS（macOS + Xcode が必要）
flutter build web           # Web（静的ファイル）
flutter build macos         # macOS
flutter build windows       # Windows

┌─────────────┐     FCM HTTP v1 API     ┌───────────┐     APNs / FCM     ┌─────────────┐
│  iDempiere   │ ──────────────────────→ │  Google    │ ────────────────→ │  Flutter App │
│  Server      │   OAuth2 + JSON         │  FCM       │                   │  (iOS/Android)│
│              │                         └───────────┘                   └─────────────┘
│ tw.idempiere.firebase plugin                                           │
│  ├─ WorkflowFcmEventHandler (DS)                                      │ FCM token
│  ├─ FcmService (OAuth2 + send)                                        │ registration
│  └─ FcmTokenServlet (WAB)  ←──────────────────────────────────────────┘ POST /fcm/token
└─────────────┘

<key>aps-environment</key>
<string>development</string>

tw.idempiere.firebase/
├── META-INF/MANIFEST.MF        # Web-ContextPath: fcm, Jetty-Environment: ee8
├── WEB-INF/web.xml              # FcmTokenServlet を /* にマッピング
├── OSGI-INF/
│   ├── process_factory.xml
│   └── workflow_fcm_event_handler.xml
├── resources/
│   └── firebase-service-account.json
└── src/tw/idempiere/firebase/
    ├── ChatActivator.java           # OSGi activator
    ├── FcmService.java              # OAuth2 + FCM HTTP v1 API 送信
    ├── FcmTokenServlet.java         # POST/DELETE /fcm/token
    ├── TokenUtil.java               # JWT トークンデコード
    ├── WorkflowFcmEventHandler.java # DS コンポーネント、ワークフローイベント監視
    └── WorkflowFcmValidator.java    # FCM トリガーイベントの検証

ログイン → SysConfig 取得 → WiFi IP 検出 → CIDR 照合 → 状態更新

R&D モジュールタップ → ネットワークチェック
  ├─ はい → モジュールに入る
  └─ いいえ → 「社内ネットワークが必要」画面