# 素材库系统 — 完整 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
```