App - Sites Related Pages

App 的 View 頁把裝置改成依 Site 分組呈現。清單為攤平（flattened）結構：每個 群組標題直接顯示該 Site 或 Area 的完整路徑（Site > Area > ...），而非縮排樹狀；群組 可收合。Site 列表與 Portal Site module 同步，Portal 為單一真實來源。

流程 Happy Path

1. 進入 App 的 View 頁（底部 tab bar 的完整項目待確認——App OpenSpec 未定義 tab bar）。
2. 頂部 control bar 顯示 Site 數量（截圖為「15 sites」）與一個「全部收合」控制。
3. 裝置依所屬 Site / Area 分組；群組標題以攤平的完整路徑呈現：
   • 直接掛在 Site 下：標題為 Site 名稱。
   • 掛在 Area 下：標題顯示自 Site 起算的完整路徑，各層以 > 分隔（如 Site > Area、 最深至 L4：Site > Area > Area > Area > Area）。
4. 每列裝置顯示縮圖、裝置類型圖示、裝置名稱（截圖佔位為「Camera name」）與「...」更多選單。
5. 點群組標題右側的箭頭可展開 / 收合該群組。

by-Site 路徑的顯示為 Sites Breadcrumbs 顯示慣例的 App 應用；該慣例（含截斷）的權威在 06 Sites Breadcrumbs。App 端的 分隔符與排序以 app-site-sync 為準，此處不重述截斷規則。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 View 頁，Then 裝置依所屬 Site / Area 分組顯示。
• Given 某群組掛在 Area 下，Then 標題顯示自 Site 起算、以 > 分隔的完整路徑。
• Given 攤平清單載入，Then Site 與 Area 依顯示標題升冪 alphanumeric 排序。
• Given Portal 端改名某 Site，Then App View 清單反映新名稱。
• Given 組織有未指派裝置，Then 清單出現以組織名稱命名的系統 Site；當其清空後自動移除。
• Given 檢視組織名稱 Site，Then 顯示指派引導；When 選取其中一台裝置，Then 提供指派到 Site / Area 的入口。
• Given 從組織名稱 Site 指派裝置失敗，Then 顯示錯誤且該裝置仍留在組織名稱 Site。
• Given 同步服務不可用，Then 顯示最後已知的 Site 清單並標示資料過期。
• Given Site 清單同步逾時，Then 顯示逾時訊息且清單仍以快取資料呈現。
• Given 即時 Site 更新同步失敗，Then 顯示同步狀態指示且更新排入重試。

元件與 Token 決策

• 群組為可收合的 accordion；群組標題採攤平完整路徑（非縮排樹狀）。
• 每列裝置：縮圖 + 類型圖示 + 裝置名稱 + 「...」更多選單。
• 攤平顯示與 Device Picker（見 Section 2）共用；tree 顯示則用於 Site Picker（見 Section 3）。

TODO / 未解問題

• control bar 的 Site 計數文案（截圖為「15 sites」）與「全部收合」控制的實際文案 / 圖示，以實作為準。
• 未指派裝置的指派引導文案（app-site-migration 定義行為，未定義 App 端文案），以實作為準。
• 上表四種同步 / 指派異常的呈現方式未定案。 app-site-sync 與 app-site-migration 只寫「顯示過期指示 / 逾時訊息 / 同步狀態指示 / 錯誤」，沒有定義是 banner、inline 標記還是 toast，也沒有文案。需與 PM 及 App 端確認後補上。
• 三條純後端的遷移異常（網路失敗、部分失敗、系統 Site 建立失敗）在規格中只有 log / queue / 通知管理員，沒有 App 端使用者可見畫面，因此本節不列狀態。若日後要對使用者揭露，需另立規格。

一個共用的裝置選取元件，取代 App 原本的 device picker。裝置依 Site 階層分組、以攤平 的群組標題呈現，支援多選。所有需要選裝置的 App 頁面都改用這個元件。

流程 Happy Path

1. 任一 App 頁面開啟裝置選取器，navbar 標題為「Device」，右上為「Save」。
2. 頂部搜尋列「Search devices」可在階層內搜尋，結果顯示其所屬 Site / Area 路徑。
3. control bar 顯示已選數量（截圖為「15 / 15 selected」）與右側「Deselect all」。
4. 裝置依所屬 Site / Area 分組；群組標題為攤平完整路徑（Site、Site > Area、最深 L4）， 可展開 / 收合。
5. 每列與每個群組標題左側都有 checkbox；群組層級的 checkbox 可一次選取 / 取消該群組下的裝置。
6. 選取完成點「Save」套用。

