本地運行

本指南說明如何在本地環境運行花店管理系統。

前置條件

確認你已完成環境設定。

啟動方式

方式一：僅前端（使用 Mock API）

適合：

前端功能開發
UI/UX 調整
不需要真實後端資料

cd app-web

# 啟動前端（預設使用 Mock API）
npm run dev

訪問 http://localhost:3000

優點：

不需要啟動後端和資料庫
快速啟動
可離線開發

限制：

使用模擬資料（MSW）
無法測試真實 API 整合

方式二：前後端整合

適合：

API 整合測試
完整功能測試
真實資料流測試

1. 啟動資料庫（可選）

注意：後端預設使用 H2 嵌入式資料庫，開發時無需額外啟動資料庫。H2 Console 可透過 http://localhost:8080/app-server/h2-console 存取。

如需使用 PostgreSQL，請修改 application.yml 並啟動資料庫：

使用 Docker：

# 啟動 PostgreSQL
docker start app-postgres

# 如果容器不存在，建立新容器
docker run --name app-postgres \
  -e POSTGRES_DB=appdb \
  -e POSTGRES_USER=appmgr \
  -e POSTGRES_PASSWORD=app1943 \
  -p 5432:5432 \
  -d postgres:16

或使用本地 PostgreSQL：

# macOS (Homebrew)
brew services start postgresql@16

2. 啟動後端

cd app-server

# 使用 Gradle 啟動（推薦用於開發）
./gradlew bootRun

後端應該會在 http://localhost:8080/app-server 啟動。

驗證後端：

# 檢查健康狀態
curl http://localhost:8080/app-server/actuator/health

# 應該回應：
# {"status":"UP"}

注意：後端有設定 context-path /app-server，所有 API 路徑都需要加上此前綴。

3. 啟動前端（連接後端）

cd app-web

# 啟動前端開發伺服器
npm run dev

訪問 http://localhost:3000

注意：前端的 API baseURL 由 config.ts 中的 app.baseURL 配置控制。開發環境連接後端時，需確保後端已啟動且 MSW 已關閉。

開發模式

Mock API 模式（預設）

前端使用 MSW (Mock Service Worker) 模擬 API。開發環境（npm run dev）預設啟用 MSW。

配置位置（app-web/src/conf/config.ts）：

export const config: AppEnvironConfig = {
  app: {
    // ...
    msw: {
      enabled: import.meta.env.DEV, // 開發環境預設啟用 MSW
    },
  },
}

特性：

在瀏覽器中攔截 API 請求
回應模擬資料
不需要後端
支援離線開發

查看 Mock Handlers：app-web/src/mocks/handlers/

真實 API 模式

關閉 MSW 以連接真實後端：

// app-web/src/conf/config.ts
export const config: AppEnvironConfig = {
  app: {
    // ...
    baseURL: '/app-server', // 指向後端 context-path
    msw: {
      enabled: false, // 關閉 MSW
    },
  },
}

特性：

使用真實後端 API
真實資料庫資料
可測試完整流程

混合模式（漸進式切換）

MSW 配置 onUnhandledRequest: 'bypass'，未匹配的請求會繼續傳送到真實後端。可透過註解 handler 來選擇性使用真實 API：

// app-web/src/mocks/handlers/index.ts
export const handlers: RequestHandler[] = [
  ...authHandlers,
  ...dashboardHandlers,
  ...orderHandlers,
  ...customerHandlers,
  // ...productHandlers,  // 註解後使用真實 Product API
  ...referenceDataHandlers,
  ...fileHandlers,
];

預設帳號

Mock 環境測試帳號

MSW Mock 環境的測試帳號（定義於 app-web/src/mocks/data/test-accounts.ts）：

帳號	角色	說明
`superadmin`	超級管理員	系統最高權限，跨租戶管理
`admin`	租戶管理員	租戶內完整管理權限
`manager`	店長	業務管理權限
`sales`	銷售人員	訂單與客戶管理
`florist`	花藝師	商品與訂單檢視
`delivery`	配送員	訂單配送操作
`accountant`	會計	唯讀財務報表
`user`	一般使用者	基本讀取權限

統一密碼：所有測試帳號密碼為 Password123!

查看完整測試資料：app-web/src/mocks/data/test-accounts.ts

除錯

