🐛 学习通答题

2025-12-11 16:49:02 +08:00
parent 24da8bde3a
commit d1b954ab8e
25 changed files with 4220 additions and 2636 deletions
@@ -0,0 +1,289 @@
+# AI 答题配置接口文档
+
+## 概述
+
+AI 答题功能用于在刷课过程中自动完成作业任务点。系统支持多种 AI 服务商，管理员可以通过配置接口设置 AI 参数。
+
+核心代码位于 `internal/application/quesbank` 包，提供通用的题库答题能力，可被不同平台（学习通、智慧教育等）复用。
+
+## 接口列表
+
+### 1. 获取支持的 AI 类型列表
+
+获取系统支持的所有 AI 类型及其说明。
+
+**请求**
+
+```
+GET /v1/system/ai-config/types
+```
+
+**响应**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "types": [
+      {
+        "type": "chatglm",
+        "name": "智谱AI (ChatGLM)",
+        "description": "智谱AI大模型，支持glm-4等模型",
+        "needUrl": false
+      },
+      {
+        "type": "xinghuo",
+        "name": "讯飞星火",
+        "description": "讯飞星火认知大模型",
+        "needUrl": false
+      },
+      {
+        "type": "tongyi",
+        "name": "通义千问",
+        "description": "阿里云通义千问大模型",
+        "needUrl": false
+      },
+      {
+        "type": "doubao",
+        "name": "豆包",
+        "description": "字节跳动豆包大模型",
+        "needUrl": false
+      },
+      {
+        "type": "openai",
+        "name": "OpenAI",
+        "description": "OpenAI GPT系列模型",
+        "needUrl": false
+      },
+      {
+        "type": "other",
+        "name": "其他 (兼容OpenAI格式)",
+        "description": "支持任何兼容OpenAI API格式的服务",
+        "needUrl": true
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 2. 获取当前 AI 配置
+
+获取当前系统配置的 AI 参数（API密钥会脱敏显示）。
+
+**请求**
+
+```
+GET /v1/system/ai-config
+```
+
+**响应**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "type": "chatglm",
+    "url": "",
+    "model": "glm-4",
+    "apiKey": "sk-1****************************xyz"
+  }
+}
+```
+
+**字段说明**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| type | string | AI类型，可选值见类型列表 |
+| url | string | API地址，仅 `other` 类型需要 |
+| model | string | 模型名称 |
+| apiKey | string | API密钥（脱敏显示） |
+
+---
+
+### 3. 更新 AI 配置
+
+更新系统的 AI 配置参数。
+
+**请求**
+
+```
+PUT /v1/system/ai-config
+```
+
+**权限**
+
+需要 `sys:ai:edit` 权限
+
+**请求体**
+
+```json
+{
+  "type": "chatglm",
+  "url": "",
+  "model": "glm-4",
+  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}
+```
+
+**参数说明**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | string | 是 | AI类型，可选值：`chatglm`, `xinghuo`, `tongyi`, `doubao`, `openai`, `other` |
+| url | string | 否 | API地址，当 type 为 `other` 时必填 |
+| model | string | 否 | 模型名称，不填则使用默认模型 |
+| apiKey | string | 是 | API密钥 |
+
+**各 AI 类型默认模型**
+
+| AI类型 | 默认模型 |
+|--------|----------|
+| chatglm | glm-4 |
+| xinghuo | generalv3.5 |
+| tongyi | qwen-plus |
+| doubao | 需指定 |
+| openai | gpt-3.5-turbo |
+| other | 需指定 |
+
+**响应**
+
+```json
+{
+  "code": 0,
+  "message": "AI配置更新成功"
+}
+```
+
+---
+
+### 4. 测试 AI 配置
+
+测试 AI 配置是否可用，发送测试消息验证连接。
+
+**请求**
+
+```
+POST /v1/system/ai-config/test
+```
+
+**权限**
+
+需要 `sys:ai:edit` 权限
+
+**请求体**
+
+```json
+{
+  "type": "chatglm",
+  "url": "",
+  "model": "glm-4",
+  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}
+```
+
+**响应**
+
+成功：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "success": true,
+    "message": "AI连接测试成功，响应: 测试成功..."
+  }
+}
+```
+
+失败：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "success": false,
+    "message": "AI连接测试失败: failed to execute request: ..."
+  }
+}
+```
+
+---
+
+## AI 服务商配置指南
+
+### 智谱AI (ChatGLM)
+
+1. 访问 [智谱AI开放平台](https://open.bigmodel.cn/)
+2. 注册并创建 API Key
+3. 配置参数：
+   - type: `chatglm`
+   - model: `glm-4` 或 `glm-3-turbo`
+   - apiKey: 你的 API Key
+
+### 讯飞星火
+
+1. 访问 [讯飞开放平台](https://www.xfyun.cn/)
+2. 创建应用并获取 API Key
+3. 配置参数：
+   - type: `xinghuo`
+   - model: `generalv3.5` 或其他版本
+   - apiKey: 你的 API Key
+
+### 通义千问
+
+1. 访问 [阿里云百炼](https://dashscope.aliyun.com/)
+2. 开通服务并获取 API Key
+3. 配置参数：
+   - type: `tongyi`
+   - model: `qwen-plus` 或 `qwen-turbo`
+   - apiKey: 你的 API Key
+
+### 豆包
+
+1. 访问 [火山引擎](https://www.volcengine.com/)
+2. 开通豆包大模型服务
+3. 配置参数：
+   - type: `doubao`
+   - model: 你的模型端点 ID
+   - apiKey: 你的 API Key
+
+### OpenAI
+
+1. 访问 [OpenAI Platform](https://platform.openai.com/)
+2. 创建 API Key
+3. 配置参数：
+   - type: `openai`
+   - model: `gpt-3.5-turbo` 或 `gpt-4`
+   - apiKey: 你的 API Key
+
+### 其他兼容服务
+
+支持任何兼容 OpenAI API 格式的服务（如 DeepSeek、Moonshot 等）。
+
+配置参数：
+- type: `other`
+- url: API 地址（如 `https://api.deepseek.com/v1/chat/completions`）
+- model: 模型名称
+- apiKey: 你的 API Key
+
+---
+
+## 使用说明
+
+1. 配置 AI 后，系统在执行刷课任务时会自动使用 AI 完成作业任务点
+2. 作业答案默认仅保存不提交，需要用户手动确认后提交
+3. 如果未配置 AI，作业任务点将被跳过
+4. 建议先使用测试接口验证配置是否正确
+
+## 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| 400 | 参数错误或配置不完整 |
+| 403 | 无权限操作 |
+| 500 | 服务器内部错误 |