ai_wht_B/API接口文档.md

# AI文章生成管理平台 API接口文档

## 接口概述

- **Base URL**: `http://127.0.0.1:8216`
- **搜索服务**: `http://127.0.0.1:8321`
- **数据格式**: JSON
- **字符编码**: UTF-8
- **认证方式**: JWT Token (Bearer)

---

## 统一响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "错误信息",
  "data": null
}
```

### 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 一、基础接口

### 1.1 根路径
**接口**: `GET /`

**认证**: 无需认证

**响应数据**:
```json
{
  "code": 200,
  "message": "万花筒API服务正常运行",
  "data": {
    "version": "1.0",
    "service": "wht_api"
  }
}
```

---

### 1.2 健康检查
**接口**: `GET /health`

**认证**: 无需认证

**响应数据**:
```json
{
  "code": 200,
  "message": "服务正常",
  "data": {
    "status": "healthy",
    "timestamp": 1704267825000,
    "version": "2.0"
  }
}
```

---

## 二、认证接口

### 2.1 统一登录
**接口**: `POST /api/auth/login`

**认证**: 无需认证

**支持方式**: 用户名登录、手机号登录

**请求参数（用户名方式）**:
```json
{
  "username": "13621242430",
  "password": "admin123"
}
```

**请求参数（手机号方式）**:
```json
{
  "phone": "13621242430",
  "password": "admin123"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "13621242430",
      "enterprise_id": 1
    }
  }
}
```

---

### 2.2 员工登录
**接口**: `POST /api/auth/employee/login`

**认证**: 无需认证

**请求参数**:
```json
{
  "phone": "13800138001",
  "password": "123456"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "employee": {
      "id": 1,
      "name": "张三",
      "phone": "13800138001",
      "enterprise_id": 1
    }
  }
}
```

---

### 2.3 用户登出
**接口**: `POST /api/auth/logout`

**认证**: 可选（建议携带token）

**请求头**:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**响应数据**:
```json
{
  "code": 200,
  "message": "登出成功",
  "data": null
}
```

---

## 三、工作台接口

### 3.1 工作台概览
**接口**: `GET /api/dashboard/overview`

**认证**: 需要token

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_articles": 1250,
    "published_today": 45,
    "total_authors": 128,
    "active_products": 23
  }
}
```

---

### 3.2 最近发布
**接口**: `GET /api/dashboard/recent-publishes`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| limit | int | 否 | 返回条数，默认10 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "冬季护肤小技巧",
        "author_name": "张医生",
        "product_name": "保湿面霜",
        "published_at": "2024-12-29 15:30:00"
      }
    ]
  }
}
```

---

### 3.3 热门产品
**接口**: `GET /api/dashboard/hot-products`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| limit | int | 否 | 返回条数，默认5 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "product_name": "保湿面霜",
        "publish_count": 156,
        "image_url": "https://oss.example.com/product1.jpg"
      }
    ]
  }
}
```

---

## 四、企业管理接口

### 4.1 获取企业列表
**接口**: `GET /api/enterprises/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| status | string | 否 | 状态筛选 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "list": [
      {
        "id": 1,
        "name": "示例医疗集团",
        "short_name": "示例医疗",
        "phone": "13800138000",
        "email": "admin@example.com",
        "status": "active",
        "created_at": "2024-01-15 10:00:00"
      }
    ]
  }
}
```

---

### 4.2 企业统计
**接口**: `GET /api/enterprises/stats`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_count": 50,
    "active_count": 45,
    "disabled_count": 5
  }
}
```

---

### 4.3 获取企业信息
**接口**: `GET /api/enterprises/info`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "示例医疗集团",
    "short_name": "示例医疗",
    "phone": "13800138000",
    "email": "admin@example.com",
    "created_at": "2024-01-15 10:00:00"
  }
}
```

---

### 4.4 更新企业信息
**接口**: `PUT /api/enterprises/info`

**认证**: 需要token

**请求参数**:
```json
{
  "short_name": "新名称",
  "email": "new@example.com"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 4.5 修改密码
**接口**: `PUT /api/enterprises/change-password`

**认证**: 需要token

**请求参数**:
```json
{
  "old_password": "123456",
  "new_password": "654321"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}
