# PDF 书籍模块 WebAPI 接口文档

> 对应功能：PC 端《PDF 书籍阅读》页（FineUIPro.Web/HSSE/PDFDOC/PdfBookView.aspx）—— 多级章节目录 + 富文本正文维护。
> 服务项目：SGGL/WebAPI（经典 ASP.NET Web API，.NET Framework 4.8）；数据服务：SGGL/BLL/API/APIPdfBookService.cs。
> 数据表：Sys_PdfBook（书籍）/ Sys_PdfChapter（章节，目录层级用 ParentChapterId + Level(1章 2节 3小节)，同级用 SortNo 排序，正文 HTML 存 [Text]）。
> 状态：已实现并经本地 IIS Express 联调验证（2026-09）。

---

## 1. 通用约定

### 1.1 地址与路由

- 路由模板：api/{controller}/{action}/{id}，本模块控制器名为 **PdfBook**。
- 调用前缀示例：http://<host>/api/PdfBook/getBooks
- 只支持 JSON 输出（服务端已清除 XML 格式化器）；请使用 UTF-8 编码收发中文。

### 1.2 统一响应包装（Model.ResponeData）

所有接口返回同一结构：

| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | **1** = 成功；**0** = 失败（注：权限过滤返回的 code 为字符串 "0"） |
| message | string | 失败时的中文错误描述；成功为 null |
| data | object | 业务数据，失败为 null |

示例：

```json
{ "code": 1, "message": null, "data": { } }
```

### 1.3 字段命名

响应 JSON 键名与 C# 属性一致，采用 **PascalCase**（如 BookId、ChapterTitle），与全站既有 API 保持一致；请求 JSON 键名大小写不敏感（Newtonsoft 反序列化），文档示例统一小写开头书写。

### 1.4 鉴权

本模块接口按读/写区分权限（全局过滤器 WebAPI/Filter/TestPermissionAttribute.cs）：

| 类型 | 接口 | 鉴权 |
|---|---|---|
| 只读 | getBooks / getChapterTree / getChapter / searchChapter | **免登录**（已加入白名单，与 ProtectionStandards 等规范类只读接口一致） |
| 维护 | addBook / addChapter / editChapter / deleteChapter / saveContent | 需**登录态 + token 双重校验**（见下） |

维护接口调用步骤：

1. 先调登录接口获取 FormsAuth Cookie：
   POST /api/user/postLoginOn
   ```json
   { "Account": "jinkn", "Password": "xxxxxx" }
   ```
   成功后响应会写入名为 auth 的 Cookie（十年有效），后续请求须携带该 Cookie。
2. 请求头携带 token: <UserId>（Sys_User.UserId，登录响应 data.UserId 即该值）。
3. 二者缺一不可：缺 Cookie 或缺有效 token 均返回 {"code":"0","message":"您没有权限！"}。

---

## 2. 接口总览

| # | 方法 | 路径 | 说明 |
|---|---|---|---|
| 1 | GET | /api/PdfBook/getBooks | 书籍列表（含章节数） |
| 2 | GET | /api/PdfBook/getChapterTree?bookId= | 某本书多级章节目录树 |
| 3 | GET | /api/PdfBook/getChapter?chapterId= | 章节正文详情（HTML + 纯文本） |
| 4 | POST | /api/PdfBook/searchChapter | 章节关键词检索（可限定书籍） |
| 5 | POST | /api/PdfBook/addBook | 新增书籍（需登录） |
| 6 | POST | /api/PdfBook/addChapter | 新增章节（可指定父章节，需登录） |
| 7 | POST | /api/PdfBook/editChapter | 修改章节名称（需登录） |
| 8 | POST | /api/PdfBook/deleteChapter | 删除章节（连同全部子章节，需登录） |
| 9 | POST | /api/PdfBook/saveContent | 保存章节正文（富文本 HTML，需登录） |
---

## 3. 接口明细

### 3.1 书籍列表

GET /api/PdfBook/getBooks

