Codex/service api restore config extras #8
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -118,7 +118,9 @@ curl -X POST http://localhost:19178/api/surveys/parse \ | |
|
|
||
| ```json | ||
| { | ||
| "error": "url 不能为空", | ||
| "code": "validation_error", | ||
| "message": "url 不能为空" | ||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -236,6 +238,18 @@ Accept: application/json | |
|
|
||
| 完整字段见 [数据结构](./schemas#runtimeconfig)。 | ||
|
|
||
| 也支持 Python 桌面端常用包络： | ||
|
|
||
| ```json | ||
| { | ||
| "config": { | ||
| "url": "https://www.wjx.cn/vm/example.aspx", | ||
| "target": 10, | ||
| "threads": 2 | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### 请求示例 | ||
|
|
||
| ```bash | ||
|
|
@@ -441,6 +455,121 @@ curl "http://localhost:19178/api/tasks/9f4c6b2b1a2d4e9f/logs?after=12&limit=100" | |
|
|
||
| `event` 字段来自 Go 结构体，目前没有 JSON 标签，所以返回字段是大写驼峰。 | ||
|
|
||
| ## 导出任务配置 | ||
|
|
||
| ```http | ||
| GET /api/tasks/{id}/config | ||
| ``` | ||
|
|
||
| 返回指定任务保存的运行配置 JSON，并设置附件下载响应头。 | ||
|
|
||
| ### 请求示例 | ||
|
|
||
| ```bash | ||
| curl -OJ http://localhost:19178/api/tasks/9f4c6b2b1a2d4e9f/config | ||
| ``` | ||
|
|
||
| ## 导出任务报告 | ||
|
|
||
| ```http | ||
| GET /api/tasks/{id}/report | ||
| ``` | ||
|
|
||
| 默认导出 JSON 报告。传 `?format=csv` 时导出日志 CSV。 | ||
|
|
||
| ### 请求示例 | ||
|
|
||
| ```bash | ||
| curl -OJ http://localhost:19178/api/tasks/9f4c6b2b1a2d4e9f/report | ||
| curl -OJ "http://localhost:19178/api/tasks/9f4c6b2b1a2d4e9f/report?format=csv" | ||
| ``` | ||
|
|
||
| ### JSON 返回字段 | ||
|
|
||
| | 字段 | 说明 | | ||
| |---|---| | ||
| | `task_id` | 任务 ID。 | | ||
| | `status` | 任务状态。 | | ||
| | `config` | 任务配置摘要。 | | ||
| | `progress` | 当前进度摘要。 | | ||
| | `error_code` | 标准化错误码。 | | ||
| | `failure_reason` | 失败原因。 | | ||
| | `terminal_stop_category` | 运行时终止类别。 | | ||
| | `logs` | 完整任务日志。 | | ||
|
|
||
| ## 导入兼容配置 | ||
|
|
||
| ```http | ||
| POST /api/configs/import | ||
| ``` | ||
|
|
||
| 导入并标准化运行配置。支持直接传 `RuntimeConfig`，也支持 `{ "config": ... }` 包络。旧配置中的私有业务字段会被忽略。 | ||
|
|
||
| ### 请求示例 | ||
|
|
||
| ```bash | ||
| curl -X POST http://localhost:19178/api/configs/import \ | ||
| -H "Content-Type: application/json" \ | ||
| -d "{\"config\":{\"url\":\"https://www.wjx.cn/vm/example.aspx\",\"target\":\"10\"}}" | ||
| ``` | ||
|
|
||
| ## 导出兼容配置 | ||
|
|
||
| ```http | ||
| POST /api/configs/export | ||
| ``` | ||
|
|
||
| 读取兼容配置后返回标准化 JSON 文件。 | ||
|
|
||
| ### 请求示例 | ||
|
|
||
| ```bash | ||
| curl -OJ -X POST http://localhost:19178/api/configs/export \ | ||
| -H "Content-Type: application/json" \ | ||
| -d "{\"url\":\"https://www.wjx.cn/vm/example.aspx\",\"target\":10}" | ||
| ``` | ||
|
|
||
| ## 测试 AI 连接 | ||
|
|
||
| ```http | ||
| POST /api/ai/test | ||
| ``` | ||
|
|
||
| 用于测试一组 AI 连接参数是否可用。SurveyCore 不内置免费 AI 私有服务链路；生产任务的 AI 默认值建议放在服务端 `configs/surveycore.toml`。 | ||
|
|
||
| ### 请求体 | ||
|
|
||
| ```json | ||
| { | ||
| "ai_provider": "custom", | ||
| "ai_api_key": "sk-...", | ||
| "ai_base_url": "https://api.example.com/v1", | ||
| "ai_api_protocol": "responses", | ||
| "ai_model": "example-model", | ||
| "question": "这是一个测试问题" | ||
| } | ||
| ``` | ||
|
|
||
| | 字段 | 类型 | 必填 | 说明 | | ||
| |---|---|---|---| | ||
| | `ai_provider` | `string` | 否 | `custom` 表示自定义 OpenAI 兼容服务。 | | ||
| | `ai_api_key` | `string` | 是 | AI API Key。 | | ||
| | `ai_base_url` | `string` | 否 | Base URL 或完整 endpoint。为空时使用默认 DeepSeek Base URL。 | | ||
| | `ai_api_protocol` | `string` | 否 | `auto`、`chat_completions` 或 `responses`。 | | ||
| | `ai_model` | `string` | 否 | 模型名。为空时使用默认模型。 | | ||
| | `ai_system_prompt` | `string` | 否 | 系统提示词。 | | ||
| | `question` | `string` | 否 | 测试问题。 | | ||
|
|
||
| ### 返回示例 | ||
|
|
||
| ```json | ||
| { | ||
| "ok": true, | ||
| "message": "AI 连接测试成功", | ||
| "preview": "连接成功" | ||
| } | ||
| ``` | ||
|
|
||
| ## 解析二维码 | ||
|
|
||
| ```http | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,11 +8,14 @@ outline: deep | |
|
|
||
| ```json | ||
| { | ||
| "error": "任务配置无效", | ||
| "code": "validation_error", | ||
| "message": "任务配置无效", | ||
| "detail": "url 不能为空" | ||
| } | ||
| ``` | ||
|
|
||
| 客户端应优先看 HTTP 状态码和 `code`，`detail` 只用于调试展示。 | ||
|
|
||
| ## 状态码 | ||
|
|
||
|
|
@@ -37,12 +40,20 @@ outline: deep | |
| | `POST /api/surveys/parse` | `502` | 问卷平台访问失败、链接不支持、问卷关闭、需要登录。 | | ||
| | `POST /api/configs` | `400` | JSON 无效、字段名错误。 | | ||
| | `POST /api/configs` | `502` | 传入 `url` 后解析问卷失败。 | | ||
| | `POST /api/configs/import` | `400` | JSON 无效或配置包络无效。 | | ||
| | `POST /api/configs/export` | `400` | JSON 无效或配置包络无效。 | | ||
| | `POST /api/tasks` | `400` | JSON 无效、字段名错误、任务保存失败。 | | ||
| | `GET /api/tasks` | `200` | 成功返回任务列表。 | | ||
| | `GET /api/tasks/{id}` | `404` | 任务 ID 不存在。 | | ||
| | `POST /api/tasks/{id}/stop` | `404` | 任务 ID 不存在。 | | ||
| | `GET /api/tasks/{id}/logs` | `400` | `after` 或 `limit` 参数不合法。 | | ||
| | `GET /api/tasks/{id}/logs` | `404` | 任务 ID 不存在。 | | ||
| | `GET /api/tasks/{id}/config` | `404` | 任务 ID 不存在。 | | ||
| | `GET /api/tasks/{id}/report` | `400` | `format` 参数不合法。 | | ||
| | `GET /api/tasks/{id}/report` | `404` | 任务 ID 不存在。 | | ||
| | `GET /api/tasks/{id}/report` | `500` | 日志读取或报告生成失败。 | | ||
| | `POST /api/ai/test` | `400` | JSON 无效或 AI 配置不完整。 | | ||
| | `POST /api/ai/test` | `502` | AI 上游连接失败。 | | ||
| | `POST /api/qrcode/decode` | `400` | 表单无效、缺少 `image` 文件、二维码无法解析出问卷链接。 | | ||
| | `POST /api/qrcode/decode` | `500` | 临时文件、文件读取或服务内部处理失败。 | | ||
|
|
||
|
|
@@ -65,39 +76,53 @@ outline: deep | |
|
|
||
| ```json | ||
| { | ||
| "error": "JSON 请求体无效", | ||
| "code": "invalid_json", | ||
| "message": "JSON 请求体无效", | ||
| "detail": "json: unknown field \"taskTarget\"" | ||
| } | ||
| ``` | ||
|
|
||
| URL 为空： | ||
|
|
||
| ```json | ||
| { | ||
| "error": "url 不能为空", | ||
| "code": "validation_error", | ||
| "message": "url 不能为空" | ||
| } | ||
| ``` | ||
|
|
||
| 日志游标错误： | ||
|
|
||
| ```json | ||
| { | ||
| "error": "日志查询参数无效", | ||
| "code": "invalid_query", | ||
| "message": "日志查询参数无效", | ||
| "detail": "日志游标必须是非负整数" | ||
| } | ||
| ``` | ||
|
|
||
| 日志条数错误： | ||
|
|
||
| ```json | ||
| { | ||
| "error": "日志查询参数无效", | ||
| "code": "invalid_query", | ||
| "message": "日志查询参数无效", | ||
| "detail": "日志条数必须是 1 到 1000 之间的整数" | ||
| } | ||
| ``` | ||
|
|
||
| 二维码文件缺失： | ||
|
|
||
| ```json | ||
| { | ||
| "error": "缺少 image 文件", | ||
| "code": "validation_error", | ||
| "message": "缺少 image 文件", | ||
| "detail": "http: no such file" | ||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -111,7 +136,9 @@ URL 为空： | |
|
|
||
| ```json | ||
| { | ||
| "error": "任务不存在", | ||
| "code": "not_found", | ||
| "message": "任务不存在" | ||
| } | ||
| ``` | ||
|
|
||
|
|
@@ -125,7 +152,10 @@ URL 为空： | |
|
|
||
| ```json | ||
| { | ||
| "error": "问卷解析失败", | ||
| "code": "upstream_error", | ||
| "message": "问卷解析失败", | ||
| "detail": "无法获取题目: 问卷已停止，无法作答" | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -42,6 +42,15 @@ async function createTaskFromURL(url) { | |
| async function getTask(taskID) { | ||
| return requestJSON(`/api/tasks/${taskID}`); | ||
| } | ||
|
|
||
| async function exportTaskReport(taskID) { | ||
| const response = await fetch(`${baseURL}/api/tasks/${taskID}/report`); | ||
| if (!response.ok) { | ||
| const data = await response.json(); | ||
| throw new Error(data.message || data.error || `HTTP ${response.status}`); | ||
| } | ||
| return response.json(); | ||
| } | ||
| ``` | ||
|
|
||
| ## Python | ||
|
|
@@ -75,6 +84,9 @@ task = request_json("POST", "/api/tasks", json=config) | |
| task_id = task["task_id"] | ||
|
|
||
| print(task_id) | ||
|
|
||
| report = request_json("GET", f"/api/tasks/{task_id}/report") | ||
| print(report["status"]) | ||
| ``` | ||
|
|
||
| ## 上传二维码 | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
导出报告应该是问卷平台的职责，而非 SurveyCore 要做的事？能够读取任务日志已经足够了导出配置在客户端做会更合适一些，服务端 SDK 进做接收配置、执行提交、返回状态的流程