youzan-datahub/docs/餐饮零售数据中台/implementation_plan.md

搭建 Spring Boot 有赞数据中台服务

基于已完成的设计文档和数据库 DDL，在 AIMachineSystem/server/ 下搭建 Spring Boot 服务，覆盖数据同步、洞察计算、API 接口三层。

全局蓝图（5 Phase）

Phase	内容	层	定时
Phase 1	订单同步 (trades.sold.get → dwd_trade_order_detail)	同步层	每日 02:00
Phase 2	商品同步 + 客户同步	同步层	每日 02:30
Phase 3	库存流水 + 优惠券 + 退款同步	同步层	每日 03:00
Phase 4	RFM 计算、动销排名、购物篮分析、客群分层	洞察层	每日 04:00
Phase 5	REST API（仪表盘接口、导出接口）	接口层	实时

技术选型确认

• Java 17 / Spring Boot 3.2.x
• MyBatis-Plus 3.5.x (持久层)
• Spring @Scheduled (定时任务)
• RestTemplate (HTTP 调用有赞 API)
• 有赞应用类型：自用型（grant_type=silent，直接用 client_id + client_secret + kdt_id 获取 Token）

项目目录结构

server/
├── pom.xml
└── src/main/
    ├── java/com/chuyishidai/datahub/
    │   ├── DataHubApplication.java
    │   ├── config/
    │   │   └── YouzanConfig.java             # 有赞配置 + RestTemplate Bean
    │   ├── entity/                           # MyBatis-Plus Entity（对齐 DDL）
    │   │   ├── TradeOrderDetail.java
    │   │   ├── TradeRefundDetail.java
    │   │   ├── ItemSku.java
    │   │   ├── CustomerInfo.java
    │   │   ├── OfflineStore.java
    │   │   ├── InventoryFlow.java
    │   │   └── CouponFlow.java
    │   ├── mapper/                           # MyBatis-Plus Mapper
    │   ├── service/
    │   │   ├── youzan/                       # 有赞 API 基础设施
    │   │   │   ├── YouzanTokenService.java   # Token 获取与缓存
    │   │   │   └── YouzanApiClient.java      # API 调用封装
    │   │   ├── sync/                         # Phase 1-3: 数据同步
    │   │   │   ├── TradeSyncService.java
    │   │   │   ├── ItemSyncService.java
    │   │   │   ├── CustomerSyncService.java
    │   │   │   ├── InventorySyncService.java
    │   │   │   └── CouponSyncService.java
    │   │   └── insight/                      # Phase 4: 洞察计算
    │   │       ├── ProductInsightService.java
    │   │       ├── CustomerInsightService.java
    │   │       └── InventoryInsightService.java
    │   ├── controller/                       # Phase 5: REST API
    │   │   ├── ProductController.java
    │   │   ├── CustomerController.java
    │   │   └── DashboardController.java
    │   └── job/                              # 定时任务
    │       ├── TradeSyncJob.java
    │       └── InsightComputeJob.java
    └── resources/
        └── application.yml

当前实施范围：Phase 1（订单同步）

[NEW] pom.xml

Spring Boot 3.2 + MyBatis-Plus + MySQL + Lombok + Jackson

[NEW] application.yml

数据源、有赞 API 配置、cron 表达式

[NEW] YouzanTokenService.java

自用型 Token：POST https://open.youzanyun.com/auth/token，body: client_id + client_secret + grant_type=silent + kdt_id。缓存至 80% TTL 自动刷新。

[NEW] YouzanApiClient.java

通用调用：GET https://open.youzanyun.com/api/{apiName}/{version}?access_token=xxx，带重试（最多 3 次）。

[NEW] TradeOrderDetail.java + Mapper

MyBatis-Plus Entity 完全对齐 DDL 的 dwd_trade_order_detail。

[NEW] TradeSyncService.java

