docs: 更新根目录 README，整合前后端项目完整信息
- 更新项目结构，反映分层架构（handler → service → repository） - 完善技术栈说明，包含所有依赖和版本信息 - 添加首次启动的自动初始化说明 - 展开管理接口的详细 CRUD 端点 - 添加完整配置文件示例和数据文件说明 - 分离前后端测试和开发命令 - 指向子项目 README 获取详细开发规范
This commit is contained in:
178
README.md
178
README.md
@@ -6,30 +6,33 @@
|
|||||||
|
|
||||||
```
|
```
|
||||||
nex/
|
nex/
|
||||||
├── backend/ # Go 后端服务
|
├── backend/ # Go 后端服务（分层架构）
|
||||||
│ ├── main.go
|
│ ├── cmd/server/ # 主程序入口
|
||||||
│ ├── go.mod
|
│ ├── internal/
|
||||||
│ └── internal/
|
│ │ ├── handler/ # HTTP 处理器 + 中间件
|
||||||
│ ├── handler/ # HTTP 处理器
|
│ │ ├── service/ # 业务逻辑层
|
||||||
│ ├── protocol/ # 协议适配器
|
│ │ ├── repository/ # 数据访问层
|
||||||
│ ├── provider/ # 供应商客户端
|
│ │ ├── domain/ # 领域模型
|
||||||
│ ├── router/ # 模型路由
|
│ │ ├── protocol/ # 协议适配器（OpenAI/Anthropic）
|
||||||
│ ├── stats/ # 统计记录
|
│ │ ├── provider/ # 供应商客户端
|
||||||
│ └── config/ # 配置与数据库
|
│ │ └── config/ # 配置管理
|
||||||
|
│ ├── pkg/ # 公共包（logger/errors/validator）
|
||||||
|
│ ├── migrations/ # 数据库迁移
|
||||||
|
│ └── tests/ # 测试（unit/integration）
|
||||||
│
|
│
|
||||||
├── frontend/ # React 前端界面
|
├── frontend/ # React 前端界面
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── api/ # API 层（统一请求封装 + 字段转换）
|
│ │ ├── api/ # API 层（统一请求封装 + 字段转换）
|
||||||
│ │ ├── hooks/ # TanStack Query hooks
|
│ │ ├── hooks/ # TanStack Query hooks
|
||||||
│ │ ├── components/ # 通用组件（AppLayout）
|
│ │ ├── components/ # 通用组件（AppLayout）
|
||||||
│ │ ├── pages/ # 页面（Providers, Stats, NotFound）
|
│ │ ├── pages/ # 页面（Providers, Stats）
|
||||||
│ │ ├── routes/ # React Router 路由配置
|
│ │ ├── routes/ # React Router 路由配置
|
||||||
│ │ ├── types/ # TypeScript 类型定义
|
│ │ ├── types/ # TypeScript 类型定义
|
||||||
│ │ └── __tests__/ # 测试（API、Hooks、组件）
|
│ │ └── __tests__/ # 单元测试 + 组件测试
|
||||||
│ ├── e2e/ # Playwright E2E 测试
|
│ ├── e2e/ # Playwright E2E 测试
|
||||||
│ └── package.json
|
│ └── package.json
|
||||||
│
|
│
|
||||||
└── README.md # 本文件
|
└── README.md # 本文件
|
||||||
```
|
```
|
||||||
|
|
||||||
## 功能特性
|
## 功能特性
|
||||||
@@ -45,21 +48,25 @@ nex/
|
|||||||
## 技术栈
|
## 技术栈
|
||||||
|
|
||||||
### 后端
|
### 后端
|
||||||
- **Go 1.21+**
|
- **语言**: Go 1.26+
|
||||||
- **Gin** - HTTP 框架
|
- **HTTP 框架**: Gin
|
||||||
- **GORM** - ORM
|
- **ORM**: GORM
|
||||||
- **SQLite** - 数据库
|
- **数据库**: SQLite
|
||||||
|
- **日志**: zap + lumberjack（结构化日志 + 日志轮转）
|
||||||
|
- **配置**: gopkg.in/yaml.v3
|
||||||
|
- **验证**: go-playground/validator/v10
|
||||||
|
- **迁移**: goose
|
||||||
|
|
||||||
### 前端
|
### 前端
|
||||||
- **Bun** - 运行时
|
- **运行时**: Bun
|
||||||
- **Vite** - 构建工具
|
- **构建工具**: Vite
|
||||||
- **TypeScript** (strict mode) - 类型系统
|
- **语言**: TypeScript (strict mode)
|
||||||
- **React** - UI 框架
|
- **框架**: React
|
||||||
- **Ant Design 5** - UI 组件库
|
- **UI 组件库**: Ant Design 5
|
||||||
- **React Router v7** - 路由
|
- **路由**: React Router v7
|
||||||
- **TanStack Query v5** - 数据获取
|
- **数据获取**: TanStack Query v5
|
||||||
- **SCSS Modules** - 样式方案
|
- **样式**: SCSS Modules
|
||||||
- **Vitest + Playwright** - 测试
|
- **测试**: Vitest + React Testing Library + Playwright
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
@@ -68,10 +75,14 @@ nex/
|
|||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
go mod download
|
go mod download
|
||||||
go run main.go
|
go run cmd/server/main.go
|
||||||
```
|
```
|
||||||
|
|
||||||
后端服务将在 `http://localhost:9826` 启动。
|
后端服务将在 `http://localhost:9826` 启动。首次启动会自动：
|
||||||
|
- 创建配置文件 `~/.nex/config.yaml`
|
||||||
|
- 初始化数据库 `~/.nex/config.db`
|
||||||
|
- 运行数据库迁移
|
||||||
|
- 创建日志目录 `~/.nex/log/`
|
||||||
|
|
||||||
### 前端
|
### 前端
|
||||||
|
|
||||||
@@ -81,7 +92,7 @@ bun install
|
|||||||
bun dev
|
bun dev
|
||||||
```
|
```
|
||||||
|
|
||||||
前端开发服务器将在 `http://localhost:5173` 启动。
|
前端开发服务器将在 `http://localhost:5173` 启动，API 请求通过 Vite proxy 转发到后端。
|
||||||
|
|
||||||
## API 接口
|
## API 接口
|
||||||
|
|
||||||
@@ -92,19 +103,100 @@ bun dev
|
|||||||
|
|
||||||
### 管理接口（对前端）
|
### 管理接口（对前端）
|
||||||
|
|
||||||
- `GET/POST/PUT/DELETE /api/providers` - 供应商管理
|
#### 供应商管理
|
||||||
- `GET/POST/PUT/DELETE /api/models` - 模型管理
|
- `GET /api/providers` - 列出所有供应商
|
||||||
- `GET /api/stats` - 统计查询
|
- `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` - 删除模型
|
||||||
|
|
||||||
配置数据存储在用户目录：`~/.nex/config.db`
|
#### 统计查询
|
||||||
|
- `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.md：
|
||||||
- [后端 README](backend/README.md)
|
- [后端 README](backend/README.md) - 分层架构、依赖注入、数据库迁移
|
||||||
- [前端 README](frontend/README.md)
|
- [前端 README](frontend/README.md) - TypeScript strict、SCSS Modules、测试策略
|
||||||
|
|
||||||
## 许可证
|
## 许可证
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user