群組標題的 by-Site 路徑（Site > Area > ...）與 View by Site（Section 1）同為 Sites Breadcrumbs 顯示慣例的 consumer；該慣例的路徑組成與截斷規則權威在 06 Sites Breadcrumbs，此處不重述截斷規則。

套用此元件的頁面 Integration points

Message System event：NVR 與 Bridge 裝置顯示在其所屬的 Site 或 Area 之下。

Add Device / Move Device 的 Site 選取用的是 Site Picker（tree，見 Section 3 / 4）， 不是本裝置選取器。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 任一 App 頁面開啟裝置選取器，Then 裝置依其 Site > Area 階層分組顯示。
• Given 選取器顯示裝置，Then 涵蓋 Camera、NVR、VSS、Bridge、Network Speaker、PoE Switch 六類。
• Given 展開一個 Site 群組，Then 顯示其下的 Area 與裝置。
• Given 在「Search devices」搜尋，Then 過濾出相符裝置並顯示其 Site / Area 路徑。
• Given Member 使用者開啟選取器，Then 只顯示其有權限的 Site 與裝置。
• Given 在 Message System event 使用，Then NVR 與 Bridge 顯示於其所屬 Site 或 Area 之下。

元件與 Token 決策

• 攤平顯示（群組標題為完整路徑）與 View by Site（Section 1）共用；tree 顯示用於 Site Picker（Section 3）。兩種顯示模式由 app-site-sync 分別定義。
• 多選：每列 + 每群組 checkbox、control bar 顯示已選數量與「Deselect all」、navbar「Save」。
• 此元件為單一共用來源，各頁面沿用相同行為（app-site-device-picker）。

TODO / 未解問題

• 已選數量文案（截圖為「15 / 15 selected」）的實際格式，以實作為準。
• 群組層級 checkbox 的半選（部分選取）表現，截圖未涵蓋，以實作為準。

選取 Site / Area 的對話框，以 tree view 呈現 Site 與 Area 的層級關係（與 View by Site、Device Picker 的攤平顯示不同）。有多選與單選兩種模式，另含搜尋與空狀態。

兩種模式總覽 Multiple vs single select

多選模式 Multiple select

navbar 為「Cancel / Site / Save」，control bar 顯示「150 / 150 selected」與「Deselect all」， 每列右側為圓形 checkbox；勾選完成後點「Save」套用。

單選模式 Single select

navbar 為「Cancel / Site」、沒有 Save：點選某一列後，該列右側顯示藍色勾選標記，選取值 即被帶回、畫面直接跳轉回原本的畫面。右上提供「Create Site or Area」。

未選狀態：

點選一列後（已選）：

樹狀操作 Tree expand / collapse

1. Site 位於樹的最上層（列首為定位 pin 圖示）。
2. 展開一個 Site 節點 → 顯示其下的 L1 Area；Area 以樹狀連接線（└）縮排呈現。
3. 逐層展開：L1 → L2 → L3 → L4（最多 4 層 Area）。
4. 收合 Site 或 Area 節點 → 隱藏其子節點；無子節點者不顯示展開指示器。

樹狀展開 / 收合為通用 tree pattern；Portal 端的 Tree View 元件見 03 Design Pattern - Tree View。App 端 Site Picker 的展開層級（L1–L4）以 app-site-sync 為準。

與 03 的一處明示分歧： 無子節點時 App 不顯示展開指示器（app-site-sync · No expand indicator for childless nodes），Portal 的 Tree View 則一律顯示、只看節點種類。 兩邊各自有規格依據，不是筆誤。

搜尋 Search

於搜尋列輸入關鍵字（截圖為「area」）後，相符文字高亮；命中節點連同其父層 Site / Area 一併顯示，不相關節點隱藏（截圖為多選模式，命中列仍帶 checkbox）。

搜尋時「顯示命中節點的所有父層、隱藏不相關節點」的比對 / 展開行為沿用 Tree View 搜尋； 其權威在 03 Design Pattern - Tree View，此處不重述。

