專案初始化指南

本指南說明如何使用 app* 參考實作來初始化基於 AppFuse 框架的新專案。

適用對象

準備使用 AppFuse 框架開發新應用程式的團隊
想要參考花店管理系統架構來建構自己業務系統的團隊
需要快速啟動專案並遵循最佳實踐的開發者

前置準備

環境需求

環境	需求
前端	Node.js 22.x、npm 10.x
後端	Java 24+（建議使用 SDKMAN，專案已配置 `.sdkmanrc`）
資料庫	H2（開發預設）/ MySQL 8.0+ / PostgreSQL 15+
IDE	VS Code + Java Extension Pack

建議的開發工具

工具	用途	安裝指南
git	版本控制	https://git-scm.com/
VS Code	整合開發環境	https://code.visualstudio.com/
SDKMAN	Java 版本管理	https://sdkman.io/
Volta	Node.js 版本管理	https://volta.sh/
Claude Code	AI 輔助開發	https://claude.ai/claude-code

開發環境資料庫

預設使用 H2 內嵌資料庫，無需額外安裝。生產環境可切換至 MySQL、PostgreSQL 或 SQL Server。

初始化步驟

步驟 1：建立專案目錄結構

建立專案根目錄與 modules 子目錄：

mkdir -p myapp/modules
cd myapp

目標結構（以 myapp 專案為例）：

myapp/                            # 專案根目錄
├── .git/                         # Git repository
├── .gitignore                    # Git 忽略規則
├── README.md                     # 專案說明
└── modules/                      # 模組目錄
    ├── .claude/                  # Claude Code 設定
    │   ├── rules/                # 專案開發規範
    │   └── skills/               # 自動化技能
    ├── CLAUDE.md                 # Claude Code 指令
    ├── myapp.code-workspace      # VS Code workspace
    ├── myapp-web-mockup/         # 前端 Prototype
    ├── myapp-web/                # 前端 SPA
    ├── myapp-server/             # 後端 API
    └── ...                       # 其他模組

步驟 2：初始化開發環境配置

從參考實作複製開發環境配置檔：

Git 配置

# 複製 .gitignore
cp /path/to/appfuse-webapp-v1/.gitignore myapp/

# 初始化 Git repository
cd myapp
git init

VS Code Workspace

複製並修改 workspace 檔案：

cp /path/to/appfuse-webapp-v1/modules/appfuse-webapp.code-workspace \
   myapp/modules/myapp.code-workspace

修改 myapp.code-workspace：

更新 folders 陣列，列出您的模組
保留 settings 中的 Java 配置

Claude Code 配置

# 複製 CLAUDE.md 與 .claude 目錄
cp /path/to/appfuse-webapp-v1/modules/CLAUDE.md myapp/modules/
cp -r /path/to/appfuse-webapp-v1/modules/.claude myapp/modules/

包含的配置：

目錄/檔案	說明
`CLAUDE.md`	Claude Code 專案指令
`.claude/rules/`	專案開發規範（語言、commit、架構等）
`.claude/skills/`	自動化技能（升級框架、發布等）

調整 Claude 規則

複製後請檢視 .claude/rules/ 中的規則，根據團隊需求調整。

步驟 3：複製參考實作模組

根據當前階段需求選擇要複製的模組。不需要一次初始化所有模組，可在日後根據需要再初始化其他模組。

模組	用途	初始化時機
app-web-mockup	前端 Prototype（Mock API）	⭐ Prototype 階段
app-web	前端 SPA 生產版	生產開發階段
app-server	後端 RESTful API	生產開發階段
app-web-host	前端 WAR 託管	準備部署時
app-docs	應用文檔站	需要文檔時
app-docs-host	文檔 WAR 託管	準備部署文檔時

漸進式初始化

建議從 Prototype 開始，待需求確認後，再初始化生產模組。

模組命名

模組名稱可自由命名。基本對應：

參考實作	初始化為
app-web-mockup	myapp-web-mockup
app-web	myapp-web
app-server	myapp-server
app-web-host	myapp-web-host
app-docs	myapp-docs

複製範例：

cd myapp/modules

# Prototype 階段
cp -r /path/to/appfuse-webapp-v1/modules/app-web-mockup myapp-web-mockup

# 生產階段
cp -r /path/to/appfuse-webapp-v1/modules/app-web myapp-web
cp -r /path/to/appfuse-webapp-v1/modules/app-server myapp-server

# 準備部署時再初始化
cp -r /path/to/appfuse-webapp-v1/modules/app-web-host myapp-web-host

# 需要文檔時再初始化
cp -r /path/to/appfuse-webapp-v1/modules/app-docs myapp-docs

進階：前後台分離

同一參考實作可初始化多個模組。例如需要前後台分離時：

參考實作	初始化為	用途
app-web	myapp-office	後台管理系統
app-web	myapp-portal	前台網站
app-server	myapp-server	共用後端 API

步驟 4：更新專案識別

VS Code Workspace

