147 lines
7.3 KiB
Markdown
147 lines
7.3 KiB
Markdown
# 搭建 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 结构。
|