本地部署

本文檔說明如何在本地環境部署和運行花店管理系統。

前置需求

• Java 25+
• Node.js 22.x
• PostgreSQL 15+（或使用 Docker）
• Gradle 8+

快速開始

1. 啟動資料庫

使用 Docker：

docker run -d \
  --name postgres \
  -e POSTGRES_USER=florist \
  -e POSTGRES_PASSWORD=florist \
  -e POSTGRES_DB=florist \
  -p 5432:5432 \
  postgres:15

2. 啟動後端

cd app-tenant-server
./gradlew bootRun

後端將在 http://localhost:8080/app-server 啟動。

3. 啟動前端

cd app-office
npm install
npm run dev

前端將在 http://localhost:3000 啟動。

開發模式配置

後端配置

# app-tenant-server/src/main/resources/application-local.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/florist
    username: florist
    password: florist

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

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

前端配置

// app-office/vite.config.ts
export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080/app-server',
        changeOrigin: true
      }
    }
  }
});

使用 Mock API

前端可以使用 MSW (Mock Service Worker) 模擬 API：

cd app-office
VITE_MSW=true npm run dev

統一部署模式

如需測試統一部署（WAR 模式）：

# 1. 建置前端
cd app-office
npm run build

# 2. 建置並啟動 WAR
cd ../app-office-host
./gradlew bootRun

應用將在 http://localhost:8080/app-office 啟動。app-office-host 的 Gradle build 會先 建置 hostedApp 指定的前端，再將 dist/ 複製到靜態資源目錄。

資料初始化

真實 Server 的資料初始化由應用 migration／seed 政策決定；不要假設存在固定帳密。 使用 MSW 時，測試帳號以目前 src/mocks/data/test-accounts.ts 為準。

常見問題

資料庫連線失敗

確認 PostgreSQL 正在運行：

docker ps | grep postgres

CORS 錯誤

確認後端已配置允許前端來源：

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

一般開發流程透過 Vite 同源 proxy 呼叫 Server，不需要瀏覽器跨 origin；只有繞過 proxy 直接呼叫 Server 時才會進入 CORS 判定。

連接埠被佔用

# 查找占用連接埠的程序
lsof -i :8080
lsof -i :3000

# 先嘗試正常終止程序
kill <PID>

下一步

• 開發流程 - 日常開發流程
• 測試環境部署 - 部署到測試環境