会员管理代码

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/constant/OpenStatsConstants.java

@@ -24,12 +24,8 @@ public final class OpenStatsConstants
 
     public static final String UNKNOWN_CITY = "未知";
 
-    public static final String DATE_PATTERN = "yyyy-MM-dd";
-
     public static final String YEAR_PATTERN = "yyyy";
 
-    public static final int CACHE_TTL_CATEGORY_MIN = 5;
-
     public static final int CACHE_TTL_YEARLY_HOUR = 1;
 
     public static final int CACHE_TTL_WORDCLOUD_HOUR = 24;

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/controller/MallStatsOpenController.java

@@ -22,16 +22,16 @@ public class MallStatsOpenController extends BaseController
 
     @Anonymous
     @GetMapping("/categorySales")
-    public AjaxResult categorySales(@RequestParam(value = "statDate", required = false) String statDate)
+    public AjaxResult categorySales(@RequestParam(value = "statYear", required = false) String statYear)
     {
-        return success(mallStatsOpenService.getCategorySales(statDate));
+        return success(mallStatsOpenService.getCategorySales(statYear));
     }
 
     @Anonymous
     @GetMapping("/hotCategoryRank")
-    public AjaxResult hotCategoryRank(@RequestParam(value = "statDate", required = false) String statDate)
+    public AjaxResult hotCategoryRank(@RequestParam(value = "statYear", required = false) String statYear)
     {
-        return success(mallStatsOpenService.getHotCategoryRank(statDate));
+        return success(mallStatsOpenService.getHotCategoryRank(statYear));
     }
 
     @Anonymous
@@ -64,10 +64,8 @@ public class MallStatsOpenController extends BaseController
 
     @Anonymous
     @GetMapping("/overview")
-    public AjaxResult overview(
-            @RequestParam(value = "statDate", required = false) String statDate,
-            @RequestParam(value = "statYear", required = false) String statYear)
+    public AjaxResult overview(@RequestParam(value = "statYear", required = false) String statYear)
     {
-        return success(mallStatsOpenService.getOverview(statDate, statYear));
+        return success(mallStatsOpenService.getOverview(statYear));
     }
 }

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/mapper/MallStatsOpenMapper.java