更新 workspace 檔名與 folders，列出已初始化的模組：

// myapp.code-workspace
{
  "folders": [
    { "path": "myapp-web-mockup" },
    { "path": "myapp-web" },
    { "path": "myapp-server" }
    // 日後初始化其他模組時再加入
  ],
  "settings": {
    // 保留原有設定
  }
}

漸進式更新

每次初始化新模組後，記得將其加入 VS Code workspace。

前端模組 (package.json)

{
  "name": "@myteam/myproject-web",
  "description": "My Project 前端應用",
  "volta": {
    "node": "22.19.0"
  }
}

後端模組

settings.gradle.kts：

rootProject.name = "myproject-server"

build.gradle.kts：

group = "com.mycompany.myproject"

Java package 路徑：

將 io.leandev.app 重新命名為 com.mycompany.myproject

SDKMAN 配置 (.sdkmanrc)

各後端模組已包含 .sdkmanrc，確認 Java 版本：

# .sdkmanrc
java=24.0.1-tem

步驟 5：配置框架依賴

前端 (.npmrc)

在各前端模組根目錄建立 .npmrc：

@appfuse:registry=https://devops.leandev.io/repository/npm-releases/

後端

Gradle repository 已在 build.gradle.kts 中預設配置，無需額外設定。

步驟 6：參考實作程式碼處理

保留花店管理系統程式碼供團隊參考。

參考實作中包含完整的「花店管理系統」業務邏輯，涵蓋：

前端：

src/applets/ - 業務模組（產品、訂單、客戶管理）
src/services/ - API 服務層
src/mocks/ - Mock API handlers 與種子數據
src/features/ - Redux slices

後端：

entity/ - JPA 實體
controller/ - REST API 端點
service/ - 業務邏輯層
repository/ - 資料存取層

保留供參考

建議在初始化階段保留這些程式碼，團隊可參考實作方式，自行決定移除時機。

步驟 7：驗證開發環境

使用 VS Code Workspace 開啟專案

code myapp/modules/myapp.code-workspace

啟動前端 Prototype

cd myapp/modules/myapp-web-mockup
npm install
npm run dev
# 開啟 http://localhost:3001

啟動後端

cd myapp/modules/myapp-server
./gradlew bootRun
# API 位於 http://localhost:8080/myapp-server

伺服器端口

Prototype (app-web-mockup): http://localhost:3001
前端 SPA (app-web): http://localhost:3000
後端 API (app-server): http://localhost:8080/app-server

開發流程

獨立發展

初始化後，團隊的專案模組即為獨立程式碼，不再與參考實作同步。框架更新透過 npm / Gradle 取得。

Prototype → 生產流程

Mock → 真實 API 漸進切換

app-web 透過 config.app.msw.enabled 控制 MSW：

環境	MSW 狀態	說明
開發環境（`npm run dev`）	自動啟用	所有 API 由 MSW 處理
生產環境（`npm run build`）	預設關閉	所有 API 連接真實後端

混合模式：MSW 設定 onUnhandledRequest: 'bypass'，未匹配的請求自動轉發到真實後端。移除對應的 handler 即可切換到真實 API。

詳細說明請參閱「Mock → 真實 API 漸進切換」

必讀文檔索引

按優先級閱讀：

優先級	文檔	說明
🔴 P0	快速開始	環境設定與啟動步驟
🔴 P0	專案程式結構	程式碼組織與各層職責
🟠 P1	系統架構	整體架構說明
🟠 P1	開發流程指南	完整 SCRUM 流程
🟡 P2	貢獻指南	開發規範與 Code Review
🟡 P2	規格撰寫指南	Epic、User Story、SBE 撰寫規範

框架使用指南

文檔	說明
AppFuse Web 指南	React 框架使用指南
AppFuse Server 指南	Spring 框架使用指南

常見問題 (FAQ)

Q: 可以只用前端，不用後端嗎？

A: 僅限 Prototype 階段可以。複製 app-web-mockup 使用 Mock API 即可。適合：

設計驗證與原型展示
與利害關係人確認需求
前端開發先行，後端稍後加入

生產環境

若要部署到生產環境，必須使用完整架構：app-web + app-server + app-web-host。

app-server：提供真實 API 與資料持久化
app-web-host：將 SPA 封裝成 WAR 部署到 Java Application Server

Q: app-web 與 app-web-mockup 的差異？

A: 程式碼幾乎完全相同，主要差異在環境變數：

app-web-mockup：強制使用 Mock API
app-web：支援 Mock → 真實 API 漸進切換

Q: 如何測試未發布的框架變更？

A: 使用 yalc 工作流程：

# 1. 在框架專案發布到本地
cd appfuse-web
npm run build && yalc publish

# 2. 在應用專案使用本地框架
cd my-app
yalc add @appfuse/appfuse-web
npm install

詳見 yalc 工作流程。

Q: 初始化後還會與參考實作同步嗎？

A: 不會。初始化後，團隊的專案模組就獨立發展，不再與參考實作（app-*）同步。

