mtsd/docs/superpowers/specs/2026-04-29-web-admin-dashboard-console-region-tab-and-scope-design.md

Web Admin 工作台 Console 顶部区域 Tab（权限范围汇总）设计

背景

http://localhost:3006/#/dashboard/console 的“今日各区域”“今日下单客户”“概览卡片/最新订单/趋势图”等统计数据目前是全局拉取。 需要新增顶部“区域 Tab”，并按角色展示不同范围的数据：

• super_admin：可以看到所有区域 Tab，并且“全部区域”展示全量数据
• admin/运营人员：只能看到其权限范围内的区域 Tab，并且“全部区域”展示其权限范围内区域的数据之和

目标（用户可见行为）

1. Console 页面最顶部新增区域 Tab 栏
2. Tab 默认选中“全部区域”
3. 区域 Tab 文案形如：全部区域、区域A、区域B…
4. 页面展示的数据随 Tab 切换：
   • 选中单个区域：仅展示该区域数据
   • 选中“全部区域”：取该角色可见的区域集合进行汇总
     • 数值按规则求和
     • “趋势折线”按日期聚合求和
     • “今日各区域柱状图”按 region 聚合求和
     • “今日下单客户柱状图”按 client 聚合求和后排序取前 N（N 取当前页面的固定 limit，不引入额外条数规则）
     • “最新订单”合并后按 createAt 倒序排序显示（不引入新增条数规则）

非目标

• 不重构后端接口
• 不更改“订单列表/配送列表”等其它页面的筛选行为（仅确保 Console 自身数据范围正确）

数据与接口

当前 Console 页面使用的统计接口（均支持 regionId）：

• fetchWorkbenchDashboard({ regionId? })：概览卡片、recentOrders、todoSnapshots、warningCount 等
• fetchOrderTrend({ regionId?, days })：近 30 日趋势折线（按日期包含 orderCount 与 orderAmount）
• fetchTodayOrdersByRegion({ regionId? })：今日各区域统计（列表项包含 regionId/regionName/orderCount/orderAmount）
• fetchTodayOrdersByClient({ regionId?, limit })：今日下单客户统计（列表项包含 clientId/clientName/orderAmount/productQuantity）

新增取数所需的区域列表：

• fetchActiveRegions()：加载启用区域，用于构建 Tab 列表

权限区域来源：

• useUserStore().getUserInfo.role
• useUserStore().getUserInfo.regionIds（多区域）
• 兼容 getUserInfo.regionId（单区域）

交互与状态机

1. UI 状态：
   • activeRegionTabKey：
     • all：代表“全部区域”
     • regionId：代表单个区域
2. 可见区域集合：
   • super_admin：visibleRegionIds = allActiveRegionIds
   • 运营 admin：visibleRegionIds = userRegionIds
3. Tab 默认：
   • 默认选中 all

汇总策略（admin 多区域 && all Tab）

当角色为运营且选中“全部区域”，将对 visibleRegionIds 中每个 regionId 并行/串行拉取对应接口结果，并汇总：

1) 概览与最新订单（fetchWorkbenchDashboard）

• 数值字段求和：
  • todayOrderCount、todayOrderAmount、pendingDeliveryCount、customerCount、supplierCount、deliveryWarningCount 等按字段求和
• todoSnapshots：
  • 以 type 为 key 聚合 count 求和
  • items 做去重合并（保留顺序不做强制，展示以去重后数组为准）
• recentOrders：
  • 合并各区域的 recentOrders 数组
  • 按 createAt 倒序排序
  • 条数：取“单区域接口返回的 recentOrders 数量”为基准（即不额外定义一条新规则；若单区域返回为空则使用当前页面原有行为兜底）

2) 趋势折线（fetchOrderTrend）

• 对每个区域拉取同样 days（页面固定 30）
• 按 date 聚合：
  • 同一天的 orderCount 求和
  • 同一天的 orderAmount 求和
• 最终输出顺序与接口 date 顺序保持一致

3) 今日各区域柱状图（fetchTodayOrdersByRegion）

• 合并所有区域返回列表
• 按 regionId 聚合求和：
  • orderCount 求和
  • orderAmount 求和
• 图表展示顺序：按 visibleRegionIds 的顺序渲染（更符合用户直觉）

4) 今日下单客户柱状图（fetchTodayOrdersByClient）

• 对每个区域拉取 limit=30（与现有页面一致）
• 按 clientId 聚合：
  • orderAmount 求和
  • productQuantity 求和
• 汇总后按 orderAmount 倒序排序取前 limit（复用现有 limit，不引入新条数规则）

UI 约束与样式

• Tab 样式沿用其它页面的 region-tabs region-tab-strip / tab-button-group / region-tab-btn
• Tab 默认选中“全部区域”

错误处理

• 任一区域接口失败：
  • 保底：该区域结果视为“空集合”
  • 页面仍展示其它区域汇总结果
• 若全部区域失败：
  • 回退到空数据并关闭 loading

测试建议（手工验证）

1. super_admin：
   • Tab 中能看到所有区域 + 全部区域
   • 切到任一单区域：图表/概览/最新订单都只显示该区域
   • 切到“全部区域”：恢复全量
2. admin（权限区域 A,B）：
   • Tab 仅展示 A,B（加上全部区域）
   • 切到“全部区域”：概览数值等于 A + B 的汇总
   • “趋势折线/今日柱状图/客户柱状图/最新订单”满足上述聚合规则与排序规则