233 lines
6.7 KiB
Markdown
233 lines
6.7 KiB
Markdown
# 素材库系统 — 完整 API 文档
|
||
|
||
- 基础地址：`http://<主机>:16091`
|
||
- 数据格式：JSON（`Content-Type: application/json`）
|
||
- 文件上传：`multipart/form-data`
|
||
- 所有接口均为无鉴权访问（内网工具）；如需鉴权可自行在前面加网关
|
||
|
||
---
|
||
|
||
## 一、项目 Projects
|
||
|
||
### 1.1 项目列表
|
||
`GET /api/projects`
|
||
|
||
查询参数：
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `q` | 关键词（匹配名称/描述/标签） |
|
||
| `category` | 按类别过滤（精确） |
|
||
| `tags` | 按标签过滤（逗号分隔，多标签=同时满足 AND） |
|
||
|
||
响应：项目数组，每项含 `id, name, description, category, tags, created_at, updated_at, material_count, analyzed_count, analysis`（最新项目摘要）
|
||
|
||
### 1.2 新建项目
|
||
`POST /api/projects`
|
||
|
||
```json
|
||
{"name": "项目名", "description": "描述", "category": "市场资讯", "tags": "AI,行业"}
|
||
```
|
||
|
||
### 1.3 项目详情（含全部素材+分析）
|
||
`GET /api/projects/<id>`
|
||
|
||
响应：项目对象 + `materials` 数组（每个素材含抽取文本与最新 AI 分析）
|
||
|
||
### 1.4 修改项目
|
||
`PUT /api/projects/<id>`
|
||
```json
|
||
{"name": "新名", "description": "新描述", "category": "新类别", "tags": "新标签"}
|
||
```
|
||
（缺省字段保持原值）
|
||
|
||
### 1.5 删除项目（级联删素材+分析+文件）
|
||
`DELETE /api/projects/<id>`
|
||
|
||
### 1.6 项目摘要历史
|
||
`GET /api/projects/<id>/summaries`
|
||
|
||
响应：该项目全部项目级 AI 摘要（按时间倒序），每份含 `id, summary, key_points[], keywords[], tags[], category, created_at, model`
|
||
|
||
---
|
||
|
||
## 二、素材 Materials
|
||
|
||
### 2.1 批量上传文件
|
||
`POST /api/projects/<id>/materials/upload`
|
||
`multipart/form-data`，字段 `files`（可多个）
|
||
|
||
支持类型：文本(txt/md/csv/json/xml/srt/log/html) · 文档(pdf/docx/pptx) · 图片 · 视频 · 音频
|
||
|
||
响应：`{"results": [素材对象], "count": n}`；不支持的扩展名返回 `{"ok":false,"error":"..."}`
|
||
|
||
### 2.2 新增文本素材（粘贴内容）
|
||
`POST /api/projects/<id>/materials`
|
||
```json
|
||
{"name": "素材名", "content": "文本内容"}
|
||
```
|
||
|
||
### 2.3 素材详情
|
||
`GET /api/materials/<id>`
|
||
|
||
响应含：`name, mtype, file_path, file_size, ext, meta(宽高/格式), extracted_text, text_status, status, created_at, analysis`（最新素材级分析）
|
||
|
||
### 2.4 修改素材（改名 / 编辑文本内容）
|
||
`PUT /api/materials/<id>`
|
||
```json
|
||
{"name": "新名字", "content": "新内容", "mtype": "text"}
|
||
```
|
||
- `content` 有值时更新正文并**作废旧分析**（需重新分析）
|
||
- 缺省字段保持原值
|
||
|
||
### 2.5 删除素材
|
||
`DELETE /api/materials/<id>`
|
||
|
||
### 2.6 下载/预览素材文件
|
||
`GET /files/<material_id>`
|
||
- 图片/音视频：浏览器内预览；其它：下载
|
||
|
||
---
|
||
|
||
## 三、AI 分析 Analysis
|
||
|
||
### 3.1 分析单个素材
|
||
`POST /api/materials/<id>/analyze`
|
||
→ `{"ok": true, "task": "material:<project_id>"}`
|
||
后台执行，用任务接口轮询进度。
|
||
|
||
### 3.2 分析项目全部素材
|
||
`POST /api/projects/<id>/analyze`
|
||
→ `{"ok": true, "task": "material:<project_id>"}`
|
||
|
||
### 3.3 生成项目级 AI 摘要
|
||
`POST /api/projects/<id>/summary`
|
||
→ `{"ok": true, "task": "summary:<project_id>"}`
|
||
每次生成都会保留为一条历史记录。
|
||
|
||
### 3.4 任务进度查询
|
||
`GET /api/tasks/<key>`
|
||
→ `{"running": bool, "done": n, "total": n, "msg": "已分析 2/4", "error": null}`
|
||
|
||
---
|
||
|
||
## 四、搜索 Search
|
||
|
||
### 4.1 全文搜索
|
||
`GET /api/search?q=关键词`
|
||
- 项目匹配（名称/描述/标签 LIKE）
|
||
- 素材匹配（SQLite FTS5 + jieba 中文分词，索引含素材名/正文/AI摘要/关键词）
|
||
|
||
响应：`{"projects": [...], "materials": [...]}`
|
||
|
||
### 4.2 元数据/统计
|
||
`GET /api/meta`
|
||
响应：`{"categories": [{name,count}], "tags": [{name,count}], "stats": {projects, materials, analyzed}}`
|
||
|
||
---
|
||
|
||
## 五、设置 Settings
|
||
|
||
### 5.1 读取设置
|
||
`GET /api/settings`
|
||
响应（KV）：
|
||
```json
|
||
{
|
||
"llm_base_url": "https://api.deepseek.com",
|
||
"llm_api_key": "sk-...",
|
||
"llm_model": "deepseek-v4-flash",
|
||
"vision_base_url": "https://ark.cn-beijing.volces.com/api/plan/v3",
|
||
"vision_api_key": "ark-...",
|
||
"vision_model": "doubao-seed-evolving",
|
||
"backup_interval_hours": "24",
|
||
"backup_change_threshold": "50",
|
||
"backup_max_keep": "10",
|
||
"last_backup_time": "...",
|
||
"change_counter": "0"
|
||
}
|
||
```
|
||
|
||
### 5.2 保存设置
|
||
`PUT /api/settings`
|
||
传需要修改的字段即可（部分更新）。大模型/视觉接口改动**立即生效**，无需重启。
|
||
|
||
### 5.3 测试接口连接
|
||
`POST /api/settings/test`
|
||
```json
|
||
{"kind": "llm|vision", "base_url": "...", "api_key": "...", "model": "..."}
|
||
```
|
||
→ `{"ok": true, "reply": "..."}` 或 `{"ok": false, "error": "..."}`
|
||
|
||
---
|
||
|
||
## 六、备份 Backups
|
||
|
||
### 6.1 备份列表
|
||
`GET /api/backups`
|
||
→ `{"backups": [{name,size,time}], "last_backup_time": "...", "change_counter": "5"}`
|
||
|
||
### 6.2 手动立即备份
|
||
`POST /api/backup`
|
||
→ `{"ok": true, "name": "backup_20260827_100000_manual.zip"}`
|
||
备份包含完整数据库 + 上传目录，打包为 zip 存于 `data/backups/`
|
||
|
||
### 6.3 下载备份
|
||
`GET /api/backup/download/<文件名>`
|
||
|
||
### 6.4 删除备份
|
||
`DELETE /api/backup/<文件名>`
|
||
|
||
### 6.5 导入恢复备份
|
||
`POST /api/backup/restore`
|
||
`multipart/form-data`，字段 `file`（上传备份 zip）
|
||
|
||
⚠️ 会**覆盖当前全部数据**（数据库 + 上传目录），后台有任务运行时返回 409 拒绝。
|
||
|
||
---
|
||
|
||
## 七、自动备份触发规则
|
||
|
||
后台调度器每 30 秒检查一次，满足以下任一条件即自动备份：
|
||
1. **时间间隔**：距上次备份 ≥ `backup_interval_hours` 小时（0=关闭）
|
||
2. **变更量**：`change_counter`（项目/素材增删改次数）≥ `backup_change_threshold`（0=关闭）
|
||
|
||
备份后 `change_counter` 清零、`last_backup_time` 更新。保留份数 `backup_max_keep`，超出自动删除最旧备份。
|
||
|
||
---
|
||
|
||
## 八、错误码约定
|
||
|
||
| 情况 | 状态码 |
|
||
|------|--------|
|
||
| 参数/校验错误 | 400（`{"error": "..."}`） |
|
||
| 资源不存在 | 404 |
|
||
| 后台任务运行中（恢复备份） | 409 |
|
||
| 服务器内部错误 | 500 |
|
||
|
||
## 九、调用示例（curl）
|
||
|
||
```bash
|
||
# 新建项目
|
||
curl -X POST http://127.0.0.1:16091/api/projects \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"name":"调研","category":"研究","tags":"AI"}'
|
||
|
||
# 上传文件
|
||
curl -X POST http://127.0.0.1:16091/api/projects/1/materials/upload \
|
||
-F "files=@report.pdf" -F "files=@pic.png"
|
||
|
||
# 新增文本素材
|
||
curl -X POST http://127.0.0.1:16091/api/projects/1/materials \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"name":"笔记","content":"这是内容"}'
|
||
|
||
# 全文搜索
|
||
curl "http://127.0.0.1:16091/api/search?q=大模型"
|
||
|
||
# 分析项目全部素材 → 轮询任务
|
||
curl -X POST http://127.0.0.1:16091/api/projects/1/analyze
|
||
curl http://127.0.0.1:16091/api/tasks/material:1
|
||
|
||
# 立即备份
|
||
curl -X POST http://127.0.0.1:16091/api/backup
|
||
```
|