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 结构。