# i3 FM 混合式平台 — 產品需求文件（PRD）

## 1. 文件資訊

| 項目 | 內容 |
| --- | --- |
| 文件名稱 | i3 FM 混合式平台 產品需求文件（Product Requirements Document, PRD） |
| 版本 | v1.0 |
| 日期 | 2026-09-03 |
| 作者 | i3 FM 設計團隊 |
| 適用專案 | i3-fm-platform-hybrid.design（設施管理平台） |
| 相關文件 | docs/ARD.md（架構需求文件）、pages/architecture.html、pages/access-control.html |

> 本文件以專案內 `.design` 頁面清單（18 個 page node）、`pages/access-control.html` 權限矩陣及 `pages/architecture.html` 系統架構圖為 ground truth，並延伸為可交付軟體專案之需求規格。凡屬「設計假設」之內容，均以「（假設：…）」標示，不等同於已定案之專案事實。

---

## 2. 產品概述、目標與目標用戶

### 2.1 產品概述

i3 FM 混合式平台（下稱「平台」）係一套一站式的設施管理（Facility Management, FM）平台，涵蓋報修票務、維修工單、定期保養、警報管理、緊急應變、能源分析、承辦商評分、合規管理、日結／月報、稽核日誌、用戶與角色、站點管理及平台總覽等功能，並以「平台總覽」頁面作為整個設計的導覽入口。

平台採用「混合式」部署形態：現場（站點）層每 site 獨立部署一套 Site Gateway 與前端 Web App，負責就地收斂現場數據；雲端層採用單一中央 Supabase／Postgres 實例，以 RLS（Row Level Security）按 `site_id` 做多租戶隔離，唔會每個 site 各自部署一套資料庫。現場數據經 MQTT（感應器）、BACnet/IP（BMS）及 SOAP（供應商系統）三種入口進入 Site Gateway，統一轉為 canonical JSON 後寫入中央數據平面（詳見 docs/ARD.md）。

### 2.2 產品目標

1. **單一系統覆蓋日常營運**：報修、派工、保養、警報、應變、能源、合規、報表集中喺一個平台，取代分散嘅表格與通訊工具。
2. **現場人員到場可追蹤**：in-house 電工師父（technician）與外判承辦商（contractor）到場都要喺系統報到，令「有冇人到場、幾時到場」有據可查。
3. **權責分明嘅帳號治理**：以 developer → support → site_owner → site_admin → site_staff → field（technician／contractor）嘅角色階層，確保每一層級只能管理其下層級，防止越權與自升權限。
4. **多站點統一管理、數據單一來源**：所有站點共用一個中央資料庫，Root Console 可跨站唯讀總覽；前端按站點隔離部署，RLS 確保站點之間數據互不可見。
5. **合規與稽核可追溯**：合規事項到期管理、稽核日誌全面留痕（record 不可修改、保留 180 日、可匯出 CSV）。

### 2.3 目標用戶（Persona 簡介）

| Persona | 角色 | 痛點 | 平台期望 |
| --- | --- | --- | --- |
| 陳大文（40 歲，站點負責人／site_owner） | 觀塘宏利大樓 FM 主管 | 承辦商到場冇紀錄、報修靠電話追蹤 | 一眼睇晒工單／警報／保養狀況，invite 承辦商並設 expiry |
| 李慧敏（32 歲，營運員／site_staff） | 日常營運操作 | 每日要喺唔同表格度寫嘢 | 票務池集中派單、日結自動匯總、月報自動生成 |
| 鍾先生（50 歲，駐場電工師父／technician） | 現場維修 | 開工唔知邊度有工、做完唔知點上報 | 工單指派清晰，到場用系統報到，完工即時更新 |
| 黃師傅（35 歲，承辦商師傅／contractor） | 外判維修 | 入大廈要登記、完工證明靠紙張 | 憑 invite link 自助註冊，到期自動失效，完工記錄喺系統留底 |
| Root／system 管理員（developer） | 開發公司後台 | 多站點各自為政、升級困難 | Root Console 統一總覽、中央後台管理所有站點帳號 |

---

## 3. 角色與權限模型摘要

平台角色階層（完整權限矩陣見 `pages/access-control.html`「角色階層與權限矩陣」）：

```
developer（系統開發 · 全系統總管）
├── support（開發公司 customer support · 全系統唯讀＋人事查詢）
└── site_owner（站點負責人 · 單 site · 可多位 co-owner）
    └── site_admin（站點管理員 · 專責 account 管理 · 全 site 人事）
        └── site_staff（站點員工 · 日常操作）
            └── field（現場維護 · 到場需報到）
                ├── technician（駐場電工師父 · in-house · 無 expiry）
                └── contractor（承辦商 · 有 expiry · 由 site admin／owner 管理）
```

### 3.1 管理鏈規則

- **developer**：全系統總管，可以 handle 所有 site 嘅帳號；擁有角色定義／系統設定權限（唯一具此權限嘅角色）。
- **support**：開發公司 customer support，後台全系統唯讀、可查閱人事資料（唯讀）、可檢視現場報到紀錄；**唔可以開任何 account**、冇 invite link 權限、冇 contractor expiry 管理權。
- **site_owner**：管理自己 site 嘅帳號，可 invite 同級 co-owner，亦可 invite admin／staff／contractor；可睇自己 site 全部人事資料；可設 contractor 期限。
- **site_admin**：專責 account 管理，可存取全 site 人事資料；**只可派 staff／field 下級角色，唔可以派 owner／admin**（防止自升權限）；可設 contractor 期限。
- **site_staff**：日常操作，可喺自己 site 範圍做設備／資產 CRUD 及讀取數據；冇 account 管理權、冇 invite 權。
- **technician／contractor（field）**：只接觸被指派嘅項目（設備 CRUD、數據讀取都係「只限指派」）；兩者到場都要喺 system 報到；contractor 嘅帳號有 expiry，到期自動失效、過期後無法報到；technician 係 in-house、無 expiry，但一樣要報到。

### 3.2 權限矩陣摘要（共 8 項權限能力）

| 權限能力 | developer | support | site_owner | site_admin | site_staff | technician | contractor |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Account 管理（開／停用／派權限） | 全部 | 只讀 | 自己 site（可 invite 同級） | 自己 site（只可派下級） | 無 | 無 | 無 |
| 人事資料存取 | 全部 | 全部（唯讀） | 自己 site | 自己 site | 只睇自己 | 只睇自己 | 只睇自己 |
| 設備／資產 CRUD | 全部 | 只讀 | 自己 site | 只讀 | 自己 site | 只限指派 | 只限指派 |
| 數據讀取（監測／工單／報表） | 全部 | 全部（唯讀） | 自己 site | 自己 site | 自己 site | 指派項目 | 指派項目 |
| Invite link 發出 | 全部 | 無 | 自己 site（含同級） | 自己 site（只可下級） | 無 | 無 | 無 |
| Contractor expiry 管理 | 全部 | 無 | 自己 site（可設期限） | 自己 site（可設期限） | 無 | 無（in-house 冇 expiry） | 無（自身受管理） |
| 現場報到 | 檢視 | 檢視 | 檢視（自己 site） | 檢視（自己 site） | 檢視 | **需要報到** | **需要報到**（過期報唔到） |
| 角色定義／系統設定 | 全部 | 無 | 無 | 無 | 無 | 無 | 無 |

