init: 初始化项目

2026-07-08 20:02:29 +08:00
parent 22590ae7b8
commit 1bb84df4ca
98 changed files with 8535 additions and 2 deletions
@@ -0,0 +1,103 @@
+# 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": "<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`
+```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": "错误描述"
+}
+```