
# 组卷系统对外开放文档 v1.0.0

## 1 规范说明

### 1.1 通信协议

HTTPS || HTTP协议

### 1.2 请求方法
本文档的接口遵循RESTful设计风格。

### 1.3 字符编码
HTTP通讯及报文BASE64编码均采用UTF-8字符集编码格式。

### 1.4 格式说明
元素出现要求说明：

符号				|说明
:----:			|:---
R				|报文中该元素必须出现（Required）
O				|报文中该元素可选出现（Optional）
C				|报文中该元素在一定条件下出现（Conditional）

### 1.5 报文规范说明

1. 报文规范仅针对交易请求数据进行描述；  

2. 报文规范中请求报文的内容为Https请求报文中RequestData值的明文内容；

3. 报文规范分为请求报文和响应报文。请求报文描述由发起方，响应报文由报文接收方响应。

### 1.6 请求报文结构
接口只接收两个参数 **RequestData** 和 **SignData** ，其中RequestData的值为请求内容，SignData的值为签名内容。

#### 1.6.1 参数说明
**RequestData（请求内容）：** 其明文为每次请求的具体参数，采用 JSON 格式，依次经过 DES 加密（以UTF-8编码、BASE64编码输出结果）和 URLEncode 后，作为 RequestData 的值。  

**SignData（签名内容）：** 请求参数（明文）的MD5加密字符串，用于校验RequestData是否合法。

#### 1.6.2 请求内容（RequestData）明文结构说明

采用JSON格式，其中包含Header（公有参数）、Body（私有参数）节点：

名称		|描述											|备注
:---	|:---											|:---
公共参数	|每个接口都包含的通用参数，以JSON格式存放在Header属性	|详见以下公共参数说明
私有参数	|每个接口特有的参数，以JSON格式存放在Body属性		    |详见每个接口定义

**公共参数说明：**

公共参数（Header）是用于标识产品及接口鉴权的参数，每次请求均需要携带这些参数：

参数名称				|类型		|出现要求	|描述  
:----				|:---		|:------	|:---	
authorization		|string		|R			|用户登录后token，没有登录则为空字符串

## 2. 接口定义

### 2.1 试题难度
- **接口说明：** 试题难度
- **接口地址：** /api/services/QuestionLibrary/QuestionBaseData/GetDifficulty

#### 2.1.1 请求参数

参数名称						 |类型		    |出现要求	|描述  
:----						 |:---		    |:------	|:---	
Header						 |&nbsp;		|R			|请求报文头
&emsp;authorization			 |string		|R			|用户登录后token，没有登录则为空字符串


请求示例：

```
{
    "Header":{
        "authorization":"",
    },
}

```


#### 2.1.2 返回结果

参数名称						    |类型		|出现要求	|描述  
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |array		|R			|&nbsp;
&emsp;name      			    |string		|R			|名称
&emsp;value             	    |string		|R			|ID

示例：

```
{
    "success":true,
    "error":null,
    "result":[{
        "name":'容易',
        "value":1,
    }]
}
```



### 2.2 学科信息
- **接口说明：** 学科信息
- **接口地址：** /api/services/QuestionLibrary/Discipline/GetList

#### 2.2.1 请求参数

参数名称						 |类型		    |出现要求	|描述
:----						 |:---		    |:------	|:---	
Header						 |&nbsp;		|R			|请求报文头
&emsp;authorization			 |string		|R			|用户登录后token，没有登录则为空字符串
Body						 |&nbsp;		|R			|&nbsp;
&emsp;EducationCategoryId 	 |int   		|O			|教育类别Id
&emsp;KeyWord            	 |string		|O			|学科名称
&emsp;SkipCount          	 |int   		|R			|开始记录数
&emsp;MaxResultCount    	 |int   		|R			|记录的条数

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "EducationCategoryId":null,
        "KeyWord":null,
        "SkipCount":0,
        "MaxResultCount":9999
    }
}

