這張卡做什麼（白話）

後端做「首次開通 Web 設定精靈」需要的三件事：① 偵測系統還沒有管理員帳號時，把來訪者導向設定精靈；② 驗證安裝腳本印出的一次性 setup token（防止精靈開放期間被別人搶先建帳號）；③ 提供一條「建第一個 admin 帳號」的一次性特殊通道——建完就永久關閉，之後誰都不能再走。另加一個給精靈頁用的機器指紋查詢介面。

• 母案 CM-1189：https://app.notion.com/p/FR-065-Installer-3bc346da4cd081c4abf3ce74a28ba384
• 所屬子需求卡 CM-1245：https://app.notion.com/p/FR-065-3-Web-3be346da4cd081f3b401c610fa8e419d
• 設計文件：docs/features/FR-065-2608-onprem-installer/design.md §4.6（D6／D10）

具體實作內容

• 未初始化態偵測：提供「系統是否已初始化（有無 admin）」查詢；FE 據此決定進精靈或正常登入頁
• setup token 驗證：install.sh 產生的一次性 token（落點與傳遞方式實作定，需 BE 讀得到）；精靈第一步驗 token，錯誤拒入
• 建 admin 一次性通道：繞過既有權限體系的特殊 API（此時系統無任何帳號，JWT 體系不可用），用後即封——admin 建立成功後通道永久關閉、重放被拒；密碼走既有密碼政策驗證
• 指紋顯示介面：供精靈頁取 sha256(/etc/machine-id) 指紋（現有取指紋介面需 JWT 登入，精靈階段還沒帳號——這條通道需在未登入態可用但受 setup token 保護）
• 遵守專案 DDD 規範：route 不碰 session、app service @transaction、error code 走 GRC_<HTTP><序號> 命名

易踩雷提醒

• 一次性通道的「封閉」必須是持久狀態（admin 存在即封），不能只靠記憶體旗標——服務重啟不得重開
• token 比對注意 timing-safe；token 用後作廢
• 未登入可達的端點是攻擊面——只開精靈需要的最小集合，且全部掛 setup token 守門
• license 無照態全站 403（/license/ 與 /login 豁免）——精靈端點需一併納入豁免清單，否則裝機時精靈自己被 403 擋死

驗收條件

• token 錯誤拒入
• admin 建立後通道永久封閉；重放不可（含服務重啟後）

依賴