OVERVIEWi3 FM 混合式平台
總覽
像一張大廈總平面圖——由現場機房到雲端數據平面，
由七種角色到十九張表，設計與基建，一頁睇晒。
設計 × 基建全覽 PRD / ARD v1.0 2026 麥肯錫風格項目總結
i3 FM 混合式平台 · 設計與基建總結01來源：PRD / ARD v1.0
AGENDA七章讀完全案

由核心訊息出發，七章走完「目標 → 治理 → 架構 → 數據 → 交付」

01
核心訊息與五大目標
平台要解決咩問題
P03–04
02
角色與權限治理
七層管理鏈、防越權
P05
03
資訊架構：18 頁
三大功能群組
P06
04
混合式系統架構
現場層 → 單一中央數據平面
P07–08
05
數據模型與授權防線
19 張表、三層 defense
P09–10
06
整合介面與路線圖
MQTT／BACnet／SOAP · 20 週
P11–12
07
營運保障與下一步
NFR · 排程 · 風險 · 現狀
P13–16
i3 FM 混合式平台 · 設計與基建總結02來源：PRD v1.0 §2–§9 · ARD v1.0 §2–§10
KEY MESSAGE一句講晒
一套平台覆蓋日常營運全部環節，
現場到場有據可查。
7
內建角色
管理鏈逐層向下
18
設計頁面
三大功能群組
20
實作 Session
基建到上線
19
核心數據表
單一中央 Postgres
180日
稽核保留期
append-only 可匯出
i3 FM 混合式平台 · 設計與基建總結03來源：PRD v1.0 §2–§4 · ARD v1.0 §5
OBJECTIVESPRD §2.2

五大產品目標：一個平台同時解決「系統分散」與「到場無據」兩大痛點

1
單一系統
覆蓋日常營運
報修、派工、保養、警報、應變、能源、合規、報表，集中一個平台，取代分散表格
2
現場人員
到場可追蹤
technician 與 contractor 到場都要系統報到——「有冇人到、幾時到」有據可查
3
權責分明
帳號治理
developer → field 角色階層，每層只可管理其下層級，防越權與自升權限
4
多站統一
數據單一來源
全站點共用一個中央 DB，RLS 按 site_id 隔離；Root Console 跨站唯讀總覽
5
合規稽核
全面可追溯
合規事項到期管理；稽核日誌留痕不可修改、保留 180 日、可匯出 CSV
i3 FM 混合式平台 · 設計與基建總結04來源：PRD v1.0 §2.2
GOVERNANCEPRD §3 · ARD §4.5

七角色一條管理鏈：只能向下管理，矩陣釘死每一格權限

developer 系統開發 · 全系統總管
support 全系統唯讀＋人事查詢
site_owner 單 site 負責人 · 可多位 co-owner
site_admin 專責 account 管理
site_staff 日常操作
technician in-house · 無 expiry
contractor 外判 · 有 expiry
權限能力 developersupport site_owner site_admin site_stafftechnician contractor
Account 管理全部只讀自己site·可邀同級只可派下級無無無
人事資料全部全部唯讀自己site自己site只睇自己只睇自己只睇自己
設備×數據讀取全部只讀自己site只讀自己site只限指派只限指派
Invite link全部無自己site·含同級只可下級無無無
Expiry 管理全部無可設期限可設期限無in-house 冇自身受管理
現場報到檢視檢視檢視檢視檢視需報到過期報唔到
1 admin 禁派 owner／admin 2 support 全唯讀、冇 invite 3 field 只限指派項目 4 contractor 有 expiry，到期自動失效
i3 FM 混合式平台 · 設計與基建總結05來源：PRD v1.0 §3 · pages/access-control.html
INFORMATION ARCHITECTUREPRD §4

18 個設計頁、三大群組：營運中心做主軸，分析與系統頁收邊

7 頁
營運中心
每天用嘅工作台
儀表板 票務池 警報中心 緊急應變 維修工單 保養計劃 日結
5 頁
分析與報告
睇趨勢、評表現
能源分析 承辦商評分 合規 月報 稽核日誌
6 頁
系統與架構
治理與導覽入口
平台總覽 登入（站點／Root） 用戶與角色 站點管理（中央） 系統架構圖 角色與權限架構
i3 FM 混合式平台 · 設計與基建總結06來源：PRD v1.0 §4（18 個 page node）
ARCHITECTUREARD §3–§4

混合式：現場就地收斂，雲端單一數據平面，前端按站隔離