无参数。返回按登记时间升序的全部书籍（与 PC 页下拉一致，第一本即页面默认选中书）。

响应示例（实测）：

```json
{
  "code": 1,
  "message": null,
  "data": [
    {
      "BookId": "BOOK_SAFE_20260827",
      "Title": "《施工现场安全防护手册》",
      "ChapterCount": 366,
      "CreateTime": "2026-09-03T10:30:49"
    },
    {
      "BookId": "BOOK_TEST_001",
      "Title": "《测试书籍-数据库连通》",
      "ChapterCount": 0,
      "CreateTime": "2026-09-04T15:50:30.39"
    }
  ]
}
```

data 数组元素字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| BookId | string | 书籍主键 |
| Title | string | 书名 |
| ChapterCount | int | 章节总数 |
| CreateTime | datetime? | 登记时间 |

### 3.2 章节目录树

GET /api/PdfBook/getChapterTree?bookId=BOOK_SAFE_20260827

| 参数 | 必填 | 说明 |
|---|---|---|
| bookId | 是 | 书籍主键 |

返回**多级嵌套树**：顶级节点数组，子章节在 Children 中递归（叶子章节 Children 为空数组），同级按 SortNo 排序。

响应示例（实测节选）：

```json
{
  "code": 1,
  "message": null,
  "data": [
    {
      "ChapterId": "BOOK_SAFE_20260827_C001",
      "ChapterTitle": "第一章 安全防护",
      "Level": 1,
      "PageStart": 0,
      "PageEnd": 0,
      "HasContent": false,
      "Children": [
        {
          "ChapterId": "BOOK_SAFE_20260827_C002",
          "ChapterTitle": "1.1三宝四口五临边",
          "Level": 2,
          "PageStart": 0,
          "PageEnd": 0,
          "HasContent": true,
          "Children": []
        },
        {
          "ChapterId": "BOOK_SAFE_20260827_C003",
          "ChapterTitle": "1.2三宝",
          "Level": 2,
          "PageStart": 0,
          "PageEnd": 0,
          "HasContent": false,
          "Children": [
            {
              "ChapterId": "BOOK_SAFE_20260827_C004",
              "ChapterTitle": "1.2.1安全帽",
              "Level": 3,
              "PageStart": 0,
              "PageEnd": 0,
              "HasContent": true,
              "Children": []
            }
          ]
        }
      ]
    }
  ]
}
```

data 节点字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| ChapterId | string | 章节主键（getChapter / saveContent 等接口用） |
| ChapterTitle | string | 章节名称 |
| Level | int | 层级：1=章，2=节，3=小节 |
| PageStart / PageEnd | int | 起止页码（手动维护模式无页码则为 0） |
| HasContent | bool | 该章节是否已录入正文（true 才建议作为可阅读节点） |
| Children | array | 子章节数组（叶子为 []） |

> 提示：与 PC 页交互一致——目录型节点（有子章节）自身通常无正文（HasContent=false），正文多录入在叶子章节。

### 3.3 章节正文详情

GET /api/PdfBook/getChapter?chapterId=BOOK_SAFE_20260827_C004

| 参数 | 必填 | 说明 |
|---|---|---|
| chapterId | 是 | 章节主键 |

响应示例（实测，Content 字段较长已省略）：

```json
{
  "code": 1,
  "message": null,
  "data": {
    "ChapterId": "BOOK_SAFE_20260827_C004",
    "BookId": "BOOK_SAFE_20260827",
    "BookTitle": "《施工现场安全防护手册》",
    "ChapterTitle": "1.2.1安全帽",
    "ParentChapterId": "BOOK_SAFE_20260827_C003",
    "Level": 3,
    "PageStart": 0,
    "PageEnd": 0,
    "Content": "<p>…安全帽在购买、日常检查时要检查如下内容…</p>",
    "ContentText": "1、安全帽在购买、日常检查时要检查如下内容： (1）安全帽如有下颊带，应使用宽度不小于10mm的织带…"
  }
}
```

