aitsc/API_INTERFACE_DOCUMENTATION.md

# 提示词大师平台 API 接口文档

## 📋 **文档概述**

本文档提供了提示词大师平台的所有API接口，供第三方应用或新应用开发使用。

**基础信息：**
- **API版本：** v1.0
- **基础URL：** `http://localhost:5002/api`
- **数据格式：** JSON
- **认证方式：** API Key / Session Token

---

## 🔐 **认证接口**

### 1. 获取API访问令牌
```http
POST /api/auth/token
Content-Type: application/json

{
    "username": "your_username",
    "password": "your_password"
}
```

**响应示例：**
```json
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user_info": {
        "id": 1,
        "username": "your_username",
        "email": "user@example.com"
    }
}
```

### 2. 刷新访问令牌
```http
POST /api/auth/refresh
Authorization: Bearer {token}
```

---

## 📝 **模板管理接口**

### 1. 获取模板列表
```http
GET /api/templates?page=1&limit=20&category=all&search=关键词
Authorization: Bearer {token}
```

**查询参数：**
- `page`: 页码（默认1）
- `limit`: 每页数量（默认20，最大100）
- `category`: 分类筛选
- `search`: 搜索关键词
- `industry`: 行业筛选
- `profession`: 职业筛选
- `sub_category`: 子分类筛选

**响应示例：**
```json
{
    "success": true,
    "data": {
        "templates": [
            {
                "id": 1,
                "name": "通用优化",
                "description": "通用提示词优化",
                "category": "通用工具",
                "industry": "通用",
                "profession": "通用",
                "sub_category": "优化",
                "content": "你是一个专业的AI助手...",
                "usage_count": 1250,
                "rating": 4.8,
                "created_at": "2024-01-01T00:00:00Z",
                "updated_at": "2024-01-01T00:00:00Z"
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 20,
            "total": 281,
            "pages": 15
        }
    }
}
```

### 2. 获取单个模板详情
```http
GET /api/templates/{template_id}
Authorization: Bearer {token}
```

### 3. 创建新模板
```http
POST /api/templates
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "新模板名称",
    "description": "模板描述",
    "category": "分类名称",
    "industry": "行业",
    "profession": "职业",
    "sub_category": "子分类",
    "content": "模板内容"
}
```

### 4. 更新模板
```http
PUT /api/templates/{template_id}
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "更新后的名称",
    "description": "更新后的描述",
    "content": "更新后的内容"
}
```

### 5. 删除模板
```http
DELETE /api/templates/{template_id}
Authorization: Bearer {token}
```

---

## 🎯 **提示词生成接口**

### 1. 生成提示词
```http
POST /api/generate
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "input_text": "用户输入的详细需求描述",
    "options": {
        "max_length": 1000,
        "style": "professional",
        "language": "zh-CN"
    }
}
```

**响应示例：**
```json
{
    "success": true,
    "data": {
        "generated_text": "生成的提示词内容...",
        "template_used": {
            "id": 1,
            "name": "通用优化"
        },
        "generation_time": 1.2,
        "word_count": 150
    }
}
```

### 2. 批量生成提示词
```http
POST /api/generate/batch
Authorization: Bearer {token}
Content-Type: application/json

{
    "requests": [
        {
            "template_id": 1,
            "input_text": "需求1"
        },
        {
            "template_id": 2,
            "input_text": "需求2"
        }
    ]
}
```

---

## 📊 **分类管理接口**

### 1. 获取所有分类
```http
GET /api/categories
Authorization: Bearer {token}
```

**响应示例：**
```json
{
    "success": true,
    "data": {
        "categories": [
            {
                "name": "通用工具",
                "description": "通用工具类模板",
                "icon": "fas fa-tools",
                "template_count": 45
            }
        ]
    }
}
```

### 2. 获取行业列表
```http
GET /api/industries
Authorization: Bearer {token}
```

### 3. 获取职业列表
```http
GET /api/professions
Authorization: Bearer {token}
```

### 4. 获取子分类列表
```http
GET /api/sub-categories
Authorization: Bearer {token}
```

---

## ❤️ **收藏管理接口**

### 1. 获取用户收藏列表
```http
GET /api/favorites?page=1&limit=20
Authorization: Bearer {token}
```

