接入控制

集成合同详情

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

中文
报价模板
auto_sync

飞书到 Shopify 自动同步

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

返回集成准备查看 Mock API
Mock API/api/mock/feishu-shopify-auto-sync

/api/mock/feishu-shopify-auto-sync

字段合同8

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

Adapter 边界4

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

校验状态合同无错误

0 个警告或错误

contract summary

合同摘要

合同范围auto_sync

飞书到 Shopify 自动同步

只读
Mock API只读

/api/mock/feishu-shopify-auto-sync

只读
保护边界禁止越界

事件只生成同步任务，不直接在 request handler 内写 Shopify。

只读
field contracts

字段合同

Brand new / Asis / Asis+ / CPO / 库存InventorySnapshot.quantityAvailable / required

飞书原始库存减去未完成订单占用后，自动写入 Shopify 可售库存。

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

作为 Shopify 第一版销售价格；变化超过 20% 进入异常隔离。

632
Brand new / Asis / Asis+ / CPO / 栏目 + 机型 + Version + 容量 + 卡槽规格 + 状态Product.title / handle / derived

自动拆分 Shopify Product，避免单个商品 option 或 variant 过多。

Brand new iPhone 17e A3634-B/A 256GB 1 Sim+E Sim Not Activate
Brand new / Asis / Asis+ / CPO / 颜色/货号ProductVariant.title / required

作为同一 Shopify Product 下的 variant 展示名。

Black-黑色-RV4
Shopify映射表 / SKU / productId / variantId / inventoryItemIdShopifyProductMapping.shopifyProductId / shopifyVariantId / shopifyInventoryItemId / required

确保重复事件不会重复创建商品，并能对同一 SKU 做价格和库存更新。

gid://shopify/Product/123
Shopify订单占用表 / SKU / 占用数量 / 占用状态InventorySnapshot.quantityReserved / derived

Shopify 下单后自动占用库存，避免下一次飞书同步把库存回弹。

sku=brand-new-iphone-17e...; quantity=2; status=open
同步日志表 / 动作 / 结果 / 错误SyncLog.status / error / required

记录 dry-run、事件同步、巡检同步、重试和 Shopify userErrors。

event_sync / success
异常隔离表 / 异常原因 / 重试次数 / 当前状态QuarantineRecord.reason / attempts / status / required

错价、缺字段、库存异常或 API 连续失败时只隔离当前 SKU。

price_spike_gt_20_percent
adapter boundaries

Adapter 边界

01
adapter_boundary_feishu_event_sync

事件只生成同步任务，不直接在 request handler 内写 Shopify。

当前：mock API 暴露自动同步合同，不接收真实飞书事件。；未来：ECS HTTPS webhook 接收飞书记录新增、编辑和删除事件。

硬停：webhook 签名无效 / source table 不在白名单 / 事件缺少 record id

adapter
02
adapter_boundary_polling_reconcile

巡检只补偿漏事件和状态漂移，不改客户原货源库存。

当前：dry-run 样例展示巡检规则，不读取真实飞书。；未来：ECS 定时巡检四张货源表，对账映射表和 Shopify 状态。

硬停：飞书读取失败 / 字段结构变化 / 分页不完整

adapter
03
adapter_boundary_shopify_auto_write

Shopify 写入只消费标准同步计划，不直接读取原始飞书数组。

当前：生成 Shopify 写入计划，不调用 Admin API。；未来：自动执行 product/variant 创建、价格更新、库存更新和发布。

硬停：稳定 SKU 无法派生 / 价格变化超过 20% / Shopify userErrors 超过重试上限

adapter
04
adapter_boundary_shopify_order_holds

订单只写占用表和日志，不直接改客户原货源表库存。

当前：样例展示订单占用表规则，不处理真实订单 webhook。；未来：Shopify 订单 webhook 自动写订单占用表，再触发库存重算。

硬停：订单无法匹配 SKU / 重复 webhook 幂等失败 / 占用数量超过源库存

adapter
validation

合同无错误

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