### 3.3 關鍵設計要點（來自 access-control.html 決策卡）

- **Invite link 流程**：site_owner／site_admin 揀好權限先 send invite link；link 有 expiry（例如 7 日）同埋用後即棄；對方用 link 自己 set 密碼，唔使 admin 代設。
- **Contractor 與 in-house 師父**：兩類人都係 field 角色、到場都要喺 system 報到；contractor 帳號受 expiry 限制（由 site admin／owner 管理，到期自動失效）；in-house technician 冇 expiry，但同樣要報到。
- **site_members 一對多**：一位 staff／contractor 可以服務多個 site，每個 site 嘅 membership 各自記錄 role、status 同 expiry；跨 site 帳號唔會互撞。

---

## 4. 資訊架構：18 個頁面清單

以下按 `.design` 嘅 18 個 page node（id＋title）列出，並附一句功能描述。平台總覽頁（page-home）將頁面分為「營運中心」「分析與報告」「系統與架構」三大群組。

| # | Page id | 標題 | 一句功能 |
| --- | --- | --- | --- |
| 1 | page-home | 平台總覽 | 平台導覽首頁，將全部功能頁面分組列出（營運中心／分析與報告／系統與架構），並提供前往儀表板嘅入口。 |
| 2 | page-login | 登入（站點實例 / Root） | 站點登入頁：揀站點、輸入用戶名稱與密碼登入；支援「以 Root 帳戶登入中央控制台」；底部顯示版本（離線優先 · 本地實例 v1.4.2）及繁中／EN 切換。 |
| 3 | page-dashboard | 儀表板 | 平台首頁工作台：今日營運率、進行中工單、未處理警報、今日能耗、裝置健康等關鍵指標；7 日能耗趨勢與警報分布；header 提供搜尋、主題切換、繁中／EN、通知。 |
| 4 | page-ticket-pool | 票務池 | 統一收集報修單同查詢，集中分類、指派同追蹤：SLA 達標率、平均回覆時間、逾期票單；可按優先級／狀態／樓層／承辦商篩選，「新增票單」快速開單。 |
| 5 | page-alert-cockpit | 警報中心 | 集中睇警報、研判風險同處理系統異常：未處理／處理中／今日新增警報統計（自動＋手動），按等級／系統／狀態／時間篩選，「新增規則」設定警報產生規則。 |
| 6 | page-emergency | 緊急應變 | 緊急情況嘅通報、應變流程同現場協調：「開始應變」、應變等級、已動員人數、平均到場時間（對比目標）、中央上報狀態（快照同步）、當值應變團隊、事故事件時間線、值班表。 |
| 7 | page-maintenance | 維修工單 | 由開單、派工到完工記錄嘅完整維修流程：工單分「新單／處理中」分組展示，含優先級、SLA 剩餘時間、承辦商、負責人。 |
| 8 | page-maintenance-plan | 保養計劃 | 定期保養排程、預警同執行記錄：本月完成率（對比目標）、到期任務、逾期數；計劃表列出任務、頻率（每日／每週／每月／每季／每年）、下次／上次執行日期、狀態、負責人。 |
| 9 | page-energy-analysis | 能源分析 | 能源用量趨勢、用電分析同比對：總能耗、峰值功率、平均功率、碳排估算、24 小時能耗曲線、能源 breakdown；支援今日／本月／本年切換及匯出。 |
| 10 | page-vendor-scoring | 承辦商評分 | 承辦商表現評分、完工質素同可靠性追蹤：評分排名（評分、評級、平均回應、完成率、合約到期、趨勢、操作），「評分規則」設定計分標準。 |
| 11 | page-compliance | 合規 | 法規同內部標準嘅合規檢查同記錄：合規事項表格（電力裝置檢查、水質檢測、升降機註冊續期、滅火筒檢驗等等），狀態（通過／未通過／待核查／已到期）、風險等級、下次全面合規審計日期。 |
| 12 | page-end-of-day | 日結 | 每日營運結算：日結進度、8 項檢查清單（巡檢完成、未處理警報覆核、工單狀態確認、能耗記錄上傳、異常事件確認、合規檢查掃描、明日值班交接、日結簽署）。 |
| 13 | page-monthly-report | 月報 | 每月營運總結報告：營運率、總工單／已關閉、警報趨勢（同比）、能耗（同比）、全年能耗趨勢柱狀圖、工單分類占比。 |
| 14 | page-audit-log | 稽核日誌 | 操作審計全面留痕：保留 180 日、記錄不可修改、可匯出 CSV；按動作（登入／登出、開立工單、更新設定、刪除記錄、上報中央、匯出報表）／使用者／結果／日期範圍篩選；來源分中央監控台／本地實例。 |
| 15 | page-users-roles | 用戶與角色 | 用戶同角色管理：角色摘要（管理員、營運員、檢視員等展示標籤）、用戶列表（用戶、角色、狀態、最後登入、操作：編輯／停用）、「邀請用戶」發送 invite link。 |
| 16 | page-sites | 站點管理（中央控制台） | Root 中央控制台嘅站點總覽：已部署站點／在線／待同步／緊急警報統計，站點卡片（名稱、地區、類型、在線狀態、版本、營運率、裝置數、待處理、查看監控）、「新增站點」。 |
| 17 | page-architecture | 系統架構圖 | 系統架構說明頁：現場層（MQTT／BACnet／SOAP 三數據源 → Site Gateway）→ 雲端中央 Supabase（RLS 按 site_id 隔離）→ 前端（Site Web App 每 site 獨立部署＋Root Console 唯讀）；附數據流說明同核心設計決定。 |
| 18 | page-access-control | 角色與權限架構 | 角色階層樹狀圖、8 項權限能力矩陣、三張決策卡（Invite link 流程、Contractor 與 in-house 師父、site_members 一對多）。 |

---

## 5. 功能需求：20 個 Session

本階段將產品按「基建 → 登入 → 權限 → 站點 → 營運 → 現場 → 分析 → 報表 → 收尾」推進，明確分為 20 個 session。每個 session 包含：**名稱、目標、範圍（涉及頁面／模組）、用戶故事、驗收標準、依賴（前一個 session）、產出物**。

> 每個 session 嘅驗收標準以「可以喺真實環境操作驗證」為原則；涉及非專案既定事實嘅細節（如密碼長度、MQTT topic 格式）均以「（假設：…）」標示。

### Session 1：專案 setup 與設計系統基建

