Astro EC Site MVP - Monorepo Architecture Documentation (Bun Edition)

Astro EC Site MVP: Next-Gen Monorepo Architecture

Project Name: Astro EC Site MVP (Edge + AI Hybrid)
Engine: Bun 1.3+
Management: Turborepo
Version: 2.1 (Bun Edition)
Last Updated: 2025-12-02

本文檔定義了本專案的工程架構。我們採用 Monorepo 組織代碼，並選用 Bun 作為核心運行時與包管理器，旨在 Windows 環境下實現極速的開發體驗，並支持 Cloudflare 與 Vercel 的多雲部署。

1. 技術哲學：為什麼選擇 Bun + Monorepo？

在進入架構細節前，需釐清我們為何這樣選型。

1.1 核心概念拆解

Monorepo 與 Bun 是獨立概念，但在此專案中是「黃金搭檔」：

Monorepo (廚房/組織方式)：
- 將 Frontend (apps/web)、Backend (apps/api) 和 Shared Libs (packages/db) 放在同一個代碼倉庫。
- 目的：確保 Database Schema 與 TypeScript 類型在全棧中是「單一來源真理 (SSOT)」，修改一次 Schema，前後端自動同步。
Bun (高壓鍋/高效引擎)：
- 集成了包管理器、運行時、測試工具與打包器。
- 目的：解決傳統 Node.js + npm 在 Monorepo 下依賴安裝慢、啟動慢的痛點。

1.2 Bun 1.3+ 的關鍵優勢 (Windows Friendly)

自 Bun 1.3 起，預設採用 isolated linker 模式。

傳統痛點：舊式 Monorepo 常因 Symlink (符號連結) 問題在 Windows 上崩潰，或者因 hoisted (依賴提升) 導致幽靈依賴。
Bun 的解法：isolated 模式為每個 Workspace 複製必要的依賴（利用硬連結 Hardlinks 優化空間），這讓 Windows 下的依賴解析堅若磐石，同時保持極致的安裝速度。

2. Windows 開發環境準備 (必讀)

為了在 Windows 上獲得 Bun 的最佳體驗，請務必執行以下設定：

2.1 開啟開發人員模式 (Developer Mode)