空狀態 Empty

無任何 Site 時顯示定位 pin 圖示與空狀態文案（文案權威在 02 Sites Related Pages §08）：「No Sites Found」與「Create a site to organize your devices.」，右上仍提供「Create Site or Area」。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 開啟 Site Picker，Then 以 tree view 呈現、Site 位於最上層。
• Given 展開一個 Site 節點，Then 顯示其下的 L1 Area。
• Given 展開 L1 / L2 / L3 Area 節點，Then 分別顯示 L2 / L3 / L4 Area。
• Given 收合某節點，Then 隱藏其子節點。
• Given 某 Site 或 Area 無子節點，Then 不顯示展開指示器。
• Given 在搜尋列輸入關鍵字，Then 相符文字高亮、命中節點連同其父層一併顯示、不相關節點隱藏。
• Given 單選模式點選一列，Then 該列顯示藍色勾且不出現多選的計數 / Save。
• Given 組織無任何 Site，Then 顯示「No Sites Found」空狀態。

元件與 Token 決策

• Tree view（縮排 + └ 連接線）；Site 列首為定位 pin，Area 依層級縮排。
• 兩種模式的差異：navbar（有無 Save）、每列控制（圓形 checkbox vs 藍色勾）、有無計數。
• Site Picker 用於 Add Device 的 Site 選取與 Move Device 目的地選取（見 Section 4）。

TODO / 未解問題

• 多選模式（checkbox + Save + 計數）的實際進入點 / 使用情境，app-site-sync 僅明確定義 單選目的地情境，多選入口以實作為準。
• 「150 / 150 selected」的實際計數格式，以實作為準。

搬移裝置時選取目的地 Site / Area 的畫面。沿用 Site Picker 的 tree 呈現，額外標出裝置 目前所在位置，並在底部提供固定的「Move device」按鈕。

流程 Happy Path

1. 對某裝置發動搬移，開啟「Move to」（navbar：Cancel / Move to）；control bar 左側提示 「Select a destination」，右側為「Create Site or Area」。以 tree 瀏覽 Site / Area，裝置目前 所在的 Area 標示「Current」、不可選（其下子場域仍可選）。

2. 點選目的地 Site 或 Area，該列顯示藍色勾選標記。

3. 點底部固定按鈕「Move device」送出搬移。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 開啟 Move to，Then 以 tree 顯示 Site / Area 且裝置目前位置標示「Current」、不可選（其下子場域仍可選）。
• Given 點選一個目的地，Then 該列顯示藍色勾。
• Given 點「Create Site or Area」，Then 可建立新 Site / Area 並指派為目的地。
• Given 選好目的地點「Move device」，Then 裝置搬移至該 Site / Area。

元件與 Token 決策

• Tree 呈現沿用 Site Picker（Section 3）；差異為 control bar 提示「Select a destination」、 標示「Current」（不可選、其下子場域仍可選）、底部固定「Move device」按鈕。
• 「Create Site or Area」建立行為以 Section 5 為權威。

TODO / 未解問題

• 無。（Current 節點的鎖定與 Portal 一致：僅鎖 Current 節點本身，上層、同層與其下子場域仍可選； 見「Move to redesign rationale」決策 2.6。）

與 Portal 的界線： Current 這條規則已經不在 OpenSpec 裡——add-tree-view-component 明載它 已移轉到 02 Sites Related Pages §09， 那裡是 Portal 側的唯一記錄處。App 端的三個 capability 都沒有定義 Current，因此本節的敘述目前 沒有 OpenSpec 依據，只有 key screen 與本 deck 的 rationale 檔。兩個 picker 的視覺與互動各自 為政、不互為權威，所以不逕行 defer 給 02 §09。

在 Add Device 與 Move Device 流程中，原本的「Create Site」按鈕改為「Create Site or Area」。 表單頂部以 segmented control 切換 Site / Area 兩種型別，欄位隨型別變動。xLite 組織不提供 Area，按鈕維持「Create Site」。

流程 Happy Path

1. 在 Site Picker（付費組織）點「Create Site or Area」，開啟建立表單（navbar：Create Site or Area / Create），頂部 segmented control 選「Site」或「Area」。
2. 選「Site」型別：填「Site name」（必填），「Site location (Optional)」可輸入地址或於 地圖上設定（「Type an address or set on the map」）。

