系統架構
花店管理系統採用前後端分離架構，基於 AppFuse 快速開發框架建構，採用 Prototype → 生產實作 的漸進式開發流程。
整體架構
模組關係
| 模組 | 類型 | 說明 | API 模式 |
|---|---|---|---|
| app-web-mockup | Prototype | 需求確認、UI/UX 設計驗證 | Mock API (MSW) |
| app-web | 生產前端 | React SPA 生產實作 | Mock → 真實 API 漸進切換 |
| app-server | 生產後端 | RESTful API + 資料庫 | 真實 API |
| app-web-host | 托管層 | 將 SPA 與 Spring Boot 整合打包 | N/A |
| app-docs | 文檔站 | Docusaurus 應用文檔 | N/A |
| app-docs-host | 托管層 | 將文檔站與 Spring Boot 整合打包 | N/A |
技術棧
後端 (app-server)
| 層級 | 技術 |
|---|---|
| Framework | Spring Boot 3.x |
| Security | Spring Security + JWT |
| ORM | Spring Data JPA + Hibernate |
| Database | H2（開發預設）/ MySQL 8.0+ / PostgreSQL 15+ / SQL Server 2012+ |
| API Docs | Spring REST Docs |
| Build | Gradle (Kotlin DSL) |
前端 (app-web, app-web-mockup)
| 層級 | 技術 |
|---|---|
| Framework | React 19 + TypeScript |
| State | Redux Toolkit |
| Routing | React Router |
| UI | Tailwind CSS + AppFuse Components |
| Mock | MSW (Mock Service Worker) |
| Build | Vite |
托管層 (app-web-host, app-docs-host)
| 層級 | 技術 |
|---|---|
| Framework | Spring Boot 3.x |
| 功能 | SPA 路由轉發、CSP nonce 注入、安全 Headers |
| 部署 | WAR（整合靜態資源） |
模組結構
app-server
app-server/
├── src/main/java/
│ └── io/leandev/app/
│ ├── config/ # 配置類
│ ├── controller/ # REST API 層
│ ├── dto/ # 資料傳輸物件
│ ├── entity/ # JPA 實體
│ │ ├── customer/ # 客戶
│ │ ├── order/ # 訂單
│ │ └── sales/ # 產品
│ ├── repository/ # 資料存取層
│ ├── service/ # 業務邏輯層
│ └── security/ # 安全相關
└── src/test/
app-web / app-web-mockup
兩者結構相同，app-web-mockup 作為設計指引，app-web 從其同步程式碼：
app-web/
├── src/
│ ├── applets/ # 業務功能模組
│ │ ├── customer/
│ │ ├── order/
│ │ └── product/
│ ├── components/ # 應用程式組件
│ ├── features/ # Redux slices
│ ├── layouts/ # 佈局組件
│ ├── mocks/ # MSW handlers
│ ├── services/ # API 服務層
│ └── routes/ # 路由配置
└── tests/
app-web-host
app-web-host/
├── src/main/java/
│ └── io/leandev/florist/host/
│ ├── config/ # 安全配置（CSP、HSTS）
│ └── controller/ # SPA 路由轉發
├── src/main/resources/
│ └── static/ # app-web build 輸出
└── build.gradle.kts
框架依賴
本專案使用 AppFuse 框架提供的基礎設施：
┌─────────────────────────────────────────────────────────────┐
│ AppFuse Framework (框架層) │
├─────────────────────────────────────────────────────────────┤
│ appfuse-server Spring Boot 工具集 │
│ - HTTP Client、CSV 處理、檔案存儲 │
│ - Security utilities、Audit logging │
├─────────────────────────────────────────────────────────────┤
│ appfuse-web React 組件庫 │
│ - 表單、表格、佈局組件 │
│ - Application Shell、i18n │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 花店管理系統 (參考實作) │
├─────────────────────────────────────────────────────────────┤
│ app-web-mockup ──→ app-web ←──→ app-server │
│ (Prototype) (SPA) (API) │
└─────────────────────────────────────────────────────────────┘
框架引用方式
| 模組 | 引用方式 |
|---|---|
| app-web-mockup | npm 安裝編譯後的 @appfuse/appfuse-web |
| app-web | npm 安裝編譯後的 @appfuse/appfuse-web |
| app-server | Gradle 依賴編譯後的 @appfuse/appfuse-server |
詳細框架文檔請參閱 AppFuse 框架文檔。
開發流程
- Prototype 階段：在 app-web-mockup 使用 Mock API 快速驗證需求
- 前端實作：從 mockup 同步程式碼到 app-web，初期使用 Mock API
- 後端實作：在 app-server 實作 RESTful API
- 漸進切換：app-web 逐步從 Mock API 切換到真實 API
- 整合打包：透過 app-web-host 將 SPA 與 Spring Boot 整合