路徑：設定 > 系統 > 開發者選項 > 開啟 「開發人員模式」。
原因：Bun 依賴 Symlinks 來連結內部的 packages/*。開啟此模式允許 Bun 在不使用管理員權限的情況下，快速創建符號連結，避免權限報錯。

2.2 啟用長路徑支援 (Long Paths)

操作：開啟 PowerShell (管理員)，執行 reg edit 修改註冊表，或透過 Group Policy 開啟 LongPathsEnabled。
原因：現代前端依賴樹極深（尤其是 node_modules），容易超過 Windows 傳統的 260 字元限制。開啟此選項可防止詭異的 "File not found" 錯誤。

3. 核心架構視圖 (Directory Structure)

本專案利用 Bun 的 Workspaces 功能管理依賴。

root/
├── apps/
│   ├── web/                # [Frontend] Astro Storefront
│   │   ├── (Target: Cloudflare Pages)
│   │   └── Stack: Astro 5, Tailwind, React (Islands)
│   │
│   ├── api/                # [Gateway] Cloudflare Workers
│   │   ├── (Target: Cloudflare Workers)
│   │   └── Stack: Hono / Native Fetch
│   │
│   └── admin/              # [Backend] Vercel AI Dashboard
│       ├── (Target: Vercel)
│       └── Stack: Next.js 14+, Vercel AI SDK
│
├── packages/
│   ├── db/                 # [Shared] Database Schema
│   │   ├── (SSOT: Single Source of Truth)
│   │   ├── 包含: Drizzle Schema, Migrations
│   │   └── 導出: db client 供 apps 使用
│   │
│   └── tsconfig/           # [Shared] TypeScript Configs
│       └── base.json (統一編譯規則)
│
├── package.json            # Root config (定義 workspaces)
├── bun.lockb               # Binary lockfile (極速安裝的核心)
└── turbo.json              # Pipeline orchestration

4. 快速開始 (Getting Started)

4.1 安裝依賴

在根目錄執行：

bun install

Bun 會自動並行下載所有依賴，並建立 Workspace 之間的連結。

4.2 環境變數設定 (.env)

請在根目錄或各 App 目錄下建立 .env。由於 packages/db 是共用的，建議確保 DATABASE_URL 在所有環境皆可存取。

# Connection String (Neon Postgres)
DATABASE_URL="postgresql://user:[email protected]/db?sslmode=require"

4.3 啟動開發環境 (Development)

我們使用 Turborepo 來協調多個 App 的啟動：

# 一次啟動所有應用 (Web, API, Admin)
bun run dev

# 僅啟動特定應用
bun run dev --filter=web

5. 資料庫管理 (Database Management)

資料庫定義位於 packages/db。

5.1 修改 Schema

編輯 packages/db/src/schema.ts 後，執行遷移：

# 產生 Migration SQL
bun run --filter db generate

# 推送變更至 Neon (需確保 .env 有連線字串)
bun run --filter db push

5.2 在 App 中使用

由於 Bun 的自動連結，你在 apps/web 中可以直接這樣寫：

// apps/web/src/pages/index.astro
import { db } from "@your-project/db"; // 自動指向 packages/db/src/index.ts
import { products } from "@your-project/db/schema";

const allProducts = await db.select().from(products);

6. 部署策略 (Deployment)

雖然我們使用 Bun 進行開發，但部署時會針對各平台特性進行編譯。

6.1 Cloudflare Pages (`web`)

Build Command: bun run build --filter=web
Output: apps/web/dist
說明: Cloudflare 構建環境中可選用 Bun，或使用 Node.js 環境但透過 Bun 安裝依賴。

6.2 Cloudflare Workers (`api`)

Deploy Command: bun run --filter api deploy (呼叫 wrangler)
說明: Wrangler 原生支持讀取 package.json，會自動處理 TypeScript 編譯。

6.3 Vercel (`admin`)

設定: 在 Vercel 後台將 Build Command 覆寫為 cd ../.. && bun install && bun run build --filter=admin (若 Vercel 原生支援 Bun 則更簡單)。

7. Turborepo 配置 (`turbo.json`)

配合 Bun 的極速啟動，Turborepo 負責緩存管理：

{
	"$schema": "https://turbo.build/schema.json",
	"pipeline": {
		"build": {
			"dependsOn": ["^build"],
			"outputs": ["dist/**", ".next/**"]
		},
		"dev": {
			"cache": false,
			"persistent": true
		}
	}
}

8. 常見問題 (FAQ)

Q: 為什麼我在 apps/web 裡找不到 node_modules/@your-project/db？
A: Bun 1.3+ 預設使用 isolated 模式，且使用了硬連結優化。只要 package.json 裡有寫 "@your-project/db": "workspace:*"，Bun 運行時就能正確找到檔案。你不需要手動 npm link。

Q: 為什麼需要開啟 Windows 開發人員模式？
A: 這是為了讓 Bun 能夠在 node_modules/.bin 創建執行檔的符號連結，確保你可以直接執行 astro 或 wrangler 等命令，而不會遇到權限錯誤。

Q: 如何新增依賴？
A: 使用 bun add 並指定 filter。

# 給 web 安裝 React
bun add react --filter web

# 給根目錄安裝 turbo
bun add turbo -d -w

附註：
這是一份整合了 Monorepo 架構設計、Bun 1.3+ 技術特性以及 Windows 環境最佳實踐 的完整工程文檔。

這份文檔將原先的 pnpm 方案升級為 Bun 驅動，並詳細解釋了為何選擇「Bun + Monorepo」作為你的技術基石。你可以直接將此內容存為 README.md 或 docs/ENGINEERING.md。