From 1580b5b8383ed4708ac13c5e77f4b92ca3fe811d Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Thu, 16 Apr 2026 12:22:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=A0=B9=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=20README=EF=BC=8C=E6=95=B4=E5=90=88=E5=89=8D=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E9=A1=B9=E7=9B=AE=E5=AE=8C=E6=95=B4=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新项目结构，反映分层架构（handler → service → repository） - 完善技术栈说明，包含所有依赖和版本信息 - 添加首次启动的自动初始化说明 - 展开管理接口的详细 CRUD 端点 - 添加完整配置文件示例和数据文件说明 - 分离前后端测试和开发命令 - 指向子项目 README 获取详细开发规范 --- README.md | 178 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 135 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 8fb5017..d0bd71e 100644 --- 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、测试策略 ## 许可证