3. 選「Area」型別：填「Area name」（必填），選「Parent site」（必填，「Select parent site」；父層可為 Site 或另一個 Area）。

4. 點右上「Create」建立；於 Add Device / Move Device 流程中可將裝置直接指派到新建的 Site / Area。

型別與欄位 Type-specific fields

xLite 與付費組織差異 Plan differences

結構上限 Structural limits

Site 結構的單一真實來源為 Portal Site module（見 01 Site Management）；App 端建立時以 app-site-sync 反映上述上限。

Add Device 的 Site 指派規則 Site assignment on Add Device

與 Portal 不一致，待 PM 確認：Portal 端把 PoE Switch 與 Network Speaker 從 Add device 的類型選單隱藏（ADAT-834，標記為 [Portal]）。App 端規格（app-site-sync、 app-site-migration）只寫這兩類「不需選 Site」，未要求隱藏，而 app-site-device-picker 明列 picker 應包含這兩種類型。上表依 App 現行規格撰寫；是否比照 Portal 隱藏尚未定案。

驗收條件 QA · Given-When-Then

• Given 付費組織於 Site Picker，Then 顯示「Create Site or Area」按鈕。
• Given xLite 組織，Then 顯示「Create Site」按鈕、無型別選擇、且不提供建立 Area。
• Given 選「Site」型別，Then 表單顯示 Site name（必填）與 Site location（選填）。
• Given 選「Area」型別，Then 表單顯示 Area name（必填）與 Parent site（必填）。
• Given 於 Add Device / Move Device 建立 Site / Area，Then 可將裝置指派到新建的節點。
• Given 組織無任何 Site 而發動 Add Device，Then 先提示建立 Site 才能繼續。
• Given 新增 NVR 或 VSS 並選定 Site，Then 其所有 channel 自動指派到同一 Site。
• Given 建立 Area 超過深度或每層數量上限，Then 系統擋下並提示對應上限錯誤。
• Given 發動 Add Device 但 Site 檢查因網路錯誤失敗，Then 顯示錯誤並可重試。
• Given Add Device 流程中建立 Area 失敗，Then 顯示錯誤、可重試，且重試後仍在原本的 Add Device 流程中。

元件與 Token 決策

• 表單：segmented control（Site / Area）+ list 型輸入欄位 + navbar「Create」。
• Site location 欄位帶地圖選取（chevron 進入）；Area 的 Parent site 欄位帶父層選取（chevron 進入）。

TODO / 未解問題

• 本節採 OpenSpec 的「Create Site or Area」（title case）——app-site-migration 以 SHALL 明確引用此按鈕文案。App key screen 看來是 sentence case「Create site or area」，需確認實作取哪個。
• 各上限錯誤訊息的實際文案（OpenSpec 定義行為，未定義文案），以實作為準。
• 上表兩種錯誤的呈現方式（inline 錯誤、alert 或 toast）與重試入口位置未定案，app-site-migration 只寫「顯示錯誤並允許重試」。

刪除裝置的破壞性確認畫面：要求使用者輸入「DELETE」才能執行，並警示資料將永久清除。

範圍註記：此畫面隨附於 App 設計板，但不屬於 site-management-for-app 三個 capability （app-site-sync / app-site-migration / app-site-device-picker）的需求範圍；其行為 / 驗收的 權威來源不在該 OpenSpec。本節僅據實呈現設計板上的畫面與文案；是否納入本次 Site 專案待與 PM 確認（見 TODO）。

畫面內容 What the screen shows

1. 頂部警示三角圖示。
2. 標題「Delete this device」，副標「All associated data will be permanently erased.」。
3. 紅色「WARNING!」與警示區塊，文案與 Portal 相同，權威在 01 Site Management US5。
4. 「Type DELETE to confirm」輸入欄（placeholder「DELETE」）。
5. 「Delete Device」按鈕（未輸入前為 disabled 樣式）與「Cancel」。

狀態與邊界

TODO / 未解問題

• 此「Delete device」是否屬本次 Site 專案範圍待 PM 確認；site-management-for-app 的三個 capability 未定義刪除裝置需求。
• 「Delete Device」的實際啟用條件（是否需完全相符「DELETE」、大小寫等）以實作為準。