Skip to content
chyuanerPublic

About

抓取與提供 MozTW 摩茲工寮空間 環境資訊的 API 與 Telegram 機器人

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MozTW Space Info API

這是一個用於抓取與提供 MozTW 摩茲工寮空間 環境資訊的 API 與 Telegram 機器人。基於 Hono 框架開發,可部署於 Cloudflare Workers 或 Node.js 環境。

功能用法

1. HTTP API

提供簡單的 HTTP 端點供外部整合:

  • GET /: 回傳所有資訊 (JSON)。

2. Telegram 機器人

機器人支援以下指令:

  • /space: 顯示完整的空間資訊(溫度、濕度、CO2)。

3. CLI 工具

如果你只想在終端機快速查看資訊,可以使用:

npm run get

搭建開發環境

1. 安裝依賴

npm install

2. 設定環境變數

將 .env.sample 複製為 .env 並填入相關資訊:

cp .env.sample .env
# 若使用 Cloudflare Workers 模式 (wrangler dev),請同時複製一份為 .dev.vars
cp .env .dev.vars
  • TELEGRAM_BOT_TOKEN: 你的 Telegram Bot Token。
  • SENSORS_CONFIG: 所有IoT設備的相關資訊,結構範例請看 .env.sample 檔案 (目前支援SwitchBot Meter/Hub 的設備)

3. 啟動本地伺服器測試

專案支援三種本地測試模式,啟動時皆會自動建置前端與靜態資源(npm run build:assets):

模式 A:Node.js 伺服器模式(推薦,快速離線開發)

使用本機 Node.js 與 @hono/node-server 執行,讀取 .env。資料庫會使用本機檔案系統(.data/ 目錄)模擬,完全獨立於 Cloudflare 遠端環境,適合離線開發、修改 API 或調整前端儀表板:

npm run dev:node
  • 預設網址:http://localhost:3000(可透過環境變數 PORT 調整)
  • 儀表板頁面:開啟瀏覽器造訪 http://localhost:3000/ 查看即時空間狀態
  • API 文件 (Swagger UI):造訪 http://localhost:3000/doc 即可線上測試 API

模式 B:Cloudflare Workers 模式(模擬線上環境)

使用 wrangler dev 模擬 Cloudflare Workers Runtime,讀取 .dev.vars:

npm run dev
# 或若需開放同區域網路的其他設備測試(監聽 0.0.0.0):
npm run dev:worker-host
  • 預設網址:http://localhost:8787
  • 儀表板頁面:http://localhost:8787/
  • API 文件 (Swagger UI):http://localhost:8787/doc

模式 C:Telegram 機器人本機測試(Long Polling 模式)

本機測試 Telegram Bot 指令時,無需對外暴露 Webhook 或架設 ngrok,直接由本機主動向 Telegram 伺服器長輪詢:

npm run dev:tg

⚠️ 注意:在此模式下,必須確保該 Bot Token 目前沒有綁定 Webhook(否則 Telegram 會拒絕連線)。若需清除 Webhook,可至瀏覽器造訪:
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/deleteWebhook

4. 本地常用測試與指令

  • 終端機快速查看感測器數值:
    npm run get
  • 手動重新編譯前端與靜態資源:
    npm run build:assets
  • 常用驗證端點:
    • GET /:前端儀表板 (Dashboard)
    • GET /doc:內建 Swagger UI 互動式文件
    • GET /openapi.json:OpenAPI 3.1 規範
    • GET /sensors/data:感測器詳細數值

部署

1. 設定資料庫 (Cloudflare D1 或 KV)

本專案支援 Cloudflare D1 (分散式 SQLite,推薦) 與 Cloudflare KV 兩種儲存後端,可透過環境變數 SENSOR_STORAGE 隨時切換(d1 或 kv)。

方式 A:使用 Cloudflare D1 (推薦)

  1. 建立 D1 資料庫:
    npx wrangler d1 create moztw-co2-db
  2. 將終端機回傳的 database_id 填入 wrangler.jsonc 中的 d1_databases 區塊:
    "d1_databases": [
      {
        "binding": "DB",
        "database_name": "moztw-co2-db",
        "database_id": "貼上你的 D1 資料庫 ID"
      }
    ]
  3. 匯入資料表結構與既有資料(可透過本地遷移腳本自動生成):
    # 1. 執行本地遷移(將 .data/ JSON 轉移為 SQLite 並生成 seed_for_d1.sql)
    npm run db:migrate
    # 2. 匯入至線上 D1 資料庫
    npx wrangler d1 execute moztw-co2-db --remote --file=./migrations/seed_for_d1.sql

方式 B:使用 Cloudflare KV (保留相容)

若需切回 KV 模式,建立 KV Namespace 並在 wrangler.jsonc 設定 "vars": { "SENSOR_STORAGE": "kv" }:

npx wrangler kv:namespace create "SENSOR_KV"

2. 設定重要環境變數 (Secrets)

請將機器人 Token 與感測器設定存入 Cloudflare Workers 內部:

npx wrangler secret put TELEGRAM_BOT_TOKEN

npx wrangler secret put SENSORS_CONFIG

(⚠️ 小提醒:在終端機貼上給 Cloudflare 的值時,不需要頭尾的單引號,直接貼上 [{...}] 即可)

3. 部署到 Cloudflare Workers

npm run deploy

注意:部署到 Cloudflare 時請使用 Webhook 模式(/bot 端點),本地測試可使用 Long Polling (npm run dev:tg)。

