# Goalfy Admin Web - Token 统计系统

基于 React + Ant Design + TypeScript + Vite 技术栈开发的 Token 使用统计前端页面。

## 技术栈

- **React 19.1.1** - 前端框架
- **Ant Design 5.x** - UI 组件库
- **TypeScript 5.9.3** - 类型系统
- **Vite 7.1.7** - 构建工具
- **Axios** - HTTP 客户端
- **Day.js** - 日期处理
- **ESLint** - 代码检查

## 功能特性

### 🎯 核心功能
- **Token 使用统计** - 实时显示 Token 使用量、用户数、项目数、模型数
- **历史数据查询** - 支持按时间范围、用户、项目等条件查询
- **数据可视化** - 图表展示使用趋势和排行榜
- **详细数据表格** - 支持排序、分页的详细数据展示

### 🎨 界面设计
- **深色主题** - 参考 goalfy-admin 的深色设计风格
- **响应式布局** - 支持桌面和移动端
- **现代化 UI** - 使用 Ant Design 组件库
- **直观操作** - 简洁的查询界面和操作流程

## 项目结构

```
src/
├── components/          # React 组件
│   ├── QuotaFilters.tsx    # 查询过滤器
│   ├── QuotaStats.tsx      # 统计概览
│   ├── QuotaCharts.tsx     # 图表组件
│   └── QuotaHistoryTable.tsx # 历史数据表格
├── services/           # API 服务
│   └── api.ts             # API 客户端
├── types/              # TypeScript 类型
│   └── quota.ts           # 配额相关类型
├── App.tsx             # 主应用组件
├── App.css             # 全局样式
└── main.tsx            # 应用入口
```

## 快速开始

### 1. 安装依赖
```bash
npm install
```

### 2. 启动开发服务器
```bash
npm run dev
```

### 3. 构建生产版本
```bash
npm run build
```

## API 配置

在 `src/services/api.ts` 中配置后端 API 地址：

```typescript
const API_BASE_URL = 'http://localhost:8080'; // 修改为实际的后端地址
```

## 后端 API 接口

应用调用以下后端接口：

- `POST /api/quotas/history` - 获取配额历史数据
- `GET /health` - 健康检查

### 请求参数示例

```json
{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "user_id": "user123",
  "api_group": "openai",
  "project_id": "project456",
  "period": "daily",
  "group_by": ["user_id", "model"]
}
```

### 响应数据格式

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": "user123",
      "api_group": "openai",
      "project_id": "project456",
      "day": "2024-01-01",
      "account": "account123",
      "model": "gpt-4",
      "quota_used": 1000.5,
      "created_at": "2024-01-01T10:00:00Z"
    }
  ]
}
```

## 组件说明

### QuotaFilters
查询条件过滤器，支持：
- 时间范围选择
- 用户ID、API组、项目ID筛选
- 统计周期选择
- 分组维度配置

### QuotaStats
统计概览卡片，显示：
- 总 Token 使用量
- 活跃用户数
- 项目数量
- 模型数量

### QuotaCharts
数据可视化图表：
- 每日使用趋势图
- 用户使用量排行
- 模型使用量排行

### QuotaHistoryTable
详细数据表格，支持：
- 数据排序
- 分页显示
- 响应式布局
- 数据导出

## 样式定制

应用使用深色主题，主要颜色变量：

```css
--bg: #0b0c0f;        /* 背景色 */
--panel: #12141a;     /* 面板色 */
--text: #e7e9ee;      /* 文字色 */
--accent: #5f97d2;    /* 强调色 */
--border: #232634;    /* 边框色 */
```

## 开发说明

### 添加新功能
1. 在 `src/types/` 中定义类型
2. 在 `src/services/` 中添加 API 调用
3. 在 `src/components/` 中创建组件
4. 在 `App.tsx` 中集成组件

### 代码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 规则
- 组件使用函数式写法
- 使用 Ant Design 组件库

## 部署说明

1. 构建生产版本：`npm run build`
2. 将 `dist` 目录部署到 Web 服务器
3. 配置后端 API 地址
4. 确保 CORS 配置正确

## 许可证

内部使用，仅供 Goalfy 团队使用。