# 书籍管理系统 API 设计

基于之前设计的 MySQL 表结构，以下是完整的 RESTful API 设计，包含调用示例和必填/非必填项说明。

## 1. 作者管理接口

### 1.1 创建作者

```
POST /api/authors
```

​**​请求参数​**​：

```
{
  "name": "鲁迅", // 必填
  "bio": "中国现代文学奠基人", // 非必填
  "birth_date": "1881-09-25", // 非必填
  "death_date": "1936-10-19", // 非必填
  "nationality": "中国" // 非必填
}
```

​**​成功响应​**​：

```
{
  "author_id": 1,
  "name": "鲁迅",
  "bio": "中国现代文学奠基人",
  "birth_date": "1881-09-25",
  "death_date": "1936-10-19",
  "nationality": "中国",
  "created_at": "2023-08-01T10:00:00Z"
}
```

### 1.2 获取作者列表

```
GET /api/authors?page=1&page_size=10&name=鲁迅
```

​**​查询参数​**​：

- `page`: 页码 (非必填，默认1)
- `page_size`: 每页数量 (非必填，默认10)
- `name`: 作者姓名模糊搜索 (非必填)

​**​成功响应​**​：

```
{
  "total": 1,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "author_id": 1,
      "name": "鲁迅",
      "bio": "中国现代文学奠基人",
      "birth_date": "1881-09-25",
      "death_date": "1936-10-19",
      "nationality": "中国"
    }
  ]
}
```

## 2. 书籍管理接口

### 2.1 创建书籍

```
POST /api/books
```

​**​请求参数​**​：

```
{
  "title": "呐喊", // 必填
  "author_id": 1, // 必填
  "type_id": 1, // 必填
  "cover_image_url": "https://example.com/nahan.jpg", // 非必填
  "description": "鲁迅的第一部小说集", // 非必填
  "isbn": "9787020090006", // 非必填
  "publish_date": "1923-08-01", // 非必填
  "publisher": "新潮社", // 非必填
  "page_count": 200, // 非必填
  "language": "中文", // 非必填
  "status": "published" // 非必填，默认draft
}
```

​**​成功响应​**​：

```
{
  "book_id": 1,
  "title": "呐喊",
  "author_id": 1,
  "type_id": 1,
  "cover_image_url": "https://example.com/nahan.jpg",
  "status": "published",
  "created_at": "2023-08-01T10:00:00Z"
}
```

### 2.2 更新书籍信息

```
PUT /api/books/{book_id}
```

​**​请求参数​**​：

```
{
  "title": "呐喊（修订版）", // 非必填
  "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇", // 非必填
  "status": "published" // 非必填
}
```

​**​成功响应​**​：

```
{
  "book_id": 1,
  "title": "呐喊（修订版）",
  "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇",
  "updated_at": "2023-08-01T11:00:00Z"
}
```

## 3. 章节管理接口

### 3.1 创建章节

```
POST /api/books/{book_id}/chapters
```

​**​请求参数​**​：

```
{
  "chapter_number": 1, // 必填
  "title": "狂人日记", // 必填
  "content": "今天晚上，很好的月光..." // 非必填
}
```

​**​成功响应​**​：

```
{
  "chapter_id": 1,
  "book_id": 1,
  "chapter_number": 1,
  "title": "狂人日记",
  "word_count": 0,
  "created_at": "2023-08-01T10:00:00Z"
}
```

### 3.2 更新章节内容

```
PUT /api/chapters/{chapter_id}/content
```

​**​请求参数​**​：

```
{
  "content": "今天晚上，很好的月光...我不见他，已是三十多年...", // 必填
  "change_reason": "修正错别字" // 非必填
}
```

​**​成功响应​**​：

```
{
  "content_id": 1,
  "chapter_id": 1,
  "version": 2,
  "word_count": 15,
  "updated_at": "2023-08-01T11:00:00Z"
}
```

## 4. 历史记录查询接口

### 4.1 获取书籍修改历史

```
GET /api/books/{book_id}/history?page=1&page_size=10
```

​**​查询参数​**​：

- `page`: 页码 (非必填，默认1)
- `page_size`: 每页数量 (非必填，默认10)

​**​成功响应​**​：

```
{
  "total": 2,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "history_id": 1,
      "title": "呐喊",
      "description": "鲁迅的第一部小说集",
      "changed_at": "2023-08-01T10:00:00Z"
    },
    {
      "history_id": 2,
      "title": "呐喊（修订版）",
      "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇",
      "changed_at": "2023-08-01T11:00:00Z"
    }
  ]
}
```

### 4.2 获取章节内容历史

```
GET /api/chapters/{chapter_id}/content/history?page=1&page_size=10
```

​**​成功响应​**​：

```
{
  "total": 2,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "history_id": 1,
      "version": 1,
      "word_count": 0,
      "change_reason": "初始版本",
      "changed_at": "2023-08-01T10:00:00Z"
    },
    {
      "history_id": 2,
      "version": 2,
      "word_count": 15,
      "change_reason": "修正错别字",
      "changed_at": "2023-08-01T11:00:00Z"
    }
  ]
}
```

## 5. 错误响应

所有接口的错误响应格式统一：

```
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "作者ID不能为空",
    "details": {
      "author_id": "该字段为必填项"
    }
  }
}
```

常见错误码：

- `INVALID_PARAMETER`: 参数验证失败
- `RESOURCE_NOT_FOUND`: 资源不存在
- `DUPLICATE_RESOURCE`: 资源已存在
- `PERMISSION_DENIED`: 权限不足

## 接口设计说明

1. ​**​必填项验证​**​：所有创建接口的必填字段都会进行验证
2. ​**​版本控制​**​：章节内容修改会自动生成新版本
3. ​**​分页查询​**​：所有列表接口都支持分页
4. ​**​历史追踪​**​：书籍和章节的修改都会记录历史
5. ​**​RESTful风格​**​：资源路径清晰，HTTP方法语义明确

这个API设计覆盖了表结构中的所有核心功能，并考虑了实际应用场景中的需求。