現場層 · 每個 SITE 一套
感應器 MQTT
BMS BACnet/IP Points
供應商系統 SOAP Web Service
→
Site Gateway
MQTT Broker · BACnet Adapter · SOAP Adapter
Normalize → canonical JSON（補 site_id＋timestamp）
TLS · service role 寫入（前端用戶絕不直接寫 telemetry）
平台核心 · 雲端單一 instance
Supabase / Postgres ×1
RLS 隔離
所有表按 site_id
REST API
每模組 endpoint＋RBAC
Auth
JWT · session · refresh
排程 jobs
expiry · 月報 · 封存
讀寫經 API · 角色範圍過濾
Site Web App 每 site 獨立部署
離線優先 · 本地實例 v1.4.2 · 繁中／EN
Root Console developer／support 專用
跨站唯讀總覽 · sites 管理為唯一例外
i3 FM 混合式平台 · 設計與基建總結07來源：ARD v1.0 §3–§4 · pages/architecture.html
DATA PIPELINEARD §4.4 · §6.4

Site Gateway 數據入口：Normalize 一次，後端與報表永遠只面對一種格式

MQTT
感應器讀數 · QoS≥1
BACnet/IP
BMS Points 輪詢 · 點表映射
SOAP
供應商 Web Service · XML
→
Normalize 層
三路輸入統一為 canonical JSON，單位／範圍驗證，錯誤入 error 日誌
{ site_id, timestamp, source,
device_id, metric, value, unit, raw }
→
telemetry 表（中央）
service role 經單一管道寫入，一律帶 site_id＋timestamp
斷網 buffer
本地 queue 暫存，恢復後按序補送，保留原始 timestamp 不錯位
i3 FM 混合式平台 · 設計與基建總結08來源：ARD v1.0 §4.4 · §6.4
DATA MODELARD §5

19 張核心表、六個域：身份先行，治理表收口

身份5
users · roles · permissions
site_members · invites
全域身份＋site membership 一對多
營運4
tickets · maintenance_work_orders
maintenance_plans · field_attendance
票務→工單→保養→到場報到
供應商2
contractors
vendor_scores
主檔＋合約到期 · 表現評分
監測2
alerts
telemetry
警報規則 · Gateway 唯一寫入管道
應變合規2
incidents
compliance_items
事故時間線＋中央快照 · 到期管理
治理4
audit_log · daily_close
monthly_reports · sites
留痕 · 日結簽署 · 月報 · 站點主檔
i3 FM 混合式平台 · 設計與基建總結09來源：ARD v1.0 §5（19 張核心 Table）
AUTHORIZATIONARD §7.2 · §8.2

授權三層防線：Route guard 只係 UX，後端同 RLS 先係保安邊界

3
Postgres RLS — 最後防線
全部 site 表按 site_id＋active membership；field 只見指派行；admin 建 owner/admin membership 被拒
2
API RBAC — 保安邊界
middleware 按 JWT claims（user_id × site_members.role_key）逐 endpoint 檢查；support 全寫操作拒絕
1
前端 Route guard — UX 輔助
按角色隱藏入口與路由；被繞過亦唔影響實際授權
audit_log · append-only
無 UPDATE／DELETE policy，DB trigger 禁改禁刪；保留 180 日可匯出
telemetry · INSERT 僅 service role
只有 Gateway（service role）可寫；用戶側一律只 SELECT
RLS policy 隨 migration 版本管理；UAT 專項測試「跨 site 數據洩漏」。
i3 FM 混合式平台 · 設計與基建總結10來源：ARD v1.0 §7.2 · §8.2–§8.3
INTEGRATIONARD §6

三個現場入口，每個都有明確協定參數——唔靠口講整合

MQTT 感應器數據
i3fm/{site_id}/{device_id}/{metric}
  • · 數據訊息 QoS ≥ 1
  • · 狀態 topic retained（新訂閱者即取最新）
  • · 重連指數退避 · 斷線本地 buffer
  • · 假設：MQTT over TLS 8443，唔開放公開 publish
BACnet/IP BMS
WhoIs / ReadProperty 輪詢
  • · 關鍵點 30 秒 · 一般點 5 分鐘（可配置）
  • · Object/Property → canonical metric 映射表，每 site 自訂
  • · 不可達設備重試＋標記離線
  • · 單位轉換喺映射層完成
SOAP 供應商系統
timeout 30s · 重試 1s / 4s / 16s
  • · 重試 3 次，指數退避
  • · 連續失敗寫 error 日誌＋gateway_health 訊號
  • · 單一 vendor 故障唔拖垮成個 Gateway
  • · 假設：HTTP Basic／WS-Security；XML deserialize 後入 Normalize
i3 FM 混合式平台 · 設計與基建總結11來源：ARD v1.0 §6.1–§6.4
ROADMAPPRD §8

20 個 Session 收進六個里程碑：每個里程碑 demo＋驗收簽核先過關

