压缩历史至 95081aff

2026-10-13 10:26:38 +08:00 · 2026-06-08 20:34:27 +08:00
commit 8a782525de
435 changed files with 71146 additions and 0 deletions
@@ -0,0 +1,69 @@
+import { BaseService } from '../core/base.service';
+import type {
+  DailyStatsResponse,
+  TopCustomersResponse,
+} from './types';
+
+/**
+ * 仪表板服务
+ * 处理仪表板统计数据相关的 API 请求
+ */
+export class DashboardService extends BaseService {
+  protected static readonly basePath = '/api/v1/dashboard';
+
+  /**
+   * 获取每日收支统计
+   * @param days - 查询天数，最大7天，最小1天
+   * @returns 每日统计数据列表
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * const stats = await DashboardService.getDailyStats(7);
+   * console.log('每日统计:', stats);
+   * // 输出: [
+   * //   { date: '2025-12-22', income: '1000.00', expense: '500.00' },
+   * //   { date: '2025-12-21', income: '800.00', expense: '300.00' },
+   * //   ...
+   * // ]
+   * ```
+   * 
+   * @remarks
+   * - days 参数必须在 1-7 之间
+   * - 返回的数据按日期降序排列
+   * - income 和 expense 为字符串格式的金额
+   */
+  static async getDailyStats(days: number): Promise<DailyStatsResponse> {
+    return this.get<DailyStatsResponse>('/stats/daily', { days });
+  }
+
+  /**
+   * 获取 Top 客户统计
+   * @param days - 查询天数，最大7天，最小1天
+   * @param limit - 返回数量，最大10条，最小1条
+   * @returns Top 客户列表
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * const customers = await DashboardService.getTopCustomers(7, 5);
+   * console.log('Top 5 客户:', customers);
+   * // 输出: [
+   * //   { user_id: 123, username: 'user1', total_amount: '5000.00', order_count: 10 },
+   * //   { user_id: 456, username: 'user2', total_amount: '3000.00', order_count: 8 },
+   * //   ...
+   * // ]
+   * ```
+   * 
+   * @remarks
+   * - days 参数必须在 1-7 之间
+   * - limit 参数必须在 1-10 之间
+   * - 返回的数据按累计付款金额降序排列
+   * - total_amount 为字符串格式的金额
+   */
+  static async getTopCustomers(days: number, limit: number): Promise<TopCustomersResponse> {
+    return this.get<TopCustomersResponse>('/stats/top-customers', { days, limit });
+  }
+}