- **目標**：建立專案基建（monorepo 目錄、版本控制、CI 基礎）、設計系統 token（顏色、字型、間距、圓角）、共用元件庫與頁面框架，確保後續 19 個 session 喺一致嘅設計系統上開發。
- **範圍**：全平台共用基建；對應 `.design` 嘅 `colors_and_type.css`、`components.css` 及 18 個頁面共用嘅 header/sidebar/卡片/表格/表單元件。
- **用戶故事**：
  1. 作為開發者，我希望專案有統一嘅目錄結構同設計 token，令每個新頁面都唔使重新發明樣式。
  2. 作為開發者，我希望有共用嘅元件（按鈕、表格、卡片、篩選器、badge、modal），令 18 個頁面嘅視覺一致性有保證。
  3. 作為設計師，我希望 token 分 primitive 與 semantic 兩層並支援 light/dark，令主題切換唔使逐頁改。
- **驗收標準**：
  1. 建立 `apps/`（前端）與 `infra/`（資料庫 migration、gateway）目錄及 minimap 文件。
  2. CSS token（brand/background/text/state 色階、字型、radius、shadow、light/dark semantic mapping）落地並被至少 3 個頁面引用。
  3. 共用元件庫包含：Button、Badge、Card、Table、Select、Input、Field、Modal、Tabs、Toast，並有使用範例頁。
  4. CI pipeline 可以執行 lint 與 build。
- **依賴**：無（本 session 係第一站）。
- **產出物**：專案骨架、設計 token CSS、元件庫與元件文件、CI 配置。

### Session 2：登入與 Auth 流程

- **目標**：實現站點登入（揀站點 → 用戶名稱 → 密碼）與「Root 帳戶登入中央控制台」雙模式登入，並建立 session 管理與登出。
- **範圍**：page-login（登入（站點實例 / Root））；後端 Auth（JWT 簽發、session、refresh）；支援繁中／EN 與版本標示（離線優先 · 本地實例 v1.4.2）。
- **用戶故事**：
  1. 作為 site_staff，我希望喺登入頁揀屬於自己嘅站點再輸入帳密，令我只會進入自己站點嘅實例。
  2. 作為 root（developer），我希望用「以 Root 帳戶登入中央控制台」進入 Root Console，統一管理所有站點。
  3. 作為用戶，我希望登入後 session 過期或登出後要重新驗證，確保帳號唔會被他人冒用。
- **驗收標準**：
  1. 登入頁可以揀站點（以真實站點清單填充，例如觀塘宏利大樓／荃灣工廈A座／銅鑼灣商場）、輸入用戶名稱與密碼登入；密碼錯誤有明確錯誤訊息。
  2. Root 登入入口可以跳轉至中央控制台並以 developer 身份載入。
  3. JWT 發行、過期與 refresh 流程完成；（假設：access token 有效期 2 小時、refresh token 7 日）。
  4. 登出會清除 session 並返回登入頁；登入／登出動作寫入 audit_log（供 Session 17 使用）。
- **依賴**：Session 1（共用元件與 token）。
- **產出物**：登入頁完成品、Auth API（login/logout/refresh）、audit_log 登入事件寫入、密碼策略初版。

### Session 3：RBAC 角色層級與權限矩陣實作

- **目標**：按 `pages/access-control.html` 定義嘅角色階層同 8 項權限能力矩陣，實作 RBAC 角色模型同權限檢查（前端路由守衛＋後端授權）。
- **範圍**：page-access-control（角色與權限架構）；roles／permissions 資料模型；前端 route guard、menu 按角色顯示；後端 API 授權 middleware。
- **用戶故事**：
  1. 作為 developer，我希望系統內建 7 個角色（developer／support／site_owner／site_admin／site_staff／technician／contractor），每層可 handle 其下層級。
  2. 作為 support，我希望系統只俾我唯讀權限，令我可以查人事但唔會誤改數據。
  3. 作為 site_admin，我希望系統禁止我派 owner／admin 角色，防止我自升權限。
  4. 作為 site_staff，我希望登入後只見到我有權限嘅功能，唔會見到 Account 管理入口。
- **驗收標準**：
  1. roles 表內建 7 角色，同 access-control 階層一致；permissions 與 8 項權限能力一一對應。
  2. 前端 route guard：無權限用戶無法進入對應頁面（403 或隱藏入口）；menu 按角色動態渲染。
  3. 後端 API 全部有角色／權限檢查；特別驗證：site_admin 嘗試 create owner/admin 會被拒絕、support 所有寫操作被拒絕。
  4. page-access-control 頁面可以讀取真實角色與權限資料渲染矩陣（而非死資料）。
- **依賴**：Session 2（登入後先有身份可判斷角色）。
- **產出物**：RBAC 資料模型、權限檢查 middleware、路由守衛、轉入 matrix 頁之動態資料。

### Session 4：Invite link 與 account 管理（site_members 一對多）

- **目標**：實作「揀好權限先 send invite link」流程，link 有 expiry 同用後即棄；對方收到 link 自己 set 密碼；以 site_members 表支援一對多（同一人可喺多個 site 有唔同角色）。
- **範圍**：page-users-roles（用戶與角色）；invites 表、site_members 表、users 表；invite email 發送（假設：使用電郵發送 invite link，實際閘道（SMTP）可於本 session 用假 provider stub）。
- **用戶故事**：
  1. 作為 site_owner，我希望揀好角色（可含同級 co-owner）先產生 invite link，令邀請有明確權限邊界。
  2. 作為受邀者，我希望用 link 自己 set 密碼啟動帳號，唔使 admin 代設。
  3. 作為 site_admin，我希望只可以邀請 staff／field，令到唔會誤派高階角色。
  4. 作為一位服務多個 site 嘅 staff，我希望同一個登入帳號喺每個 site 有獨立權限與狀態，唔會互相影響。
- **驗收標準**：
  1. Invite link 產生時必須鎖定 role 同 site；(假設：expiry 預設 7 日、可用後即棄、一次性使用)；已過期或已使用嘅 link 無法啟動帳號。
  2. 受邀者註冊流程：自行設定密碼 → 建立 users 記錄 → 建立對應 site_members 記錄（含 role/status/expiry）。
  3. site_members 一對多：同一個 user 加入第二個 site 時，新增獨立 membership；兩站點權限互相獨立、唔會互撞。
  4. 管理鏈驗證：owner 可 invite owner/admin/staff/contractor；admin 只可 invite staff/technician/contractor；support 冇 invite 權。
- **依賴**：Session 3（RBAC 角色與權限）。
- **產出物**：invites 表與註冊流程、site_members 表、邀請用戶 UI、invite link 過期／用後即棄機制。

### Session 5：站點管理與 onboarding

