快速開始
本指南將協助你設定開發環境並啟動透過 /scaffold-project 建立的 AppFuse 專案。
環境需求
後端
- Java 25 或以上（建議使用 SDKMAN 管理，專案已配置
.sdkmanrc） - Gradle 8.x（專案已包含 Gradle Wrapper）
- 資料庫：預設使用 H2（開發環境），生產環境支援 MySQL 8.0+ / PostgreSQL 15+ / SQL Server 2012+
前端
- Node.js 22.x（建議使用 Volta 管理，專案已配置
volta設定） - npm 10.x
:::info 測試/生產環境需求 測試與生產環境的軟體需求（Tomcat、資料庫等），請參閱環境配置。 :::
專案結構
以下以專案名稱 myapp 為例，模組由 /scaffold-module 依開發階段逐步加入：
myapp/modules/
├── myapp-office-mockup/ # Prototype 前端（使用 Mock API 進行需求確認）
├── myapp-docs/ # 專案文檔站
├── myapp-office/ # React SPA 生產前端（支援 Mock/真實 API 切換）
├── myapp-server/ # Spring Boot RESTful 後端
├── myapp-office-host/ # 前端托管層（SPA + Spring Boot 整合打包）
└── myapp-docs-host/ # 文檔站托管層
模組說明
| 模組 | 說明 | API 模式 |
|---|---|---|
| {name}-web-mockup | Prototype，用於需求確認與設計驗證 | Mock API (MSW) |
| {name}-web | React SPA 生產實作 | 支援 Mock → 真實 API 漸進式切換 |
| {name}-server | Spring Boot RESTful API | 真實 API + 資料庫 |
| {name}-web-host | 將前端與 Spring Boot 整合打包成 WAR | N/A |
| {name}-docs | Docusaurus 文檔站 | N/A |
| {name}-docs-host | 將文檔站與 Spring Boot 整合打包成 WAR | N/A |
啟動步驟
開發模式 A：使用 Prototype（推薦新手）
適合快速體驗系統功能，無需啟動後端：
cd myapp-office-mockup
npm install
npm run dev
Prototype 將在 http://localhost:3001 啟動，使用 Mock API 模擬所有後端功能。
開發模式 B：前後端分離開發
1. 啟動後端
cd myapp-server
./gradlew bootRun
後端將在 http://localhost:8080 啟動。
:::tip H2 Console
開發環境預設使用 H2 資料庫，可透過 H2 Console 存取資料庫管理介面，路徑依 application.yml 設定而異。
:::
2. 啟動前端
cd myapp-office
npm install
npm run dev
前端將在 http://localhost:3000 啟動。
3. 使用 Mock API（可選）
前端模組支援 Mock API 用於後端功能尚未實作時的開發：
開發模式（Vite dev server）：
Mock API 預設自動啟用，無需額外設定：
cd myapp-office
npm run dev # Mock API 自動啟用
測試/生產環境（web-host 部署於 Tomcat）：
透過後端配置 app.msw.enabled=true 啟用 Mock API。
預設帳號
開發環境預設帳號統一使用密碼：Password123!
| 帳號 | 角色 | 說明 |
|---|---|---|
admin | 租戶管理員 | 租戶內最高權限 |
user | 一般使用者 | 基本讀取權限 |
:::tip 自訂帳號
專案可在 {name}-web/src/mocks/data/test-accounts.ts 定義更多業務角色的測試帳號。
:::
開發流程建議
1. Prototype 階段（{name}-web-mockup）
└─→ 使用 Mock API 快速確認需求與 UI/UX
2. 前端生產實作（{name}-web）
└─→ 從 Prototype 同步程式碼
└─→ 初期使用 Mock API，逐步切換到真實 API
3. 後端生產實作（{name}-server）
└─→ 實作 RESTful API
└─→ 前端逐步切換到真實 API