快速開始
本指南將協助你設定開發環境並啟動花店管理系統。
環境需求
後端 (app-server)
- Java 24 或以上（建議使用 SDKMAN 管理，專案已配置
.sdkmanrc） - Gradle 8.x（專案已包含 Gradle Wrapper）
- 資料庫：預設使用 H2（開發環境），生產環境支援 MySQL 8.0+ / PostgreSQL 15+ / SQL Server 2012+
前端 (app-web, app-web-mockup)
- Node.js 22.x
- npm 10.x
測試/生產環境需求
測試與生產環境的軟體需求（Tomcat、資料庫等），請參閱環境配置。
專案結構
florist/
├── app-web-mockup/ # Prototype 前端（使用 Mock API 進行需求確認）
├── app-web/ # React SPA 生產前端（支援 Mock/真實 API 切換）
├── app-server/ # Spring Boot RESTful 後端
├── app-web-host/ # 前端托管層（SPA + Spring Boot 整合打包）
├── app-docs/ # 文檔站（本站）
└── app-docs-host/ # 文檔站托管層
模組說明
| 模組 | 說明 | API 模式 |
|---|---|---|
| app-web-mockup | Prototype，用於需求確認與設計驗證 | Mock API (MSW) |
| app-web | React SPA 生產實作 | 支援 Mock → 真實 API 漸進式切換 |
| app-server | Spring Boot RESTful API | 真實 API + 資料庫 |
| app-web-host | 將 app-web 與 Spring Boot 整合打包成 WAR | N/A |
| app-docs | Docusaurus 文檔站 | N/A |
| app-docs-host | 將 app-docs 與 Spring Boot 整合打包成 WAR | N/A |
啟動步驟
開發模式 A：使用 Prototype（推薦新手）
適合快速體驗系統功能，無需啟動後端：
cd app-web-mockup
npm install
npm run dev
Prototype 將在 http://localhost:3001 啟動，使用 Mock API 模擬所有後端功能。
開發模式 B：前後端分離開發
1. 啟動後端
cd app-server
./gradlew bootRun
後端將在 http://localhost:8080/app-server 啟動。
H2 Console
開發環境預設使用 H2 資料庫，可透過 http://localhost:8080/app-server/h2-console 存取資料庫管理介面。
2. 啟動前端
cd app-web
npm install
npm run dev
前端將在 http://localhost:3000 啟動。
3. 使用 Mock API（可選）
app-web 支援 Mock API 用於後端功能尚未實作時的開發：
開發模式（Vite dev server）：
Mock API 預設自動啟用，無需額外設定：
cd app-web
npm run dev # Mock API 自動啟用
測試/生產環境（app-web-host 部署於 Tomcat）：
透過後端配置 app.msw.enabled=true 啟用 Mock API。
預設帳號
開發環境預設帳號統一使用密碼：Password123!
| 帳號 | 角色 | 說明 |
|---|---|---|
admin | 租戶管理員 | 租戶內最高權限 |
manager | 店長 | 完整業務權限 |
sales | 銷售人員 | 訂單與客戶管理 |
florist | 花藝師 | 花藝設計與製作 |
delivery | 配送員 | 訂單配送 |
accountant | 會計 | 僅讀取權限 |
完整帳號與權限資訊
詳見範例專案的 角色權限設計
開發流程建議
1. Prototype 階段（app-web-mockup）
└─→ 使用 Mock API 快速確認需求與 UI/UX
2. 前端生產實作（app-web）
└─→ 從 app-web-mockup 同步程式碼
└─→ 初期使用 Mock API，逐步切換到真實 API
3. 後端生產實作（app-server）
└─→ 實作 RESTful API
└─→ 前端逐步切換到真實 API