- **目標**：實現站點（site）資料模型、建立站點流程（Root）與站點 onboarding（首次登入設定、Gateway 註冊準備），對應 page-sites 站點管理（中央控制台）。
- **範圍**：page-sites（站點管理（中央控制台））；sites 表、site 設定（時區、地址、類別）、站點上線狀態（已部署／在線／待同步）。
- **用戶故事**：
  1. 作為 root（developer），我希望可以新增站點並設定基本資料，令新大廈可以快速 onboarding。
  2. 作為 root（developer），我希望站點列表顯示已部署站點／在線／待同步／緊急警報，令我掌握全港站點健康狀況。
  3. 作為站點 owner，我希望站點上線後自動建立首個 site_owner 帳號（由 root 指派），令管理鏈有起點。
- **驗收標準**：
  1. sites 表完成，包含名稱、地區、類型、（假設：時區、地址、Gateway 配置欄位）；Root 可以新增／編輯站點。
  2. 站點管理頁統計卡（已部署、在線、待同步、緊急警報）同站點卡片網格以真實數據渲染。
  3. 每次新 site 建立後可指派一名 site_owner；該 owner 登入後只能見到自己站點。
- **依賴**：Session 4（account 與 membership 體系）。
- **產出物**：sites 表與 CRUD、站點管理頁動態數據、site onboarding 流程文件。

### Session 6：儀表板

- **目標**：實現站點儀表板（page-dashboard）——關鍵指標、7 日能耗趨勢、警報分布，作為登入後嘅營運首頁。
- **範圍**：page-dashboard；聚合查詢（KPI、趨勢、分布）；header 通用區（搜尋、主題切換、繁中／EN、通知）。
- **用戶故事**：
  1. 作為 site_staff，我希望開機即見到今日營運率、進行中工單、未處理警報、今日能耗、裝置健康，唔使逐頁開。
  2. 作為 site_owner，我希望睇到 7 日能耗趨勢同警報分布，快速掌握異常方向。
  3. 作為任何站點用戶，我希望 header 有通知入口同繁中／EN 切換，符合日常工作習慣。
- **驗收標準**：
  1. 五個 KPI 卡以真實數據計算（營運率、工單、警報、能耗、裝置健康；（假設：統計口徑於本 session 凍結並寫入文件））。
  2. 7 日能耗趨勢折線圖與警報分布（按系統分類）以 telemetry／alerts 數據渲染。
  3. 儀表板只顯示用戶所屬 site 嘅數據（RLS 生效驗證）。
- **依賴**：Session 2、5（登入後先有站點上下文；站點資料先存在）。
- **產出物**：KPI 聚合查詢、儀表板頁面、通知中心雛形。

### Session 7：票務池

- **目標**：實現票務池（page-ticket-pool）——報修單／查詢集中收集、篩選、指派與 SLA 追蹤。
- **範圍**：page-ticket-pool；tickets 表；SLA 設定與計算；篩選器（優先級／狀態／樓層／承辦商）；「新增票單」。
- **用戶故事**：
  1. 作為 site_staff，我希望開一張票單可以揀優先級（嚴重／高／中／低）、狀態、樓層同承辦商，令派單有足夠資訊。
  2. 作為營運員，我希望一眼睇到 SLA 達標率、平均回覆時間、逾期票單同進行中數目，令我跟進有焦點。
  3. 作為 site_owner，我希望所有票單自動記錄更新時間同操作者，令責任可追蹤。
- **驗收標準**：
  1. tickets 表完成（票號如 T-2026-09xx、主題、樓層、優先級、狀態、承辦商、更新時間、操作者）。
  2. 統計卡（SLA 達標率＝達標／總數、平均回覆時間、逾期、進行中）由真實資料計算。
  3. 篩選器全部可組合使用；「新增票單」表單可在票務池原地開單並即時出現喺列表。
  4. （假設：SLA 規則——嚴重 30 分鐘內首次回應、高 60 分鐘、中 4 小時、低 24 小時；本 session 將規則參數化）。
- **依賴**：Session 6（儀表板有票單數據入口基礎；承辦商資料於 Session 11 完善，本 session 可先以承辦商名錄 stub）。
- **產出物**：tickets 表與開單流程、SLA 計算引擎、票務池頁面、篩選器。

### Session 8：維修工單

- **目標**：實現維修工單（page-maintenance）——由開單、派工到完工記錄嘅完整維修流程，工單分「新單／處理中」分組。
- **範圍**：page-maintenance；maintenance_work_orders 表；工單狀態機（新單 → 處理中 → 待驗收 → 已完成）；派工畀 field 人員（technician／contractor）；SLA 剩餘時間顯示。
- **用戶故事**：
  1. 作為營運員，我希望由票單一鍵轉為工單，令報修到維修有連續追蹤。
  2. 作為技術員，我希望睇到自己被指派嘅工單同優先級、SLA 剩餘時間，令我知道邊張單最急。
  3. 作為 site_owner，我希望工單可以指派畀指定承辦商或內部師父，並記錄負責人。
- **驗收標準**：
  1. maintenance_work_orders 表完成（工單編號如 WO-2409-xxx、優先級、SLA 剩餘、承辦商、負責人、狀態）。
  2. 工單狀態機完整，「新單／處理中」兩組卡片正確流轉；完工需填寫結果同時間。
  3. SLA 剩餘時間由完成期限倒數計算；（假設：工單完成期限與優先級掛鈎，場地以 48 小時為預設上限）。
  4. 派工可選 technician 或 contractor；被派者只見到指派畀自己嘅工單（「只限指派」權限落地）。
- **依賴**：Session 7（票單轉工單）、Session 3（field 只限指派權限）、Session 10（完工後現場報到銜接）。
- **產出物**：工單表與狀態機、派工流程、維修工單頁面。

### Session 9：保養計劃

- **目標**：實現保養計劃（page-maintenance-plan）——定期保養排程、預警同執行記錄，防止設備過期唔保養。
- **範圍**：page-maintenance-plan；maintenance_plans 表（任務、頻率、下次／上次執行日期、狀態、負責人）；完成率／到期任務／逾期統計；與 equipment 關聯。
- **用戶故事**：
  1. 作為 site_staff，我希望定期保養任務（消防年檢、升降機季度保養、冷氣風櫃月度清潔、後備電源測試、天台排水泵巡查等）自動排程，令唔會漏做。
  2. 作為 site_owner，我希望睇到本月完成率（對比目標）同逾期任務，令保養進度有 KPI。
  3. 作為技術員，我希望接到保養任務後可以標記完成並記錄執行日期。
- **驗收標準**：
  1. maintenance_plans 表完成，支援頻率：每日／每週／每月／每季／每年；狀態：排期中／進行中／已完成／逾期。
  2. 排程引擎按上次執行日期＋頻率計算「下次執行」，逾期判定以當前日期比較。
  3. 統計卡正確：本月完成率（完成／應完成，目標 90%）、到期任務（本週內）、逾期數。
  4. 完成保養任務會寫入執行記錄並更新上次日期；紀錄進入 audit_log。
- **依賴**：Session 8（工單與負責人體系）、Session 11（保養任務可指派承辦商）。
- **產出物**：maintenance_plans 表、排程引擎、保養計劃頁面、完成記錄流程。

