Sites Related Pages

View 頁面左半部的 Sidemenu 是 Site 的 Tree View（階層清單）。因為裝置改以 Site 組織，這個 Tree View 新增了搜尋，讓操作者在龐大的 site 階層裡快速定位。

流程 Happy Path

1. 進入 View 頁面，左側 Sidemenu 顯示 Site 的 Tree View，頂部有搜尋。
2. 輸入文字即時過濾，搜尋範圍涵蓋 site 名稱、area 名稱、device 名稱；命中節點的祖先自動展開。

左側清單即 Tree View；其展開 / 收合、搜尋自動展開匹配路徑、選取等行為以 Design Pattern: Tree View 為準，此處不重述。

本頁右半部的內容以當前 Production 為準，本次專案未修改，因此 UI Key Screen 不做呈現。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 View 頁面，Then 左側 Sidemenu 顯示 Site 的 Tree View 與搜尋。
• Given 在搜尋輸入文字，Then 過濾出 site / area / device 名稱含該文字的節點並自動展開其祖先（行為同 Tree View）。

元件與 Token 決策

• 左側 Sidemenu = Tree View（見 03）；本頁新增的是 Tree View 的搜尋，搜尋範圍 = site / area / device 名稱。
• 右半部沿用 Production、本次未動。

Customized View 的編輯模式（挑選要放進自訂 View 的裝置）裡，每個 Camera 以 by-site 路徑 （Sites Breadcrumb） 標示所屬位置，讓操作者在多站環境下辨識來源。

流程 Happy Path

1. 進入 Customized View 編輯模式，顯示可挑選的裝置清單。
2. 每個 Camera 以 Sites Breadcrumb 顯示其 site 路徑（葉層為當前 site）。
3. 清單頂部提供搜尋，搜尋範圍涵蓋 site 名稱、area 名稱、device 名稱。

Camera 的 site 路徑以麵包屑呈現；其顯示與截斷規則以 Sites Breadcrumbs 為準，此處不重述。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 Customized View 編輯模式，Then 每個 Camera 以 by-site Sites Breadcrumb 標示所屬位置（截斷規則同 06）。
• Given 在搜尋輸入文字，Then 過濾出 site / area / device 名稱含該文字的裝置。

元件與 Token 決策

• Camera 位置以 Sites Breadcrumbs（見 06）呈現。
• 搜尋範圍 = site / area / device 名稱（module-search-bars spec）。

TODO / 未解問題

• 搜尋列所連元件（Tree View / Filter Combo）以實作為準，本頁不臆測；空狀態文案以實作為準。

Floorplans 頁面左半部的 Sidemenu 是 Site 的 Tree View（階層清單）。它新增了搜尋，讓操作者 快速定位到某個樓層平面圖或其所屬位置。

流程 Happy Path

1. 進入 Floorplans 頁面，左側 Sidemenu 顯示 Site 的 Tree View，頂部有搜尋。
2. 輸入文字即時過濾，搜尋範圍涵蓋 site 名稱、area 名稱、floor plan 名稱、device 名稱；命中節點的祖先自動展開。

左側清單即 Tree View；其展開 / 收合、搜尋自動展開匹配路徑、選取等行為以 Design Pattern: Tree View 為準，此處不重述。

本頁右半部的樓層圖檢視內容以當前 Production 為準，本次專案未修改，因此 UI Key Screen 不做 呈現。（下方的 Create floor plan 對話框與 xLite 商業頁是另外兩個表面，本次有涵蓋。）

Create floor plan 對話框 Create dialog

Create floor plan 對話框有三個必填欄位，由上而下：

底部按鈕為 Submit 與 Cancel。

Site 欄位使用單選 Site picker 的收合形式（picker 只是表單欄位之一，不是對話框的主體）， 規格見 Section 09 —— 觸發器尺寸、popover 幾何與層級、選取樣式、搜尋與空狀態都由該節擁有， 本節不重述。

版面（key screen Floorplans-create floor plan，11233:117818）：對話框 540 × 510 （header 70 + content 370 + footer 70 = 510），左右內距各 40，故欄位寬 460；輸入框與 Site 觸發器同為 460 × 32，檔案上傳區 460 × 154（內含 64 × 64 插圖）；底部兩顆按鈕各 160 × 42。

xLite Free plan

