电商与支付

电商平台（commerce）

产品模型分两层：SPU（产品） 与 SKU（规格库存）。

创建产品

POST /commerce/v1/commerce/products
{
  "code": "dm7",
  "name": "DM7 平头塞",
  "name_json": { "en": "DM7", "cn": "DM7" },
  "summary": "旗舰平头塞",
  "price": 129900,                    # 金额一律 int64 分
  "currency": "CNY",
  "status": "active",
  "images": [{ "url": "https://..." }],
  "params": { "driver": "14.8mm", "impedance": "32Ω" }
}

SKU 与库存

POST /commerce/v1/commerce/products/{id}/skus
{ "spec": { "color": "黑金" }, "price": 129900, "stock": 50 }

# 库存扣减（事务条件更新，防超卖）
POST /commerce/v1/commerce/stock/deduct

产品列表

GET /commerce/v1/commerce/products?status=active&page_size=12&category_slug=flathead&sort=price_asc
GET /commerce/v1/commerce/products/by-slug/{slug}

支付平台（pay）

创建订单

POST /pay/v1/orders
{
  "appid": "app-xxxx",
  "channel": "alipay|wechat|stripe",
  "amount": 100,                      # 分
  "subject": "积分充值 100",
  "metadata": { "user_id": "..." }
}

Webhook

支付结果通过 POST /v1/pay/webhook/{channel}（公开路径）回调，平台校验签名后发 order.paid 事件；电商平台订阅事件自动置订单已支付。

金额与精度铁律

• 金额一律 int64 分，禁止浮点；
• 库存扣减/回补在事务内条件更新（WHERE stock >= ?）；
• 写操作幂等（Idempotency-Key），防止重复下单。