# 智能文献检索 DeepSearch 集成方案（MVP）

> **文档版本：** v1.2 MVP  
> **创建日期：** 2026-01-18  
> **维护者：** 开发团队  
> **模块位置：** ASL 模块 → 智能文献检索  
> **技术验证：** ✅ unifuncs DeepSearch API 已验证通过  
> **预计工期：** 3天

---

## 📋 MVP 范围

### 策略

| 层面 | 策略 | 理由 |
|------|------|------|
| **数据库** | 完整设计，所有字段都留 | 一次性到位，避免后续迁移 |
| **功能开发** | 只做核心，其他先不做 | 快速验证，减少工作量 |

### ✅ 本次开发

| 功能 | 说明 |
|------|------|
| 搜索输入框 | 自然语言输入 |
| 开始检索按钮 | 触发 unifuncs API |
| **思考过程展示** | **重点功能** - 实时展示 AI 检索思路 |
| 检索进度条 | 状态反馈 |
| 结果列表 | PMID、标题、作者、期刊、年份 |
| PubMed 链接 | 跳转原文 |

### 🔜 后续迭代

| 功能 | 说明 |
|------|------|
| 左侧检索历史 | 数据库已存，UI后做 |
| 导入到初筛 | 后续开发 |
| 高级筛选 | 年份、研究类型等 |
| 导出功能 | Excel、BibTeX |
| Token 统计展示 | 使用量统计 |

---

## 🏗️ 技术架构

```
┌─────────────────────────────────────────────────────────┐
│  前端：React + Ant Design + React Query                  │
│  - ResearchSearch.tsx（主页面）                          │
└─────────────────────────────────────────────────────────┘
                         ↓ HTTP
┌─────────────────────────────────────────────────────────┐
│  后端：Fastify + Prisma                                  │
│  - researchService.ts                                   │
│  - researchWorker.ts                                    │
│  - researchController.ts                                │
└─────────────────────────────────────────────────────────┘
                         ↓ pg-boss
┌─────────────────────────────────────────────────────────┐
│  unifuncs DeepSearch API（异步模式）                     │
│  - POST /v1/create_task                                 │
│  - GET  /v1/query_task                                  │
└─────────────────────────────────────────────────────────┘
```

---

## 💾 数据库设计（完整保留）

```prisma
// prisma/schema.prisma

/// 智能文献检索任务
model AslResearchTask {
  id               String   @id @default(cuid())
  
  // 关联
  projectId        String   @map("project_id")
  userId           String   @map("user_id")
  
  // 检索输入
  query            String                           // 用户的自然语言查询
  filters          Json?                            // 🔜 后续：高级筛选
  
  // unifuncs 任务
  externalTaskId   String?  @map("external_task_id")
  
  // 状态
  status           String   @default("pending")     // pending/processing/completed/failed
  errorMessage     String?  @map("error_message")
  
  // 结果
  resultCount      Int?     @map("result_count")
  rawResult        String?  @map("raw_result") @db.Text
  reasoningContent String?  @map("reasoning_content") @db.Text  // 思考过程
  literatures      Json?                            // 解析后的文献列表
  
  // 统计（🔜 后续展示）
  tokenUsage       Json?    @map("token_usage")
  searchCount      Int?     @map("search_count")
  readCount        Int?     @map("read_count")
  iterations       Int?
  
  // 时间
  createdAt        DateTime @default(now()) @map("created_at")
  updatedAt        DateTime @updatedAt @map("updated_at")
  completedAt      DateTime? @map("completed_at")
  
  @@map("asl_research_tasks")
  @@schema("asl_schema")
}
```

---

## 🔌 API 设计

### 本次开发（2个）

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/asl/research/tasks` | 创建检索任务 |
| `GET` | `/api/v1/asl/research/tasks/:taskId/status` | 获取状态+思考过程+结果 |

### 后续开发

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/asl/research/history` | 🔜 检索历史 |
| `POST` | `/api/v1/asl/research/tasks/:taskId/import` | 🔜 导入到初筛 |

---

## 🎨 前端设计

### 页面布局

```
┌─────────────────────────────────────────────────────────────┐
│ 智能文献检索                                                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ 🔍 输入您的研究问题，AI将自动在PubMed中检索...           ││
│ │                                                         ││
│ │ [                                                     ] ││
│ │                                                         ││
│ │                    [🚀 开始检索]                         ││
│ └─────────────────────────────────────────────────────────┘│
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ 💭 AI 思考过程                                 [展开 ▼] ││
│ ├─────────────────────────────────────────────────────────┤│
│ │ 用户查询："糖尿病 SGLT2抑制剂 心血管 RCT"                ││
│ │ 这是一个关于糖尿病药物的学术文献查询...                  ││
│ │                                                         ││
│ │ 📊 检索策略：                                           ││
│ │ 1. 核心关键词：SGLT2 inhibitors, cardiovascular         ││
│ │ 2. MeSH术语：Sodium-Glucose Transporter 2 Inhibitors    ││
│ │                                                         ││
│ │ 🔍 正在执行第 5/15 轮检索...                            ││
│ └─────────────────────────────────────────────────────────┘│
│                                                             │
│ ⏳ 检索进度                                                 │
│ ████████████████████░░░░░░░░░░ 65%                         │
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ 📚 检索结果 (15篇)                                      ││
│ ├─────────────────────────────────────────────────────────┤│
│ │ 1. PMID: 26378978                            [PubMed ↗] ││
│ │    Empagliflozin, Cardiovascular Outcomes...            ││
│ │    Zinman B, et al. | NEJM | 2015                       ││
│ ├─────────────────────────────────────────────────────────┤│
│ │ 2. PMID: 28605608                            [PubMed ↗] ││
│ │    Canagliflozin and Cardiovascular...                  ││
│ │    Neal B, et al. | NEJM | 2017                         ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

---

## 📁 文件结构

### 后端

```
backend/src/modules/asl/
├── controllers/
│   └── researchController.ts    # 2个API
├── services/
│   └── researchService.ts       # 核心逻辑
├── workers/
│   └── researchWorker.ts        # unifuncs轮询
└── routes/
    └── research.ts              # 路由配置
```

### 前端

```
frontend-v2/src/modules/asl/
├── pages/
│   └── ResearchSearch.tsx       # 主页面
└── api/
    └── research.ts              # API函数
```

---

## 📅 开发计划（3天）

| 天数 | 任务 | 产出 |
|------|------|------|
| **Day 1** | 数据库 + 后端 Service + Worker | Schema迁移 + 核心逻辑 |
| **Day 2** | 后端 Controller + 前端页面 | API + 页面框架 |
| **Day 3** | 思考过程展示 + 联调测试 | **重点：思考过程UI** |

---

## ✅ MVP 验收标准

- [ ] 用户可输入研究问题
- [ ] 点击"开始检索"后显示进度
- [ ] **思考过程实时展示**
- [ ] 检索完成后显示文献列表
- [ ] 文献可跳转到 PubMed

---

## 🔧 环境变量

```bash
# .env
UNIFUNCS_API_KEY=sk-xxx
```

---

**文档维护者**: 开发团队  
**最后更新**: 2026-01-18  
**文档状态**: ✅ MVP方案确认，开始开发