Journey · 首次安裝 bootstrap

使用者旅程

Arova Nexus

本旅程涵蓋平台從 cold install 到第一個 Admin 帳號開通的完整路徑。供 PM 做 demo 腳本、訓練客戶交付工程師、未來作為使用者手冊「入門章節」的素材來源。

流程總覽

+------------------+
| 平台 cold start   |
| bootstrap=false  |
+--------+---------+
         |
         | 開啟任何 URL
         v
+------------------+
| 自動導向          |
| /bootstrap       |
+--------+---------+
         |
         | 填寫 Admin 表單
         v
+------------------+        +--------------+
| 強度檢查即時驗證  +-------> | 密碼太弱      |
+--------+---------+         | 提示具體缺項  |
         |                   +------+-------+
         | 通過 + 點選提交           |
         v                          | 修正後重提
+------------------+                |
| 後端建 Admin     +<---------------+
| 寫稽核紀錄        |
| 標記 completed   |
+--------+---------+
         |
         | 同 transaction commit
         v
+------------------+
| 自動登入          |
| 導向 /dashboard  |
| 顯示歡迎 toast    |
+------------------+

使用者背景

屬性	內容
角色	管理員 / 交付工程師
環境	金融客戶內網、剛完成 Arova Nexus 地端部署
情境	第一次開啟平台、尚無任何帳號
前置	平台已部署、HTTPS 已啟用、可訪問首頁 URL
預期工作	30 分鐘內開通第一個 Admin 帳號並登入

流程 1：開啟平台

開啟客戶提供的 Arova Nexus 網址。由於系統尚未完成 bootstrap，任何 URL 都會被導向 /bootstrap。

步驟	動作	系統反應
1	在瀏覽器輸入平台網址（例如 `https://nexus.client.local`）	後端檢查 `bootstrap_completed = false`
2	—	系統 308 重導至 `/bootstrap`
3	—	顯示 bootstrap 表單，提交按鈕為灰色（disabled）

流程 2：填寫 Admin 表單

依序填入 4 個欄位。強度檢查器會即時驗證密碼，所有檢核項通過後提交按鈕才會變藍。

步驟	動作	系統反應
1	輸入使用者名稱（username）	即時檢查格式（半形英數 + 底線）
2	輸入顯示名稱	無格式限制
3	輸入 Email	即時檢查 email 格式
4	輸入密碼	強度檢查器顯示每個檢核項：字數、含數字、含大小寫、含符號
5	全部通過	提交按鈕變為可點選（藍底白字）

💡 提示： 密碼策略產品下限為 8 字 + 含數字。預設策略為 12 字 + 大小寫 + 數字 + 特殊符號。生產環境建議使用預設策略。

流程 3：提交並建立帳號

點選提交後，系統會以單一 transaction 完成「建帳號 + 寫稽核 + 標記 bootstrap 完成 + 建 session」。

步驟	動作	系統反應
1	點選提交	按鈕變為 spinner「建立中」，表單欄位 disable
2	—	後端執行 Argon2id hash + DB INSERT
3	—	同 transaction 寫稽核（actor=`system_init`, action=`bootstrap_admin`）
4	—	設定 `bootstrap_completed = true`
5	—	建立 session cookie
6	—	回應 302 導向 `/dashboard`

流程 4：登入後初始狀態

成功完成 bootstrap 後，畫面導向 Dashboard，使用者已登入 Admin 角色。

步驟	動作	系統反應
1	—	顯示 Dashboard 預設視圖
2	—	右上角顯示「歡迎 <顯示名稱>」toast（3 秒後自動消失）
3	—	頂部使用者選單顯示帳號名 + Admin 角色
4	—	左側導航顯示所有區塊（Admin 角色看得到 Settings / Audit）

流程 5：狀態總覽

完成 bootstrap 後系統進入「正常運作」狀態。/bootstrap 路徑從此失效。

+----------------+   bootstrap   +----------------+
| 未初始化       +-------------> | 已初始化       |
| bs=false        |              | bs=true         |
| /bootstrap 開啟 |              | /bootstrap 關閉 |
+----------------+              +----------------+
                                        |
                                        | 訪問 /bootstrap
                                        v
                                +----------------+
                                | 導向 /login   |
                                +----------------+

狀態	進入條件	系統表現
未初始化	平台 cold start	任何 URL 自動導向 `/bootstrap`
已初始化	bootstrap 成功完成	正常運作；`/bootstrap` 訪問被導向 `/login`

Edge Cases 速查

情境	觸發條件	系統行為	你的下一步
密碼太弱	字數不足或缺類型	提交按鈕保持 disable + 紅標未達標項目	補足後重新提交
後端寫入失敗	DB 錯 / disk full	整個 transaction rollback、表單狀態保留	點重試或聯絡支援
兩瀏覽器同時 bootstrap	A 先提交完成	B 提交時收 409 + 導向 `/login`	改走登入流程
關閉瀏覽器再開	表單未提交	重新開啟回到空白表單	重新填寫
直接 POST `/bootstrap` API	繞過 UI	仍會檢查強度 + 防重入	修正請求參數
HTTP（非 HTTPS）請求	未升級	自動升級至 HTTPS 或拒絕	改用 HTTPS URL
稽核寫入失敗	DB 錯	整個 bootstrap rollback、顯示「儲存失敗」	聯絡支援檢查 DB