```


#### 2.2.2 返回结果

参数名称						    |类型		|出现要求	|描述
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |object		|R			|&nbsp;
&emsp;totalCount                |int	    |R			|总记录数
&emsp;items                     |array	    |R			|&nbsp;
&emsp;&emsp;id                  |int	    |R			|学科ID
&emsp;&emsp;name                |string	    |R			|学科名称
&emsp;&emsp;educationCategoryId |int	    |R			|教育类别Id
&emsp;&emsp;EducationCategory   |string	    |R			|教育类别名称


示例：

```
{
    "success":true,
    "error":null,
    "result":{
        "totalCount":1,
        "items":[{
            "id":10,
            "name":"数学",
            "educationCategoryId":4,
            "EducationCategory":"高中"
        }],
    }
}
```


### 2.3 教材信息
- **接口说明：** 教材信息
- **接口地址：** /api/services/QuestionLibrary/Textbook/GetList

#### 2.3.1 请求参数

参数名称						    |类型		    |出现要求	|描述
:----						    |:---		    |:------	|:---	
Header						    |&nbsp;		    |R			|请求报文头
&emsp;authorization			    |string		    |R			|用户登录后token，没有登录则为空字符串
Body						    |&nbsp;		    |R			|&nbsp;
&emsp;educationCategoryId       |int	        |O			|教育类别Id
&emsp;DisciplineId       	    |int   		    |O			|学科id
&emsp;IsActive            	    |bool  		    |O			|是否激活
&emsp;SkipCount          	    |int   		    |R			|开始记录数
&emsp;MaxResultCount    	    |int   		    |R			|记录的条数

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "EducationCategoryId":null,
        "DisciplineId":10,
        "IsActive":true,
        "SkipCount":0,
        "MaxResultCount":9999
    }
}

```


#### 2.3.2 返回结果

参数名称						    |类型		|出现要求	|描述
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |object		|R			|&nbsp;
&emsp;totalCount                |int	    |R			|总记录数
&emsp;items                     |array	    |R			|&nbsp;
&emsp;&emsp;id                  |int	    |R			|教材ID
&emsp;&emsp;name                |string	    |R			|教材名称
&emsp;&emsp;isActive            |bool	    |R			|是否激活
&emsp;&emsp;educationCategory   |string	    |R			|教育类别名称
&emsp;&emsp;disciplineId        |int	    |R			|学科ID
&emsp;&emsp;discipline          |string	    |R			|学科名称

示例：

```
{
    "success":true,
    "error":null,
    "result":{
        "totalCount":1,
        "items":[{
            "id":2,
            "name":"教材1",
            "isActive":4,
            "educationCategory":"高中",
            "disciplineId":10,
            "discipline":"数学"
        }],
    }
}
```

### 2.4 章节信息
- **接口说明：** 章节信息
- **接口地址：** /api/services/QuestionLibrary/Chapter/GetList

#### 2.4.1 请求参数

参数名称						    |类型		    |出现要求	|描述
:----						    |:---		    |:------	|:---	
Header						    |&nbsp;		    |R			|请求报文头
&emsp;authorization			    |string		    |R			|用户登录后token，没有登录则为空字符串
Body						    |&nbsp;		    |R			|&nbsp;
&emsp;ParentId                  |int	        |O			|父章节Id
&emsp;TextbookId       	        |int   		    |R			|教材id
&emsp;KeyWord            	    |string  		|O			|章节名称
&emsp;SkipCount          	    |int   		    |R			|开始记录数
&emsp;MaxResultCount    	    |int   		    |R			|记录的条数

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "ParentId":null,
        "TextbookId":2,
        "KeyWord":null,
        "SkipCount":0,
        "MaxResultCount":9999
    }
}

```


#### 2.4.2 返回结果

参数名称						    |类型		|出现要求	|描述
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |object		|R			|&nbsp;
&emsp;totalCount                |int	    |R			|总记录数
&emsp;items                     |array	    |R			|&nbsp;
&emsp;&emsp;id                  |int	    |R			|章节ID
&emsp;&emsp;name                |string	    |R			|章节名称
&emsp;&emsp;parentId            |int	    |R			|父章节Id
&emsp;&emsp;disciplineId        |int	    |R			|学科ID
&emsp;&emsp;discipline          |string	    |R			|学科名称
&emsp;&emsp;textbookId          |string	    |R			|教材id
&emsp;&emsp;textbook            |string	    |R			|教材名称
&emsp;&emsp;path                |string	    |R			|章节名称路径
&emsp;&emsp;hasChild            |true	    |R			|是否有子章节


示例：

```
{
    "success":true,
    "error":null,
    "result":{
        "totalCount":1,
        "items":[{
            "id":33,
            "name":"章节1",
            "parentId":null,
            "disciplineId":10,
            "discipline":"数学",
            "textbookId":2,
            "textbook":"教材1",
            "path":"章节1",
            "hasChild":true
        }],
    }
}
```

### 2.5 学科试题题型
- **接口说明：** 学科试题题型
- **接口地址：** /api/services/QuestionLibrary/DisciplineQuestionType/GetList

#### 2.5.1 请求参数

参数名称						    |类型		    |出现要求	|描述
:----						    |:---		    |:------	|:---	
Header						    |&nbsp;		    |R			|请求报文头
&emsp;authorization			    |string		    |R			|用户登录后token，没有登录则为空字符串
Body						    |&nbsp;		    |R			|&nbsp;
&emsp;disciplineId              |int	        |R			|学科id

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "disciplineId":10
    }
}

```