### Session 10：現場報到（technician／contractor 到場報到）

- **目標**：實現現場報到機制——in-house 師父同承辦商到場都要喺 system 報到；報到紀錄可被管理角色檢視；contractor 過期後無法報到。
- **範圍**：field_attendance 表；現場報到 API（check-in／check-out）；報到紀錄檢視（developer／support／owner／admin 檢視、staff 檢視）；與工單／保養任務指派關聯。
- **用戶故事**：
  1. 作為技術員，我入到場地後喺 system 報到，令管理層知道我幾時到達。佢到場做嘢前必須完成報到（現場報到權限＝「需要報到」）。
  2. 作為承辦商師傅，我希望報到前系統會檢查我嘅帳號未過期，過期就報唔到，令到期承辦商自然失效。
  3. 作為 site_owner，我希望睇到今日邊個到場、幾時到場、負責邊張單，令現場管理有憑據。
- **驗收標準**：
  1. field_attendance 表完成（user、site、work_order_id（可空）、check_in_at、check_out_at、expiry 檢查結果）。
  2. technician 與 contractor 報到前必須通過權限檢查；contractor 對應 membership 已過期時報到請求被拒絕並返回明確錯誤。
  3. 報到／離開時間記錄並顯示喺指定工單詳情；管理角色可按站點查閱報到紀錄。
  4. 報到事件寫入 audit_log。
- **依賴**：Session 4（membership 含 expiry）、Session 8（工單指派）。
- **產出物**：field_attendance 表、報到 API（含 expiry 檢查）、報到紀錄頁面區塊。

### Session 11：承辦商管理與 expiry

- **目標**：建立承辦商（vendor／contractor）資料主檔與管理流程——contractor 帳號有 expiry、由 site admin／owner 管理、到期自動失效；對應承辦商評分所需嘅基礎資料。
- **範圍**：page-vendor-scoring（承辦商評分）之基礎資料、contractors／vendor_scores 相關表；contractor membership expiry 管理 UI；合約到期欄位。
- **用戶故事**：
  1. 作為 site_admin，我希望為每個承辦商帳號設定有效期，到期自動失效，令合約結束後佢自動冇得報到同接單。
  2. 作為 site_owner，我希望承辦商列表顯示合約到期日，令我提前安排續約（例如合約到期 2027-01-31）。
  3. 作為承辦商供應商，我希望平台登記我嘅基本資料（公司名、服務範疇），令我被指派時有正確記錄。
- **驗收標準**：
  1. contractors 表／contractor membership 完成，含 expiry；site_owner／site_admin 可以設定與延長期限；到期後系統自動將該 membership 轉為失效。
  2. 到期承辦商無法報到（與 Session 10 連結驗證）、無法再被指派新工單；已指派未完成嘅工單會出現提醒。
  3. 承辦商評分頁可顯示承辦商名錄、（假設：評分公式——由回應時間、完成率、完工質素加權得出，規則由「評分規則」設定，本 session 只凍結構與 seed 數據）。
  4. developer 可跨站管理全部承辦商；support 唯讀。
- **依賴**：Session 4（membership 與 expiry 機制）、Session 10（expiry 影響報到）。
- **產出物**：contractors 表、expiry 管理 UI、到期自動停權排程、承辦商名錄 seed 數據。

### Session 12：警報中心與通知引擎

- **目標**：實現警報中心（page-alert-cockpit）——警報產生（自動＋手動）、分級、篩選、規則設定同通知引擎（header 通知鈴）。
- **範圍**：page-alert-cockpit；alerts 表；alert rules（自動產生規則）／手動建立警報；通知引擎（站內通知；假設：電郵／推送通知閘道於本 session 只留 interface 同 mock）。
- **用戶故事**：
  1. 作為營運員，我希望警報自動由規則產生（例如冷凍高壓跳掣），亦可以手動開警報，令異常唔會漏。
  2. 作為營運員，我希望按等級（嚴重／警告／提示）、系統（冷凍／電梯／消防／供水／電力／保安）、狀態、時間篩選警報，令工作台唔會太亂。
  3. 作為 site_owner，我希望「新增規則」可以設定警報產生條件，令系統自動監測關鍵設備。
  4. 作為任何用戶，我希望 header 通知鈴顯示未處理警報數目。
- **驗收標準**：
  1. alerts 表完成（等級、系統分類、狀態、產生來源：自動／手動、時間）；統計卡（未處理、處理中、今日新增）正確。
  2. 規則引擎可以產生警報（例如依 telemetry 閾值觸發）；（假設：規則定義於 alert_rules 表，包含條件、等級、目標系統）。
  3. 手動開警報流程完成；警報認領／處理狀態流轉（未處理 → 處理中 → 已解決）完成。
  4. 通知引擎：警報產生時 header 通知鈴即時更新；（假設：WebSocket 或輪詢做即時更新，本 session 可先以輪詢落地）。
- **依賴**：Session 13（telemetry 數據觸發自動警報；本 session 可先以 mock 數據驗證流程）。
- **產出物**：alerts 表、規則引擎、警報中心頁面、通知引擎雛形。

### Session 13：MQTT／SOAP 數據入口接線

- **目標**：實現 Site Gateway 嘅三個 adapter（MQTT Broker、BACnet Adapter、SOAP Adapter）與 Normalize 層，將現場原始數據統一為 canonical JSON（補 site_id＋timestamp）寫入中央 Supabase telemetry 表。
- **範圍**：page-architecture 所描述之 Site Gateway；MQTT（感應器：溫濕度・能耗・設備狀態）、BACnet/IP（BMS Points 輪詢）、SOAP（供應商 Web Service）；telemetry 表；service role 寫入管道。
- **用戶故事**：
  1. 作為開發者，我希望 Gateway 用同一個 canonical 格式接收唔同來源數據，令後端同報表永遠見到統一格式。
  2. 作為開發者，我希望 MQTT 訂閱支援保留訊息、重連與 QoS，令斷線後數據唔會永久流失。
  3. 作為開發者，我希望 SOAP 呼叫有錯誤重試同超時，令供應商系統唔穩定時有緩衝。
  4. 作為營運員，我希望能源與設備狀態數據可以流入能源分析同儀表板，唔使手動輸入。
- **驗收標準**：
  1. Site Gateway 完成並能在測試環境收到模擬 MQTT 訊息、輪詢 BACnet Points、呼叫 SOAP stub，三路數據喺 Normalize 後格式一致。
  2. telemetry 表 schema 完成（site_id、timestamp、來源、metric、value、unit、raw metadata）；Gateway 用 service role 寫入，前端唔會直接寫 telemetry。
  3. MQTT：訂閱 sensor topics、QoS≥1、斷線自動重連、狀態 topic 用 retained message；（假設：topic 命名 `i3fm/{site_id}/{device_id}/{metric}`，payload 為 JSON，於 ARD 第 6 節詳列）。
  4. SOAP：endpoint 認證（假設：HTTP Basic／WS-Security，以承辦商提供為主）、超時與重試（例如 3 次、指數退避）、失敗寫入錯誤日誌。
  5. BACnet：點表映射（BACnet Object/Property → canonical metric name）配置化，輪詢間隔可按 site 設定。
  6. 數據延遲驗證：感應器讀數到 DB 可見嘅端到端延遲（假設：≤10 秒，於 ARD 列為 NFR）。