```

---

## 五、图片管理接口

### 5.1 图片列表
**接口**: `GET /api/images/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "id": 1,
        "image_name": "产品展示图",
        "image_url": "https://oss.example.com/image1.jpg",
        "image_type_name": "产品图",
        "width": 1920,
        "height": 1080,
        "file_size": 524288,
        "created_at": "2024-12-29 10:00:00"
      }
    ]
  }
}
```

---

### 5.2 图片仪表盘
**接口**: `GET /api/images/list_dashboard`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_images": 1250,
    "total_types": 8,
    "total_tags": 45,
    "recent_uploads": 23
  }
}
```

---

### 5.3 上传图片
**接口**: `POST /api/images/upload`

**认证**: 需要token

**请求参数**: multipart/form-data
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| image | file | 是 | 图片文件 |
| image_name | string | 是 | 图片名称 |
| image_type_name | string | 否 | 图片类型 |
| tag_keywords | string | 否 | 标签，逗号分隔 |

**响应数据**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "image_url": "https://oss.example.com/image1.jpg",
    "thumbnail_url": "https://oss.example.com/thumb1.jpg"
  }
}
```

---

### 5.4 删除图片
**接口**: `DELETE /api/images/:id`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

### 5.5 标签名称列表
**接口**: `GET /api/images/tags/names/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "list": [
      {
        "id": 1,
        "tag_name": "美白",
        "description": "美白相关标签",
        "usage_count": 156
      }
    ]
  }
}
```

---

### 5.6 创建标签名称
**接口**: `POST /api/images/tags/names/create`

**认证**: 需要token

**请求参数**:
```json
{
  "tag_name": "美白",
  "description": "美白相关标签"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1
  }
}
```

---

### 5.7 更新标签名称
**接口**: `PUT /api/images/tags/names/:id`

**认证**: 需要token

**请求参数**:
```json
{
  "tag_name": "美白淡斑",
  "description": "美白淡斑相关"
}
```

---

### 5.8 删除标签名称
**接口**: `DELETE /api/images/tags/names/:id`

**认证**: 需要token

---

### 5.9 标签关系列表
**接口**: `GET /api/images/tags/relations/list`

**认证**: 需要token

**说明**: 查询图片与标签的关联关系

---

### 5.10 图片类型列表
**接口**: `GET /api/images/types/list`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "type_name": "产品图",
        "description": "产品展示图片",
        "image_count": 156
      }
    ]
  }
}
```

---

### 5.11 创建类型
**接口**: `POST /api/images/types/create`

**认证**: 需要token

**请求参数**:
```json
{
  "type_name": "产品图",
  "description": "产品展示图片"
}
```

---

### 5.12 更新类型
**接口**: `PUT /api/images/types/:id`

**认证**: 需要token

---

### 5.13 删除类型
**接口**: `DELETE /api/images/types/:id`

**认证**: 需要token

---

### 5.14 标签列表
**接口**: `GET /api/images/tags/list`

**认证**: 需要token

**说明**: 获取图片标签列表（图片-标签关联）

---

### 5.15 创建标签
**接口**: `POST /api/images/tags/create`

**认证**: 需要token

**说明**: 为图片添加标签

---

### 5.16 删除标签
**接口**: `DELETE /api/images/tags/:id`

**认证**: 需要token

**说明**: 删除图片标签关联

---

## 六、日志管理接口

### 6.1 获取操作日志
**接口**: `GET /api/log/logs`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| action | string | 否 | 操作类型 |
| status | string | 否 | 状态：success/error |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 1000,
    "list": [
      {
        "id": 1,
        "user_id": 1,
        "action": "create_article",
        "description": "创建文章：冬季护肤小技巧",
        "status": "success",
        "created_at": "2024-12-29 14:30:00"
      }
    ]
  }
}
```

---

### 6.2 日志文件列表
**接口**: `GET /api/log/logs/files`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "files": [
      {
        "filename": "article_server.log",
        "size": 1024000,
        "modified_at": "2024-12-29 15:00:00"
      }
    ]
  }
}
```

