# Nex - AI Gateway

一个统一的大模型 API 网关，支持 OpenAI 和 Anthropic 双协议，让应用只需配置一个地址即可透明使用多个供应商的大模型服务。

## 项目结构

```
nex/
├── backend/              # Go 后端服务（分层架构）
│   ├── cmd/server/       # 主程序入口
│   ├── internal/
│   │   ├── handler/      # HTTP 处理器 + 中间件
│   │   ├── service/      # 业务逻辑层
│   │   ├── repository/   # 数据访问层
│   │   ├── domain/       # 领域模型
│   │   ├── protocol/     # 协议适配器（OpenAI/Anthropic）
│   │   ├── provider/     # 供应商客户端
│   │   └── config/       # 配置管理
│   ├── pkg/              # 公共包（logger/errors/validator）
│   ├── migrations/       # 数据库迁移
│   └── tests/            # 测试（unit/integration）
│
├── frontend/             # React 前端界面
│   ├── src/
│   │   ├── api/          # API 层（统一请求封装 + 字段转换）
│   │   ├── hooks/        # TanStack Query hooks
│   │   ├── components/   # 通用组件（AppLayout）
│   │   ├── pages/        # 页面（Providers, Stats）
│   │   ├── routes/       # React Router 路由配置
│   │   ├── types/        # TypeScript 类型定义
│   │   └── __tests__/    # 单元测试 + 组件测试
│   ├── e2e/              # Playwright E2E 测试
│   └── package.json
│
└── README.md             # 本文件
```

## 功能特性

- **双协议支持**：同时支持 OpenAI 和 Anthropic 协议
- **透明代理**：对 OpenAI 兼容供应商透传请求
- **流式响应**：完整支持 SSE 流式传输
- **Function Calling**：支持工具调用（Tools）
- **多供应商管理**：配置和管理多个供应商
- **用量统计**：按供应商、模型、日期统计请求数量
- **Web 配置界面**：提供供应商和模型配置管理

## 技术栈

### 后端
- **语言**: Go 1.26+
- **HTTP 框架**: Gin
- **ORM**: GORM
- **数据库**: SQLite
- **日志**: zap + lumberjack（结构化日志 + 日志轮转）
- **配置**: gopkg.in/yaml.v3
- **验证**: go-playground/validator/v10
- **迁移**: goose

### 前端
- **运行时**: Bun
- **构建工具**: Vite
- **语言**: TypeScript (strict mode)
- **框架**: React
- **UI 组件库**: TDesign React
- **图表库**: Recharts
- **路由**: React Router v7
- **数据获取**: TanStack Query v5
- **样式**: SCSS Modules
- **测试**: Vitest + React Testing Library + Playwright

## 快速开始

### 后端

```bash
cd backend
go mod download
go run cmd/server/main.go
```

后端服务将在 `http://localhost:9826` 启动。首次启动会自动：
- 创建配置文件 `~/.nex/config.yaml`
- 初始化数据库 `~/.nex/config.db`
- 运行数据库迁移
- 创建日志目录 `~/.nex/log/`

### 前端

```bash
cd frontend
bun install
bun dev
```

前端开发服务器将在 `http://localhost:5173` 启动，API 请求通过 Vite proxy 转发到后端。

## API 接口

### 代理接口（对外部应用）

- `POST /v1/chat/completions` - OpenAI Chat Completions API
- `POST /v1/messages` - Anthropic Messages API

### 管理接口（对前端）

#### 供应商管理
- `GET /api/providers` - 列出所有供应商
- `POST /api/providers` - 创建供应商
- `GET /api/providers/:id` - 获取供应商
- `PUT /api/providers/:id` - 更新供应商
- `DELETE /api/providers/:id` - 删除供应商

#### 模型管理
- `GET /api/models` - 列出模型（支持 `?provider_id=xxx` 过滤）
- `POST /api/models` - 创建模型
- `GET /api/models/:id` - 获取模型
- `PUT /api/models/:id` - 更新模型
- `DELETE /api/models/:id` - 删除模型

#### 统计查询
- `GET /api/stats` - 查询统计
- `GET /api/stats/aggregate` - 聚合统计

查询参数支持：`provider_id`、`model_name`、`start_date`、`end_date`、`group_by`

## 配置

配置文件位于 `~/.nex/config.yaml`，首次启动自动生成：

```yaml
server:
  port: 9826
  read_timeout: 30s
  write_timeout: 30s

database:
  path: ~/.nex/config.db
  max_idle_conns: 10
  max_open_conns: 100
  conn_max_lifetime: 1h

log:
  level: info
  path: ~/.nex/log
  max_size: 100        # MB
  max_backups: 10
  max_age: 30          # 天
  compress: true
```

数据文件：
- `~/.nex/config.yaml` - 配置文件
- `~/.nex/config.db` - SQLite 数据库
- `~/.nex/log/` - 日志目录

## 测试

### 后端测试

```bash
cd backend
make test              # 运行所有测试
make test-coverage     # 生成覆盖率报告
```

### 前端测试

```bash
cd frontend
bun run test            # 单元测试 + 组件测试
bun run test:watch      # 监听模式
bun run test:coverage   # 生成覆盖率报告
bun run test:e2e        # E2E 测试
```

## 开发

### 后端开发

```bash
cd backend
make build              # 构建
make lint               # 代码检查
make migrate-up         # 数据库迁移
```

### 前端开发

```bash
cd frontend
bun run build           # 构建生产版本
bun run lint            # 代码检查
```

## 开发规范

详见各子项目的 README.md：
- [后端 README](backend/README.md) - 分层架构、依赖注入、数据库迁移
- [前端 README](frontend/README.md) - TypeScript strict、SCSS Modules、测试策略

## 许可证

MIT