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