---

### 6.3 文件日志内容
**接口**: `GET /api/log/logs/file`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| filename | string | 是 | 文件名 |
| lines | int | 否 | 读取行数，默认100 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": "[2024-12-29 15:00:00] INFO: 服务启动\n..."
  }
}
```

---

## 七、文章管理接口

### 7.1 文章列表
**接口**: `GET /api/articles/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| status | string | 否 | 状态筛选 |
| keyword | string | 否 | 搜索关键词 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 500,
    "list": [
      {
        "id": 1,
        "title": "冬季护肤小技巧",
        "topic": "护肤",
        "content": "文章内容...",
        "author_name": "张医生",
        "status": "published",
        "created_at": "2024-12-29 10:00:00"
      }
    ]
  }
}
```

---

### 7.2 文章仪表盘
**接口**: `GET /api/articles/list_dashboard`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_articles": 1250,
    "published_count": 856,
    "draft_count": 394,
    "today_generated": 23
  }
}
```

---

### 7.3 生成文章
**接口**: `POST /api/articles/generate`

**认证**: 需要token

**请求参数**:
```json
{
  "topic": "冬季护肤",
  "author_id": 1,
  "product_id": 5,
  "template_id": 2
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "生成成功",
  "data": {
    "id": 1,
    "title": "冬季护肤小技巧",
    "content": "..."
  }
}
```

---

### 7.4 文章详情
**接口**: `GET /api/articles/:id`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "冬季护肤小技巧",
    "topic": "护肤",
    "content": "详细内容...",
    "author_id": 1,
    "author_name": "张医生",
    "status": "published",
    "created_at": "2024-12-29 10:00:00"
  }
}
```

---

### 7.5 更新文章
**接口**: `PUT /api/articles/:id`

**认证**: 需要token

**请求参数**:
```json
{
  "title": "新标题",
  "content": "新内容",
  "status": "published"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 7.6 批量发布（账号循环）
**接口**: `POST /api/articles/batch-published-account-cycle`

**认证**: 需要token

**请求参数**:
```json
{
  "article_ids": [1, 2, 3, 4, 5],
  "cycle_mode": "round_robin"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "批量发布成功",
  "data": {
    "success_count": 5,
    "failed_count": 0
  }
}
```

---

### 7.7 批量发布（指定作者）
**接口**: `POST /api/articles/batch-published-review`

**认证**: 需要token

**请求参数**:
```json
{
  "article_ids": [1, 2, 3],
  "author_id": 5
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "批量发布成功",
  "data": {
    "success_count": 3,
    "failed_count": 0
  }
}
```

---

## 八、员工管理接口

### 8.1 员工列表
**接口**: `GET /api/employees/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| keyword | string | 否 | 搜索关键词 |
| status | string | 否 | 状态筛选 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "list": [
      {
        "id": 1,
        "name": "张三",
        "phone": "13800138001",
        "role": "员工",
        "status": "active",
        "created_at": "2024-01-15 10:00:00"
      }
    ]
  }
}
```

---

### 8.2 员工统计
**接口**: `GET /api/employees/stats`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_count": 50,
    "active_count": 45,
    "inactive_count": 5
  }
}
```

---

### 8.3 添加员工
**接口**: `POST /api/employees/add`

**认证**: 需要token

**请求参数**:
```json
{
  "name": "张三",
  "phone": "13800138001",
  "password": "123456",
  "role": "员工"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": {
    "id": 1
  }
}
```

---

### 8.4 删除员工
**接口**: `DELETE /api/employees/:id`

**认证**: 需要token

**说明**: 软删除，仅删除登录权限，保留发布记录

**响应数据**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

## 九、作者管理接口

### 9.1 作者列表（按科室分组）
**接口**: `GET /api/authors`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "departments": [
      {
        "department_name": "皮肤科",
        "authors": [
          {
            "id": 1,
            "author_name": "张医生",
            "title": "主治医师",
            "department": "皮肤科"
          }
        ]
      }
    ]
  }
}
```

---

### 9.2 创建作者
**接口**: `POST /api/authors`

**认证**: 需要token

