From d82632414a1f4dcfd10deda3a5d0d1b5b13b3c26 Mon Sep 17 00:00:00 2001
From: eafonyang <eafonyang@gmail.com>
Date: Mon, 21 Sep 2026 15:55:09 +0800
Subject: [PATCH] =?UTF-8?q?feat(frontend):=20=E6=96=B0=E5=A2=9E=E8=AE=BE?=
 =?UTF-8?q?=E5=A4=87=E5=9E=8B=E5=8F=B7=E7=89=88=E6=9C=AC=E5=88=86=E5=B8=83?=
 =?UTF-8?q?=E7=BB=9F=E8=AE=A1=E4=B8=8E=E5=B1=95=E7=A4=BA=E6=A8=A1=E5=9D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 后端新增接口，按型号统计全量设备版本分布，空版本计入“未知版本”
- 前端API添加获取设备版本分布的请求方法
- 首页新增各型号版本占比的饼图展示，支持展开查看完整版本列表
- 饼图支持高亮显示前10大版本，其他版本合并显示
- 设备版本数据加载失败时提供重试功能
- 优化客服反馈状态下拉选项类型定义及默认值
- 组件重构饼图模块，增强易用性和可访问性
---
 dashboard/backend/src/routes/dashboard.ts     |  42 ++++
 .../frontend/src/service/api/dashboard.ts     |   7 +
 .../frontend/src/typings/api/dashboard.d.ts   |  13 ++
 .../customer-service/feedbacks/index.vue      |   6 +-
 dashboard/frontend/src/views/home/index.vue   |  45 +++-
 .../src/views/home/modules/pie-chart.vue      | 213 ++++++++++--------
 6 files changed, 230 insertions(+), 96 deletions(-)

diff --git a/dashboard/backend/src/routes/dashboard.ts b/dashboard/backend/src/routes/dashboard.ts
index 8fe4123..9803519 100644
--- a/dashboard/backend/src/routes/dashboard.ts
+++ b/dashboard/backend/src/routes/dashboard.ts
@@ -268,4 +268,46 @@ router.get('/api/dashboard/active-daily', async (req: Request, res: Response) =>
   }
 });
 
+/**
+ * GET /api/dashboard/device-versions
+ * 按型号统计全量设备的版本分布，空版本计入“未知版本”
+ */
+router.get('/api/dashboard/device-versions', async (_req: Request, res: Response) => {
+  try {
+    const version = sql<string>`COALESCE(NULLIF(TRIM(${userDevices.ver}), ''), '未知版本')`;
+    const rows = await db
+      .select({
+        model: userDevices.model,
+        ver: version.as('version'),
+        count: sql<number>`COUNT(*)`.mapWith(Number).as('count'),
+      })
+      .from(userDevices)
+      .groupBy(userDevices.model, version)
+      .orderBy(userDevices.model, desc(sql`COUNT(*)`), version);
+
+    const modelMap = new Map<string, {
+      model: string;
+      total: number;
+      versions: Array<{ ver: string; count: number }>;
+    }>();
+
+    for (const row of rows) {
+      let stats = modelMap.get(row.model);
+      if (!stats) {
+        stats = { model: row.model, total: 0, versions: [] };
+        modelMap.set(row.model, stats);
+      }
+      const count = Number(row.count);
+      stats.total += count;
+      stats.versions.push({ ver: row.ver, count });
+    }
+
+    res.json(ApiResponse.success({ items: [...modelMap.values()] }));
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    logger.error(`获取设备版本分布失败：${msg}`);
+    res.json(ApiResponse.error(`获取设备版本分布失败：${msg}`));
+  }
+});
+
 export default router;
diff --git a/dashboard/frontend/src/service/api/dashboard.ts b/dashboard/frontend/src/service/api/dashboard.ts
index 2f58ac9..9215577 100644
--- a/dashboard/frontend/src/service/api/dashboard.ts
+++ b/dashboard/frontend/src/service/api/dashboard.ts
@@ -15,6 +15,13 @@ export function fetchGetDeviceDaily(days: number = 30) {
   });
 }
 
