# 麟曜數位工作室 完整文件

# 快速開始

HUAN 讙讓你在瀏覽器裡設計一面畫面，然後把它送到現場的螢幕上。

HUAN 讙讓你在瀏覽器裡設計一面畫面，然後把它送到現場的螢幕上。

這一頁帶你走完一次完整流程：從登入到第一面看板亮起來。

:::tip[這一份是給使用者的]

如果你要架設 HUAN、改程式或部署伺服器，請看[開發者文件](/huan/dev)。

:::

## 開始之前

你需要：

- 一組 HUAN 後台帳號。HUAN **不開放自助註冊**，帳號由管理員建立。
- 一台安裝好 HUAN 播放器的裝置（Raspberry Pi、Windows、Ubuntu 或 macOS），而且連得到你的 HUAN 伺服器。安裝方式見[安裝播放裝置](/huan/guide/install-raspberry-pi)。

## 1. 登入

打開你的 HUAN 網址，用管理員給你的 Email 或帳號登入。

<figure class="huan-figure">
	<img src="/huan/screenshots/login.png" alt="HUAN 登入畫面" />
	<figcaption>登入畫面</figcaption>
</figure>

登入後會看到總覽，上面是裝置的線上狀態與需要注意的項目。

建議第一件事是到「安全設定」[開啟兩步驟驗證](/huan/guide/two-factor)。

## 2. 上傳素材

到「素材庫」，把影片或圖片拖進上傳區。

<figure class="huan-figure">
	<img src="/huan/screenshots/media.png" alt="素材庫" />
	<figcaption>素材庫</figcaption>
</figure>

檔案會依序經過**上傳中 → 處理中 → 可使用**三個狀態。處理階段 HUAN 會自動轉出適合播放的版本、縮圖與預覽圖。

文字與跑馬燈不需要上傳，等一下直接寫在版面裡。

詳見[上傳素材](/huan/guide/media)。

## 3. 設計版面

到「版面」建立一份新版面，選擇畫布尺寸（一般橫式螢幕就選 1920 × 1080）。

<figure class="huan-figure">
	<img src="/huan/screenshots/layout-editor.png" alt="版面編輯器" />
	<figcaption>版面編輯器：左邊素材、中間預覽、右邊屬性</figcaption>
</figure>

HUAN 的版面是**把畫面切開**，不是自由拖放：

1. 選一個區塊，按「水平分割」把它切成左右兩半。
2. 在右側面板把第一塊的占比調成 70。
3. 從左邊的素材面板把影片拖進左半邊。
4. 選右半邊，按「放入文字」，寫上你的標語。

比例是百分比而不是像素，所以同一份版面放到不同解析度的螢幕上，構圖不會跑掉。

滿意之後按**發布**。發布會建立一個固定的版本，現場播的就是它——你之後繼續編輯草稿不會影響已經在播的畫面。

詳見[設計版面](/huan/guide/layouts)。

## 4. 配對裝置

第一次啟動播放器時，螢幕上會顯示一組 `XXXX-XXXX` 配對碼與 QR Code。

<figure class="huan-figure">
	<img src="/huan/screenshots/device-pairing.png" alt="裝置上的配對畫面" />
	<figcaption>播放器啟動後顯示的配對畫面</figcaption>
</figure>

用已經登入的瀏覽器掃描 QR Code，或到後台的「裝置 → 配對新裝置」輸入這組配對碼。確認是眼前這一台之後按下綁定，順便幫它取個名字並指定要播的預設版面。

配對碼 10 分鐘後失效，而且只能用一次。

詳見[配對裝置](/huan/guide/pairing)。

## 5. 看它動起來

綁定完成後，裝置會自己完成剩下的事：

```text
取得該播什麼
  ↓
下載需要的影片與圖片
  ↓
逐一驗證檔案完整
  ↓
全部就緒才切換畫面
```

在後台的「裝置」頁可以看到同步進度。目標版本與實際版本一致時，就代表現場已經在播你剛才做的畫面了。

<figure class="huan-figure">
	<img src="/huan/screenshots/devices.png" alt="裝置管理" />
	<figcaption>裝置管理</figcaption>
</figure>

## 6.（選用）安排播放時段

想讓不同時段播不同畫面的話，到「排程」建立規則：

```text
星期一至五 08:00–11:00  早餐版面
星期一至五 11:00–14:00  午餐版面
```

沒有任何排程命中的時間，裝置就播它的預設版面。

排程會下載到裝置本機，所以**就算伺服器離線，現場一樣會照時間換畫面**。

詳見[安排播放時段](/huan/guide/schedules)。

## 網路斷了會怎樣

畫面照播。

HUAN 的素材永遠是先下載到裝置上才播放，排程也存在裝置裡。網路只負責告訴裝置「內容換了」——這件事延遲幾小時甚至幾天，都不影響現在正在播的畫面。

詳見[離線播放](/huan/guide/offline)。

## 接下來

- [核心概念](/huan/guide/concepts)：版面、修訂、排程與裝置之間的關係
- [管理裝置](/huan/guide/devices)：改名、強制同步、重新啟動、解除綁定
- [使用者與權限](/huan/guide/users)：誰可以做什麼
- [疑難排解](/huan/guide/troubleshooting)：東西不對勁的時候

---

# 核心概念

理解這六個概念就理解了 HUAN。

理解這六個概念就理解了 HUAN。

## 素材（Media Asset）

一個上傳的檔案：影片、圖片或 HTML。文字與網址不需要上傳，它們直接寫在版面設定裡。

每個素材會產生數種產物：

| 產物        | 用途               | 保留                      |
| ----------- | ------------------ | ------------------------- |
| `original`  | 使用者上傳的原始檔 | 轉檔成功後刪除            |
| `thumbnail` | 素材庫縮圖         | 長期                      |
| `preview`   | 後台排版預覽       | 長期                      |
| `playback`  | 派送到裝置播放     | 全部 ACK 且過保留期後回收 |

詳見[素材生命週期](/huan/dev/asset-lifecycle)。

## 版面（Layout）

一份畫面的設計。包含畫布尺寸、背景、間距，以及一棵遞迴分割樹。

任何區塊都可以被水平或垂直切成兩塊，每一塊可以放文字、跑馬燈、圖片、影片、網址或上傳的 HTML。

分割用的是**比例**而不是像素，因此同一份版面在不同解析度上維持相同的構圖。詳見[版面與縮放](/huan/dev/layout-engine)。

## 修訂（Revision）

發布版面時建立的**不可變快照**。

草稿與已發布版本完全分離：你可以放心編輯草稿，現場播的還是上一次發布的內容。

裝置的目標狀態指向的是修訂 id，因此可以明確知道某台裝置在某個時刻播的是哪一版。

## 排程（Schedule）

「在哪些日子的哪個時段，哪些裝置播哪個版面」。

排程綁定 IANA 時區，正確處理日光節約時間。多筆排程同時生效時依明確定義的順序決勝：優先度 → 視窗較短 → 天數較少 → 有日期區間 → 較新 → id。

排程清單會下載到裝置本機，因此 **Server 離線時裝置仍會照時間切換版面**。詳見[排程與時區](/huan/dev/scheduling)。

## 裝置（Device）

一台已配對的播放器。

配對流程：裝置顯示 `XXXX-XXXX` 配對碼與 QR Code，已登入的管理員掃碼或輸入配對碼後確認綁定。裝置取得一組**專屬的憑證**，不同裝置不共用秘密。

裝置綁定後**不能在本機修改內容**。本機只提供裝置資訊、連線狀態與解除綁定。

## 目標狀態與回報狀態

Server 宣告「這台裝置應該是修訂 42」；裝置回報「我現在是 41」，然後自己下載、驗證、啟用，最後回報 42。

```text
Server:  desiredVersion = 42
Device:  reportedVersion = 41
            ↓ 下載
            ↓ 驗證 SHA-256
            ↓ 全部就緒才原子性切換
Device:  reportedVersion = 42
```

任何一個檔案失敗，裝置就留在 41 繼續播舊內容，稍後重試。**絕不會為了下載新版本而先刪掉舊版本。**

詳見 [Desired / Reported State](/huan/dev/desired-reported-state)。

---

# 上傳素材

/app/media 是素材庫。

`/app/media` 是素材庫。

<figure class="huan-figure">
	<img src="/huan/screenshots/media.png" alt="素材庫畫面" />
	<figcaption>素材庫</figcaption>
</figure>

## 可以上傳什麼

| 類型 | 格式                           |
| ---- | ------------------------------ |
| 影片 | MP4、MOV、MKV、WebM、MPEG、AVI |
| 圖片 | JPEG、PNG、WebP、AVIF、GIF     |
| HTML | 單一自帶資源的 `.html`         |

**文字與網址不需要上傳。** 它們直接寫在版面設定裡，不佔用素材庫。

## 上傳流程

```mermaid
sequenceDiagram
	participant B as 瀏覽器
	participant S as Server
	participant R as RustFS
	participant W as Worker

	B->>S: 要求上傳授權
	S-->>B: 簽章網址
	B->>R: 直接上傳檔案
	B->>S: 通知上傳完成
	S->>W: 建立轉檔工作
	W->>W: ffprobe、轉檔、縮圖
	W->>S: 標記為就緒
```

檔案**不經過 Server 的記憶體**，瀏覽器直接傳到物件儲存。一支 4 GB 的影片如果經過 Node.js，幾個人同時上傳就會把 Server 打掛。

## 狀態

| 狀態             | 意義                            |
| ---------------- | ------------------------------- |
| **上傳中**       | 檔案正在傳到物件儲存            |
| **處理中**       | Worker 正在轉檔、產生縮圖與預覽 |
| **就緒**         | 可以放進版面                    |
| **失敗**         | 轉檔失敗，畫面上會有原因        |
| **需要重新上傳** | 已經沒有可派送的副本            |

## 影片會被怎麼處理

Worker 會產生三種版本：

| 版本 | 用途                     |
| ---- | ------------------------ |
| 縮圖 | 素材庫的預覽圖           |
| 預覽 | 後台排版時的低解析度播放 |
| 播放 | 實際派送到裝置的版本     |

播放版本的規格：MP4 容器、H.264、`yuv420p`、最高 1920×1080、最高 30fps、AAC 音訊、啟用 fast start。

**不做放大。** 640×360 的來源轉出來還是 640×360。長寬比一律保持原樣。

`yuv420p` 是刻意指定的：某些來源使用 `yuv444p` 或 10-bit 格式，Raspberry Pi 的硬體解碼器不支援，會退回軟體解碼而卡頓。

## 圖片會被怎麼處理

同樣產生三種版本。播放版本限制在合理尺寸——不能讓 Raspberry Pi 每次算繪都去解一張 12000×9000 的原圖。

來源含有透明資訊時會保留，不會被壓成黑底。

## HTML

第一版只支援**單一自帶資源**的 HTML 檔案。需要圖片時請用 `data:` URI 內嵌。

HTML 在裝置上以 sandbox iframe 執行，**沒有** Node、檔案系統或 Electron API 的存取權。

## 「需要重新上傳」是什麼意思

:::warning[這是產品的真實限制，不是故障]

HUAN 不永久保存原始檔，播放產物也會在所有裝置下載完成並經過保留期後回收。

:::

當下列情況同時成立時，這份素材就無法再派送：

- 原始檔已在轉檔後刪除
- 播放產物已在所有裝置 ACK 後回收
- 而你現在需要重新派送（新增了裝置、或某台裝置清掉了本機儲存）

後台會直接把它標示為「需要重新上傳」。**系統不會假裝檔案還在，然後在派送時才失敗。**

解法是重新上傳這個檔案。想降低發生機率的話，把 `DISTRIBUTION_RETENTION_HOURS` 調長（`720` 表示 30 天）。

完整理由見 [ADR-0003](/huan/dev/adr/0003-temporary-object-storage)。

## 刪除

刪除之前，HUAN 會檢查這份素材有沒有被使用：

- 草稿中的版面
- 已發布的版面修訂
- 排程
- 裝置目前的狀態

有任何一項使用中，刪除會被擋下來，並列出是哪些版面或排程在用它。請先解除引用再刪除。

**不會有無提示的刪除。**

## 轉檔失敗怎麼看

畫面上顯示的是給使用者看的說明，例如「影片轉檔失敗，來源檔案可能損毀或格式不支援」。

完整的 FFmpeg 指令、stderr 與檔案系統路徑只留在伺服器日誌裡。那些資訊對一般使用者沒有幫助，而且會洩漏伺服器的內部結構。

---

# 設計版面

/app/layouts 是版面列表，/app/layouts/:id 是編輯器。

`/app/layouts` 是版面列表，`/app/layouts/:id` 是編輯器。

<figure class="huan-figure">
	<img src="/huan/screenshots/layout-editor.png" alt="版面編輯器" />
	<figcaption>版面編輯器：左側素材、中間預覽、右側屬性</figcaption>
</figure>

## 建立版面

先決定畫布尺寸：

| 預設        | 用途             |
| ----------- | ---------------- |
| 1920 × 1080 | 一般橫式螢幕     |
| 1080 × 1920 | 直式螢幕         |
| 3840 × 2160 | 4K               |
| 1280 × 720  | 較低解析度的裝置 |

也可以自訂，或選擇**使用裝置解析度**，直接從已配對裝置回報的顯示器資訊帶入。

## 遞迴分割

版面不是自由拖曳的畫布，而是一棵分割樹。任何區塊都可以被切成兩塊：

```text
根區塊（水平分割 70/30）
├─ 左 70%  → 影片
└─ 右 30%（垂直分割 50/50）
   ├─ 上 → 標題文字
   └─ 下 → 跑馬燈
```

- **水平分割**：兩塊左右並排。
- **垂直分割**：兩塊上下堆疊。

分割用的是**比例**而不是像素。因此同一份版面在 1080p 與 4K 上維持相同的構圖。

比例有 5% 到 95% 的限制——沒有這個限制，一不小心就會拖出再也點不回來的版面。

理由見 [ADR-0004](/huan/dev/adr/0004-recursive-split-layout)。

## 操作

| 操作           | 方式                                 |
| -------------- | ------------------------------------ |
| 選取區塊       | 點擊，或用 Tab 鍵移動焦點            |
| 水平／垂直分割 | 工具列按鈕或快捷鍵                   |
| 調整比例       | 拖曳分隔線，或在右側面板輸入數值     |
| 刪除分割       | 選取後按刪除，兄弟區塊會頂上來       |
| 放入內容       | 從左側素材面板拖入，或在右側面板選擇 |
| 交換內容       | 把一個區塊拖到另一個區塊上           |

:::tip[拖曳不是唯一的方式]

每一個拖曳操作都有鍵盤或表單的替代方式。比例可以用方向鍵微調，也可以直接輸入數字。

:::

## 區塊內容

| 類型       | 設定                                                   |
| ---------- | ------------------------------------------------------ |
| **文字**   | 內容、背景色、文字色、字級、字重、水平與垂直對齊、內距 |
| **跑馬燈** | 同文字，另加方向、速度與重複間距                       |
| **圖片**   | 素材、填滿方式（contain／cover／fill）、背景色         |
| **影片**   | 素材、填滿方式、循環、靜音、音量、背景色               |
| **網址**   | https 網址，以 iframe 顯示                             |
| **HTML**   | 上傳的 HTML 素材，以 sandbox iframe 顯示               |

字型固定使用 sans-serif，HUAN 不提供字型上傳。

填滿方式的預設是 `contain`，也就是不變形。

### 關於 iframe

:::warning[很多網站不能被嵌入]

外部網站可以用 `X-Frame-Options` 或 `Content-Security-Policy: frame-ancestors` 明確禁止被嵌入。遇到這種網站，區塊會顯示空白。

這是對方網站的安全設定，**HUAN 不會也不應該繞過它**。改用可嵌入的來源，或把內容做成上傳的 HTML。

:::

## 全域設定

- **背景色**：畫布本身的底色，也是螢幕長寬比與畫布不同時留白區域的顏色。
- **背景圖片**：可選。
- **間距**：區塊之間的距離，單位是設計畫布的 px，會跟著畫布等比縮放。

間距是從可用空間扣掉的，所以不論分幾層，所有區塊的外緣永遠貼齊畫布邊界。

## 草稿與發布

編輯器改的是**草稿**，會自動儲存。現場播的還是上一次發布的內容，所以可以放心編輯。

按下發布會建立一筆**不可變的修訂**：

```text
版面 3
├─ 修訂 12（2026-08-01）
├─ 修訂 13（2026-08-14）
└─ 修訂 14（2026-09-02）← 目前
```

裝置的目標狀態指向修訂 id，因此可以明確知道某台裝置播的是哪一版，也可以在需要時回溯。

發布前會檢查所有引用到的素材都已經就緒。有素材還在處理中或需要重新上傳時，發布會被擋下並列出是哪幾個。

## 預覽和實機一模一樣

編輯器的預覽和裝置播放器用的是**同一套版面引擎**（`@huan/layout-engine`）。

這不是為了少寫程式碼，而是為了保證兩邊一致。如果後台自己算一套、裝置再算一套，遲早會出現「後台是 70/30，實機變成 68/32」這種沒人查得出來的偏差。

幾何計算有針對 1920×1080、1280×720、3840×2160 與 1080×1920 的單元測試，斷言的是實際數值。

## 螢幕長寬比不一樣時

裝置的螢幕和設計畫布長寬比不同時，HUAN 會把整份畫布**等比縮放並置中**，剩下的區域填入版面背景色。

**不做拉伸。** 變形的看板比黑邊難看得多，而且客戶不會知道問題出在哪裡。

---

# 安排播放時段

/app/schedules 決定「在哪些日子的哪個時段，哪些裝置播哪個版面」。

`/app/schedules` 決定「在哪些日子的哪個時段，哪些裝置播哪個版面」。

<figure class="huan-figure">
	<img src="/huan/screenshots/schedules.png" alt="排程管理畫面" />
	<figcaption>排程管理</figcaption>
</figure>

## 一筆排程包含什麼

| 欄位           | 說明                                       |
| -------------- | ------------------------------------------ |
| 名稱           | 給人看的識別                               |
| 版面           | 要播的版面。實際派送的是它目前已發布的修訂 |
| 時區           | IANA 時區，例如 `Asia/Taipei`              |
| 優先度         | 數字愈大愈優先                             |
| 日期區間       | 可留空表示不限                             |
| 星期           | 星期幾生效                                 |
| 開始／結束時間 | `HH:MM`                                    |
| 目標裝置       | 這筆排程套用在哪些裝置上                   |

典型用法：

```text
星期一至五 08:00–11:00  早餐版面
星期一至五 11:00–14:00  午餐版面
星期一至五 14:00–17:00  下午茶版面
```

沒有任何排程命中的時段，裝置播它的**預設版面**（在裝置設定裡指定）。

## 時區

排程存的是 IANA 時區名稱，不是 UTC 偏移。

這很重要：UTC 偏移會隨日光節約時間改變，時區不會。一個設在 `America/New_York` 早上八點的排程，在三月和十一月對應到不同的 UTC 時刻。只存「UTC 13:00」的話，換季的那個週末看板就會在錯的時間換畫面。

判定完全用當地牆上時間進行，日光節約時間、半小時偏移、南半球的反向切換全都自動正確。

## 跨午夜

結束時間早於或等於開始時間就代表跨午夜。視窗**錨定在開始的那一天**：

```text
星期一 22:00–02:00
= 星期一晚上十點 → 星期二凌晨兩點
```

星期二凌晨一點會命中（屬於星期一開始的視窗），星期三凌晨一點不會。

## 衝突怎麼決勝

兩筆排程同時生效時，依序比較：

1. **優先度**較大的勝出
2. **每日視窗較短**的勝出
3. **指定天數較少**的勝出
4. **有日期區間**的勝過沒有的
5. **最後修改時間較新**的勝出
6. 以 **id** 作為最後的決勝

最後一條的存在是為了讓結果**永遠是決定性的**。兩筆條件完全相同的排程不會隨機挑一筆。

實務上的用法：

```text
優先度 100  星期一至五 08:00–18:00  一般營業版面
優先度 500  星期一至五 12:00–12:30  午間限時活動  ← 勝出
```

## 離線也會照時間切換

排程清單本身會下載到裝置本機。判定完全在裝置上進行。

**Server 離線時，裝置依然會照時間切換版面。**

裝置不會在每個時間點去問 Server「現在要播什麼」——那種設計在網路正常時很優雅，網路一斷就整個停擺，而數位看板最常出問題的地方就是網路。

## 停用

排程可以停用而不刪除。停用的排程不會參與判定，但設定都留著，隨時可以再打開。

---

# 管理裝置

/app/devices 是裝置列表，/app/devices/:id 是單一裝置的詳情。

`/app/devices` 是裝置列表，`/app/devices/:id` 是單一裝置的詳情。

<figure class="huan-figure">
	<img src="/huan/screenshots/devices.png" alt="裝置管理畫面" />
	<figcaption>裝置管理</figcaption>
</figure>

## 看得到什麼

| 欄位                | 說明                             |
| ------------------- | -------------------------------- |
| 名稱                | 可以隨時改                       |
| 線上／離線          | 依 heartbeat 判定                |
| 平台與架構          | linux／win32／darwin，x64／arm64 |
| 螢幕解析度          | 裝置回報的顯示器資訊             |
| App 版本            | 播放器的版本                     |
| 最後上線            | 最後一次 heartbeat 的時間        |
| 目前版面            | 現在正在播的版面修訂             |
| 目標版本 / 回報版本 | 兩者相同代表已同步               |
| 磁碟空間            | 剩餘與總容量                     |
| 最後同步            | 最後一次成功套用目標狀態的時間   |

Raspberry Pi 上還會回報 CPU 溫度。Windows 與 macOS 讀不到就顯示「—」，**不會編一個數字出來**。

## 目標版本與回報版本

這兩個數字是理解裝置狀態的關鍵。

```text
目標 42 / 回報 42  → 已同步
目標 42 / 回報 41  → 正在下載新版本，目前仍播 41
```

裝置落後不一定是問題——大檔案下載本來就要時間。持續落後才需要看一下詳情頁的素材同步狀態。

常見原因：

- **磁碟空間不足**：裝置會回報儲存錯誤，後台會顯示出來
- **某個素材下載失敗**：裝置會留在舊版本並重試，這是**正確**行為
- **素材已被回收**：如果素材標示為需要重新上傳，裝置永遠拿不到它

## 可以做什麼

| 操作           | 說明                       |
| -------------- | -------------------------- |
| 重新命名       | 只改顯示名稱，不影響配對   |
| 設定預設版面   | 沒有排程命中時播的版面     |
| 強制同步       | 讓裝置立刻重新取得目標狀態 |
| 重新啟動播放器 | 遠端重啟算繪行程           |
| 解除綁定       | 撤銷憑證，裝置回到配對畫面 |

所有具破壞性的操作都需要二次確認。

## 解除綁定

解除綁定會：

1. 撤銷這台裝置的憑證
2. 清除帳戶綁定
3. 讓裝置回到配對畫面

被撤銷的憑證立即失效。**不會留下任何舊帳戶仍可遠端控制的憑證。**

裝置端也可以自己解除綁定，見 [Device 解除綁定](/huan/guide/unbind)。

## 配對

裝置第一次啟動會顯示 `XXXX-XXXX` 配對碼與 QR Code。

<figure class="huan-figure">
	<img src="/huan/screenshots/pairing.png" alt="裝置配對確認畫面" />
	<figcaption>後台的配對確認畫面</figcaption>
</figure>

用已登入的後台掃描 QR Code，或到 `/pair` 手動輸入配對碼。確認裝置資訊後綁定，可以順便命名並指定預設版面。

配對碼是隨機產生、10 分鐘過期、只能使用一次。字母表排除了 0/O/1/I，因為這串字要被人從螢幕上抄下來。

詳見 [Device 配對](/huan/guide/pairing)。

## 稽核

裝置的配對、解除綁定、重新命名、強制同步與重新啟動都會留下稽核紀錄。

---

# 配對裝置

裝置第一次啟動時還不屬於任何帳戶。配對就是把它綁定到你的 HUAN 的過程。

裝置第一次啟動時還不屬於任何帳戶。配對就是把它綁定到你的 HUAN 的過程。

## 裝置端

啟動後畫面顯示：

```text
HUAN
讙

7K4M-9PXA
```

以及一個 QR Code。

<figure class="huan-figure">
	<img src="/huan/screenshots/device-pairing.png" alt="裝置配對畫面" />
	<figcaption>裝置端的配對畫面</figcaption>
</figure>

## 後台端

用已登入的瀏覽器掃描 QR Code，或直接到 `/pair` 手動輸入配對碼。

確認畫面會顯示這台裝置回報的名稱、平台、架構與 App 版本，讓你確定綁的是眼前這一台。可以順便重新命名並指定預設版面。

按下綁定之後，裝置畫面會顯示「已綁定」並進入播放器。

## 流程

```mermaid
sequenceDiagram
	participant D as 裝置
	participant S as Server
	participant A as 管理員

	D->>S: 要求配對碼
	S-->>D: 7K4M-9PXA + 配對 token
	D->>D: 顯示配對碼與 QR Code
	loop 每隔幾秒
		D->>S: 用配對 token 查詢狀態
		S-->>D: 尚未配對
	end
	A->>S: 掃碼或輸入配對碼
	S-->>A: 裝置資訊
	A->>S: 確認綁定
	S->>S: 建立裝置與憑證
	D->>S: 查詢狀態
	S-->>D: 已配對 + 一次性憑證
	D->>D: 安全保存憑證，進入播放器
```

## 配對碼

- 8 個字元，顯示成 `XXXX-XXXX`
- 密碼學隨機產生，不可預測
- 10 分鐘過期
- 只能使用一次
- 字母表排除 0、O、1、I

排除易混淆字元是因為這串字要被人從牆上的螢幕抄到手機或電腦裡。

## 為什麼有兩個秘密

配對碼給人看，配對 token 給裝置用。

裝置在要求配對碼的同時會拿到一個配對 token，只有持有這個 token 的裝置能領取配對結果。

這表示**即使有人猜到或看到配對碼，也搶不走那組憑證**——他可以完成綁定，但憑證只會交給發起配對的那一台裝置。

## 裝置憑證

配對完成後，裝置取得一組**專屬的憑證**。

- 每台裝置各自獨立，不共用秘密。撤銷一台不影響其他台。
- Server 只保存憑證的 SHA-256，**憑證原值只在配對當下回傳一次**。
- 憑證在裝置上使用作業系統提供的加密能力保存（Electron 的 `safeStorage`），不以明文寫在設定檔裡。
- 憑證不會出現在任何日誌或稽核紀錄中。

## 配對碼過期了

重新啟動裝置就會產生新的一組。

## 已綁定的裝置能做什麼

**不能在裝置本機修改版面、素材或排程。** 內容一律由後台控制。

本機只提供：

- 裝置基本資訊
- 網路與連線狀態
- 配對狀態
- 解除綁定

透過系統匣、選單或鍵盤快捷鍵開啟，不影響正常播放。

---

# 離線播放

這是 HUAN 最重要的一項行為。

這是 HUAN 最重要的一項行為。

## 保證

**網路斷線時，HUAN 繼續播放目前的內容。**

不會有這種事：

```text
網路斷線
	↓
黑畫面
```

一面看板的價值就是它一直亮著。客戶不會知道是網路的問題，他們只會看到自己花錢買的螢幕變成一塊黑板。

## 為什麼做得到

素材永遠**先下載到裝置本機**才播放。正常播放時裝置完全不需要網路——它讀的是自己硬碟上的檔案。

