daShangDao_centerBook/md/API.md

# 图书中心系统 API 文档

## 基础信息

- **Base URL**: `http://localhost:9009`
- **API 版本**: v1.0
- **数据格式**: JSON
- **字符编码**: UTF-8

---

## 目录

- [图书管理](#图书管理)
- [搜索服务](#搜索服务)
- [销量管理](#销量管理)
- [图片管理](#图片管理)
- [系统监控](#系统监控)
- [Elasticsearch 操作](#elasticsearch-操作)

---

## 通用响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

### 错误响应

```json
{
  "error": "错误描述",
  "details": "详细错误信息"
}
```

### 分页响应

```json
{
  "current_page": 1,
  "data": [...],
  "per_page": 10,
  "total": 100
}
```

---

## 图书管理

### 1. 根据 ISBN 查询图书

**请求**:
```http
GET /api/book/isbn?isbn=9787111111111
```

**参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| isbn | string | 是 | 图书ISBN号 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123456,
    "isbn": "9787111111111",
    "book_name": "Go语言编程",
    "author": "作者名",
    "publisher": "清华大学出版社",
    "fix_price": 99.00,
    "book_pic": "http://example.com/image.jpg",
    "update_time": "1705228800"
  }
}
```

### 2. 添加图书到 ES

**请求**:
```http
POST /api/es/book
Content-Type: application/json

{
  "book_name": "Go语言编程实战",
  "isbn": "9787111122222",
  "author": "作者名",
  "publisher": "出版社",
  "fix_price": 89.00,
  "book_pic": {
    "localPath": "",
    "pddPath": "http://example.com/image.jpg"
  },
  "book_pic_s": {
    "localPath": "",
    "pddResponse": "http://example.com/image_s.jpg"
  }
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123457,
    "source": "service"
  }
}
```

### 3. 批量添加图书

**请求**:
```http
POST /api/es/books/batch
Content-Type: application/json

{
  "books": [
    {
      "book_name": "Go语言编程",
      "isbn": "9787111111111",
      "author": "作者1",
      "publisher": "出版社1"
    },
    {
      "book_name": "Python实战",
      "isbn": "9787111133333",
      "author": "作者2",
      "publisher": "出版社2"
    }
  ]
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "批量插入完成",
  "data": {
    "total_count": 2,
    "success_count": 2,
    "failed_count": 0,
    "results": [
      {
        "index": 0,
        "isbn": "9787111111111",
        "success": true,
        "document": "9787111111111"
      },
      {
        "index": 1,
        "isbn": "9787111133333",
        "success": true,
        "document": "9787111133333"
      }
    ]
  }
}
```

### 4. 检查图书是否存在

**请求**:
```http
GET /api/es/book/exists?isbn=9787111111111
```

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "data": {
    "exists": true,
    "isbn": "9787111111111",
    "book_id": "123456",
    "book_name": "Go语言编程",
    "message": "书籍存在"
  }
}
```

### 5. 更新图书字段

**请求**:
```http
PUT /api/es/book/fields
Content-Type: application/json

{
  "isbn": "9787111111111",
  "data": {
    "fix_price": 88.00,
    "author": "新作者名",
    "total_sale": 1000
  }
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "updated": 1,
    "fields_updated": 3,
    "updated_fields": ["fix_price", "author", "total_sale"]
  }
}
```

### 6. 删除图书

**请求**:
```http
DELETE /api/es/book?isbn=9787111111111
```

或

```http
DELETE /api/es/book?id=123456
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "deleted": true
  }
}
```

---

## 搜索服务

### 1. 关键词搜索

**请求**:
```http
GET /api/search?keyword=Go语言&page=1&pageSize=10
```

**参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页数量，默认10 |

**响应示例**:
```json
{
  "count": 100,
  "data": [
    {
      "id": 123456,
      "book_name": "Go语言编程",
      "author": "作者名",
      "isbn": "9787111111111",
      "publisher": "清华大学出版社",
      "fix_price": 99.00
    }
  ]
}
```

### 2. 多条件搜索

**请求**:
```http
GET /api/search/conditions?book_name=Go&author=张三&page=1&pageSize=20
```

**支持的查询参数**:
- `book_name` - 书名
- `isbn` - ISBN
- `author` - 作者
- `category` - 分类
- `publisher` - 出版社
- `publication_time` - 出版时间范围（逗号分隔）
- `day_sale_7` - 7天销量范围
- `total_sale` - 总销量范围
- `sell_counts` - 在售数量范围
- `is_suit` - 是否套装 (0/1)
- `is_return` - 是否驳回 (0/1)
- `is_filter` - 过滤字段
- `book_pic` - 是否有图 (0/1)
- `picType` - 图片类型 (1-官图, 2-小图)
- `saleSelect` - 销量维度选择 (7/15/30/60/90/180/365/0/1)
- `categoryType` - 分类类型 (1-教材, 其他-非教材)

**响应示例**:
```json
{
  "code": 200,
  "current_page": 1,
  "data": [...],
  "per_page": 20,
  "total": 156
}
```

### 3. 全字段搜索

**请求**:
```http
GET /api/search/all?q=Go语言编程
```

**参数**:
- `q` - 搜索关键词（搜索所有字段）

---

## 销量管理

### 1. 更新在售数量

**请求**:
```http
POST /api/sellcounts/update?isbn=9787111111111&onSaleCount=100
```

**参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| isbn | string | 是 | 图书ISBN |
| onSaleCount | int | 是 | 在售数量（非负整数） |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "sell_counts": 100,
    "async": true
  }
}
```

### 2. 从外部API更新在售数量

**请求**:
```http
POST /api/sellcounts/fetch?isbn=9787111111111
```

**说明**: 自动调用 tail API 获取在售数量并更新

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "on_sale_count": 150,
    "async": true
  }
}
```

---

## 图片管理

### 1. 更新图书图片

**请求**:
```http
POST /api/book/pic/update?isbn=9787111111111&book_pic=http://example.com/new.jpg&book_pic_s=http://example.com/new_s.jpg
```

**参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| isbn | string | 是 | 图书ISBN |
| book_pic | string | 否 | 大图URL |
| book_pic_s | string | 否 | 小图URL |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "updated": 1
  }
}
```

---

## 系统监控

### 1. 健康检查

**请求**:
```http
GET /health
```

**响应示例**:
```json
{
  "status": "healthy",
  "mysql": "connected",
  "redis": "connected",
  "elasticsearch": "connected",
  "timestamp": "2025-01-14T10:30:00Z"
}
```

### 2. 服务就绪检查

**请求**:
```http
GET /ready
```

**响应示例**:
```json
{
  "ready": true
}
```

---

## Elasticsearch 操作

### 1. 查询所有索引

**请求**:
```http
GET /api/es/indices
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    "books-from-mysql-v2",
    "books-from-mysql-new",
    "test-go-index"
  ]
}
```

### 2. 获取索引详情

**请求**:
```http
GET /api/es/index/detail?indexName=books-from-mysql-v2
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "books-from-mysql-v2": {
      "aliases": {},
      "mappings": { ... },
      "settings": { ... }
    }
  }
}
```

### 3. 获取文档数量

**请求**:
```http
GET /api/es/index/count?indexName=books-from-mysql-v2
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "count": 1000000
  }
}
```

### 4. 检查套装书

**请求**:
```http
GET /api/book/check-suit?bookName=Go语言编程（套装）
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "book_name": "Go语言编程（套装）",
    "is_suit": true
  }
}
```

### 5. 更新套装标记

**请求**:
```http
PUT /api/book/suit
Content-Type: application/json