xLite 組織不提供 Floorplans 功能。本頁整個 content area 換成商業頁，比照 AI Hub / Archive / Profile Search 的處理；直接開 /sites/:siteId/floor-plans 會 redirect 到商業頁。

商業頁說明文字（character-exact）：

See the entire property at a glance. VORTEX Floor Plan turns building layouts into interactive security maps — with cameras placed at their real-world positions and coverage areas visualized on screen. To access this feature, contact your reseller for upgrade options.

版面（key screen Floorplans-paid features dark mode，7583:18976）：

OpenSpec 只寫 replace the full content area，未界定 Site 樹是否在內；覆蓋範圍以 key screen 的 overlay 節點自 x = 64 起算為準。

商業頁的版面遵循 organization-license-lifecycle 的 Locked Feature Commercial Pages （該 requirement 同時規範 AI Hub / Profile Search / Archive / Cloud Backup 等鎖定功能，並定義 商業頁的可見性須符合自訂角色權限）。

Site 頁裡的 Floor plan 區塊是另一條規則，不要混用：那裡只換掉區塊自己、Devices 區塊仍在， 文案較短且 CTA 是 Explore Floorplans（導向本功能頁），見 Site Management US8。本頁是整頁替換 + redirect，行動方向是聯絡經銷商。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 Floorplans 頁面，Then 左側 Sidemenu 顯示 Site 的 Tree View 與搜尋。
• Given 在搜尋輸入文字，Then 過濾出 site / area / floor plan / device 名稱含該文字的節點並自動展開其祖先（行為同 Tree View）。
• Given 開啟 Create floor plan，Then 顯示 Floor plan name *、Site *、Floor plan file * 三個必填欄位與 Submit / Cancel。
• Given 開啟 Create floor plan 且尚未選 Site，Then Site * 欄位顯示 placeholder Select a site 與朝下的 chevron（收合形式，行為見 Section 09）。
• Given xLite 組織進入 Floorplans 頁，Then 整個 content area 顯示商業頁而非樓層圖清單。
• Given xLite 組織直接開啟 /sites/:siteId/floor-plans，Then redirect 到商業頁。

元件與 Token 決策

• 左側 Sidemenu = Tree View（見 03）；本頁新增的是 Tree View 的搜尋，搜尋範圍 = site / area / floor plan / device 名稱。
• 右半部的樓層圖檢視沿用 Production、本次未動。
• Create floor plan 對話框：Modal/custom/md 540 × 510；欄位寬 460；Site 欄位為 Dropdown / outline (Radius) 460 × 32，即 Section 09 的收合形式觸發器。
• xLite 商業頁：整頁替換，樣式遵循 organization-license-lifecycle 的 locked feature 商業頁。

TODO / 未解問題

• Upgrade 按鈕的行為未確認：key screen 只呈現它存在於 header 右上，點擊後導向何處 （升級說明頁、聯絡經銷商、或開啟對話框）未在 key screen 或 OpenSpec 中定義。
• 商業頁底圖是一張宣傳圖（1856 × 1160 的圖片填充），實作時該圖的來源與是否需要 多語系 / 多解析度版本未定，待確認。

Device 模組重整為依產品類型分頁的清單，每個分頁有專屬欄位集。清單預設以 device name 排序， 並提供跨欄位搜尋與 Statuses / Sites 兩個篩選器（site 既是欄位也是篩選維度，但不是排序鍵）。

流程 Happy Path

1. 進入 Device 模組，頂部依產品類型分頁：Camera / NVR / Bridge / Network Speaker / PoE Switch / VSS / Unknown。
2. 選一個類型分頁，顯示該類型專屬欄位的清單，預設以 device name 排序。
3. 用搜尋列可跨所有可見欄位搜尋；用 Statuses 與 Sites 兩個篩選器縮小範圍。各分頁工具列一致。
4. 開欄位設定可顯示 / 隱藏欄位（順序固定，不可重排），偏好依使用者、依清單類型記住。

搜尋 + 篩選 + 類型分頁為 Filter Combo 統一樣式，套用於 Devices / Message Center / Archive / Users；其互動細節以 Design Pattern: Filter Combo 為準，此處不重述。

各類型欄位集 Columns per type

VSS 是唯一同時有 firmware 與 software 兩欄的類型，其餘類型只有 firmware （OpenSpec device-type-list-views 明列，見 ADAT-850）。

