專案初始化指南

本指南說明如何使用 AppFuse 框架的自動化工具初始化新專案。透過 /scaffold-project 建立專案骨架，再以 /scaffold-module 逐步加入模組。

適用對象

• 準備使用 AppFuse 框架開發新應用程式的團隊
• 想要參考花店管理系統架構來建構自己業務系統的團隊

:::info 已有專案？ 若你是加入現有專案的開發者，請直接前往快速開始設定開發環境。 :::

前置準備

開發環境需求與安裝步驟請參閱環境設定。

額外需要：

工具	用途
Claude Code	執行 /scaffold-project 與 /scaffold-module 自動化工具

---

初始化步驟

:::info 執行位置 以下兩個指令皆在 appfuse 框架的 modules/ 目錄下執行（即包含 app-office、appfuse-web 等模組的目錄）。 :::

步驟 1：建立專案骨架 (/scaffold-project)

建立新專案的目錄結構與共用配置，不複製模組。

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

工具會互動式收集以下資訊：

參數	說明	範例
專案名稱	用於模組前綴	myapp
目標目錄	新專案的絕對路徑	/path/to/myapp
組織名稱	用於推導 npm scope	mycompany（→ @mycompany）

完成後產生的目錄結構：

myapp/                            # 專案根目錄
├── .gitignore                    # Git 忽略規則
└── modules/                      # 模組目錄
    ├── .claude/                  # Claude Code 設定
    │   ├── rules/                # 專案開發規範
    │   └── skills/               # 自動化技能
    ├── CLAUDE.md                 # Claude Code 指令
    ├── project.json              # 專案設定（供 /scaffold-module 使用）
    ├── myapp.code-workspace      # VS Code workspace
    └── README.md                 # 專案說明

步驟 2：新增模組 (/scaffold-module)

從參考實作複製模組到標的專案，自動套用識別並驗證建構。不需要一次新增所有模組，依開發階段逐步加入即可。

/scaffold-module <targetPath>                              # 指定標的專案，互動式選擇模組
/scaffold-module <targetPath> web-mockup                   # 指定標的專案與模組代號
/scaffold-module <targetPath> web-mockup my-prototype      # 指定模組代號與自訂名稱

支援的模組代號：

代號	參考實作	複製為	階段
web-mockup	app-office-mockup	{name}-web-mockup	提案
docs	app-docs	{name}-docs	提案
server	app-server	{name}-server	成案
web	app-office	{name}-web	成案
web-host	app-office-host	{name}-web-host	部署
docs-host	app-docs-host	{name}-docs-host	部署

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

提案階段 → web-mockup, docs
成案階段 → server, web
部署階段 → web-host, docs-host

:::

工具會自動處理：

• 從參考實作複製並重命名模組
• 套用識別（npm scope、Gradle group、Java package）
• 更新 workspace、README.md、project.json
• 驗證建構（npm run build / gradlew compileJava）

:::info 識別延遲收集 npm scope 在 /scaffold-project 時收集。Gradle group 與 Java base package 在首次新增後端模組（server、web-host）時才詢問，避免一開始就要決定所有識別。 :::

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

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

步驟 3：初始化 Git

cd /path/to/myapp
git init
git add .
git commit -m "chore: 初始化專案骨架"

---

初始化後

開發環境設定

專案初始化完成後，團隊成員依照快速開始系列文檔設定開發環境：

1. 環境設定 — 安裝 Node.js、Java、IDE
2. 快速開始 — 啟動前後端服務
3. 本地運行 — API 模式切換與故障排除
4. 開發流程 — 日常開發工作流

獨立發展

資訊

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

Prototype → 生產流程

Mock → 真實 API 的漸進切換機制，請參閱「Mock → 真實 API 漸進切換」。

參考實作程式碼

初始化後的模組包含完整的「花店管理系統」業務邏輯，供團隊參考：

層級	目錄	內容
前端	src/applets/	業務模組（產品、訂單、客戶管理）
前端	src/services/	API 服務層
前端	src/mocks/	Mock API handlers 與種子數據
前端	src/features/	Redux slices
後端	entity/	JPA 實體
後端	controller/	REST API 端點
後端	service/	業務邏輯層
後端	repository/	資料存取層

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

---

常見問題 (FAQ)

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

A: 僅限 Prototype 階段可以。使用 /scaffold-module <targetPath> web-mockup 新增 Prototype 模組即可。適合：

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

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

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

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

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

• app-office-mockup：強制使用 Mock API
• app-office：支援 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: 由開發團隊自行決定。建議：

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

---

附錄：手動初始化步驟

若需了解自動化工具背後的操作細節，或在無法使用 Claude Code 的環境下手動初始化，可展開參考。

A1. 建立專案目錄結構

mkdir -p myapp/modules
cd myapp

A2. 複製開發環境配置

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

# Claude Code 配置
cp /path/to/appfuse-webapp-v1/modules/CLAUDE.md myapp/modules/
cp -r /path/to/appfuse-webapp-v1/modules/.claude myapp/modules/
rm -f myapp/modules/.claude/settings.local.json

# VS Code Workspace
cp /path/to/appfuse-webapp-v1/modules/appfuse-webapp.code-workspace \
   myapp/modules/myapp.code-workspace

修改 myapp.code-workspace：更新 folders 陣列，列出您的模組。

A3. 複製參考實作模組

cd myapp/modules

# 按需複製（不需一次全部）
cp -r /path/to/appfuse-webapp-v1/modules/app-office-mockup myapp-office-mockup
cp -r /path/to/appfuse-webapp-v1/modules/app-office myapp-office
cp -r /path/to/appfuse-webapp-v1/modules/app-server myapp-server
cp -r /path/to/appfuse-webapp-v1/modules/app-office-host myapp-office-host
cp -r /path/to/appfuse-webapp-v1/modules/app-docs myapp-docs

# 清理建構產物
rm -rf myapp-*/node_modules myapp-*/dist myapp-*/build myapp-*/.gradle

A4. 更新專案識別

前端模組 (package.json)：

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

前端框架依賴 (.npmrc)：

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

後端模組 (settings.gradle.kts)：

rootProject.name = "myproject-server"

後端模組 (gradle.properties)：

group = com.mycompany.myproject

Java package 路徑：將 io.leandev.app 重新命名為 com.mycompany.myproject（保留 io.leandev.appfuse.* 框架 package）。

A5. 初始化 Git

cd myapp
git init