youzan-datahub/docs/餐饮零售数据中台/3.有赞云对接设计文档.md

餐饮零售数据中台 V2.0 - 有赞云对接设计文档

文档版本： V1.0 关联文档：

• 《1.业务蓝图 (聚焦数据洞察)》
• 《2.产品需求文档 (PRD)》

对接目标： 实现基于有赞云的交易、商品、客户数据的全面打通，为中台的“商品洞察网络”与“客户洞察引擎”提供稳健的数据底座及自动化营销触达能力。

---

一、 总体对接架构与鉴权体系

为了实现轻量级 MVP 架构并保障数据安全流转，系统与有赞云的交互架构设计如下：

1.1 应用类型与授权

• 应用类型： 自用型应用（针对商家自有系统对接）。
• 鉴权方式： OAuth 2.0 (Client ID + Client Secret)。
• Token 管理：
  • 中台定期调用 oauth/token 接口获取 access_token。
  • access_token 与 refresh_token 统一持久化至 Redis，有效期以接口返回的 expires_in 为准。
  • 设计定时任务在 expires_in 的 80% 时点刷新 Token，防止接口调用中断。

1.2 数据交互引擎 (纯 T+1 离线拉取)

为保持系统架构的轻量化与高可用，本期 MVP 剥离复杂的 Webhook 实时消息订阅，采用纯主动拉取 (Pull) 模式：

• 定时任务拉取： 通过设定特定频率的定时任务（如 T+1 凌晨批处理或高频率的小时级级拉取），分页调用有赞 API。
• 适用场景： 用于历史数据初始化、T+1 夜间数据对账合并、全量/增量商品库及客户池信息的同步。
• 优势： 去除对 Kafka/Redis Stream 等高并发消息件的重度依赖，大幅降低运维成本和幂等性处理的复杂度。

---

二、 核心业务域对接设计（能力包驱动）

本章节以“能力包名称”为准，不使用未验证的具体接口方法名。
字段与接口明细以《4.有赞云接口对应表》为准，并在控制台“查看”页确认后补齐。

2.1 交易与售后域 - 支撑动销分析、全域RFM、净额口径

这是中台最核心的数据流水来源。

• 依赖能力包（已获得）：
  • 订单同步
  • 售后单同步
  • 售后单审核处理
  • 网店仅退款 / 网店退货退款
  • 门店仅退款基于有赞POS / 门店退货退款基于有赞POS
• 核心数据提取与应用（字段待确认）：
  • 订单主表与明细：订单ID、支付时间、实付金额、订单明细SKU/数量/价格
  • 售后/退款单：退款金额、退款时间、退款状态
  • 门店/网点归属字段：用于门店维度对比
• 口径要求：
  • 净销售额 = 支付成功订单金额 - 已完成退款金额
  • 退款单必须与订单明细关联，避免动销失真

2.2 商品与SKU域 - 支撑生命周期流转、智能订货

实现门店加热款与线上冷链款的数据统一。

• 依赖能力包（已获得）：
  • 商品查询 / 商品更新 / 上下架商品
  • 商品分组 / 商品标准
  • 门店商品管理 / 店铺商品上下架到网点 / 多网点商品关联配送方式
• 核心数据提取与应用（字段待确认）：
  • 商品ID、SKU ID、名称、类目、规格、状态、售价
  • 门店/网点商品状态与配送方式
• 口径建议：
  • 使用“外部编码/自定义字段”建立热食与冷链SKU统一映射
  • 若无统一编码，需人工维护 SKU 映射表

2.3 客户与粉丝域 - 支撑 OneID 画像与人群分层

解决“谁在买”，并为精准触达提供人群基础。

• 依赖能力包（已获得）：
  • 店铺客户信息同步
  • 店铺客户标签管理
  • 会员等级打通 / 会员权益卡打通
  • 微信粉丝关联有赞用户 / 微信粉丝查询 / 微信粉丝标签管理