#### 2.5.2 返回结果

参数名称						    |类型		|出现要求	|描述
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |array		|R			|&nbsp;
&emsp;id                        |int	    |R			|试题题型Id
&emsp;name                      |string	    |R			|试题题型名称
&emsp;discipline                |string	    |R			|学科名称
&emsp;questionCategory          |string	    |R			|试题类别 代码定义请见“附录A 试题类别说明”
&emsp;questionType              |string	    |R			|试题类型


示例：

```
{
    "success":true,
    "error":null,
    "result":[{
        "id":18,
        "name":"单选题1",
        "discipline":"数学",
        "questionCategory":0,
        "questionType":"单选题"
    }]
}
```


### 2.6 知识点
- **接口说明：** 知识点
- **接口地址：** /api/services/QuestionLibrary/KnowledgePoint/GetList

#### 2.6.1 请求参数

参数名称						    |类型		    |出现要求	|描述
:----						    |:---		    |:------	|:---	
Header						    |&nbsp;		    |R			|请求报文头
&emsp;authorization			    |string		    |R			|用户登录后token，没有登录则为空字符串
Body						    |&nbsp;		    |R			|&nbsp;
&emsp;ParentId                  |int	        |O			|父知识点Id
&emsp;DisciplineId       	    |int   		    |O			|学科id
&emsp;CognitiveAbilityId       	|int   		    |O			|认知能力Id
&emsp;KeyWord            	    |string  		|O			|知识点名称
&emsp;SkipCount          	    |int   		    |R			|开始记录数
&emsp;MaxResultCount    	    |int   		    |R			|记录的条数

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "ParentId":null,
        "DisciplineId":10,
        "CognitiveAbilityId":null,
        "KeyWord":null,
        "SkipCount":0,
        "MaxResultCount":9999
    }
}

```


#### 2.6.2 返回结果

参数名称						    |类型		|出现要求	|描述
:----						    |:---		|:------	|:---	
success						    |bool		|R			|响应码，true为成功，false失败
error						    |string		|R			|&nbsp;
result						    |object		|R			|&nbsp;
&emsp;totalCount                |int	    |R			|总记录数
&emsp;items                     |array	    |R			|&nbsp;
&emsp;&emsp;id                  |int	    |R			|知识点ID
&emsp;&emsp;name                |string	    |R			|知识点名称
&emsp;&emsp;parentId            |int	    |R			|父知识点Id
&emsp;&emsp;disciplineId        |int	    |R			|学科ID
&emsp;&emsp;discipline          |string	    |R			|学科名称
&emsp;&emsp;cognitiveAbilityId  |string	    |R			|认知能力Id
&emsp;&emsp;cognitiveAbility    |string	    |R			|认知能力称
&emsp;&emsp;path                |string	    |R			|章知识点名称路径
&emsp;&emsp;hasChild            |true	    |R			|是否有子知识点


示例：

```
{
    "success":true,
    "error":null,
    "result":{
        "totalCount":1,
        "items":[{
            "id":110,
            "name":"三角函数的相关概念",
            "parentId":null,
            "disciplineId":10,
            "discipline":"数学",
            "cognitiveAbilityId":0,
            "cognitiveAbility":null,
            "path":"三角函数的相关概念",
            "hasChild":true
        }],
    }
}
```


### 2.7 试题列表
- **接口说明：** 试题列表
- **接口地址：** /api/services/QuestionLibrary/Question/GetList

#### 2.7.1 请求参数

参数名称						    |类型		    |出现要求	|描述
:----						    |:---		    |:------	|:---	
Header						    |&nbsp;		    |R			|请求报文头
&emsp;authorization			    |string		    |R			|用户登录后token，没有登录则为空字符串
Body						    |&nbsp;		    |R			|&nbsp;
&emsp;DisciplineId       	    |int   		    |R			|学科id
&emsp;QuestionTypeId       	    |int   		    |O			|题型Id
&emsp;DisciplineQuestionTypeId  |int   		    |O			|学科细分题型Id
&emsp;Difficulty            	|int      		|O			|试题难度 代码定义请见“附录B 试题难度说明”
&emsp;IsActive            	    |bool      		|O			|是否激活
&emsp;KnowledgePointIdList      |array<long>    |O			|知识点id
&emsp;ChapterId       	        |long   		|O			|章节id
&emsp;IncludeChildChapter       |bool   		|O			|是否包括子章节(默认包括)
&emsp;IncludeAncestor           |bool  		    |O			|是否包括父级知识点(默认不包括)
&emsp;StartAriseTime            |datetime   	|O			|出题年份(范围开始)
&emsp;EndAriseTime              |datetime  		|O			|出题年份(范围结束)
&emsp;KeyWord            	    |string  		|O			|试题简称
&emsp;SkipCount          	    |int   		    |R			|开始记录数
&emsp;MaxResultCount    	    |int   		    |R			|记录的条数

请求示例：

```