- **依賴**：Session 1（gateway 基建）、Session 5（site 存在先有 site_id）。
- **產出物**：Site Gateway 三 adapter＋Normalize、telemetry 表與 service role 寫入、MQTT topic 規範、SOAP 錯誤處理策略、端到端數據流驗證報告。

### Session 14：能源分析

- **目標**：實現能源分析（page-energy-analysis）——總能耗、峰值／平均功率、碳排估算、24 小時能耗曲線同能源 breakdown，支援今日／本月／本年切換與匯出。
- **範圍**：page-energy-analysis；能源聚合查詢（由 telemetry 聚合）；碳排估算邏輯（假設：碳排係數按電力供應商提供，本 session 凍結構）。
- **用戶故事**：
  1. 作為 site_owner，我希望睇到今日／本月／本年總能耗同峰值功率，令能源表現有數得計。
  2. 作為營運員，我希望睇到 24 小時能耗曲線同各系統能源 breakdown，搵出異常時段。
  3. 作為管理層，我希望可以匯出能源數據，用於月報同向業主交代。
- **驗收標準**：
  1. 能源聚合係由 telemetry 真實數據計算（總能耗 kWh、峰值功率 kW 與錄得時間、平均功率 kW、碳排估算 kg）。
  2. 時間粒度切換（今日／本月／本年）與 24 小時曲線、breakdown 圖表正確渲染。
  3. 匯出功能可輸出報表（假設：CSV；月報則於 Session 19 整合節能數據）。
  4. 數據只限所屬 site（RLS）。
- **依賴**：Session 13（telemetry 真實流入）。
- **產出物**：能源聚合查詢、能源分析頁面、碳排估算設定、匯出功能。

### Session 15：緊急應變流程

- **目標**：實現緊急應變（page-emergency）——開始應變、應變等級、動員記錄、中央上報（快照同步）、當值團隊同事件時間線。
- **範圍**：page-emergency；incidents 表；應變狀態機（未開始 → 應變中 → 已結束）；中央上報（快照）；當值團隊與值班表。
- **用戶故事**：
  1. 作為營運員，我希望緊急事故（例如天台冷氣機組 F-02 高壓跳掣）可以一鍵「開始應變」，令流程即刻啟動。
  2. 作為應變指揮，我希望設定應變等級同已動員人數，並記錄平均到場時間（對比目標 15 分鐘），令應變效率可量度。
  3. 作為 site_owner，我希望事故可以「中央上報」並同步快照（例如快照 #128）到中央監控台，令 Root 掌握全港事態。
  4. 作為當值團隊成員，我希望事件時間線自動記錄「上報中央監控台、承辦商已出發」等節點。
- **驗收標準**：
  1. incidents 表完成（事故編號如 INC-092、標題、應變等級、狀態、動員人數、上報快照編號、時間線事件）。
  2. 「開始應變」後狀態流轉、時間線自動加「應變開始」節點；應變結束需填寫結論。
  3. 中央上報：快照生成並推送到 Root Console（唯讀顯示），建立 audit 記錄（動作＝上報中央）。
  4. 值班表以 users／site_members 資料呈現；「致電」操作顯示當值人員聯絡資訊。
- **依賴**：Session 6-8（工單／警報數據可掛入事故）、Session 12（警報可觸發事故建立）。
- **產出物**：incidents 表、應變狀態機、中央上報快照機制、事件時間線、值班表 UI。

### Session 16：合規

- **目標**：實現合規管理（page-compliance）——合規事項清單、到期追蹤、狀態同風險等級管理、全面合規審計排程。
- **範圍**：page-compliance；compliance_items 表；到期提醒；審計排程。
- **用戶故事**：
  1. 作為 site_admin，我希望登記合規事項（電力裝置定期檢查、水質檢測、升降機註冊續期、滅火筒檢驗、緊急照明測試、食水水質報告、外牆檢查等），令到期前有提醒。
  2. 作為 site_owner，我希望一次過睇到各事項狀態（通過／未通過／待核查／已到期）同風險等級，令優先處理有依據。
  3. 作為稽核人員，我希望「下次全面合規審計」有明確日期（例如 2026年10月12日），令審計節奏可預期。
- **驗收標準**：
  1. compliance_items 表完成（事項、類別、狀態、風險等級、下次檢查日期、負責人）；到期自動標記「已到期」。
  2. 狀態更新流程完成（通過／未通過／待核查／已到期），操作寫入 audit_log。
  3. 全面合規審計日期設定同到期前提醒（通知引擎接駁 Session 12）。
  4. 只有 owner／admin 可改狀態；staff 可檢視；（假設：support 唯讀可檢視）。
- **依賴**：Session 12（通知提醒）、Session 3（權限限制）。
- **產出物**：compliance_items 表、合規頁面、到期提醒、審計排程。

### Session 17：稽核日誌

- **目標**：實現稽核日誌（page-audit-log）——全平台操作留痕、記錄不可修改、保留 180 日、篩選與匯出 CSV。
- **範圍**：page-audit-log；audit_log 表；寫入點覆蓋所有寫操作（登入／登出、開立工單、更新設定、刪除記錄、上報中央、匯出報表）；來源（中央監控台／本地實例）。
- **用戶故事**：
  1. 作為稽核人員，我希望所有關鍵操作都有紀錄（時間、使用者、角色、動作、對象、結果、來源），令責任可追溯。
  2. 作為管理員，我希望稽核紀錄不可修改，保留 180 日，令證據可信。
  3. 作為管理員，我希望按動作／使用者／結果／日期範圍篩選，並匯出 CSV，令調查有效率。
- **驗收標準**：
  1. audit_log 表完成；所有既定寫操作（登入／登出、開立工單、更新設定、刪除記錄、上報中央、匯出報表）均自動寫入。
  2. 稽核記錄為 append-only（無 update／delete 入口；資料庫層以 trigger 或 RLS 禁止修改）。
  3. 保留策略：超過 180 日嘅記錄自動封存或清除（假設：封存至冷儲存，於 ARD 第 8 節細化）；目前頁面顯示「共 1,284 條」等真實統計。
  4. 篩選器全部可用；匯出 CSV 內容與畫面一致。
- **依賴**：Session 2-16 各 session 提供寫入點（本 session 統一收口同驗證）。
- **產出物**：audit_log 表、append-only 保護、稽核日誌頁面、CSV 匯出、保留策略設定。

### Session 18：日結

