本地運行
本指南深入說明 AppFuse 專案在本地運行時的 API 模式切換與故障排除。啟動指令請參閱快速開始。
前置條件
確認你已完成環境設定。
啟動方式總覽
| 方式 | 啟動模組 | API 來源 | 適合場景 |
|---|---|---|---|
| 僅前端 | myapp-office | Mock API (MSW) | 前端開發、UI/UX 調整、離線開發 |
| 前後端整合 | myapp-server + myapp-office | 真實 API | API 整合測試、完整功能驗證 |
| 混合模式 | myapp-server + myapp-office | Mock + 真實 API 混用 | 後端功能逐步上線 |
前兩種方式的啟動步驟見快速開始，以下聚焦說明各模式的運作原理與切換方式。
API 模式詳解
Mock API 模式（預設）
前端使用 MSW (Mock Service Worker) 在瀏覽器中攔截 API 請求並回應模擬資料。開發環境（npm run dev）預設啟用。
運作方式：
瀏覽器發出 API 請求 → MSW Service Worker 攔截 → 比對 Mock Handler → 回傳模擬資料
配置位置（myapp-office/src/conf/config.ts）：
msw: {
enabled: import.meta.env.DEV, // 開發環境自動啟用
},
確認 MSW 已啟動：瀏覽器 Console 應顯示 [MSW] Mock Service Worker started。
Mock Handler 目錄：myapp-office/src/mocks/handlers/，每個業務領域一個檔案，在 index.ts 中彙整。
真實 API 模式
關閉 MSW 並將 baseURL 指向後端 context-path：
// myapp-office/src/conf/config.ts
app: {
baseURL: '/myapp-server',
msw: {
enabled: false,
},
},
需確保後端已啟動於 http://localhost:8080/myapp-server。
混合模式（漸進式切換）
混合模式是 AppFuse 推薦的漸進式開發策略：後端 API 逐步實作完成時，前端逐一從 Mock 切換到真實 API，而非一次性全部切換。
原理：MSW 配置了 onUnhandledRequest: 'bypass'，未被 Mock Handler 匹配的請求會穿透到真實後端。因此只要移除特定領域的 Handler，該領域的請求就會自動導向後端。
操作方式：
// myapp-office/src/mocks/handlers/index.ts
export const handlers: RequestHandler[] = [
...authHandlers,
...dashboardHandlers,
...orderHandlers,
...customerHandlers,
// ...productHandlers, // ← 註解後，Product API 改走真實後端
...referenceDataHandlers,
...fileHandlers,
];
使用流程：
config.ts維持msw.enabled = true，baseURL指向後端- 後端完成某個領域的 API（如 Product）
- 在
handlers/index.ts註解該領域的 Handler - 該領域的請求自動導向真實後端，其餘領域維持 Mock
- 重複步驟 2–4 直到所有 API 切換完成
:::tip 混合模式下的 baseURL
混合模式需要將 baseURL 設為後端 context-path（如 /myapp-server），讓穿透的請求能正確到達後端。Mock Handler 的回應不受 baseURL 影響。
:::
測試帳號
開發環境預設帳號見快速開始 — 預設帳號。
Mock 環境額外提供 superadmin（超級管理員，跨租戶管理）帳號，密碼同為 Password123!。
專案可在 myapp-office/src/mocks/data/test-accounts.ts 自訂更多業務角色的測試帳號。
熱重載
| 端 | 機制 | 說明 |
|---|---|---|
| 前端 | Vite HMR | 修改 .tsx、.css 檔案即時生效，無需手動重載 |
| 後端 | Spring Boot DevTools | 修改 Java 檔案後 IDE 自動重新編譯（IntelliJ 需開啟 "Build project automatically"） |
故障排除
Port 3000 已被佔用
lsof -i :3000
kill -9 <PID>
H2 資料庫鎖定導致後端無法啟動
關閉其他可能使用該資料庫的程式，或刪除 lock 檔案：
rm ~/Project/myapp/var/data/myapp-server/myappdb.lock.db
CORS 錯誤
後端的 application.yml 預設已配置 app.cors.allowed-origins: "http://localhost:*"，開發環境通常不需調整。
若因特殊需求需要覆蓋，在外部設定檔 $APP_HOME/conf/myapp-server.yml 中設定：
app:
cors:
allowed-origins: "http://localhost:*,http://192.168.1.100:*"
MSW 未攔截請求
API 請求直接發送到後端而非被 Mock 攔截時，依序檢查：
config.ts中app.msw.enabled是否為truepublic/mockServiceWorker.js是否存在（不存在則執行npx msw init public --save）- 瀏覽器 Console 是否顯示
[MSW] Mock Service Worker started