排程清單也存在本機，因此時段切換也不需要 Server。

網路只負責一件事：告訴裝置「內容變了」。這件事延遲幾分鐘、幾小時，甚至幾天，都不影響現在正在播的畫面。

理由見 [ADR-0005](/huan/dev/adr/0005-local-first-playback)。

## 更新怎麼進行

```mermaid
flowchart TD
	A["目前播放版本 A"] --> B["收到通知：有版本 B"]
	B --> C["背景下載版本 B 需要的全部素材"]
	C --> D{"每個檔案<br/>SHA-256 都正確？"}
	D -->|否| E["刪除暫存檔並重試"]
	E --> C
	D -->|是| F["全部就緒"]
	F --> G["原子性切換到版本 B"]
	C -->|任一檔案最終失敗| H["維持播放版本 A"]
	H --> I["稍後重試"]
	I --> C
```

關鍵在於：**版本 A 全程都在播。**

- 下載期間播 A
- 驗證期間播 A
- 任何一個檔案失敗，就繼續播 A
- 只有全部就緒才切到 B

**絕對不會先刪除版本 A 的檔案再下載版本 B。** 舊版本的素材要等新版本成功啟用並經過保留期之後才會被回收。

## 校驗

每個檔案都用 SHA-256 驗證：

```text
下載到 .part 暫存檔（邊寫邊算雜湊）
	↓
比對 manifest 裡的值
	↓
符合 → rename 成正式檔名 → 回報 ACK
不符 → 刪除暫存檔 → 重試
```

雜湊不符時**絕不回報 ACK**。回報一個其實沒下載成功的檔案，會讓 Server 以為可以回收派送產物——那才是真正無法挽回的錯誤。

## 重新連線

WebSocket 斷線後以指數退避加抖動重連：

```text
1s → 2s → 4s → 8s → 16s → 30s → 60s（上限）
```

每次等待時間都加上隨機抖動。整個賣場的看板同時斷線時，沒有抖動就會在同一秒一起重連，把剛恢復的 Server 再打掛一次。

即使 WebSocket 正常，裝置仍然每 5 分鐘做一次完整狀態同步，不完全依賴推播。

## 斷電之後

所有本機狀態的寫入都是原子的：先寫暫存檔、`fsync`、再 `rename`。

看板通常裝在牆上，沒有 UPS，斷電是常態而不是意外。半寫入的 manifest 會讓裝置開機後不知道自己該播什麼——原子寫入讓這件事不可能發生。

重新開機後：

```text
載入最後一份已知良好的狀態
	↓
繼續播放
	↓
在背景重新連線 Server
```

**開機不需要 Server 在線。**

## 儲存空間

裝置有本機快取上限。空間不足時：

1. 先回收未被引用的舊素材
2. 仍然不足就向 Server 回報儲存錯誤，後台會顯示

回收**永遠不會刪除**：

- 目前啟用版本的素材
- 下一個排程版本需要的素材
- 正在下載中的檔案

## 下載節流

裝置同時最多下載 2 到 3 個檔案，不會一次抓五十支影片把現場網路塞死。

已經存在且雜湊正確的檔案會直接跳過，重新開機不會重下載一輪。伺服器支援 `Range` 時可以續傳。

簽章網址過期時裝置會重新索取，**不會讓整次同步失敗**。

---

# 解除綁定

解除綁定會切斷裝置與帳戶的關係，讓它回到配對畫面。

解除綁定會切斷裝置與帳戶的關係，讓它回到配對畫面。

## 兩種方式

**從後台**：`/app/devices/:id` → 解除綁定。需要二次確認。

**從裝置本機**：開啟裝置資訊面板 → 解除綁定。同樣需要二次確認。

兩種方式的結果相同。

## 會發生什麼

```text
撤銷裝置憑證
	↓
清除帳戶綁定與目標狀態
	↓
回到配對畫面
```

被撤銷的憑證**立即失效**。裝置下一次請求就會被拒絕。

:::tip[憑證立即失效]

解除綁定之後，不會留下任何舊帳戶仍可遠端控制這台裝置的憑證。

:::

## 離線時解除綁定

在裝置本機解除綁定時，如果剛好連不上 Server：

1. **本機立即停止接受帳戶控制。** 不等 Server 確認。
2. 本機保留一個「待撤銷」狀態。
3. 下次連上線時完成 Server 端的撤銷。

待撤銷狀態**不會因為收到過期的伺服器回應而被還原**。已經解除的綁定不會自己恢復。

這一點很重要：使用者按下解除綁定的當下就期待它生效了。如果因為網路不通而讓裝置繼續接受遠端控制，那個按鈕就是騙人的。

## 重新配對

解除綁定後裝置回到配對畫面，顯示一組**新的**配對碼。

舊的憑證已經失效，重新綁定會產生全新的裝置紀錄。

## 本機素材

解除綁定後，裝置本機的素材檔案會在下一次垃圾回收時清除。

需要立刻清空的話，重新安裝應用程式或直接刪除資料目錄。

## 稽核

不論從哪一端發起，解除綁定都會留下稽核紀錄，包含操作者、裝置與時間。

---

# 在 Raspberry Pi 上安裝

Raspberry Pi 是 HUAN 的主要目標裝置，但產品沒有綁死在它上面。同一份程式碼也跑在 Ubuntu、Windows 與 macOS 上。

Raspberry Pi 是 HUAN 的主要目標裝置，但**產品沒有綁死在它上面**。同一份程式碼也跑在 Ubuntu、Windows 與 macOS 上。

## 建議規格

| 項目     | 需求                                    |
| -------- | --------------------------------------- |
| 機型     | Raspberry Pi 4 以上                     |
| 作業系統 | Raspberry Pi OS 64-bit（Bookworm 以上） |
| 記憶體   | 最低 2GB，**建議 4GB**                  |
| 儲存     | 32GB 以上的 A2 等級 microSD，或 USB SSD |
| 網路     | 有線網路優先                            |

:::tip[用 SSD 而不是 SD 卡]

microSD 卡在持續寫入下的壽命有限，而 HUAN 會在同步時寫入不少資料。長期部署建議從 USB SSD 開機。

:::

## 安裝

