param-hub-python/API.md

# ParamHub API 能力文档

> 本文档记录系统所有 API 能力，变更时请及时更新
>
> 最后更新：2026-07-11

---

## 基础信息

- **基础地址**: `http://localhost:16041`
- **认证方式**: Session Cookie（登录后获取）
- **认证要求**: 所有 POST/PUT/DELETE 请求需先登录

---

## 1. 认证 API

### 1.1 登录
```
POST /login
Content-Type: application/json

请求体：
{
  "password": "admin123"
}

响应：
{
  "success": true,
  "redirect": "/admin"
}
```

### 1.2 登出
```
GET /logout
```

### 1.3 检查登录状态
```
GET /api/config  (未登录返回 401)
```

---

## 2. 分类管理 API

### 2.1 获取分类列表
```
GET /api/categories
GET /api/categories?all=1  (包含隐藏分类)
```

### 2.2 获取分类详情
```
GET /api/categories/{category_id}
```

### 2.3 创建分类
```
POST /api/categories
Content-Type: application/json

请求体：
{
  "name": "分类名称",
  "icon": "ri-icon-name",
  "order": 0,
  "visible": true,
  "fields": ["field1", "field2"]  // 动态字段配置
}
```

### 2.4 更新分类
```
PUT /api/categories/{category_id}
Content-Type: application/json

请求体：同创建
```

### 2.5 删除分类
```
DELETE /api/categories/{category_id}
```

### 2.6 切换分类显示/隐藏
```
POST /api/categories/{category_id}/visible
```

### 2.7 导出分类
```
GET /api/categories/export              // 导出所有分类
GET /api/categories/export/{category_id}  // 导出单个分类
```

### 2.8 导入分类
```
POST /api/categories/import?mode=merge|replace
Content-Type: application/json

请求体：
{
  "categories": [...]
}
```

---

## 3. AI模型 API

### 3.1 获取模型列表
```
GET /api/models
GET /api/models?all=1              // 包含隐藏模型
GET /api/models?q=关键词            // 搜索
GET /api/models?sort=name&order=desc  // 排序
```

### 3.2 获取模型详情
```
GET /api/models/{model_id}
```

### 3.3 创建模型
```
POST /api/models
Content-Type: application/json

请求体：
{
  "name": "模型名称",
  "organization": "组织",
  "parameters": "70B",
  "context_length": 4096,
  "mmlu": 85.5,
  "publish_date": "2024-01-01",
  "visible": true,
  "is_pinned": false
}
```

### 3.4 更新模型
```
PUT /api/models/{model_id}
```

### 3.5 删除模型
```
DELETE /api/models/{model_id}
```

### 3.6 切换显示/隐藏
```
POST /api/models/{model_id}/visible
```

### 3.7 置顶/取消置顶
```
POST /api/models/{model_id}/pin
```

### 3.8 增加阅读数
```
POST /api/models/{model_id}/view
```

### 3.9 导出模型
```
GET /api/models/export
```

### 3.10 导入模型
```
POST /api/models/import?mode=merge|replace
Content-Type: application/json

请求体：
{
  "type": "models",
  "items": [...]
}
```

---

## 4. GPU API

### 4.1 获取GPU列表
```
GET /api/gpus
GET /api/gpus?all=1
GET /api/gpus?q=关键词
GET /api/gpus?sort=memory_gb&order=desc
```

### 4.2 获取GPU详情
```
GET /api/gpus/{gpu_id}
```

### 4.3 创建GPU
```
POST /api/gpus
Content-Type: application/json

请求体：
{
  "name": "GPU名称",
  "manufacturer": "NVIDIA",
  "memory_gb": 80,
  "cuda_cores": 10752,
  "tensor_cores": 336,
  "price_usd": 30000,
  "release_year": 2024,
  "visible": true,
  "is_pinned": false
}
```

### 4.4 更新GPU
```
PUT /api/gpus/{gpu_id}
```

### 4.5 删除GPU
```
DELETE /api/gpus/{gpu_id}
```

### 4.6 切换显示/隐藏
```
POST /api/gpus/{gpu_id}/visible
```

### 4.7 置顶/取消置顶
```
POST /api/gpus/{gpu_id}/pin
```

### 4.8 增加阅读数
```
POST /api/gpus/{gpu_id}/view
```

### 4.9 导出GPU
```
GET /api/gpus/export
```

### 4.10 导入GPU
```
POST /api/gpus/import?mode=merge|replace
```

---

## 5. CPU API