• 核心数据提取与应用（字段待确认）：
  • 客户ID/buyer_id、手机号、注册时间、来源
  • 标签/等级/权益卡信息
  • 粉丝ID、open_id/union_id、关联 buyer_id
• OneID 策略：
  • 以手机号为主键，必须输出“识别率”指标（手机号覆盖率）
  • 微信粉丝仅作为补充画像渠道，不做强制跨端合并

2.4 库存与进销存域 - 支撑动销、损耗与补货

商品洞察闭环的关键依赖域。

• 依赖能力包（已获得）：
  • ERP全渠道库存同步
  • 多网点有赞库存同步线下 / 多网点线下库存同步有赞
  • 网店库存调整 / 库存盘点 / 库存采购 / 采购退货 / 库存调拨
  • 连锁库存同步（总部管理/网店独立管理）
• 核心数据提取与应用（字段待确认）：
  • 库存数量、库存变动流水、采购/调拨/盘点单据
• 口径建议：
  • 以库存流水 + 订单明细计算真实动销与损耗

2.5 营销与评价域 - 支撑活动效果与触达闭环

• 依赖能力包（已获得）：
  • 营销活动查询
  • 优惠券管理（活动、发放、核销）
  • 电子卡券核销
  • 限时折扣 / 自定义会员价
  • 评价管理
• 核心数据提取与应用（字段待确认）：
  • 活动ID、活动类型、开始/结束时间、核销记录
• 触达闭环：
  • 可基于人群包输出进行自动发券（具体接口名待控制台确认）

---

三、 定时任务与数据流转编排 (MVP 架构)

3.1 T+1 离线批处理 (建议触发时间：凌晨 02:00)

1. 订单与售后流水增量拉取： 基于“订单同步 + 售后/退款相关能力包”拉取前一日增量。依靠订单ID与更新时间在中台 MySQL 执行 UPSERT，确保数据最终一致性。
2. RFM 批量重算： 基于清洗后的 MySQL 全局交易宽表，重新计算所有涉及变动用户的 R、F、M 值，并重新刷新其客户生命周期标签（如：高优客 -> 沉睡客）。
3. 连带率与购物篮挖掘： 执行 Apriori / FP-Growth 算法或离线 SQL 统计过去一周的外卖订单 orders 组合频率，更新高频搭配推荐库。
4. 智能订货预测： 统计过去 14 天各统一映射后的物理单品日均消耗量，结合周末权重因子，生成门店视角的《次日最优拿货建议单》。

3.2 灵活的近线调度 (可选)

对于店长极其关心的“日内单品动销趋势”（例如想看今天中午小龙虾卖了多少），可在 T+1 的基础上，增加一个基于 XXL-JOB 的“每2小时执行一次”的轮询短任务，仅拉取当日订单增量数据入库，实现伪实时监控，依然无需引入 Webhook。

---

四、 边界条件与容错机制策略

1. 接口频控策略 (Rate Limiting)：
   • 有赞 API 严格限制每秒 QPS。系统在统一的 API 调用 HTTP Client 封装层，使用 Guava RateLimiter 控制并发调用速率，超出部分排队等待，避免触发 429 Too Many Requests 封禁。
2. 数据入库幂等性设计 (Idempotency)：
   • 由于采用增量拉取机制，时间窗口可能会发生重叠（例如拉取昨日 23:55 到今日 00:05 的数据），甚至同一笔订单在不同时间因为售后状态的改变被拉取多次。中台数据库必须以 tid (订单号) 为主键（或辅助唯一复合索引），所有的订单写入底层必须转换为 UPSERT 操作（MySQL 中的 ON DUPLICATE KEY UPDATE），确保被重复拉取的数据不会造成销售额的重复计算。
3. 冷启动历史数据抓取：
   • 系统首次上线时，编写独立的 HistoryDataSyncService 配合 XXL-JOB 分片，基于时间范围参数，循环按天倒推调用 API 获取过去至少 6 个月的历史订单与客户数据，以建立初始的回归基线并冷启动 RFM 模型及推荐算法。