**请求参数**:
```json
{
  "author_name": "张医生",
  "title": "主治医师",
  "department": "皮肤科",
  "bio": "专注皮肤护理20年"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1
  }
}
```

---

### 9.3 更新作者
**接口**: `PUT /api/authors/:id`

**认证**: 需要token

**请求参数**:
```json
{
  "author_name": "张医生",
  "title": "副主任医师",
  "department": "皮肤科"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 9.4 删除作者
**接口**: `DELETE /api/authors/:id`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

### 9.5 作者列表（用户关联）
**接口**: `GET /api/authors/list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | int | 否 | 用户ID |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "author_name": "张医生",
        "department": "皮肤科"
      }
    ]
  }
}
```

---

### 9.6 作者详细列表
**接口**: `GET /api/authors/detail_list`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 128,
    "list": [
      {
        "id": 1,
        "author_name": "张医生",
        "title": "主治医师",
        "department": "皮肤科",
        "bio": "专注皮肤护理20年",
        "article_count": 45,
        "created_at": "2024-01-15 10:00:00"
      }
    ]
  }
}
```

---

### 9.7 科室列表
**接口**: `GET /api/authors/departments`

**认证**: 需要token

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "departments": [
      {
        "department_name": "皮肤科",
        "author_count": 12
      },
      {
        "department_name": "内科",
        "author_count": 15
      }
    ]
  }
}
```

---

### 9.8 搜索作者
**接口**: `GET /api/authors/search`

**认证**: 需要token

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 是 | 搜索关键词 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "author_name": "张医生",
        "title": "主治医师",
        "department": "皮肤科"
      }
    ]
  }
}
```

---

## 附录

### A. 请求头说明

所有需要认证的接口都需要携带以下请求头：

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```

### B. 分页参数说明

所有列表接口都支持以下分页参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | int | 1 | 页码 |
| pageSize | int | 20 | 每页数量，最大100 |

### C. 错误码说明

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 1001 | 用户名/手机号已存在 | 使用其他账号 |
| 1002 | 密码错误 | 检查密码 |
| 1003 | Token过期 | 重新登录 |
| 1004 | 权限不足 | 检查用户角色 |
| 1005 | 资源不存在 | 检查资源ID |
| 1006 | 参数错误 | 检查请求参数 |

### D. 业务规则说明

1. **文章生成规则**
   - 支持AI自动生成文章
   - 可指定作者、产品、模板
   - 生成后状态为topic，需人工审核

2. **批量发布规则**
   - 支持账号循环模式
   - 支持指定作者模式
   - 发布后状态变为published

3. **权限管理规则**
   - 不同企业之间的数据完全隔离
   - 员工只能看到所属企业的数据
   - 管理员可以管理所有数据

4. **图片管理规则**
   - 支持OSS存储
   - 自动生成缩略图
   - 支持标签和类型管理

5. **日志记录规则**
   - 所有关键操作必须记录日志
   - 支持按多维度查询日志
   - 日志文件每日自动切割

6. **作者管理规则**
   - 支持按科室分组
   - 记录作者的文章数量
   - 支持模糊搜索

---

### E. 数据库表结构对应

本接口文档对应的数据库表结构：

| 模块 | 核心表 |
|------|------|
| 企业管理 | ai_enterprises |
| 员工管理 | ai_employees |
| 图片管理 | ai_images, ai_image_tags, ai_image_tag_names, ai_image_types |
| 文章管理 | ai_articles |
| 作者管理 | ai_authors |
| 系统管理 | ai_logs, ai_users |

**总计**: 10+张数据库表

---

### F. 接口数量统计

| 模块 | 接口数量 |
|------|----------|
| 基础接口 | 2个 |
| 认证接口 | 3个 |
| 工作台接口 | 3个 |
| 企业管理 | 5个 |
| 图片管理 | 16个 |
| 日志管理 | 3个 |
| 文章管理 | 7个 |
| 员工管理 | 4个 |
| 作者管理 | 8个 |
| **总计** | **51个接口** |

---

**文档版本**: v2.0  
**最后更新**: 2025-12-29  
**维护团队**: AI文章生成平台开发团队