首頁(yè)統計API接口文檔

概述

本文檔描述了首頁(yè)Dashboard中TopPanel組件的統計數據API實(shí)現，包括GetCategoryStatisticsAsync接口的使用方法和數據結構。

API接口

GetCategoryStatisticsAsync

獲取首頁(yè)面板統計數據的異步接口。

接口路徑

GET /api/dashboard/category-statistics

請求參數

無(wú)需參數

響應數據結構

// 響應數據類(lèi)型
interface CategoryStatisticsResponse {
  code: number;          // 狀態(tài)碼，200表示成功
  message: string;       // 響應消息
  data: CategoryStatistics[];  // 統計數據數組
}

// 單個(gè)統計項數據結構
interface CategoryStatistics {
  id: string;           // 唯一標識
  title: string;        // 標題（支持國際化key）
  number: string | number;  // 顯示數值
  leftType: string;     // 左側圖標類(lèi)型
  upTrend?: string;     // 上升趨勢百分比
  downTrend?: string;   // 下降趨勢百分比
  desc?: string;        // 描述文字
}

響應示例

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "title": "pages.dashboardBase.topPanel.card1",
      "number": "￥ 126,560",
      "leftType": "echarts-line",
      "upTrend": "20.5%",
      "desc": "自上月"
    },
    {
      "id": "2", 
      "title": "pages.dashboardBase.topPanel.card2",
      "number": "6,972",
      "leftType": "echarts-bar",
      "upTrend": "15.2%",
      "desc": "自上月"
    },
    {
      "id": "3",
      "title": "pages.dashboardBase.topPanel.card3",
      "number": "2,126",
      "leftType": "icon-usergroup",
      "downTrend": "5.1%",
      "desc": "自上月"
    },
    {
      "id": "4",
      "title": "pages.dashboardBase.topPanel.card4",
      "number": "723",
      "leftType": "icon-file-paste",
      "upTrend": "8.7%",
      "desc": "自上月"
    }
  ]
}

前端使用方法

1. API調用

import { getDashboardPanelData } from '@/api/dashboard';

// 獲取面板數據
const fetchPanelData = async () => {
  try {
    const data = await getDashboardPanelData();
    console.log('統計數據:', data);
  } catch (error) {
    console.error('獲取數據失敗:', error);
  }
};

2. 組件集成

TopPanel組件已經(jīng)集成了動(dòng)態(tài)數據獲取功能：

<template>
  <t-row :gutter="[16, 16]">
    <t-col v-for="(item, index) in (panelData.length > 0 ? panelData : PANE_LIST)" 
           :key="item.title || item.id" :xs="6" :xl="3">
      <!-- 卡片內容 -->
    </t-col>
  </t-row>
</template>

<script setup lang="ts">
import { getDashboardPanelData, type CategoryStatistics } from '@/api/dashboard';

// 面板數據狀態(tài)
const panelData = ref<CategoryStatistics[]>([]);
const loading = ref(true);

// 獲取面板數據
const fetchPanelData = async () => {
  try {
    loading.value = true;
    panelData.value = await getDashboardPanelData();
  } catch (error) {
    console.error('獲取面板數據失敗:', error);
  } finally {
    loading.value = false;
  }
};

onMounted(() => {
  fetchPanelData();
});
</script>

數據字段說(shuō)明

leftType 字段值說(shuō)明

• echarts-line: 顯示折線(xiàn)圖（第一個(gè)卡片）
• echarts-bar: 顯示柱狀圖（第二個(gè)卡片）
• icon-usergroup: 顯示用戶(hù)組圖標
• icon-file-paste: 顯示文件圖標

趨勢顯示邏輯

• 當upTrend有值時(shí)，顯示上升趨勢（綠色箭頭）
• 當downTrend有值時(shí)，顯示下降趨勢（紅色箭頭）
• 第一個(gè)卡片（index=0）使用反色顯示

錯誤處理

降級策略

當API調用失敗時(shí)，組件會(huì )自動(dòng)使用靜態(tài)默認數據作為降級方案，確保頁(yè)面正常顯示。

錯誤狀態(tài)碼

• 200: 成功
• 400: 請求參數錯誤
• 401: 未授權
• 500: 服務(wù)器內部錯誤

國際化支持

title字段支持國際化key，例如：

• pages.dashboardBase.topPanel.card1: 對應第一個(gè)卡片標題
• pages.dashboardBase.topPanel.card2: 對應第二個(gè)卡片標題

性能優(yōu)化建議

1. 緩存策略: 建議在后端實(shí)現適當的緩存機制
2. 數據更新: 可以考慮使用WebSocket或定時(shí)刷新來(lái)更新數據
3. 錯誤重試: 實(shí)現自動(dòng)重試機制提高可靠性

更新日志

• v1.0.0 (2024-10-06): 初始版本，實(shí)現基礎統計數據API
• 支持動(dòng)態(tài)數據獲取和降級策略
• 集成到TopPanel組件中