【揭密協議 之三】實戰：撰寫第一支跨平台 AI 電商分析小工具

直接答案：跨平台 AI 電商工具的關鍵，是把各平台資料先轉成共同 payload，再交給 AI Ready Gateway 分析。工具不應直接改動商品、庫存或價格，而應先產生可審核報表，例如庫存風險、滯銷品項與補貨建議。

這篇文章適合誰？#

• 想從零開始做 AI 電商整合的全端開發者。

• 需要替 WooCommerce、PrestaShop、OpenCart 或 Magento 建立報表工具的外包團隊。

• 想了解 AI Ready 協議如何落地的技術主管。

實作目標：庫存水位分析報表#

我們要做的小工具很明確：讀取最近 30 天銷售摘要與目前庫存，產生「可能缺貨」「可能滯銷」「需要人工檢查」三類報表。

這個工具適合作為第一個 AI Ready 實作，因為它有三個優點：

1. 只需要彙總資料，不需要顧客個資。
2. 輸出是建議報表，不會直接修改交易資料。
3. WooCommerce、PrestaShop、OpenCart、Magento 都有類似的 SKU、銷售與庫存概念。

Step 1：建立共同資料格式#

{
  "sku": "BAG-18L-NAVY",
  "name": "18L 防潑水通勤背包",
  "current_stock": 84,
  "sales_30d": 126,
  "returns_30d": 3,
  "supplier_lead_time_days": 21
}

不同平台可以用不同方法取得資料，但送到 AI Ready 前應整理成共同格式。

Step 2：封裝 AI Ready Payload#

{
  "intent": "analyze_inventory_risk",
  "source": {
    "platform": "opencart",
    "store_id": "main"
  },
  "context": {
    "locale": "zh-TW",
    "permissions": ["inventory:read", "report:write"]
  },
  "data": {
    "period_days": 30,
    "items": []
  },
  "constraints": {
    "write_mode": "report_only",
    "do_not_create_purchase_order": true
  }
}

write_mode 很重要，它告訴系統這只是報表，不是自動採購。

Step 3：Node.js 範例#

'use strict';

const payload = {
  intent: 'analyze_inventory_risk',
  source: { platform: 'woocommerce', store_id: 'demo' },
  context: {
    locale: 'zh-TW',
    permissions: ['inventory:read', 'report:write']
  },
  data: {
    period_days: 30,
    items: [
      {
        sku: 'BAG-18L-NAVY',
        name: '18L 防潑水通勤背包',
        current_stock: 84,
        sales_30d: 126,
        returns_30d: 3,
        supplier_lead_time_days: 21
      }
    ]
  },
  constraints: {
    write_mode: 'report_only',
    do_not_create_purchase_order: true
  }
};

const response = await fetch('https://gateway.example.com/ai-ready/tasks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.AI_READY_TOKEN}`
  },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  throw new Error(`AI Ready task failed: ${response.status}`);
}

console.log(await response.json());

正式環境還需要 HMAC 簽章、timeout、重試、idempotency key 與錯誤日誌。

Step 4：驗證輸出#

期望輸出可以是：

{
  "report": [
    {
      "sku": "BAG-18L-NAVY",
      "risk": "stockout",
      "reason": "30 天銷售 126 件，目前庫存 84 件，供應商交期 21 天。",
      "recommendation": "建議採購人員本週確認補貨。",
      "requires_review": true
    }
  ]
}

系統應檢查 sku 是否存在、risk 是否為允許值、recommendation 是否包含不該執行的自動採購指令。

Step 5：呈現在後台#

報表頁建議顯示：

• SKU 與商品名稱。

• 風險類型。

• AI 建議。

• 資料依據。

• 信心等級。

• 人工備註。

• 已處理 / 已忽略狀態。

這樣 AI 工具會成為營運輔助，而不是黑箱決策。

FAQ#

這個工具真的能跨平台嗎？#

核心分析邏輯可以跨平台，但每個平台仍需要自己的 adapter 取得資料與回寫報表。跨平台的重點是共同 payload，不是完全相同程式碼。

為什麼不直接讓 AI 下採購單？#

採購涉及供應商、現金流、庫存策略與人工判斷。第一階段應只產生建議報表，等企業建立審核與權限後再考慮更高自動化。

是否需要把顧客資料送給模型？#

不需要。庫存水位分析通常使用彙總銷售與庫存資料即可，不應傳送姓名、地址、email 或付款資訊。

參考資料#

• Node.js Fetch API，https://nodejs.org/api/globals.html#fetch
• WooCommerce REST API Documentation，https://woocommerce.github.io/woocommerce-rest-api-docs/
• Adobe Commerce Web APIs，https://developer.adobe.com/commerce/webapi/