環境設定

本指南將協助你設定花店管理系統的開發環境。

系統需求

必要工具

工具	版本	用途
Node.js	22.19.0	前端開發與建置
Java	24（執行）/ 25（編譯目標）	後端開發
Git	最新版	版本控制

資料庫

環境	資料庫	說明
開發環境	H2（預設）	嵌入式資料庫，無需安裝，開箱即用
生產環境	MySQL 8.x / SQL Server 2012+ / PostgreSQL 8.2+	依需求選擇

版本管理工具

工具	用途	說明
Volta	Node.js 版本管理	專案已配置 `volta` 設定，自動切換版本
SDKMAN	Java 版本管理	專案已配置 `.sdkmanrc`，自動切換版本

工具	用途
VS Code	IDE（專案已內建工作區配置）
Bruno	API 測試（專案已內建規格於 `app-server/bruno/`）
DBeaver	資料庫管理（支援 H2 及各種生產環境資料庫）

安裝步驟

1. 安裝 Node.js

使用 Volta（推薦）：

Volta 會自動讀取專案中的 package.json 設定，確保使用正確的 Node.js 版本。

# 安裝 Volta
curl https://get.volta.sh | bash

# 重新載入 shell 設定
source ~/.bashrc  # 或 source ~/.zshrc

# 驗證 Volta 安裝
volta --version

# Volta 會在進入專案目錄時自動安裝並使用正確版本
cd app-web
node --version  # 應顯示 v22.19.0

專案配置（app-web/package.json）：

{
  "volta": {
    "node": "22.19.0"
  }
}

Volta 與 nvm 的差異：Volta 會自動根據專案配置切換版本，無需手動 nvm use。

2. 安裝 Java

使用 SDKMAN（推薦）：

SDKMAN 會自動讀取專案中的 .sdkmanrc 設定，確保使用正確的 Java 版本。

# 安裝 SDKMAN
curl -s "https://get.sdkman.io" | bash

# 重新載入 shell 設定
source ~/.bashrc  # 或 source ~/.zshrc

# 啟用自動切換功能（重要！）
sdk config
# 設定 sdkman_auto_env=true

# 驗證 SDKMAN 安裝
sdk version

# SDKMAN 會在進入專案目錄時自動使用正確版本
cd app-server
java -version  # 應顯示 openjdk version "24.0.1"

專案配置（app-server/.sdkmanrc）：

# 使用 JDK 24 執行 Gradle（避免 Kotlin DSL 相容性問題）
# 編譯目標 JDK 25 由 build.gradle.kts toolchain 設定
java=24.0.1-tem

版本說明：

JDK 24.0.1-tem：Gradle daemon 執行使用，避免 Kotlin DSL 相容性問題
JDK 25：編譯目標，由 Gradle toolchain 自動下載管理

Gradle toolchain 配置（build.gradle.kts）：

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

首次建置時，Gradle 會自動下載 JDK 25 用於編譯，無需手動安裝。

其他平台

從 Adoptium 下載 JDK 24（Temurin 發行版）。

3. 安裝 Git

macOS

# 使用 Homebrew
brew install git

# 或使用 Xcode Command Line Tools
xcode-select --install

其他平台

從 Git 官網下載安裝。

專案設定

1. Clone 專案

# Clone 專案（Monorepo 結構）
git clone git@gitlab.com:appfuse/webapp/appfuse-webapps-v1.git
cd appfuse-webapps-v1/modules

專案結構：

appfuse-webapps-v1/modules/
├── app-server/      # 後端參考實作
├── app-web/         # 前端參考實作（生產）
├── app-web-mockup/  # 前端參考實作（Prototype）
├── appfuse-server/  # 後端框架
├── appfuse-web/     # 前端框架
└── appfuse-docs/    # 文檔站

2. 後端設定

cd app-server

# 建置專案
./gradlew clean build

# 啟動應用程式
./gradlew bootRun

預設資料庫：使用 H2 嵌入式資料庫，資料存放於 ~/Project/appfuse/var/data/app-server/appdb。 Hibernate 會自動建立 Schema（ddl-auto: update），無需手動遷移。

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

驗證：訪問 http://localhost:8080/actuator/health

3. 前端設定

cd app-web

# 安裝依賴
npm install

# 啟動開發伺服器（使用 Mock API）
npm run dev

前端應該會在 http://localhost:3000 啟動。

Mock API：開發環境預設使用 MSW（Mock Service Worker）模擬後端 API，無需啟動 app-server 即可開發前端。

IDE 設定

VS Code 工作區（推薦）

專案提供完整的 VS Code 工作區配置，可同時開發前後端：