- Content：富文本 HTML（UMeditor 生成）。2026-09 起页面上传图片在保存时转为 base64 内嵌（data:image/png;base64,...），正文自包含不依赖图片文件；个别历史数据仍可能是 res/umeditor 路径引用。WebView/rich-text 均可直接渲染 data URL；
- ContentText：去标签纯文本，适合列表摘要/全文展示；
- 章节不存在时返回 code=0、message=章节不存在或已被删除。

### 3.4 章节关键词检索

POST /api/PdfBook/searchChapter

请求体：

```json
{ "keyword": "安全帽", "bookId": "BOOK_SAFE_20260827" }
```

| 字段 | 必填 | 说明 |
|---|---|---|
| keyword | 是 | 检索关键词（正文纯文本 LIKE 字面匹配；% _ 通配符已转义） |
| bookId | 否 | 限定书籍；不传则全库检索 |

响应示例（实测，命中两章）：

```json
{
  "code": 1,
  "message": null,
  "data": [
    {
      "BookId": "BOOK_SAFE_20260827",
      "BookTitle": "《施工现场安全防护手册》",
      "ChapterId": "BOOK_SAFE_20260827_C002",
      "ChapterTitle": "1.1三宝四口五临边",
      "PageStart": 0,
      "PageEnd": 0,
      "Snippet": "1.三宝：是指安全帽、安全带、安全网…"
    },
    {
      "BookId": "BOOK_SAFE_20260827",
      "BookTitle": "《施工现场安全防护手册》",
      "ChapterId": "BOOK_SAFE_20260827_C004",
      "ChapterTitle": "1.2.1安全帽",
      "PageStart": 0,
      "PageEnd": 0,
      "Snippet": "1、安全帽在购买、日常检查时要检查如下内容…"
    }
  ]
}
```

- 匹配对象为 Sys_PdfChapter.[Text]（先剔除 HTML 标签再做 LIKE），命中片段取关键词前后各约 40 字；
- 说明：当前为字面匹配，未做分词/全文索引，后续可升级 SQL Server 全文检索。
---

### 3.5 新增书籍（需登录）

POST /api/PdfBook/addBook

请求体：

```json
{ "title": "《新书示例》", "createUser": "apitest" }
```

| 字段 | 必填 | 说明 |
|---|---|---|
| title | 是 | 书名 |
| createUser | 否 | 登记人，缺省 api |

响应：

```json
{ "code": 1, "message": null, "data": { "bookId": "PB202609051447346108" } }
```

新增书籍无章节；与 PC 页一致：FilePath=NULL、TotalPages=0、IndexStatus=2（手动维护）。

### 3.6 新增章节（需登录）

POST /api/PdfBook/addChapter

请求体：

```json
{ "bookId": "PB202609051447346108", "parentChapterId": "", "chapterTitle": "第一章 示例" }
```

| 字段 | 必填 | 说明 |
|---|---|---|
| bookId | 是 | 所属书籍主键 |
| parentChapterId | 否 | 父章节主键；**为空=顶级章节**；传入则挂到该章节下（层级=父级+1） |
| chapterTitle | 是 | 章节名称 |
| createUser | 否 | 预留 |

响应：

```json
{ "code": 1, "message": null, "data": { "chapterId": "CH20260905144734f549" } }
```

### 3.7 修改章节名称（需登录）

POST /api/PdfBook/editChapter

```json
{ "chapterId": "CH20260905144734ba08", "chapterTitle": "1.1 子章节(改名后)" }
```

成功响应：{ "code": 1, "data": true }；仅改名，不影响层级与正文。

### 3.8 删除章节（需登录，级联删除）

POST /api/PdfBook/deleteChapter

```json
{ "chapterId": "CH20260905144734f549" }
```

成功响应（实测：父章节带 1 个子章节，共删 2 条）：

```json
{ "code": 1, "message": null, "data": { "deletedCount": 2 } }
```