### 2. 添加收藏
```http
POST /api/favorites
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "note": "个人备注"
}
```

### 3. 删除收藏
```http
DELETE /api/favorites/{favorite_id}
Authorization: Bearer {token}
```

### 4. 快速添加收藏（包含生成内容）
```http
POST /api/favorites/quick-add
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "original_text": "用户原始输入",
    "generated_prompt": "生成的提示词",
    "category": "分类名称"
}
```

---

## 📈 **统计接口**

### 1. 获取平台统计信息
```http
GET /api/stats/platform
Authorization: Bearer {token}
```

**响应示例：**
```json
{
    "success": true,
    "data": {
        "total_templates": 281,
        "total_categories": 73,
        "total_generations": 15420,
        "total_users": 1250,
        "popular_templates": [
            {
                "id": 1,
                "name": "通用优化",
                "usage_count": 1250
            }
        ]
    }
}
```

### 2. 获取用户统计信息
```http
GET /api/stats/user
Authorization: Bearer {token}
```

### 3. 获取模板使用统计
```http
GET /api/stats/templates/{template_id}
Authorization: Bearer {token}
```

---

## 🔍 **搜索接口**

### 1. 智能搜索
```http
GET /api/search?q=搜索关键词&type=template&limit=20
Authorization: Bearer {token}
```

**查询参数：**
- `q`: 搜索关键词
- `type`: 搜索类型（template, category, all）
- `limit`: 结果数量限制

### 2. 获取热门搜索
```http
GET /api/search/hot
Authorization: Bearer {token}
```

### 3. 获取搜索建议
```http
GET /api/search/suggestions?q=关键词
Authorization: Bearer {token}
```

---

## 👤 **用户管理接口**

### 1. 获取用户信息
```http
GET /api/user/profile
Authorization: Bearer {token}
```

### 2. 更新用户信息
```http
PUT /api/user/profile
Authorization: Bearer {token}
Content-Type: application/json

{
    "username": "新用户名",
    "email": "newemail@example.com",
    "avatar": "头像URL"
}
```

### 3. 修改密码
```http
PUT /api/user/password
Authorization: Bearer {token}
Content-Type: application/json

{
    "old_password": "旧密码",
    "new_password": "新密码"
}
```

---

## 📝 **使用示例**

### Python 示例
```python
import requests
import json

class PromptMasterAPI:
    def __init__(self, base_url="http://localhost:5002/api", token=None):
        self.base_url = base_url
        self.token = token
        self.headers = {
            "Content-Type": "application/json"
        }
        if token:
            self.headers["Authorization"] = f"Bearer {token}"
    
    def login(self, username, password):
        """用户登录获取token"""
        response = requests.post(
            f"{self.base_url}/auth/token",
            json={"username": username, "password": password}
        )
        data = response.json()
        if data["success"]:
            self.token = data["token"]
            self.headers["Authorization"] = f"Bearer {self.token}"
        return data
    
    def get_templates(self, page=1, limit=20, category="all", search=None):
        """获取模板列表"""
        params = {
            "page": page,
            "limit": limit,
            "category": category
        }
        if search:
            params["search"] = search
        
        response = requests.get(
            f"{self.base_url}/templates",
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def generate_prompt(self, template_id, input_text, options=None):
        """生成提示词"""
        data = {
            "template_id": template_id,
            "input_text": input_text
        }
        if options:
            data["options"] = options
        
        response = requests.post(
            f"{self.base_url}/generate",
            headers=self.headers,
            json=data
        )
        return response.json()
    
    def add_favorite(self, template_id, note=None):
        """添加收藏"""
        data = {"template_id": template_id}
        if note:
            data["note"] = note
        
        response = requests.post(
            f"{self.base_url}/favorites",
            headers=self.headers,
            json=data
        )
        return response.json()

# 使用示例
api = PromptMasterAPI()

# 登录
result = api.login("your_username", "your_password")
if result["success"]:
    print("登录成功！")
    
    # 获取模板列表
    templates = api.get_templates(page=1, limit=10)
    print(f"找到 {templates['data']['pagination']['total']} 个模板")
    
    # 生成提示词
    if templates["data"]["templates"]:
        template_id = templates["data"]["templates"][0]["id"]
        result = api.generate_prompt(
            template_id=template_id,
            input_text="请帮我写一篇关于人工智能的文章"
        )
        if result["success"]:
            print("生成的提示词：", result["data"]["generated_text"])
```