### 5.1 获取CPU列表
```
GET /api/cpus
GET /api/cpus?all=1
GET /api/cpus?q=关键词
GET /api/cpus?sort=cores&order=desc
```

### 5.2 获取CPU详情
```
GET /api/cpus/{cpu_id}
```

### 5.3 创建CPU
```
POST /api/cpus
Content-Type: application/json

请求体：
{
  "name": "CPU名称",
  "manufacturer": "AMD",
  "cores": 64,
  "threads": 128,
  "base_clock": 2.4,
  "boost_clock": 3.7,
  "price_usd": 8000,
  "visible": true,
  "is_pinned": false
}
```

### 5.4 更新CPU
```
PUT /api/cpus/{cpu_id}
```

### 5.5 删除CPU
```
DELETE /api/cpus/{cpu_id}
```

### 5.6 切换显示/隐藏
```
POST /api/cpus/{cpu_id}/visible
```

### 5.7 置顶/取消置顶
```
POST /api/cpus/{cpu_id}/pin
```

### 5.8 增加阅读数
```
POST /api/cpus/{cpu_id}/view
```

### 5.9 导出CPU
```
GET /api/cpus/export
```

### 5.10 导入CPU
```
POST /api/cpus/import?mode=merge|replace
```

---

## 6. 动态分类数据 API

### 6.1 获取分类数据列表
```
GET /api/items/{category_id}
GET /api/items/{category_id}?all=1
GET /api/items/{category_id}?sort=price&order=desc
```

### 6.2 获取数据详情
```
GET /api/items/{category_id}/{item_id}
```

### 6.3 创建数据
```
POST /api/items/{category_id}
Content-Type: application/json

请求体：
{
  "name": "名称",
  "visible": true,
  "is_pinned": false,
  // ... 其他动态字段
}
```

### 6.4 更新数据
```
PUT /api/items/{category_id}/{item_id}
```

### 6.5 删除数据
```
DELETE /api/items/{category_id}/{item_id}
```

### 6.6 切换显示/隐藏
```
POST /api/items/{category_id}/{item_id}/visible
```

### 6.7 置顶/取消置顶
```
POST /api/items/{category_id}/{item_id}/pin
```

### 6.8 增加阅读数
```
POST /api/items/{category_id}/{item_id}/view
```

### 6.9 导出分类数据
```
GET /api/items/{category_id}/export
```

### 6.10 导入分类数据
```
POST /api/items/{category_id}/import?mode=merge|replace
```

---

## 7. 知识库 API

### 7.1 获取知识库列表
```
GET /api/knowledge
GET /api/knowledge?all=1
GET /api/knowledge?q=关键词
GET /api/knowledge?category=分类名
```

### 7.2 获取知识详情
```
GET /api/knowledge/{knowledge_id}
```

### 7.3 创建知识
```
POST /api/knowledge
Content-Type: application/json

请求体：
{
  "title": "标题",
  "content": "内容",
  "category": "分类",
  "order": 0,
  "visible": true
}
```

### 7.4 更新知识
```
PUT /api/knowledge/{knowledge_id}
```

### 7.5 删除知识
```
DELETE /api/knowledge/{knowledge_id}
```

### 7.6 切换显示/隐藏
```
POST /api/knowledge/{knowledge_id}/visible
```

---

## 8. 审核系统 API

### 8.1 获取待审核列表
```
GET /api/reviews
GET /api/reviews?status=pending    // 待审核
GET /api/reviews?status=approved   // 已通过
GET /api/reviews?status=rejected    // 已拒绝
GET /api/reviews?status=all         // 全部
```

### 8.2 获取待审核数量
```
GET /api/reviews/count
```

### 8.3 获取审核详情
```
GET /api/reviews/{review_id}
```

### 8.4 通过审核
```
POST /api/reviews/{review_id}/approve
```

### 8.5 拒绝审核
```
POST /api/reviews/{review_id}/reject
Content-Type: application/json

请求体：
{
  "reason": "拒绝原因"
}
```

---

## 9. 通知系统 API

### 9.1 获取通知列表
```
GET /api/notifications
GET /api/notifications?unread=1   // 仅未读
GET /api/notifications?limit=20
```

### 9.2 获取未读数量
```
GET /api/notifications/unread-count
```

### 9.3 标记已读
```
POST /api/notifications/{notification_id}/read
```

### 9.4 全部标记已读
```
POST /api/notifications/read-all
```

### 9.5 删除通知
```
DELETE /api/notifications/{notification_id}
```

---

## 10. 智能解析 API

