feat(mcp): 新增人流量统计工具，统计类工具查询区间统一限一个月

- district.traffic.statistics.query：复刻老 trafficStatistics 饼图与
  trafficStatisticsDetail 折线图，SUM(use_count) 按 gender/日期×gender 聚合，
  view=gender 占比 + view=daily_gender 按日趋势零填充（修正老系统插入错位 bug）
- 行级权限对齐 district.paper.* 系列；gender=null 归「未配置」不再 NPE
- 日期区间硬限 31 天（一个月），超出报错提示修改日期（2026-09-24 拍板）；
  district.paper.percapita.query 与 district.paper.device_average.query 同步加限，
  与 Redis StatisticsDays 取更严
- 新增 12 个单测；设计文档 doc/traffic-statistics-mcp-tool-design.md

xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

@@ -835,7 +835,7 @@
   未参与的维度为 null；无数据日期或分组不补零。`daily=false` 另返回区间 `totalPerCapita`。
 - gender 文案：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他。
 - 行级权限：先用 `applyDistrictRowFilter` 校验站点可见性；不可见统一返回“站点不存在或无权访问”。
-- 日期不得晚于今天，查询天数受 Redis `Dictionary.StatisticsDays` 限制。
+- 日期不得晚于今天；查询区间硬限 31 天（一个月，2026-09-24 拍板），且受 Redis `Dictionary.StatisticsDays` 限制，两者取更严。
 - scope：仅绑定 `service_enabled=0` 的用户委托作用域，不向服务身份作用域开放。
 
 详细设计见 `paper-percapita-statistics-mcp-design.md`。
@@ -861,7 +861,7 @@
 - gender 文案：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他；null 为未配置，其他整数显示 `未知(code)`。
 - 行级权限：先用 `applyDistrictRowFilter` 校验站点可见性；不可见统一返回 `NOT_FOUND_OR_FORBIDDEN`。
   tenant_service 仅可通过 `ops-query` 调用，按总部视角查询。
-- 日期不得晚于上海时区当天，查询自然日数受 Redis `Dictionary.StatisticsDays` 限制。
+- 日期不得晚于上海时区当天；查询区间硬限 31 天（一个月，2026-09-24 拍板），且受 Redis `Dictionary.StatisticsDays` 限制，两者取更严。
 
 示例响应：
 
@@ -926,6 +926,30 @@
 
 ---
 
+## 37. district.traffic.statistics.query
+
+查询站点人流量统计（人次，SUM(use_count)），复刻老 `StatisticsReportController.trafficStatistics`（饼图）
+与 `trafficStatisticsDetail`（折线图）。
+
+- 分类：customer ｜ 类型：读
+- 数据来源：m0 `monthly_statistics` 日汇总表，固定 `soft_delete=0`、指定站点和日期范围，DB 完成聚合；不查 ES。
+- 入参：`districtId`、`startDate`、`endDate`、`view`（gender=人流量占比、daily_gender=按日趋势），以及可选
+  `deviceType`（非负整数透传，不限枚举）、`buildingIds`/`floors`/`toiletIds`（列表内 IN，维度间 AND）。
+- `view=gender` 返回 `totalCount` 与 `rows[]`（genderCode/gender/useCount/percent，percent 两位小数 HALF_UP，
+  totalCount=0 时 percent=0）。
+- `view=daily_gender` 返回 `dates[]`（区间全日期）与 `series[]`（genderCode/gender/useCount/values），
+  values 与 dates 等长零填充——修正了老系统首次分组插入错位的 bug。
+- gender 文案：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他；null 为「未配置」，其他整数 `未知(code)`。
+- 行级权限：`applyDistrictRowFilter` 校验站点可见性，不可见返回「站点不存在或无权访问」；
+  tenant_service 按总部视角查询。
+- 日期不得晚于今天；查询区间硬限 31 天（一个月，2026-09-24 拍板），超出报错提示修改日期，
+  不依赖 Redis StatisticsDays。
+- 无数据时 `totalCount=0`、rows/series 为空，并在 notice 说明。
+
+详细设计见 [traffic-statistics-mcp-tool-design](traffic-statistics-mcp-tool-design.md)。
+
+---
+
 ---
 
 ## 附录：在线查看工具清单