前端除錯

Chrome DevTools

開啟 Chrome DevTools（F12）
Sources → 設定中斷點
重新載入頁面

VS Code 除錯

.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/src"
    }
  ]
}

後端除錯

IntelliJ IDEA

開啟 AppServer.java
點擊行號旁的綠色箭頭
選擇 "Debug 'AppServer'"

VS Code

安裝 Java Extension Pack，然後 F5 啟動除錯。

熱重載

前端熱重載

Vite 預設支援熱重載：

npm run dev

修改 .tsx、.css 檔案會自動重新載入。

後端熱重載

使用 Spring Boot DevTools：

./gradlew bootRun

修改 Java 檔案後，IDE 會自動重新編譯（IntelliJ IDEA 需開啟 "Build project automatically"）。

環境配置

前端配置

前端配置位於 app-web/src/conf/config.ts：

export const config: AppEnvironConfig = {
  app: {
    name: 'App',
    version: '1.0.0',
    stage: import.meta.env.MODE,
    basename: '/',
    baseURL: '/', // API 基礎 URL
    msw: {
      enabled: import.meta.env.DEV, // 開發環境啟用 MSW
    },
  },
  i18n: {
    language: 'zh-TW',
    fallback: 'en',
    languages: ['en', 'zh-TW'],
  },
}

後端配置

application.yml（主要配置）：

server:
  servlet:
    context-path: /app-server

spring:
  datasource:
    # 預設使用 H2 嵌入式資料庫
    driver-class-name: org.h2.Driver
    url: jdbc:h2:file:${user.home}/Project/appfuse/var/data/app-server/appdb
    username: appmgr
    password: app1943

  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

  h2:
    console:
      enabled: true
      path: /h2-console

logging:
  level:
    io.leandev.app: DEBUG
    io.leandev.appfuse: DEBUG

app:
  cors:
    allowed-origins: "http://localhost:*"

常用指令

前端

# 開發模式
npm run dev

# 建置（含型別檢查）
npm run build

# 預覽建置結果
npm run preview

# Lint
npm run lint

# 格式化程式碼
npm run format

# 檢查格式
npm run format:check

# 測試
npm run test

# 測試覆蓋率
npm run coverage

後端

# 開發模式
./gradlew bootRun

# 建置
./gradlew clean build

# 執行測試
./gradlew test

注意：後端使用 Hibernate auto DDL（ddl-auto: update），無需手動執行資料庫遷移。

故障排除

前端無法啟動

錯誤：Port 3000 is already in use

解決：

# 找出佔用端口的程式
lsof -i :3000

# 終止程式
kill -9 <PID>

後端無法啟動

錯誤：H2 資料庫鎖定

解決：關閉其他可能使用該資料庫的程式，或刪除 lock 檔案：

# 刪除 H2 資料庫 lock 檔案
rm ~/Project/appfuse/var/data/app-server/appdb.lock.db

API 請求失敗

錯誤：CORS 錯誤

解決：確認後端 CORS 配置允許前端 origin

# application.yml
app:
  cors:
    allowed-origins: "http://localhost:*"

MSW 未攔截請求

現象：API 請求直接發送到後端而非被 Mock 攔截

解決：

確認 config.ts 中 app.msw.enabled 為 true
確認 public/mockServiceWorker.js 存在
檢查 Console 是否有 [MSW] Mock Service Worker started 訊息

下一步

開發流程 - 了解日常開發流程
前端開發指南 - 開發前端功能
後端開發指南 - 開發後端功能

前置條件​

啟動方式​

方式一：僅前端（使用 Mock API）​

方式二：前後端整合​

1. 啟動資料庫（可選）​

2. 啟動後端​

3. 啟動前端（連接後端）​

開發模式​

Mock API 模式（預設）​

真實 API 模式​

混合模式（漸進式切換）​

預設帳號​

Mock 環境測試帳號​

除錯​

前端除錯​

Chrome DevTools​

VS Code 除錯​

後端除錯​

IntelliJ IDEA​

VS Code​

熱重載​

前端熱重載​

後端熱重載​

環境配置​

前端配置​

後端配置​

常用指令​

前端​

後端​

故障排除​

前端無法啟動​

後端無法啟動​

API 請求失敗​

MSW 未攔截請求​

下一步​