# API 设计文档 所有接口前缀为 `/api/v1`，返回 JSON 格式数据。认证暂未启用（单用户环境）。 ## 1. AI 模型管理 (`/models`) ### 1.1 创建模型 `POST /models` **请求体**： ```json { "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": "..."}` ### 2.4 更新模板 HTML（编辑后保存） `PUT /templates/{id}/html` 请求体`{"html_content": "..."}` 后端将同步更新对应的 .docx 文件。 ### 2.5 下载最终文档 `GET /templates/{id}/download` 返回文件流（.docx）。 ## 3. 生成点管理 (`/generation-points`) ### 3.1 创建生成点 `POST /generation-points` ```json { "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` **响应**： ```json { "task_id": "uuid", "status": "pending" } ``` ### 4.2 查询任务状态 `GET /tasks/{task_id}` **响应**： ```json { "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`: 服务器内部错误 错误响应格式： ```json { "detail": "错误描述" } ```