# GoalfyMax Admin

基于 Go 语言开发的管理后台系统基础架构，提供数据模型、存储层、服务层等核心组件。

## 🚀 项目特性

- **数据模型**: 完整的用户、角色、菜单等数据模型
- **存储层**: 统一的数据访问接口
- **服务层**: 业务逻辑封装
- **工具包**: 加密、JWT、日志等工具函数
- **配置管理**: 灵活的配置管理
- **数据库支持**: MySQL数据库支持

## 🏗️ 项目架构

```
goalfymax-admin/
├── cmd/                   # 应用程序入口
│   └── server/           # 主服务
│       └── main.go      # 主程序入口
├── internal/             # 内部包
│   ├── config/          # 配置管理
│   ├── models/          # 数据模型
│   ├── services/        # 业务服务层
│   └── storage/         # 数据访问层
├── pkg/                 # 公共包
│   └── utils/           # 工具函数
└── etc/                 # 配置文件
```

## 📋 技术栈

- **语言**: Go 1.25+
- **数据库**: MySQL 8.0+
- **ORM**: GORM
- **配置**: Viper + YAML
- **日志**: Zap

## 🚀 快速开始

### 环境要求

- Go 1.25+
- MySQL 8.0+

### 1. 克隆项目

```bash
git clone <repository-url>
cd goalfymax-admin
```

### 2. 安装依赖

```bash
go mod download
```

### 3. 配置数据库

创建数据库：

```sql
CREATE DATABASE goalfymax_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 4. 配置文件

编辑 `etc/config.yaml`：

```yaml
server:
  addr: "0.0.0.0"
  port: 8080

database:
  dsn: "root:password@tcp(127.0.0.1:3306)/goalfymax_admin?charset=utf8mb4&parseTime=True&loc=Local"
  maxIdleConns: 10
  maxOpenConns: 100

log:
  level: "info"
  format: "json"
  output: "stdout"
```

### 5. 运行项目

```bash
# 开发模式
go run main.go

# 或指定配置文件
go run main.go -config etc/config.yaml
```

### 6. 运行项目

```bash
# 运行项目
go run cmd/server/main.go

# 或指定配置文件
go run cmd/server/main.go -config etc/config.yaml
```

### 7. 访问服务

- **API服务**: http://localhost:8084
- **健康检查**: http://localhost:8084/health
- **配额历史**: http://localhost:8084/api/quotas/history

## 🔧 CORS 配置

项目已配置CORS支持，允许以下域名跨域访问：
- `http://localhost:5173` (Vite开发服务器)
- `http://localhost:5174` (Vite开发服务器)
- `http://localhost:3000` (其他前端服务)

支持的HTTP方法：GET, POST, PUT, DELETE, OPTIONS

## 📖 API 接口

### 配额历史接口

#### 获取配额历史数据

```bash
POST /api/quotas/history
Content-Type: application/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", "api_group"]
}
```

**请求参数：**
- `start_date` (必填): 开始日期，格式 YYYY-MM-DD
- `end_date` (必填): 结束日期，格式 YYYY-MM-DD
- `user_id` (可选): 用户ID过滤
- `api_group` (可选): API组过滤
- `project_id` (可选): 项目ID过滤
- `period` (可选): 周期类型，daily 或 monthly，默认 daily
- `group_by` (可选): 分组维度，默认 ["user_id"]

**注意：** 此接口会转发请求到 goalfy-ai-gateway 的 `/aigateway-admin/api/quotas/history` 接口。

**响应示例：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "user_id": "user123",
      "api_group": "openai",
      "project_id": "project456",
      "day": "2024-01-01",
      "account": "account1",
      "model": "gpt-4",
      "quota_used": 1.5,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

#### 配额服务健康检查

```bash
GET /api/quotas/health
```

**响应示例：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "status": "ok",
    "service": "quota"
  }
}
```

## 🛠️ 开发指南

### 项目结构说明

- `internal/config/`: 配置管理
- `internal/models/`: 数据模型定义
- `internal/services/`: 业务逻辑层
- `internal/storage/`: 数据访问层
- `pkg/utils/`: 工具函数

### 添加新功能

1. 在 `internal/models/` 中定义数据模型
2. 在 `internal/storage/` 中实现数据访问
3. 在 `internal/services/` 中实现业务逻辑

### 数据库迁移

项目启动时会自动执行数据库迁移，创建必要的表结构。

## 📊 监控和日志

### 日志

系统使用结构化日志，支持不同级别的日志输出：

```bash
# 查看实时日志
tail -f logs/app.log

# 按级别过滤
grep "ERROR" logs/app.log
```

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。

## 🆘 支持

如果您遇到问题或有疑问，请：

1. 查看 [文档](docs/)
2. 搜索 [Issues](https://github.com/your-org/goalfymax-admin/issues)
3. 创建新的 Issue