- **目標**：實現日結（page-end-of-day）——每日營運結算 8 項檢查清單、進度追蹤、夜班覆核與日結簽署。
- **範圍**：page-end-of-day；daily_close 表（檢查清單項目、完成狀態、簽署）；與警報／工單／能耗／合規／值班數據掛鈎。
- **用戶故事**：
  1. 作為夜班覆核人員，我希望日結有固定 8 項清單（巡檢完成、未處理警報覆核、工單狀態確認、能耗記錄上傳、異常事件確認、合規檢查掃描、明日值班交接、日結簽署），令收工冇遺漏。
  2. 作為站點主管，我希望睇到日結進度（例如 86%，已完成 7/8），知道仲爭邊項。
  3. 作為簽署人，我希望所有項目完成後先可以日結簽署，令日結有最終確認。
- **驗收標準**：
  1. daily_close 表完成，含 8 項標準清單項目、逐項完成狀態、完成時間與操作者、簽署記錄。
  2. 每項檢查可以完成並顯示進度百分比；部分項目（如未處理警報覆核、工單狀態確認）會自動預填當日對應數據供覆核。
  3. 未完成所有項目時無法簽署；簽署後該日日結凍結並寫入 audit_log。
  4. 月報（Session 19）嘅日數據以已完成日結為準。
- **依賴**：Session 6、7、9、12（日結各項對應之數據來源）。
- **產出物**：daily_close 表、日結頁面、簽署流程、日結凍結機制。

### Session 19：月報

- **目標**：實現月報（page-monthly-report）——每月營運總結：營運率、工單、警報、能耗（含同比）、全年趨勢同分類占比，支援自動生成。
- **範圍**：page-monthly-report；月報聚合查詢（跨 tickets／work orders／alerts／energy telemetry／daily close）；同比計算；生成排程（每月 1 日自動生成上月報表）。
- **用戶故事**：
  1. 作為管理層，我希望月報自動整合營運率、工單（開單／關閉）、警報（同比變化）、能耗（同比），令每月檢討有統一數據。
  2. 作為 site_owner，我希望睇到全年能耗趨勢柱狀圖同工單分類占比（空調、電力等），令年度計劃有依據。
  3. 作為管理層，我希望月報可以導出分享畀業主或公司管理層。
- **驗收標準**：
  1. 月報聚合可以生成：營運率、總工單（已關閉數）、警報總數（當月與同比）、能耗（當月與同比）。
  2. 全年能耗趨勢柱狀圖同工單分類占比圖正確渲染。
  3. 每月 1 日自動生成上月報告（假設：以 cron／排程 jobs 執行），亦支援手動重新生成。
  4. 月報只涵蓋已完成日結嘅月份數據（與 Session 18 銜接）。
- **依賴**：Session 18（日結數據）、Session 14（能源數據）、Session 7-8（工單／警報數據）。
- **產出物**：月報聚合查詢、月報頁面、自動生成排程、導出功能。

### Session 20：UAT、部署、培訓同上線

- **目標**：完成使用者驗收測試（UAT）、正式部署（中央 Supabase＋各站點 Gateway 與前端）、培訓材料同上線，確保平台可以正式營運。
- **範圍**：全平台端到端；UAT 劇本（按 18 個頁面設計）；部署文檔（architecture.html 嘅部署邊界）；培訓（管理員／營運員／現場人員）；上線切換與支援。
- **用戶故事**：
  1. 作為測試用戶，我希望跟 UAT 劇本逐頁驗證功能，令上線前發現嘅問題有系統收集。
  2. 作為 root（developer），我希望有部署手冊可以喺新站點重複部署 Site Gateway 同前端，令擴站可複製。
  3. 作為營運員，我希望有培訓材料（繁中）涵蓋日結、月報同緊急應變操作，令上線後有人識用。
  4. 作為管理層，我希望上線計劃包含數據遷移同 rollback 方案，令切換風險可控。
- **驗收標準**：
  1. UAT 完成：18 個頁面均有測試案例與結果記錄；P0／P1 缺陷全部關閉（假設：P0＝阻礙上線必須修、P1＝嚴重影響營運、P2 可在上線後補）。
  2. 部署手冊完成：中央 Supabase 初始化 migration 執行、RLS 政策驗證、Site Gateway 部署（containers）與前端 build 部署流程；（假設：Gateway 以 container 部署於站點伺服器／邊緣裝置）。
  3. 培訓材料完成並完成至少一輪培訓；上線後設支援窗口同監控 dashboard。
  4. 上線檢查清單通過：備份、監控、稽核日誌啟動、contractor expiry 排程執行、月報自動生成排程就緒。
- **依賴**：Session 1-19 全部完成。
- **產出物**：UAT 報告、部署手冊、培訓材料、上線檢查清單、支援計劃。

---

## 6. 非功能需求

### 6.1 保安（Security）

1. **身份驗證**：密碼強度政策（（假設：最少 12 字元、需含大小寫與數字；禁止常見弱密碼））、登入失敗鎖定（（假設：連續 5 次失敗鎖定 15 分鐘））、JWT access／refresh 機制（見 Session 2，access 2 小時／refresh 7 日）。
2. **授權（RBAC＋RLS）**：所有 API 必須通過角色權限檢查；所有資料查詢必須通過 Postgres RLS 按 `site_id`／角色範圍隔離；前端 Route guard 為 UX 輔助，後端授權先係保安邊界。
3. **資料傳輸**：所有前端↔後端、Gateway↔中央數據平面通訊使用 TLS；MQTT 建議 TLS（（假設：MQTT over TLS 8443）；於 ARD 第 6 節細化）。
4. **敏感資料**：密碼以 bcrypt/argon2 雜湊儲存；refresh token 以 httpOnly cookie 或安全儲存處理；人事資料（姓名、電話）僅對授權角色可見（見權限矩陣「人事資料存取」欄）。
5. **稽核**：所有關鍵寫操作寫入 append-only audit_log（見 Session 17）。
6. **Invite link 安全**：link 一次性使用、7 日過期（見 Session 4）；不接受以 link 改變已鎖定嘅 role／site。

### 6.2 效能（Performance）

1. 頁面載入：前端首屏（LCP）目標（假設：≤ 2.5 秒，4G 網絡、典型站點規模）。
2. 儀表板／能源分析聚合查詢（假設：月報與能源聚合以 materialized view 或排程預聚合支援，常用查詢 P95 ≤ 2 秒）。
3. 即時數據：感應器讀數到 DB 可見端到端延遲（假設：≤ 10 秒）；警報產生到通知鈴更新（假設：≤ 30 秒，先以輪詢落地）。
4. Gateway 吞吐：單 Gateway 支援現場設備規模（假設：每站點 ≤ 2,000 個 telemetry 點、每秒 ≤ 50 條訊息）而無數據堆積。
5. 稽核日誌大量寫入不得影響交易路徑（假設：audit 以獨立寫入路徑／列隊處理）。