### 10.1 获取解析提示词模板
```
POST /api/parse-prompt
Content-Type: application/json

请求体：
{
  "category_type": "model|gpu|cpu|dynamic",
  "category_id": "分类ID",
  "subcategory_id": "子分类ID"
}
```

### 10.2 图片解析
```
POST /api/parse-images
Content-Type: application/json

请求体：
{
  "text": "附加文本描述",
  "images": ["图片URL或Base64"],
  "category_type": "model|gpu|cpu|dynamic",
  "subcategory_id": "子分类ID",
  "custom_prompt": "自定义提示词"
}

响应：
{
  "success": true,
  "count": 1,
  "products": [解析结果]
}
```

### 10.3 智能添加 - AI模型
```
POST /api/models/smart-add
Content-Type: application/json

请求体：
{
  "text": "文本描述",
  "images": ["图片URL"],
  "subcategory_id": "子分类ID",
  "custom_prompt": "自定义提示词"
}
```

### 10.4 智能添加 - GPU
```
POST /api/gpus/smart-add
```

### 10.5 智能添加 - CPU
```
POST /api/cpus/smart-add
```

### 10.6 智能添加 - 动态分类
```
POST /api/items/{category_id}/smart-add
```

### 10.7 智能补充 - AI模型
```
POST /api/models/{model_id}/smart-update
Content-Type: application/json

请求体：
{
  "text": "补充信息文本",
  "images": ["图片URL"]
}

响应：
{
  "success": true,
  "updated_fields": ["field1", "field2"],
  "model": 更新后的模型数据
}
```

### 10.8 智能补充 - GPU
```
POST /api/gpus/{gpu_id}/smart-update
```

### 10.9 智能补充 - CPU
```
POST /api/cpus/{cpu_id}/smart-update
```

### 10.10 智能补充 - 动态分类
```
POST /api/items/{category_id}/{item_id}/smart-update
```

---

## 11. 搜索与统计 API

### 11.1 全局搜索
```
GET /api/search?q=关键词

响应：
{
  "models": [...],
  "gpus": [...],
  "cpus": [...]
}
```

### 11.2 显存计算
```
GET /api/calculate/vram?params=7&precision=fp16

参数：
- params: 模型参数量（单位：B）
- precision: 精度 (fp32|fp16|int8|int4)

响应：
{
  "model_vram": 14.0,      // 模型显存需求(GB)
  "total_vram": 18.2,       // 总显存需求(含30%余量)
  "suitable_gpus": [...]    // 适用GPU列表
}
```

### 11.3 统计数据
```
GET /api/stats

响应：
{
  "models_count": 10,
  "gpus_count": 5,
  "cpus_count": 8,
  "categories_count": 3,
  "knowledge_count": 20,
  "latest_models": [...]
}
```

---

## 12. 网站配置 API

### 12.1 获取配置
```
GET /api/config

响应：
{
  "site_name": "ParamHub",
  "admin_password": "admin123",
  ...
}
```

### 12.2 更新配置
```
PUT /api/config
Content-Type: application/json

请求体：
{
  "site_name": "新名称",
  "admin_password": "新密码"
}
```

---

## 13. 图片上传 API

### 13.1 上传图片（文件）
```
POST /api/upload/image
Content-Type: multipart/form-data

请求体：
- file: 图片文件

响应：
{
  "success": true,
  "filename": "abc123_1234567890.png",
  "url": "/static/uploads/abc123_1234567890.png"
}
```

### 13.2 上传图片（Base64）
```
POST /api/upload/image/base64
Content-Type: application/json

请求体：
{
  "image": "data:image/png;base64,xxxxx...",
  "ext": "png"
}
```

### 13.3 删除图片
```
DELETE /api/upload/image/delete/{filename}
```

---

## 错误响应

所有 API 错误响应格式：
```json
{
  "error": "错误信息"
}
```

常见错误码：
- `400` - 请求参数错误
- `401` - 未登录
- `404` - 资源不存在
- `500` - 服务器错误

---

## 审核模式说明

当系统开启审核模式（`REQUIRE_REVIEW = True`）时：

1. 创建产品（POST /api/models, /api/gpus, /api/cpus, /api/items/{category_id}）时：
   - 数据不会直接入库
   - 而是提交到审核队列
   - 返回 `{ "success": true, "message": "已提交审核", "review_id": "xxx" }`

2. 管理员需通过审核 API 确认：
   - `POST /api/reviews/{review_id}/approve` - 通过
   - `POST /api/reviews/{review_id}/reject` - 拒绝

---

## 变更日志

| 日期 | 变更内容 |
|------|----------|
| 2026-07-11 | 初始版本，记录所有 API 能力 |