SHM 實作筆記
APP DEVELOPMENT / 02學習教材
從固定資料開始

先讓資料
成為畫面。

一份 JSON、一個裝置列表。
從能看見的結果出發,再接上真實 API。

開始本週實作
THE LEARNING PATH 本週路線
01
讀懂資料站點與裝置的關係
JSON
02
呈現畫面列表、詳情與狀態
UI
03
替換來源從本機檔案到請求
API
先在本機練習,再逐步串接
本篇涵蓋CommonAndroidiOS可下載練習檔案
第 2 週 / COMMON

從固定資料,走到 API 串接

SHM 平台收集建築物感測器資料。手機 App 的工作,是讓站點、裝置狀態和量測時間,變成容易閱讀與操作的畫面。

這次先建立裝置列表與詳情,再加入登入。把畫面和資料來源分開後,即使測試 API 尚未就緒,也能用固定資料持續實作。

入口登入
瀏覽裝置總覽
深入裝置詳情

列表與詳情先共用同一筆資料,登入狀態可先用本機模擬。

01

先讀懂一筆裝置資料

總覽回應以站點分組,每個站點包含一個 devices 陣列。先找出裝置名稱、狀態與最後量測時間,對應到列表上的三個位置。

裝置資料節錄 · JSON
{
  "id": "demo-device-01",
  "name": "示範加速度計 A",
  "status": "normal",
  "lastMeasurementAt": "2026-10-15T01:00:00.000Z",
  "currentValue": { "ax": 0.01, "ay": -0.02, "az": 0.03 }
}

合成資料與欄位子集,並非真實站點量測。完整範例可在文末下載。

名稱與狀態
name 顯示裝置名稱;狀態搭配文字和顏色,不只靠顏色區分。
量測時間
lastMeasurementAt 是 ISO 時間或 null。顯示時轉為本機時區,沒有時間則標示「尚無量測資料」。
缺值與零值
currentValue: null 表示沒有量測值,和數值為零不同。單位等正式裝置設定確認後再標示。
02

資料改變時,畫面怎麼回應?

列表不是只有「有資料」一種情況。讓資料來源回傳空列表、延遲或錯誤,就能先把畫面行為整理好,再處理真實網路。

小實驗

切換資料狀態

僅本機示意
SHM / 裝置總覽合成資料

把資料存取包在獨立介面,畫面只處理載入、內容、空列表與錯誤。未來從 JSON 換成 HTTP 時,就能沿用已經建立的畫面邏輯。

03

走一次登入與查詢流程

登入不是只切換頁面。帳密送到後端後會取得 token,之後的受保護請求再帶上這份登入資訊。下面把三個請求放進同一條路徑。

REQUEST FLOW App 與 API 的對話
登入、確認身分與查詢裝置總覽App 發出 POST auth login 取得 token,接著帶 Bearer token 呼叫 GET auth me 確認身分,再呼叫 GET dashboard overview 取得裝置資料。登入錯誤不會進入後續成功流程。AppAPI 01 POST /api/auth/logintoken · tokenType · expiresIn · user 02 GET /api/auth/mesub · userId · role 03 GET /api/dashboard/overviewdata.sites[].devices[]第 2、3 個請求帶上 Authorization: Bearer <token>
01 / App → APIPOST /api/auth/login

送出 userName、password

API 回應:token 與登入資訊
02 / App → APIGET /api/auth/me

帶上 Bearer token

API 回應:sub、userId、role
03 / App → APIGET /api/dashboard/overview

帶上 Bearer token

API 回應:站點與裝置陣列
成功路徑示意。先用 Postman 觀察回應,再把相同請求接進 App。
登入 request body
{
  "userName": "<測試帳號>",
  "password": "<測試密碼>"
}

登入回應的 user 包含 id、name、role;/auth/me 則直接回傳 sub、userId、role。兩者的資料模型不同。

400檢查輸入

缺少必要欄位時,提示補齊。

401登入資訊無效

登入失敗顯示錯誤;查詢時收到則重新登入。

403權限不足

呈現權限訊息,不當成密碼錯誤。

測試入口與帳號尚待提供。這份網頁只展示流程,不接收帳密、不連線到正式 API。

04

把相同概念,放進各自的平台

資料結構與畫面行為相同,UI 元件和網路工具則沿用平台習慣。選擇一條路線閱讀。

用 Compose 呈現裝置資料

以 Kotlin 資料類別表示站點與裝置,將可能為空的時間與量測值保留為可空型別。用 LazyColumn 顯示站點與裝置列,再把選取的裝置帶到詳情。

  1. 固定資料先上畫面將範例 JSON 轉成畫面使用的資料模型。
  2. 加入狀態變化集中管理載入、內容、空列表與錯誤,畫面依狀態繪製。
  3. 替換成 HTTP 來源確認網路權限,以非同步方式發出請求,避免在主執行緒等待。
閱讀 Compose 列表文件 ↗
05

把練習帶進開發環境

兩份 JSON 可直接用來練習列表狀態。Postman 範本包含登入、查身分與總覽三個請求,待測試入口就緒後使用。

匯入 Postman 後怎麼設定?
  1. 匯入 collection,建立個人的本機 environment。
  2. 設定 baseUrl、userName、password、token。baseUrl 是服務根網址,不含尾端 /api。
  3. 執行登入,把回應的 token 填到本機變數,再執行身分與總覽請求。

帳密與 token 保留在本機私有值,不同步到共用 workspace,也不隨檔案匯出。範本尚未對實際服務執行。

把這幾步串起來

畫面先走通,資料再接上。

固定 JSON 建立列表與詳情,模擬狀態整理畫面行為,再將資料來源換成 API。每一次小實驗,都留下能在下一步沿用的成果。

回到學習路線 ↑