接入控制

集成合同详情

把一个合同范围里的字段映射、Adapter 边界、硬停条件和 mock API 放到同一页，方便接真实系统前审核。

中文
报价模板
product

商品源与 Shopify 商品

当前合同只读取本地 mock 和 seed，不访问真实飞书、Shopify、邮箱或数据库。真实接入前， 这里就是字段与保护边界的验收清单。

返回集成准备查看 Mock API
Mock API/api/mock/integration-contract

/api/mock/integration-contract

字段合同13

外部字段到平台对象的映射数量

Adapter 边界3

只读、写入、Webhook 或保护边界

校验状态合同无错误

0 个警告或错误

contract summary

合同摘要

合同范围product

商品源与 Shopify 商品

只读
Mock API只读

/api/mock/integration-contract

只读
保护边界禁止越界

飞书事件只生成标准同步计划，页面和 Shopify 写入都不直接读取原始字段数组。

只读
field contracts

字段合同

商品源数据 / 供应商外部键Supplier.id / required

识别商品归属，后续支持多供应商隔离。

supplier_3c_demo
商品源数据 / 行业包编码Product.industryPackageId / required

把 3C 字段与未来百业字段隔离。

electronics_3c
Brand new / Asis / Asis+ / CPO / 品牌 + 机型 + 栏目Product.title / required

自动生成平台商品标题和 Shopify 商品标题。

Apple iPhone 17e Brand new
Brand new / Asis / Asis+ / CPO / 栏目 + 机型 + Version + 容量 + 卡槽规格 + 状态 + 颜色/货号ProductVariant.sku / derived

自动派生稳定 SKU，作为飞书、库存、价格和 Shopify 映射的幂等键。

brand-new-iphone-17e-a3634-b-a-256gb-1sim-esim-not-activate-rv4
Brand new / Asis / Asis+ / CPO / Version / 容量 / 卡槽规格 / 状态 / 颜色/货号ProductVariant.attributes / required

承载手机规格差异，并生成 Shopify variant 标题。

A3634-B/A / 256GB / 1 Sim+E Sim / Not Activate / Black-黑色-RV4
Brand new / Asis / Asis+ / CPO / 库存InventorySnapshot.quantityAvailable / required

作为源库存，减去 Shopify 订单占用后自动同步可售库存。

1
Brand new / Asis / Asis+ / CPO / USD价格PriceRule.value / required

作为第一版 Shopify 销售价格；超过 20% 波动自动隔离。

632
Shopify映射表 / 同步状态Product.syncToShopify / derived

记录自动创建、更新、隔离或源记录删除后的 Shopify 同步状态。

success
Product / titleProduct.title / required

创建或更新 Shopify 商品主体。

iPhone 15 Pro
ProductVariant / skuProductVariant.sku / required

用于 Shopify variant 与平台 SKU 稳定匹配。

IP15P-256-A-UL
ProductVariant / pricePriceRule.value / required

从价格规则生成 Shopify 可售价格草稿。

735
InventoryItem / availableInventorySnapshot.quantityAvailable / required

从库存快照生成绝对库存同步草稿。

38
Checkout / checkoutUrlShopifyProductMapping.checkoutUrl / derived

报价页和邮件中使用的结账占位链接。

https://demo-ai-trade.myshopify.com/cart/iphone-15-pro-demo:10
adapter boundaries

Adapter 边界

01
adapter_boundary_feishu_products

飞书事件只生成标准同步计划，页面和 Shopify 写入都不直接读取原始字段数组。

当前：读取本地 seed 和自动同步合同，不处理真实飞书事件。；未来：ECS webhook 接收飞书变更事件，并用定时巡检兜底。

硬停：稳定 SKU 无法派生 / 价格或库存不是数字 / 四张源表字段结构发生变化

feishu_base
02
adapter_boundary_shopify_product_sync

同步函数只能消费平台标准对象，不读取供应商原始表格。

当前：生成 Shopify 同步草稿和 checkout 占位链接，不调用真实 API。；未来：自动创建/更新 Shopify 商品、规格、库存和发布状态。

硬停：价格变化超过 20% / Shopify userErrors 超过重试上限 / 库存占用无法对账

shopify
03
adapter_boundary_shopify_orders

订单回流只创建 Order，不直接改写报价或买家状态。

当前：读取本地 Order seed，模拟订单回流。；未来：替换为 Shopify 订单 webhook 或定时拉取 adapter。

硬停：支付状态不可信 / 无法匹配 BuyerCompany / 无法匹配 Quote

shopify
validation

合同无错误

  • 无错误当前字段合同和 Adapter 边界没有 error 级问题。