PAS/.qoder/repowiki/zh/content/API端点参考/专利管理API/专利导入导出API/专利导入导出API.md

专利导入导出API

本文档引用的文件

• ImportTaskController.java
• ExportTaskDTO.java
• ImportTaskDTO.java
• PatentExportService.java
• PDFExportFirstPageService.java
• ImportTaskService.java
• ResponseEnum.java
• ExceptionEnum.java
• importTask.json
• importTaskConfig.json

目录

1. 简介
2. 核心API端点
3. 导入任务配置
4. 导出功能
5. 异步任务处理机制
6. 错误码说明
7. API使用示例
8. 附录

简介

本API文档详细描述了专利导入导出系统的功能，包括批量导入、导入状态查询和专利数据导出等核心功能。系统采用异步任务处理机制，支持多种数据源类型的导入和多种格式的导出，为用户提供灵活的专利数据管理能力。

核心API端点

系统提供了三个主要的API端点来支持专利导入导出功能：

• POST /importTask/create: 创建专利导入任务
• GET /importTask/status: 查询导入任务状态
• POST /export/patent: 创建专利数据导出任务

这些端点通过ImportTaskController和PatentController实现，采用RESTful设计风格，返回标准的JSON响应格式。

Section sources

• ImportTaskController.java
• PatentController.java

导入任务配置

导入任务通过ImportTaskDTO对象进行配置，该对象包含了导入任务的所有必要参数。

ImportTaskDTO参数说明

ImportTaskDTO是导入任务的核心数据传输对象，包含以下关键字段：

• importToId: 目标导入ID，指定导入到哪个专题库、报告或产品
• importToType: 导入目标类型，0表示专题库，1表示报告，2表示产品
• type: 导入类型，1表示Excel导入，2表示专利号导入，3表示专利号文件导入，4表示检索导入，5表示PDF文档导入
• ifUpdate: 是否更新现有数据
• searchCondition: 检索条件，用于检索导入场景
• fileGuid: 文件GUID，用于文件导入场景
• sourceId: Excel导入时使用的配置文件source_id
• DBType: 检索导入使用的数据库类型（中国或世界）
• fieldDTOS: 字段映射配置，定义数据源字段与系统字段的映射关系
• patentNos: 专利号列表，用于专利号导入场景
• productId: 产品ID，当导入到产品时使用
• updateCycle: 更新周期，用于定时导入任务
• optionType: 操作类型，0表示取消，1表示增加，2表示覆盖

去重规则

系统在导入过程中会自动处理重复数据。当ifUpdate参数为true时，系统会更新现有记录；当为false时，会跳过已存在的记录。对于专利号导入，系统会检查专利号的唯一性，避免重复导入相同的专利。

Section sources

• ImportTaskDTO.java
• importTaskConfig.json

导出功能

系统支持将专利数据导出为多种格式，包括Excel和PDF首页。

支持的导出格式

• Excel: 导出完整的专利信息，支持自定义字段选择
• PDF首页: 导出专利的PDF首页文档

自定义选项

导出功能支持高度自定义，用户可以通过PatentExportVO对象指定需要导出的字段。每个PatentExportVO包含以下属性：

• value: 字段名
• name: 字段中文名
• selected: 是否选择该字段
• type: 字段类型
• order: 字段顺序

用户可以自由选择需要导出的字段，并设置它们的显示顺序。

Section sources

• ExportTaskDTO.java
• PatentExportVO.java

异步任务处理机制

系统采用异步任务处理机制来处理耗时的导入导出操作，确保API响应的及时性。

任务生命周期

导入导出任务遵循以下生命周期：

1. 创建: 通过API创建任务，返回任务ID
2. 执行: 任务在后台异步执行
3. 状态更新: 任务执行过程中定期更新状态
4. 完成: 任务完成后更新最终状态和结果

进度查询方式

系统通过WebSocket和轮询两种方式提供进度查询：

• WebSocket: 实时推送任务进度更新
• 轮询: 通过查询接口获取任务状态

任务状态包括：

• 0: 待处理
• 1: 处理中
• 2: 完成
• 4: 暂停
• 5: 取消

进度信息通过ImportTaskAMVO对象提供，包含总条数(allNum)、完成条数(doneNum)和失败条数(defaultNum)等统计信息。

sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器"
participant Service as "服务层"
participant TaskManager as "任务管理器"
participant WebSocket as "WebSocket服务"
Client->>Controller : POST /importTask/create
Controller->>Service : 创建导入任务
Service->>TaskManager : 添加任务到队列
TaskManager-->>Service : 返回任务ID
Service-->>Controller : 返回成功响应
Controller-->>Client : 返回任务ID
loop 任务执行
TaskManager->>TaskManager : 处理任务
TaskManager->>WebSocket : 发送进度更新
WebSocket->>Client : 推送进度
end
TaskManager->>Service : 更新任务状态
Service->>TaskManager : 任务完成

Diagram sources

• ImportTaskService.java
• SchedulingTaskService.java
• MessageService.java

Section sources

• ImportTaskAMVO.java
• WebSocketMessageVO.java

错误码说明

系统定义了详细的错误码体系，用于处理各种异常情况。

主要错误码

错误码	错误信息	说明
202	参数错误	请求参数验证失败
203	检索式错误	检索条件格式错误
401	未登录	用户未登录或会话过期
500	系统异常	服务器内部错误
708	请求失败	业务逻辑处理失败
999999	系统异常	系统级异常

特定场景错误处理

文件格式错误

当上传的文件格式不符合要求时，系统会返回参数错误(202)或业务错误(708)。对于Excel文件，系统会验证文件结构和数据格式；对于PDF文件，会验证文件的完整性和可读性。

导入失败

导入失败可能由多种原因引起：

• 数据源连接失败
• 文件读取错误
• 数据格式不匹配
• 权限不足

系统会记录详细的错误日志，用户可以通过查询接口获取具体的错误信息。

导出超时

由于专利数据量可能很大，导出操作可能需要较长时间。系统设置了合理的超时机制：

• 短时间任务：5分钟超时
• 长时间任务：30分钟超时

当任务超时时，系统会自动终止任务并返回超时错误，同时保留已处理的数据。

Section sources

• ResponseEnum.java
• ExceptionEnum.java
• GlobalExceptionHandler.java

API使用示例

以下示例展示了如何使用API完成完整的导入导出流程。

创建导入任务

curl -X POST "http://localhost:8080/api/importTask/addImportTask" \
  -H "Content-Type: application/json" \
  -d '{
    "importToId": 123,
    "importToType": 0,
    "type": 1,
    "ifUpdate": true,
    "searchCondition": "",
    "fileGuid": "abc123",
    "sourceId": 1,
    "DBType": "CN"
  }'

查询导入状态

curl -X GET "http://localhost:8080/api/importTask/status?taskId=456"

创建导出任务

curl -X POST "http://localhost:8080/api/patent/exportPatentExcel" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 123,
    "EsVO": {
      "projectId": 123,
      "selectedFields": ["appNo", "title", "abstract"]
    }
  }'

完整流程示例

1. 创建导入任务，获取任务ID
2. 轮询查询任务状态，直到完成
3. 创建导出任务，指定需要导出的字段
4. 查询导出任务状态，获取结果文件GUID
5. 下载导出的文件

Section sources

• ImportTaskController.java
• PatentController.java

附录

状态码映射表

状态码	含义
0	待处理
1	处理中
2	完成
4	暂停
5	取消

任务类型映射表

类型	含义
1	Excel导入
2	专利号导入
3	专利号文件导入
4	检索导入
5	PDF文档导入
6	Excel导出
7	PDF首页导出