從 [Releases](https://github.com/linyao-tw/huan/releases) 下載 **linux-arm64** 的版本。

AppImage：

```sh
chmod +x HUAN-Device-*-linux-arm64.AppImage
./HUAN-Device-*-linux-arm64.AppImage
```

Debian 套件：

```sh
sudo apt install ./HUAN-Device-*-linux-arm64.deb
huan-device
```

## 開機自動啟動

Raspberry Pi OS 使用 systemd，但 **HUAN 不假設系統上一定有 systemd**——它只是最常見的情況。

```ini
# ~/.config/systemd/user/huan-device.service
[Unit]
Description=HUAN Device Player
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/huan-device
Restart=always
RestartSec=10

[Install]
WantedBy=graphical-session.target
```

```sh
systemctl --user enable --now huan-device
loginctl enable-linger "$USER"   # 讓服務在沒有登入時也能執行
```

## 螢幕設定

### 關閉螢幕保護與休眠

```sh
sudo apt install xscreensaver
xset s off
xset -dpms
xset s noblank
```

或在 `~/.config/wayfire.ini` 加上：

```ini
[idle]
dpms_timeout = -1
screensaver_timeout = -1
```

### 直式螢幕

```sh
# Wayland（Raspberry Pi OS Bookworm 預設）
wlr-randr --output HDMI-A-1 --transform 90
```

版面的畫布尺寸要跟著改成 1080×1920。裝置回報的顯示器資訊會反映實際的方向，建立版面時可以直接選「使用裝置解析度」。

## 影片播放

Worker 產生的播放檔已經針對 Raspberry Pi 最佳化：

- H.264（不是 H.265）
- `yuv420p` 像素格式
- 最高 1920×1080
- 最高 30fps

`yuv420p` 是刻意指定的：某些來源使用 `yuv444p` 或 10-bit 格式，Pi 的硬體解碼器不支援，會退回軟體解碼而卡頓。

### 增加 GPU 記憶體

`/boot/firmware/config.txt`：

```ini
gpu_mem=256
```

## 溫度

Raspberry Pi 上讀得到 CPU 溫度，會在 heartbeat 中回報，後台可以看到。

Windows 與 macOS 上讀不到，回報 `null`，後台顯示「—」。**不會為了統一型別而編一個數字。**

裝置超過 80°C 會開始降頻，畫面可能變卡。裝在密閉機殼裡的 Pi 建議加散熱片或風扇。

## 沒有的假設

HUAN **不會假設**系統上一定存在：

- `apt`
- `vcgencmd`
- `systemd`

這些平台差異都封裝在 `PlatformAdapter` 介面裡。讀不到的資訊回報 `null`，不會讓播放器崩潰。

## 疑難排解

**畫面全黑但程式在跑**：檢查 HDMI 是不是被偵測成未連接。Pi 在開機時沒接螢幕會停用輸出。

**影片卡頓**：確認素材真的是 H.264 / `yuv420p`（後台的素材詳情看得到），並增加 GPU 記憶體。

**同步很慢**：Wi-Fi 在多數場地都不穩定，有線網路差很多。

**磁碟空間不足**：後台會顯示裝置回報的儲存錯誤。清掉不需要的排程與版面可以讓裝置回收對應的素材。

---

# 在 Ubuntu 上安裝

支援 x64 與 arm64。

支援 x64 與 arm64。

## 需求

| 項目     | 需求                  |
| -------- | --------------------- |
| 版本     | Ubuntu 22.04 LTS 以上 |
| 架構     | x64 或 arm64          |
| 記憶體   | 最低 2GB，建議 4GB    |
| 桌面環境 | 需要 X11 或 Wayland   |

## 安裝

從 [Releases](https://github.com/linyao-tw/huan/releases) 下載對應架構的版本。

AppImage：

```sh
chmod +x HUAN-Device-*-linux-x64.AppImage
./HUAN-Device-*-linux-x64.AppImage
```

Debian 套件：

```sh
sudo apt install ./HUAN-Device-*-linux-x64.deb
huan-device
```

## 開機自動啟動

```ini
# ~/.config/systemd/user/huan-device.service
[Unit]
Description=HUAN Device Player
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/huan-device
Restart=always
RestartSec=10

[Install]
WantedBy=graphical-session.target
```

```sh
systemctl --user enable --now huan-device
loginctl enable-linger "$USER"
```

也可以用桌面環境自己的自動啟動機制，放一個 `.desktop` 檔到 `~/.config/autostart/`。

## 關閉螢幕休眠

GNOME：

```sh
gsettings set org.gnome.desktop.session idle-delay 0
gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type nothing
```

X11 通用：

```sh
xset s off -dpms
```

## 無桌面環境的伺服器版

Electron 需要一個顯示伺服器。最小安裝：

```sh
sudo apt install --no-install-recommends xserver-xorg xinit openbox
```

然後用 `~/.xinitrc` 啟動：

```sh
#!/bin/sh
exec openbox-session &
exec huan-device
```

## 憑證儲存

裝置憑證使用 Electron 的 `safeStorage`，在 Linux 上會透過 `libsecret` 存進系統的金鑰環（GNOME Keyring 或 KWallet）。

沒有可用的金鑰環服務時，`safeStorage` 會退回較弱的保護。無人值守的看板機器建議確認金鑰環在開機時會自動解鎖，或接受這個限制——裝置憑證的權限範圍僅限這一台裝置，而且隨時可以從後台撤銷。

## 疑難排解

**AppImage 無法執行**：需要 FUSE。

```sh
sudo apt install libfuse2
```

**沙箱錯誤**：某些容器或受限環境需要調整 user namespace 設定。**不要用 `--no-sandbox` 繞過**——那會關掉 Electron 的核心安全機制。

---

# 在 Windows 上安裝

支援 x64 與 arm64。

支援 x64 與 arm64。

## 需求

| 項目   | 需求                             |
| ------ | -------------------------------- |
| 版本   | Windows 10 1809 以上、Windows 11 |
| 架構   | x64 或 arm64                     |
| 記憶體 | 最低 4GB                         |

## 安裝

從 [Releases](https://github.com/linyao-tw/huan/releases) 下載對應架構的安裝檔並執行。

:::tip[未簽章的安裝檔]

安裝檔目前沒有經過程式碼簽章，Windows SmartScreen 會出現警告。選擇「其他資訊」→「仍要執行」。

要消除這個警告需要 EV 程式碼簽章憑證，可以在 CI 的 secrets 裡設定後啟用。

:::

## 開機自動啟動

**工作排程器**（建議）：

1. 開啟工作排程器 → 建立工作
2. 觸發程序：登入時
3. 動作：啟動程式 → HUAN Device 的執行檔路徑
4. 設定 → 勾選「如果工作失敗，每隔一分鐘重新啟動」

**啟動資料夾**（較簡單）：

按 `Win + R`，輸入 `shell:startup`，把 HUAN Device 的捷徑放進去。

## 關閉螢幕休眠

```powershell
powercfg /change monitor-timeout-ac 0
powercfg /change standby-timeout-ac 0
```

## Kiosk 模式

Windows 的指派存取（Assigned Access）可以把裝置鎖在單一應用程式上：

**設定** → **帳戶** → **其他使用者** → **設定 Kiosk**

## 溫度

Windows 上無法透過一般 API 取得 CPU 溫度，裝置回報 `null`，後台顯示「—」。

這是刻意的：**不會為了讓所有平台的欄位都有值而編一個數字出來。**

## 憑證儲存

裝置憑證使用 Electron 的 `safeStorage`，在 Windows 上由 DPAPI 加密，綁定到目前的使用者帳戶。

## ARM64

Windows on ARM 的支援取決於 Electron 對該版本的支援狀況。打包 workflow 會嘗試建置 arm64 版本；建置失敗時 x64 版本可以透過模擬執行，但效能較差。

## 疑難排解

**播放器啟動後閃退**：檢查顯示卡驅動程式。舊的驅動程式可能讓 Chromium 的 GPU 行程崩潰。

**影片播放卡頓**：確認硬體加速已啟用，並更新顯示卡驅動程式。

**連不上 Server**：檢查 Windows 防火牆有沒有擋下對外連線，以及公司網路的 Proxy 設定。

---

# 在 macOS 上安裝

支援 Intel（x64）與 Apple Silicon（arm64）。

支援 Intel（x64）與 Apple Silicon（arm64）。

## 需求

| 項目   | 需求                   |
| ------ | ---------------------- |
| 版本   | macOS 12 Monterey 以上 |
| 架構   | x64 或 arm64           |
| 記憶體 | 最低 4GB               |

## 安裝

從 [Releases](https://github.com/linyao-tw/huan/releases) 下載對應架構的 `.dmg`，拖進「應用程式」。

:::tip[未經公證的應用程式]

目前的版本沒有經過 Apple 公證，第一次開啟時 Gatekeeper 會擋下來。

在 Finder 裡對應用程式按右鍵 → 開啟，然後在對話框中確認。或者：

```sh
xattr -dr com.apple.quarantine /Applications/HUAN\ Device.app
```

要消除這個步驟需要 Apple Developer 帳號與公證流程，可以在 CI 的 secrets 裡設定後啟用。

:::

## 開機自動啟動

**系統設定** → **一般** → **登入項目** → 加入 HUAN Device。

或用 launchd：

```xml
<!-- ~/Library/LaunchAgents/tw.linyao.huan.device.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
		<key>Label</key>
		<string>tw.linyao.huan.device</string>
		<key>ProgramArguments</key>
		<array>
			<string>/Applications/HUAN Device.app/Contents/MacOS/HUAN Device</string>
		</array>
		<key>RunAtLoad</key>
		<true/>
		<key>KeepAlive</key>
		<true/>
	</dict>
</plist>
```

```sh
launchctl load ~/Library/LaunchAgents/tw.linyao.huan.device.plist
```

## 關閉螢幕休眠

```sh
sudo pmset -a displaysleep 0 sleep 0
```

或用 `caffeinate` 包住播放器。

## 溫度

macOS 上沒有不需要特殊權限就能取得 CPU 溫度的公開 API，裝置回報 `null`，後台顯示「—」。

## 憑證儲存

裝置憑證使用 Electron 的 `safeStorage`，在 macOS 上存進系統的鑰匙圈。

## 適合的情境

macOS 主要用於**開發與測試**——它讓開發者不需要準備 Raspberry Pi 就能執行真正的播放器。

正式部署的看板通常會選 Raspberry Pi 或小型 Linux 電腦，成本與功耗都低得多。Mac mini 在需要 4K、色彩準確度或已經有 Apple 生態系統的場合仍然是合理的選擇。

## 疑難排解

**應用程式無法開啟，顯示「已損毀」**：這通常是 quarantine 屬性造成的，用上面的 `xattr` 指令處理。

**全螢幕時仍然看得到選單列**：在系統設定裡把「自動隱藏並顯示選單列」設為「一律」。

---

# 登入

HUAN 沒有公開註冊。帳號一律由最高權限管理員在後台建立，第一個管理員則由 CLI 建立。

HUAN **沒有公開註冊**。帳號一律由最高權限管理員在後台建立，第一個管理員則由 CLI 建立。

<figure class="huan-figure">
	<img src="/huan/screenshots/login.png" alt="HUAN 登入畫面" />
	<figcaption>登入畫面</figcaption>
</figure>

## 登入

在 `/login` 輸入 Email 或帳號，加上密碼。

啟用了兩步驟驗證的帳號會進入第二階段，輸入驗證器產生的六位數驗證碼，或改用復原碼。

## 登入保護

連續失敗會被暫時擋下。節流以**帳號**與**來源 IP** 兩個維度計算，預設是五分鐘內十次失敗。

紀錄寫在資料庫而不是記憶體，因此重啟 Server 不會把計數歸零。

## Session

登入狀態存在 `HttpOnly` cookie 裡。這表示 JavaScript 讀不到它，也就無法透過 XSS 竊取。

正式環境的 cookie 帶有 `Secure`，只會在 HTTPS 下送出。

Session 預設 14 天過期。可以在[安全設定](/huan/guide/two-factor#工作階段)看到所有登入中的裝置並個別撤銷。

## 建立第一個管理員

```sh
pnpm --filter @huan/server admin:create
```

互動式地詢問 Email、帳號、顯示名稱與密碼。密碼至少 12 個字元。

Docker 環境：

```sh
docker compose -f docker/compose.yaml exec \
	-e HUAN_ADMIN_PASSWORD='<一組強密碼>' \
	server node apps/server/dist/cli/create-admin.js \
	--email you@example.com --username admin --display-name 管理員
```

:::danger[原始碼裡沒有預設密碼]

HUAN 不內建任何預設管理員帳號或密碼。第一個帳號一定要用這個指令建立。

:::

## 忘記密碼

第一版沒有自助的密碼重設流程（那需要可靠的郵件寄送，而自架環境往往沒有）。

請最高權限管理員到[使用者管理](/huan/guide/users)重設。所有管理員都無法登入時，用 CLI 再建立一個。

---

# 兩步驟驗證

每位使用者都可以在 /app/security 為自己的帳號啟用 TOTP 兩步驟驗證。

每位使用者都可以在 `/app/security` 為自己的帳號啟用 TOTP 兩步驟驗證。

<figure class="huan-figure">
	<img src="/huan/screenshots/security.png" alt="安全設定畫面" />
	<figcaption>安全設定：兩步驟驗證與工作階段</figcaption>
</figure>

## 啟用

```mermaid
flowchart LR
	A["確認目前密碼"] --> B["產生密鑰"]
	B --> C["顯示 QR Code"]
	C --> D["用驗證器掃描"]
	D --> E["輸入驗證碼確認"]
	E --> F["啟用完成<br/>顯示復原碼"]
```

1. 進入 `/app/security`，按下啟用。
2. **輸入目前的密碼。** 這一步是為了避免有人趁你離開座位時把自己的驗證器綁上去。
3. 用驗證器 App 掃描 QR Code，或手動輸入顯示的密鑰。
4. 輸入驗證器產生的六位數驗證碼確認。
5. 記下畫面顯示的復原碼。

支援任何符合 RFC 6238 的驗證器：Google Authenticator、1Password、Bitwarden、Aegis、Authy 等等。

## 復原碼

啟用時會產生 10 組復原碼。

:::warning[只會顯示一次]

離開這個畫面之後就再也看不到了。Server 只保存雜湊，任何人都無法還原。

:::

請把它們存在密碼管理器或列印下來收好。每一組只能使用一次。

用完或遺失時可以重新產生一批——舊的會全部失效。

## 登入流程

啟用之後：

```text
輸入帳號密碼
	↓
沒有 2FA → 直接登入
	↓
有 2FA → 輸入驗證碼 → 登入
```

第二階段使用的是短時效、一次性的中繼憑證，**不能存取任何 API**，只能用來完成驗證。

## 時鐘誤差

驗證會容忍前後各一個時間步長，也就是大約 ±30 秒的裝置時鐘誤差。

驗證碼一直被拒絕時，先檢查手機的時間是不是設成自動同步。

同一組驗證碼不能用第二次——Server 記錄了上次成功的時間步長。

## 停用

需要同時提供目前的密碼與一組有效的驗證碼。

## 工作階段

安全設定頁面列出所有登入中的工作階段：建立時間、最後活動時間、來源 IP 與瀏覽器，目前這一個會被標示出來。

可以個別撤銷。撤銷是立即生效的——被撤銷的工作階段下一次請求就會被拒絕。

## 一件不會發生的事

TOTP 密鑰只在啟用流程回傳一次。之後它不會出現在任何 API 回應、任何日誌、任何稽核紀錄裡。

---

# 使用者與權限

/app/users 只有 superadmin 可以使用。

`/app/users` 只有 `super_admin` 可以使用。

<figure class="huan-figure">
	<img src="/huan/screenshots/users.png" alt="使用者管理畫面" />
	<figcaption>使用者管理</figcaption>
</figure>

## 角色

| 角色          | 權限                                                             |
| ------------- | ---------------------------------------------------------------- |
| `super_admin` | 建立、停用、修改使用者、重設密碼、管理所有裝置、查看稽核紀錄     |
| `user`        | 操作素材、版面、排程與裝置，**不能**管理其他使用者或查看稽核紀錄 |

一般使用者連 `/app/users` 這個頁面都進不去，看到的是明確的權限不足說明，而不是一片空白或被靜默重導。

## 建立使用者

需要 Email、帳號、顯示名稱、初始密碼與角色。

- 帳號只能使用小寫英數字與 `.`、`_`、`-`，長度 3 到 32。
- 密碼至少 12 個字元。這是唯一的複雜度要求——強制混合大小寫與符號只會讓人選出更容易預測的密碼。

密碼以 Argon2id 雜湊儲存，系統中沒有任何地方保存明文。

## 停用

停用的帳號無法登入，但所有紀錄都保留下來。稽核日誌裡「誰在什麼時候做了什麼」仍然指得到這個人。

**沒有硬刪除。** 刪掉使用者會讓稽核紀錄失去意義。

## 重設密碼

`super_admin` 可以直接為其他使用者設定新密碼。新密碼**只顯示一次**。

重設密碼會撤銷該使用者所有的工作階段。

## 稽核

所有使用者管理的操作都會留下稽核紀錄：建立、修改、停用、重設密碼。

紀錄包含操作者、動作、目標、時間與來源 IP，**不包含**密碼或任何憑證。

---

# 疑難排解

轉檔在伺服器端進行，一般幾十秒內完成。長時間停住通常代表轉檔程序沒有在跑，請聯絡架設 HUAN 的人。

## 素材

### 上傳卡在「處理中」

轉檔在伺服器端進行，一般幾十秒內完成。長時間停住通常代表轉檔程序沒有在跑，請聯絡架設 HUAN 的人。

### 素材顯示「轉檔失敗」

常見原因是檔案損毀，或格式其實不是副檔名寫的那一種。畫面上會有一句說明。重新輸出成 MP4（H.264）再上傳通常就好了。

### 素材顯示「需要重新上傳」

:::warning[這不是故障，是產品的設計]

HUAN **不永久保存**你上傳的原始檔。

:::

原始檔在轉檔完成後就會刪除，派送用的播放檔也會在所有裝置都拿到之後回收，因為正式的播放副本已經存在裝置本機了。

當下列情況同時成立，這份素材就沒有可以派送的副本了：

- 原始檔已刪除
- 播放檔已回收
- 而你現在需要重新派送（新增了一台裝置，或某台裝置清掉了本機資料）

**解法是重新上傳這個檔案。** 後台會直接標示出來，不會等到派送時才失敗。

想降低發生機率的話，請架設者把保留期調長。詳見[素材生命週期](/huan/dev/asset-lifecycle)。

### 刪不掉素材

素材正在被草稿、已發布的版面、排程或某台裝置使用時，刪除會被擋下來，畫面上會列出是哪些地方在用它。請先把那些地方換掉或移除，再回來刪。

## 版面

### 網頁區塊一片空白

很多網站會明確禁止被嵌入（`X-Frame-Options` 或 `frame-ancestors`）。這是對方網站的安全設定，HUAN 不會也不應該繞過它。

改用允許嵌入的來源，或把內容做成一個 HTML 檔上傳。

### 上傳的 HTML 沒有作用

目前只支援**單一自帶資源**的 HTML 檔案。外部的 `<script src>`、`<link href>` 與圖片都不會載入，需要的資源請用 `data:` URI 內嵌。

### 螢幕上下（或左右）有黑邊

裝置螢幕的長寬比和你設計的畫布不一樣時，HUAN 會把整份畫布等比縮放並置中，剩下的地方填版面背景色。

這是刻意的——拉伸變形比黑邊難看得多。想填滿的話，把版面的畫布尺寸改成和螢幕一樣的比例。

## 裝置

### 配對碼過期

配對碼有效期是 10 分鐘，而且只能用一次。重新啟動播放器就會產生新的一組。

### 裝置顯示離線，但現場明明在播

這兩件事本來就可以同時成立——HUAN 是離線優先的，斷網時畫面照播。

裝置每分鐘左右回報一次，斷線後會以漸增的間隔重連（最長一分鐘）。網路恢復後最多一兩分鐘才會變回線上。

一直是離線的話，請確認裝置連得到 HUAN 的網址。

### 裝置卡在舊版本

打開該裝置的詳細頁，看「目標版本 / 實際版本」與每個素材的同步狀態。

常見原因：

- **磁碟空間不足**：裝置會回報儲存錯誤，後台會顯示出來。
- **某個素材下載失敗**：裝置會**留在舊版本繼續播**並自動重試，這是正確行為，不是故障。
- **素材需要重新上傳**：那份素材已經沒有副本了，裝置永遠拿不到。

按「強制同步」可以讓裝置立刻重新確認一次。

### 畫面全黑但程式在跑

先確認 HDMI 有沒有被偵測到——有些小電腦在開機時沒接螢幕就會停用輸出。接上螢幕後重新啟動裝置。

### 影片播放卡頓

到素材的詳細資訊確認它已經轉成 H.264。若裝置是 Raspberry Pi，另見 [Raspberry Pi 安裝說明](/huan/guide/install-raspberry-pi)裡的效能建議。

## 帳號

### 忘記密碼

HUAN 沒有自助重設流程。請最高權限管理員到「使用者」幫你重設。

### 驗證碼一直說錯

兩步驟驗證允許前後約 30 秒的時鐘誤差。先檢查手機的時間是不是設成自動同步。

同一組驗證碼不能用第二次，等下一組出現再試。

驗證器不在身邊時，用啟用當下抄下來的**復原碼**登入，每組只能用一次。

### 登入之後馬上被登出

通常是伺服器的 Cookie 設定問題，請聯絡架設 HUAN 的人，並提供[部署疑難排解](/huan/dev/troubleshooting#登入之後馬上被登出)這一段。

---

# 開始開發

這一頁把 HUAN 從零跑起來，包含後台、Server、Worker 與一台模擬裝置。

這一頁把 HUAN 從零跑起來，包含後台、Server、Worker 與一台模擬裝置。

## 需求

| 項目    | 版本                           |
| ------- | ------------------------------ |
| Node.js | 24 LTS（見 `.nvmrc`）          |
| pnpm    | 12                             |
| Docker  | 用於 PostgreSQL 與 RustFS      |
| FFmpeg  | 只有在本機直接跑 Worker 時需要 |

```sh
npm install --global corepack@latest
corepack enable pnpm
```

## 1. 安裝與設定

```sh
git clone https://github.com/linyao-tw/huan.git
cd huan
pnpm install
cp .env.example .env
```

打開 `.env`，把 `POSTGRES_PASSWORD` 與 `S3_SECRET_ACCESS_KEY` 換成你自己的值，並確認 `DATABASE_URL` 裡的密碼一致。

## 2. 啟動 PostgreSQL 與 RustFS

```sh
pnpm docker:up
```

這會啟動兩個容器並等到它們通過健康檢查。

## 3. 建立資料表

```sh
pnpm db:migrate
```

## 4. 建立第一個管理員

HUAN **沒有公開註冊**，也沒有預設密碼。第一個最高權限帳號由 CLI 建立：

```sh
pnpm --filter @huan/server admin:create
```

指令會互動式地詢問 Email、帳號、顯示名稱與密碼。密碼至少 12 個字元。

在 Docker 環境或自動化流程裡可以改用非互動模式：

```sh
HUAN_ADMIN_PASSWORD='…' pnpm --filter @huan/server admin:create \
	--email you@example.com --username admin --display-name 管理員
```

## 5. 啟動開發環境

```sh
pnpm dev
```

這會同時啟動：

| 服務   | 位址                    |
| ------ | ----------------------- |
| Admin  | <http://localhost:5173> |
| Server | <http://localhost:4000> |
| Worker | 背景執行                |

用剛才建立的帳號登入 <http://localhost:5173/login>。

## 6.（選用）載入示範資料

想要一組可以直接點的內容：

```sh
pnpm db:seed
```

種子資料包含幾台不同狀態的裝置、幾筆不同處理狀態的素材、一份 70/30 的已發布版面，以及早餐與午餐兩筆排程。

:::warning[只供開發使用]

種子資料的帳號密碼會在執行時印在終端機上，並附帶明確的警告。**絕對不要在正式環境執行 seed。**

:::

## 7. 啟動一台模擬裝置

不需要準備 Raspberry Pi 就能走完整條流程：

```sh
pnpm dev:device-sim
```

終端機會顯示一組 `XXXX-XXXX` 配對碼。到後台的 `/pair` 輸入這組配對碼（或直接開啟終端機印出的網址），確認裝置資訊後綁定。

綁定後模擬裝置會：

1. 連上 WebSocket
2. 取得目標狀態
3. 下載需要的素材並驗證 SHA-256
4. 回報 ACK
5. 開始送 heartbeat

終端機會即時顯示目前的版面修訂、目標與回報版本，以及素材同步進度。

## 8. 走一次完整流程

1. **上傳影片**：`/app/media` → 拖入一支 MP4。狀態會依序變成上傳中 → 處理中 → 就緒。
2. **建立版面**：`/app/layouts` → 新增 1920×1080 的版面。
3. **切分畫面**：在編輯器裡對根區塊做水平分割，把比例拖到 70/30。
4. **放內容**：把影片從左側素材面板拖進左邊的區塊，右邊的區塊放一段文字。
5. **發布**：按發布，建立第一個修訂。
6. **指派**：到 `/app/devices/:id` 把這份版面設為裝置的預設版面。
7. **觀察**：模擬裝置會收到通知、下載影片、驗證雜湊、切換版面，後台的回報版本會跟上目標版本。
8. **測試離線**：`docker compose -f docker/compose.yaml stop`，模擬裝置會繼續播放並持續重試連線。

## 啟動 Electron 播放器

```sh
pnpm dev:device
```

開發模式下是視窗模式；正式打包後預設全螢幕 kiosk。

## 接下來

- [核心概念](/huan/guide/concepts)
- [Docker 部署](/huan/dev/deploy/docker)
- [管理員手冊](/huan/guide/account)

---

# Monorepo

HUAN 是一個 pnpm workspace。

HUAN 是一個 pnpm workspace。

## 結構

```text
apps/
	admin/       Vite + React 的後台與官網（CSR）
	server/      Fastify API、WebSocket 與靜態服務
	worker/      FFmpeg 轉檔 worker
	device/      Electron 播放器
	device-sim/  無 GUI 的模擬裝置
	docs/        Astro 靜態文件站
	e2e/         Playwright 端對端測試與文件截圖
packages/
	protocol/      @huan/protocol — 共用的 zod 結構與型別
	db/            @huan/db — Drizzle schema、連線、migration
	shared/        @huan/shared — 排程判定、退避、格式化、TOTP
	layout-engine/ @huan/layout-engine — 分割樹幾何與樹狀操作
	config/        @huan/config — 環境變數結構
	device-core/   @huan/device-core — 裝置同步引擎
docker/          compose.yaml 與 Dockerfile
scripts/         開發與發布腳本
```

## 為什麼是這幾個套件

每一個共用套件都有**兩個以上的消費者**。這是拆套件的唯一標準。

| 套件                  | 消費者                        |
| --------------------- | ----------------------------- |
| `@huan/protocol`      | Admin、Server、Worker、Device |
| `@huan/db`            | Server、Worker                |
| `@huan/shared`        | Server、Admin、Device         |
| `@huan/layout-engine` | Admin、Device                 |
| `@huan/config`        | Server、Worker                |
| `@huan/device-core`   | Device、模擬裝置              |

`@huan/protocol` 的存在讓「Admin 以為欄位叫 `assetId`、Server 以為叫 `asset_id`」這種問題在編譯期就會被抓到。`@huan/layout-engine` 的存在讓後台預覽與裝置播放不可能算出不同的版面。

## 建置順序

`apps/*` 依賴 `packages/*` 的**建置產物**（`dist/`），不是原始碼。

```sh
pnpm build:packages   # 先建置共用套件
pnpm build            # 再建置應用程式
```

`pnpm dev`、`pnpm test` 與 `pnpm typecheck` 都會自動先跑 `build:packages`。直接執行 `pnpm --filter @huan/server dev` 則不會，這是「找不到 `@huan/protocol`」最常見的原因。

## Import 規範

**絕對不要跨層級相對匯入：**

```ts
import { foo } from "../../../shared/foo"; // ✗
```

正確做法：

```ts
import { thing } from "@/lib/thing"; // ✓ 同一個 app 內部
import { DeviceSchema } from "@huan/protocol"; // ✓ 跨套件
```

### `@/` 只用在 `apps/*`

別名由各自的 bundler 與 `tsconfig.json` 的 `paths` 同時設定：

| App                              | 解析者                      |
| -------------------------------- | --------------------------- |
| `admin`                          | Vite `resolve.alias`        |
| `device`                         | electron-vite               |
| `server`、`worker`、`device-sim` | 開發時 `tsx`，建置時 `tsup` |

因此開發、型別檢查與 production build 三邊都解析得到。**不會只有 IDE 看得懂。**

### `packages/*` 用相對匯入

共用套件以 `tsc` 直接輸出 ESM，沒有 bundler 可以改寫別名，硬加 `@/` 會在 Node 執行時炸掉。

這些套件維持扁平結構，用同層的相對匯入，而且**副檔名要寫 `.js`**（`NodeNext` 模組解析的要求）：

```ts
import { clampRatio } from "./geometry.js"; // ✓
```

## 建置方式

| 目標                             | 工具          | 原因                                      |
| -------------------------------- | ------------- | ----------------------------------------- |
| `packages/*`                     | `tsc`         | 產生真正的 `.d.ts`，Node 可以直接執行     |
| `server`、`worker`、`device-sim` | `tsup`        | 只打包自己的原始碼，npm 相依維持 external |
| `admin`                          | Vite          |                                           |
| `device`                         | electron-vite | main / preload / renderer 三段各自建置    |
| `docs`                           | Astro         | SSG，另跑 Pagefind 產生搜尋索引           |

`tsup` 刻意只打包應用程式自己的程式碼：`@/` 別名在打包時就被解析掉，而第三方套件保持原樣，避免把有動態 `require` 的函式庫硬塞進單一檔案而在執行期爆炸。

## TypeScript

全 workspace 開啟 `strict`。

- 不使用 `any`。需要未知型別時用 `unknown` 並在使用點收斂。
- 不用 `as unknown as T` 繞過型別系統。
- 編譯錯誤要修，不要關掉檢查換取「能跑」。

## 加入新的相依套件

```sh
pnpm --filter @huan/server add some-package
```

加之前先想一下 [ADR-0007](/huan/dev/adr/0007-postgres-job-queue) 的精神：每多一個相依就多一個要維運、要更新、會壞掉的東西。

Device 的相依套件要額外考慮六個平台架構組合（linux-arm64、linux-x64、win-x64、win-arm64、darwin-x64、darwin-arm64）。**原生 Node 模組會讓 ARM 交叉打包變得很困難**，優先找純 JS、Web API 或 Electron 內建的解法。

---

# 指令

pnpm install

## 安裝

```sh
pnpm install
```

repository 只接受 pnpm，`npm install` 與 `yarn` 會被 `preinstall` 腳本拒絕。

## 開發

| 指令                  | 說明                                   |
| --------------------- | -------------------------------------- |
| `pnpm dev`            | 同時啟動 server、worker 與 admin       |
| `pnpm dev:server`     | 只啟動 Fastify（`tsx watch`）          |
| `pnpm dev:admin`      | 只啟動 Vite（<http://localhost:5173>） |
| `pnpm dev:worker`     | 只啟動 FFmpeg worker                   |
| `pnpm dev:device`     | 啟動 Electron 播放器                   |
| `pnpm dev:device-sim` | 啟動無 GUI 的模擬裝置                  |

## 建置

| 指令                  | 說明                                |
| --------------------- | ----------------------------------- |
| `pnpm build:packages` | 建置 `packages/*`（其他指令的前置） |
| `pnpm build`          | 建置所有套件與應用程式              |
| `pnpm typecheck`      | 全 workspace 型別檢查               |

## 測試

| 指令            | 說明                  |
| --------------- | --------------------- |
| `pnpm test`     | 單元與整合測試        |
| `pnpm test:e2e` | Playwright 端對端測試 |

Server 與 Worker 的測試需要 PostgreSQL 與 RustFS，請先 `pnpm docker:up`。

## 資料庫

| 指令                                      | 說明                         |
| ----------------------------------------- | ---------------------------- |
| `pnpm db:migrate`                         | 套用 migration               |
| `pnpm db:generate`                        | 依 schema 產生新的 migration |
| `pnpm db:seed`                            | 寫入開發用示範資料           |
| `pnpm --filter @huan/server admin:create` | 建立第一個最高權限管理員     |

## Docker

| 指令                | 說明     |
| ------------------- | -------- |
| `pnpm docker:up`    | 啟動服務 |
| `pnpm docker:down`  | 停止服務 |
| `pnpm docker:build` | 建置映像 |
| `pnpm docker:logs`  | 追蹤日誌 |

## 文件

| 指令                    | 說明                           |
| ----------------------- | ------------------------------ |
| `pnpm docs:dev`         | 本機文件站                     |
| `pnpm docs:build`       | SSG 建置到 `apps/docs/dist`    |
| `pnpm docs:screenshots` | 以 Playwright 重新擷取產品截圖 |

## 格式

| 指令                | 說明                    |
| ------------------- | ----------------------- |
| `pnpm format`       | 以 Prettier 格式化      |
| `pnpm format:check` | 只檢查不修改（CI 使用） |

Prettier 設定已經存在：tab 縮排、`printWidth: 200`、雙引號、不加尾逗號。**不要修改。**

## Device 打包

| 指令                                       | 說明                 |
| ------------------------------------------ | -------------------- |
| `pnpm --filter @huan/device package:linux` | Linux x64 與 ARM64   |
| `pnpm --filter @huan/device package:win`   | Windows x64 與 ARM64 |
| `pnpm --filter @huan/device package:mac`   | macOS x64 與 ARM64   |

---

# 測試

HUAN 的測試不只是「編譯得過」。

HUAN 的測試不只是「編譯得過」。

```sh
pnpm test        # 單元與整合測試
pnpm test:e2e    # Playwright 端對端測試
```

## 層次

| 層次        | 範圍                   | 需要的環境                 |
| ----------- | ---------------------- | -------------------------- |
| 單元測試    | 共用套件的純邏輯       | 無                         |
| 整合測試    | Server 的 API 與資料庫 | PostgreSQL、RustFS         |
| Worker 測試 | 真實的 FFmpeg 轉檔     | PostgreSQL、RustFS、FFmpeg |
| 元件測試    | Admin 的 React 元件    | 無（jsdom）                |
| 端對端測試  | 瀏覽器操作完整流程     | 全部                       |

需要的環境不存在時，測試會**明確跳過並印出原因**，不會假裝通過。

## 單元測試

集中在幾個一旦錯掉就很難察覺的地方：

**版面分割樹**（`packages/layout-engine`）——分割、刪除、交換、序列化往返，以及幾何計算在 1920×1080、1280×720、3840×2160 與 1080×1920 四種畫布上的實際數值。70/30 在 1920 寬上就是 1344 與 576，測試斷言的是這個數字，不是「差不多」。

**排程判定**（`packages/shared`）——時區換算、跨午夜的錨定日期、日期區間、日光節約時間切換，以及衝突決勝的每一條規則。特別測「同一組輸入永遠得到同一個結果」——把排程用不同順序傳進去必須得到同一個答案。

**TOTP**（`packages/shared`）——RFC 4226 與 RFC 6238 的官方測試向量，加上時鐘誤差容忍與重放拒絕。

**退避**（`packages/shared`）——指數成長、上限封頂、抖動範圍。

**環境變數**（`packages/config`）——預設值、必填檢查、格式驗證。

## Server 整合測試

用 `app.inject()` 對真正的 Fastify 實例發請求，接的是真正的 PostgreSQL 與 RustFS。

涵蓋登入成功與失敗、速率限制、TOTP 完整流程、復原碼只能用一次、權限邊界、配對流程、版面發布、排程 CRUD、素材上傳流程、裝置 ACK 的雜湊驗證，以及刪除被引用的素材會被擋下來。

## Worker 測試

測試素材由 FFmpeg 自己產生：

```sh
ffmpeg -f lavfi -i testsrc=duration=2:size=1280x720:rate=30 …
```

**repository 裡不放任何大型或有版權的影片。**

測試斷言的是實際的輸出屬性：播放版本是 H.264、`yuv420p`、不超過 1920×1080、不超過 30fps、有 faststart，而且 640×360 的來源**不會被放大**。

佇列的測試驗證 `FOR UPDATE SKIP LOCKED` 真的讓兩個並行的取件拿到不同的工作、失敗的工作會退避重試、被強制終止的工作會被回收。

## Admin 元件測試

vitest 加 Testing Library（jsdom）。

涵蓋認證守衛的重導、版面編輯器的分割與交換操作、比例拖曳的座標換算與夾制、素材上傳的各個狀態，以及排程表單的驗證。

## 端對端測試

Playwright，跑完整的流程：

```text
登入
  ↓
建立版面
  ↓
分割區塊
  ↓
放入內容
  ↓
發布
  ↓
配對模擬裝置
  ↓
建立排程
```

模擬裝置（`@huan/device-sim`）讓這件事不需要真的 Raspberry Pi。它走的是和 Electron 播放器**完全相同的同步引擎**，因此測到的行為是真的。

## 文件截圖

```sh
pnpm docs:screenshots
```

用 Playwright 對種子環境擷取真實的產品畫面。種子資料是決定性的，因此每次產生的截圖內容一致，不會讓文件的圖片在每次執行後都不一樣。

**文件裡不放示意圖或 placeholder。**

## CI

`.github/workflows/ci.yml` 在每次 push 與 PR 上執行：

```text
格式檢查 → 建置共用套件 → migration → 型別檢查 → 測試 → 建置 → 文件建置
```

外加獨立的端對端測試 job 與 Docker 映像建置驗證。

PostgreSQL 與 RustFS 以 GitHub Actions 的 service container 提供，FFmpeg 用 apt 安裝。

---

# 系統架構

HUAN 由五個執行中的元件與兩個儲存後端組成。

HUAN 由五個執行中的元件與兩個儲存後端組成。

```mermaid
flowchart LR
	Admin["Admin<br/>React SPA"]
	Server["Server<br/>Fastify"]
	DB[("PostgreSQL")]
	RustFS[("RustFS<br/>S3 相容")]
	Worker["Worker<br/>FFmpeg"]
	Device["Device<br/>Electron"]

	Admin -->|HTTPS REST| Server
	Admin -->|簽章網址直傳| RustFS
	Server --> DB
	Server --> RustFS
	Worker --> DB
	Worker -->|轉檔 / 縮圖 / 回收| RustFS
	Server -.->|WebSocket 通知| Device
	Device -->|HTTPS 取狀態| Server
	Device -->|簽章網址下載| RustFS
```

## 控制平面與資料平面

HUAN 刻意把「通知」與「資料」分開。

```mermaid
flowchart TB
	subgraph control["控制平面 — WebSocket"]
		direction LR
		S1["Server"] -->|"{ type: 'desired_state_changed', version: 42 }"| D1["Device"]
		D1 -->|"heartbeat / command_result"| S1
	end

	subgraph data["資料平面 — HTTPS"]
		direction LR
		D2["Device"] -->|"GET /api/v1/device/state"| S2["Server"]
		D2 -->|"GET 簽章網址"| R["RustFS"]
		D2 -->|"POST /api/v1/device/assets/ack"| S2
	end

	control --> data
```

WebSocket 傳的訊息永遠很小，而且只表達「有東西變了」。真正的狀態一律回到 REST API 取得——**REST 才是唯一的事實來源**。

這樣做的理由見 [ADR-0001](/huan/dev/adr/0001-websocket-plus-rest)。

## 為什麼不是每 10 秒問一次

一台裝置每 10 秒完整拉一次狀態，一百台就是每秒十次全量查詢，而其中九成九的回應內容完全相同。

HUAN 用的是：

- **WebSocket 通知**：有變化時立刻推播，延遲接近零。
- **每 5 分鐘的保底同步**：推播漏掉時仍會補上，不完全依賴長連線。
- **約 60 秒的 heartbeat**：回報實際狀態並確認裝置還活著。

斷線後以指數退避加抖動重連（1s → 2s → 4s → … → 60s 上限）。抖動不是裝飾：整個賣場的看板同時斷線時，沒有抖動就會在同一秒一起重連，把剛恢復的 Server 再打掛一次。

## 資料流：從上傳到播放

```mermaid
sequenceDiagram
	participant A as Admin
	participant S as Server
	participant R as RustFS
	participant W as Worker
	participant D as Device

	A->>S: POST /media/uploads
	S-->>A: 簽章 PUT 網址
	A->>R: PUT 原始影片
	A->>S: POST /media/uploads/complete
	S->>S: 建立 transcode 工作

	W->>S: 取得工作（FOR UPDATE SKIP LOCKED）
	W->>R: 下載原始檔
	W->>W: ffprobe + 轉檔 + 縮圖
	W->>R: 上傳 playback / preview / thumbnail
	W->>R: 刪除原始檔
	W->>S: 標記 ready

	A->>S: 建立版面、拖入影片、發布
	S->>S: 建立 layout revision、重算目標狀態
	S-->>D: desired_state_changed(version)

	D->>S: GET /device/state
	D->>S: GET /device/assets/:id/url
	D->>R: 下載播放檔
	D->>D: 驗證 SHA-256
	D->>S: POST /device/assets/ack
	D->>D: 全部就緒 → 原子性切換版本
	D->>S: heartbeat（reported = 42）
```

## 元件職責

### Admin

React 19 單頁應用程式，用 Vite 建置，不做伺服器端算繪。TanStack Query 管理伺服器狀態，React Router 管理路由。版面編輯器的預覽用的是 `@huan/layout-engine`——和 Device 播放器完全同一套幾何計算，因此後台看到 70/30，實機就是 70/30。

大型檔案不經過 Fastify：Admin 向 Server 換一組簽章網址，然後瀏覽器直接 PUT 到 RustFS。

### Server

Fastify 5，所有路由都用 `@huan/protocol` 的 zod 結構驗證，OpenAPI 由同一份結構自動產生，不會出現文件與實作不同步的情況。

Server 負責帳號、session、TOTP、裝置憑證、配對、素材中繼資料、版面修訂、排程、目標狀態計算、簽章網址與稽核紀錄。

### Worker

獨立的 process 與獨立的容器。FFmpeg 轉一支 1080p 影片可能要好幾分鐘，這件事絕對不能跑在 Fastify 的事件迴圈裡。

工作佇列就是 PostgreSQL 的一張表，用 `SELECT ... FOR UPDATE SKIP LOCKED` 取件。這個 MVP 不需要 Redis（[ADR-0007](/huan/dev/adr/0007-postgres-job-queue)）。

### Device

Electron 應用程式，主行程負責身分、API、WebSocket、下載佇列、排程與本機儲存；算繪行程只負責畫面。算繪行程沒有 Node 權限（`nodeIntegration: false`、`contextIsolation: true`、`sandbox: true`），上傳的 HTML 在再一層 sandbox iframe 裡執行。

同步引擎在 `@huan/device-core`，是純 Node 程式庫，因此可以完全不用 Electron 就跑起來——這也是模擬裝置能存在的原因。

## 共用套件

| 套件                  | 內容                                      | 使用者                |
| --------------------- | ----------------------------------------- | --------------------- |
| `@huan/protocol`      | 所有 API、WebSocket、版面、排程、裝置結構 | 全部                  |
| `@huan/db`            | Drizzle schema、連線、migration           | Server、Worker        |
| `@huan/shared`        | 排程判定、退避、格式化、TOTP              | Server、Device、Admin |
| `@huan/layout-engine` | 分割樹幾何、縮放、樹狀操作                | Admin、Device         |
| `@huan/config`        | 環境變數結構與驗證                        | Server、Worker        |
| `@huan/device-core`   | 裝置同步引擎                              | Device、模擬裝置      |

型別只定義一次。Admin、Server 與 Device 不會各自維護一份會漂移的介面。

---

# Server

Fastify 5，TypeScript，PostgreSQL。

Fastify 5，TypeScript，PostgreSQL。

## 結構

```text
apps/server/src/
	main.ts          進入點
	app.ts           buildServer()，測試也用同一個組裝函式
	env.ts           以 @huan/config 驗證環境變數
	plugins/         cookie、cors、rate limit、websocket、swagger、static、錯誤處理
	lib/             認證、密碼、session、TOTP、儲存、稽核、目標狀態計算
	routes/          依領域切分的路由
	ws/              裝置與後台的 WebSocket 端點
	cli/             migrate、seed、create-admin
```

## 結構驗證與 OpenAPI

每一條路由的請求與回應都用 `@huan/protocol` 的 zod 結構驗證，OpenAPI 文件由**同一份結構**自動產生。

這表示 API 文件不可能和實作不同步——它們是同一個東西的兩種輸出。

開發模式下可以在 `/api/v1/docs` 瀏覽，`/api/v1/openapi.json` 取得原始規格。

## 認證

### 密碼

Argon2id。系統中沒有任何地方保存明文密碼，也沒有任何可逆的表示法。

### Session

登入成功後產生一組隨機的不透明 token，放進 `HttpOnly`、`SameSite=Lax` 的 cookie（正式環境加上 `Secure`）。

資料庫只存這個 token 的 SHA-256。資料庫外洩時拿不到可用的 token，撤銷也只是刪掉一列資料。

:::tip[為什麼 session token 用 SHA-256 而不是 Argon2]

Argon2 是為了對抗**低熵**密碼的暴力破解而設計的慢雜湊。Session token 是密碼學隨機產生的 256 bit 值，沒有暴力破解的可能性，用慢雜湊只會讓每一次請求都多花數十毫秒。

:::

長期憑證絕不放在 `localStorage`——那裡的東西任何一段跑在同源的 JavaScript 都讀得到。

### 兩步驟驗證

啟用 TOTP 後，登入分成兩段：

```mermaid
sequenceDiagram
	participant U as 使用者
	participant S as Server

	U->>S: POST /auth/login（帳號、密碼）
	alt 未啟用 2FA
		S-->>U: 設定 session cookie
	else 已啟用 2FA
		S-->>U: { status: "totp_required", challengeToken }
		U->>S: POST /auth/totp/challenge（challengeToken + 驗證碼）
		S-->>U: 設定 session cookie
	end
```

`challengeToken` 是短時效、一次性的中繼憑證，**不能存取任何 API**，只能用來完成第二階段。

TOTP 遵循 RFC 6238，容忍前後各一個時間步長的時鐘誤差，並記錄上次成功的時間步長以拒絕同一組驗證碼的重放。實作有 RFC 4226 與 RFC 6238 官方測試向量的單元測試。

TOTP 密鑰只在啟用流程回傳一次，之後不會出現在任何 API 回應或日誌中。

### 復原碼

啟用 2FA 時產生 10 組復原碼，**只顯示一次**。Server 只保存雜湊，使用後立即失效。

### 速率限制

每次登入嘗試都寫進 `login_attempts`。同一組帳號或同一個來源 IP 在時間窗內失敗次數超過上限就會被擋下。

紀錄寫在資料庫而不是記憶體，因此重啟 Server 不會把攻擊者的計數歸零。

## 角色

只有兩種角色：

| 角色          | 權限                                           |
| ------------- | ---------------------------------------------- |
| `super_admin` | 管理使用者、所有裝置、查看稽核紀錄             |
| `user`        | 操作素材、版面、排程與裝置，不能管理其他使用者 |

**沒有公開註冊。** 第一個管理員由 CLI 建立，之後的使用者由 `super_admin` 在後台建立。

## 健康檢查

| 端點                | 檢查內容                         |
| ------------------- | -------------------------------- |
| `GET /health/live`  | 永遠 200，只證明 process 還活著  |
| `GET /health/ready` | 檢查 PostgreSQL 連線，失敗回 503 |

RustFS 刻意**不列入** readiness。物件儲存暫時不可用時，Server 仍然能提供後台 API 與裝置的目標狀態，裝置也能繼續播放本機已有的內容；把整個服務標成 not ready 只會讓負載平衡器把它從輪替中移除，讓情況更糟。上傳與下載會在當下回報明確的錯誤。

## 稽核紀錄

所有重要操作都會留下紀錄：登入、登入失敗、啟用與停用 2FA、建立與停用使用者、裝置配對與解除綁定、發布版面、修改排程、刪除素材、強制同步。

每筆紀錄包含操作者、動作、目標、時間與來源 IP。

**絕不寫入**密碼、TOTP 密鑰、復原碼、session token、裝置憑證或簽章網址的查詢字串。

---

# Worker

獨立的 process、獨立的容器。

獨立的 process、獨立的容器。

## 為什麼要獨立

FFmpeg 轉一支 1080p 的影片可能要好幾分鐘，而且會把 CPU 吃滿。這件事跑在 Fastify 裡會有兩個後果：轉檔期間 API 完全沒有回應；而且要擴充轉檔能力就必須連 API 一起擴充。

分開之後，Server 只負責把工作寫進資料表，Worker 自己去取。要加快轉檔就多開幾個 Worker 容器，Server 完全不用動。

## 工作佇列就是一張資料表

```sql
SELECT * FROM worker_jobs
WHERE status = 'pending' AND run_after <= now()
ORDER BY run_after, created_at
FOR UPDATE SKIP LOCKED
LIMIT 1;
```

`FOR UPDATE SKIP LOCKED` 是 PostgreSQL 內建的佇列原語：取件的交易會鎖住那一列，其他 Worker 直接跳過它去拿下一件。不需要 Redis，也不需要外部的訊息佇列（[ADR-0007](/huan/dev/adr/0007-postgres-job-queue)）。

### 狀態機

```mermaid
stateDiagram-v2
	[*] --> pending
	pending --> running: 取件成功
	running --> success: 完成
	running --> pending: 失敗且還有重試次數<br/>run_after = now() + 退避
	running --> failed: 用完重試次數
	running --> pending: process 被殺掉<br/>逾時回收
	success --> [*]
	failed --> [*]
```

每一筆工作都記錄 `attempt`、`max_attempts`、`error`、`started_at`、`finished_at` 與 `run_after`。

重試使用指數退避。被強制終止的 Worker 留下的 `running` 工作會在逾時後被回收成 `pending`，不會永遠卡住。

## 工作種類

| 種類                   | 內容                                    |
| ---------------------- | --------------------------------------- |
| `transcode_video`      | ffprobe → 轉檔 → 縮圖 → 預覽 → 播放版本 |
| `process_image`        | 尺寸限制、縮圖、預覽、播放版本          |
| `process_html`         | 驗證、大小限制、複製為播放版本          |
| `cleanup_distribution` | 回收已結清且過保留期的播放產物          |

## FFmpeg 的呼叫方式

**一律使用 `spawn` 加參數陣列，永遠不拼接 shell 字串。**

```ts
spawn(ffmpegPath, ["-i", inputPath, "-c:v", "libx264", "-pix_fmt", "yuv420p", outputPath]);
```

這是硬性的安全要求。使用者可以控制檔名與中繼資料，只要有一個地方把它們接進 shell 字串，就變成命令注入。參數陣列從根本上讓這件事不可能發生。

實際上 Worker 連檔名都不會傳給 FFmpeg——輸入輸出都是 Worker 自己在暫存目錄裡產生的 UUID 路徑。

## 錯誤訊息

工作最終失敗時，資料庫裡存的是一句給使用者看的中文說明：

```text
影片轉檔失敗，來源檔案可能損毀或格式不支援。
```

完整的 FFmpeg 指令、stderr 與檔案系統路徑只留在結構化日誌裡。一般使用者不需要看到 `/var/tmp/huan/9f3a.../input.mkv`，那對他們沒有幫助，還洩漏了伺服器的內部結構。

## 日誌

每一行工作日誌都帶著 `jobId`、`assetId` 與 `kind`。

**不記錄簽章網址**——那些網址的查詢字串裡就是憑證。日誌記的是物件鍵。

---

# Device

Electron 播放器。同一份程式碼跑在 Raspberry Pi、Ubuntu、Windows 與 macOS 上。

Electron 播放器。同一份程式碼跑在 Raspberry Pi、Ubuntu、Windows 與 macOS 上。

## 行程分工

```mermaid
flowchart TB
	subgraph main["主行程（Node）"]
		ID["裝置身分與憑證"]
		API["REST 用戶端"]
		WS["WebSocket 用戶端"]
		DL["下載佇列"]
		SCH["排程執行"]
		ST["本機儲存"]
		PA["PlatformAdapter"]
	end

	subgraph renderer["算繪行程（沙箱）"]
		PAIR["配對畫面"]
		PLAY["播放器"]
	end

	main <-->|"preload 暴露的最小 IPC"| renderer
```

主行程掌握所有敏感能力。算繪行程只知道「現在要畫什麼」。

## 安全設定

```ts
{
	nodeIntegration: false,
	contextIsolation: true,
	sandbox: true
}
```

這三個設定不會為了任何功能而放寬。

preload 只暴露必要的幾個方法（取得目前版面、回報播放錯誤、取得裝置資訊、觸發解除綁定），而且每一個都經過結構驗證。

### 上傳的 HTML

使用者上傳的 HTML 在**再一層** sandbox iframe 裡執行，透過自訂協定從本機讀取，並套用嚴格的 CSP。

它拿不到 `require`、拿不到檔案系統、拿不到 Electron API、也拿不到 preload 暴露的介面。

「因為要播放 HTML 所以把 Electron 的安全設定關掉」是絕對不會發生的事。

## 本機儲存

```text
appData/
├─ config/     裝置身分、伺服器位址
├─ state/      目標狀態、回報狀態、啟用中的版本
├─ media/      已驗證的播放檔
├─ manifests/  active.json、pending.json
└─ logs/
```

所有寫入都是原子的：先寫 `.tmp`、`fsync`、再 `rename`。

看板通常裝在牆上，沒有 UPS，斷電是常態而不是意外。半寫入的 manifest 會讓裝置開機後不知道自己該播什麼——原子寫入讓這件事不可能發生。

讀取遇到缺檔或損毀時回傳 `null` 並記錄，**不會拋例外把播放器弄掛**。

## 下載

- 同時最多 2 到 3 個檔案。不會一次抓五十支影片把現場網路塞死。
- 下載到 `.part` 暫存檔，邊寫邊算 SHA-256。
- 雜湊符合才 `rename` 成正式檔名，然後才 ACK。
- **雜湊不符時刪除暫存檔並重試，絕不 ACK。**
- 簽章網址過期時重新向 Server 索取，不會讓整次同步失敗。
- 已經存在且雜湊正確的檔案直接跳過，重開機不會重下載一輪。
- 伺服器支援 `Range` 時可以續傳。

## 儲存空間管理

下載前先檢查剩餘空間。不足時先回收未被引用的檔案；仍然不足就向 Server 回報 `storageError`，讓後台顯示出來。

回收**永遠不會刪除**：

- 目前啟用版本的素材
- 下一個排程版本需要的素材
- 正在下載中的檔案

## PlatformAdapter

平台差異集中在一個介面裡：

```ts
interface PlatformAdapter {
	getDisplays(): Promise<DisplayInfo[]>;
	getDiskInfo(): Promise<DiskInfo>;
	getTemperature(): Promise<number | null>;
	getUptime(): Promise<number>;
}
```

`LinuxAdapter`、`WindowsAdapter`、`MacOSAdapter` 各自實作，核心程式碼完全不需要出現 `if (process.platform === "win32")`。

裝置**不可以假設**系統上一定有 `apt`、`vcgencmd` 或 `systemd`。Raspberry Pi 上讀得到 CPU 溫度，Windows 上讀不到就回報 `null`——不為了型別好看而編一個數字。

## 本機介面

未綁定時顯示配對畫面：品牌、`XXXX-XXXX` 配對碼與 QR Code。

綁定後直接進入播放器，預設全螢幕 kiosk 模式，不顯示作業系統桌面。

**綁定後不能在裝置本機修改版面、素材或排程。** 本機只提供：

- 裝置基本資訊
- 網路與連線狀態
- 配對狀態
- 解除綁定

透過系統匣、選單或鍵盤快捷鍵開啟，不影響正常播放。

## 解除綁定

解除綁定需要二次確認，之後：

1. 撤銷本機憑證
2. 清除帳戶綁定與目標狀態
3. 回到配對畫面

離線時解除綁定也會**立即生效**：本機馬上停止接受帳戶控制，並保留一個待撤銷狀態，下次連上線時完成伺服器端的撤銷。

待撤銷狀態不會因為收到過期的伺服器回應而被還原——已經解除的綁定不會自己恢復。

## 崩潰後復原

裝置重新啟動後：

```text
載入最後一份已知良好的狀態
  ↓
繼續播放
  ↓
在背景重新連線 Server
```

**開機不需要 Server 在線。** 這是離線優先設計的必然結果，也是驗收時一定要測的一項。

---

# 素材生命週期

這一章描述一個檔案從上傳到被回收的完整過程，以及 HUAN 在儲存上刻意做的取捨。

這一章描述一個檔案從上傳到被回收的完整過程，以及 HUAN 在儲存上刻意做的取捨。

## 完整流程

```mermaid
flowchart TD
	U["使用者選擇檔案"] --> A["POST /media/uploads<br/>取得簽章網址"]
	A --> B["瀏覽器 PUT 直傳 RustFS<br/>uploads/"]
	B --> C["POST /media/uploads/complete<br/>狀態：UPLOADED"]
	C --> D["建立 worker job"]

	D --> E["Worker 下載原始檔"]
	E --> F["ffprobe 取得中繼資料"]
	F --> G["產生 thumbnail / preview / playback"]
	G --> H["上傳到 thumbnail/、preview/、distribution/"]
	H --> I["刪除原始檔"]
	I --> J["狀態：READY"]

	J --> K{"被已發布的版面<br/>指派給裝置？"}
	K -->|否| J
	K -->|是| L["產生短時效簽章下載網址"]
	L --> M["Device 下載 → 驗證 SHA-256 → ACK"]
	M --> N{"所有目標裝置<br/>都 ACK？"}
	N -->|否| M
	N -->|是| O["記錄結清時間，開始保留期"]
	O --> P{"保留期屆滿？"}
	P -->|否| O
	P -->|是| Q["回收 playback 產物"]
	Q --> R{"還有其他可用副本？"}
	R -->|有| J
	R -->|沒有| S["狀態：NEEDS_REUPLOAD"]
```

## 儲存命名空間

RustFS 裡的物件依用途分成幾個前綴：

| 前綴            | 內容                         | 保留策略                          |
| --------------- | ---------------------------- | --------------------------------- |
| `uploads/`      | 使用者上傳的原始檔           | 轉檔成功後立即刪除                |
| `processing/`   | Worker 的中間產物            | 工作結束即刪除                    |
| `thumbnail/`    | 素材庫縮圖                   | 長期保留（很小）                  |
| `preview/`      | 後台排版預覽用的低解析度版本 | 長期保留                          |
| `distribution/` | 派送到裝置的播放檔           | 所有目標裝置 ACK 且過保留期後回收 |

**物件鍵一律由 UUID 組成，永遠不使用使用者提供的檔名。**

一個叫 `../../etc/passwd.mp4` 的上傳檔案不會變成路徑問題，因為那個名字只會被存成中繼資料裡的一個字串，從來不會出現在物件鍵裡。副檔名由 content type 推導，不是從檔名擷取。

## 為什麼原始檔會被刪除

一支 4K 的原始影片可能有 8 GB。轉檔後的 1080p 播放檔可能只有 200 MB。如果原始檔永久保存，物件儲存的成本會隨著上傳量線性成長，而那些原始檔在系統裡沒有任何用途——播放用的是轉檔後的版本，預覽用的是預覽版本。

所以 HUAN 在轉檔成功後就刪除原始檔。這是刻意的產品決定，理由完整寫在 [ADR-0003](/huan/dev/adr/0003-temporary-object-storage)。

## 為什麼播放產物也會被回收

同樣的道理再往前一步：正式的播放副本最終保存在**裝置本機**。當所有目標裝置都下載完成並回報 ACK 之後，RustFS 上那份 `distribution/` 的副本就沒有讀者了。

回收前有兩道保護：

1. **必須所有目標裝置都 ACK**。第一台下載成功就刪除，第二台就永遠拿不到了。
2. **必須經過保留期**（預設 24 小時，`DISTRIBUTION_RETENTION_HOURS`）。這段緩衝是為了吸收 ACK 與重試之間的競態——裝置可能剛回報成功就重開機並重新下載，也可能有一台裝置的 ACK 因為網路問題晚了幾分鐘才到。

## 需要重新上傳

:::warning[這是產品的真實限制，不是 bug]

HUAN 不永久保存完整的播放素材。

:::

當下列情況同時成立：

- 原始檔已在轉檔後刪除
- `distribution/` 的播放產物已在所有裝置 ACK 後回收
- 而你現在需要重新派送這份素材（新增了一台裝置、或某台裝置清掉了本機儲存）

RustFS 上就不再有可以派送的版本。這時素材會被標記為 **需要重新上傳**（`NEEDS_REUPLOAD`），後台會直接這樣顯示。

系統不會假裝檔案還在，也不會在派送時才發現失敗。資料模型本身就能表達這個狀態：每個 `media_variants` 資料列都有 `available` 欄位，物件被回收後轉為 `false`，資料列保留下來，讓 UI 能解釋素材為什麼需要重新上傳。

### 怎麼避免

- 把 `DISTRIBUTION_RETENTION_HOURS` 調長。設成 `720`（30 天）就等於「一個月內都還能重新派送」。
- 在既有裝置還在線上時就先完成新裝置的配對與同步。
- 對於重要的長期素材，在自己這邊保留一份原始檔備份。HUAN 是播放系統，不是資產管理系統。

## 影片轉檔目標

目標是產生「小、通用、Raspberry Pi 也放得動」的檔案。

| 項目       | 設定                             |
| ---------- | -------------------------------- |
| 容器       | MP4                              |
| 視訊       | H.264（High profile, level 4.0） |
| 像素格式   | `yuv420p`                        |
| 最大解析度 | 1920×1080                        |
| 最大影格率 | 30 fps                           |
| 音訊       | AAC                              |
| Fast start | 啟用（`-movflags +faststart`）   |

**不做放大。** 一支 640×360 的來源檔轉出來還是 640×360，把它拉成 1080p 只會讓檔案變大、畫質不變。長寬比一律保持原樣。

`yuv420p` 是刻意指定的：某些來源使用 `yuv444p` 或 10-bit 格式，Raspberry Pi 的硬體解碼器不支援，播放時會退回軟體解碼並卡頓。

## 圖片處理

圖片上傳後同樣產生三種產物。播放版本會限制在合理尺寸——不能讓 Raspberry Pi 每次算繪都去解一張 12000×9000 的原圖。

長寬比保持不變。來源含有 alpha 通道時，播放版本會保留透明資訊，不會被壓成黑底。

## HTML

第一版只支援**單一自帶資源的 HTML 檔案**。需要圖片時請用 `data:` URI 內嵌。完整的網站 ZIP 代管不在這一版的範圍內。

上傳的 HTML 在裝置上以 sandbox iframe 執行，沒有 Node、沒有檔案系統、沒有 Electron API。詳見 [Device 架構](/huan/dev/device)。

---

# Desired / Reported State

這是 HUAN 最核心的同步模型。

這是 HUAN 最核心的同步模型。

## 模型

Server 不對裝置下命令，而是宣告一個**目標**：

```json
{
	"deviceId": "…",
	"version": 42,
	"defaultLayout": { "revisionId": "…", "document": { … } },
	"schedules": [ … ],
	"assets": [ { "assetId": "…", "sha256": "…", "downloadPath": "…" } ]
}
```

裝置回報一個**現況**：

```json
{
	"desiredVersion": 41,
	"currentLayoutRevisionId": "…",
	"readyAssetIds": [ … ],
	"pendingAssetIds": [ … ],
	"diskFreeBytes": 12884901888
}
```

差異由裝置自己彌平：下載、驗證、啟用、回報。

```mermaid
stateDiagram-v2
	[*] --> 同步中: desired 42 ≠ reported 41
	同步中 --> 下載中: 取得目標狀態
	下載中 --> 驗證中: 檔案下載完成
	驗證中 --> 下載中: SHA-256 不符，刪除重試
	驗證中 --> 就緒: 全部檔案通過驗證
	就緒 --> 已同步: 原子性切換版本
	已同步 --> [*]: reported = 42

	下載中 --> 維持舊版: 任何檔案最終失敗
	維持舊版 --> 下載中: 稍後重試
```

## 為什麼不用命令式 RPC

想像一下命令式的版本：Server 送出「下載這個檔案」、「切換到那個版面」、「重新啟動播放器」。

那麼裝置在下載到一半時斷電，會發生什麼事？Server 以為指令送出去了，裝置醒來卻不知道自己該做什麼。Server 得記住每一條指令送到哪一步、哪些成功、哪些要重送——這就是在資料庫裡重新發明一套不可靠的工作流程引擎。

宣告式模型讓這個問題消失。裝置重新開機後只要做一件事：比較目標與現況，然後把差距補上。中間斷過幾次、重試過幾輪，都不影響最終結果。

完整理由見 [ADR-0002](/huan/dev/adr/0002-desired-reported-state)。

## 版本號

`desiredVersion` 是每台裝置各自的單調遞增整數。

Server 在下列情況重算目標狀態：

- 裝置完成配對
- 版面發布新的修訂
- 排程建立、修改或刪除
- 裝置的預設版面改變

重算之後**只有內容真的不同**才會遞增版本號。這一點很重要：如果每次重算都遞增，改一個不相干的排程就會讓一百台裝置全部誤以為自己落後，然後同時來要狀態。

## 原子性切換

新版本必須**全部**準備好才能啟用：

1. 下載版本 B 需要的每一個檔案
2. 逐一驗證 SHA-256
3. 全部通過後，寫入新的 `manifests/active.json` 並切換播放器

在這整段期間，版本 A 一直在播。任何一個檔案失敗，裝置就留在版本 A 並稍後重試。

**絕對不會先刪除版本 A 的檔案再下載版本 B。** 舊版本的素材要等新版本成功啟用並經過保留期之後才會被回收。

## Heartbeat 回報什麼

| 欄位                                | 說明                                                |
| ----------------------------------- | --------------------------------------------------- |
| `desiredVersion`                    | 裝置目前已啟用的版本                                |
| `appVersion` / `protocolVersion`    | 用於相容性判斷                                      |
| `platform` / `arch` / `osVersion`   | 平台資訊                                            |
| `displays`                          | 每個顯示器的解析度、縮放與方向                      |
| `currentLayoutRevisionId`           | 現在正在播的版面修訂                                |
| `currentScheduleId`                 | 命中的排程，沒有排程時為 `null`                     |
| `readyAssetIds` / `pendingAssetIds` | 同步進度                                            |
| `diskFreeBytes` / `diskTotalBytes`  | 儲存空間                                            |
| `temperatureCelsius`                | Raspberry Pi 取得得到；Windows 與 macOS 回報 `null` |
| `uptimeSeconds` / `lastSyncAt`      | 運作時間與最後同步時間                              |
| `storageError`                      | 空間不足或寫入失敗時的說明                          |

取不到的欄位一律回報 `null`。HUAN 不會為了讓型別好看而填假數值——後台顯示「—」比顯示一個編出來的溫度誠實得多。

---

# 版面與縮放

HUAN 的版面不是自由拖曳的絕對定位畫布，而是一棵遞迴分割樹。

## 遞迴分割樹

HUAN 的版面不是自由拖曳的絕對定位畫布，而是一棵遞迴分割樹。

```ts
type LayoutNode =
	| {
			type: "split";
			id: string;
			direction: "horizontal" | "vertical";
			ratio: number;
			first: LayoutNode;
			second: LayoutNode;
	  }
	| {
			type: "slot";
			id: string;
			content: SlotContent | null;
	  };
```

任何區塊都可以被水平或垂直切成兩塊，切出來的每一塊又都可以繼續切。

```text
root（水平分割 0.7）
├─ first  → 影片（畫面左側 70%）
└─ second（垂直分割 0.5）
   ├─ first  → 標題文字（右上）
   └─ second → 跑馬燈（右下）
```

### 方向的定義

`direction` 描述的是**兩個子區塊怎麼排**，不是分隔線的方向：

- `horizontal`：兩塊水平並排，`first` 在左、`second` 在右。
- `vertical`：兩塊垂直堆疊，`first` 在上、`second` 在下。

這和 CSS 的 `flex-direction: row / column` 是同一種直覺。

### 為什麼是比例而不是像素

`ratio` 是 0 到 1 之間的比例，不是固定的 px 寬度。

一份 1920×1080 的版面裡，70/30 的分割在 1920 寬時是 1344/576。同一份版面放到 1280×720 的螢幕上，仍然是 70/30——896/384。如果存的是「左邊 1344px」，換一台螢幕就整個歪掉。

比例也有下限與上限（0.05 到 0.95）。沒有這個限制，使用者一不小心就會拖出 0.001 / 0.999 這種再也點不回來的版面。

完整理由見 [ADR-0004](/huan/dev/adr/0004-recursive-split-layout)。

## 間距

`gap` 的單位是**設計畫布的 px**，會跟著畫布一起等比縮放。

間距是從可用空間裡扣掉的，不是加在外面：不論分幾層，所有區塊的外緣永遠貼齊畫布邊界，只有區塊之間有間距。

```text
容器寬 1000、gap 20、ratio 0.5
→ 左塊 x=0   寬 490
→ 右塊 x=510 寬 490
→ 右緣 510 + 490 = 1000 ✓
```

## 縮放策略

設計畫布的尺寸和實體螢幕往往不同。HUAN 的策略是 **contain**：

```text
scale = min(螢幕寬 / 畫布寬, 螢幕高 / 畫布高)
```

整份畫布等比縮放並置中，長寬比不同時剩下的區域填入版面背景色。

**不做拉伸。** 一份 16:9 的版面放到 4:3 的螢幕上，會上下（或左右）留邊，而不是把所有東西壓扁。變形的看板比黑邊難看得多，而且客戶不會知道問題出在自己選錯解析度還是系統壞了。

| 畫布      | 螢幕      | 結果                    |
| --------- | --------- | ----------------------- |
| 1920×1080 | 1280×720  | 完整填滿，scale = 0.667 |
| 1920×1080 | 1000×1000 | 上下留邊，內容高 562.5  |
| 1080×1920 | 1920×1080 | 左右留邊，內容寬 607.5  |

## 一份實作，兩個地方使用

`@huan/layout-engine` 同時被後台預覽與裝置播放器使用：

```mermaid
flowchart LR
	LE["@huan/layout-engine<br/>computeLayoutGeometry<br/>computeFitTransform"]
	LE --> A["Admin 版面編輯器預覽"]
	LE --> D["Device 播放器算繪"]
```

這不是為了少寫程式碼，而是為了**保證兩邊完全一致**。如果後台自己算一套、裝置再算一套，遲早會出現「後台看起來是 70/30，實機顯示變成 68/32」這種沒人查得出來的偏差。

幾何計算有針對 1920×1080、1280×720、3840×2160 與 1080×1920 的單元測試，斷言的是實際數值——70/30 在 1920 寬上就是 1344 與 576，不多不少。

## 版面修訂

發布不會覆蓋現有內容，而是建立一筆**不可變的修訂**：

```text
版面 3
├─ 修訂 12（2026-08-01 發布）
├─ 修訂 13（2026-08-14 發布）
└─ 修訂 14（2026-09-02 發布）← 目前
```

草稿與已發布版本完全分離。你可以放心編輯草稿，現場播的還是上一次發布的內容。

裝置的目標狀態指向的是**修訂 id**，不是版面 id。這讓下列事情變得可行：

- 稽核：知道某台裝置在某個時間點播的是哪一版
- 回溯：把裝置指回舊的修訂
- 版本判斷：裝置能明確知道自己是不是落後
- 原子更新：修訂內容不會在裝置下載到一半時被改掉

---

# 排程與時區

一筆排程描述「在哪些日子的哪個時段，哪些裝置該播哪個版面」。

## 排程長什麼樣

一筆排程描述「在哪些日子的哪個時段，哪些裝置該播哪個版面」。

| 欄位                    | 說明                                         |
| ----------------------- | -------------------------------------------- |
| `layoutId`              | 要播的版面。實際派送的是它目前已發布的修訂。 |
| `timezone`              | IANA 時區，例如 `Asia/Taipei`。              |
| `priority`              | 數字愈大愈優先。                             |
| `startDate` / `endDate` | 生效的日期區間，可留空表示不限。             |
| `daysOfWeek`            | 星期幾生效，0 是星期日。                     |
| `startTime` / `endTime` | `HH:MM`。結束早於或等於開始時代表跨午夜。    |
| `deviceIds`             | 目標裝置。                                   |

典型的用法：

```text
星期一至五 08:00–11:00  早餐版面
星期一至五 11:00–14:00  午餐版面
星期一至五 14:00–17:00  下午茶版面
```

沒有任何排程命中的時段，裝置播放它的**預設版面**；連預設版面都沒有時顯示待命畫面。

## 時區必須存 IANA 名稱

排程存的是 `Asia/Taipei`，不是 UTC+8，也不是 Server 的本機時區。

理由很簡單：UTC 偏移會變，時區不會。一個設在 `America/New_York` 早上八點的排程，在三月和十一月對應到不同的 UTC 時刻。如果只存「UTC 13:00」，日光節約時間切換的那個週末，看板就會在錯誤的時間換畫面。

判定完全建立在**牆上時間**之上：

```ts
const wall = toWallClock(instant, entry.timezone);
// { date: "2026-03-02", time: "08:30", weekday: 1 }
```

平台的時區資料庫負責換算，HUAN 只比較「當地現在幾點」。日光節約時間、半小時偏移的時區、南半球的反向切換，全都自動正確。

不存在的當地時刻（日光節約時間往前跳過的那一小時）在那一天就是不會命中——這是刻意的行為，而不是靜默地播錯東西。

## 跨午夜

`endTime` 小於或等於 `startTime` 時代表視窗跨過午夜。

視窗**錨定在開始的那一天**：

```text
星期一 22:00–02:00
= 星期一晚上十點  →  星期二凌晨兩點
```

星期二凌晨一點會命中（因為它屬於星期一開始的視窗），星期三凌晨一點則不會（星期二晚上沒有排程）。

## 衝突怎麼決勝

兩筆排程同時生效時，依序比較下列條件，直到分出勝負：

1. **`priority` 較大**的勝出。
2. **每日視窗較短**的勝出。愈短代表指定得愈精確，適合用來覆蓋長時段的底圖。
3. **指定天數較少**的勝出。
4. **有日期區間**的勝過沒有日期區間的。
5. **`updatedAt` 較新**的勝出。
6. 以 **`id` 字典序**作為最後的決勝。

最後一條的存在是為了讓結果**永遠是決定性的**。兩筆條件完全相同的排程不會隨機挑一筆——同一組輸入永遠得到同一個答案，不管你把它們用什麼順序傳進來。

實務上的用法：

```text
priority 100  星期一至五 08:00–18:00  一般營業版面
priority 500  星期一至五 12:00–12:30  午間限時活動  ← 勝出
```

## 離線執行

裝置會把**排程清單本身**下載下來，存在 `manifests/` 底下。

```mermaid
flowchart LR
	S["Server"] -->|"desired state 內含<br/>schedule manifest"| D["Device"]
	D --> M[("manifests/active.json")]
	M --> R["每秒重新判定<br/>resolveActiveSchedule()"]
	R --> P["切換版面"]
```

判定完全在本機進行，用的是和 Server 完全相同的 `resolveActiveSchedule()`。因此：

**Server 離線時，裝置依然會照時間切換版面。**

裝置不會在每個時間點去問 Server「現在要播什麼」。那種設計在網路正常時很優雅，網路一斷就整個停擺——而數位看板最常出問題的地方就是網路。

判定是純計算（一次 `Intl.DateTimeFormat` 加幾個字串比較），因此裝置每秒重算一次，切換誤差不超過一秒，成本可以忽略。

---

# 協定

Admin、Server、Worker 與 Device 共用 @huan/protocol 的結構定義。型別只定義一次。

Admin、Server、Worker 與 Device 共用 `@huan/protocol` 的結構定義。**型別只定義一次。**

## API 版本

所有 REST 端點掛在 `/api/v1` 之下：

```ts
import { API_PREFIX, PROTOCOL_VERSION } from "@huan/protocol";
```

`PROTOCOL_VERSION` 是裝置與 Server 之間的通訊協定版本，裝置在 WebSocket handshake 與 heartbeat 中回報，Server 用它判斷相容性。

## 認證

| 對象   | 方式                                                                               |
| ------ | ---------------------------------------------------------------------------------- |
| 瀏覽器 | `Cookie: huan_session=<不透明 token>`（HttpOnly、SameSite=Lax、正式環境加 Secure） |
| 裝置   | `Authorization: Bearer <deviceId>.<secret>`                                        |

## 錯誤

所有錯誤回應共用同一個結構：

```ts
{ code: string, message: string, details?: Record<string, unknown> }
```

`code` 是穩定的機器可讀識別字，`message` 是使用者可讀的繁體中文說明。

常見的 `code`：`unauthorized`、`forbidden`、`not_found`、`validation_failed`、`rate_limited`、`totp_required`、`invalid_credentials`、`conflict`、`asset_in_use`、`asset_unavailable`、`pairing_expired`。

## OpenAPI

規格由 zod 結構**自動產生**，不是人工維護的第二份文件：

| 端點                       | 說明                          |
| -------------------------- | ----------------------------- |
| `GET /api/v1/openapi.json` | 原始規格                      |
| `GET /api/v1/docs`         | 互動式 API 文件（非正式環境） |

因此 API 文件不可能和實作不同步——它們是同一份結構的兩種輸出。

## WebSocket

### 裝置通道 `/api/v1/devices/socket`

Server 送出：

```ts
{
	type: "hello";
	serverTime;
	protocolVersion;
	desiredVersion;
}
{
	type: "desired_state_changed";
	version: number;
}
{
	type: "command";
	commandId: string;
	command: "force_sync" | "restart_player" | "unbind";
}
{
	type: "pong";
	serverTime;
}
```

裝置送出：

```ts
{ type: "ping" }
{ type: "heartbeat"; reported: ReportedState }
{ type: "command_result"; commandId: string; ok: boolean; message?: string }
```

**WebSocket 不傳輸任何素材。** 它只說「有東西變了」，真正的狀態一律回到 REST 取得（[ADR-0001](/huan/dev/adr/0001-websocket-plus-rest)）。

每一個進來的訊框都用結構驗證。不合法的訊框會被丟棄並記錄，**不會拋例外**。

### 後台通道 `/api/v1/admin/socket`

以 session cookie 認證，推播 `device_changed` 與 `media_changed`，讓後台不需要重新整理就能看到裝置上下線與轉檔完成。

## 裝置同步

```mermaid
sequenceDiagram
	participant D as Device
	participant S as Server
	participant R as RustFS

	S-->>D: desired_state_changed(42)
	D->>S: GET /api/v1/device/state
	S-->>D: DesiredState（版面、排程、素材清單與 SHA-256）

	loop 每個需要的素材
		D->>S: GET /api/v1/device/assets/:variantId/url
		S-->>D: 短時效簽章網址
		D->>R: 下載
		D->>D: 驗證 SHA-256
		D->>S: POST /api/v1/device/assets/ack
	end

	D->>D: 全部就緒 → 原子性切換
	D->>S: POST /api/v1/device/heartbeat（reported = 42）
```

簽章網址**不會寫進目標狀態**，因為目標狀態會被快取在裝置本機，而簽章網址只有 15 分鐘的壽命。裝置在需要下載時才即時索取。

## 相容性

- REST 走路徑版本（`/api/v1`）。破壞性的變更會開 `/api/v2`。
- WebSocket 訊息以 `type` 做可辨識聯集，新增訊息類型不會影響舊裝置——它們會驗證失敗並丟棄，而不是崩潰。
- 裝置回報 `appVersion` 與 `protocolVersion`，Server 可以據此拒絕或降級處理過舊的裝置。
- 新增的欄位一律是選填，或帶有預設值。

---

# Docker 部署

Server 端的所有元件都以 Docker 部署。

Server 端的所有元件都以 Docker 部署。

## 元件

`docker/compose.yaml` 定義四個服務：

| 服務       | 說明                                                             |
| ---------- | ---------------------------------------------------------------- |
| `postgres` | PostgreSQL 18。唯一的資料庫，同時也是工作佇列。                  |
| `rustfs`   | S3 相容物件儲存。暫存與派送用。                                  |
| `server`   | Fastify API、WebSocket，同時靜態提供 Admin 的 production build。 |
| `worker`   | FFmpeg 轉檔與素材回收。                                          |

Admin 不需要獨立容器——它是純靜態檔案，由 Server 以 `@fastify/static` 提供，同源也讓 cookie 與 WebSocket 的設定變得單純。

## 步驟

```sh
cp .env.example .env
```

至少要設定：

```sh
POSTGRES_PASSWORD=<一組強密碼>
S3_SECRET_ACCESS_KEY=<另一組強密碼>
DATABASE_URL=postgres://huan:<同上的密碼>@postgres:5432/huan
PUBLIC_URL=https://huan.example.com
CORS_ORIGINS=https://huan.example.com
```

建置並啟動：

```sh
pnpm docker:build
pnpm docker:up
```

建立資料表：

```sh
docker compose -f docker/compose.yaml exec server node apps/server/dist/cli/migrate.js
```

建立第一個管理員：

```sh
docker compose -f docker/compose.yaml exec \
	-e HUAN_ADMIN_PASSWORD='<一組強密碼>' \
	server node apps/server/dist/cli/create-admin.js \
	--email you@example.com --username admin --display-name 管理員
```

:::warning[不要把密碼留在檔案裡]

不要把密碼寫進 `compose.yaml`，也不要 commit 進 repository。上面的指令用的是一次性的環境變數，不會留在容器的設定裡。

:::

確認服務狀態：

```sh
docker compose -f docker/compose.yaml ps
curl -fsS http://localhost:4000/health/ready
```

## 容器設定

每個服務都具備：

- **healthcheck**：`postgres` 用 `pg_isready`，`rustfs` 用它自己的 `/health`，`server` 用 `/health/ready`，`worker` 用它的存活端點。
- **restart policy**：`unless-stopped`。
- **非 root 執行**：`server` 與 `worker` 都以 `node` 使用者執行。
- **具名 volume**：資料庫、物件儲存與轉檔暫存都不寫在 overlay 層。
- **固定版本**：所有映像都指定版本，不使用 `latest`。
- **production build**：容器裡跑的是建置後的產物，不是開發伺服器。

## 反向代理

正式環境請在前面放一層負責 TLS 的反向代理。它必須正確轉發 WebSocket 的 upgrade 請求：

```nginx
location / {
	proxy_pass http://127.0.0.1:4000;
	proxy_http_version 1.1;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection "upgrade";
	proxy_set_header Host $host;
	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Forwarded-Proto $scheme;
}
```

沒有這幾行的話，裝置的 WebSocket 會連不上，系統會退化成每 5 分鐘輪詢一次——功能還在，但更新變慢。

## 擴充轉檔能力

Worker 是無狀態的，可以直接開多份：

```sh
docker compose -f docker/compose.yaml up -d --scale worker=3
```

`FOR UPDATE SKIP LOCKED` 保證每一件工作只會被一個 Worker 取走。

## 備份

需要備份的有兩樣：

**PostgreSQL** —— 這是唯一不可重建的資料。

```sh
docker compose -f docker/compose.yaml exec postgres \
	pg_dump -U huan huan | gzip > huan-$(date +%F).sql.gz
```

**RustFS** —— 依 HUAN 的設計，這裡只有暫存內容：縮圖、預覽，以及還沒被所有裝置取走的播放產物。遺失縮圖不會影響播放，但正在派送中的產物遺失就必須重新上傳素材。

原始檔不在裡面。這是刻意的設計，見 [ADR-0003](/huan/dev/adr/0003-temporary-object-storage)。

## 升級

```sh
git pull
pnpm docker:build
docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml exec server node apps/server/dist/cli/migrate.js
```

Migration 是往前相容的，執行順序是先啟動新版容器再套用 migration。升級期間裝置會繼續播放本機內容，不會受影響。

---

# 環境變數

所有環境變數在啟動時由 @huan/config 以 zod 驗證。缺少或格式錯誤時 Server 與 Worker 會拒絕啟動，並明確指出是哪一個變數有問題——不會帶著錯誤的設定跑起來，然後在某個奇怪的地方失敗。

所有環境變數在啟動時由 `@huan/config` 以 zod 驗證。缺少或格式錯誤時 Server 與 Worker 會**拒絕啟動**，並明確指出是哪一個變數有問題——不會帶著錯誤的設定跑起來，然後在某個奇怪的地方失敗。

完整範例見 repository 根目錄的 `.env.example`。

## 共用

| 變數           | 預設          | 說明                                  |
| -------------- | ------------- | ------------------------------------- |
| `NODE_ENV`     | `development` | `development`、`test` 或 `production` |
| `LOG_LEVEL`    | `info`        | `fatal` 到 `trace`                    |
| `DATABASE_URL` | —             | **必填。** PostgreSQL 連線字串        |

## 物件儲存

| 變數                   | 預設             | 說明                                             |
| ---------------------- | ---------------- | ------------------------------------------------ |
| `S3_ENDPOINT`          | —                | **必填。** Server 與 Worker 連得到的 RustFS 位址 |
| `S3_PUBLIC_ENDPOINT`   | 同 `S3_ENDPOINT` | 瀏覽器與裝置連得到的位址                         |
| `S3_REGION`            | `us-east-1`      | S3 簽章需要，RustFS 不在意實際值                 |
| `S3_BUCKET`            | `huan`           | 儲存桶名稱                                       |
| `S3_ACCESS_KEY_ID`     | —                | **必填。**                                       |
| `S3_SECRET_ACCESS_KEY` | —                | **必填。**                                       |
| `S3_FORCE_PATH_STYLE`  | `true`           | RustFS 需要 path-style 位址                      |

:::tip[為什麼有兩個 endpoint]

Server 簽出來的網址是給**瀏覽器和裝置**用的。Server 在 Docker 網路裡透過 `http://rustfs:9000` 連到儲存，但那個主機名稱在容器外面不存在。兩者不同時就必須分開設定，否則簽出來的網址在外部連不上。

:::

## Server

| 變數                              | 預設                    | 說明                           |
| --------------------------------- | ----------------------- | ------------------------------ |
| `HOST`                            | `0.0.0.0`               | 監聽位址                       |
| `PORT`                            | `4000`                  | 監聽埠                         |
| `PUBLIC_URL`                      | `http://localhost:4000` | 對外網址，用於組出配對連結     |
| `CORS_ORIGINS`                    | `http://localhost:5173` | 逗號分隔的允許來源             |
| `SESSION_COOKIE_NAME`             | `huan_session`          |                                |
| `SESSION_TTL_HOURS`               | `336`（14 天）          |                                |
| `SESSION_COOKIE_SECURE`           | production 為 `true`    | 沒有 TLS 的環境才設為 `false`  |
| `TOTP_ISSUER`                     | `HUAN`                  | 顯示在驗證器 App 裡的名稱      |
| `LOGIN_RATE_LIMIT_MAX`            | `10`                    | 時間窗內允許的失敗次數         |
| `LOGIN_RATE_LIMIT_WINDOW_SECONDS` | `300`                   |                                |
| `SIGNED_URL_TTL_SECONDS`          | `900`                   | 簽章網址有效時間               |
| `DISTRIBUTION_RETENTION_HOURS`    | `24`                    | 全部 ACK 之後播放產物的保留期  |
| `DEVICE_HEARTBEAT_SECONDS`        | `60`                    | 下發給裝置的 heartbeat 間隔    |
| `DEVICE_FALLBACK_SYNC_SECONDS`    | `300`                   | 下發給裝置的保底同步間隔       |
| `DEVICE_MAX_CONCURRENT_DOWNLOADS` | `3`                     | 裝置同時下載的檔案數           |
| `ADMIN_DIST_DIR`                  | —                       | 設定後由 Server 靜態提供 Admin |

### `DISTRIBUTION_RETENTION_HOURS` 值得想一下

這個值決定「所有裝置都下載完成之後，播放產物還要在 RustFS 上留多久」。

| 值           | 效果                                         |
| ------------ | -------------------------------------------- |
| `24`（預設） | 一天內新增裝置還來得及取得素材               |
| `168`        | 一週                                         |
| `720`        | 一個月。實務上幾乎不會遇到需要重新上傳的情況 |

調長只是多花儲存空間；調短則會更快遇到「需要重新上傳」的狀態。詳見 [ADR-0003](/huan/dev/adr/0003-temporary-object-storage)。

## Worker

| 變數                      | 預設         | 說明             |
| ------------------------- | ------------ | ---------------- |
| `WORKER_CONCURRENCY`      | `2`          | 同時處理的工作數 |
| `WORKER_POLL_INTERVAL_MS` | `2000`       | 取件輪詢間隔     |
| `WORKER_JOB_MAX_ATTEMPTS` | `3`          | 最大重試次數     |
| `FFMPEG_PATH`             | `ffmpeg`     |                  |
| `FFPROBE_PATH`            | `ffprobe`    |                  |
| `WORKER_TMP_DIR`          | 系統暫存目錄 | 轉檔暫存位置     |
| `WORKER_HEALTH_PORT`      | `4001`       | 存活檢查端點的埠 |

## Admin（建置期）

| 變數                | 說明                                      |
| ------------------- | ----------------------------------------- |
| `VITE_API_BASE_URL` | 開發時的 API 位址。同源部署時不需要設定。 |

## 文件（建置期）

| 變數               | 說明                                         |
| ------------------ | -------------------------------------------- |
| `DOCS_SITE_ORIGIN` | 站台來源，預設 `https://docs.huan.linyao.tw` |

只影響 `llms.txt` 與各頁 Markdown 裡的絕對連結。GitHub Actions 會從 Pages 設定自動帶入，本機不需要設定。

## 秘密管理

- **不要 commit `.env`。** `.gitignore` 已經排除它。
- 不要把密碼寫進 `compose.yaml`。用 `.env` 或部署平台提供的秘密管理機制。
- 正式環境的 `POSTGRES_PASSWORD` 與 `S3_SECRET_ACCESS_KEY` 要用高熵的隨機字串。
- **原始碼裡沒有任何預設管理員密碼。** 第一個管理員一定要用 CLI 建立。

---

# PostgreSQL

HUAN 只用一個資料庫。它同時是資料儲存與工作佇列。

HUAN 只用一個資料庫。它同時是資料儲存與工作佇列。

## 版本

PostgreSQL 18。`compose.yaml` 使用 `postgres:18.2-alpine`。

需要的功能：

- `gen_random_uuid()`（PostgreSQL 13 起內建於核心，不需要 `pgcrypto` 擴充）
- `jsonb`
- `FOR UPDATE SKIP LOCKED`（9.5 起提供）
- 陣列欄位（`smallint[]` 用於排程的星期設定）

## Schema

Schema 定義在 `packages/db/src/schema.ts`，用 Drizzle 撰寫，migration 由 `drizzle-kit` 產生。

```text
users                  帳號
sessions               瀏覽器登入狀態（只存 token 雜湊）
auth_challenges        通過密碼但還沒完成 2FA 的中繼狀態
totp_credentials       TOTP 密鑰與重放防護
totp_recovery_codes    復原碼雜湊
login_attempts         登入節流

devices                裝置與目標／回報狀態
device_credentials     裝置憑證雜湊
device_pairing_codes   配對碼

media_assets           素材與 ffprobe 中繼資料
media_variants         各種產物與其物件鍵
media_device_sync      每台裝置對每個產物的同步狀態

layouts                版面與草稿
layout_revisions       不可變的發布快照

schedules              排程
schedule_devices       排程與裝置的關聯

worker_jobs            工作佇列
audit_logs             稽核紀錄
```

## Migration

```sh
pnpm db:migrate
```

改動 schema 之後產生新的 migration：

```sh
pnpm --filter @huan/db db:generate
```

**不要手寫 migration SQL，也不要修改已經產生的檔案。** 已套用的 migration 是不可變的歷史。

Migration 檔案跟著 `@huan/db` 一起發布（`package.json` 的 `files` 列了 `migrations`），因此 Docker 映像不需要另外複製 SQL。

## 為什麼工作佇列在資料庫裡

```sql
SELECT * FROM worker_jobs
WHERE status = 'pending' AND run_after <= now()
ORDER BY run_after, created_at
FOR UPDATE SKIP LOCKED
LIMIT 1;
```

`FOR UPDATE SKIP LOCKED` 是 PostgreSQL 為佇列設計的原語。取件的交易鎖住那一列，其他 Worker 直接跳過。

這讓「建立素材紀錄」與「排入轉檔工作」可以在同一個交易裡完成。用外部佇列就變成跨兩個系統的寫入，必須自己處理其中一邊失敗的情況。

完整理由見 [ADR-0007](/huan/dev/adr/0007-postgres-job-queue)。

## 備份

```sh
docker compose -f docker/compose.yaml exec postgres \
	pg_dump -U huan --format=custom huan > huan-$(date +%F).dump
```

還原：

```sh
docker compose -f docker/compose.yaml exec -T postgres \
	pg_restore -U huan -d huan --clean --if-exists < huan-2026-09-06.dump
```

**PostgreSQL 是 HUAN 唯一不可重建的資料。** RustFS 裡只有暫存內容，裝置本機的素材可以重新派送（只要素材還有可用的副本），但帳號、版面、修訂、排程與稽核紀錄一旦遺失就沒有了。

## 維護

`worker_jobs` 與 `login_attempts` 會持續成長。已完成的工作與過期的登入紀錄可以定期清理：

```sql
DELETE FROM worker_jobs
WHERE status IN ('success', 'failed') AND finished_at < now() - interval '30 days';

DELETE FROM login_attempts WHERE created_at < now() - interval '30 days';
```

`audit_logs` **不要自動刪除**——那是稽核紀錄，保留期應該由組織的政策決定。

---

# RustFS

RustFS 是 HUAN 使用的 S3 相容物件儲存。

RustFS 是 HUAN 使用的 S3 相容物件儲存。

## 它不是永久素材庫

:::warning[這一點決定了整個儲存模型]

RustFS 在 HUAN 裡是**暫存與派送**用的，不是資產庫。正式的播放副本最終保存在裝置本機。

:::

它負責五件事：

1. 原始檔的短暫暫存
2. FFmpeg Worker 的輸入與輸出
3. 後台的預覽
4. 縮圖
5. 裝置下載前的暫時派送

完整理由見 [ADR-0003](/huan/dev/adr/0003-temporary-object-storage)。

## 命名空間

| 前綴            | 內容                     | 保留                      |
| --------------- | ------------------------ | ------------------------- |
| `uploads/`      | 使用者上傳的原始檔       | 轉檔成功後刪除            |
| `processing/`   | Worker 的中間產物        | 工作結束即刪除            |
| `thumbnail/`    | 素材庫縮圖               | 長期                      |
| `preview/`      | 後台預覽用的低解析度版本 | 長期                      |
| `distribution/` | 派送到裝置的播放檔       | 全部 ACK 且過保留期後回收 |

## 物件鍵

**物件鍵一律由 UUID 組成，永遠不使用使用者提供的檔名。**

```text
distribution/9f3a7c21-…/4b8e0d13-….mp4
```

副檔名由 content type 推導，不是從上傳的檔名擷取。

一個叫 `../../etc/passwd.mp4` 的上傳檔案不會變成路徑穿越問題，因為那個名字只會被存成中繼資料裡的一個字串。同名檔案也不會互相覆蓋。

## 直傳

大型檔案不經過 Fastify：

```mermaid
sequenceDiagram
	participant B as 瀏覽器
	participant S as Server
	participant R as RustFS

	B->>S: POST /api/v1/media/uploads
	S-->>B: 簽章 PUT 網址與必要標頭
	B->>R: PUT 影片檔（直傳）
	B->>S: POST /api/v1/media/uploads/complete
	S->>R: HeadObject 確認物件真的存在
	S-->>B: 素材已建立，等待轉檔
```

一支 4 GB 的影片如果經過 Node.js 的記憶體，只要幾個人同時上傳就會把 Server 打掛。直傳讓 Server 只處理幾百位元組的中繼資料。

`complete` 步驟會用 `HeadObject` 確認物件真的存在——不能只相信瀏覽器說它上傳成功了。

## 設定

```sh
S3_ENDPOINT=http://rustfs:9000          # Server 與 Worker 用
S3_PUBLIC_ENDPOINT=https://storage.example.com   # 瀏覽器與裝置用
S3_REGION=us-east-1
S3_BUCKET=huan
S3_ACCESS_KEY_ID=…
S3_SECRET_ACCESS_KEY=…
S3_FORCE_PATH_STYLE=true
```

`S3_FORCE_PATH_STYLE` 必須是 `true`。RustFS 使用 path-style 位址（`http://host/bucket/key`），不是 virtual-hosted style（`http://bucket.host/key`）。

儲存桶會在 Server 啟動時自動建立（如果不存在的話）。

## 簽章網址

所有對外的存取都透過短時效的簽章網址，預設 15 分鐘（`SIGNED_URL_TTL_SECONDS`）。

- 網址不會被儲存在資料庫裡，每次讀取時即時產生。
- 網址不會寫進任何日誌——查詢字串本身就是憑證。
- 裝置遇到過期的網址時會重新索取，**不會讓整次同步失敗**。

## 替換成其他 S3 相容儲存

HUAN 用的是標準的 S3 API（`PutObject`、`GetObject`、`HeadObject`、`DeleteObject` 與預簽章網址），因此可以換成 MinIO、Ceph RGW、AWS S3、Cloudflare R2 等等。

只要改 `S3_ENDPOINT`、憑證與 `S3_FORCE_PATH_STYLE`（AWS S3 與 R2 要設為 `false`）。

---

# GitHub Pages

文件站以 Astro 建置成靜態網站，由 GitHub Actions 部署到 GitHub Pages。

文件站以 Astro 建置成靜態網站，由 GitHub Actions 部署到 GitHub Pages。

:::warning[只有文件放在 Pages]

Server、Worker、Admin 與資料庫都用 Docker 部署。GitHub Pages 上只有這份文件。

:::

## 啟用

1. GitHub repository → **Settings** → **Pages**
2. **Source** 選 **GitHub Actions**

這是一次性的手動步驟。workflow 刻意不使用 `configure-pages` 的 `enablement: true` 自動開啟——建立 Pages 站台需要 repository 的管理權限，而 `GITHUB_TOKEN` 沒有，失敗訊息會是一句看不出原因的 `Resource not accessible by integration`。

沒有先完成這一步時，`設定 GitHub Pages` 會停在：

```text
Get Pages site failed. Error: Not Found
```

## Workflow

`.github/workflows/docs.yml` 的流程：

```text
checkout
  ↓
pnpm 與 Node 設定
  ↓
pnpm install --frozen-lockfile
  ↓
pnpm build:packages
  ↓
configure-pages（取得 origin）
  ↓
pnpm docs:build
  ↓
upload-pages-artifact
  ↓
deploy-pages
```

## 網域與 base

HUAN 的文件站部署在 <https://docs.huan.linyao.tw>，服務在**根路徑**，因此 `base` 固定是 `/`，設定檔裡沒有任何子路徑的處理。

自訂網域在 **Settings → Pages → Custom domain** 設定即可，**不需要**在 `public/` 放 `CNAME` 檔案——用 GitHub Actions 部署時，網域設定存在 repository 的 Pages 設定裡，不是從產物讀出來的。

:::warning[記得打開 Enforce HTTPS]

這不只是安全性問題。`configure-pages` 回報的 `origin` 會跟著這個設定變動，而那個值會寫進 `llms.txt` 與各頁 Markdown 的**絕對連結**。沒打開的話，AI 工具拿到的會是一整份 `http://` 連結。

:::

```sh
gh api repos/<owner>/<repo>/pages | jq '{cname, https_enforced, html_url}'
```

`site` 由 workflow 從 `configure-pages` 的輸出帶入，只有它會影響絕對連結；fork 出去換網域時覆寫 `DOCS_SITE_ORIGIN` 即可，設定檔裡不需要動。

## AI 可讀的輸出

`src/pages/` 底下有三個端點，在建置時一起輸出：

| 檔案            | 產生者             | 內容                       |
| --------------- | ------------------ | -------------------------- |
| `llms.txt`      | `llms.txt.ts`      | 全站結構化索引             |
| `llms-full.txt` | `llms-full.txt.ts` | 全站內容的單一 Markdown 檔 |
| `<route>.md`    | `[...slug].md.ts`  | 每一頁的 Markdown 版本     |

順序跟著 `src/lib/navigation.ts` 的側欄走，因此索引的結構和讀者看到的目錄一致。

這讓 AI 工具不必解析 HTML 就能讀懂整份文件。`site` 設定正確時，這些檔案裡的連結才會指向真實可存取的網址——這也是為什麼它必須由 workflow 帶入。

## 本機預覽

```sh
pnpm docs:dev                      # 開發伺服器（搜尋不可用，索引要建置後才有）
pnpm docs:build                    # SSG 建置到 apps/docs/dist，並產生 Pagefind 索引
pnpm --filter @huan/docs preview   # 預覽建置結果
```

本機建置出來的絕對連結會指向正式網域。要換成別的網域：

```sh
DOCS_SITE_ORIGIN=https://docs.example.com pnpm docs:build
```

---

# 發布

三個東西各自有版本：

## 版本

三個東西各自有版本：

| 對象                  | 版本來源                               |
| --------------------- | -------------------------------------- |
| Server 與 Worker 映像 | `compose.yaml` 的 `HUAN_VERSION`       |
| Device 應用程式       | `apps/device/package.json`             |
| 協定                  | `@huan/protocol` 的 `PROTOCOL_VERSION` |

裝置在 heartbeat 中同時回報 `appVersion` 與 `protocolVersion`，因此後台可以看到現場有哪些版本，Server 也能據此判斷相容性。

## Server 端

```sh
git pull
pnpm docker:build
docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml exec server node apps/server/dist/cli/migrate.js
```

升級期間裝置會繼續播放本機內容。Server 短暫不可用不會造成黑畫面——這是離線優先設計的直接好處。

## Device 端

`.github/workflows/device-release.yml` 在推送 `device-v*` 標籤時觸發：

```sh
git tag device-v0.2.0
git push origin device-v0.2.0
```

Workflow 會在三種 runner 上分別打包：

| Runner           | 產出                       |
| ---------------- | -------------------------- |
| `ubuntu-latest`  | Linux x64、Linux ARM64     |
| `windows-latest` | Windows x64、Windows ARM64 |
| `macos-latest`   | macOS x64、macOS ARM64     |

產物命名遵循固定格式：

```text
HUAN-Device-<version>-linux-arm64.AppImage
HUAN-Device-<version>-win-x64.exe
HUAN-Device-<version>-darwin-arm64.dmg
```

Raspberry Pi 使用 **Linux ARM64** 的版本。

## 簽章

Workflow 預設關閉自動尋找簽章憑證（`CSC_IDENTITY_AUTO_DISCOVERY: false`），讓沒有設定憑證時的失敗原因是明確的「沒有憑證」，而不是難懂的簽章錯誤。

要啟用簽章的話，把憑證放進 repository secrets 並在 workflow 中引用。macOS 的公證另外需要 Apple ID 與 app-specific password。

## 文件

`.github/workflows/docs.yml` 在 `apps/docs/**` 或 `packages/**` 有變動時自動部署到 GitHub Pages。

截圖不是在 CI 產生的——它們需要一整套跑起來的環境。截圖由開發者在本機執行 `pnpm docs:screenshots` 後 commit 進 repository。

## 發布前檢查

```sh
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm docs:build
pnpm test:e2e

docker compose -f docker/compose.yaml build
docker compose -f docker/compose.yaml up -d
curl -fsS http://localhost:4000/health/ready
```

CI 會跑完上面全部，但在推標籤之前自己跑一次比較快發現問題。

---

# 架構決策紀錄

這裡記錄 HUAN 幾個影響全域的決定，以及做這些決定的理由。

這裡記錄 HUAN 幾個影響全域的決定，以及做這些決定的理由。

寫下來的目的不是儀式，而是讓幾個月後（或換一批人之後）想改動這些地方的人，先知道當初為什麼不那樣做。

| 編號                                                    | 決策                                         |
| ------------------------------------------------------- | -------------------------------------------- |
| [ADR-0001](/huan/dev/adr/0001-websocket-plus-rest)      | WebSocket 只送通知，REST 才是事實來源        |
| [ADR-0002](/huan/dev/adr/0002-desired-reported-state)   | 用 desired / reported state 而不是命令式 RPC |
| [ADR-0003](/huan/dev/adr/0003-temporary-object-storage) | 物件儲存只做暫存，不當永久素材庫             |
| [ADR-0004](/huan/dev/adr/0004-recursive-split-layout)   | 版面使用遞迴分割樹而不是絕對定位             |
| [ADR-0005](/huan/dev/adr/0005-local-first-playback)     | 本機優先播放                                 |
| [ADR-0006](/huan/dev/adr/0006-electron)                 | 播放器使用 Electron                          |
| [ADR-0007](/huan/dev/adr/0007-postgres-job-queue)       | 工作佇列用 PostgreSQL，不引入 Redis          |

---

# ADR-0001：WebSocket 只送通知，REST 才是事實來源

已採用

## 狀態

已採用

## 背景

裝置需要知道內容什麼時候變了。可行的做法有幾種：

1. 每隔幾秒完整拉一次狀態。
2. 用 WebSocket 把完整的狀態推給裝置。
3. 用 WebSocket 推「有東西變了」，裝置再自己去拉。

## 決策

採用第三種。WebSocket 只傳這種訊息：

```json
{ "type": "desired_state_changed", "version": 42 }
```

裝置收到後打 `GET /api/v1/device/state` 取得完整內容。**REST API 是唯一的事實來源。**

同時保留每 5 分鐘一次的保底同步，不完全依賴 WebSocket。

## 理由

**輪詢太浪費。** 一百台裝置每 10 秒拉一次，就是每秒十次全量查詢，而其中九成九的回應完全相同。

**推完整狀態會有一致性問題。** 推播是「射後不理」的：訊息在傳輸中遺失、裝置剛好在重連、或者兩次推播的順序顛倒，裝置就會停在一個錯誤的狀態，而且沒有人知道。要修這個問題就得加上確認、序號與重送——等於在 WebSocket 之上重新實作一次 TCP。

**通知加拉取沒有這個問題。** 通知遺失最壞的結果是延遲，因為保底同步一定會補上。順序顛倒也沒關係，因為裝置拉到的永遠是當下最新的完整狀態。裝置重連後只要拉一次就同步了，不需要重播任何訊息。

保底同步不是備援設計上的懶惰，而是承認長連線本來就會斷、會被中間設備靜默丟棄、會遇到 NAT 逾時。

## 後果

- 一次變更會產生一次推播加一次 REST 請求，比純推播多一趟往返。對於「幾分鐘才變一次」的數位看板，這完全不是問題。
- WebSocket 完全掛掉時，系統會退化成 5 分鐘輪詢一次，功能不受影響，只是變慢。
- 訊息很小，因此 WebSocket 連線本身的成本很低。

## 替代方案

**Server-Sent Events**：單向、比 WebSocket 簡單。但裝置的 heartbeat 需要往上傳，只用 SSE 就得再開一條 HTTP 通道。WebSocket 一條連線兩個方向，反而更單純。

**長輪詢**：可行，但每次逾時都要重建連線，在幾百台裝置的規模下會產生大量無謂的連線。

---

# ADR-0002：用 desired / reported state 而不是命令式 RPC

已採用

## 狀態

已採用

## 背景

Server 需要讓裝置播放特定的內容。最直覺的做法是下命令：「下載這個檔案」、「切換到那個版面」、「重新啟動播放器」。

## 決策

Server 不下命令，而是宣告一個目標狀態：

```json
{ "version": 42, "defaultLayout": { … }, "schedules": [ … ], "assets": [ … ] }
```

裝置回報現況，並自己負責把差距補上。少數真正屬於「動作」的操作（強制同步、重新啟動播放器）才用命令表達。

## 理由

**命令式的模型必須記住每一條命令的狀態。** 裝置在下載到一半時斷電，Server 怎麼知道？它得記錄命令送出、命令確認、命令失敗、命令重送——這就是在資料庫裡重新發明一套不可靠的工作流程引擎，而且每加一種操作就要多一套狀態。

**宣告式的模型沒有中間狀態要記。** 裝置重新開機後只做一件事：比較目標與現況，把差距補上。中間斷過幾次、重試過幾輪、命令有沒有送到，都不影響最終結果。這是冪等的。

**除錯也容易得多。** 「這台裝置為什麼播錯東西」在命令式模型下要去翻命令歷史，在宣告式模型下只要比對兩個 JSON。

這個模式在基礎設施領域已經被驗證很久了——Kubernetes 的控制器、Terraform 的計畫執行、各種設定管理工具，用的都是同一個想法。

## 後果

- 裝置端的邏輯比較複雜：它必須自己算出差異、排下載順序、處理部分失敗。這個複雜度集中在 `@huan/device-core` 的調和器裡，而且是可以單獨測試的。
- Server 端變得很單純：算出目標、寫進資料庫、發一個通知。
- 版本號必須只在內容真的改變時才遞增。否則改一個不相干的排程就會讓所有裝置誤以為自己落後，然後同時來要狀態。

## 替代方案

**純命令式 RPC**：如上所述，需要在 Server 端維護一套可靠的命令狀態機。

**混合模型**：內容用宣告式、動作用命令式。這其實就是最終採用的做法——`force_sync`、`restart_player` 與 `unbind` 是命令，因為它們本來就是動作而不是狀態。

---

# ADR-0003：物件儲存只做暫存，不當永久素材庫

已採用

## 狀態

已採用

## 背景

上傳的影片與圖片要放在哪裡？最常見的答案是「放在物件儲存裡，永遠留著」。

## 決策

RustFS 只做暫存與派送：

- 原始檔在轉檔成功後**立即刪除**。
- 縮圖與預覽長期保留（它們很小）。
- 播放產物在所有目標裝置都 ACK 且經過保留期後**回收**。
- 正式的播放副本最終保存在**裝置本機**。

當某個素材已經沒有任何可派送的副本時，把它標記為 `NEEDS_REUPLOAD` 並在介面上誠實顯示。

## 理由

**原始檔在系統裡沒有讀者。** 一支 4K 原始影片可能有 8 GB，轉檔後的播放版本只有 200 MB。播放用轉檔版、預覽用預覽版、縮圖用縮圖——沒有任何功能會去讀那 8 GB 的原始檔。留著它只是讓儲存成本隨上傳量線性成長。

**播放副本已經在裝置上了。** 素材的用途就是被裝置播放。所有目標裝置都下載完成並驗證通過之後，RustFS 上那份副本就沒有讀者了。

**這是一個產品定位的決定。** HUAN 是播放系統，不是數位資產管理系統。想要保存原始母帶的人應該用 DAM，而不是期待看板系統替他做備份。

## 後果

這個決定有一個**真實的、使用者會遇到的代價**：

原始檔已刪除、播放產物也已回收之後，如果你新增一台裝置，或某台裝置清掉了本機儲存，這份素材就無法重新派送，必須重新上傳。

我們選擇正面處理這件事：

- 資料模型本身能表達這個狀態（`media_variants.available`）。
- 後台會明確顯示「需要重新上傳」，並解釋原因。
- 文件在多個地方說明這個限制。
- 保留期可以透過 `DISTRIBUTION_RETENTION_HOURS` 調整，設成 720 就等於一個月內都能重新派送。

**不會做的事**：假裝伺服器還留著不存在的檔案，然後在派送的時候才失敗。

回收前的兩道保護也很重要：必須所有目標裝置都 ACK（不能第一台成功就刪），而且必須經過保留期（吸收 ACK 與重試之間的競態）。

## 替代方案

**永久保留原始檔**：儲存成本無上限地成長，而且那些檔案沒有讀者。

**永久保留播放產物**：比保留原始檔便宜得多，也確實避免了重新上傳的問題。這是最值得未來重新評估的選項——只要把 `DISTRIBUTION_RETENTION_HOURS` 設得夠大，實務上就等於這個方案。目前的預設值選擇了成本，而不是便利。

---

# ADR-0004：版面使用遞迴分割樹而不是絕對定位

已採用

## 狀態

已採用

## 背景

版面編輯器的資料模型有兩種常見選擇：

1. **絕對定位**：每個元素有 x、y、寬、高，可以自由拖曳與重疊。
2. **遞迴分割**：任何區塊都可以被切成兩塊，切出來的每一塊又可以繼續切。

## 決策

核心資料模型使用遞迴分割樹，比例而非像素。

```ts
type LayoutNode = { type: "split"; direction: "horizontal" | "vertical"; ratio: number; first: LayoutNode; second: LayoutNode } | { type: "slot"; content: SlotContent | null };
```

## 理由

**自由拖曳會產生無效的版面。** 元素重疊、留下無法解釋的空隙、超出畫布邊界——這些狀態在絕對定位模型裡全都是合法的，然後在現場的螢幕上變成一團混亂。分割樹在結構上就不可能產生重疊或空隙。

**RWD 只有在比例模型下才成立。** 存「左邊 1344px」的版面換一台螢幕就歪了；存「左邊 0.7」的版面在任何尺寸都是 70%。這對一個明確要支援 1080p、4K 與直式螢幕的產品是必要條件。

**幾何可以完整測試。** 分割樹的算繪是一個純函式：輸入樹與畫布尺寸，輸出每一塊的矩形。這讓「後台看到的和裝置播出來的一模一樣」變成可以用單元測試斷言的事，而不是靠人眼比對。

**操作也比較好懂。** 「把這一塊切成上下兩半」比「把這個框拖到那個座標，然後對齊」更容易做對，尤其是在需要鍵盤操作的無障礙情境下。

## 後果

- 做不出重疊的元素（例如浮在影片上的半透明字幕列）。這在數位看板的使用情境裡不常見，而且可以用未來的「圖層」機制補上，不需要放棄分割樹。
- 比例需要下限與上限（0.05 到 0.95）。沒有限制，使用者一不小心就會拖出 0.001 / 0.999 這種再也點不回來的版面。
- 刪除區塊實際上是「移除它的父分割」——兄弟節點會頂上來。直接刪掉插槽會留下只有一個孩子的分割節點，那種樹沒有幾何意義。

## 替代方案

**CSS Grid 風格的網格**：比自由拖曳結構化，但要表達巢狀的不對稱切分（左邊 70%，右邊再上下對切）就得引入複雜的跨列跨行語法。分割樹用兩層節點就表達完了。

**自由拖曳加上吸附輔助**：改善了體驗，但沒有解決根本問題——資料模型仍然允許無效狀態。

---

# ADR-0005：本機優先播放

已採用

## 狀態

已採用

## 背景

播放裝置要怎麼取得要播的影片？

1. 從伺服器串流。
2. 先下載到本機再播放。

## 決策

**素材必須先完整下載到裝置本機並通過 SHA-256 驗證，才會播放。** 正常播放時裝置不會去讀 RustFS。

新版本的切換是原子的：所有檔案就緒之後才切換，任何一個失敗就留在舊版本。

## 理由

**現場網路是整套系統裡最不可靠的一環。** 看板裝在賣場後場、電梯口、展場角落，用的是延伸出去的 Wi-Fi 或別人插著的網路線。串流播放意味著網路一抖畫面就卡，網路一斷就是黑畫面。

**黑畫面是這個產品最嚴重的失效模式。** 一面看板的價值就是它一直亮著。客戶不會知道是網路的問題，他們只會看到自己花錢買的螢幕變成一塊黑板。

**先下載讓失敗變得無害。** 網路斷了，裝置照播現有內容；新版本下載失敗，裝置照播舊版本。網路問題從「立刻可見的故障」降級成「延遲更新」。

**原子切換避免了半新半舊的狀態。** 如果邊下載邊切換，使用者會看到左邊已經是新影片、右邊還是舊圖片。全部就緒才切換讓每一次更新都是一次乾淨的轉換。

## 後果

- 裝置需要足夠的本機儲存空間。這帶來了儲存管理的需求：空間門檻檢查、垃圾回收，以及空間不足時向後台回報。
- 更新有延遲。發布之後裝置要先下載完才會顯示，一支大影片可能要幾分鐘。這對數位看板完全可以接受。
- **絕對不能先刪舊版本再下載新版本。** 舊版本的檔案要等新版本成功啟用並經過保留期之後才回收。
- 垃圾回收永遠不能刪除目前啟用版本的素材、下一個排程版本需要的素材，或正在下載的檔案。

## 替代方案

**串流播放**：實作簡單、不需要本機儲存，但完全不能接受黑畫面的風險。

**串流加上本機快取**：看起來兩全其美，實際上是最糟的組合——首播仍然依賴網路，而且要同時維護串流與快取兩套邏輯，失效模式比任何一種單獨的做法都多。

---

# ADR-0006：播放器使用 Electron

已採用

## 狀態

已採用

## 背景

播放器必須在 Raspberry Pi OS（arm64）、Ubuntu（x64 與 arm64）、Windows（x64 與 arm64）與 macOS（x64 與 arm64）上執行，而且要能播放影片、圖片、文字、跑馬燈、iframe 與上傳的 HTML。

## 決策

使用 Electron，React 負責算繪行程。

## 理由

**要播的內容本來就是網頁內容。** 影片、圖片、文字排版、CSS 動畫、iframe、HTML——這些全都是瀏覽器原生就會做的事。用原生 UI 框架重做一次等於重寫一個排版引擎。

**版面引擎可以和後台共用。** `@huan/layout-engine` 同一份程式碼跑在 Admin 的預覽與 Device 的播放器上，這是「後台看到什麼、現場就播什麼」的保證。換一個非網頁的算繪技術就得維護兩套幾何實作，而它們一定會漂移。

**上傳的 HTML 需要一個真的瀏覽器。** 而且需要一個可以嚴格 sandbox 的瀏覽器。Electron 的 `sandbox: true` 加上巢狀 iframe 提供了這個能力。

**跨平台打包是解決過的問題。** electron-builder 直接支援上面列的六個平台架構組合。

## 後果

- 記憶體用量比原生播放器高。Raspberry Pi 4 的最低建議配置因此是 2GB，實際建議 4GB。
- 應用程式體積較大（每個平台大約一百多 MB）。看板裝置一次安裝之後很少更新，這是可以接受的。
- 必須嚴格遵守 Electron 的安全模型。`nodeIntegration: false`、`contextIsolation: true`、`sandbox: true` 不會為了任何功能而放寬，preload 只暴露最小介面。
- 要盡量避免原生 Node 模組。每一個原生相依都會讓六個平台架構的打包變得更困難，因此優先選擇純 JS 或 Web API 的方案。

## 替代方案

**Chromium kiosk 模式加一個小服務**：更輕量，但排程、下載、狀態管理都得另外寫一個常駐程序，而且和瀏覽器之間的溝通要自己設計。等於用兩個行程做 Electron 一個行程做的事。

**原生應用程式（Qt、Flutter）**：記憶體用量低很多，但要自己實作 HTML 內容的算繪與 sandbox，而且無法與後台共用版面引擎。

**libmpv 加自製排版**：影片播放效能最好，但文字、跑馬燈、HTML 與 iframe 全都要重做。

---

# ADR-0007：工作佇列用 PostgreSQL，不引入 Redis

已採用

## 狀態

已採用

## 背景

FFmpeg 轉檔必須離開 Fastify 的行程，因此需要一個工作佇列。業界的預設答案通常是 Redis 加上 BullMQ 之類的函式庫。

## 決策

工作佇列就是 PostgreSQL 的一張表，用 `SELECT ... FOR UPDATE SKIP LOCKED` 取件。

**這個 MVP 不引入 Redis。**

## 理由

**`FOR UPDATE SKIP LOCKED` 就是為這件事設計的。** 它是 PostgreSQL 內建的佇列原語：取件的交易鎖住那一列，其他工作者直接跳過去拿下一件。不需要輪詢衝突，也不需要分散式鎖。

**工作量級完全不需要 Redis。** 這是數位看板系統，不是影片平台。一天可能有幾十次上傳，尖峰也就是幾百件工作。PostgreSQL 在這個量級下連暖身都算不上。

**少一個要維運的東西。** 加上 Redis 就要多一個容器、多一組健康檢查、多一份備份策略、多一個會壞掉的地方。而且 Redis 預設不持久化——工作佇列放在會遺失的儲存裡，需要額外的設計才能保證不掉件。

**交易一致性是免費的。** 「建立素材紀錄」與「排入轉檔工作」在同一個交易裡完成。用 Redis 就是跨兩個系統的寫入，必須自己處理其中一邊失敗的情況。

**Server 只需要一個外部相依。** 這對想自架的客戶是很實際的差別。

## 後果

- 取件是輪詢的（預設每 2 秒），不是即時推播。對於本來就要跑好幾分鐘的轉檔工作，兩秒的延遲毫無意義。
- 工作表會成長，需要定期清理已完成的紀錄。
- 高頻率的短工作會在資料庫上產生可觀的負載。如果未來出現那種工作型態，這個決定就該重新評估。

## 何時該重新評估

- 工作量進入每秒數百件的等級。
- 出現需要毫秒級延遲的工作型態。
- 資料庫的佇列查詢在監控上開始成為熱點。

在那之前，多一個中介軟體只會增加維運負擔，換不到任何實際的好處。

## 替代方案

**Redis 加 BullMQ**：功能完整，但引入了一個新的有狀態元件，而且需要額外設計才能保證不掉件。

**RabbitMQ / Kafka**：這個規模下完全是過度設計。

**在 Fastify 裡直接跑**：轉檔期間 API 完全沒有回應，而且無法獨立擴充轉檔能力。

---

# 疑難排解

面向架設與開發的問題。使用者端的問題見使用教學的疑難排解。

面向架設與開發的問題。使用者端的問題見[使用教學的疑難排解](/huan/guide/troubleshooting)。

## 安裝與啟動

### `pnpm dev` 說找不到 `@huan/protocol`

`apps/*` 依賴共用套件的建置產物。先執行：

```sh
pnpm build:packages
```

`pnpm dev`、`pnpm test` 與 `pnpm typecheck` 都會自動先做這一步，直接執行 `pnpm --filter @huan/server dev` 則不會。

### `pnpm dev` 報 `EADDRINUSE: port 4000`

`pnpm docker:up` 會啟動 `server` 容器，它同樣佔用 4000 埠。兩者只能擇一：

```sh
docker compose -f docker/compose.yaml stop server worker
pnpm dev
```

只需要資料庫與物件儲存時，啟動這兩個服務就好：

```sh
docker compose -f docker/compose.yaml up -d postgres rustfs
```

### `pnpm install` 被擋下來

repository 只接受 pnpm。`npm install` 或 `yarn` 會被 `preinstall` 腳本拒絕。

```sh
corepack enable pnpm
```

### Server 啟動時報環境變數錯誤

`@huan/config` 會在啟動時驗證所有環境變數，並明確指出哪一個有問題。對照 `.env.example` 補齊，特別是 `DATABASE_URL`、`S3_ENDPOINT`、`S3_ACCESS_KEY_ID` 與 `S3_SECRET_ACCESS_KEY`。

## 資料庫

### `pnpm db:migrate` 連不上

確認容器已經起來且通過健康檢查：

```sh
docker compose -f docker/compose.yaml ps
```

`.env` 裡 `DATABASE_URL` 的密碼必須和 `POSTGRES_PASSWORD` 一致。改過密碼之後舊的 volume 仍然保留著舊密碼，需要重建：

```sh
docker compose -f docker/compose.yaml down -v
pnpm docker:up
pnpm db:migrate
```

:::danger[這會刪掉資料]

`down -v` 會刪除資料庫的具名 volume。正式環境不要這樣做。

:::

### PostgreSQL 容器啟動後立刻重啟

日誌裡會看到：

```text
Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" ...
       there appears to be PostgreSQL data in:
         /var/lib/postgresql/data (unused mount/volume)
```

PostgreSQL 18 起，官方映像把資料放進帶主版本號的子目錄，掛載點必須是 `/var/lib/postgresql`，不是它底下的 `data`。`compose.yaml` 已經是正確的設定；如果你從舊版升級，volume 裡還是舊的目錄結構，需要用 `pg_upgrade` 或倒出重灌。

## 轉檔

### 工作卡在 pending

檢查 Worker 是不是在跑：

```sh
docker compose -f docker/compose.yaml logs -f worker
```

本機開發時 Worker 需要系統上有 FFmpeg。`ffmpeg -version` 應該要有輸出。

### 想看轉檔失敗的完整原因

後台顯示的是給使用者看的訊息，完整的 FFmpeg 輸出只留在 Worker 的日誌裡：

```sh
docker compose -f docker/compose.yaml logs worker | grep <assetId>
```

這是刻意的：完整指令與檔案系統路徑對一般使用者沒有幫助，而且會洩漏伺服器的內部結構。

### 瀏覽器直傳物件儲存失敗

Server 簽出來的網址是給**瀏覽器**用的。如果 Server 在 Docker 內部而瀏覽器在外面，`S3_ENDPOINT`（內部位址）與 `S3_PUBLIC_ENDPOINT`（外部位址）必須分開設定：

```sh
S3_ENDPOINT=http://rustfs:9000
S3_PUBLIC_ENDPOINT=https://storage.example.com
```

## 測試

### `pnpm test:e2e` 找不到資料

端對端測試會自己執行種子（`globalSetup`），並由 Playwright 的 `webServer` 帶起 Server 與 Admin，所以通常只要 `pnpm docker:up` 之後直接跑就好。

要改測 Docker 直接提供的 Admin：

```sh
HUAN_E2E_NO_WEB_SERVER=true HUAN_E2E_BASE_URL=http://localhost:4000 pnpm test:e2e
```

### 端對端測試出現 429

`/auth/*` 有速率限制，這是產品該有的行為。測試已經改成整份只登入兩次並共用 cookie；如果你新增的測試每個都自己登入，就會撞到這個限制。請改用 `storageState`。

### Server 與 Worker 的測試互相干擾

兩者共用同一個資料庫，而 Server 的整合測試會清空資料表。`pnpm test` 已經設成逐一執行 workspace（`--workspace-concurrency=1`），不要改成平行。

## 部署

### 登入之後馬上被登出

正式環境的 session cookie 帶有 `Secure`，只會在 HTTPS 下送出。如果反向代理還沒有接上 TLS，暫時設定：

```sh
SESSION_COOKIE_SECURE=false
```

正式上線前務必改回來。

### 後台載得起來但 API 全部失敗

`CORS_ORIGINS` 必須包含瀏覽器實際使用的來源。由 Server 直接靜態提供 Admin 時兩者同源，不會有這個問題。

### 裝置連得上 REST 但 WebSocket 一直重連

反向代理沒有轉發 upgrade 請求。見 [Docker 部署](/huan/dev/deploy/docker#反向代理)的 nginx 範例。

少了它系統會退化成每 5 分鐘輪詢一次——功能還在，只是更新變慢。

### `/health/ready` 回 503

readiness 檢查的是 PostgreSQL。看 Server 日誌確認連線錯誤的原因。

RustFS 刻意不列入 readiness——物件儲存暫時不可用時，後台與裝置的目標狀態仍然可以運作，裝置也能繼續播放本機內容。

### 文件部署失敗：`Get Pages site failed: Not Found`

repository 還沒在 **Settings → Pages** 把 Source 設成 GitHub Actions。這是一次性的手動步驟，詳見 [GitHub Pages](/huan/dev/deploy/github-pages)。

---

# 開始使用

安裝 @linyao.tw/ui、載入樣式、設定語系與主題。

`@linyao.tw/ui` 是麟曜數位工作室的 React 元件與設計規範套件。所有產品的介面都由它提供，不再另外引入第二套元件庫。

## 安裝

```sh
pnpm add @linyao.tw/ui
```

peer dependency 需要一起裝：

```sh
pnpm add react react-dom @phosphor-icons/react
```

| 套件                    | 版本    |
| ----------------------- | ------- |
| `react`                 | ^19.0.0 |
| `react-dom`             | ^19.0.0 |
| `@phosphor-icons/react` | ^2.1.10 |

## 載入樣式

在應用程式入口匯入一次：

```tsx
import "@linyao.tw/ui/fonts.css"; // 選用，品牌字型
import "@linyao.tw/ui/styles.css"; // 必要
```

公開的樣式入口只有這兩個。

:::danger[不要從 dist 或 src 匯入]

`@linyao.tw/ui/dist/**`、`src/**` 與任何內部 CSS 路徑都不是公開介面，版本升級時會無預警改變。

:::

`styles.css` 不載入任何遠端資源，因此離線環境與封閉網路都能正常顯示。字型是獨立的可選入口，不需要品牌字型時不必付出那份下載成本。

詳細說明見[主題](/ui/theming)。

## 設定 Provider

`LinyaoProvider` 一次設定語系、翻譯與書寫方向，包在應用程式最外層：

```tsx
import { LinyaoProvider } from "@linyao.tw/ui";

export function AppProviders({ children }: { children: React.ReactNode }) {
	return <LinyaoProvider locale="zh-TW">{children}</LinyaoProvider>;
}
```

內建 `zh-TW` 與 `en-US` 兩組訊息。要自訂個別字串時用 `MessagesProvider`，細節見[元件](/ui/components)的在地化一節。

## 切換主題

主題由根元素的 `data-lyds-theme` 屬性決定：

```ts
document.documentElement.setAttribute("data-lyds-theme", "dark");
```

亮色與深色共用同一份元件 CSS，切換時只有語意變數被重新指定，不需要重新載入樣式表，也不需要重新掛載元件。

:::warning[首次繪製會閃一下]

主題如果等到 React 掛載才設定，使用者會先看到預設主題再跳成實際主題。把讀取偏好與設定屬性的那幾行放進 `<head>` 的同步 script 就不會閃。

:::

完整做法見[主題](/ui/theming)。

## 使用元件

```tsx
import { Button, TextField } from "@linyao.tw/ui";

export function LoginForm() {
	return (
		<form>
			<TextField label="電子郵件" type="email" required />
			<Button type="submit">登入</Button>
		</form>
	);
}
```

所有元件都從套件根匯入，沒有深層路徑。完整清單見[元件](/ui/components)。

## 設計規範

寫介面之前建議先讀這兩份：

- [設計原則](/ui/design-principles)：元件結構、色彩、字體與互動的依據。
- [設計變數](/ui/tokens)：可以用哪些變數，以及什麼時候該用語意角色而不是色盤。

顏色、間距、圓角與字級一律使用套件提供的設計變數，不要寫死色碼或 px。套件沒有提供的版面容器可以自己寫 CSS，但值必須取自設計變數。

---

# 設計原則

元件結構、色彩、字體、圖示與互動的依據。

Linyao Design System 的元件結構、尺寸、`variant` 與互動狀態以 Modulor Figma 可驗證的設計為依據。主要差異是麟曜數位工作室的色盤、字體，以及 Web 與 WCAG 2.2 AA 所需的狀態。Figma 未提供的元件使用相同的表面、圓角、字級、間距與狀態規則。

## Modulor 依據

研究來源是公開 Figma 檔案「❖ Modulor・Components (Community)」。`1277:150465` 是 **Start Here** 畫布，不是單一元件。實作時先依階層定位 Glossary、可見範例、元件集、variants 與 variables，再檢查個別元件的設計內容；截圖只用於交叉檢查。

| 範圍                    | Figma nodes                             | 採用規格                                                                 |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| Glossary／結構          | `26014:40556`, `1277:150465`            | 元件分類、組合規則、公開頁面邊界                                         |
| Button regular          | `16469:37879`–`16469:37882`             | 高 `3.5rem`、圓角 `0.75rem`、16/20 semibold、無邊框與陰影                |
| Checkbox／Radio／Switch | `204:69822`                             | 12 種狀態；24px 控制項；52×30px switch 與 28px knob                      |
| Segmented control       | `234:61252`, `224:61156`                | 2–6 個選項、medium／small、共用表面與選取底板                            |
| Tabs                    | `9457:23922`, `1009:124555`             | 2rem 內容寬度項目、0.25rem 間距、active quaternary surface、無軌道或底線 |
| Text fields             | `132:59432`, `709:93524`, `740:98259`   | 56px 欄位、12px 圓角、1px 外框、浮動標籤與錯誤結構                       |
| Code／Phone fields      | `9297:23908`, `10703:28303`             | 56px 分段欄位、8px 間距、電話國家區段寬度                                |
| List／Section heading   | `9457:29047`–`9457:29056`               | 56px 列、內縮 0.5px 分隔線；32px 大寫區段標題                            |
| Bottom Sheet            | `9457:26270`, `2589:10397`–`2589:10405` | 表面、把手、導覽、固定操作區、分隔線與行動裝置安全區域                   |

已驗證的 Modulor 命名包含 `Background/Main`、`Background/Secondary`、`Text/Title`、`Text/Body`、`Icon/Main`、`Divider/Main`、`Control/Primary`、`Control/Secondary`、`Control/Quaternary`、switch 狀態角色與 `Radius/md`。Linyao Design System 依類別／角色／狀態建立固定的 CSS 變數名稱，元件不直接使用實體色票。

Figma MCP 無法直接讀取未放在可見畫布的隱藏母元件。Button low 沒有可驗證範例，因此不宣稱是 1:1 複刻。深色主題、Web hover／焦點狀態與 Figma 未提供的元件依已驗證規則延伸，並另外進行可存取性與瀏覽器驗證。

## 元件結構

### 元件分類

Checkbox、Radio、Switch 共用選取規則；SegmentedControl 由等寬項目組成；Tabs 使用依內容寬度排列的項目。浮層元件由 Root、Trigger、Portal、Backdrop、Popup、Title、Description 與 Close 等 parts 組合。

### 元件狀態

每個互動元件按適用情況檢查預設、hover、按下、`focus-visible`、選取／勾選、開啟、停用、唯讀、載入與無效狀態。Storybook 顯示實際狀態；測試驗證鍵盤、焦點、開關與受控／非受控行為。

### 語意變數

元件 CSS 使用 `--text-main`、`--control-primary-hover`、`--divider-main`，不使用色名或元件內部十六進位色碼。同一元件可在亮色、深色與使用者自訂主題中維持相同角色。

### 表面與尺寸

使用下列規格：

- main、secondary、elevated 與 quaternary 表面；
- 只在結構需要時使用低對比細分隔線；
- 核心 radius 為 `0.75rem`；
- 選取底板、switch knob 與低對比陰影；
- 32／40／56px 控制項高度；
- 清楚的 title／body／caption 層級。

不得加入裝飾性切角、假序號、背景工程網格、面板刻紋、內凹接縫或全站 uppercase。沒有元件結構或互動用途的細節不應加入。

## 色彩

### 淺色主題

亮色主題使用接近 Modulor `Background/Main` 的暖白作為主背景。Limestone 衍生色用於 secondary／quaternary 表面；Charcoal 衍生色用於文字與圖示；Vermilion 取代 Modulor blue，作為主要操作、選取與勾選狀態。

### 深色主題

深色主題保留相同的元件結構與間距，以暖色近黑、逐層變亮的表面與 Limestone 文字建立層級。Vermilion 保留強調角色，不使用霓虹光暈。

### 強調色與狀態色

Vermilion 用於主要操作、選取／勾選狀態與必要指示器。危險操作使用獨立語意變數，不與主要操作共用角色。Vermilion 上的一般尺寸文字使用通過對比檢查的深色 `OnAccent`，不直接使用白色。

## 字體

- `GenKiGothicTW`：一般 UI 無襯線字體。
- `GenKiMinTW`：由產品控制的編輯內容。
- `Geist Mono`：程式碼、日期／時間、計數器、計時器與數值。
- SectionHeading 的大寫只用於 Figma 明確顯示的 12／16 說明文字。
- 日期、時間與數值欄位使用 tabular numerals。

## 圖示

介面圖示統一使用 Phosphor。Button、欄位、選單與日曆導覽的圖示由元件控制尺寸並繼承語意前景色。預設使用 regular／bold；只有勾選／選取狀態在語意需要時使用 fill。圖示不取代可見的狀態文字，也不得以手寫 SVG、Unicode 字元或 CSS 圖形代替。

## 互動

可操作狀態透過 hover／按下表面、選取底板、knob 位置、短時間動態效果與焦點回饋表達。不使用厚邊框、硬陰影、位移刻線或面板裝飾表達互動。

所有元件必須：

- 支援長文字與地區語言擴展；
- 在窄螢幕不造成頁面 overflow；
- 維持至少 44px 互動目標，或提供等效點擊區域；
- 清楚區分驗證、停用與唯讀；
- 支援完整鍵盤操作；
- 在減少動態效果下仍能辨識狀態變化。

## 可存取性

Linyao Design System 以 WCAG 2.2 AA 為目標。Figma 的尺寸與結構是視覺依據；若原始配色不符合一般 Web 文字對比，會保留語意角色並改用可存取的前景色，例如 Vermilion 上使用深色 `OnAccent`。

`focus-visible` 不能只以低對比陰影表示；選取、無效與狀態不能只依賴顏色；停用內容仍應可讀。一般 transition 使用動態效果變數，`prefers-reduced-motion: reduce` 時移除非必要的距離與時間。

---

# 設計變數

色盤、語意色彩、字體、間距與動態效果的變數層級。

設計變數是 Linyao Design System 在 Figma、CSS、主題與元件之間的語意契約。基礎變數描述色盤與量尺；元件 CSS 只使用角色／狀態語意變數。

## 命名與轉換

Figma variables 使用 `Category/Role_State`。CSS 變數依下列規則轉換：

1. `/` 轉為 `-`；
2. `_` 轉為 `-`；
3. 英文字母轉為小寫；
4. 合併連續分隔符號；
5. 加上 `--`。

```text
Text/Always_White        -> --text-always-white
Background/Main          -> --background-main
Control/Primary_Hover    -> --control-primary-hover
Motion/Ease/InOut        -> --motion-ease-in-out
```

新的設計變數不得使用手動例外映射。

## 變數層級

### 色盤

品牌色：

| 變數                  | Hex       | OKLCH                        | 用途               |
| --------------------- | --------- | ---------------------------- | ------------------ |
| `--palette-limestone` | `#D3CCC1` | `oklch(0.8478 0.0169 79.34)` | 暖色材質基礎       |
| `--palette-charcoal`  | `#4D4D4D` | `oklch(0.4202 0 0)`          | 結構與文字基礎     |
| `--palette-vermilion` | `#FE3300` | `oklch(65% 0.245 31.5)`      | 主要操作與選取狀態 |

另提供暖色中性色階與狀態色階。資訊、成功、警告使用低彩度藍色、綠色、琥珀色色階，負責狀態辨識與對比，不取代 Vermilion 的主要操作角色。

深色主題的表面另有一組 `--palette-warm-dark-*` 色階。深色介面的層級靠亮度而非陰影表達，需要比亮色色階更細的分階；字尾就是該色的 OKLCH 亮度（`--palette-warm-dark-18` 即 `oklch(0.18 0.008 75)`），因此整個深色主題可以從這十二個值重新調校。帶透明度的遮罩與陰影在兩個主題都直接寫在角色上：一個色調加一個透明度不是色盤項目。

色盤變數只供主題設定使用。元件不得直接使用 `--palette-warm-700` 或 `--palette-vermilion`；`pnpm lint:css` 會擋下元件 CSS 中的 `var(--palette-*)`。

### 語意色彩

- `Background/*`：`Main`、`Secondary`、`Elevated`、`Inset`、`Sunken`、`Modal`、`Accent`、`Selected`、`Disabled`、`Backdrop`。
- `Text/*`：`Title`、`Main`、`Secondary`、`Muted`、`Disabled`、`Accent`、`Link`、`On_Accent`、`On_Danger`、`Always_White`、`Always_Dark`。
- `Icon/*`：一般、次要、強調、停用、on-accent 與固定角色。
- `Divider/*`、`Border/*`：subtle／main／strong、控制項狀態與無效狀態。
- `Control/*`：primary／secondary／neutral／quaternary／surface、hover／按下／停用、選取、軌道、knob、預留文字。`neutral` 提供跨主題的高對比灰色操作；`danger` 保留給破壞性操作。控制項邊框一律使用 `Border/*` 角色，沒有平行的 `Control/Border` 系列。
- `Focus/*`、`Selection/*`：焦點環、光暈與選取前景色／背景色。在強調色表面內側繪製的焦點環使用 `--focus-ring-on-accent`。
- `Status/*`：中性、資訊、成功、警告、危險的背景色／前景色／邊框。
- `Shadow/*`、`Elevation/*`：低、中、浮層、選取與浮動控制項陰影。

正確：

```css
.lyds-button[data-variant="primary"] {
	background: var(--control-primary);
	color: var(--control-on-primary);
	border-color: var(--control-primary);
}

.lyds-button[data-variant="primary"]:hover {
	background: var(--control-primary-hover);
}
```

不允許：

```css
.lyds-button {
	background: #fe3300;
	color: black;
}
```

## 對比

品牌原色不保證彼此符合可存取性：

| 配色                 |   對比 | 一般介面文字 |
| -------------------- | -----: | ------------ |
| 純黑／Vermilion      | 5.69:1 | AA           |
| Limestone／Vermilion | 2.32:1 | 不通過       |
| Charcoal／Vermilion  | 2.29:1 | 不通過       |
| 純白／Vermilion      | 3.69:1 | 不通過       |
| Warm 25／Signal 600  | 4.54:1 | AA           |
| Charcoal／Limestone  | 5.30:1 | AA           |

品牌強調表面使用 `--text-on-accent` 的深色前景；主要控制項使用較深的 `--palette-signal-600` 與暖近白 `--control-on-primary`。這兩種語意不可互換。`Always_White`／`Always_Dark` 只用於跨主題不可改變的語意，不得當作一般文字捷徑。

### 自動驗證

`pnpm lint:contrast`（`scripts/check-contrast.mjs`）直接解析 `styles.css`，對兩個主題計算一份具名配對表：文字對 4.5:1，界定控制項的邊框與指示器對 3:1。停用狀態依規範豁免，因此刻意不列入，而不是用一個它從未被要求達到的門檻讓它「通過」。

這份檢查補上 Storybook axe 掃描的兩個盲點：只出現在 story 裡的組合才會被量到，而且 axe 完全不檢查非文字對比，邊框或底線掉到 2:1 也不會有人反對。色盤值一改動，依賴它的配對就會在這裡以實際數字失敗。

新增語意角色時，若它承載文字或用來辨識控制項，就在 `PAIRS` 補一列。

### 人工驗證

自動檢查涵蓋不到的部分仍需人工確認：

- 半透明遮罩之上的文字（必須以實際合成後的背景測量）；
- hover 與按下狀態的實際堆疊結果；
- 焦點環與其相鄰表面（`outline-offset` 會讓相鄰色變成頁面底色而非控制項底色）；
- 大型文字適用的較寬門檻。

## 字體

```css
--font-family-sans: "GenKiGothicTW", system-ui, sans-serif;
--font-family-serif: "GenKiMinTW", ui-serif, serif;
--font-family-mono: "Geist Mono", ui-monospace, monospace;
```

這三個字族由可選入口 `@linyao.tw/ui/fonts.css` 載入，`styles.css` 不含任何遠端請求：

- `https://font.emtech.cc/css/GenKiGothicTW.css`
- `https://font.emtech.cc/css/GenKiMinTW.css`
- Google Fonts 的 Geist Mono variable family

正式環境建議自行代管並覆寫 `--font-family-*`。變數本身已帶系統字型備援，未載入 `fonts.css` 時元件仍可正常呈現。

行高分成兩組：`--line-height-tight`／`-heading`／`-body` 是無單位比例，用於會隨繼承字級縮放的文字；`--line-height-control-xs`／`-sm`／`-md`／`-flat` 是固定行高，用於盒高本身就是設計一部分的控制項。字距同理，`--letter-spacing-tight`／`-body`／`-label`／`-technical` 使用 `em`，`--letter-spacing-control` 與 `--letter-spacing-control-supporting` 是與固定行高搭配的 `rem` 值。

字級、字重、行高與字距均有對應設計變數。日期、時間、計數器、計時器與數值欄位使用：

```css
font-variant-numeric: tabular-nums lining-nums;
```

`.lyds-numeric` 與 `.lyds-technical-label` 是公開工具類別，不得用來改變內容語意。

## 間距、尺寸與形狀

固定長度使用 `rem`：

```css
padding: var(--space-3); /* 0.75rem */
min-height: var(--control-height-md); /* 3.5rem */
border-radius: var(--radius-md); /* 0.75rem */
```

只有 1px 邊框／分隔線與 Figma 明確指定的 0.5px 分隔線可使用 `px`。SVG viewBox 座標不屬於 CSS 長度。流動版面可使用 `%`、`fr`、`vw`、`dvh` 與無單位行高。

`pnpm lint:css` 會強制檢查：`font-size`、`line-height`、`letter-spacing`、`border-radius`、`gap`、`padding-*` 與 `margin-*` 的每個值都必須是 `var(...)`、`calc()`／`clamp()`／`min()`／`max()`／`env()`，或 `0`、`auto`、`normal`、`inherit`、百分比等關鍵字。`z-index` 必須是 `var(--z-*)`，或用於元件自身堆疊脈絡內的 `0`、`1`、`2`。寫入原始長度會讓檢查失敗：

```css
padding: 0.75rem var(--space-4); /* 失敗 */
padding: var(--space-3) var(--space-4); /* 通過 */
```

刻度沒有對應值時，先確認是否應該貼齊既有刻度；確實是元件專屬的光學常數，才新增 `--component-*` 變數或該元件檔案內的區域 `--lyds-*` 變數。檢查範圍涵蓋 `packages/ui/src/components` 與 `apps/storybook/src`。

控制項高度分成兩組刻度，元件 CSS 不得再寫入原始高度：

| 刻度                          |       值 | 用途                                                         |
| ----------------------------- | -------: | ------------------------------------------------------------ |
| `--control-height-sm`         |   `3rem` | 有 `size` 屬性的元件：Button、IconButton、ListCell、各種欄位 |
| `--control-height-md`         | `3.5rem` | 同上，預設尺寸                                               |
| `--control-height-lg`         |   `4rem` | 同上                                                         |
| `--control-height-compact-sm` | `2.5rem` | 行內與次要控制項：選單項目、工具列按鈕、頭像                 |
| `--control-height-compact-md` |   `3rem` | 同上                                                         |
| `--control-height-compact-lg` | `3.5rem` | 同上                                                         |

主刻度最小值是 `3rem`，高於 `--control-target-min`（`2.75rem`）；`--control-target-min` 仍用於本身沒有高度刻度的圖示命中區。沒有 Figma 結構依據時，不得在元件加入 `clip-path`。

## 動態效果

持續時間：

| Figma 名稱                   | CSS 變數                       |      值 | 用途                    |
| ---------------------------- | ------------------------------ | ------: | ----------------------- |
| `Motion/Duration/Instant`    | `--motion-duration-instant`    |   `0ms` | 無插值的狀態            |
| `Motion/Duration/Fast`       | `--motion-duration-fast`       | `120ms` | hover、按下、小型指示器 |
| `Motion/Duration/Normal`     | `--motion-duration-normal`     | `220ms` | 一般控制項／彈出元件    |
| `Motion/Duration/Slow`       | `--motion-duration-slow`       | `360ms` | 小型表面                |
| `Motion/Duration/Deliberate` | `--motion-duration-deliberate` | `480ms` | 少量非必要展示          |

Easing：

| 名稱       | CSS 變數                   | 值                                  |
| ---------- | -------------------------- | ----------------------------------- |
| Out        | `--motion-ease-out`        | `cubic-bezier(0.16, 1, 0.3, 1)`     |
| InOut      | `--motion-ease-in-out`     | `cubic-bezier(0.65, 0, 0.35, 1)`    |
| In         | `--motion-ease-in`         | `cubic-bezier(0.7, 0, 0.84, 0)`     |
| Snap       | `--motion-ease-snap`       | `cubic-bezier(0.34, 1.56, 0.64, 1)` |
| Linear     | `--motion-ease-linear`     | `linear`                            |
| Mechanical | `--motion-ease-mechanical` | `steps(4, end)`                     |

`Snap` 只用於 toggle、knob、小型指示器或確認回饋，不用於 Dialog、Drawer 或頁面轉場。`Mechanical` 只用於非必要裝飾，不用於導覽或閱讀。元件 CSS 不得加入未命名的 `ease` 或 cubic-bezier。

在減少動態效果下，非必要持續時間降至 `1ms`、位移歸零、按下縮放回到 `1`，Snap／Mechanical 改為 linear。動畫關閉後仍須能透過形狀、文字、圖示或顏色辨識狀態。

## 元件專用變數

`--component-*` 是設計變數的第三層，用於在不移動全域語意角色的前提下微調單一元件。所有元件專用變數集中定義在 `styles.css` 的元件角色區塊，該區塊同時對 `:root`、`[data-lyds-theme="light"]` 與 `[data-lyds-theme="dark"]` 生效，因此子樹主題會一併重新計算：

```css
:root,
[data-lyds-theme="light"],
[data-lyds-theme="dark"] {
	--component-field-background: var(--control-surface);
	--component-field-border-focus: var(--border-control-focus);
	--component-calendar-day-background-selected: var(--control-primary);
	--component-calendar-day-foreground-selected: var(--control-on-primary);
	--component-calendar-day-indicator-today: currentColor;
}
```

規則：

- 只有共用語意變數無法描述元件，而且需要跨主題覆寫時，才新增元件專用變數。
- 元件專用變數必須引用語意角色或 `currentColor`，不得包含原始色值。
- 元件 CSS 直接讀取元件專用變數，不再使用 `var(--component-x, var(--semantic-y))` 這種行內備援；備援會讓變數看起來存在卻從未被定義。
- 元件專用變數不得定義在基礎 `:root` 區塊，否則會在 `:root` 上算出亮色值並繼承到深色子樹。

## 新增或修改變數

1. 定義要解決的角色／狀態。
2. 檢查現有語意變數是否可使用。
3. 同時設定亮色與深色。
4. 固定長度使用 `rem`；動態效果使用共用持續時間／easing。
5. 更新 Storybook Foundations 與本文件。
6. 檢查所有使用處，避免同義變數。
7. 重新驗證受影響的對比與互動狀態。

刪除或重新定義公開語意變數可能破壞使用者主題，應依 SemVer 評估。

---

# 主題

以語意變數定義主題；亮色、深色與自訂主題共用同一份元件 CSS。

Linyao Design System 以語意變數定義主題。所有主題共用相同的元件 CSS；亮色、深色或自訂主題只重新指定角色變數。

## 載入樣式

在應用程式入口匯入一次：

```tsx
import "@linyao.tw/ui/styles.css";
```

不得從 `@linyao.tw/ui/dist/**`、`src/**` 或內部 CSS 路徑匯入。公開樣式入口只有兩個：必要的 `@linyao.tw/ui/styles.css`，以及可選的 `@linyao.tw/ui/fonts.css`。

### 字型

`styles.css` 不載入任何遠端資源。品牌字型是獨立的可選入口：

```tsx
import "@linyao.tw/ui/fonts.css"; // 選用
import "@linyao.tw/ui/styles.css";
```

`fonts.css` 會向 `font.emtech.cc` 與 `fonts.gstatic.com` 發出三個跨來源請求。正式環境建議自行代管相同字型，並覆寫 `--font-family-sans`、`--font-family-serif` 與 `--font-family-mono` 指向自己的 `@font-face`；設計變數本身已帶有系統字型備援，未載入 `fonts.css` 時元件仍可正常呈現。

不匯入 `fonts.css` 的理由通常是：Content Security Policy 未允許這兩個網域、離線或內網環境無法連線，或需要避免 CSS `@import` 造成的串行阻塞。

## 選擇主題

亮色是 `:root` 預設，也可明確指定：

```html
<html data-lyds-theme="light"></html>
```

深色：

```html
<html data-lyds-theme="dark"></html>
```

主題也可套在子樹：

```tsx
<main data-lyds-theme="light">
	<Preview />
	<aside data-lyds-theme="dark">
		<DarkPreview />
	</aside>
</main>
```

一般應用程式應將主題設在文件根元素。`Select`、`Combobox`、`Menu`、`Tooltip`、`Dialog`、`DatePicker` 等浮層元件預設透過 portal 呈現在 `body`，會依 portal 目的節點的祖先元素取得設計變數。若主題只套在子樹，portal 容器也必須位於相同主題範圍。

每個主題範圍同時設定對應的 `color-scheme`，使瀏覽器原生控制項與 Linyao Design System 表面一致。

## 主題狀態

主題狀態由應用程式管理。Linyao Design System 不讀取系統偏好、不寫入 localStorage，也不建立全域 React context。

```tsx
type LydsTheme = "light" | "dark";

export function AppTheme({ theme, children }: React.PropsWithChildren<{ theme: LydsTheme }>) {
	document.documentElement.dataset.lydsTheme = theme;
	return children;
}
```

需要跟隨系統時，應用程式可使用 `matchMedia("(prefers-color-scheme: dark)")`。需要保存設定時，由應用程式選擇 cookie、伺服器設定或 localStorage。

### 首次繪製

SSR 的伺服器標記與用戶端第一次 render 必須使用相同主題。若只能在瀏覽器決定，可由應用程式在 hydration 前設定 `document.documentElement.dataset.lydsTheme`。Linyao Design System 不注入此程式，因為儲存方式、CSP、nonce 與系統偏好都屬於產品設定。

## 淺色主題

```text
Limestone
├─ Background/Main       暖白主背景
├─ Background/Secondary  清單與相鄰表面
├─ Background/Elevated   浮動表面
├─ Background/Inset      群組控制項表面
└─ Background/Sunken     次要表面

Charcoal
├─ Text/Title 與 Text/Main
├─ 圖示
└─ 低對比分隔線

Vermilion
├─ primary action
├─ 選取／勾選
└─ 必要的狀態強調
```

表面層級主要透過明度、選取底板與結構性分隔線表達。陰影只用於浮動元件或浮層元件。Vermilion 上的文字使用 `OnAccent` 語意值。

## 深色主題

- `Background/Main` 約為 `oklch(0.18 0.008 75)` 的暖色近黑。
- `Background/Secondary` 與 `Background/Elevated` 逐層提高明度。
- `Background/Inset`／`Sunken` 保留群組層級，不使用單一純黑背景。
- `Text/Main` 使用 Limestone／暖色中性色系。
- Vermilion 保留主要操作與選取角色，不加入 neon glow。
- 細線與陰影依深色主題重新指定，不直接反轉亮色主題值。

深色色盤、語意設定與動態效果是 Linyao Design System 的設計，不是 Modulor 公開 Figma 元件庫的原始內容。

## 自訂主題

### 覆寫語意變數

使用 class 或 data attribute 覆寫語意角色：

```css
.operations-theme {
	--background-main: oklch(88% 0.018 82);
	--background-secondary: oklch(92% 0.014 82);
	--text-main: oklch(35% 0.01 82);
	--control-primary: var(--palette-signal-600);
	--control-primary-hover: var(--palette-signal-700);
	--control-primary-pressed: var(--palette-signal-800);
	--control-on-primary: var(--palette-warm-25);
	--focus-ring: oklch(48% 0.17 32);
}
```

```tsx
<section className="operations-theme" data-lyds-theme="light">
	<AccountSettings />
</section>
```

完整自訂主題必須覆寫語意角色，不能只修改 `--palette-vermilion`。元件不直接使用色盤變數。

### 使用語意角色

建議：

```css
.billing-surface {
	--control-primary: var(--billing-action);
}
```

不建議：

```css
.billing-surface .lyds-button[data-variant="primary"] {
	background: #e04010;
}
```

直接覆寫 `.lyds-*` 會略過 hover、按下、停用、深色主題與未來內部變更。若現有語意角色無法完成合理的自訂，應先提出設計變數調整，不要分支修改元件 CSS。

### 版面調整

`className` 與 `style` 用於應用程式控制的位置、寬度與 grid／flex 關係：

```tsx
<DatePicker className="checkout-delivery-date" label="交付日期" />
```

```css
.checkout-delivery-date {
	inline-size: min(100%, 24rem);
}
```

不要以 `style` 傳入元件原始色值。需要從 React 動態傳入設計變數時，使用 CSS custom property 與可檢查的型別包裝。

## 主題驗證

每個主題都必須檢查：

- 內文、標題、次要、停用與連結文字；
- primary、secondary、quiet、danger 操作；
- 輸入元件預設／hover／焦點／無效／唯讀／停用；
- 選取／勾選控制項；
- popup、dialog、drawer、bottom sheet、backdrop；
- Toast／狀態表面；
- 日期選取／範圍／今天／不可用狀態；
- `focus-visible`、鍵盤順序與焦點返回；
- 繁體中文與英文混合的長文字；
- 200% zoom 與窄螢幕；
- `prefers-reduced-motion: reduce`；
- 產品需要列印時的 print colors。

修改主題不應造成版面位移。語意值改變時，元件尺寸、互動目標與文字換行應保持一致。

## 對比責任

內建主題以 WCAG 2.2 AA 為目標。使用者覆寫主題後，必須重新驗證：

- 前景色與合成後背景；
- 焦點指示器與控制項／相鄰表面；
- 非文字控制項邊界；
- hover／按下／選取狀態；
- 停用狀態的可讀性。

品牌原色不保證符合對比。Limestone、Charcoal 與 white 都不適合直接作為 Vermilion 上的一般尺寸文字。品牌強調表面應使用 `--text-on-accent`；需要近白前景的主要控制項，應同時使用較深的 `--control-primary` 與 `--control-on-primary`。

---

# 元件

元件清單、共用 API、在地化與組合方式。

本文件列出 Linyao Design System 的元件分類、共用 API 與組合邊界。實際可匯入項目以 `packages/ui/src/index.ts` 與建置產生的 `dist/index.d.ts` 為準。未列入公開匯出入口的原始檔不屬於公開 API。

## 共用 API

| 概念       | API                                                            | 規則                                        |
| ---------- | -------------------------------------------------------------- | ------------------------------------------- |
| 視覺／語意 | `variant`                                                      | 不以 `intent`／`appearance` 表達相同概念    |
| 尺寸       | `size="sm"`／`size="md"`／`size="lg"`                          | 元件只支援適用的範圍                        |
| 方向       | `orientation`                                                  | 只用於有水平／垂直語意的元件                |
| 狀態       | `disabled`, `readOnly`, `required`, `invalid`, `loading`       | 映射至原生、Base UI 或 RAC 語意             |
| 值         | `value`, `defaultValue`, `onValueChange`                       | 受控／非受控，不混用兩種狀態所有權          |
| 開啟狀態   | `open`, `defaultOpen`, `onOpenChange`                          | 彈出／展開元件的受控／非受控狀態            |
| 表單語意   | `name`, `min`, `max`, `step`                                   | 底層基礎元件支援時傳遞                      |
| 地區設定   | `locale`, `hourCycle`, `firstDayOfWeek`, structured value type | 只用於相關元件；時區由 `ZonedDateTime` 表示 |
| 組合       | `children`, parts, `render`                                    | 優先組合，不分支修改原始碼                  |
| 版面       | `className`, `style`                                           | 用於位置／尺寸；顏色使用設計變數            |

受控：

```tsx
const [value, setValue] = React.useState("line-a");

<SegmentedControl value={value} onValueChange={next => next && setValue(next)} aria-label="生產線">
	<SegmentedControlItem value="line-a">生產線 A</SegmentedControlItem>
	<SegmentedControlItem value="line-b">生產線 B</SegmentedControlItem>
</SegmentedControl>;
```

非受控：

```tsx
<Select
	defaultValue="normal"
	options={[
		{ value: "normal", label: "一般" },
		{ value: "priority", label: "優先" }
	]}
	aria-label="派送模式"
/>
```

不得同時傳入 `value` 與 `defaultValue`。使用者控制值或開啟狀態時，也必須在回呼中更新狀態。Linyao Design System 不建立另一份業務狀態。

## 元件清單

### 基礎元件

- `Button`：`primary`、`secondary`、`neutral`、`quiet`、`danger`；尺寸、載入、起始／結尾圖示。`neutral` 在亮色與深色主題均使用高對比灰色表面；破壞性操作使用 `danger`，不得以一般灰色按鈕代替。
- `IconButton`：只有圖示的操作，必須有可存取名稱。
- `Link`：保留連結與導覽語意。
- `Badge`、`Avatar`、`Separator`。
- `Card` 與 `CloudBox` 別名：material／elevated／inset／outline／cloud 表面。
- `SectionHeading`。
- `ListCell`：前置內容、主要內容、標題、說明、metadata、後置內容。

`Button` 載入時會停用操作並設定 `aria-busy`。`IconButton` 的可見圖示屬於裝飾，可存取名稱必須由 `aria-label` 或 `aria-labelledby` 提供。

```tsx
import { ArrowRightIcon } from "@phosphor-icons/react/dist/csr/ArrowRight";
import { FloppyDiskIcon } from "@phosphor-icons/react/dist/csr/FloppyDisk";
import { PlusIcon } from "@phosphor-icons/react/dist/csr/Plus";
import { Button, IconButton } from "@linyao.tw/ui";

<Button startIcon={<FloppyDiskIcon weight="bold" />}>儲存變更</Button>;
<Button endIcon={<ArrowRightIcon weight="bold" />}>繼續</Button>;
<IconButton aria-label="新增項目">
	<PlusIcon weight="bold" />
</IconButton>;
```

`startIcon`／`endIcon` 是裝飾性的 `ReactNode` 插槽，尺寸與顏色由 Button 控制。載入時 spinner 取代起始圖示並隱藏結尾圖示，但可見標籤仍作為可存取名稱。只有圖示的操作應使用 `IconButton`。用戶端程式碼使用 Phosphor 個別 CSR 匯入；不得手寫 SVG 或以 Unicode 字元代替圖示。

### 表單輸入

- `Input`。
- `TextField`、`Textarea`／`TextView`。
- `SearchField`、`PasswordField`、`NumberField`。
- `CodeField`、`PhoneField`、`OTPField`。
- `FileUpload`、`DropZone`。

欄位元件共用標籤、說明、錯誤、必填／無效／停用／唯讀狀態與 `sm`／`md`／`lg` 尺寸。沒有可見標籤時，實際控制項必須提供 `aria-label` 或 `aria-labelledby`。

`PhoneField` 不解析國碼或驗證電話號碼。`CodeField` 不決定驗證協定。`OTPField` 只處理多欄輸入；發送、重送、倒數與伺服器驗證由應用程式負責。

`FileUpload`／`DropZone` 只回傳瀏覽器 `File` 物件。上傳傳輸、限制、MIME／內容驗證、重試、進度來源與安全掃描由應用程式處理；`accept` 只提供瀏覽器提示。

### 選取元件

- `Checkbox`、`CheckboxGroup`、`CheckboxItem`。
- `RadioGroup`、`Radio`、`RadioItem`。
- `Switch`。
- `Slider`。
- `Toggle`、`ToggleGroup`、`SegmentedControl`／`SegmentedControlItem`。
- `Select`，提供 `options` API 與組合 parts。
- `Combobox`、`Autocomplete`，提供選項與組合 parts。
- `DropdownMenu`／`Menu`、`ContextMenu`。

`Switch` 用於立即生效的二元設定；`Checkbox` 用於表單中的獨立選項；`RadioGroup` 用於互斥選項；`SegmentedControl` 用於少量並列的檢視／模式。不得因外觀相近而交換語意。

一般選項可使用高階 `Select`／`Combobox`。需要群組、分隔線、複合項目或特殊 render 時，使用同一元件的 parts，不直接混用未樣式化基礎元件。

Base UI 1.8.0 已包含 [#5058](https://github.com/mui/base-ui/pull/5058) 的巢狀選單 portal owner 修正；Linyao Design System 不再使用 workspace patch。Storybook 保留開啟狀態的 `role="group"`、axe、方向鍵、Escape 與焦點返回回歸測試。Base UI 焦點守衛用於 portal 的 Tab 順序導引，不得刪除、設為 inert 或以 MutationObserver 改寫。

### 展開與結構

- `Accordion`。
- `Collapsible`。
- `Tabs`：Root、List、Tab、Indicator 與 Panel。Indicator 預設隱藏。

Accordion 用於多個展開區段；Collapsible 用於單一區域；Tabs 用於同一內容中切換面板。需要 URL／連結語意時，應使用導覽元件，不以 Tabs 代替路由。

### 浮層元件

- `Tooltip`、`Popover`、`PreviewCard`。
- `Dialog`／`Modal`。
- `AlertDialog`。
- `Drawer`。
- `BottomSheet`：把手、頁首／內容／頁尾與停駐點。

浮層元件保留 Base UI 的焦點限制、Escape、焦點返回、外部互動與定位。最小 Dialog：

```tsx
<Dialog.Root>
	<Dialog.Trigger render={triggerProps => <Button {...triggerProps}>開啟設定</Button>} />
	<Dialog.Portal>
		<Dialog.Backdrop />
		<Dialog.Viewport>
			<Dialog.Popup hasCustomClose>
				<Dialog.Header>
					<Dialog.Title>設定</Dialog.Title>
					<Dialog.Description>調整工作站設定。</Dialog.Description>
				</Dialog.Header>
				<Dialog.Body>{/* 欄位 */}</Dialog.Body>
				<Dialog.Footer>
					<Dialog.Close
						render={closeProps => (
							<Button {...closeProps} variant="secondary">
								完成
							</Button>
						)}
					/>
				</Dialog.Footer>
			</Dialog.Popup>
		</Dialog.Viewport>
	</Dialog.Portal>
</Dialog.Root>
```

自行提供 `Dialog.Close` 時，在 `Dialog.Popup` 設定 `hasCustomClose`，避免重複關閉按鈕。`AlertDialog` 只用於需要明確確認的決策。Tooltip 不能承載完成任務所需的唯一資訊；需要螢幕閱讀器與觸控使用者主動探索內容時，使用 `Popover`。

### 回饋元件

- `Alert`／`AlertView`、`Banner`。
- `ToastProvider`、`ToastViewport`、`ToastRoot` 與 Toast 管理工具。
- `Progress`、`Meter`。
- `Spinner`／`Loader`。
- `Skeleton`。
- `EmptyState`。

狀態使用 `neutral`、`info`、`success`、`warning`、`danger`。狀態不能只靠顏色，必須提供可理解的標題／說明或可存取標籤。

Toast 佇列由 Base UI 管理器處理。使用者決定加入佇列、去重複、重試與後端錯誤文案。需要長期保留或會影響任務完成的訊息，不應只使用短暫 Toast。

`Progress` 表示任務進度；`Meter` 表示已知範圍中的測量值。無確定進度的載入使用 `Spinner`／`Loader`，並由周圍區域提供適當的忙碌狀態關聯。

### 導覽

- `Breadcrumb`、`Pagination`。
- `NavigationMenu`、`Menubar`、`Toolbar`。
- `Header` 組合 parts。
- `TabBar`。
- `CommandPalette`。

路由由應用程式管理。連結目的地、目前路由、預先載入與導覽副作用都由使用者提供；接上路由連結時仍須保留錨點語意、可存取名稱與鍵盤行為。

Pagination 只呈現控制項與狀態，不取得資料或決定頁碼模型。CommandPalette 只提供 Dialog 與 Combobox 組合，不建立指令登錄、快捷鍵規則、權限或非同步搜尋後端。

### 資料與內容

- 使用原生語意的 `Table`、`TableFrame`。
- `DataTable`：頁首／標題／說明／控制項／狀態／區域。
- `ScrollArea`。
- `List`、`OrderedList`、`Collection` 與項目／內容／操作／metadata parts。

`DataTable` 不包含排序演算法、篩選狀態、伺服器分頁、列選取業務規則、資料取得或欄位 schema 引擎。

`Collection` 不處理大量資料虛擬化。大型清單的視窗化、尺寸測量與非同步載入由應用程式選擇方案，再套用 Linyao Design System 語意與設計變數。

### 日期與時間

- `Calendar`：月份／年份導覽、鍵盤日曆格線、最小／最大值與不可用日期。
- `DateField`。
- `DatePicker`。
- `DateRangePicker`。
- `TimeField`、`TimePicker`。
- `DateTimePicker`。

Linyao Design System 從套件根目錄重新匯出常用值類別與剖析器：

```tsx
import { useState } from "react";
import { CalendarDate, DateRangePicker } from "@linyao.tw/ui";

const [range, setRange] = useState({
	start: new CalendarDate(2026, 9, 1),
	end: new CalendarDate(2026, 9, 5)
});

<DateRangePicker label="維護期間" locale="zh-TW" value={range} onValueChange={next => next && setRange(next)} minValue={new CalendarDate(2026, 9, 1)} isDateUnavailable={date => date.day === 13} />;
```

值型別：

- `CalendarDate`：不含時間／時區的日期，例如生日或結算日。
- `CalendarDateTime`：不含指定時區的當地日期與時間。
- `ZonedDateTime`：包含 IANA 時區與確切時間點。
- `Time`：不含日期的當地時間。

`locale` 控制語言與區段；`hourCycle`、`granularity`、`firstDayOfWeek`、`minValue`、`maxValue` 與 `isDateUnavailable` 由使用者指定。不得將 `zh-TW`、`Asia/Taipei`、`YYYY/MM/DD` 或 24 小時制設為套件預設值。

Linyao Design System 不自動將 `CalendarDateTime` 轉為 `ZonedDateTime`。需要確切時間點時，應用程式必須提供時區、處理 DST／不存在／重複的當地時間，並決定序列化方式。

## 不屬於元件層的功能

下列功能由應用程式處理：

- DataTable 排序／篩選／資料取得／虛擬化；
- 上傳傳輸或雲端供應商轉接器；
- 國際電話解析／國家資料庫；
- 指令登錄、全域鍵盤快捷鍵管理器或路由整合；
- 表單套件專用轉接器；
- 分析、持久化、權限、API 用戶端；
- 產品特定的日期格式、假日日曆、預約限制或時區轉換規則。

只有跨產品、沒有業務假設且可維持可存取性的需求，才評估新增 headless 轉接器或組合模式。

## 新增元件的判斷

1. 現有 `variant`、`size` 或語意變數是否已支援？
2. 是否可用現有 parts 組合？
3. 差異是否只屬於使用者版面，可用 `className` 解決？
4. 是否為應用程式業務邏輯？
5. 只有共用、可重複且可存取的行為才新增元件。

分支修改會失去後續修正、設計變數、鍵盤行為與測試。確定需要新元件時，依[貢獻指南](https://github.com/linyao-tw/ui/blob/main/CONTRIBUTING.md)完成 API、狀態、Storybook stories、測試、可存取性與套件匯出。

## 在地化

元件的預設字串（關閉、上一頁、清除選取、已選擇 N 個檔案等）集中在訊息套件，不再散落於各元件的預設參數。沒有 provider 時使用繁體中文套件，行為與過去一致：

```tsx
import { MessagesProvider, enUSMessages } from "@linyao.tw/ui";

<MessagesProvider messages={enUSMessages}>
	<App />
</MessagesProvider>;
```

部分覆寫會與外層套件合併，因此只調整單一字串不需要重寫整份：

```tsx
<MessagesProvider messages={{ dialogClose: "收合面板" }}>
	<SettingsDialog />
</MessagesProvider>
```

優先順序是「元件屬性 → 最近的 provider → 繼承的 provider → 繁體中文預設」。`ComponentMessages` 是完整的字串清單；`codeSlotLabel` 與 `fileSelectionSummary` 是函式，用於需要插入數字的字串。

### 一次設定兩邊：`LinyaoProvider`

字串套件與日期時間的地區設定是兩套獨立機制：前者是 `MessagesProvider`，後者是 React Aria 的 `I18nProvider`。分別設定很容易漂移，出現「按鈕是英文、日期格式是 zh-TW」這種組合。`LinyaoProvider` 從單一 `locale` 同時決定兩者：

```tsx
import { LinyaoProvider } from "@linyao.tw/ui";

<LinyaoProvider locale="en-US">
	<App />
</LinyaoProvider>;
```

`locale` 會挑選內建套件（`zh` 開頭用繁體中文，其餘用英文），同時提供給日期時間元件決定區段順序、星期名稱、數字格式與預設小時制。需要套件未內建的語言，或只想改幾個字串時，`messages` 會合併在挑選出的套件之上：

```tsx
<LinyaoProvider locale="ja-JP" messages={{ dialogClose: "閉じる" }}>
	<App />
</LinyaoProvider>
```

`getMessagesForLocale(locale)` 會回傳某個地區代碼對應的內建套件，可用於自行組合。省略 `locale` 時行為與單獨使用 `MessagesProvider` 相同：保持繁體中文預設，也不建立 `I18nProvider`。

個別日期時間元件的 `locale` 屬性仍然有效，會覆寫 provider 提供的值。

### 書寫方向

書寫方向不由 provider 控制。`dir` 屬於文件層級，和 `data-lyds-theme` 一樣必須在伺服器輸出的標記裡就正確，否則第一次繪製會閃動：

```html
<html lang="ar" dir="rtl" data-lyds-theme="light"></html>
```

元件 CSS 全面使用 logical properties，設定 `dir` 後間距、圓角與圖示位置會自動跟著鏡射。

## 組合方式

`Dialog`、`Drawer`、`Tabs`、`Accordion`、`Popover`、`Menu`、`Select`、`Combobox` 與 `CommandPalette` 都同時提供 namespace 與扁平匯出，建議使用 namespace：

```tsx
<CommandPalette.Root>
	<CommandPalette.Trigger>開啟指令列</CommandPalette.Trigger>
	<CommandPalette.Portal>
		<CommandPalette.Backdrop />
		<CommandPalette.Popup>
			<CommandPalette.Input />
			<CommandPalette.List>{/* … */}</CommandPalette.List>
		</CommandPalette.Popup>
	</CommandPalette.Portal>
</CommandPalette.Root>
```

`CommandPalette` 本身也是 root 元件，因此 `<CommandPalette>` 與 `<CommandPalette.Root>` 之外的 parts 都掛在同一個匯出上。完整規則見[架構文件的組合模型](/ui/architecture#組合模型)。

---

# 架構

工作區結構、公開套件邊界、行為層級與依賴規則。

Linyao Design System 採 pnpm 單一儲存庫架構，對外只提供 `@linyao.tw/ui`。使用者安裝一個套件即可取得 React 元件、TypeScript 型別與 CSS；Storybook、測試與發佈流程使用相同的公開邊界。

## 工作區結構

```text
/
├─ apps/
│  └─ storybook/       # 審閱與文件，不發佈
├─ packages/
│  └─ ui/              # 唯一預計公開的 npm 套件
├─ docs/               # 架構、設計、使用與發佈規則
├─ skills/
│  └─ lyds-ui/         # coding-agent skill 原始檔
├─ scripts/            # 儲存庫與 tarball 驗證工具
└─ .github/workflows/  # CI 與受開關保護的發佈流程
```

根目錄與 `apps/storybook` 的套件均為 `private: true`。只有 `packages/ui` 對應 `@linyao.tw/ui`。

## 公開套件邊界

公開使用方式：

```tsx
import { Button, DatePicker } from "@linyao.tw/ui";
import "@linyao.tw/ui/styles.css";
```

`packages/ui/package.json` 的 `exports` 是公開 API 的依據。`src/**`、測試工具、內部工具與建置設定均不是公開 API。`files` 白名單與 `pnpm pack:check` 會限制 tarball 內容。

CSS 標記為 side effect，避免正式建置的 tree shaking 移除樣式。建置必須輸出 ESM JavaScript、TypeScript 宣告與 `dist/styles.css`。

建置會為每個輸出模組加上 `"use client"`（`vite.config.ts` 的 `output.banner`）。套件內每個模組都渲染互動介面——讀取 context、持有狀態，或呼叫 Base UI 的 hook——因此整包都在用戶端邊界之後。少了這個指示詞，任何從根 barrel 匯入的 Server Component 都會把整張依賴圖（含在模組頂層呼叫 `createContext` 的 `intl/provider`）拉到伺服器並失敗。`preserveModules` 讓每個原始檔各自輸出，banner 因此標記到每一個檔案而不是單一入口。Storybook 只能透過 `@linyao.tw/ui` 工作區依賴使用套件，不得以跨套件相對路徑匯入原始碼。

目前使用單一根目錄匯出。只有在 bundle 分析證明有需要、子路徑有穩定維護邊界、型別與 CSS side effects 可測試，而且不會暴露內部檔案結構時，才新增元件子路徑匯出。

## 行為層級

```text
產品狀態與業務規則
        ↓
Linyao Design System 元件 API 與樣式
        ↓
Base UI 基礎元件         React Aria Components
（一般元件行為）         （日期與時間行為）
        ↓
React、瀏覽器平台與 Intl
```

### Base UI

Base UI 負責按鈕、選取、選單、浮層、展開元件與導覽等一般互動。Linyao Design System 保留其焦點管理、鍵盤互動、ARIA 關聯與受控／非受控模式，再加入一致的 API、元件結構與語意 CSS。

不得重新實作 Base UI 已處理的巡迴焦點、Escape 關閉、焦點限制、焦點返回或彈出元件定位。

### 日期與時間

Base UI 不提供完整的日期元件，因此日期與時間元件使用：

- `react-aria-components`：日曆格線、日期區段、範圍選取、鍵盤導覽、依地區設定調整的 ARIA 與焦點行為。
- `@internationalized/date`：`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`、日期運算與時區明確的值型別。

這兩項依賴只負責日期邏輯與行為。可見介面、設計變數、間距與狀態仍由 Linyao Design System 控制。其他元件不得只為方便而引入 React Aria Components。

### 圖示

`@phosphor-icons/react` 是唯一標準介面圖示套件。它是 `@linyao.tw/ui` 的同儕依賴，也是套件與 Storybook 的開發依賴。建置時會將 Phosphor 設為外部依賴，不把整套圖示庫包入 `@linyao.tw/ui`。

套件原始碼、Storybook 與一般用戶端元件使用個別 `/dist/csr/<Name>` 匯出；React Server Components 使用 `/ssr`。品牌標誌、插圖與資料視覺化不屬於介面圖示，但仍需設計審核；不得用手寫 JSX SVG、Unicode 字形或 CSS 偽元素圖示取代既有圖示。

## 組合模型

元件只有三種對外形狀，選哪一種取決於元件本身的結構，不取決於寫的時間：

1. **只有屬性。** 沒有內部結構的元件（`Button`、`Badge`、`TextField`）只暴露屬性，不提供 parts。
2. **Parts namespace。** 建立在 context root 上的元件（`Dialog`、`Drawer`、`Tabs`、`Accordion`、`Popover`、`Menu`、`Select`、`Combobox`、`CommandPalette`）同時提供 namespace 物件與扁平具名匯出。文件與範例一律使用 namespace 形式：

   ```tsx
   <Dialog.Root>
   	<Dialog.Popup>…</Dialog.Popup>
   </Dialog.Root>
   ```

3. **可呼叫的預設編排 + parts。** 當單一編排能涵蓋多數情境時（`Select`、`Combobox`、`Autocomplete`），元件本身可直接以 `options` 呼叫，parts 仍保留給需要完全控制的情況。

沒有共用 root 的語意包裝（`Table`、`Breadcrumb`、`Pagination`、`Collection`、`Header`、`TabBar`）只提供扁平匯出。它們的各部位彼此獨立、不共用 context，硬掛上 namespace 只會製造「有 root」的錯覺。

別名（`Modal` 之於 `Dialog`、`AlertView` 之於 `Alert`、`List*` 之於 `Collection*`、`SegmentedControlItem` 之於 `Toggle`）必須是同一個物件，並由測試斷言其同一性。新增別名前先確認名稱差異真的有意義。

## API 規則

相同概念使用相同名稱：

- `variant`：語意或視覺層級，例如 `primary`、`secondary`、`neutral`、`quiet`、`danger`。
- `size`：主要使用 `sm`、`md`、`lg`。
- `orientation`：只用於需要水平或垂直方向的元件。
- `disabled`、`readOnly`、`required`、`invalid`、`loading`：映射至底層基礎元件。
- `value`／`defaultValue`／`onValueChange`：受控／非受控值。
- `open`／`defaultOpen`／`onOpenChange`：浮層與展開元件狀態。
- `className`、`style`、`render` 或元件 parts：支援組合，不暴露內部樣式細節。

`name`、`min`、`max`、`step` 等 HTML 屬性應正確傳遞。Ref 應指向最有用的互動或根元素。可安全繼承底層型別時，不應複製 props 清單。

## 產品邏輯邊界

下列責任由應用程式處理：

- API 呼叫、server actions、快取與樂觀更新。
- 路由導覽、權限與分析。
- localStorage、cookie 或主題保存。
- 領域驗證、貨幣／日期業務規則與資料轉換。
- DataTable 排序、篩選、分頁資料來源與虛擬化規則。
- 檔案上傳端點、multipart 協定、病毒掃描與重試規則。
- Toast 文案、錯誤代碼映射與通知去重複。

元件可提供回呼、render slot 與組合 parts，但不決定回呼的業務效果。

## CSS 架構

`styles.css` 是唯一必要的樣式入口，順序為：

1. 最小基準樣式；
2. 色盤、字體、間距、形狀、動態效果、z-index 等基礎設計變數；
3. 亮色／深色語意值；
4. 共用工具類別；
5. 元件結構與狀態 selectors。

字型由獨立的可選入口 `fonts.css` 提供，因此 `styles.css` 不含任何跨來源請求；CSP、離線環境與自行代管字型都不需要分支處理。

### 浮層堆疊

會 portal 到 `body` 的表面共用同一個 `--z-floating`，不各自佔一階。每一種浮層都可能從另一種裡面被開啟——Dialog 裡的 Select 必須蓋過該 Dialog，而從 Popover 裡開啟的 Dialog 必須蓋過該 Popover——所以任何固定階梯必然在其中一個方向出錯。React 依掛載順序 append 每個 portal，文件順序本身就記錄了開啟順序；backdrop 永遠是它所遮蔽的 popup 在同一個 portal 內的前一個兄弟節點。共用一個值就讓這個順序決定疊放。

`--z-toast` 與 `--z-tooltip` 刻意高於這個層：Dialog 開啟時發出的 toast 仍須可讀，tooltip 則可能掛在上述任何表面內的控制項上。`--z-base` 與 `--z-sticky` 給留在文件流內的元素。

`--z-dropdown`、`--z-popover`、`--z-overlay`、`--z-modal` 保留為指向 `--z-floating` 的別名，讓既有覆寫不會失效；單獨覆寫其中一個會重新製造原本的問題。

元件 CSS 一律使用全域 `lyds-*` 類別，不使用 CSS Modules。使用端因此能以一致的方式檢視、覆寫與偵錯任何元件，型別也不需要靠手寫的 `*.css.d.ts` 維護。命名為 `lyds-<元件>`、`lyds-<元件>__<部位>`、`lyds-<元件>--<變體>`；跨元件共用的部位使用共通字首（例如 Select、Combobox 與 Autocomplete 的清單共用 `lyds-listbox__*`）。

所有元件顏色必須使用語意變數。固定長度必須來自設計變數，由 `pnpm lint:css` 強制檢查；只有 1px 細線或分隔線可使用 `px`。流動版面可使用 `%`、`fr`、viewport units 或無單位行高。

全域基準樣式限定為 box-sizing 與 margin／padding 歸零、`body` 的背景／文字色／字體、表單控制項的 `font: inherit`、`::selection`，以及列印色彩。全部包在 `@layer lyds.base` 內：

```css
@layer lyds.base {
	*,
	*::before,
	*::after {
		margin: 0;
		padding: 0;
		box-sizing: border-box;
	}

	body {
		background: var(--background-main);
		color: var(--text-main);
		/* … */
	}
}
```

未分層的樣式一律勝過分層樣式，因此使用端不需要靠選擇器權重就能覆寫這層基準；元件庫不應該讓應用程式為了改自己的 `body` 而提高權重。設計變數、元件樣式與 `.lyds-*` 工具類別維持未分層，行為與過去一致。

新增全域正規化前必須說明具體的相容性問題，不加入完整且具版面偏好的 CSS reset。

## 依賴規則

新增正式環境依賴前必須確認：

1. 瀏覽器、React、Base UI 或現有日期依賴無法可靠完成需求；
2. 依賴只提供邏輯／headless 行為，不是另一套樣式化元件系統；
3. bundle、tree shaking、型別、SSR 與授權可接受；
4. 不包含業務假設；
5. 在架構或元件文件記錄原因。

不得加入 MUI、Chakra UI、Mantine、Ant Design 或另一套樣式執行環境。GSAP 不得成為 `@linyao.tw/ui` 執行期依賴；一般動態效果使用設計變數控制的 CSS transition／animation。

## 驗證範圍

`pnpm check` 必須涵蓋格式、lint、型別檢查、測試、套件建置與 Storybook 建置；`pnpm pack:check` 驗證實際 npm tarball。`pnpm lint` 內含 `lint:css`（語意色彩、已宣告的變數、代幣化長度與堆疊）與 `lint:contrast`（對兩個主題計算具名配對的 WCAG 對比）。可見介面變更還需在 Storybook 檢查桌面、行動裝置、亮色、深色、鍵盤操作與減少動態效果。

原始碼可編譯不代表套件可使用；Storybook 可顯示也不代表公開匯出與 tarball 正確。兩項都必須驗證。