@@ -11,7 +11,7 @@ import com.ruoyi.web.modules.openstats.dto.RegionAmountRow;
  */
 public interface MallStatsOpenMapper
 {
-    List<CategoryQtyRow> selectCategoryQtyByFinishDate(@Param("statDate") String statDate);
+    List<CategoryQtyRow> selectCategoryQtyByFinishYear(@Param("statYear") int statYear);
 
     List<MonthCountRow> selectOrderCountByYear(@Param("statYear") int statYear);
 

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/service/IMallStatsOpenService.java

@@ -13,9 +13,9 @@ import com.ruoyi.web.modules.openstats.vo.StatsOverviewVO;
  */
 public interface IMallStatsOpenService
 {
-    CategorySalesVO getCategorySales(String statDate);
+    CategorySalesVO getCategorySales(String statYear);
 
-    HotCategoryRankVO getHotCategoryRank(String statDate);
+    HotCategoryRankVO getHotCategoryRank(String statYear);
 
     OrderTrendVO getOrderTrend(String statYear);
 
@@ -25,5 +25,5 @@ public interface IMallStatsOpenService
 
     ReviewWordCloudVO getReviewWordCloud();
 
-    StatsOverviewVO getOverview(String statDate, String statYear);
+    StatsOverviewVO getOverview(String statYear);
 }

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/service/impl/MallStatsOpenServiceImpl.java

@@ -4,8 +4,6 @@ import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.time.LocalDate;
 import java.time.ZoneId;
-import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Comparator;
@@ -44,8 +42,6 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
 {
     private static final ZoneId ZONE_SHANGHAI = ZoneId.of("Asia/Shanghai");
 
-    private static final DateTimeFormatter DATE_FMT = DateTimeFormatter.ofPattern(OpenStatsConstants.DATE_PATTERN);
-
     @Autowired
     private MallStatsOpenMapper statsMapper;
 
@@ -56,34 +52,34 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
     private ReviewWordCloudSupport wordCloudSupport;
 
     @Override
-    public CategorySalesVO getCategorySales(String statDate)
+    public CategorySalesVO getCategorySales(String statYear)
     {
-        String date = resolveStatDate(statDate);
-        String cacheKey = StatsCacheKeys.categorySales(date);
+        int year = resolveStatYear(statYear);
+        String cacheKey = StatsCacheKeys.categorySales(year);
         CategorySalesVO cached = redisCache.getCacheObject(cacheKey);
         if (cached != null)
         {
             return cached;
         }
-        List<CategoryQtyRow> rows = safeList(statsMapper.selectCategoryQtyByFinishDate(date));
-        CategorySalesVO vo = buildCategorySales(date, rows);
-        redisCache.setCacheObject(cacheKey, vo, OpenStatsConstants.CACHE_TTL_CATEGORY_MIN, TimeUnit.MINUTES);
+        List<CategoryQtyRow> rows = safeList(statsMapper.selectCategoryQtyByFinishYear(year));
+        CategorySalesVO vo = buildCategorySales(year, rows);
+        redisCache.setCacheObject(cacheKey, vo, OpenStatsConstants.CACHE_TTL_YEARLY_HOUR, TimeUnit.HOURS);
         return vo;
     }
 
     @Override
-    public HotCategoryRankVO getHotCategoryRank(String statDate)
+    public HotCategoryRankVO getHotCategoryRank(String statYear)
     {
-        String date = resolveStatDate(statDate);
-        String cacheKey = StatsCacheKeys.hotCategory(date);
+        int year = resolveStatYear(statYear);
+        String cacheKey = StatsCacheKeys.hotCategory(year);
         HotCategoryRankVO cached = redisCache.getCacheObject(cacheKey);
         if (cached != null)
         {
             return cached;
         }
-        List<CategoryQtyRow> rows = safeList(statsMapper.selectCategoryQtyByFinishDate(date));
-        HotCategoryRankVO vo = buildHotCategoryRank(date, rows);
-        redisCache.setCacheObject(cacheKey, vo, OpenStatsConstants.CACHE_TTL_CATEGORY_MIN, TimeUnit.MINUTES);
+        List<CategoryQtyRow> rows = safeList(statsMapper.selectCategoryQtyByFinishYear(year));
+        HotCategoryRankVO vo = buildHotCategoryRank(year, rows);
+        redisCache.setCacheObject(cacheKey, vo, OpenStatsConstants.CACHE_TTL_YEARLY_HOUR, TimeUnit.HOURS);
         return vo;
     }
 
@@ -151,11 +147,11 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
     }
 
     @Override
-    public StatsOverviewVO getOverview(String statDate, String statYear)
+    public StatsOverviewVO getOverview(String statYear)
     {
         StatsOverviewVO overview = new StatsOverviewVO();
-        overview.setCategorySales(getCategorySales(statDate));
-        overview.setHotCategoryRank(getHotCategoryRank(statDate));
+        overview.setCategorySales(getCategorySales(statYear));
+        overview.setHotCategoryRank(getHotCategoryRank(statYear));
         overview.setOrderTrend(getOrderTrend(statYear));
         overview.setShopEntry(getShopEntry(statYear));
         overview.setRegionRank(getRegionRank(statYear));
@@ -163,10 +159,10 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
         return overview;
     }
 
-    private CategorySalesVO buildCategorySales(String statDate, List<CategoryQtyRow> rows)
+    private CategorySalesVO buildCategorySales(int statYear, List<CategoryQtyRow> rows)
     {
         CategorySalesVO vo = new CategorySalesVO();
-        vo.setStatDate(statDate);
+        vo.setStatYear(statYear);
         long totalQty = 0L;
         List<CategorySalesItemVO> items = new ArrayList<>();
         for (CategoryQtyRow row : rows)
@@ -186,12 +182,12 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
         return vo;
     }
 
-    private HotCategoryRankVO buildHotCategoryRank(String statDate, List<CategoryQtyRow> rows)
+    private HotCategoryRankVO buildHotCategoryRank(int statYear, List<CategoryQtyRow> rows)
     {
         rows.sort(Comparator.comparing(CategoryQtyRow::getQty, Comparator.nullsFirst(Long::compareTo)).reversed()
                 .thenComparing(row -> row.getCategoryId() != null ? row.getCategoryId() : OpenStatsConstants.UNCATEGORIZED_ID));
         HotCategoryRankVO vo = new HotCategoryRankVO();
-        vo.setStatDate(statDate);
+        vo.setStatYear(statYear);
         int limit = Math.min(OpenStatsConstants.HOT_CATEGORY_LIMIT, rows.size());
         for (int i = 0; i < limit; i++)
         {
@@ -363,22 +359,6 @@ public class MallStatsOpenServiceImpl implements IMallStatsOpenService
         return monthMap;
     }
 
-    private String resolveStatDate(String statDate)
-    {
-        if (StringUtils.isEmpty(statDate))
-        {
-            return LocalDate.now(ZONE_SHANGHAI).format(DATE_FMT);
-        }
-        try
-        {
-            return LocalDate.parse(statDate.trim(), DATE_FMT).format(DATE_FMT);
-        }
-        catch (DateTimeParseException ex)
-        {
-            return LocalDate.now(ZONE_SHANGHAI).format(DATE_FMT);
-        }
-    }
-
     private int resolveStatYear(String statYear)
     {
         if (StringUtils.isEmpty(statYear))

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/support/StatsCacheKeys.java

@@ -11,14 +11,14 @@ public final class StatsCacheKeys
     {
     }
 
-    public static String categorySales(String statDate)
+    public static String categorySales(int statYear)
     {
-        return PREFIX + "cat:sales:" + statDate;
+        return PREFIX + "cat:sales:" + statYear;
     }
 
-    public static String hotCategory(String statDate)
+    public static String hotCategory(int statYear)
     {
-        return PREFIX + "cat:hot:" + statDate;
+        return PREFIX + "cat:hot:" + statYear;
     }
 
     public static String orderTrend(int statYear)

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/vo/CategorySalesVO.java

@@ -5,20 +5,20 @@ import java.util.List;
 
 public class CategorySalesVO
 {
-    private String statDate;
+    private int statYear;
 
     private long totalQty;
 
     private List<CategorySalesItemVO> items = new ArrayList<>();
 
-    public String getStatDate()
+    public int getStatYear()
     {
-        return statDate;
+        return statYear;
     }
 
-    public void setStatDate(String statDate)
+    public void setStatYear(int statYear)
     {
-        this.statDate = statDate;
+        this.statYear = statYear;
     }
 
     public long getTotalQty()

baqing-shop/src/main/java/com/ruoyi/web/modules/openstats/vo/HotCategoryRankVO.java

@@ -5,18 +5,18 @@ import java.util.List;
 
 public class HotCategoryRankVO
 {
-    private String statDate;
+    private int statYear;
 
     private List<HotCategoryRankItemVO> items = new ArrayList<>();
 
-    public String getStatDate()
+    public int getStatYear()
     {
-        return statDate;
+        return statYear;
     }
 
-    public void setStatDate(String statDate)
+    public void setStatYear(int statYear)
     {
-        this.statDate = statDate;
+        this.statYear = statYear;
     }
 
     public List<HotCategoryRankItemVO> getItems()

baqing-shop/src/main/resources/mapper/openstats/MallStatsOpenMapper.xml

@@ -2,7 +2,7 @@
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <mapper namespace="com.ruoyi.web.modules.openstats.mapper.MallStatsOpenMapper">
 
-    <select id="selectCategoryQtyByFinishDate" resultType="com.ruoyi.web.modules.openstats.dto.CategoryQtyRow">
+    <select id="selectCategoryQtyByFinishYear" resultType="com.ruoyi.web.modules.openstats.dto.CategoryQtyRow">
         select
             ifnull(c1.category_id, 0) as categoryId,
             ifnull(c1.category_name, '未分类') as categoryName,
@@ -15,7 +15,7 @@
         where o.order_status = '3'
           and o.order_status &lt;&gt; '5'
           and o.finish_time is not null
-          and date(o.finish_time) = #{statDate}
+          and year(o.finish_time) = #{statYear}
         group by ifnull(c1.category_id, 0), ifnull(c1.category_name, '未分类')
     </select>
 

baqing-shop/src/test/java/com/ruoyi/web/modules/openstats/service/MallStatsOpenServiceImplTest.java

@@ -42,7 +42,7 @@ import com.ruoyi.web.modules.openstats.vo.WordCloudItemVO;
 @ExtendWith(MockitoExtension.class)
 class MallStatsOpenServiceImplTest
 {
-    private static final String STAT_DATE = "2026-05-26";
+    private static final int STAT_YEAR = 2026;
 
     @Mock
     private MallStatsOpenMapper statsMapper;
@@ -65,26 +65,26 @@ class MallStatsOpenServiceImplTest
     @Test
     void categorySales_ratioSumNear100()
     {
-        when(statsMapper.selectCategoryQtyByFinishDate(STAT_DATE)).thenReturn(Arrays.asList(
+        when(statsMapper.selectCategoryQtyByFinishYear(STAT_YEAR)).thenReturn(Arrays.asList(
                 row(1L, "兽药", 500L),
                 row(2L, "饲料", 400L),
                 row(3L, "农药", 300L)));
 
-        CategorySalesVO vo = service.getCategorySales(STAT_DATE);
+        CategorySalesVO vo = service.getCategorySales("2026");
 
-        assertEquals(STAT_DATE, vo.getStatDate());
+        assertEquals(STAT_YEAR, vo.getStatYear());
         assertEquals(1200L, vo.getTotalQty());
         assertEquals(3, vo.getItems().size());
         double ratioSum = vo.getItems().stream().mapToDouble(i -> i.getRatio()).sum();
         assertEquals(100.0, ratioSum, 0.05);
-        verify(redisCache).setCacheObject(eq(StatsCacheKeys.categorySales(STAT_DATE)), eq(vo),
-                eq(OpenStatsConstants.CACHE_TTL_CATEGORY_MIN), eq(TimeUnit.MINUTES));
+        verify(redisCache).setCacheObject(eq(StatsCacheKeys.categorySales(STAT_YEAR)), eq(vo),
+                eq(OpenStatsConstants.CACHE_TTL_YEARLY_HOUR), eq(TimeUnit.HOURS));
     }
 
     @Test
     void hotCategoryRank_onlyTop5()
     {
-        when(statsMapper.selectCategoryQtyByFinishDate(STAT_DATE)).thenReturn(Arrays.asList(
+        when(statsMapper.selectCategoryQtyByFinishYear(STAT_YEAR)).thenReturn(Arrays.asList(
                 row(1L, "A", 100L),
                 row(2L, "B", 90L),
                 row(3L, "C", 80L),
@@ -92,8 +92,9 @@ class MallStatsOpenServiceImplTest
                 row(5L, "E", 60L),
                 row(6L, "F", 50L)));
 
-        HotCategoryRankVO vo = service.getHotCategoryRank(STAT_DATE);
+        HotCategoryRankVO vo = service.getHotCategoryRank("2026");
 
+        assertEquals(STAT_YEAR, vo.getStatYear());
         assertEquals(5, vo.getItems().size());
         assertEquals(1, vo.getItems().get(0).getRank());
         assertEquals("A", vo.getItems().get(0).getCategoryName());
@@ -164,14 +165,14 @@ class MallStatsOpenServiceImplTest
     @Test
     void overview_containsAllSections()
     {
-        when(statsMapper.selectCategoryQtyByFinishDate(anyString())).thenReturn(Collections.emptyList());
+        when(statsMapper.selectCategoryQtyByFinishYear(anyInt())).thenReturn(Collections.emptyList());
         when(statsMapper.selectOrderCountByYear(anyInt())).thenReturn(Collections.emptyList());
         when(statsMapper.selectShopCountByYear(anyInt())).thenReturn(Collections.emptyList());
         when(statsMapper.selectRegionAmountByYear(anyInt())).thenReturn(Collections.emptyList());
         when(statsMapper.selectReviewContentsForWordCloud()).thenReturn(Collections.emptyList());
         when(wordCloudSupport.buildTopWords(any())).thenReturn(new ReviewWordCloudVO());
 
-        StatsOverviewVO overview = service.getOverview(STAT_DATE, "2026");
+        StatsOverviewVO overview = service.getOverview("2026");
 
         assertNotNull(overview.getCategorySales());
         assertNotNull(overview.getHotCategoryRank());
@@ -179,7 +180,7 @@ class MallStatsOpenServiceImplTest
         assertNotNull(overview.getShopEntry());
         assertNotNull(overview.getRegionRank());
         assertNotNull(overview.getReviewWordCloud());
-        verify(statsMapper, atLeastOnce()).selectCategoryQtyByFinishDate(STAT_DATE);
+        verify(statsMapper, atLeastOnce()).selectCategoryQtyByFinishYear(STAT_YEAR);
     }
 
     private CategoryQtyRow row(Long id, String name, Long qty)

doc/平台后台/外部接口/商城数据统计功能需求-草稿.md

@@ -1,7 +1,7 @@
 做一个商城数据统计模块：
 
-1. 农资品类销售:根据农资商城中农资品类分类统计各个品类销售量与总销售量的占比；饼状图展示；农资品类分类以农资商城一级分类进行统计；时间为当前天；
-2. 热销农资排行（前5）：根据农资商城中农资品类分类统计各个品类销售量，展示销售量前5的热销农资；农资品类分类以农资商城一级分类进行统计；时间为当前天；
+1. 农资品类销售:根据农资商城中农资品类分类统计各个品类销售量与总销售量的占比；饼状图展示；农资品类分类以农资商城一级分类进行统计；时间为当前年份；
+2. 热销农资排行（前5）：根据农资商城中农资品类分类统计各个品类销售量，展示销售量前5的热销农资；农资品类分类以农资商城一级分类进行统计；时间为当前年份；
 3. 商城订单趋势: 按月统计当前年份每月的商城订单数（单），曲线图展示；
 4. 店铺入驻：按月统计当前年份每月入驻商城的店铺数（家），饼状图展示；
 5. 消费区域排名（前5）: 根据农资商城的订单的收货城市分类统计各个城市的农资销售额（万），展示前5的消费区域；

doc/平台后台/外部接口/商城数据统计功能需求.md

@@ -5,7 +5,7 @@
 > **说明：** 本文档 **仅描述功能需求、统计口径与业务规则**；**不涉及** 数据库结构、接口路径、Token 实现机制及技术栈细节。  
 > **v1.0：** 首版定稿；对齐草稿 §1～§7；补全时间口径、分类归属、订单/店铺/评价边界与空数据规则；排除草稿 §8～§9。  
 > **v1.0.1：** §5.2 **热销农资排行** 回归草稿口径——按 **平台一级品类** 当日销量 **Top5**（非商品 Top5）。  
-> **v1.0.2：** 明示 **完成时间** 含 **买家手动确认收货** 与 **系统自动确认收货**（《商城设置》）写入的时点，口径一致。
+> **v1.0.4：** §5.1、§5.2 **统计口径改为当前自然年**（与草稿一致）；按 **完成时间** 归属 **统计年** 汇总一级品类销量。
 
 ---
 
@@ -17,8 +17,8 @@
 
 | 序号 | 指标（草稿） | 展示形态（建议） |
 |:----:|--------------|------------------|
-| 1 | **农资品类销售** | 饼图：各 **一级品类** 当日销量占比 |
-| 2 | **热销农资排行（前 5）** | 列表/条形：当日销量 **Top5 一级品类** |
+| 1 | **农资品类销售** | 饼图：各 **一级品类** **当年**销量占比 |
+| 2 | **热销农资排行（前 5）** | 列表/条形：**当年**销量 **Top5 一级品类** |
 | 3 | **商城订单趋势** | 折线：当年 **逐月订单笔数** |
 | 4 | **店铺入驻** | 饼图：当年 **逐月新入驻店铺** 占比 |
 | 5 | **消费区域排名（前 5）** | 列表：当年 **Top5 收货城市** 销售额（万元） |
@@ -40,8 +40,8 @@
 
 | 草稿条目 | 定稿处理 |
 |----------|----------|
-| §1 农资品类销售 · 饼图 · 一级分类 · 当天 | §5.1 |
-| §2 热销农资排行 · 前 5 · 一级分类 · 当天 | §5.2（与 §5.1 **同口径**，输出 **销量 Top5 一级品类** 排行） |
+| §1 农资品类销售 · 饼图 · 一级分类 · **当前年份** | §5.1 |
+| §2 热销农资排行 · 前 5 · 一级分类 · **当前年份** | §5.2（与 §5.1 **同口径**，输出 **销量 Top5 一级品类** 排行） |
 | §3 商城订单趋势 · 按月 · 当年 · 折线 | §5.3 |
 | §4 店铺入驻 · 按月 · 当年 · 饼图 | §5.4 |
 | §5 消费区域排名 · 前 5 · 收货城市 · 销售额（万） | §5.5 |
@@ -67,9 +67,9 @@
 | 关联模块 | 关系 | 边界说明 |
 |----------|------|----------|
 | **商品分类** v1.5 | **口径依赖** | 品类统计 **仅平台一级分类**（`shop_id` 为空）；商品挂 **二级**，**归并至父级一级** |
-| **商品管理** v1.3.3 | **间接** | 当日销量 **按订单商品行汇总**；**不得** 用商品档案 **累计销量** 代替（见 §4.2） |
-| **订单管理** v1.0.1 | **强关联** | 订单趋势、区域销售额 **以订单为准**；**已完成** 参与金额/当日销量；**已删除** **不参与** |
-| **商城设置** v1.1 | **口径依赖** | **自动确认收货** 写入的 **完成时间** 与 **手动确认** **等价**，纳入 **统计日/统计年（完成侧）** 指标；C 端 **是否展示销量** **不影响** 本模块统计 |
+| **商品管理** v1.3.3 | **间接** | 当年销量 **按订单商品行汇总**；**不得** 用商品档案 **累计销量** 代替（见 §4.2） |
+| **订单管理** v1.0.1 | **强关联** | 订单趋势、区域销售额 **以订单为准**；**已完成** 参与金额/当年销量；**已删除** **不参与** |
+| **商城设置** v1.1 | **口径依赖** | **自动确认收货** 写入的 **完成时间** 与 **手动确认** **等价**，纳入 **统计年（完成侧）** 指标；C 端 **是否展示销量** **不影响** 本模块统计 |
 | **店铺管理** v1.3.5 | **强关联** | 入驻统计 **以店铺创建时间** 为准；含 **入驻审核通过建店** 与 **平台代开店** |
 | **评价管理** | **口径依赖** | 词云 **仅 C 端可见、未删除** 的买家评价 **正文** |
 | **会员管理 / 资金概览** | **无直接** | 本模块 **不输出** 会员数、平台资金 |
@@ -99,10 +99,10 @@
 | 项 | 定稿 |
 |----|------|
 | 订单笔数（§5.3） | 按 **下单时间** 归属自然月；**排除已删除**；**含** 待支付/待发货/已发货/已完成/已关闭 |
-| 当日销量（§5.1、§5.2） | 按订单 **完成时间** 归属 **自然日**（**含手动确认** 与 **自动确认收货**）；统计 **订单商品行销售件数** 之和 |
+| 当年销量（§5.1、§5.2） | 按订单 **完成时间** 归属 **自然年**（**含手动确认** 与 **自动确认收货**）；统计 **订单商品行销售件数** 之和 |
 | 区域销售额（§5.5） | 按订单 **完成时间** 归属 **自然年**（**含手动确认** 与 **自动确认收货**）；金额 = 订单 **实付金额**（与 O11 **累计消费金额** 同口径） |
-| 未完成订单 | **不计入** 当日销量与区域销售额 |
-| 已关闭 | **不计入** 当日销量与区域销售额；**可计入** 订单趋势笔数（若当月曾下单且未删） |
+| 未完成订单 | **不计入** 当年销量与区域销售额 |
+| 已关闭 | **不计入** 当年销量与区域销售额；**可计入** 订单趋势笔数（若当月曾下单且未删） |
 
 ### 2.3 与平台《商品分类功能需求》
 
@@ -127,7 +127,7 @@
 | 项 | 定稿 |
 |----|------|
 | 完成路径 | 订单 **已完成** 的 **完成时间** 来源：**买家手动确认收货** 或 **系统自动确认收货**（MC-O1～O3），**二者等价** |
-| 统计归属 | 以 **完成时间的日历日/日历年** 归属 **统计日**（§5.1、§5.2）或 **统计年完成侧指标**（§5.5）；**不** 以发货时间代替 |
+| 统计归属 | 以 **完成时间的日历年** 归属 **统计年**（§5.1、§5.2、§5.5）；**不** 以发货时间代替 |
 | 与 O7 | 与 **订单管理 O7**、**商城设置** 自动确认规则 **一致**；平台登记「送达」**不** 写入完成时间 |
 
 ---
@@ -136,8 +136,7 @@
 
 | 概念 | 说明 |
 |------|------|
-| 统计日 | **当前自然日**（服务器 **Asia/Shanghai** 日历日，下同） |
-| 统计年 | **当前自然年**（1 月 1 日～12 月 31 日） |
+| 统计年 | **当前自然年**（1 月 1 日～12 月 31 日，服务器 **Asia/Shanghai**） |
 | 平台一级品类 | 商品分类模块中 **平台维护**、**无上级** 的分类节点 |
 | 销售件数 | 某维度下 **已完成订单商品行** 的 **购买数量** 合计 |
 | 完成时间 | 订单进入 **已完成** 时写入的时点；含 **手动确认收货** 与 **自动确认收货**（《商城设置》），**口径相同** |
@@ -156,18 +155,18 @@
 
 | 指标组 | 时间范围 | 归属字段（业务语义） |
 |--------|----------|----------------------|
-| 农资品类销售、热销排行 | **统计日 = 当天** | 订单 **已完成** 的 **完成时间**（**含自动确认收货** 写入时刻） |
+| 农资品类销售、热销排行 | **统计年 = 当年** | 订单 **已完成** 的 **完成时间**（**含自动确认收货** 写入时刻） |
 | 订单趋势、店铺入驻 | **统计年 = 当年** | 订单 **下单时间** / 店铺 **创建时间** |
 | 消费区域排名 | **统计年 = 当年** | 订单 **已完成** 的 **完成时间**（**含自动确认收货** 写入时刻） |
 | 消费者评价词云 | **全量历史**（截至请求时刻） | 评价 **提交时间** **不参与** 过滤（草稿未限定时效） |
 
-### 4.2 当日销量 vs 商品累计销量
+### 4.2 当年销量 vs 商品累计销量
 
-| 维度 | 当日销量（§5.1、§5.2） | 商品档案 `sales_count` |
+| 维度 | 当年销量（§5.1、§5.2） | 商品档案 `sales_count` |
 |------|------------------------|-------------------------|
-| 用途 | 本模块 **当日** 排行/占比 | C 端展示 **累计** 销量 |
-| 口径 | **仅统计日当天完成** 的件数 | **历史全部已完成** 累计 |
-| 关系 | **不得** 用 `sales_count` 直接代替当日销量 | — |
+| 用途 | 本模块 **当年** 排行/占比 | C 端展示 **累计** 销量 |
+| 口径 | **仅统计年年内完成** 的件数 | **历史全部已完成** 累计 |
+| 关系 | **不得** 用 `sales_count` 直接代替当年销量 | — |
 
 ### 4.3 数据范围与排除
 
@@ -183,8 +182,8 @@
 
 | 场景 | 定稿 |
 |------|------|
-| 当日无任何完成订单 | 品类销售 **空列表或全 0**；热销 **空列表**；占比 **不展示** 或 **无饼图** |
-| 占比计算 | 各品类销量 / **当日有销量的品类销量合计** × 100%；**保留 1 位小数**；合计 **100%**（四舍五入误差 **归最大项或「其他」**，实现 **须一致**） |
+| 当年无任何完成订单 | 品类销售 **空列表或全 0**；热销 **空列表**；占比 **不展示** 或 **无饼图** |
+| 占比计算 | 各品类销量 / **当年有销量的品类销量合计** × 100%；**保留 1 位小数**；合计 **100%**（四舍五入误差 **归最大项或「其他」**，实现 **须一致**） |
 | 当年某月无订单/无新店 | 订单趋势/入驻 **该月记 0**，**仍返回 12 个月** |
 | 评价正文均空或无评价 | 词云 **空列表** |
 
@@ -205,12 +204,12 @@
 
 ### 5.1 农资品类销售
 
-**业务含义：** 展示 **统计日** 各 **平台一级品类** 的 **销售件数** 及 **占当日总销量比重**，供饼图渲染。
+**业务含义：** 展示 **统计年** 各 **平台一级品类** 的 **销售件数** 及 **占当年总销量比重**，供饼图渲染。
 
 **统计逻辑：**
 
 ```text
-取统计日内「已完成」的全部订单（完成时间 = 手动确认 或 自动确认收货写入时刻）
+取统计年内「已完成」的全部订单（完成时间 = 手动确认 或 自动确认收货写入时刻）
     → 展开订单商品行（goods_id、购买数量 qty）
     → 按 goods 的 category_id 找到平台二级分类
     → 归并至父级「一级品类」
@@ -230,21 +229,21 @@
 | 编号 | 规则 |
 |------|------|
 | **ST-C1** | **仅一级品类**；**不** 输出二级明细 |
-| **ST-C2** | 某品类当日 **0 件** → **可不返回该项** 或 **返回 0**（实现 **须六项接口一致**） |
+| **ST-C2** | 某品类当年 **0 件** → **可不返回该项** 或 **返回 0**（实现 **须六项接口一致**） |
 | **ST-C3** | **不** 含运费、**不** 按金额 |
 
 ### 5.2 热销农资排行（前 5）
 
-**业务含义：** 展示 **统计日** **销售件数最多** 的 **前 5 个平台一级品类**（草稿「根据农资品类分类统计各个品类销售量，展示销售量前 5」），供 **排行列表 / 条形图** 渲染。
+**业务含义：** 展示 **统计年** **销售件数最多** 的 **前 5 个平台一级品类**（草稿「根据农资品类分类统计各个品类销售量，展示销售量前 5」），供 **排行列表 / 条形图** 渲染。
 
-> **与 §5.1 的关系：** 二者 **统计口径相同**（均为统计日、已完成订单、归并至 **一级品类** 的销售件数）。**§5.1** 面向 **全量品类结构 + 占比（饼图）**；**§5.2** 面向 **销量 Top5 品类排行**，**不重复输出占比**（排行以 **销售件数** 为主字段）。
+> **与 §5.1 的关系：** 二者 **统计口径相同**（均为统计年、已完成订单、归并至 **一级品类** 的销售件数）。**§5.1** 面向 **全量品类结构 + 占比（饼图）**；**§5.2** 面向 **销量 Top5 品类排行**，**不重复输出占比**（排行以 **销售件数** 为主字段）。
 
 **统计逻辑：**
 
 ```text
 与 §5.1 相同，先得到各一级品类 categoryQty
     → 按 categoryQty 降序排序
-    → 取 Top5（当日有销量的品类不足 5 个则全部返回）
+    → 取 Top5（当年有销量的品类不足 5 个则全部返回）
     → 输出：排名序号、一级品类 ID/名称、销售件数
 ```
 
@@ -252,7 +251,7 @@
 |------|------|
 | **ST-H1** | **仅一级品类**；**不** 输出二级、**不** 输出单品（商品） |
 | **ST-H2** | **并列第 5** 时：按 **一级品类 ID 升序** 取满 5 条（**或** 全部并列返回导致 >5 条，产品 **择一** 并 **文档化**） |
-| **ST-H3** | 某品类当日 **0 件** **不参与** 排行 |
+| **ST-H3** | 某品类当年 **0 件** **不参与** 排行 |
 | **ST-H4** | **不** 输出店铺、商户、商品明细 |
 
 ### 5.3 商城订单趋势
@@ -370,7 +369,7 @@
 |----|------|
 | 场景 | 外部大屏 **定时刷新**（如 1～5 分钟）可能 **并发** 拉取 |
 | 要求 | 单次请求 **应在可接受等待时间内** 返回完整结果；**不** 因统计查询 **阻塞** 下单/支付/发货等 **交易主流程** |
-| 策略 | 允许 **预聚合、缓存** 统计结果；**当日/当年** 指标 **准实时** 即可（完成订单后 **下一次刷新周期内** 可见） |
+| 策略 | 允许 **预聚合、缓存** 统计结果；**统计年** 指标 **准实时** 即可（完成订单后 **下一次刷新周期内** 可见） |
 | 降级 | 极端情况下 **可返回空数据或上次缓存** 并 **记录告警**（**不** 返回错误业务数） |
 
 ---
@@ -391,7 +390,7 @@
 
 | 指标 | 建议刷新频率 |
 |------|--------------|
-| 品类销售、热销 Top5 | **≤5 分钟**（统计日指标） |
+| 品类销售、热销 Top5 | **≤1 小时**（统计年指标） |
 | 订单趋势、店铺入驻、区域 Top5 | **≤1 小时**（统计年指标） |
 | 评价词云 | **≤24 小时**（全量历史，变化慢） |
 
@@ -401,7 +400,7 @@
 
 | 事件 | 影响 |
 |------|------|
-| 订单完成后 | **当日/当年（完成侧）** 指标 **下一刷新周期** 纳入；**含系统自动确认收货** |
+| 订单完成后 | **统计年（完成侧）** 指标 **下一刷新周期** 纳入；**含系统自动确认收货** |
 | 订单改 **已删除** | 从 **订单趋势** 等 **剔除**（若实现按当前状态重算） |
 | 店铺逻辑删除 | **入驻统计不回退**；**不影响** 历史订单统计 |
 | 分类调整层级 | **历史商品** **仍按档案 category_id** 归并 |
@@ -438,10 +437,10 @@
 
 | 编号 | 场景 | 预期 |
 |------|------|------|
-| **ST-TST1** | 统计日有 3 个一级品类完成销量 | 饼图 **三项占比合计 ≈100%** |
-| **ST-TST2** | 某一级品类当日销量排第 6 | **不出现在** Top5 排行 |
-| **ST-TST3** | 3 月下单、4 月手动完成 | **订单趋势计 3 月**；**当日销量计 4 月完成日** |
-| **ST-TST3a** | 已发货超期 **自动确认收货** 于 5 月 2 日完成 | **当日销量/区域金额** 计 **5 月 2 日**（**非** 发货日） |
+| **ST-TST1** | 统计年有 3 个一级品类完成销量 | 饼图 **三项占比合计 ≈100%** |
+| **ST-TST2** | 某一级品类当年销量排第 6 | **不出现在** Top5 排行 |
+| **ST-TST3** | 3 月下单、4 月手动完成 | **订单趋势计 3 月**；**当年销量计 4 月完成年** |
+| **ST-TST3a** | 已发货超期 **自动确认收货** 于 5 月 2 日完成 | **当年销量/区域金额** 计 **完成年**（**非** 发货日） |
 | **ST-TST4** | 2 月创建店铺 | **入驻饼图 2 月扇区 +1** |
 | **ST-TST5** | 北京、上海已完成实付 | **区域排名** 按 **万元** 降序 **Top5** |
 | **ST-TST6** | 100 条含「质量好」评价 | 词云 **含「质量好」** 且频次 **合理** |
@@ -458,5 +457,6 @@
 | **v1.0.1** | §5.2 热销排行改为 **一级品类 Top5**，与草稿及 §5.1 口径一致 |
 | **v1.0.2** | 完成时间 **含自动确认收货**；新增 §2.5、ST-R3、ST-TST3a |
 | **v1.0.3** | Token 认证改为 **调用方 AES 加密 UUID**；ST-T2/T3、§7 流程与边界对齐技术方案 v1.1 |
+| **v1.0.4** | §5.1、§5.2 统计口径改为 **当前自然年**（`finish_time` 归属统计年）；与草稿一致 |
 
-*文档版本：v1.0.3 · 关联《商城数据统计功能需求-草稿》、《关联需求分析.md》v1.6、《商品分类功能需求》v1.5、《订单管理功能需求》v1.0.1、《商城设置功能需求》v1.1、《店铺管理功能需求》v1.3.5、《评价管理功能需求》、《我的订单功能需求》v1.1*
+*文档版本：v1.0.4 · 关联《商城数据统计功能需求-草稿》、《关联需求分析.md》v1.6、《商品分类功能需求》v1.5、《订单管理功能需求》v1.0.1、《商城设置功能需求》v1.1、《店铺管理功能需求》v1.3.5、《评价管理功能需求》、《我的订单功能需求》v1.1*

doc/平台后台/外部接口/商城数据统计技术方案.md

@@ -1,6 +1,6 @@
 # 商城数据统计 — 技术方案
 
-> **依据：** 《商城数据统计功能需求.md》v1.0.3  
+> **依据：** 《商城数据统计功能需求.md》v1.0.4  
 > **关联：** 《订单管理技术方案.md》v1.0.2、《商品分类功能需求》v1.5、《商城设置技术方案.md》v1.1  
 > **范围：** 对外 **只读** 六项统计；**无** 平台 Web 菜单；**不新建** 业务明细表，**聚合查询** 现有订单/分类/店铺/评价数据。  
 > **原则：** 统计 **不阻塞** 交易写路径；**准实时** + **Redis 缓存**；Token **与** 会员 JWT **隔离**。
@@ -103,7 +103,7 @@ biz_order_item oi
 
 ```sql
 o.order_status = '3'
-AND DATE(o.finish_time) = #{statDate}   -- 当天，Asia/Shanghai
+AND YEAR(o.finish_time) = #{statYear}   -- 当年，Asia/Shanghai
 AND o.order_status <> '5'
 ```
 
@@ -190,20 +190,19 @@ WHERE del_flag = '0' AND show_flag = '1'
 
 | 方法 | 路径 | 功能需求 | 缓存 TTL |
 |------|------|----------|----------|
-| GET | `/categorySales` | §5.1 品类销售 | 5 min |
-| GET | `/hotCategoryRank` | §5.2 热销 Top5 品类 | 5 min |
+| GET | `/categorySales` | §5.1 品类销售 | 1 h |
+| GET | `/hotCategoryRank` | §5.2 热销 Top5 品类 | 1 h |
 | GET | `/orderTrend` | §5.3 订单趋势 | 1 h |
 | GET | `/shopEntry` | §5.4 店铺入驻 | 1 h |
 | GET | `/regionRank` | §5.5 区域 Top5 | 1 h |
 | GET | `/reviewWordCloud` | §5.6 词云 Top50 | 24 h |
 | GET | `/overview` | **组合** 上述六项（大屏一次拉取） | 取各子项最小 TTL |
 
-**Query（可选，默认当天/当年）：**
+**Query（可选，默认当年）：**
 
 | 参数 | 适用 | 默认 |
 |------|------|------|
-| `statDate` | categorySales、hotCategoryRank | 今天 `yyyy-MM-dd` |
-| `statYear` | orderTrend、shopEntry、regionRank | 今年 `yyyy` |
+| `statYear` | categorySales、hotCategoryRank、orderTrend、shopEntry、regionRank、overview | 今年 `yyyy` |
 
 > v1 **不开放** 任意历史区间（对齐功能需求非本期）；参数 **仅用于联调**，生产大屏 **可不传**。
 
@@ -213,7 +212,7 @@ WHERE del_flag = '0' AND show_flag = '1'
 
 ```json
 {
-  "statDate": "2026-05-26",
+  "statYear": 2026,
   "totalQty": 1200,
   "items": [
     { "categoryId": 1, "categoryName": "兽药", "qty": 500, "ratio": 41.7 }
@@ -225,7 +224,7 @@ WHERE del_flag = '0' AND show_flag = '1'
 
 ```json
 {
-  "statDate": "2026-05-26",
+  "statYear": 2026,
   "items": [
     { "rank": 1, "categoryId": 1, "categoryName": "兽药", "qty": 500 }
   ]
@@ -347,8 +346,8 @@ Header: X-Open-Token: {token}
 
 | Redis Key 示例 | TTL |
 |----------------|-----|
-| `openstats:cat:sales:{statDate}` | 5 min |
-| `openstats:cat:hot:{statDate}` | 5 min |
+| `openstats:cat:sales:{year}` | 1 h |
+| `openstats:cat:hot:{year}` | 1 h |
 | `openstats:order:month:{year}` | 1 h |
 | `openstats:shop:month:{year}` | 1 h |
 | `openstats:region:{year}` | 1 h |
@@ -382,7 +381,7 @@ Header: X-Open-Token: {token}
 | ST-A* | §3.4 + `pay_amount` |
 | ST-RV* | §3.5 + `del_flag=0 AND show_flag=1` |
 | ST-T* | Filter + AES 解密 + UUID 校验（`OpenStatsTokenCryptoSupport`） |
-| ST-TST3a | 自动确认写入的 `finish_time` 参与 §3.1 日期过滤 |
+| ST-TST3a | 自动确认写入的 `finish_time` 参与 §3.1 **统计年** 过滤 |
 
 ---
 
@@ -407,9 +406,9 @@ Header: X-Open-Token: {token}
 | 编号 | 场景 |
 |------|------|
 | OS-T1 | 无 Token / 明文 UUID / 错误密文 → 401 |
-| OS-T2 | 当日 3 品类完成单 → 占比合计 ≈100% |
+| OS-T2 | 当年 3 品类完成单 → 占比合计 ≈100% |
 | OS-T3 | 品类销量第 6 → 不在 hotCategoryRank |
-| OS-T4 | 自动确认 `finish_time` 在今日 → 计入 categorySales |
+| OS-T4 | 自动确认 `finish_time` 在 **当年** → 计入 categorySales |
 | OS-T5 | `order_status=5` → 各接口均不计 |
 | OS-T6 | overview 六项结构与单接口一致 |
 | OS-T7 | 第二次请求命中 Redis（集成环境可观测） |
@@ -421,6 +420,7 @@ Header: X-Open-Token: {token}
 | 版本 | 说明 |
 |------|------|
 | **v1.0** | 首版：RuoYi3.9.2 + MySQL5.7；复用业务表聚合；六项 Open API + overview；Redis 缓存 |
+| **v1.2** | §5.1/§5.2 改为 **统计年**（`YEAR(finish_time)`）；接口参数统一 `statYear`；缓存 key/TTL 对齐年度指标 |
 | **v1.1** | Token 改为 **AES-128-CBC 加密 UUID** 校验；**移除** `biz_open_api_token` 库表方案 |
 
-*文档版本：v1.1 · 关联《商城数据统计功能需求.md》v1.0.3 · 统计索引：`sql/biz_order.sql` → `idx_stats_finish`*
+*文档版本：v1.2 · 关联《商城数据统计功能需求.md》v1.0.4 · 统计索引：`sql/biz_order.sql` → `idx_stats_finish`*

ruoyi-common/src/main/java/com/ruoyi/common/filter/PageHelperClearFilter.java

@@ -0,0 +1,30 @@
+package com.ruoyi.common.filter;
+
+import java.io.IOException;
+import javax.servlet.Filter;
+import javax.servlet.FilterChain;
+import javax.servlet.ServletException;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import com.github.pagehelper.PageHelper;
+
+/**
+ * 清理 PageHelper 线程变量，避免 Tomcat 线程复用导致分页参数泄漏到后续请求。
+ */
+public class PageHelperClearFilter implements Filter
+{
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
+            throws IOException, ServletException
+    {
+        PageHelper.clearPage();
+        try
+        {
+            chain.doFilter(request, response);
+        }
+        finally
+        {
+            PageHelper.clearPage();
+        }
+    }
+}

ruoyi-framework/src/main/java/com/ruoyi/framework/config/FilterConfig.java

@@ -9,6 +9,7 @@ import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import com.ruoyi.common.constant.Constants;
+import com.ruoyi.common.filter.PageHelperClearFilter;
 import com.ruoyi.common.filter.RefererFilter;
 import com.ruoyi.common.filter.RepeatableFilter;
 import com.ruoyi.common.filter.XssFilter;
@@ -65,6 +66,19 @@ public class FilterConfig
         return registration;
     }
 
+    @SuppressWarnings({ "rawtypes", "unchecked" })
+    @Bean
+    public FilterRegistrationBean pageHelperClearFilterRegistration()
+    {
+        FilterRegistrationBean registration = new FilterRegistrationBean();
+        registration.setDispatcherTypes(DispatcherType.REQUEST);
+        registration.setFilter(new PageHelperClearFilter());
+        registration.addUrlPatterns("/*");
+        registration.setName("pageHelperClearFilter");
+        registration.setOrder(FilterRegistrationBean.HIGHEST_PRECEDENCE);
+        return registration;
+    }
+
     @SuppressWarnings({ "rawtypes", "unchecked" })
     @Bean
     public FilterRegistrationBean someFilterRegistration()