Unknown 的欄位順序與其他類型一致，並且有 status 欄。 OpenSpec device-type-list-views · Unknown device list 目前寫成 site, device name, device ID——順序與 其餘六類相反，且沒有 status，卻又在同一份規格定義了「依 status 篩選 Unknown」的 scenario， 本身不自洽。ADAT-968 已確認 Unknown 的 status 取得得到且恆為 Offline，因此本節以四欄 device name、status、site、device ID 為準，OpenSpec 待發 PR 對齊。

status 欄各類型的實際換算規則（四組行為不同、Network Speaker 一律 -、PoE Switch 另有 Unknown 狀態值）見 01 Site Management US3「Status 欄的顯示規則」，此處不重列。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 Device 模組，Then 顯示 Camera / NVR / Bridge / Network Speaker / PoE Switch / VSS / Unknown 七個類型分頁。
• Given 載入任一類型清單，Then 預設以 device name 排序（不以 site 排序）。
• Given 在搜尋列輸入文字，Then 過濾出「任一可見欄位」包含該文字的裝置。
• Given 選取 Statuses 或 Sites 的篩選值，Then 只顯示符合的裝置。
• Given 顯示 / 隱藏欄位並儲存，Then 下次進入時還原該偏好（依使用者、依類型）。
• Given 開啟欄位設定，Then 沒有任何重排欄位的控制項，欄位維持固定順序。
• Given 檢視 Unknown 分頁，Then 顯示 device name、status、site、device ID 四欄，欄位順序與其他類型一致。
• Given 檢視 VSS 分頁，Then 同時顯示 firmware 與 software 兩欄（其餘類型只有 firmware）。
• Given 切到 Unknown 分頁，Then 工具列與其他分頁一致（Search + Statuses + Sites）。
• Given 在 Unknown 分頁選 Online 或 Updating，Then 清單為空；選 Offline，Then 顯示該分頁全部裝置。

元件與 Token 決策

• Pattern：Filter Combo（搜尋列 + Statuses / Sites 篩選 + 類型分頁）。
• 每類型獨立欄位集、預設 sort by device name、搜尋跨所有可見欄位、篩選維度為 Statuses 與 Sites。
• 稱法：UI 的 chip 標籤是 Statuses / Sites，欄位清單裡的規格名稱是 status / site，兩者指同一資料（與 Time / client time 的關係相同，見 Message Center 章節）。
• 欄位可設定：僅顯示 / 隱藏，偏好依使用者、依清單類型持久化。不支援重排，順序固定（見 ADAT-819）。

TODO / 未解問題

• 空搜尋結果、載入中狀態的實際文案，待與實作對齊（OpenSpec 未定義文案）。
• software 欄的定義與來源未記載：OpenSpec 只列出欄位名稱，未說明它與 firmware 的差異、取值來源或格式。需與實作 / 設計確認後補述。
• Figma frame 17 - Devices（node 8292:22128）目前只截到 Camera 分頁，VSS 分頁（含 software 欄）尚無截圖，此節欄位表以 OpenSpec 為準。

Message Center 重整為依事件類型分頁的清單。與 Device 清單不同的是：事件清單的欄位是 固定的——只能排序，使用者不能自行顯示 / 隱藏欄位。

流程 Happy Path

1. 進入 Message Center，頂部依事件類型分頁：Device / System / Access / Sensor。
2. 選一個事件類型分頁，顯示該類型專屬欄位的清單，預設排序依分頁而定（見下表；Device / System 為 client time）。
3. 用搜尋列搜尋（範圍逐分頁而定，見下表；System 分頁沒有搜尋列）；用該分頁的篩選器縮小範圍。
4. 點欄位標頭可排序；但欄位集固定，不提供顯示 / 隱藏設定。

搜尋 + 篩選 + 事件分頁沿用 Filter Combo 統一樣式；互動細節以 Design Pattern: Filter Combo 為準，此處不重述。

各事件類型：欄位、預設排序、篩選 Per event type

Device / System 沒有 site 欄，但仍可依 site 篩選：事件記錄本身不帶 site 識別，後端亦無 可解析的 API，故 site 僅為篩選維度（由前端解析），不作為欄位，也不可作為排序鍵（見 ADAT-795）。Access / Sensor 的 associated sites 是各自記錄上的欄位，與此無關。

篩選器中的時間維度（依 client time 篩選）在本表以 Time 指稱；該 chip 在畫面上不顯示「Time」字樣，而是顯示當前選中的區間（預設 Last 1 hour）；欄位 清單仍以規格名稱 client time 呈現，兩者指同一資料。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 Message Center，Then 顯示 Device / System / Access / Sensor 四個事件類型分頁。
• Given 載入 Device 或 System 事件清單，Then 預設以 client time 排序（不以 site 排序）；Access 依 access control point、Sensor 依 sensor name。
• Given 在 Device 分頁搜尋列輸入文字，Then 只過濾 information 欄包含該文字的事件。
• Given 在 Access 分頁搜尋列輸入文字，Then 只過濾 card holder 欄包含該文字的事件。
• Given 檢視 System 分頁，Then 沒有搜尋列。
• Given 檢視任一事件清單，Then 沒有欄位顯示 / 隱藏設定（欄位固定，僅可排序）。

元件與 Token 決策

• Pattern：Filter Combo（搜尋列 + 各分頁篩選 + 事件類型分頁）。
• 每事件類型獨立欄位集與篩選維度；預設排序 Device / System 為 client time、Access 為 access control point、Sensor 為 sensor name。
• Device / System 無 site 欄：site 僅為篩選維度（前端解析），不可作為排序鍵。
• 欄位固定、僅可排序，使用者不可顯示 / 隱藏（對比 Devices 的可設定欄位）。

依據 unify-search-filter-tag-ux / proposal.md「event list columns cannot be shown or hidden」（ADAT-544，PR 未合併），與 message-center-event-type-views · spec 一致。 注意 main 上的通則 bullet 仍寫可顯示 / 隱藏，是過時敘述，不採用。

TODO / 未解問題

• Figma 的裝置篩選 chip 標為 Cameras，OpenSpec 寫的是 device（Device / System 兩分頁皆然）。兩者是否同一維度、UI 標籤採哪個，需與設計確認（相關命名議題見 ADAT-815）。
• 空搜尋結果、載入中狀態的實際文案，待與實作對齊（OpenSpec 未定義文案）。
• Sensor 分頁的搜尋範圍未定：其餘三個分頁已確定（Device 只搜 information、Access 只搜 card holder、System 無搜尋列），Sensor 待設計確認，暫以實作為準。

Archive 有兩種檢視模式——卡片模式（下圖所示的縮圖卡片網格）與列表模式（表格）。 兩種模式共用同一套搜尋與篩選；欄位的顯示 / 隱藏只在列表模式提供。

流程 Happy Path

1. 進入 Archive（上圖為卡片模式）：頂部一列搜尋（只搜 file name 欄，不跨其他欄位） + 篩選 chip（Sites、Cameras、Time） + 排序控制；下方是封存檔案的縮圖卡片網格，每張卡片含縮圖、檔名、camera 名稱、日期時間與影片長度。
2. 篩選 chip 沿用 Filter Combo：Sites、Cameras 為 chip 上的實際文案；時間維度的 chip 不顯示「Time」字樣，而是顯示當前選中的區間（單選、預設 Last 1 hour）；對應 OpenSpec archive-list-view 的 site、device、date of footage 篩選，可多重套用（取交集）。
3. 排序：OpenSpec 定義預設以 date of archived 排序、所有欄位皆可升 / 降序。
4. 切換到列表模式時顯示表格，欄位集：snapshot、file name、camera name、site、date of archived、date of footage、video length、created by；列表模式下可開欄位設定顯示 / 隱藏欄位（偏好依使用者記住）。卡片模式不提供欄位設定。

搜尋 + 篩選沿用 Filter Combo 統一樣式；chip、Time 選單、cross-filter 等互動以 Design Pattern: Filter Combo 為準，此處不重述。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 Archive 卡片模式，Then 顯示封存縮圖卡片網格（每張含縮圖、檔名、camera、日期時間、影片長度），頂部有搜尋 + Sites / Cameras / Time chip。
• Given 切換為列表模式，Then 顯示欄位 snapshot、file name、camera name、site、date of archived、date of footage、video length、created by，且可顯示 / 隱藏欄位（卡片模式無此設定）。
• Given 載入，Then 預設以 date of archived 排序（不以 site 排序）；所有欄位可升 / 降序。
• Given 在搜尋列輸入文字，Then 只過濾 file name 欄包含該文字的封存項目（搜尋範圍不含其他欄位）。
• Given 套用 Sites / Cameras / Time chip（可多重），Then 只顯示符合全部條件的項目（AND）。

元件與 Token 決策

• Pattern：Filter Combo（搜尋列 + Sites / Cameras / Time chip，取交集 AND）。
• 兩種檢視模式：卡片模式（縮圖網格，截圖所示）與列表模式（表格）。
• 預設 sort by date of archived；所有欄位可升 / 降序。
• 列表模式下欄位可顯示 / 隱藏（依使用者持久化）；卡片模式無此設定。

TODO / 未解問題

• 卡片 / 列表模式切換與卡片模式的完整規格：OpenSpec 的 archive-list-view 以列表欄位為主，未定義卡片模式細節；以實作為準。
• 欄位重排：裝置清單已明文不支援重排（OpenSpec device-type-list-views）；但 Archive 的 spec 只定義了顯示 / 隱藏與排序，沒有對欄位順序表態——Archive 是否同樣固定順序需確認，勿逕自套用裝置清單的規則。
• 空狀態訊息的實際文案，待與實作對齊。

User 清單以 搜尋列 + Organization role 篩選 chip 組成一個 Filter Combo，讓管理者依角色 篩選、並在名稱 / email 上搜尋。

流程 Happy Path

1. 進入 User 清單，頂部有搜尋列與 Organization role 篩選 chip。本頁沒有 Site filter——這是唯一不含 Sites chip 的 filter combo 頁面。
2. 在搜尋列輸入文字即時過濾，搜尋範圍為欄位 name、email。
3. 用 Organization role chip 依角色篩選；搜尋與 role 篩選取交集（AND）。

搜尋列 + role chip 為 Filter Combo；其 chip、cross-filter（AND）等互動以 Design Pattern: Filter Combo 為準，此處不重述。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 進入 User 清單，Then 頂部顯示搜尋列與 Organization role 篩選 chip。
• Given 在搜尋列輸入文字，Then 過濾出 name 或 email 含該文字的使用者。
• Given 選取一個 Organization role，Then 只顯示該角色的使用者。
• Given 同時有搜尋字串與 role 篩選，Then 只顯示同時符合兩者（AND）的使用者。
• Given 已選一個 Organization role，When 再選另一個，Then 前一個被取代（單選，不會變成兩個條件）。
• Given Custom role 未指派給任何 user，Then 仍列於選單；選取後顯示空狀態（規則見 Filter Combo §03）。

元件與 Token 決策

• Pattern：Filter Combo（搜尋列 + Organization role 篩選 chip，取交集 AND）。
• 搜尋範圍 = name、email（見 ADAT-544）。

TODO / 未解問題

• 以 OpenSpec 為準：本頁依 ADAT-544（unify-search-filter-tag-ux 之 User list 修正， 搜尋範圍 name/email + 新增 Organization role 篩選）撰寫；該修正的 PR 合併後，補上 role chip 的預設值集與截圖。
• 空狀態訊息文案以實作為準。
• User 清單的預設排序未定義：Devices（device name）、Message Center（依分頁）、Archive（date of archived）都有明文，OpenSpec 對 User 清單則未表態，故本頁不敘述。需與設計確認是否補定義。

因為裝置改以 Site 組織，新增裝置前組織必須先有 Site。若沒有任何 Site，系統會擋下新增 並先導去建立 Site。

流程 Happy Path

1. 從 Site 頁面發起「新增裝置」。
2. 若組織已有 Site：顯示新增裝置流程，並提供 Site 指派選項。
3. 若組織沒有任何 Site：系統擋下新增，並導去建立 Site 的流程。空狀態文案為標題 「No Sites Found」+ 說明「Create a site to organize your devices.」，並就地提供「Create site」。

選擇 Site 使用單選 Site picker，此處為攤開形式（dialog 的職責是挑 Site，且沒有 Site 時 還要能就地建立），規格見 Section 09。本節維持「沒有任何 Site 時擋下並導去建立」與下方 Site 指派規則的權威，picker 那一節不重述這些。

Site 指派規則 Site assignment

Add device 的類型選單只提供 Camera、NVR、VSS、Bridge。Site management 不支援 PoE Switch 與 Network Speaker 機種，因此這兩類自選單隱藏。

若 PoE Switch / Network Speaker 所連的 bridge 尚未指派 Site，規格是放進 Default Site 供人工檢視並通知使用者無法自動指派。Default Site 有前提：它是遷移前組織那個與組織同名的 裝置群組沿用而來；依 site-migration，遷移後才建立的組織沒有 Default Site——該情境下這兩類 裝置的落點規格未定義，見下方 TODO。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 組織已有 Site 且發起新增裝置，Then 顯示新增流程與 Site 指派選項。
• Given 組織沒有 Site 且嘗試新增裝置，Then 系統擋下並顯示「No Sites Found」與「Create a site to organize your devices.」，且提供「Create site」入口。
• Given 新增 NVR 或 VSS，Then 須選擇 Site，且其 channels 自動指派同一 Site。
• Given 開啟 Add device 的裝置類型選單，Then 只出現 Camera、NVR、VSS、Bridge，沒有 PoE Switch 與 Network Speaker。
• Given PoE Switch 或 Network Speaker 經所連 bridge 裝置註冊進站，且該 bridge 已指派 Site，Then 自動指派到同一 Site，且全程不顯示選站步驟。
• Given PoE Switch 或 Network Speaker 經所連 bridge 註冊進站，但該 bridge 尚未指派 Site，Then 放進 Default Site 供人工檢視，並通知使用者該裝置無法自動指派。

元件與 Token 決策

• 無 Site 阻擋 + 導去建立 Site 為 Site 管理的前置守門；建立 Site 對話框見 01 Site Management。
• 類型選單僅四類（Camera / NVR / VSS / Bridge）；PoE Switch、Network Speaker 隱藏。此規則由 OpenSpec site-device-operations 定義。
• Site 選擇：單選 Site picker（攤開形式），規格見 Section 09；該 picker 不是 Tree View （無展開 / 收合），階層以縮排表達。

TODO / 未解問題

• bridge 未歸站時的落點，遷移後組織未定義：規格寫「放進 Default Site」，但 site-migration 同時規定遷移後才建立的組織沒有 Default Site。這類組織裡若 PoE Switch / Network Speaker 的 bridge 尚未指派 Site，裝置該落在哪裡沒有規格。此即 ADAT-834 留言中標示「下方待討論」的邊界， 已列為 tasks.md 15.4.6（PM 待決），15.4.5 標記為 blocked。
• 類型選單無截圖佐證：本節 key screen 只涵蓋「無 Site 時的 Select a site 空狀態」， 未拍到 Add device 的裝置類型選單，因此「只有四類、兩類隱藏」目前純以 OpenSpec 為準。 若要圖文對照，需要類型選單的 frame。
• Portal 與 App 規則分歧：Portal 隱藏這兩類（ADAT-834）；App 端規格 （app-site-sync、app-site-migration）只寫「不需選 Site」，沒有隱藏規則， app-site-device-picker 甚至明列 picker 應包含 PoE Switch 與 Network Speaker。ADAT-834 掛的是 [Portal]，是否要同步到 App 需與 PM 確認；在確認前 deck 08 維持 App 規格原樣。

需要「挑一個 Site」的流程共用同一個 picker。它有三個 consumer：Move devices（Site Management US4）、Add device（本 deck Section 08）、Add floor plan（本 deck Section 03）。

它不是 Tree View Not a tree

這個 picker 與 Design Pattern: Tree View 不是同一個元件，也沒有展開 / 收合。 所有層級一直可見，階層以縮排與每個 root Site 一組 表達。因此 Tree View 的樹狀行為（預設展開層級、搜尋自動展開、chevron 的 kind 規則）在此一律 不適用，本節不引用該 deck。

依 Figma 結構（11344:121404）：

與 Filter Combo 的關係是「共用零件」，不是「實例」。 選項列用的是 Filter Combo 同一組 Figma 元件（dropdown menu option，同一個 variant），但本 picker 不是 Filter Combo 的實例， 該 deck 目前也沒有任何 consumer 使用單選 site。耦合方向為反向：為 Filter Combo 修改 dropdown menu option 時，本 picker 會一併改變。

搜尋框則不是共用的：本 picker 用 Search bar (Radius)，而 Filter Combo 各 surface 用的是 另一組名為 search 的元件 —— 兩者是不同的 component set，不要因為都叫「搜尋框」就當成同一個。

攤開或收合 Inline or dropdown

判準：picker 是不是那個容器的主體。

新增的 consumer 依此判準決定形式。

攤開形式（Add device）—— 對話框標題 Select a site，清單直接展開佔滿內容區，右上角另有 Create site 讓沒有 Site 的使用者就地建立，底部為 Select / Cancel：

收合形式（Add floor plan）—— picker 只是 Create floor plan 表單的一個欄位，點擊 Site * 的觸發器後才往下展開成 popover，且該 popover 浮在對話框之上、下緣可超出對話框邊界：

兩張圖是同一組零件的兩種形態：清單本體（搜尋框 + 縮排選項列 + 左側打勾）完全相同，差別只在 有沒有觸發器、以及清單是直接攤開還是收在 popover 裡。

Current 不可選 Current location

Move devices 會把裝置當前所在的節點標為 Current 且不可選（不能移到原地）。

• Current 那一列不可選取，但它的子層仍然可選
• Current 與 disabled 是兩種不同狀態，不得混為一談

本節以 Figma key screens 為最終定案。 參考實作 SitePickerList-demo.html 目前是 placeholder Search、radio 選取、後綴 (Current)（帶括號），與本節的 Search sites、 左側打勾、Current 不一致。以 key screen 為準，該 demo 待更新。

這兩條 Current 規則源自 add-tree-view-component 的 "Current" Node in Pickers 與 Non-Selectable Node。上游措辭「不可選但仍可展開」以 Tree View 為前提；本 picker 沒有 展開收合，所有層級一直可見，因此沿用的是規則的意圖：排除 Current 不得擋住它的子層。 "Current" Node in Pickers 的權威在本節；Non-Selectable Node 留在上游，作為該元件的 一般能力（不限 picker）。

xLite Free plan

xLite 組織的 Site 只有單層，因此 picker 只列出單層、沒有縮排階層。規則見 Site Management 的 xLite 節。

容器可掛建立動作 Create affordance

Add device 的 dialog 同時帶 Create site，因為沒有 Site 時流程無法進行。該行為的權威在 Section 08，本節不重述。App 端的 Site Picker 也帶 Create site or area，同為家族既有做法。

本節限 Portal 範圍；App 端的 Site Picker 不是本節的先例。 08 App Sites Related Pages 的 Section 03 同樣叫 Site Picker、同樣有單選模式，但有兩點與本節相反：它是 tree （有展開 / 收合、以 └ 連接線呈現層級），而且選中列的勾選標記在右側（本節在左側）。 兩者不互為權威 —— 本節不得引用 App 端的視覺或互動當先例，App 端也不得 defer 給本節。 上一段提到 App 端的 Create site or area，只是說明「容器掛建立動作」在家族中並非首例， 不構成對本節任何規則的授權。

狀態與邊界

搜尋無命中的空狀態 No Matches Found

版面的權威在本節，值取自 key screen 12734:22084。本 picker 不是 Tree View、也不是 Filter Combo 的實例，沒有任何元件替它定版面。

整個列表區（452 × 352）換成空狀態、所有選項列隱藏；240 寬的區塊在列表區內水平與垂直皆置中 （左右各 106、上下各 110）：

容器層的東西不受影響——右上 Create site 仍可按（它在列表區之外），Select 為 disabled。

文案是平台統一字串，來源是 OpenSpec add-tree-view-component 的 No Matches Found Empty State —— 那兩句寫在要求本文裡，平台上各 surface 一律同一句，不因元件不同而分家。本節沿用的只有 文案；上游把版面歸給 Tree View 元件（「版面與樣式則屬本元件」），那條不涵蓋本 picker。

Figma 的節點名稱與實際綁定不一致。 標題與說明兩個 text node 都命名為 color-text02，但說明 實際綁的是 color-text/03（#C2C2C2）。以綁定為準，不要照節點名稱實作。

驗收條件 QA · Given-When-Then

• Given 任一 consumer 開啟 picker，Then 所有層級一次可見，沒有 chevron 或展開 / 收合控制。
• Given picker 是容器的主體（Move devices / Add device），Then 開啟即為攤開狀態。
• Given picker 只是表單欄位（Add floor plan），Then 初始為收合，點擊後展開為 popover。
• Given 已選一個 Site，Then 該列左側顯示打勾，不使用 radio。
• Given Move devices 的 Current 節點，Then 該列不可選，但其子層仍可選。
• Given xLite 組織，Then picker 只列單層 Site。
• Given 在搜尋框輸入，Then 清單依關鍵字過濾。
• Given Move devices 的 Current 列，Then 該列文字與 Current 後綴以 --color-text06 dimmed 呈現，且左側不顯示打勾。
• Given 收合形式尚未選取，Then 觸發器顯示 placeholder Select a site 與朝下的 chevron。
• Given 點開收合形式的觸發器，Then chevron 轉為朝上，popover 由欄位下緣展開、左緣與欄位對齊、寬度與欄位相同，並浮在對話框之上。
• Given 搜尋有命中，Then 命中文字以 --color-primary 底 + 白字 highlight，命中列的祖先一併顯示但本身不 highlight。
• Given 搜尋無任何命中，Then 顯示 No Matches Found 空狀態，文案為平台統一字串。
• Given 空狀態出現，Then 240 寬區塊在列表區水平與垂直皆置中，插圖 / 標題 / 說明由上而下間距 8、皆置中對齊，且不出現 CTA 按鈕。
• Given 空狀態出現，Then 所有選項列隱藏，但容器的 Create site 仍可按。
• Given 空狀態的說明文字，Then 使用 --color-text03（不是節點名稱所寫的 color-text02）。

元件與 Token 決策

• 選取標記：左側藍色打勾（icon / general / template + --color-icon06），不使用 radio；未選列的同一位置留白（Figma 中該 icon 槽 opacity: 0），所以有無打勾不會改變列的 文字縮排。App 端把勾放在右側，見上方 Portal 範圍註記。
• 列狀態：預設文字 --color-text03；hover 為整列底色 --color-surface05 + 文字 --color-text01；Current 為 --color-text06（dimmed）。已選列不帶底色，只靠打勾表示。
• Current 後綴：語意上是列尾的後綴（對應上游 Tree View 的 node-suffix 槽），與列文字 同為 --color-text06。Figma key screen 中 Basement 與 Current 是同一個 text node、用空白 排開，那是 mock 的畫法；實作必須是獨立的右對齊後綴，不得以空白對齊。
• 搜尋命中 highlight：底色 --color-primary、文字白色（--color-text01）。
• 收合形式的觸發器：Dropdown / outline (Radius)，460 × 32，與 Create floor plan 的其他 欄位同寬（對話框 540、左右內距各 40）。
• popover：site dropdown / menu，寬 459、高 480，左緣與觸發器對齊、由觸發器下緣 往下 8 展開。它在 Figma 中與 modal 同層而非 modal 的子節點，且下緣超出對話框範圍 —— 即浮在對話框之上的獨立浮層。內部為 filter（搜尋框，40）+ list（432）+ 右側 8 的捲軸。 觸發器 460 / popover 459 的 1px 差為 Figma 繪製誤差，實作以與欄位同寬為準。
• 攤開形式：同一個 site dropdown / menu 直接放進對話框 content，460 × 400（Move devices）。
• 空狀態：版面權威在本節（規格見上方小節，key screen 12734:22084）；只有文案是平台 統一字串，來源為 OpenSpec add-tree-view-component 的要求本文。

TODO / 未解問題

• Current 列的 hover 回饋：上游 add-tree-view-component 的 Non-Selectable Node 要求 「MUST still respond to hover」，但本 picker 沒有展開收合，hover 在此不是「為了展開」。 key screen 07 - Move Devices (Hover and Selected)（7768:41026）只示範可選列的 hover（Parking lot B2），Current 列在該圖為靜態 —— hover 回饋未在 key screen 中呈現，待確認。
• 收合形式「已選」時觸發器顯示什麼：23 - Create Floor Plan Select Site （11344:121404）是打開狀態，清單中 Building A 已帶藍勾，但觸發器仍顯示 placeholder Select a site；Figma 沒有「已選且收合」的 key screen。因此顯示 Site 名稱、 完整路徑、或其他形式無法從 key screen 判定，待確認（Section 03 需要這一項）。
• 無命中時既有選取是否保留、Select 是否維持可用：key screen 12734:22084 是「輸入 xyz 後無命中、且先前未選任何 Site」，Select 為 disabled。本節沒有選取保留規則 —— Tree View 的 「選取邏輯上保留但不可見」屬該元件行為，本 picker 不沿用 —— 因此「先選了一列、再搜尋到無 命中」時 Select 是否仍可按，無法從此 key screen 判定，待確認。
• highlight 的圓角與內距：key screen 只看得出底色與白字，數值無法量測。上游 Tree View 的 Search Filtering 定 border-radius: 4px、padding: 0 2px，本 picker 的實際值待確認。