設定Telegram Bot的模式(Webhook / Long Polling)

查狀態

https://api.telegram.org/bot<TG_TOKEN>/getWebhookInfo

綁定Webhook

https://api.telegram.org/bot<TG_TOKEN>/setWebhook?url=<YOUR_URL>/bot/<TG_TOKEN>

解除綁定Webhook (回歸Long Polling模式)

https://api.telegram.org/bot<TG_TOKEN>/deleteWebhook

API Doc 文件

本站已內建 Swagger UI,並提供標準 /openapi.json 規範:

  • 內建 Swagger UI:伺服器啟動後直接在瀏覽器開啟 /doc(例如:http://localhost:3000/doc 或 http://localhost:8787/doc)即可線上瀏覽與測試。
  • OpenAPI 規範:可將 /openapi.json 匯入相容 OpenAPI 的客戶端(如:Insomnia、Postman)。
  • 獨立 Docker Swagger UI:若想使用官方 Swagger 容器預覽,可執行:
docker run -p 9000:8080 -e SWAGGER_JSON_URL=http://localhost:8787/openapi.json docker.swagger.io/swaggerapi/swagger-ui

lastchange 判定原則

1. lastchange (連線/確認時間)

  • 只要 fetch 成功或收到 webhook,且該裝置不是 only_webhook 的主動查詢,lastchange 就會更新為當前時間。
  • 這代表了「系統最後一次與該設備取得聯繫」的時間,與數值是否有變無關。
  • 快取保護:系統會以 lastchange 結合 staleThresholdSeconds (預設 600s) 判定資料是否過期。若未過期,主動查詢時會直接回傳快取內容,不發起 API 請求與 KV 寫入。

2. temperature_lastchange (數值變動時間)

  • 只有當新取得的數值(如溫度)與資料庫中現有的數值不同時,才會更新這個項目的 lastchange。
  • 如果數值相同,則保留舊的變動時間。
  • 寫入優化:若所有感測數值均未變動,系統將跳過歷史紀錄 (Raw Ingestion) 的寫入,僅更新目前的狀態以節省 Cloudflare KV PUT 額度。

3. only_webhook 裝置保護

  • 如果裝置設定為 only_webhook: true,則主動的 fetch 行為不會更新整體的 lastchange。
  • 該裝置的 lastchange 只有在真正收到 Webhook 通知時才會變動,符合您「記錄上次被通知時間」的需求。

🛠 感測器欄位擴充與維護手冊 (Developer Guide)

當未來引入新感測器或需要擴充新的監測指標(如:battery 電量、light_level 光照度、pm25 等)時,請依照以下檢查清單依序修改:

1. 核心必改(核心業務模型與資料庫映射)

步驟 A:更新感測器資料核心層 (src/core/switchBot.ts)

  1. 宣告型別 (interface SensorDataRecord): 新增屬性及其變動追蹤元資料:
    battery?: number;
    battery_lastchange?: number;
    battery_iswebhook?: boolean;
  2. 屬性合併 (consolidate):
    • 將新欄位加入泛型 key 聯集:K extends 'temperature' | ... | 'battery'。
    • 加入取值:const batteryProps = getConsolidatedProperty('battery');。
    • 在回傳物件中組裝屬性(battery, battery_lastchange, battery_iswebhook)。
  3. 資料來源解析:
    • updateFromWebhook():從 SwitchBot Webhook context 讀取並賦值。
    • fetch():從 SwitchBot 官方雲端 API 的 body 讀取並賦值。

步驟 B:登記資料庫結構化欄位 (src/core/db/d1Sqlite.ts)

在檔案最前段的 SENSOR_FIELDS 陣列新增一筆欄位定義:

export const SENSOR_FIELDS: readonly SensorFieldDefinition[] = [
  // ...既有欄位
  { column: 'battery', property: 'battery', type: 'number' }, // 新增這行
] as const;

💡 save() 的 INSERT 與 getHistory() 的 SELECT/物件映射會自動由此陣列動態驅動,無需手動修改底層 SQL 語句。

步驟 C:更新資料庫結構 (migrations/)

在 Cloudflare D1 資料庫的 sensor_records 表新增欄位:

ALTER TABLE sensor_records ADD COLUMN battery REAL; -- 或 INTEGER / TEXT

2. 依功能需求選擇性擴充

  • OpenAPI 文件與 Webhook 驗證:
    • src/core/route/locations.ts:更新 SensorDataRecordSchema,讓 Swagger UI 與客戶端 API 包含新欄位。
    • src/core/app.ts:若 Webhook 接收端有驗證 payload,更新 SwitchBotWebhookPayload。
  • Telegram 機器人 (src/core/route/bot.ts):
    • 若要在 /co2 或其他指令中呈現該指標文字,於訊息組裝迴圈中加入顯示條件。
  • 即時圖表與 Open Graph 圖片 (src/core/og.tsx & src/core/route/og.ts):
    • 若要繪製該指標的歷史圖表,新增對應的 Chart 元件與 OG 端點。
  • SpaceAPI 格式相容 (src/core/format.ts):
    • 若該指標屬於 SpaceAPI 規範支援項目,在轉換器中加入映射。
  • 前端儀表板 (src/core/frontend/main.tsx):
    • 若網頁前端 Dashboard 需要展示,加入對應的 Card 卡片與數值渲染。

📄 授權

MPL-2.0

About

抓取與提供 MozTW 摩茲工寮空間 環境資訊的 API 與 Telegram 機器人

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages