# 麟曜數位工作室文件

> 麟曜數位工作室所有產品的文件。每一頁都有對應的 Markdown 版本，把網址的副檔名換成 `.md` 即可。

## HUAN 讙

> 雲端媒體播放與數位看板系統

### 使用教學

- [快速開始](https://docs.linyao.tw/huan.md): HUAN 讙讓你在瀏覽器裡設計一面畫面，然後把它送到現場的螢幕上。
- [核心概念](https://docs.linyao.tw/huan/guide/concepts.md): 理解這六個概念就理解了 HUAN。
- [上傳素材](https://docs.linyao.tw/huan/guide/media.md): /app/media 是素材庫。
- [設計版面](https://docs.linyao.tw/huan/guide/layouts.md): /app/layouts 是版面列表，/app/layouts/:id 是編輯器。
- [安排播放時段](https://docs.linyao.tw/huan/guide/schedules.md): /app/schedules 決定「在哪些日子的哪個時段，哪些裝置播哪個版面」。
- [管理裝置](https://docs.linyao.tw/huan/guide/devices.md): /app/devices 是裝置列表，/app/devices/:id 是單一裝置的詳情。
- [配對裝置](https://docs.linyao.tw/huan/guide/pairing.md): 裝置第一次啟動時還不屬於任何帳戶。配對就是把它綁定到你的 HUAN 的過程。
- [離線播放](https://docs.linyao.tw/huan/guide/offline.md): 這是 HUAN 最重要的一項行為。
- [解除綁定](https://docs.linyao.tw/huan/guide/unbind.md): 解除綁定會切斷裝置與帳戶的關係，讓它回到配對畫面。
- [在 Raspberry Pi 上安裝](https://docs.linyao.tw/huan/guide/install-raspberry-pi.md): Raspberry Pi 是 HUAN 的主要目標裝置，但產品沒有綁死在它上面。同一份程式碼也跑在 Ubuntu、Windows 與 macOS 上。
- [在 Ubuntu 上安裝](https://docs.linyao.tw/huan/guide/install-ubuntu.md): 支援 x64 與 arm64。
- [在 Windows 上安裝](https://docs.linyao.tw/huan/guide/install-windows.md): 支援 x64 與 arm64。
- [在 macOS 上安裝](https://docs.linyao.tw/huan/guide/install-macos.md): 支援 Intel（x64）與 Apple Silicon（arm64）。
- [登入](https://docs.linyao.tw/huan/guide/account.md): HUAN 沒有公開註冊。帳號一律由最高權限管理員在後台建立，第一個管理員則由 CLI 建立。
- [兩步驟驗證](https://docs.linyao.tw/huan/guide/two-factor.md): 每位使用者都可以在 /app/security 為自己的帳號啟用 TOTP 兩步驟驗證。
- [使用者與權限](https://docs.linyao.tw/huan/guide/users.md): /app/users 只有 superadmin 可以使用。
- [疑難排解](https://docs.linyao.tw/huan/guide/troubleshooting.md): 轉檔在伺服器端進行，一般幾十秒內完成。長時間停住通常代表轉檔程序沒有在跑，請聯絡架設 HUAN 的人。

### 開發者

- [開始開發](https://docs.linyao.tw/huan/dev.md): 這一頁把 HUAN 從零跑起來，包含後台、Server、Worker 與一台模擬裝置。
- [Monorepo](https://docs.linyao.tw/huan/dev/monorepo.md): HUAN 是一個 pnpm workspace。
- [指令](https://docs.linyao.tw/huan/dev/commands.md): pnpm install
- [測試](https://docs.linyao.tw/huan/dev/testing.md): HUAN 的測試不只是「編譯得過」。
- [系統架構](https://docs.linyao.tw/huan/dev/architecture.md): HUAN 由五個執行中的元件與兩個儲存後端組成。
- [Server](https://docs.linyao.tw/huan/dev/server.md): Fastify 5，TypeScript，PostgreSQL。
- [Worker](https://docs.linyao.tw/huan/dev/worker.md): 獨立的 process、獨立的容器。
- [Device](https://docs.linyao.tw/huan/dev/device.md): Electron 播放器。同一份程式碼跑在 Raspberry Pi、Ubuntu、Windows 與 macOS 上。
- [素材生命週期](https://docs.linyao.tw/huan/dev/asset-lifecycle.md): 這一章描述一個檔案從上傳到被回收的完整過程，以及 HUAN 在儲存上刻意做的取捨。
- [Desired / Reported State](https://docs.linyao.tw/huan/dev/desired-reported-state.md): 這是 HUAN 最核心的同步模型。
- [版面與縮放](https://docs.linyao.tw/huan/dev/layout-engine.md): HUAN 的版面不是自由拖曳的絕對定位畫布，而是一棵遞迴分割樹。
- [排程與時區](https://docs.linyao.tw/huan/dev/scheduling.md): 一筆排程描述「在哪些日子的哪個時段，哪些裝置該播哪個版面」。
- [協定](https://docs.linyao.tw/huan/dev/protocol.md): Admin、Server、Worker 與 Device 共用 @huan/protocol 的結構定義。型別只定義一次。
- [Docker 部署](https://docs.linyao.tw/huan/dev/deploy/docker.md): Server 端的所有元件都以 Docker 部署。
- [環境變數](https://docs.linyao.tw/huan/dev/deploy/environment.md): 所有環境變數在啟動時由 @huan/config 以 zod 驗證。缺少或格式錯誤時 Server 與 Worker 會拒絕啟動，並明確指出是哪一個變數有問題——不會帶著錯誤的設定跑起來，然後在某個奇怪的地方失敗。
- [PostgreSQL](https://docs.linyao.tw/huan/dev/deploy/postgresql.md): HUAN 只用一個資料庫。它同時是資料儲存與工作佇列。
- [RustFS](https://docs.linyao.tw/huan/dev/deploy/rustfs.md): RustFS 是 HUAN 使用的 S3 相容物件儲存。
- [GitHub Pages](https://docs.linyao.tw/huan/dev/deploy/github-pages.md): 文件站以 Astro 建置成靜態網站，由 GitHub Actions 部署到 GitHub Pages。
- [發布](https://docs.linyao.tw/huan/dev/release.md): 三個東西各自有版本：
- [架構決策紀錄](https://docs.linyao.tw/huan/dev/adr.md): 這裡記錄 HUAN 幾個影響全域的決定，以及做這些決定的理由。
- [ADR-0001：WebSocket 只送通知，REST 才是事實來源](https://docs.linyao.tw/huan/dev/adr/0001-websocket-plus-rest.md): 已採用
- [ADR-0002：用 desired / reported state 而不是命令式 RPC](https://docs.linyao.tw/huan/dev/adr/0002-desired-reported-state.md): 已採用
- [ADR-0003：物件儲存只做暫存，不當永久素材庫](https://docs.linyao.tw/huan/dev/adr/0003-temporary-object-storage.md): 已採用
- [ADR-0004：版面使用遞迴分割樹而不是絕對定位](https://docs.linyao.tw/huan/dev/adr/0004-recursive-split-layout.md): 已採用
- [ADR-0005：本機優先播放](https://docs.linyao.tw/huan/dev/adr/0005-local-first-playback.md): 已採用
- [ADR-0006：播放器使用 Electron](https://docs.linyao.tw/huan/dev/adr/0006-electron.md): 已採用
- [ADR-0007：工作佇列用 PostgreSQL，不引入 Redis](https://docs.linyao.tw/huan/dev/adr/0007-postgres-job-queue.md): 已採用
- [疑難排解](https://docs.linyao.tw/huan/dev/troubleshooting.md): 面向架設與開發的問題。使用者端的問題見使用教學的疑難排解。

## Linyao Design System

> 麟曜的 React 元件與設計規範

- [開始使用](https://docs.linyao.tw/ui.md): 安裝 @linyao.tw/ui、載入樣式、設定語系與主題。
- [設計原則](https://docs.linyao.tw/ui/design-principles.md): 元件結構、色彩、字體、圖示與互動的依據。
- [設計變數](https://docs.linyao.tw/ui/tokens.md): 色盤、語意色彩、字體、間距與動態效果的變數層級。
- [主題](https://docs.linyao.tw/ui/theming.md): 以語意變數定義主題；亮色、深色與自訂主題共用同一份元件 CSS。
- [元件](https://docs.linyao.tw/ui/components.md): 元件清單、共用 API、在地化與組合方式。
- [架構](https://docs.linyao.tw/ui/architecture.md): 工作區結構、公開套件邊界、行為層級與依賴規則。