【揭密协议 之三】实战：撰写第一支跨平台 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/