# 餐饮零售数据中台 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 模型及推荐算法。