zhouwentao/doc-forge-reborn

Fork 0

Files

T

zwt13703 1bb84df4ca init: 初始化项目

2026-07-08 20:02:29 +08:00

2.6 KiB

Raw Permalink Blame History

API 设计文档

所有接口前缀为 /api/v1，返回 JSON 格式数据。认证暂未启用（单用户环境）。

1. AI 模型管理 (`/models`)

1.1 创建模型

POST /models 请求体：

{
  "name": "GPT-4",
  "provider": "openai",
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "api_key": "sk-...",
  "extra_params": {"max_tokens": 1000, "temperature": 0.7},
  "is_enabled": true,
  "remark": "主模型"
}

响应：返回创建的模型对象（API Key 已加密）。

1.2 获取模型列表

GET /models?enabled=true&page=1&limit=20 响应：分页列表。

1.3 获取模型详情

GET /models/{id}

1.4 更新模型

PUT /models/{id}（字段同创建）

1.5 删除模型

DELETE /models/{id}

1.6 启用/禁用

PATCH /models/{id}/toggle
请求体{"is_enabled": false}

2. 模板管理 (`/templates`)

2.1 上传模板

POST /templates (multipart/form-data)
字段file (.docx), name (可选) 响应：模板对象（含生成的 HTML 内容）。

2.2 获取模板列表

GET /templates (分页)

2.3 获取模板 HTML 内容

GET /templates/{id}/html
返回{"html_content": "<html>..."}

2.4 更新模板 HTML（编辑后保存）

PUT /templates/{id}/html
请求体{"html_content": "<html>..."}
后端将同步更新对应的 .docx 文件。

2.5 下载最终文档

GET /templates/{id}/download
返回文件流（.docx）。

3. 生成点管理 (`/generation-points`)

3.1 创建生成点

POST /generation-points

{
  "template_id": "uuid",
  "position": {"start": 100, "end": 200},
  "prompt": "请根据参考文件生成一段总结",
  "model_id": "uuid (可选)",
  "ref_file": "file (multipart, 可选)"
}

响应：生成点对象。

3.2 获取模板的所有生成点

GET /generation-points?template_id={id}

3.3 更新生成点

PUT /generation-points/{id}（字段同创建）

3.4 删除生成点

DELETE /generation-points/{id}

4. 生成任务 (`/tasks`)

4.1 触发生成任务

POST /templates/{template_id}/generate
响应：

{
  "task_id": "uuid",
  "status": "pending"
}

4.2 查询任务状态

GET /tasks/{task_id}
响应：

{
  "id": "uuid",
  "status": "done",
  "result_file_path": "/path/to/result.docx",
  "error_msg": null,
  "created_at": "...",
  "finished_at": "..."
}

4.3 下载生成结果

GET /tasks/{task_id}/download
返回 .docx 文件流。

错误码规范

200: 成功
400: 请求参数错误
404: 资源不存在
500: 服务器内部错误错误响应格式：

{
  "detail": "错误描述"
}

2.6 KiB Raw Permalink Blame History Unescape Escape