模組（Module）開發

模組 是資訊頁可拖入的區塊，例如「圖片 + 文字」、「YouTube 影片」、「Instagram 貼文牆」、「心理測驗入口」等。

兩種來源

目前內建 24 個模組，分成 5 類：

• 圖片文字（8）
• 影片聲音（5）
• 社群（4）
• 互動體驗（5）
• 其他擴充（2）

資料模型

module_item 表欄位（關鍵）：

• slug（唯一識別）
• package_id（內建為 builtin:<slug>）
• name、description、icon、preview_image
• media_category（對應 module_category.slug，由資料表管理）
• plan_tier（free / pro / max）
• price、currency
• is_builtin（布林）
• data_schema（JSON，供 ModuleDataEditor 渲染表單）

SQL 檔案：

• hypelink-backend-v3/sql/add_module_item_media_plan_columns.sql
• hypelink-backend-v3/sql/add_module_category_table.sql
• hypelink-backend-v3/sql/seed_builtin_module_items.sql
• hypelink-backend-v3/sql/apply_module_system.sql（一次套用）

範本 / Catalog 位置

目前模組「範本」並未以獨立 repo 型式對外開放；所有內建模組的定義皆集中在 hypelink-backend-v3/src/admin/builtin-modules.catalog.ts，這份 TypeScript 檔會隨平台 code 發行。

hypelink-backend-v3/src/admin/
  builtin-modules.catalog.ts   ← DEFAULT_MODULE_CATEGORIES + BUILTIN_MODULES

若要新增一個新的 內建模組：

1. 在 builtin-modules.catalog.ts 的 BUILTIN_MODULES 陣列新增一筆，包含 slug、name、mediaCategory、planTier、完整 dataSchema
2. 部署後管理員到 /hypeadmin/module-items 點 「重建內建模組」（呼叫 POST /admin/module-items/reseed-builtins）

若要新增 擴充模組：

1. 到 /hypeadmin/module-items 的「擴充模組」分頁
2. 點「新增模組」，填寫 slug、name、mediaCategory、planTier、dataSchema 等
3. 送出後 DB 新增一筆 is_builtin=0 的 module_item

分類管理

分類也動態化，儲存於 module_category 表。管理員可在 /hypeadmin/module-items 的「分類管理」分頁：

• 新增／編輯／停用／刪除分類（內建分類不可刪、slug 不可改）
• 刪除前會檢查 module_item.media_category 使用中數量

平台側對接

• 資料來源：後端 GET /module-templates 為唯一真實來源（前端已移除硬編 MODULE_CATEGORIES / MODULE_CATALOG）
• 公開分類：GET /module-categories
• 前端 API layer：hypelink/src/lib/brand-experiences-api.ts 的 ModuleTemplateRow / ModuleCategoryRow
• 資訊頁「新增模組」對話框：AddModuleDialog.tsx（左側 5 類 + 右側 2 欄網格卡片）
• 每個品牌資訊頁上限：MAX_PAGE_MODULES = 12（page-modules-catalog.ts）

測試方式

1. 本地開發

模組並沒有獨立的前端範本 repo，請在主平台本地端測試：

# 後端
cd hypelink-backend-v3
npm run dev
 
# 前端
cd hypelink
npm run dev

2. 新增內建模組後重建

部署後進 /hypeadmin/module-items → 內建模組 tab → 按「重建內建模組」。

警告：此操作會 硬刪 所有 is_builtin=1 AND package_id LIKE 'builtin:%' 的列，再依 catalog 重建。品牌頁已放置的 pageModule 以 slug 參照，不受影響。

3. 實際驗證

1. 在後台 /dashboard/brands/[hypeId]/links 的主內容區點「新增模組」
2. 左側選分類，右側挑新模組，點「確認選擇」
3. 以 ModuleDataEditor 填入 dataSchema 定義的欄位
4. 右側預覽欄會即時顯示
5. 發布後到 /@handle 驗證公開頁效果

4. dataSchema 設計原則

• 欄位型態支援：string、number、boolean、enum、asset（圖片／影片）、richtext、array、object
• 所有欄位需要 i18n 化的 label / placeholder
• 必填欄位用 required: true 標註；表單會阻擋空值送出

參考

• builtin-modules.catalog.ts — 24 個內建模組的完整定義
• AddModuleDialog.tsx — 新增模組對話框
• ModuleDataEditor.tsx — 根據 dataSchema 動態渲染表單