開啟工作區：File → Open Workspace from File → 選擇 modules/appfuse-webapp.code-workspace
安裝推薦擴充功能：VS Code 會自動提示安裝各模組推薦的擴充功能

工作區包含的模組：

框架：appfuse-web、appfuse-server
參考實作：app-web、app-web-mockup、app-server
文檔：appfuse-docs、app-docs

後端開發擴充功能（app-server/.vscode/extensions.json）：

Extension Pack for Java
Gradle for Java
Spring Boot Extension Pack
Kotlin Language
SonarLint

前端開發擴充功能（app-web/.vscode/extensions.json）：

ESLint
Prettier
Tailwind CSS IntelliSense

啟動與除錯

後端：在 VS Code 側邊欄的「Spring Boot Dashboard」點擊 app-server 啟動

前端：在終端機執行 npm run dev

驗證環境

執行以下命令確認環境正確：

# 版本管理工具
volta --version   # 應顯示 Volta 版本
sdk version       # 應顯示 SDKMAN 版本

# Node.js 版本（在 app-web 目錄中）
cd app-web
node --version    # v22.19.0

# Java 版本（在 app-server 目錄中）
cd app-server
java -version     # openjdk version "24.0.1" (Temurin)

# Git 版本
git --version     # git version 2.x.x

注意：Node.js 和 Java 版本會根據專案目錄自動切換，請確保在正確的目錄中執行驗證。

常見問題

H2 Console 存取

開發環境可透過 H2 Console 檢視資料庫：

URL：http://localhost:8080/app-server/h2-console
JDBC URL：jdbc:h2:file:~/Project/appfuse/var/data/app-server/appdb
Username：appmgr
Password：app1943

切換至生產環境資料庫

修改 application.yml 或建立 application-prod.yml：

spring:
  datasource:
    # MySQL 8.x
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://<host>:<port>/<database>?useUnicode=true&characterEncoding=UTF-8&useSSL=false

    # SQL Server 2012+
    # driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
    # url: jdbc:sqlserver://<host>:<port>;databaseName=<database>;...

    # PostgreSQL 8.2+
    # driver-class-name: org.postgresql.Driver
    # url: jdbc:postgresql://<host>:<port>/<database>

Gradle 建置失敗

錯誤：Could not resolve toolchain

解決：Gradle toolchain 會自動下載 JDK 25，確保網路連線正常

# 清除 Gradle 快取並重新建置
./gradlew clean build --refresh-dependencies

錯誤：Kotlin DSL 相容性問題

解決：確認使用 JDK 24 執行 Gradle

# 確認 .sdkmanrc 設定
cd app-server
cat .sdkmanrc  # 應顯示 java=24.0.1-tem

# 確認當前 Java 版本
java -version  # 應顯示 openjdk version "24.0.1"

# 如果版本不對，重新進入目錄觸發自動切換
cd .. && cd app-server

SDKMAN 未自動切換版本

現象：進入專案目錄後 Java 版本沒有自動切換

解決：啟用 SDKMAN 自動切換功能

# 編輯 SDKMAN 設定
sdk config
# 或直接編輯設定檔
vim ~/.sdkman/etc/config

# 設定 sdkman_auto_env=true
# 重新開啟終端機

npm install 失敗

錯誤：網路相關錯誤

解決：

# 清除 npm 快取
npm cache clean --force

# 重新安裝
rm -rf node_modules package-lock.json
npm install

下一步

環境設定完成後：

本地運行 - 在本地啟動專案
開發流程 - 了解日常開發流程
系統架構 - 了解系統整體架構

系統需求​

必要工具​

資料庫​

版本管理工具​

推薦工具​

安裝步驟​

1. 安裝 Node.js​

2. 安裝 Java​

其他平台​

3. 安裝 Git​

macOS​

其他平台​

專案設定​

1. Clone 專案​

2. 後端設定​

3. 前端設定​

IDE 設定​

VS Code 工作區（推薦）​

啟動與除錯​

驗證環境​

常見問題​

H2 Console 存取​

切換至生產環境資料庫​

Gradle 建置失敗​

SDKMAN 未自動切換版本​

npm install 失敗​

下一步​

系統需求

必要工具

資料庫

版本管理工具

推薦工具

安裝步驟

1. 安裝 Node.js

2. 安裝 Java

其他平台

3. 安裝 Git

macOS

其他平台

專案設定

1. Clone 專案

2. 後端設定

3. 前端設定

IDE 設定

VS Code 工作區（推薦）

啟動與除錯

驗證環境

常見問題

H2 Console 存取

切換至生產環境資料庫

Gradle 建置失敗

SDKMAN 未自動切換版本

npm install 失敗

下一步