Power Funnel

WordPress 外掛，核心功能：

1. YouTube 活動管理：自動抓取 YouTube 直播場次，透過 LINE 讓用戶報名活動
2. 工作流引擎 (Workflow Engine)：以 ReactFlow 節點編輯器設計工作流規則，在觸發條件滿足時自動執行節點動作（發 Email、等待、發 LINE 訊息等）

開發狀態

技術棧

安裝與設定

環境需求

• PHP 8.1+
• WordPress 5.7+
• Node.js 18+
• pnpm 8+
• Composer 2+

初始化

# 安裝所有依賴（前端 + 後端）
pnpm run bootstrap

# 或分開安裝
pnpm install
composer install --no-interaction

指令參考

前端開發

PHP 代碼品質

版本發佈

架構說明

核心設計原則：Serializable Context Callable

工作流引擎的 context（業務資料）採用延遲求值模式 — 儲存的不是資料本身，而是「如何取得資料」的方法引用：

$context_callable_set = [
    'callable' => [TriggerPointService::class, 'resolve_registration_context'],  // 可序列化
    'params'   => [ $post_id ],                                                   // 純值
];

• callable 必須為 string（函數名）或 string[]（[Class::class, 'method']），禁止 Closure
• params 必須為純值陣列，禁止物件
• Context 在節點執行時才求值，確保 WaitNode 延遲後仍取得最新資料
• context_callable_set 透過 wp_postmeta 持久化，必須能安全通過 serialize() / unserialize()

工作流引擎 (Workflow Engine)

管理員設計 WorkflowRule（透過 ReactFlow UI）
        ↓
WorkflowRule 發佈 → 在 trigger_point hook 掛載監聽
        ↓
Trigger 觸發（如：用戶報名活動）
        ↓
TriggerPointService 組裝 context_callable_set（callable + params）
        ↓
建立 Workflow 實例（pf_workflow CPT，status: running）
        ↓
WorkflowDTO::try_execute() 逐節點執行
  └─ 每個節點執行時，call_user_func_array(callable, params) 取得最新 context
        ↓
每節點執行完 → do_next() → 下一節點
        ↓
全部完成 → status: completed
失敗時   → status: failed，記錄錯誤訊息

可用節點類型

擴充節點（後端 PHP）

透過 WordPress filter 注入自訂節點定義：

add_filter('power_funnel/workflow_rule/node_definitions', function(array $definitions): array {
    $definitions['my_node'] = new MyNodeDefinition();
    return $definitions;
});

擴充觸發點

工作流引擎的「觸發條件」下拉選單透過 REST API 動態載入，資料來源為 Repository::get_trigger_points()。 第三方開發者可透過 power_funnel/workflow_rule/trigger_points filter 新增自訂觸發點，新增後會自動出現在管理介面的下拉選單中。

REST API

GET /wp-json/power-funnel/trigger-points

回應格式：

{
  "code": "operation_success",
  "message": "操作成功",
  "data": [
    { "hook": "pf/trigger/registration_created", "name": "用戶報名後" }
  ]
}

透過 Filter 新增觸發點

add_filter('power_funnel/workflow_rule/trigger_points', function(array $trigger_points): array {
    $trigger_points['pf/trigger/my_event'] = new TriggerPointDTO([
        'hook' => 'pf/trigger/my_event',
        'name' => '自訂觸發事件',
    ]);
    return $trigger_points;
});

觸發工作流

新增觸發點後，在適當的時機呼叫 do_action 觸發工作流。必須傳入 context_callable_set（可序列化的 callable + params），不可傳入 Closure 或完整物件：

// 在 TriggerPointService 中定義靜態解析方法
public static function resolve_my_event_context( int $order_id ): array {
    return [
        'order_id'  => (string) $order_id,
        'user_email' => get_post_meta($order_id, 'email', true),
    ];
}

// 觸發時組裝 context_callable_set
$context_callable_set = [
    'callable' => [TriggerPointService::class, 'resolve_my_event_context'],
    'params'   => [ $order_id ],
];
do_action('pf/trigger/my_event', $context_callable_set);

callable 必須為 string 或 string[]（禁止 Closure），params 必須為純值陣列。詳見「核心設計原則：Serializable Context Callable」。

Custom Post Types

開發指引

• PHP 開發：參閱 .github/instructions/wordpress.instructions.md
• React 開發：參閱 .github/instructions/react.instructions.md
• 整體架構：參閱 .github/copilot-instructions.md

License

GPL v2 or later