|
|
@@ -1,6 +1,6 @@
|
|
1
|
1
|
# 大屏 — 交易销售统计 — 技术方案
|
|
2
|
2
|
|
|
3
|
|
-> 依据：同目录 `大屏交易销售功能需求.md` **v1.1**。
|
|
|
3
|
+> 依据：同目录 `大屏交易销售功能需求.md` **v1.2**。
|
|
4
|
4
|
> **牦牛交易**：交易市场平台**既有表**（订单、明细、供应商、承销商、日度行情、等级重量配置等），本服务 MyBatis 只读聚合。
|
|
5
|
5
|
> **农资商城**：**不直连**商城库表；经 **`MallStatsOpenApiClient`** 调用农资商城 Open API `GET /api/open/stats/overview`（口径见商城项目 `doc/平台后台/外部接口/商城数据统计技术方案.md`）。
|
|
6
|
6
|
> 本模块为**大屏只读看板**；看板主接口仍为**单接口** `GET /bigScreen/tradeSales/dashboard`。
|
|
|
@@ -51,10 +51,10 @@
|
|
51
|
51
|
| 项 | 说明 |
|
|
52
|
52
|
| --- | --- |
|
|
53
|
53
|
| 基路径 | `{bigscreen.mall-stats.base-url}/api/open/stats` |
|
|
54
|
|
-| 聚合接口 | `GET /overview?statDate=&statYear=` |
|
|
|
54
|
+| 聚合接口 | `GET /overview?statYear=`（可选，默认当年；**无** `statDate` 参数） |
|
|
55
|
55
|
| 认证 | 请求头 `X-Open-Token`（AES-128-CBC 加密 UUID；Key/IV 见 **§4.1**） |
|
|
56
|
56
|
| 响应 | 商城 `AjaxResult`；`data` 含六项 VO（与单接口字段一致） |
|
|
57
|
|
-| 口径文档 | 商城项目 `doc/平台后台/外部接口/商城数据统计技术方案.md` |
|
|
|
57
|
+| 口径文档 | 商城项目 `doc/平台后台/外部接口/商城数据统计技术方案.md` **v1.2**（品类/热销/区域按 **统计年** `YEAR(finish_time)`） |
|
|
58
|
58
|
|
|
59
|
59
|
> **不包含**：本服务直连农资商城订单/店铺/品类/评价等**任意表**。
|
|
60
|
60
|
|
|
|
@@ -305,15 +305,15 @@ XML：`mapper/screen/TradeSalesScreenMapper.xml`。
|
|
305
|
305
|
|
|
306
|
306
|
| 字段 | 说明 |
|
|
307
|
307
|
| --- | --- |
|
|
308
|
|
-| `statDate` | 统计日 `yyyy-MM-dd`（当日完成单按品类销量） |
|
|
309
|
|
-| `totalQty` | 当日总销量（件） |
|
|
|
308
|
+| `statYear` | 统计年（当年已完成单按 `finish_time` 归属 **Y**） |
|
|
|
309
|
+| `totalQty` | 当年总销量（件） |
|
|
310
|
310
|
| `items[]` | `categoryId`、`categoryName`、`qty`、`ratio` |
|
|
311
|
311
|
|
|
312
|
312
|
#### 3.1.7 `hotCategoryRank`
|
|
313
|
313
|
|
|
314
|
314
|
| 字段 | 说明 |
|
|
315
|
315
|
| --- | --- |
|
|
316
|
|
-| `statDate` | 同 **§3.1.6** |
|
|
|
316
|
+| `statYear` | 同 **§3.1.6** |
|
|
317
|
317
|
| `items[]` | `rank`、`categoryId`、`categoryName`、`qty`（Top5） |
|
|
318
|
318
|
|
|
319
|
319
|
#### 3.1.8 `mallOrderTrend`
|
|
|
@@ -386,8 +386,8 @@ XML：`mapper/screen/TradeSalesScreenMapper.xml`。
|
|
386
|
386
|
]
|
|
387
|
387
|
},
|
|
388
|
388
|
"mallStatsAvailable": true,
|
|
389
|
|
- "categorySales": { "statDate": "2026-05-20", "totalQty": 1200, "items": [] },
|
|
390
|
|
- "hotCategoryRank": { "statDate": "2026-05-20", "items": [] },
|
|
|
389
|
+ "categorySales": { "statYear": 2026, "totalQty": 1200, "items": [] },
|
|
|
390
|
+ "hotCategoryRank": { "statYear": 2026, "items": [] },
|
|
391
|
391
|
"mallOrderTrend": { "statYear": 2026, "items": [{ "month": 1, "orderCount": 320 }] },
|
|
392
|
392
|
"shopEntry": { "statYear": 2026, "yearTotal": 48, "items": [] },
|
|
393
|
393
|
"regionRank": { "statYear": 2026, "items": [] },
|
|
|
@@ -406,7 +406,8 @@ XML：`mapper/screen/TradeSalesScreenMapper.xml`。
|
|
406
|
406
|
6. marketId = resolveDefaultMarketId(configName)
|
|
407
|
407
|
7. rows = quoteMapper 7日窗口(marketId); originQuote = Support.aggregateQuote7d(rows, statDate)
|
|
408
|
408
|
8. availableYears = distinct finish years ∪ current year
|
|
409
|
|
-9. mall = MallStatsOpenApiClient.fetchOverview(formatStatDate(statDate), year)
|
|
|
409
|
+9. mall = MallStatsOpenApiClient.fetchOverview(year)
|
|
|
410
|
+ → 请求商城 `GET /overview?statYear={year}`（**不传** statDate）
|
|
410
|
411
|
→ 成功：Support.applyMallStats(vo, mall) + enrichOverviewWithMall(tradeOverview, mall)
|
|
411
|
412
|
→ 失败/未启用：Support.applyEmptyMallStats(vo)
|
|
412
|
413
|
10. return AjaxResult.success(vo)
|
|
|
@@ -429,7 +430,7 @@ bigscreen:
|
|
429
|
430
|
aes-iv: FU2GR30Iw76PjXbO
|
|
430
|
431
|
connect-timeout-ms: 5000
|
|
431
|
432
|
read-timeout-ms: 15000
|
|
432
|
|
- cache-ttl-minutes: 5 # 本地 Redis：bigscreen:mallstats:overview:{statDate}:{statYear}
|
|
|
433
|
+ cache-ttl-minutes: 5 # 本地 Redis：bigscreen:mallstats:overview:{statYear}
|
|
433
|
434
|
```
|
|
434
|
435
|
|
|
435
|
436
|
| 项 | 说明 |
|
|
|
@@ -469,3 +470,4 @@ SQL 示例：`sql/big_screen_trade_sales_perm.sql`（挂载「大屏」父菜单
|
|
469
|
470
|
| --- | --- | --- |
|
|
470
|
471
|
| 1.0 | 2026-05-20 | 初稿：无新表；单接口五区块；农资商城不纳入 |
|
|
471
|
472
|
| **1.1** | **2026-05-20** | **增刊农资商城**：Open API overview 对接 + 本地 Redis；dashboard 扩展六区块；`agriOrderCount`；`agriSalesAmount` 待商城 API 补年度总额 |
|
|
|
473
|
+| **1.2** | **2026-05-20** | 对齐商城 Open API **v1.2**：overview 仅传 `statYear`；`categorySales` / `hotCategoryRank` 响应字段改为 `statYear`；品类/热销/区域口径为**统计年**（`YEAR(finish_time)`） |
|
wwh