1. 按 update_time 窗口调用 youzan.trades.sold.get/4.0.4 分页拉取
2. 展开 full_order_info_list[].orders[] 到 SKU 粒度
3. saveOrUpdateBatch（基于 oid 唯一键）UPSERT

[NEW] TradeSyncJob.java

@Scheduled(cron = "0 0 2 * * ?") 每日凌晨 2 点触发，拉取前一天增量。

当前实施范围：Phase 4（商品洞察与会员洞察）

数据模型设计 (ADM 层) - sql/phase4_ddl.sql

1. adm_customer_rfm (客户 RFM 洞察表):
   • 计算逻辑：基于过去 90 天订单流水，聚合 R（最近消费）、F（消费频次）、M（消费金额）。
   • 包含 RFM 评分与系统自动划分的客群层级（如重要价值客户、沉睡客户）。
2. adm_item_sales_trend (商品销售趋势表):
   • 计算逻辑：按天聚合 dwd_trade_order_detail，统计各个 SKU 的单量、销量、销售额。用于生成智能订货预测。
3. adm_item_basket (关联销售分析表):
   • 计算逻辑：采用简化版 Apriori 算法思想，统计同一订单 (tid) 内商品对 (Item A, Item B) 的同现频率与置信度。
4. adm_item_repurchase (商品复购分析表):
   • 计算逻辑：统计某 SKU 购买过后的用户，在接下来 30 天内再次购买的比例。

业务逻辑层设计 (Service)

1. CustomerInsightService:
   • computeRfm(): 执行 SQL 统计与评分，生成/更新会员 RFM 白皮书。
   • computeUserTags(): 针对购买行为（如工作日午餐、高客单价）给用户打标签。
2. ProductInsightService:
   • computeDailySalesTrend(): 日终归集单日销售统计。
   • computeBasketRules(): 统计过去 X 天的热门搭配。
   • computeRepurchaseRates(): 更新商品的 30 天复购率指标。
3. InventoryInsightService:
   • computeStockAdvice(): 基于库存流水和流速，生成次日拿货/备货单。

定时任务层设计 (Job)

1. InsightComputeJob:
   • @Scheduled(cron = "0 0 4 * * ?") 每日凌晨 4:00 集中触发洞察层计算（由于数据全量计算，放置在凌晨数据同步完成之后）。

当前实施范围：Phase 5（可视化接口层）

API 设计方案

1. DashboardController (核心监控板):

   • GET /api/dashboard/overview: 今日总体指标 (今日实付金额, 今日退款金额, 订单数)
   • GET /api/dashboard/trend: 近 14 天整体销售趋势变化折线图数据

2. ProductController (商品洞察与预测):

   • GET /api/product/advice: 智能订货单查询 (基于过去 14 天 adm_item_sales_trend 动态计算各单品日均流速，输出建议备货量)
   • GET /api/product/basket: 购物篮高频组合列表 (查询 adm_item_basket 置信度排行)
   • GET /api/product/repurchase: 单品复购率与波士顿矩阵打标查询 (查询 adm_item_repurchase)

3. CustomerController (会员金字塔与人群):

   • GET /api/customer/rfm/distribution: RFM 金字塔分布 (各层级人数及金额贡献占比查询)
   • GET /api/customer/tags: 各类特征人群包人数统计 (查询 adm_customer_tags)

业务与数据聚合逻辑

由于数据在 Phase 4 已通过定时任务计算沉淀到了 adm_ 系列汇总表中，Phase 5 仅提供轻量级的 SQL GROUP BY 和 SELECT 汇总查询，通过 JdbcTemplate 或 MyBatis-Plus 向前端输出标准 JSON。

Verification Plan

Automated Tests

• cd server && mvn compile 编译通过验证

Manual Verification

1. 重启 Spring Boot 服务。
2. 使用 Postman 或浏览器直接测试 /api/dashboard/overview, /api/product/advice 等接口，验证返回的 JSON 结构。