+export function fetchGetDeviceVersions() {
+  return request<Api.Dashboard.DeviceVersionStats>({
+    url: '/dashboard/device-versions',
+    method: 'get'
+  });
+}
+
 export function fetchGetActiveDaily(days: number = 30) {
   return request<Api.Dashboard.ActiveDailyStats>({
     url: '/dashboard/active-daily',
diff --git a/dashboard/frontend/src/typings/api/dashboard.d.ts b/dashboard/frontend/src/typings/api/dashboard.d.ts
index 14d9ab0..22a084e 100644
--- a/dashboard/frontend/src/typings/api/dashboard.d.ts
+++ b/dashboard/frontend/src/typings/api/dashboard.d.ts
@@ -49,6 +49,19 @@ declare namespace Api {
       total: number;
     }
 
+    interface DeviceVersionModel {
+      model: string;
+      total: number;
+      versions: Array<{
+        ver: string;
+        count: number;
+      }>;
+    }
+
+    interface DeviceVersionStats {
+      items: DeviceVersionModel[];
+    }
+
     interface ActiveDailyStats {
       dates: string[];
       series: DeviceDailySeries[];
diff --git a/dashboard/frontend/src/views/customer-service/feedbacks/index.vue b/dashboard/frontend/src/views/customer-service/feedbacks/index.vue
index 1f05529..fd90a69 100644
--- a/dashboard/frontend/src/views/customer-service/feedbacks/index.vue
+++ b/dashboard/frontend/src/views/customer-service/feedbacks/index.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, h, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue';
-import { NButton, NDrawer, NDrawerContent, NInput, NSelect, NSpace, NTag, type DataTableColumns } from 'naive-ui';
+import { NButton, NDrawer, NDrawerContent, NInput, NSelect, NSpace, NTag, type DataTableColumns, type SelectOption } from 'naive-ui';
 import {
   fetchGetSupportFeedbacks,
   fetchGetSupportFeedbackMessages,
@@ -38,8 +38,8 @@ const pagination = reactive({
   pageSizes: [10, 20, 50],
 });
 
-const statusOptions = [
-  { label: '全部', value: null },
+const statusOptions: SelectOption[] = [
+  { label: '全部', value: '' },
   { label: '待处理', value: 'pending' },
   { label: '处理中', value: 'processing' },
   { label: '已解决', value: 'resolved' },
diff --git a/dashboard/frontend/src/views/home/index.vue b/dashboard/frontend/src/views/home/index.vue
index 2689cda..0bf3653 100644
--- a/dashboard/frontend/src/views/home/index.vue
+++ b/dashboard/frontend/src/views/home/index.vue
@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch, nextTick } from 'vue';
-import { fetchGetDashboardToday, fetchGetDeviceDaily, fetchGetActiveDaily } from '@/service/api';
+import { fetchGetDashboardToday, fetchGetDeviceDaily, fetchGetActiveDaily, fetchGetDeviceVersions } from '@/service/api';
 import { useAuthStore } from '@/store/modules/auth';
 import { useThemeStore } from '@/store/modules/theme';
 import { useEcharts } from '@/hooks/common/echarts';
 import type { ECOption } from '@/hooks/common/echarts';
+import PieChart from './modules/pie-chart.vue';
 
 defineOptions({ name: 'Home' });
 
@@ -269,6 +270,28 @@ watch(activeDays, () => {
   loadActiveDaily();
 });
 
+// ===== 各型号版本占比（全量设备） =====
+const versionLoading = ref(false);
+const versionLoadFailed = ref(false);
+const deviceVersions = ref<Api.Dashboard.DeviceVersionModel[]>([]);
+
+async function loadDeviceVersions() {
+  versionLoading.value = true;
+  versionLoadFailed.value = false;
+  try {
+    const { data, error } = await fetchGetDeviceVersions();
+    if (error || !data) {
+      versionLoadFailed.value = true;
+      return;
+    }
+    deviceVersions.value = data.items;
+  } catch {
+    versionLoadFailed.value = true;
+  } finally {
+    versionLoading.value = false;
+  }
+}
+
 // 主题切换时用已有数据重建图表（颜色自适应）
 watch(isDark, () => {
   nextTick(() => {
@@ -285,6 +308,7 @@ onMounted(() => {
   loadTodayStats();
   loadDeviceDaily();
   loadActiveDaily();
+  loadDeviceVersions();
 });
 </script>
 
@@ -375,6 +399,25 @@ onMounted(() => {
         </NCard>
       </NGi>
     </NGrid>
+
+    <NCard :bordered="false" class="card-wrapper" title="各型号版本占比">
+      <NSpace vertical :size="16">
+        <NText depth="3">按各型号全部设备统计，未上报版本号的设备计入“未知版本”。</NText>
+        <NSpin :show="versionLoading">
+          <NEmpty v-if="versionLoadFailed" description="版本分布加载失败">
+            <template #extra>
+              <NButton size="small" @click="loadDeviceVersions">重试</NButton>
+            </template>
+          </NEmpty>
+          <NGrid v-else-if="deviceVersions.length" cols="1 m:2 xl:3" responsive="screen" :x-gap="16" :y-gap="16">
+            <NGi v-for="item in deviceVersions" :key="item.model">
+              <PieChart :stats="item" />
+            </NGi>
+          </NGrid>
+          <NEmpty v-else :description="versionLoading ? '正在加载版本分布' : '暂无设备版本数据'" />
+        </NSpin>
+      </NSpace>
+    </NCard>
   </NSpace>
 </template>
 
diff --git a/dashboard/frontend/src/views/home/modules/pie-chart.vue b/dashboard/frontend/src/views/home/modules/pie-chart.vue
index 9ff7978..3f5ba9e 100644
--- a/dashboard/frontend/src/views/home/modules/pie-chart.vue
+++ b/dashboard/frontend/src/views/home/modules/pie-chart.vue
@@ -1,108 +1,137 @@
 <script setup lang="ts">
-import { watch } from 'vue';
-import { useAppStore } from '@/store/modules/app';
+import { computed, ref, useId, watch } from 'vue';
+import type { DataTableColumns } from 'naive-ui';
 import { useEcharts } from '@/hooks/common/echarts';
-import { $t } from '@/locales';
+import type { ECOption } from '@/hooks/common/echarts';
 
 defineOptions({
   name: 'PieChart'
 });
 
-const appStore = useAppStore();
+const props = defineProps<{
+  stats: Api.Dashboard.DeviceVersionModel;
+}>();
 
-const { domRef, updateOptions } = useEcharts(() => ({
-  tooltip: {
-    trigger: 'item'
-  },
-  legend: {
-    bottom: '1%',
-    left: 'center',
-    itemStyle: {
-      borderWidth: 0
-    }
-  },
-  series: [
-    {
-      color: ['#5da8ff', '#8e9dff', '#fedc69', '#26deca'],
-      name: $t('page.home.schedule'),
-      type: 'pie',
-      radius: ['45%', '75%'],
-      avoidLabelOverlap: false,
-      itemStyle: {
-        borderRadius: 10,
-        borderColor: '#fff',
-        borderWidth: 1
-      },
-      label: {
-        show: false,
-        position: 'center'
-      },
-      emphasis: {
-        label: {
-          show: true,
-          fontSize: '12'
-        }
-      },
-      labelLine: {
-        show: false
-      },
-      data: [] as { name: string; value: number }[]
-    }
-  ]
-}));
-
-async function mockData() {
-  await new Promise(resolve => {
-    setTimeout(resolve, 1000);
-  });
-
-  updateOptions(opts => {
-    opts.series[0].data = [
-      { name: $t('page.home.study'), value: 20 },
-      { name: $t('page.home.entertainment'), value: 10 },
-      { name: $t('page.home.work'), value: 40 },
-      { name: $t('page.home.rest'), value: 30 }
-    ];
-
-    return opts;
-  });
-}
-
-function updateLocale() {
-  updateOptions((opts, factory) => {
-    const originOpts = factory();
-
-    opts.series[0].name = originOpts.series[0].name;
-
-    opts.series[0].data = [
-      { name: $t('page.home.study'), value: 20 },
-      { name: $t('page.home.entertainment'), value: 10 },
-      { name: $t('page.home.work'), value: 40 },
-      { name: $t('page.home.rest'), value: 30 }
-    ];
-
-    return opts;
-  });
-}
-
-async function init() {
-  mockData();
-}
-
-watch(
-  () => appStore.locale,
-  () => {
-    updateLocale();
-  }
+const TOP_VERSION_LIMIT = 10;
+const expanded = ref(false);
+const versionListId = useId();
+const sortedVersions = computed(() =>
+  [...props.stats.versions].sort((a, b) => b.count - a.count || a.ver.localeCompare(b.ver))
+);
+const topVersions = computed(() => sortedVersions.value.slice(0, TOP_VERSION_LIMIT));
+const remainingCount = computed(() =>
+  sortedVersions.value.slice(TOP_VERSION_LIMIT).reduce((sum, item) => sum + item.count, 0)
 );
 
-// init
-init();
+function formatPercent(count: number) {
+  return props.stats.total > 0 ? `${((count / props.stats.total) * 100).toFixed(2)}%` : '0.00%';
+}
+
+const versionColumns: DataTableColumns<Api.Dashboard.DeviceVersionModel['versions'][number]> = [
+  { title: '版本号', key: 'ver', ellipsis: { tooltip: true } },
+  { title: '用户数量', key: 'count', align: 'right', width: 90 },
+  { title: '占比', key: 'percent', align: 'right', width: 90, render: row => formatPercent(row.count) }
+];
+
+function buildOptions(): ECOption {
+  const chartData = topVersions.value.map(item => ({ name: item.ver, value: item.count }));
+  if (remainingCount.value > 0) {
+    chartData.push({ name: '其他', value: remainingCount.value });
+  }
+  return {
+    color: ['#5B8FF9', '#5AD8A6', '#F6BD16', '#E8684A', '#6DC8EC', '#9270CA'],
+    tooltip: {
+      trigger: 'item',
+      renderMode: 'richText',
+      confine: true,
+      formatter: params => {
+        const item = Array.isArray(params) ? params[0] : params;
+        const count = typeof item.value === 'number' ? item.value : 0;
+        return `${item.name}\n用户数量：${count}\n占比：${formatPercent(count)}`;
+      }
+    },
+    legend: {
+      type: 'scroll',
+      bottom: 4,
+      left: 'center',
+      itemWidth: 12,
+      itemHeight: 8,
+      itemGap: 16,
+      // 保持占比分母为该型号全部设备，不随图例点击变化。
+      selectedMode: false,
+      formatter: name => {
+        const count = chartData.find(item => item.name === name)?.value ?? 0;
+        return `${name} (${formatPercent(count)})`;
+      }
+    },
+    series: [
+      {
+        name: props.stats.model,
+        type: 'pie',
+        // 标签避让范围限定在饼图区内，底部单独留给滚动图例。
+        top: 8,
+        bottom: 56,
+        radius: '58%',
+        center: ['50%', '50%'],
+        startAngle: 90,
+        endAngle: 'auto',
+        stillShowZeroSum: false,
+        avoidLabelOverlap: true,
+        label: {
+          show: true,
+          formatter: params => `${params.name}\n${formatPercent(typeof params.value === 'number' ? params.value : 0)}`,
+          fontSize: 12,
+          lineHeight: 18,
+          alignTo: 'edge',
+          edgeDistance: 8
+        },
+        labelLayout: { hideOverlap: true },
+        labelLine: { length: 12, length2: 8 },
+        data: chartData
+      }
+    ]
+  };
+}
+
+const { domRef, updateOptions } = useEcharts(buildOptions);
+
+watch(
+  () => props.stats,
+  () => updateOptions(buildOptions),
+  { deep: true }
+);
 </script>
 
 <template>
-  <NCard :bordered="false" class="card-wrapper">
-    <div ref="domRef" class="h-360px overflow-hidden"></div>
+  <NCard :title="stats.model" size="small">
+    <template #header-extra>
+      <NTag type="info" size="small">共 {{ stats.total }} 台</NTag>
+    </template>
+    <div ref="domRef" class="h-360px w-full overflow-hidden"></div>
+    <NSpace vertical :size="12" class="mt-12px">
+      <NText depth="3" class="text-12px">
+        展示用户数最多的前 {{ TOP_VERSION_LIMIT }} 个版本，其余版本合并为“其他”，占比按该型号全部用户计算。
+        <template v-if="remainingCount > 0">“其他”共 {{ remainingCount }} 台（{{ formatPercent(remainingCount) }}）。</template>
+      </NText>
+      <NButton
+        size="small"
+        :aria-expanded="expanded"
+        :aria-controls="versionListId"
+        @click="expanded = !expanded"
+      >
+        {{ expanded ? '收起版本列表' : `展开全部版本（${sortedVersions.length}）` }}
+      </NButton>
+      <div v-if="expanded" :id="versionListId">
+        <NDataTable
+          :columns="versionColumns"
+          :data="sortedVersions"
+          :row-key="row => row.ver"
+          :max-height="300"
+          :bordered="false"
+          size="small"
+        />
+      </div>
+    </NSpace>
   </NCard>
 </template>