框架更新：透過 npm / Gradle 持續取得 appfuse-web / appfuse-server 框架更新
參考實作：僅作為初始化起點，複製後即為團隊獨立的程式碼

Q: 多租戶架構如何運作？

A: 後端使用 Hibernate Filter 自動過濾租戶資料：

Entity 繼承 AuditableTenantEntity
Repository 繼承 TenantAwareRepository
無需手動撰寫 WHERE tenant_id = ? 條件

詳見 app-server 的 docs/design-guidelines/multi-tenancy.md。

Q: 花店管理系統的程式碼何時移除？

A: 由開發團隊自行決定。建議：

先熟悉參考實作的程式碼結構與實作方式
開發新業務功能時參考對應的實作
當團隊對架構足夠熟悉後，再逐步移除不需要的程式碼

自動化工具

專案初始化使用兩個 Claude Code Skill：骨架建立（一次）+ 模組新增（多次）。

`/scaffold-project` — 建立專案骨架

在 appfuse 框架工作目錄執行，建立新專案的目錄結構與配置。

/scaffold-project                           # 互動式詢問所有參數
/scaffold-project myapp                     # 指定專案名稱
/scaffold-project myapp /path/to/myapp      # 指定專案名稱與目標目錄

功能：

收集專案名稱、目標目錄、npm scope
複製開發環境配置（.gitignore, CLAUDE.md, .claude/, workspace）
建立 project.json（記錄專案設定，供 /add-module 使用）
不複製模組（交給 /add-module）

`/add-module` — 增量新增模組

在新專案 modules/ 目錄執行，從參考實作複製模組並套用識別。

/add-module                    # 互動式選擇模組
/add-module web-mockup         # 直接指定模組代號

支援的模組代號：

代號	參考實作	階段
web-mockup	app-web-mockup	提案
docs	app-docs	提案
server	app-server	成案
web	app-web	成案
web-host	app-web-host	部署
docs-host	app-docs-host	部署

功能：

從參考實作複製並重命名模組
套用識別（npm scope、Gradle group、Java package）
延遲收集：Gradle group 等後端識別在首次需要時才詢問
更新 workspace、README.md、project.json
驗證建構（npm run build / gradlew compileJava）

下一步

完成專案初始化後，建議：

閱讀程式結構：專案程式結構
了解系統架構：系統架構
參考花店系統：研究現有 applets 的實作方式
開始開發：根據業務需求新增 applets
撰寫規格：使用 app-docs 記錄需求和設計

適用對象​

前置準備​

環境需求​

建議的開發工具​

初始化步驟​

步驟 1：建立專案目錄結構​

步驟 2：初始化開發環境配置​

Git 配置​

VS Code Workspace​

Claude Code 配置​

步驟 3：複製參考實作模組​

步驟 4：更新專案識別​

VS Code Workspace​

前端模組 (package.json)​

後端模組​

SDKMAN 配置 (.sdkmanrc)​

步驟 5：配置框架依賴​

前端 (.npmrc)​

後端​

步驟 6：參考實作程式碼處理​

步驟 7：驗證開發環境​

使用 VS Code Workspace 開啟專案​

啟動前端 Prototype​

啟動後端​

開發流程​

Prototype → 生產流程​

Mock → 真實 API 漸進切換​

必讀文檔索引​

框架使用指南​

常見問題 (FAQ)​

Q: 可以只用前端，不用後端嗎？​

Q: app-web 與 app-web-mockup 的差異？​

Q: 如何測試未發布的框架變更？​

Q: 初始化後還會與參考實作同步嗎？​

Q: 多租戶架構如何運作？​

Q: 花店管理系統的程式碼何時移除？​

自動化工具​

/scaffold-project — 建立專案骨架​

/add-module — 增量新增模組​

下一步​

適用對象

前置準備

環境需求

建議的開發工具

初始化步驟

步驟 1：建立專案目錄結構

步驟 2：初始化開發環境配置

Git 配置

VS Code Workspace

Claude Code 配置

步驟 3：複製參考實作模組

步驟 4：更新專案識別

VS Code Workspace

前端模組 (package.json)

後端模組

SDKMAN 配置 (.sdkmanrc)

步驟 5：配置框架依賴

前端 (.npmrc)

後端

步驟 6：參考實作程式碼處理

步驟 7：驗證開發環境

使用 VS Code Workspace 開啟專案

啟動前端 Prototype

啟動後端

開發流程

Prototype → 生產流程

Mock → 真實 API 漸進切換

必讀文檔索引

框架使用指南

常見問題 (FAQ)

Q: 可以只用前端，不用後端嗎？

Q: app-web 與 app-web-mockup 的差異？

Q: 如何測試未發布的框架變更？

Q: 初始化後還會與參考實作同步嗎？

Q: 多租戶架構如何運作？

Q: 花店管理系統的程式碼何時移除？

自動化工具

`/scaffold-project` — 建立專案骨架

`/add-module` — 增量新增模組

下一步