# 题目更新接口文档

> 对应接口：`PUT /api/question/{id}`  
> 功能说明：更新题目信息，支持部分字段更新（只传需要修改的字段即可）  
> 接口版本：V1.0  
> 更新日期：2026-06-08

---

## 目录

- [1. 接口定义](#1-接口定义)
- [2. 请求参数](#2-请求参数)
- [3. 请求示例](#3-请求示例)
- [4. 响应说明](#4-响应说明)
- [5. 错误码说明](#5-错误码说明)
- [6. 边界情况说明](#6-边界情况说明)
- [7. curl 测试命令](#7-curl-测试命令)

---

## 1. 接口定义

| 项目 | 内容 |
|------|------|
| **请求方法** | `PUT` |
| **接口路径** | `/api/question/{id}` |
| **Content-Type** | `application/json` |
| **认证方式** | Bearer Token (JWT) |
| **基础URL** | `http://localhost:8080`（开发环境） |
| **完整URL示例** | `PUT http://localhost:8080/api/question/378` |

### 1.1 路径参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | String | **是** | 题目ID，支持两种格式：<br>① 自增数字ID（如 `378`）<br>② UUID格式的 questionId（如 `e6bb2566-90a8-4651-b553-083a1d695b3c`） |

### 1.2 认证要求

需要在请求头中携带 JWT Token：

```
Authorization: Bearer <token>
```

Token 通过 `/api/auth/login` 接口登录获取。

---

## 2. 请求参数

所有请求字段均为**可选**（部分更新），只传需要修改的字段即可。

### 2.1 请求体结构

```json
{
  "question_type": "single_choice",
  "difficulty": 3,
  "content": {
    "stem": "题目标题",
    "data": {},
    "answer": "A"
  },
  "tags": ["数学", "代数"],
  "score": 5.00,
  "status": "pending",
  "reviewer_comment": "审核意见",
  "document_id": "uuid-string",
  "document_name": "文件名.doc",
  "knowledge_base_path": "public/dept_1",
  "source_context": "原文上下文内容",
  "chunk_ids": ["chunk_001", "chunk_002"],
  "source_chunks_used": 3,
  "page_numbers": [12, 15]
}
```

### 2.2 字段详情

| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|---------|
| `question_type` | String | 否 | 题目类型 | 必须是以下之一：`single_choice`、`multiple_choice`、`true_false`、`fill_blank`、`subjective` |
| `difficulty` | Integer | 否 | 难度等级 | 1-5 |
| `content` | Object | 否 | 题目内容（JSON对象） | 不能为空的JSON对象 |
| `content.stem` | String | 视题型 | 题干 | 主观题必填 |
| `content.data` | Object | 视题型 | 额外数据（如选择题的选项列表） | - |
| `content.answer` | String | 视题型 | 答案 | 选择题为选项字母，判断题 "T"/"F" |
| `tags` | Array\<String\> | 否 | 知识点标签 | - |
| `score` | BigDecimal | 否 | 分值 | 范围：`-999.99` ~ `999.99`（数据库 decimal(5,2) 约束） |
| `status` | String | 否 | 审核状态 | `pending`、`approved`、`rejected` |
| `reviewer_comment` | String | 否 | 审核评论 | - |
| `document_id` | String | 否 | 关联文档ID | - |
| `document_name` | String | 否 | 文档名称 | - |
| `knowledge_base_path` | String | 否 | 知识库路径 | 最大500字符 |
| `source_context` | String | 否 | 原文上下文 | - |
| `chunk_ids` | Array\<String\> | 否 | 切片ID列表 | - |
| `source_chunks_used` | Integer | 否 | 使用的源切片数量 | - |
| `page_numbers` | Array\<Integer\> | 否 | 页码列表 | - |

---

## 3. 请求示例

### 3.1 修改题型和难度

```json
// PUT /api/question/378
{
  "question_type": "multiple_choice",
  "difficulty": 4
}
```

### 3.2 修改题目内容和分值

```json
// PUT /api/question/378
{
  "content": {
    "stem": "以下哪项是正确的？",
    "data": {
      "options": [
        { "label": "A", "text": "选项A" },
        { "label": "B", "text": "选项B" },
        { "label": "C", "text": "选项C" }
      ]
    },
    "answer": "B"
  },
  "score": 10.00
}
```

### 3.3 审核通过题目

```json
// PUT /api/question/378
{
  "status": "approved",
  "reviewer_comment": "内容正确，通过审核"
}
```

### 3.4 使用 UUID 更新

```json
// PUT /api/question/e6bb2566-90a8-4651-b553-083a1d695b3c
{
  "difficulty": 5,
  "score": 8.00
}
```

---

## 4. 响应说明

### 4.1 通用响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": "2026-06-08 10:00:00",
  "success": true
}
```

### 4.2 更新成功响应（code=200）

```json
{
  "code": 200,
  "message": "题目更新成功",
  "data": {
    "id": 378,
    "questionId": "41a890f2-c9b9-466f-b9f6-e0bd237329b7",
    "questionType": "multiple_choice",
    "difficulty": 4,
    "tags": null,
    "score": 5.00,
    "version": "1.0",
    "documentId": null,
    "excludeStems": null,
    "knowledgeBasePath": null,
    "sourceContext": null,
    "chunkIds": null,
    "sourceChunksUsed": 0,
    "examCount": 0,
    "correctCount": 0,
    "lastExamTime": null,
    "pageNumbers": null,
    "content": {
      "stem": "以下哪项是正确的？",
      "data": {
        "options": [
          { "label": "A", "text": "选项A" },
          { "label": "B", "text": "选项B" }
        ]
      },
      "answer": "A"
    },
    "status": "pending",
    "reviewerComment": null,
    "createdAt": "2026-06-08 09:00:00",
    "updatedAt": "2026-06-08 10:00:00",
    "isDeleted": 0
  },
  "timestamp": "2026-06-08 10:00:00",
  "success": true
}
```

### 4.3 data 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | Long | 自增主键ID |
| `questionId` | String | 题目UUID（全局唯一标识） |
| `questionType` | String | 题目类型 |
| `difficulty` | Integer | 难度等级 1-5 |
| `tags` | JsonNode | 知识点标签（JSON数组或null） |
| `score` | BigDecimal | 分值 |
| `version` | String | 版本号（默认"1.0"） |
| `documentId` | String | 关联文档ID |
| `excludeStems` | String | 题干内容（AI去重用） |
| `knowledgeBasePath` | String | 知识库路径 |
| `sourceContext` | String | 原文上下文 |
| `chunkIds` | JsonNode | 切片ID列表 |
| `sourceChunksUsed` | Integer | 使用切片数 |
| `examCount` | Integer | 出题次数 |
| `correctCount` | Integer | 正确次数 |
| `lastExamTime` | DateTime | 最后作答时间 |
| `pageNumbers` | JsonNode | 页码列表 |
| `content` | JsonNode | 题目内容（JSON对象） |
| `status` | String | 审核状态 |
| `reviewerComment` | String | 审核评论 |
| `createdAt` | DateTime | 创建时间 |
| `updatedAt` | DateTime | 最后更新时间 |
| `isDeleted` | Integer | 逻辑删除标志（0=正常，1=已删除） |

---

## 5. 错误码说明

### 5.1 业务错误码

| HTTP状态码 | code | message | 触发场景 |
|-----------|------|---------|---------|
| **200** | 200 | 题目更新成功 | 更新成功 |
| **404** | 404 | 题目不存在: {id} | 指定ID的题目不存在 |
| **400** | 400 | 分值超出范围，允许范围: -999.99 ~ 999.99 | score 超出 decimal(5,2) 精度范围 |
| **400** | 400 | 知识库路径过长，最大允许500字符 | knowledge_base_path 超过500字符 |
| **400** | 400 | 无效的题目类型: {type} | question_type 不在枚举值内 |
| **400** | 400 | 题目内容不能为空 | content 传了空对象 `{}` |
| **400** | 400 | 题目可能已被删除或归档 | 记录已被逻辑删除，updateById 影响行数为0 |
| **400** | 400 | 题目不存在 | getById 返回 null |

### 5.2 异常错误码

| HTTP状态码 | code | message | 触发场景 |
|-----------|------|---------|---------|
| **500** | 500 | 更新题目失败: {异常信息} | 数据库异常、JSON序列化异常等（Controller 兜底catch） |
| **401** | 401 | 用户未登录 | 未携带 Token 或 Token 无效 |
| **403** | 403 | 无权限访问 | 当前用户无操作权限 |

---

## 6. 边界情况说明

### 6.1 ID 格式自动识别

接口自动识别传入的 `{id}` 格式：

- **纯数字**（如 `378`）：按自增主键 `id` 查询
- **非数字**（如 `e6bb2566-...`）：按 `question_id`（UUID）查询
- **非法格式**：抛出 `NumberFormatException`，返回 400

### 6.2 部分更新机制

接口支持**部分字段更新**（PATCH 语义），请求体中只需包含要修改的字段：

- 未传的字段保持原值不变
- 传了 `null` 的字段会被设为 `null`
- `content` 为完整替换，非合并更新

### 6.3 防御性校验

Service 层对以下输入进行校验：

| 校验项 | 拦截条件 | 错误信息 |
|--------|---------|---------|
| score 范围 | `score > 999.99 \|\| score < -999.99` | "分值超出范围，允许范围: -999.99 ~ 999.99" |
| 路径长度 | `knowledge_base_path.length > 500` | "知识库路径过长，最大允许500字符" |
| 题型枚举 | `question_type ∉ validTypes` | "无效的题目类型: {type}" |
| 内容非空 | `content != null && content.isEmpty()` | "题目内容不能为空" |
| 存在性检查 | `getById(id) == null` | "题目不存在" |
| 更新影响行数 | `updateById 返回 false` | "题目可能已被删除或归档" |

### 6.4 逻辑删除

- 已逻辑删除的记录（`is_deleted = 1`）仍可通过 `getById` 查到
- 但 `updateById` 由于 MyBatis-Plus 自动追加 `WHERE is_deleted = 0` 条件，将返回 `false`
- 此时接口会抛出 `IllegalStateException`，返回 400 错误

### 6.5 JSON 序列化

- 后台使用 `JacksonTypeHandler` 将 `content` 字段序列化为 JSON 存入数据库
- 使用独立的 `ObjectMapper` 实例（非 Spring 管理的全局配置）
- 避免传入 `NaN`、`Infinity` 等非法 JSON 值，否则可能触发 `JsonProcessingException`

---

## 7. curl 测试命令

### 7.1 获取 Token

```bash
curl -X POST "http://localhost:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'
```

### 7.2 正常更新（数字ID）

```bash
curl -X PUT "http://localhost:8080/api/question/378" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "question_type": "multiple_choice",
    "difficulty": 4,
    "score": 5.00,
    "content": {
      "stem": "更新后的题干",
      "data": {
        "options": [
          {"label": "A", "text": "选项A"},
          {"label": "B", "text": "选项B"}
        ]
      },
      "answer": "A"
    }
  }'
```

### 7.3 使用 UUID 更新

```bash
curl -X PUT "http://localhost:8080/api/question/e6bb2566-90a8-4651-b553-083a1d695b3c" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"difficulty": 3}'
```

### 7.4 score 超出范围（测试防御性校验）

```bash
curl -X PUT "http://localhost:8080/api/question/378" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"score": 1000}'
# 期望响应: {"code": 500, "message": "更新题目失败: 分值超出范围，允许范围: -999.99 ~ 999.99"}
```

### 7.5 无效题型（测试防御性校验）

```bash
curl -X PUT "http://localhost:8080/api/question/378" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"question_type": "invalid_type"}'
# 期望响应: {"code": 500, "message": "更新题目失败: 无效的题目类型: invalid_type"}
```

### 7.6 不存在的题目

```bash
curl -X PUT "http://localhost:8080/api/question/99999" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"difficulty": 3}'
# 期望响应: {"code": 404, "message": "题目不存在: 99999"}
```