環境準備

0開始之前

全部指令都在 macOS 的「終端機」裡打（下面會教怎麼開）。卡住任何一步就截圖問 Raymond，不要硬猜。 整頁做完一次之後，之後每次開工只要「開終端機 → cd 切到專案資料夾」就緒。

1第 1 步 · 認識「終端機」

「終端機」是一個跟電腦用打字下指令的黑色視窗（不是用滑鼠點的）。文件裡凡是 像這樣一格灰底的字，就是「複製這行、貼到終端機、按 Enter」。

開啟方式：按 Cmd + 空白鍵 叫出 Spotlight → 輸入「終端機」或「Terminal」→ 按 Enter。

2第 2 步 · 裝三個工具

這三個是跑教學影片的必備工具，各裝一次。先檢查是不是已經裝好了——把下面三行貼到終端機，有印出版本號就代表裝好、可跳過該項：

node -v          # 有印出像 v22.x.x 就 OK
git --version    # 有印出 git version ... 就 OK
claude       # 有進入 Claude Code 就 OK（打 /exit 離開）

沒裝好的才裝：

3第 3 步 · 把專案抓下來（三個都要）

產線本體在 compliance-manager-test，但 AI 起草腳本時要讀的「料」散在另外兩個專案——三個都 clone，AI 才有足夠的參考文件：

跟 Raymond 要三個專案的 Git 網址，然後（<網址> 換成他給的）：

# 切到你想放專案的資料夾，例如「文件」——三個專案放同一層
cd ~/Documents

git clone <test網址> compliance-manager-test
git clone <be網址> compliance-manager-be
git clone <fe網址> compliance-manager-fe

# 進到產線專案 —— 這就是上面說的「在專案資料夾下」
cd compliance-manager-test

# 裝相依套件（只有 test 專案要跑；be/fe 只是給 AI 讀，不用裝）
npm install

4第 4 步 · 確認連對測試環境

影片是去測試站上操作錄下來的，不是正式環境——測試站是公司內網的一台測試伺服器（所以要在公司網路 / VPN 內才連得到）。連哪個站、用什麼帳號，都寫在專案根目錄的設定檔 .env.e2e 裡。

這個檔不會跟著專案下載（裡面有密碼，不進版控），但專案附了範本 .env.e2e.example——複製一份、改名、填一個密碼就好：

# 在專案資料夾下，把範本複製成正式設定檔
cp .env.e2e.example .env.e2e

然後用編輯器打開 .env.e2e，找到這一行、填上測試密碼（跟 Raymond 要）：

TEST_PASSWORD=          ← 等號後面填密碼

其他都不用動——測試站網址（BASE_URL）、各角色帳號（blsadmin、blsit…）範本都預填好了，範本註解也寫了每個帳號對應哪個角色。

5第 5 步 · 存登入狀態（auth:save）

影片裡不會出現「登入畫面」——因為我們事先把各角色的登入狀態存起來，錄影時直接載入，省得每支影片都演一次登入。這個「存登入狀態」的動作就是 auth:save，每個角色存一次即可，之後長期有效：

npm run auth:save -- --role admin
npm run auth:save -- --role pm

系統有哪些角色可以用（--role 後面能填的值）：

• 它會開一個瀏覽器、用 .env.e2e 裡對應角色的帳密登入一次，把登入狀態存成 support/auth-states/{角色}.json。
• 先存 admin 和 pm 就夠開工；其他角色等影片需要演到再存。
• 存好之後就不用管它了；哪天影片突然變成「未登入」畫面，多半是這個狀態過期了 → 重跑一次這行（詳見「疑難排解與速查」頁）。