{
  "isbn": "9787111111111"
}
```

**说明**: 自动根据书名判断是否为套装书并更新

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "book_name": "Go语言编程（套装）",
    "is_suit": 1,
    "updated": 1,
    "contains_suit_keyword": true
  }
}
```

### 6. 统计ID范围数量

**请求**:
```http
GET /api/es/count/range?minID=1&maxID=100000
```

**响应示例**:
```json
{
  "code": 200,
  "minID": 1,
  "maxID": 100000,
  "count": 50000
}
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 请求示例

### 使用 curl

```bash
# 查询图书
curl "http://localhost:9009/api/book/isbn?isbn=9787111111111"

# 搜索图书
curl "http://localhost:9009/api/search?keyword=Go语言&page=1&pageSize=10"

# 添加图书
curl -X POST http://localhost:9009/api/es/book \
  -H "Content-Type: application/json" \
  -d '{"book_name":"Go语言编程","isbn":"9787111111111","author":"作者名"}'

# 更新在售数量
curl -X POST "http://localhost:9009/api/sellcounts/update?isbn=9787111111111&onSaleCount=100"
```

### 使用 Go

```go
import "net/http"

// 查询图书
resp, err := http.Get("http://localhost:9009/api/book/isbn?isbn=9787111111111")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

// 解析响应
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### 使用 JavaScript

```javascript
// 查询图书
fetch('http://localhost:9009/api/book/isbn?isbn=9787111111111')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));
```

---

## 注意事项

1. **所有时间戳格式**: Unix 时间戳（秒）
2. **价格单位**: 分（需要除以100转换为元）
3. **分页参数**: page 从 1 开始
4. **异步操作**: 部分更新操作为异步执行，返回 `async: true`
5. **CORS**: 默认允许跨域请求

---

## 更新日志

### v1.0.0 (2025-01-14)
- 初始 API 文档
- 完整的图书管理接口
- Elasticsearch 操作接口
- 销量管理接口

---

**最后更新**: 2025-01-14