# 书籍系列 admin 接口

## 基本信息

- 模块：book
- 资源：书籍系列
- 端：admin
- 鉴权：`PrivateGroup`，需要 `JWT + Casbin`
- 审计：创建、更新、单删、批量删除启用 `OperationRecord`
- 前缀：`/book`
- 实体模型：`book.BookSeries`
- 搜索入参：`bookReq.BookSeriesSearch`
- 详情响应：`bookRes.BookSeriesResponse`
- 列表项：`book.BookSeries`
- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
- 删除策略：硬删

## CRUD

### 创建书籍系列

- Method：`POST`
- Path：`/book/createBookSeries`
- Handler：`BookSeriesApi.CreateBookSeries`
- Service：`BookSeriesService.CreateBookSeries`
- 审计：是

#### Request Body `book.BookSeries`

| 字段 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| name | string | 是 | 非空，最大长度 `128` | 系列名称 |
| coverUrl | string | 否 | 最大长度 `500` | 系列封面图片 URL |
| intro | string | 否 | 文本 | 系列简介 |
| isEnabled | bool | 否 | 默认 `true` | 系列是否启用 |

#### Response

- `response.Response{msg}`

#### 规则

- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
- `name` 写入 `book_series.name`，数据库要求非空。
- `isEnabled` 未传时按数据库默认值 `true` 落库。

### 删除书籍系列

- Method：`DELETE`
- Path：`/book/deleteBookSeries`
- Handler：`BookSeriesApi.DeleteBookSeries`
- Service：`BookSeriesService.DeleteBookSeries`
- 审计：是

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | int | 是 | `> 0` | 系列 ID |

#### Response

- `response.Response{msg}`

#### 规则

- 删除策略为硬删，删除后记录不再保留在 `book_series` 表。

### 批量删除书籍系列

- Method：`DELETE`
- Path：`/book/deleteBookSeriesByIds`
- Handler：`BookSeriesApi.DeleteBookSeriesByIds`
- Service：`BookSeriesService.DeleteBookSeriesByIds`
- 审计：是

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| ids | int[] | 二选一 | 非空，元素均 `> 0` | 系列 ID 数组 |
| ids[] | int[] | 二选一 | 非空，元素均 `> 0` | 系列 ID 数组，兼容数组写法 |

#### Response

- `response.Response{msg}`

#### 规则

- `ids` 与 `ids[]` 二选一。
- 删除策略为硬删，删除后记录不再保留在 `book_series` 表。

### 更新书籍系列

- Method：`PUT`
- Path：`/book/updateBookSeries`
- Handler：`BookSeriesApi.UpdateBookSeries`
- Service：`BookSeriesService.UpdateBookSeries`
- 审计：是

#### Request Body `book.BookSeries`

| 字段 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | uint | 是 | `> 0` | 系列 ID |
| name | string | 是 | 非空，最大长度 `128` | 系列名称 |
| coverUrl | string | 否 | 最大长度 `500` | 系列封面图片 URL |
| intro | string | 否 | 文本 | 系列简介 |
| isEnabled | bool | 否 | `true/false` | 系列是否启用 |

#### Response

- `response.Response{msg}`

#### 规则

- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
- 当前 Service 使用实体 `Save`，前端应传完整可编辑实体，避免未传字段被零值覆盖。
- `id` 不能为空；`name` 写入 `book_series.name`，数据库要求非空。

### 查询书籍系列详情

- Method：`GET`
- Path：`/book/findBookSeries`
- Handler：`BookSeriesApi.FindBookSeries`
- Service：`BookSeriesService.GetBookSeries`
- 审计：否

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | int | 是 | `> 0` | 系列 ID |

#### Response `bookRes.BookSeriesResponse`

| 字段 | 类型 | 说明 |
|:---|:---|:---|
| bookSeries | object | 书籍系列实体 |
| bookSeries.id | uint | 系列 ID |
| bookSeries.createdAt | time | 创建时间 |
| bookSeries.updatedAt | time | 更新时间 |
| bookSeries.name | string | 系列名称 |
| bookSeries.coverUrl | string | 系列封面图片 URL |
| bookSeries.intro | string | 系列简介 |
| bookSeries.isEnabled | bool | 系列是否启用 |

### 分页查询书籍系列列表

- Method：`GET`
- Path：`/book/getBookSeriesList`
- Handler：`BookSeriesApi.GetBookSeriesList`
- Service：`BookSeriesService.GetBookSeriesInfoList`
- 审计：否

#### Request Query `bookReq.BookSeriesSearch`

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
| keyword | string | 否 | 模糊匹配 `name` | 关键字 |
| name | string | 否 | 模糊匹配 `name` | 系列名称 |
| isEnabled | bool | 否 | `true/false` | 系列是否启用 |

#### Response `response.PageResult`

| 字段 | 类型 | 说明 |
|:---|:---|:---|
| list | array | `book.BookSeries` 列表 |
| list[].id | uint | 系列 ID |
| list[].createdAt | time | 创建时间 |
| list[].updatedAt | time | 更新时间 |
| list[].name | string | 系列名称 |
| list[].coverUrl | string | 系列封面图片 URL |
| list[].intro | string | 系列简介 |
| list[].isEnabled | bool | 系列是否启用 |
| total | int64 | 总数 |
| page | int | 当前页 |
| pageSize | int | 每页数量 |

#### 规则

- 列表默认排序：`id desc`。
- `keyword` 与 `name` 同时传入时，两个条件按 `AND` 叠加过滤。

## 规则

- admin 端书籍系列 CRUD 挂载在 `PrivateGroup`，统一需要 `JWT + Casbin`。
- 写操作挂载 `middleware.OperationRecord()`；读操作不挂操作审计。
- `isEnabled` 当前按实体和 SQL 使用 `bool`：`true` 表示启用，`false` 表示禁用。
- `book_series.name` 建普通索引，不定义唯一约束；接口不要求系列名称全局唯一。
- `book_series` 为硬删表，当前接口不提供软删除恢复能力。