添加完整API能力文档 API.md，更新 README.md

API.md

@@ -0,0 +1,764 @@
+# 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 能力 |

README.md

@@ -54,18 +54,27 @@ param-hub-python/
 
 ## API接口
 
-| 接口 | 方法 | 说明 |
+完整 API 能力文档请查看 [API.md](API.md)
-|------|------|------|
+
-| `/api/models` | GET | 获取模型列表 |
+### 快速参考
-| `/api/models/<id>` | GET | 获取模型详情 |
+
-| `/api/gpus` | GET | 获取GPU列表 |
+| 模块 | 主要接口 |
-| `/api/gpus/<id>` | GET | 获取GPU详情 |
+|------|----------|
-| `/api/cpus` | GET | 获取CPU列表 |
+| 认证 | `/login`, `/logout` |
-| `/api/cpus/<id>` | GET | 获取CPU详情 |
+| 分类 | `/api/categories` CRUD + 导入导出 |
-| `/api/search` | GET | 全局搜索 |
+| AI模型 | `/api/models` CRUD + 置顶 + 热度 + 导入导出 |
-| `/api/calculate/vram` | GET | 显存计算 |
+| GPU | `/api/gpus` CRUD + 置顶 + 热度 + 导入导出 |
-| `/api/stats` | GET | 统计数据 |
+| CPU | `/api/cpus` CRUD + 置顶 + 热度 + 导入导出 |
+| 动态分类 | `/api/items/{category_id}` CRUD |
+| 知识库 | `/api/knowledge` CRUD |
+| 审核 | `/api/reviews` 审核通过/拒绝 |
+| 通知 | `/api/notifications` 通知管理 |
+| 智能解析 | `/api/parse-images`, `/api/*/smart-add`, `/api/*/smart-update` |
+| 搜索统计 | `/api/search`, `/api/calculate/vram`, `/api/stats` |
+| 配置 | `/api/config` |
+| 图片上传 | `/api/upload/image` |
 
 ## 版本
 
+- v2.0.0 - 产品审核发布 + 后台通知系统 + 完整API能力
 - v0.1.0 - 初始版本