> 删除会递归收集该章节的**全部后代子章节**一并删除（与 PC 页删除章节及其子章节行为一致），请谨慎调用。

### 3.9 保存章节正文（需登录）

POST /api/PdfBook/saveContent

```json
{
  "chapterId": "CH20260905144734ba08",
  "content": "<p>安全帽验收接口测试正文：检查下颊带宽度。</p>"
}
```

成功响应：{ "code": 1, "data": true }；content 为 UMeditor 风格富文本 HTML，存 Sys_PdfChapter.[Text]。PC 页保存时会把本站上传图片引用转成 base64 内嵌，App/第三方提交的内容按原样存储。

---

## 4. 常见错误

| code | message | 场景 |
|---|---|---|
| 1 | - | 成功 |
| 0 | 书名不能为空 / 章节名称不能为空 / bookId 不能为空 / chapterId 不能为空 / keyword 不能为空 | 必填参数缺失 |
| 0 | 父章节不存在：xxx / 章节不存在：xxx / 章节不存在或已被删除 | 引用的数据不存在 |
| "0" | 您没有权限！ | 维护接口未携带 auth Cookie 或有效 token |
| "0" | 登录超出，请重新登录！ | 同上（过滤器另一分支文案，同为未授权） |

---

## 5. 附录

### 5.1 数据结构说明（SQL Server）

Sys_PdfBook：

| 列 | 说明 |
|---|---|
| BookId | 主键（PB+yyyyMMddHHmmss+4位随机，服务端生成） |
| Title | 书名 |
| IndexStatus | 2=手动维护（无自动索引流程） |
| CreateUser / CreateTime | 登记人 / 登记时间 |

Sys_PdfChapter：

| 列 | 说明 |
|---|---|
| ChapterId | 主键（CH+yyyyMMddHHmmss+4位随机，服务端生成） |
| BookId | 所属书籍 |
| ParentChapterId | 父章节，NULL=顶级 |
| Level | 1=章 2=节 3=小节（新增自动=父级+1） |
| ChapterTitle | 章节名称 |
| PageStart / PageEnd | 页码（手动维护为 NULL，接口输出 0） |
| Text | 正文富文本 HTML |
| SortNo | 同级排序（新增=全书 MAX+1） |

### 5.2 curl 调用示例（Windows；含中文的 JSON 请用文件方式 --data-binary 发送）

```bat
REM 1) 登录，保存 cookie（login.json 内容见 1.4）
curl -c cookies.txt -X POST -H "Content-Type: application/json" --data-binary "@login.json" http://localhost:7143/api/user/postLoginOn

REM 2) 只读（免登录）
curl "http://localhost:7143/api/PdfBook/getBooks"
curl "http://localhost:7143/api/PdfBook/getChapterTree?bookId=BOOK_SAFE_20260827"

REM 3) 维护（cookie + token 头）
curl -b cookies.txt -H "token: <UserId>" -X POST -H "Content-Type: application/json" --data-binary "@body.json" http://localhost:7143/api/PdfBook/saveContent
```

### 5.3 与 PC 页面（HSSE/PDFDOC/PdfBookView.aspx）的对应关系

| 页面操作 | 接口 |
|---|---|
| 页首书籍下拉（默认第一本） | getBooks |
| 左侧多级目录树 | getChapterTree |
| 点击叶子章节显示正文 | getChapter |
| 保存内容（富文本） | saveContent |
| 新增书籍弹窗 | addBook |
| 新增章节 / 编辑名称 / 删除章节（含子章节） | addChapter / editChapter / deleteChapter |

### 5.4 变更记录

| 日期 | 内容 |
|---|---|
| 2026-09-05 | 初版：新增 PdfBookController + APIPdfBookService，9 个接口全部经本地 IIS Express（http://localhost:7143）联调通过；只读接口加入权限白名单免登录 |
| 2026-09-05 | 页面富文本图片改为 base64 内嵌存储：保存内容时自动转换（getChapter 返回的 Content 中图片为 data URL） |