M1
基建
S1 · 第1週
設計系統、專案骨架、CI
M2
身份與權限
S2–S5 · 第2–4週
登入 Auth · RBAC 矩陣 · Invite · 站點 onboarding
M3
核心營運
S6–S9 · 第5–8週
儀表板 · 票務池 · 維修工單 · 保養計劃
M4
現場與整合
S10–S13 · 第9–12週
現場報到 · 承辦商 expiry · 警報 · MQTT／SOAP 接線
M5
分析與應變
S14–S16 · 第13–15週
能源分析 · 緊急應變 · 合規
M6
報表與收尾
S17–S20 · 第16–20週
稽核 · 日結 · 月報 · UAT · 部署培訓上線
交付節奏： 每個 milestone 結束前 demo＋驗收簽核 ｜ 每 session 產出物入版本控制並有對應測試 合共 20 週（基準估算）
i3 FM 混合式平台 · 設計與基建總結12來源：PRD v1.0 §8（M1–M6 · S1–S20）
NFRPRD §6 · ARD §2.2

非功能需求五條線，每條都有可驗收數字

保安
全傳輸 TLS · 密碼 argon2 雜湊（≥12 字元）· 連續 5 次失敗鎖 15 分鐘 · JWT 2h／refresh 7d 輪換
效能
感應器→DB 端到端 ≤10s · 常用聚合 P95 ≤2s · 首屏 LCP ≤2.5s · 每站 ≤2,000 telemetry 點
可用性
繁中／EN 雙語（繁中預設）· 狀態色 AA 對比 · 現場流動裝置友善報到表單 · SLA 倒數一眼判讀
擴展
新站點＝新增 site 記錄＋部署 Gateway，毋須新資料庫 · 連線池／讀寫分離應對增長
可維護
migration 向前兼容 · immutable build（v1.4.2 顯示版本）· SLA／警報／評分／碳排係數全參數化，唔使改 code
i3 FM 混合式平台 · 設計與基建總結13來源：PRD v1.0 §6 · ARD v1.0 §2.2
OPERATIONSARD §4.2 · §8.5 · §2.2

五個排程 Jobs 自動行：治理規則寫進排程，唔靠人手記得

排程 JOB
頻率
動作／保留
Contractor expiry 掃描
每日
到期 membership → status=expired 自動停權；到期前 30／7 日走通知引擎提醒
月報生成
每月 1 日
自動匯總營運率、工單、警報、能耗（同比）寫入 monthly_reports
Audit 封存
保留 180 日
append-only 留痕，之後封存冷儲存；匯出 CSV（匯出本身亦記 audit）
Telemetry 歸檔
13 個月
原始數據保留 13 個月後聚合歸檔，減低備份體積
合規到期提醒
到期前提醒
compliance_items 檢查日期臨近走通知，狀態過期自動標示
i3 FM 混合式平台 · 設計與基建總結14來源：ARD v1.0 §4.2 · §8.5 · §2.2（數據保留）
RISKPRD §9

風險登記 8 項，Top 5 全部有緩解；5 個開放問題要喺動工前收口

#風險緩解措施
1現場網絡不穩（MQTT／SOAP 斷線）Gateway 本地 buffer＋重連重試、retained 狀態 topic、延遲納入 NFR 監控
2承辦商 expiry 管理失誤提前 30／7 日提醒、到期自動停權、owner／admin 專屬管理、稽核留痕
3site_admin 自升權限API 與 RLS 雙層硬性禁止派 owner／admin；防禦性測試納入 UAT
4Invite link 洩漏／誤用一次性＋7 日過期＋鎖定 role／site；token hash 儲存；啟用後通知邀請人
5多租戶洩漏（RLS 誤配）RLS policy 隨 migration 版本管理、UAT 專項測試跨站洩漏、migration 審查
另有 3 項登記：單一中央 DB 瓶頸、感應器數據品質、現場人員唔慣用系統（見 PRD §9.1）。
開放問題 · 動工前確認
1SOAP／BACnet 供應商端點嘅實際認證與介面規格
2中央 Supabase 部署地區／資料主權要求
3承辦商評分公式加權比重（預設值）
4稽核日誌冷儲存方案嘅成本與合規取捨
5踢出站點後 membership 記錄保留 vs 刪除
i3 FM 混合式平台 · 設計與基建總結15來源：PRD v1.0 §9.1–§9.2
NEXT STEP現狀盤點 · PRD §8
啟航
指南針已經校好——設計圖完備、架構定案，
下一步唔係再畫圖，係向北方動工。
已有（設計階段產出）
18+2
設計頁面
18 主頁＋2 文件頁
2
PRD／ARD deck
規格文件已定稿 v1.0
token
設計系統
色階／元件已沉淀
下一步
1　S1 基建動工——設計系統、專案骨架、CI（M1）
2　確認 5 個開放問題，鎖定供應商介面規格
3　按 M1–M6 節奏推進，每里程碑 demo＋驗收簽核
i3 FM 混合式平台 · 設計與基建總結16來源：PRD v1.0 §8 · 本 repo pages/ 現狀
01 / 16