### 6.3 可用性（Usability）

1. 介面語言：繁中／EN 雙語切換（登入頁、儀表板 header 均有切換入口）；以繁中為預設。
2. 響應式：桌面優先，支援平板（現場人員以流動裝置報到；（假設：報到頁提供流動友好嘅簡化表單））。
3. 無障礙基礎：顏色對比（狀態色如警報紅／警告橙須滿足 AA 對比）、鍵盤操作支援主要流程、表單錯誤訊息清晰。
4. 協助現場工作：SLA 倒數、優先級色帶、逾期標示清晰可見，現場人員一眼判斷優先次序。

### 6.4 可擴展性與可維護性

1. **單一中央數據平面**：所有站點共用一個 Supabase／Postgres 實例，以 `site_id` 做邏輯隔離（RLS）；新增站點只係新增 site 記錄同部署 Gateway，唔需要新資料庫。
2. **橫向擴展**：（假設：中央實例以連線池與讀寫分離應對增長；Gateway 每 site 獨立，天然水平攤分現場連線）。
3. **版本管理**：Site Web App 顯示「本地實例 v1.4.2」等版本號；部署以 immutable build 進行；migration 向前兼容。
4. **可配置**：SLA 規則、警報規則、評分規則、碳排係數、審計保留期全部參數化，可經設定淺層調整，唔使改 code。

---

## 7. 數據需求摘要

核心資料實體（詳細 schema 與 access 備註見 docs/ARD.md 第 5 節）：

| 資料實體 | 一句說明 | 主要負責 Session |
| --- | --- | --- |
| users | 用戶主檔（帳號、密碼雜湊、全域身份） | S2、S4 |
| roles | 7 個內建角色定義（developer／support／site_owner／site_admin／site_staff／technician／contractor） | S3 |
| permissions | 8 項權限能力（Account 管理、人事存取、設備 CRUD、數據讀取、Invite、Contractor expiry、現場報到、角色定義／系統設定） | S3 |
| site_members | 用戶↔站點一對多 membership（role、status、expiry） | S4 |
| invites | Invite link（role、site、expiry、用後即棄） | S4 |
| sites | 站點主檔（名稱、地區、類型、狀態） | S5 |
| tickets | 票單（樓層、優先級、狀態、承辦商、SLA） | S7 |
| maintenance_work_orders | 維修工單（派工、負責人、SLA、狀態機） | S8 |
| maintenance_plans | 保養任務排程（頻率、下次／上次執行、狀態） | S9 |
| field_attendance | 現場報到（check-in／check-out、關聯工單） | S10 |
| contractors | 承辦商主檔（公司資料、合約到期） | S11 |
| vendor_scores | 承辦商評分（回應、完成率、質素） | S11 |
| alerts | 警報（等級、系統、狀態、自動／手動來源） | S12 |
| telemetry | 現場感應器讀數（MQTT／BACnet／SOAP 統一後） | S13 |
| incidents | 緊急事故（等級、動員、中央上報快照、時間線） | S15 |
| compliance_items | 合規事項（狀態、風險等級、下次檢查） | S16 |
| audit_log | 稽核日誌（append-only、保留 180 日） | S17 |
| daily_close | 日結（8 項清單、簽署、凍結） | S18 |
| monthly_reports | 月報結果（自動生成、同比） | S19 |

數據管理規則：RLS 按 `site_id` 隔離為默認；`audit_log` 例外（跨站點由 developer／support 查閱）；資料保留策略（audit 180 日、telemetry 之原始數據（假設：保留 13 個月後聚合歸檔）、報表永久）於 ARD 第 5 節細化。

---

## 8. 里程碑與交付計劃

| 里程碑 | 內容 | 對應 Session | 目標時長（假設） |
| --- | --- | --- | --- |
| M1 基建 | 設計系統、專案骨架、CI | S1 | 第 1 週 |
| M2 身份與權限 | 登入、Auth、RBAC、Invite、account 管理、站點 onboarding | S2–S5 | 第 2–4 週 |
| M3 核心營運 | 儀表板、票務池、維修工單、保養計劃 | S6–S9 | 第 5–8 週 |
| M4 現場與整合 | 現場報到、承辦商 expiry、警報中心、MQTT／SOAP 接線 | S10–S13 | 第 9–12 週 |
| M5 分析與應變 | 能源分析、緊急應變、合規 | S14–S16 | 第 13–15 週 |
| M6 報表與收尾 | 稽核日誌、日結、月報、UAT、部署、培訓、上線 | S17–S20 | 第 16–20 週 |

（假設：以上時長為 20 週基準估算；實際以團隊規模同優先序調整。）交付節奏：每個 milestone 結束前做一次 demo＋驗收簽核；每 session 產出物須入版本控制並有對應測試。

---

## 9. 風險與開放問題

### 9.1 風險登記

| 風險 | 影響 | 緩解措施 |
| --- | --- | --- |
| 現場（site）網絡不穩定，MQTT／SOAP 斷線 | 數據缺口、警報延遲 | Gateway 本地 buffer＋重連／重試、狀態 topic retained、error 日誌；數據延遲 NFR 監控 |
| 承辦商 expiry 管理失誤（唔記得續約責任人） | 到期承辦商仍出現喺場地、安全風險 | expiry 提前提醒（通知引擎）、到期自動停權、owner/admin 專屬管理、稽核留痕 |
| site_admin 自升權限 | 越權管理 | 後端硬性禁止派 owner/admin 角色；防禦性測試納入 UAT |
| Invite link 洩漏／被誤用 | 未授權帳號 | 一次性＋7 日過期＋鎖定 role/site；啟動後通知邀請人 |
| 多租戶數據洩漏（RLS 誤配） | 跨站點資料外洩 | RLS 政策版本管理、UAT 專項測試、migration 審查 |
| 單一中央 DB 成為瓶頸／單點 | 全平台受影響 | 監控、連線池、讀寫分離、備份＋還原演練；單一 instance 係既定架構，須以容量規劃支撐 |
| 感應器數據品質差（重複、錯單位） | 能源／警報失真 | Normalize 層驗證、單位標準化、數據品質監控 |
| 現場人員（師父）唔慣用系統 | 報到記錄不全 | 報到流程極簡、流動裝置友善、培訓材料；管理層由上而下推動 |

### 9.2 開放問題（需於設計／實作期間確認）

1. SOAP／BACnet 供應商端點嘅實際認證方式與介面規格（本文暫以「（假設：HTTP Basic／WS-Security）」標示）。
2. 中央 Supabase 實例嘅實際部署地區／資料主權要求（影響 telemetry 成本同延遲）。
3. 承辦商評分公式嘅加權比重（「評分規則」設定之預設值）。
4. 稽核日誌冷儲存方案之成本與合規取捨（180 日後封存／清除）。
5. 踢出站點後既有 membership 記錄嘅保留處理（保留歷史 vs 物理刪除）。

---

（文件完）