docs: 更新根目录 README，整合前后端项目完整信息

- 更新项目结构，反映分层架构（handler → service → repository） - 完善技术栈说明，包含所有依赖和版本信息 - 添加首次启动的自动初始化说明 - 展开管理接口的详细 CRUD 端点 - 添加完整配置文件示例和数据文件说明 - 分离前后端测试和开发命令 - 指向子项目 README 获取详细开发规范
2026-04-16 12:22:01 +08:00
parent 9359ca7f62
commit 1580b5b838
1 changed files with 135 additions and 43 deletions
--- a/README.md
+++ b/README.md
@@ -6,30 +6,33 @@

 ```
 nex/
-├── backend/          # Go 后端服务
-│   ├── main.go
-│   ├── go.mod
-│   └── internal/
-│       ├── handler/       # HTTP 处理器
-│       ├── protocol/      # 协议适配器
-│       ├── provider/      # 供应商客户端
-│       ├── router/        # 模型路由
-│       ├── stats/         # 统计记录
-│       └── config/        # 配置与数据库
+├── 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 前端界面
+├── frontend/             # React 前端界面
 │   ├── src/
-│   │   ├── api/            # API 层（统一请求封装 + 字段转换）
-│   │   ├── hooks/          # TanStack Query hooks
-│   │   ├── components/     # 通用组件（AppLayout）
-│   │   ├── pages/          # 页面（Providers, Stats, NotFound）
-│   │   ├── routes/         # React Router 路由配置
-│   │   ├── types/          # TypeScript 类型定义
-│   │   └── __tests__/      # 测试（API、Hooks、组件）
-│   ├── e2e/                # Playwright E2E 测试
+│   │   ├── api/          # API 层（统一请求封装 + 字段转换）
+│   │   ├── hooks/        # TanStack Query hooks
+│   │   ├── components/   # 通用组件（AppLayout）
+│   │   ├── pages/        # 页面（Providers, Stats）
+│   │   ├── routes/       # React Router 路由配置
+│   │   ├── types/        # TypeScript 类型定义
+│   │   └── __tests__/    # 单元测试 + 组件测试
+│   ├── e2e/              # Playwright E2E 测试
 │   └── package.json
 │
-└── README.md         # 本文件
+└── README.md             # 本文件
 ```

 ## 功能特性
@@ -45,21 +48,25 @@ nex/
 ## 技术栈

 ### 后端
- **Go 1.21+**
- **Gin** - HTTP 框架
- **GORM** - ORM
- **SQLite** - 数据库
+- **语言**: 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 框架
- **Ant Design 5** - UI 组件库
- **React Router v7** - 路由
- **TanStack Query v5** - 数据获取
- **SCSS Modules** - 样式方案
- **Vitest + Playwright** - 测试
+- **运行时**: Bun
+- **构建工具**: Vite
+- **语言**: TypeScript (strict mode)
+- **框架**: React
+- **UI 组件库**: Ant Design 5
+- **路由**: React Router v7
+- **数据获取**: TanStack Query v5
+- **样式**: SCSS Modules
+- **测试**: Vitest + React Testing Library + Playwright

 ## 快速开始

@@ -68,10 +75,14 @@ nex/
 ```bash
 cd backend
 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
 ```

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

 ## API 接口

@@ -92,19 +103,100 @@ bun dev

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

- `GET/POST/PUT/DELETE /api/providers` - 供应商管理
- `GET/POST/PUT/DELETE /api/models` - 模型管理
- `GET /api/stats` - 统计查询
+#### 供应商管理
+- `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` - 删除模型

-配置数据存储在用户目录：`~/.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](backend/README.md)
- [前端 README](frontend/README.md)
+- [后端 README](backend/README.md) - 分层架构、依赖注入、数据库迁移
+- [前端 README](frontend/README.md) - TypeScript strict、SCSS Modules、测试策略

 ## 许可证