{
    "Header":{
        "authorization":"",
    },
    "Body":{
        "DisciplineId":10,
        "QuestionTypeId":null,
        "DisciplineQuestionTypeId":null,
        "Difficulty":null,
        "IsActive":null,
        "KnowledgePointIdList":null,
        "ChapterId":null,
        "IncludeChildChapter":true,
        "IncludeAncestor":false,
        "StartAriseTime":null,
        "EndAriseTime":null,
        "KeyWord":null,
        "SkipCount":0,
        "MaxResultCount":15
    }
}

```


#### 2.7.2 返回结果

参数名称						            |类型		|出现要求	|描述
:----						            |:---		|:------	|:---	
success						            |bool		|R			|响应码，true为成功，false失败
error						            |string		|R			|&nbsp;
result						            |object		|R			|&nbsp;
&emsp;totalCount                        |int	    |R			|总记录数
&emsp;items                             |array	    |R			|&nbsp;
&emsp;&emsp;id                          |int	    |R			|试题ID
&emsp;&emsp;shortName                   |string	    |R			|试题简称
&emsp;&emsp;analysis                    |string	    |R			|解析html
&emsp;&emsp;answer                      |string	    |R			|答案html
&emsp;&emsp;ariseTime                   |datetime	|R			|出题年份
&emsp;&emsp;chapter                     |string	    |R			|章节
&emsp;&emsp;checkPoints                 |string	    |R			|考点
&emsp;&emsp;convertFailMessage          |string	    |R			|转换失败信息
&emsp;&emsp;difficulty                  |string	    |R			|难度
&emsp;&emsp;discipline                  |string	    |R			|学科名称
&emsp;&emsp;disciplineId                |string	    |R			|学科ID
&emsp;&emsp;disciplineQuestionType      |string	    |R			|学科细分题型
&emsp;&emsp;disciplineQuestionTypeId    |int	    |R			|学科细分题型Id
&emsp;&emsp;html                        |string	    |R			|试题html
&emsp;&emsp;questionCategory            |int	    |R			|题型类别 代码定义请见“附录A 试题类别说明”
&emsp;&emsp;questionConvertState        |int	    |R			|试题转换状态 代码定义请见“附录C 试题转换状态说明”
&emsp;&emsp;questionType                |string	    |R			|题型名称
&emsp;&emsp;questionTypeId              |int	    |R			|题型Id
&emsp;&emsp;knowledgePoints             |array	    |R			|&nbsp;
&emsp;&emsp;&emsp;id                    |int	    |R			|知识点名称ID
&emsp;&emsp;&emsp;name                  |string	    |R			|知识点名称

示例：

```
{
    "success":true,
    "error":null,
    "result":{
        "totalCount":1,
        "items":[{
            "id":382,
            "shortName":"一幅完整的机械零件制图需包括的要素有( )｡",
            "analysis":"<html><head><style></style></head><body></body></html>",
            "answer":"A,B,C,D,E",
            "ariseTime":null,
            "chapter":"章节2",
            "checkPoints":null,
            "convertFailMessage":null,
            "difficulty":"较易",
            "discipline":"数学",
            "disciplineId":10,
            "disciplineQuestionType":"多选12",
            "disciplineQuestionTypeId":21,
            "html":"<html><head><style></style></head><body></body></html>",
            "questionCategory":0,
            "questionConvertState":0,
            "questionType":"选择题",
            "questionTypeId":1,
            "knowledgePoints":[{
                “id”:110,
                "name":"三角函数的相关概念"
            }]
        }]
    }
}
```


## 3 附录A 试题类别说明

响应码	|说明  
:----	|:---
0		|客观题
1		|判断题
2		|非客观题


## 4 附录B 试题难度说明

响应码	|说明
:----	|:---
1		|容易
2		|较易
3		|中等
4		|较难
5		|困难


## 5 附录C 试题转换状态说明

响应码	|说明
:----	|:---
0		|正常
1		|转换中
2		|转换失败
3		|解析替换失败