### JavaScript 示例
```javascript
class PromptMasterAPI {
    constructor(baseUrl = 'http://localhost:5002/api', token = null) {
        this.baseUrl = baseUrl;
        this.token = token;
        this.headers = {
            'Content-Type': 'application/json'
        };
        if (token) {
            this.headers['Authorization'] = `Bearer ${token}`;
        }
    }
    
    async login(username, password) {
        const response = await fetch(`${this.baseUrl}/auth/token`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ username, password })
        });
        const data = await response.json();
        if (data.success) {
            this.token = data.token;
            this.headers['Authorization'] = `Bearer ${this.token}`;
        }
        return data;
    }
    
    async getTemplates(page = 1, limit = 20, category = 'all', search = null) {
        const params = new URLSearchParams({
            page: page.toString(),
            limit: limit.toString(),
            category: category
        });
        if (search) params.append('search', search);
        
        const response = await fetch(`${this.baseUrl}/templates?${params}`, {
            headers: this.headers
        });
        return await response.json();
    }
    
    async generatePrompt(templateId, inputText, options = null) {
        const data = {
            template_id: templateId,
            input_text: inputText
        };
        if (options) data.options = options;
        
        const response = await fetch(`${this.baseUrl}/generate`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(data)
        });
        return await response.json();
    }
}

// 使用示例
const api = new PromptMasterAPI();

// 登录
api.login('your_username', 'your_password').then(result => {
    if (result.success) {
        console.log('登录成功！');
        
        // 获取模板列表
        return api.getTemplates(1, 10);
    }
}).then(templates => {
    if (templates && templates.success) {
        console.log(`找到 ${templates.data.pagination.total} 个模板`);
        
        // 生成提示词
        if (templates.data.templates.length > 0) {
            const templateId = templates.data.templates[0].id;
            return api.generatePrompt(templateId, '请帮我写一篇关于人工智能的文章');
        }
    }
}).then(result => {
    if (result && result.success) {
        console.log('生成的提示词：', result.data.generated_text);
    }
});
```

---

## 🚨 **错误处理**

### 错误响应格式
```json
{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "错误描述信息",
        "details": "详细错误信息"
    }
}
```

### 常见错误码
- `AUTH_REQUIRED`: 需要认证
- `INVALID_TOKEN`: 无效的访问令牌
- `TOKEN_EXPIRED`: 令牌已过期
- `PERMISSION_DENIED`: 权限不足
- `RESOURCE_NOT_FOUND`: 资源不存在
- `VALIDATION_ERROR`: 参数验证失败
- `RATE_LIMIT_EXCEEDED`: 请求频率超限
- `INTERNAL_ERROR`: 服务器内部错误

---

## 📊 **速率限制**

- **普通用户：** 100次/小时
- **高级用户：** 1000次/小时
- **企业用户：** 10000次/小时

超过限制时返回 `429 Too Many Requests` 状态码。

---

## 🔧 **开发建议**

### 1. 环境准备
- 确保现有服务正常运行在 `http://localhost:5002`
- 准备测试账号和API访问权限
- 安装必要的开发工具和SDK

### 2. 开发流程
1. **接口测试：** 使用Postman或curl测试所有接口
2. **SDK开发：** 封装API调用为易用的SDK
3. **错误处理：** 实现完善的错误处理机制
4. **缓存策略：** 对模板列表等数据进行缓存
5. **监控日志：** 记录API调用日志和性能指标

### 3. 安全考虑
- 使用HTTPS传输
- 实现API Key轮换机制
- 添加请求签名验证
- 实现IP白名单限制

### 4. 性能优化
- 实现请求缓存
- 使用连接池
- 添加重试机制
- 实现异步处理

---

## 📞 **技术支持**

如有问题，请联系：
- **邮箱：** support@promptmaster.com
- **文档：** https://docs.promptmaster.com
- **GitHub：** https://github.com/promptmaster/api