交易市场平台（供应商）

doc/大屏/交易销售/大屏交易销售功能需求.md

@@ -138,7 +138,7 @@
 
 | 区块 | 与 **Y** / 统计日关系 | 口径摘要 |
 | --- | --- | --- |
-| 农资品类销售、热销 Top5 | **statDate**（默认统计日；当日完成单按一级品类销量） | 饼图占比 + Top5 排行 |
+| 农资品类销售、热销 Top5 | **Y**（统计年；当年已完成单按 `finish_time` 归属 **Y**，一级品类销量） | 饼图占比 + Top5 排行 |
 | 商城订单趋势 | **Y**；按月 1～12 | 非删除订单按 `create_time` 计数 |
 | 店铺入驻 | **Y**；按月占比饼图 | 按店铺 `create_time` 归属月 |
 | 消费区域 Top5 | **Y**；已完成单实付按收货城市 | 金额万元，Top5 |
@@ -323,8 +323,8 @@ flowchart TB
 
 | 项 | 规则 |
 | --- | --- |
-| 品类占比 | **饼图**；各一级品类当日销量占 `totalQty` 比例（**§2.12**） |
-| 热销 Top5 | 列表：排名、品类名、销量；与饼图同 **statDate** |
+| 品类占比 | **饼图**；各一级品类**当年**销量占 `totalQty` 比例（**§2.12**） |
+| 热销 Top5 | 列表：排名、品类名、销量；与饼图同 **statYear**（统计年 **Y**） |
 | 未接入 | 空态文案「商城统计未接入」或「暂无数据」 |
 
 ---
@@ -432,6 +432,7 @@ flowchart TB
 | --- | --- | --- |
 | 1.0 | 2026-05-26 | 由草稿优化：补全流程、边界、五区块需求；农资商城整块标为范围外 |
 | **1.1** | **2026-05-20** | **纳入农资商城 §8～13**：Open API 对接；总览增农资订单量；六区块右栏；**§2.12** 口径；农资年度销售额待商城 API |
+| **1.2** | **2026-05-20** | 对齐商城 Open API **v1.2**：品类/热销/区域改为**统计年**口径；大屏请求 overview 仅传 `statYear`；右栏标题展示统计年 |
 
 ---
 

doc/大屏/交易销售/大屏交易销售技术方案.md

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

doc/大屏/交易销售/大屏交易销售测试用例.md

@@ -1,6 +1,6 @@
 # 大屏 — 交易销售统计 — 测试用例
 
-> 依据：`大屏交易销售功能需求.md`（**v1.1**）、`大屏交易销售技术方案.md`（**v1.1**）  
+> 依据：`大屏交易销售功能需求.md`（**v1.2**）、`大屏交易销售技术方案.md`（**v1.2**）  
 > **接口 Base Path**：`/bigScreen/tradeSales`（含 `context-path`、网关前缀须补齐）。鉴权：若依 Cookie / `Authorization` Token；权限 `bigScreen:tradeSales:query`。  
 > **农资商城**：经 `MallStatsOpenApiClient` 调用商城 `GET /api/open/stats/overview`；配置 `bigscreen.mall-stats.*`。
 
@@ -19,7 +19,7 @@
 | 产地行情 | `[statDate−6, statDate]` 共 7 日；默认市场「巴青牦牛交易市场」；**与 Y 无关** |
 | 销售去向 | 承销商 `sales_destination` 1/2/3；汇总**头数** |
 | 品质等级 | 已完成明细 `grade_code`；名称来自 `biz_grade_weight_config` |
-| 农资商城 | `mallStatsAvailable`；overview 六项字段；`agriOrderCount`=当年 `mallOrderTrend` 求和；Token `X-Open-Token` |
+| 农资商城 | `mallStatsAvailable`；overview 六项字段；请求商城仅 `statYear`；`agriOrderCount`=当年 `mallOrderTrend` 求和；Token `X-Open-Token` |
 | 商城降级 | `mall-stats.enabled=false` 或 HTTP 失败 → 右栏空态，牦牛正常 |
 
 **自动化对照（建议）**：`com.ruoyi.web.modules.screen.**.*TradeSales*`、`com.ruoyi.web.modules.screen.mallstats.**`（JUnit5 / MockMvc / Playwright）。
@@ -117,7 +117,7 @@
 | DP-JY-API-028 | 农资 | overview 字段 | 接口测试 | Postman | SY-JY-08 | 商城 enabled + `MALL-OVERVIEW` | `GET dashboard` | 含 `mallStatsAvailable=true` 及六项农资对象 |
 | DP-JY-API-029 | 农资 | agriOrderCount | 接口测试 | Postman | SY-JY-12 | 已知 orderTrend | `GET dashboard` | `tradeOverview.agriOrderCount` 与月合计一致 |
 | DP-JY-API-030 | 农资 | 商城关闭降级 | 接口测试 | Postman | SY-JY-11 | `MALL-OFF` | `GET dashboard` | `mallStatsAvailable=false`；牦牛字段正常 |
-| DP-JY-API-031 | 农资 | 本地 Redis 缓存 | 接口测试 | Postman | 技术§4.1 | 连续两次请求同 statDate/Y | 第二次仍成功；可观测 Redis key（集成环境） |
+| DP-JY-API-031 | 农资 | 本地 Redis 缓存 | 接口测试 | Postman | 技术§4.1 | 连续两次请求同 statYear | 第二次仍成功；Redis key 为 `bigscreen:mallstats:overview:{statYear}`（集成环境） |
 
 ---