# 一键生成研究方案 - 开发计划

> **版本**: v1.1  
> **创建日期**: 2026-01-24  
> **最后更新**: 2026-01-24  
> **负责人**: AI Assistant  
> **状态**: 待开发

---

## 一、功能概述

### 目标
基于 Protocol Agent 收集的 5 个核心要素，一键生成完整的临床研究方案文档，支持在线编辑和 Word 导出。

### 核心价值
- 将 5-10 小时的方案撰写工作缩短至 30 分钟
- AI 生成 + 人工编辑，保证专业性和个性化
- 输出符合伦理委员会审查要求的标准文档

---

## 二、交互设计：两阶段渐进式生成

### 第一阶段：对话框生成摘要

```
用户点击"一键生成研究方案"
        ↓
AI 在对话框中流式输出研究方案摘要（约500字）
        ↓
用户确认摘要 → 进入第二阶段
用户不满意 → 在对话中继续调整要素
```

**摘要内容**：
- 研究题目
- 研究目的（主要/次要）
- 研究设计概述
- 样本量结论
- 主要结局指标

### 第二阶段：方案编辑器生成完整方案

```
用户点击"生成完整方案"
        ↓
跳转到方案编辑器页面
        ↓
流式生成完整研究方案（5000-8000字）
        ↓
用户在线编辑 / AI协作润色
        ↓
导出 Word 文档
```

---

## 三、研究方案结构

```markdown
# 临床研究方案

## 1. 研究题目
## 2. 研究背景与立题依据
## 3. 研究目的
## 4. 研究设计
## 5. 研究对象（纳入/排除标准）
## 6. 样本量估算
## 7. 研究实施步骤与技术路线
## 8. 观察指标
## 9. 数据管理与质量控制
## 10. 安全性评价
## 11. 统计分析计划
## 12. 伦理与知情同意
## 13. 研究时间表
## 14. 参考文献
```

---

## 四、方案编辑器设计

### 布局结构

```
┌────────────────────────────────────────────────────────────────┐
│  ← 返回    📄 研究方案编辑器    [自动保存✓]  [导出Word]  [发布] │
├──────────┬─────────────────────────────────────┬───────────────┤
│  📑 大纲  │         📝 编辑区                   │   🤖 AI助手   │
│          │                                     │               │
│  可点击   │  Notion 风格分块编辑                │  选中文本后： │
│  快速跳转 │  支持 Markdown + 富文本             │  - /ai 润色   │
│          │  Slash 命令 (/)                     │  - /ai 扩写   │
│          │  拖拽排序章节                        │  - /ai 精简   │
└──────────┴─────────────────────────────────────┴───────────────┘
```

### 核心功能

| 功能 | 说明 | 优先级 |
|------|------|--------|
| **Slash 命令** | 输入 / 唤起菜单，支持 /ai 调用生成 | P0 |
| **分块编辑** | 每个章节独立编辑，支持拖拽排序 | P0 |
| **大纲导航** | 左侧目录，点击跳转 | P0 |
| **自动保存** | 每30秒 + 失焦时保存 | P0 |
| **导出Word** | Tiptap JSON → docx | P0 |
| **AI润色** | 选中文本，/ai polish 优化 | P1 |
| **AI扩写** | 选中章节，/ai expand 补充 | P1 |
| **Ghost Text** | AI 生成时显示幽灵文字预览 | P1 |
| **版本历史** | 查看修改记录，回滚 | P2 |

---

## 五、技术方案

### 技术选型：Novel (Fork)

**选型结论**：Fork [Novel](https://github.com/steven-tey/novel) 源码，而非 npm 包引入。

**选择 Novel 的理由**：

| 因素 | Novel 优势 |
|------|-----------|
| **AI 原生** | 专为 AI 写作设计，已处理流式生成的 UX 细节（Ghost Text、光标锁定） |
| **标准 Tiptap** | 直接暴露 Tiptap 配置，可插入交互组件（样本量计算器、引用卡片） |
| **可控性** | 源码在手，100% 可定制 UI 和逻辑 |
| **对接成本** | 替换 useCompletion → useAIStream 即可对接现有后端 |

**Fork 策略**：

```
不要 npm install novel

将 novel/packages/core/src 复制到：
frontend-v2/src/shared/components/ProtocolEditor/

目录结构：
├── index.tsx              # 主组件
├── extensions/            # Tiptap 扩展
│   ├── ai-autocomplete.ts # 替换为 useAIStream
│   ├── slash-command.tsx  # 保留 Slash 菜单
│   ├── citation.ts        # Phase 2: 文献引用
│   └── medical-table.ts   # Phase 2: 复杂表格
├── components/            # UI 组件
│   ├── EditorContent.tsx
│   ├── SlashMenu.tsx
│   └── BubbleMenu.tsx
└── styles/                # 样式（处理 Tailwind 冲突）
    └── editor.css
```

**Tailwind CSS 冲突处理**：

```css
/* 方案：CSS 命名空间隔离 */
.novel-editor-scope {
  /* Novel 的 Tailwind 样式限制在此作用域 */
}
```

### 技术栈总览

```
前端编辑器：Novel (Fork) - 基于 Tiptap/ProseMirror
├── 优点：AI 原生、Notion 风格、源码可控
├── 核心：Slash 命令、Ghost Text、拖拽排序
│
AI 调用：复用现有 useAIStream Hook
├── 替换 Novel 的 useCompletion (Vercel AI SDK)
├── 对接 /api/v1/aia/protocol-agent/generate
│
文档导出：docx.js 或 @tiptap-pro/extension-export-docx
│
数据存储：PostgreSQL (protocol_generations 表)
```

### 数据模型

```sql
-- 方案生成记录表
CREATE TABLE protocol_generations (
  id UUID PRIMARY KEY,
  conversation_id UUID REFERENCES conversations(id),
  user_id UUID REFERENCES users(id),
  
  -- 内容
  summary TEXT,           -- 摘要（第一阶段）
  full_content JSONB,     -- 完整方案（Tiptap JSON，标准格式）
  
  -- 状态
  status VARCHAR(20),     -- draft | generating | completed
  version INT DEFAULT 1,
  
  -- 元数据
  word_file_url TEXT,     -- 导出的Word文件URL
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

### API 设计

```typescript
// 第一阶段：生成摘要（流式）
POST /api/v1/aia/protocol-agent/generate/summary
Request: { conversationId: string }
Response: SSE 流式输出摘要

// 第二阶段：生成完整方案（流式）
POST /api/v1/aia/protocol-agent/generate/full
Request: { conversationId: string }
Response: SSE 流式输出完整方案

// 保存编辑
PUT /api/v1/aia/protocol-agent/generation/:id
Request: { content: TiptapJSON }

// 导出Word
POST /api/v1/aia/protocol-agent/generation/:id/export
Response: { downloadUrl: string }

// AI编辑（润色/扩写）
POST /api/v1/aia/protocol-agent/generation/:id/ai-edit
Request: { 
  action: 'polish' | 'expand' | 'simplify',
  selectedText: string,
  context: string
}
Response: SSE 流式输出
```

---

## 六、开发计划

### Phase 1：Fork Novel + 对接后端（3天）

**目标**：3天内跑通"编辑器 + AI 流式生成"

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 1 | Fork Novel 源码 + 项目集成 | 编辑器基础渲染、Slash 菜单可用 |
| Day 2 | 替换 AI 调用 → useAIStream | /ai 命令可调用后端生成 |
| Day 3 | 摘要生成 API + 编辑器页面路由 | 完整的"对话→摘要→编辑器"流程 |

**Phase 1 交付**：
- ✅ Notion 风格编辑器可用
- ✅ /ai 命令可调用 Protocol Agent
- ✅ 支持 Markdown 导出

### Phase 2：完整方案生成 + Word 导出（3天）

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 4 | 完整方案生成 API（流式） | 编辑器中流式显示完整方案 |
| Day 5 | 自动保存 + 版本管理 | 数据库存储、草稿恢复 |
| Day 6 | Word 导出功能 | docx 文件下载 |

**Phase 2 交付**：
- ✅ 完整方案流式生成
- ✅ 自动保存
- ✅ Word 导出

### Phase 3：医疗特性增强（4天）

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 7 | 集成 Tiptap Table 扩展 | 复杂表格支持（访视排期表） |
| Day 8 | 开发 CitationBlock | 文献引用组件（对接 PKB） |
| Day 9 | AI 润色/扩写优化 | 选中文本 AI 编辑体验 |
| Day 10 | 测试 + UI 美化 | 完整功能测试 |

**Phase 3 交付**：
- ✅ 复杂表格支持
- ✅ 文献引用功能
- ✅ AI 协作编辑完善

---

## 七、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Tailwind CSS 冲突 | 样式混乱 | CSS 命名空间隔离 |
| Novel 源码维护成本 | 后续升级困难 | 代码量小(~2000行)，可独立维护 |
| LLM 生成质量不稳定 | 方案内容不专业 | 优化 Prompt + 人工模板 |
| 长文本生成超时 | 用户等待过久 | 分章节流式生成 |
| Word 导出格式问题 | 格式错乱 | 预设 Word 模板 |

### 依赖项

- [x] Protocol Agent 5阶段数据收集（已完成）
- [x] StreamingService 流式输出（已完成）
- [x] useAIStream Hook（已完成）
- [ ] Novel 源码 Fork（待执行）
- [ ] docx.js 导出功能（待开发）

### 兜底方案

如果 Fork 的 Novel 代码难以维护：
- 可回退到 **Tiptap Headless**
- 用 Ant Design 重写 UI
- **数据模型 (Tiptap JSON) 完全兼容**，用户数据不丢失

---

## 八、验收标准

### 功能验收

- [ ] 点击"一键生成"，对话框流式输出摘要
- [ ] 点击"生成完整方案"，跳转编辑器并流式生成
- [ ] 编辑器支持 Slash 命令 (/)
- [ ] 编辑器支持章节拖拽排序
- [ ] 选中文本可调用 AI 润色/扩写
- [ ] 可导出标准格式的 Word 文档
- [ ] 支持复杂表格编辑

### 性能指标

| 指标 | 目标 |
|------|------|
| 摘要生成时间 | < 30秒 |
| 完整方案生成时间 | < 3分钟 |
| 自动保存延迟 | < 1秒 |
| Word导出时间 | < 5秒 |

---

## 九、后续迭代

- **v1.1**: 方案模板库（不同研究类型）
- **v1.2**: 多人协作编辑
- **v1.3**: 方案审核流程
- **v1.4**: 与伦理系统对接

---

## 十、参考文档

- [Novel GitHub](https://github.com/steven-tey/novel)
- [Tiptap 官方文档](https://tiptap.dev/)
- [编辑器选型深度评估](./编辑器选型深度评估与落地建议.md)
- [Novel vs BlockNote 对比分析](./Novel_vs_BlockNote_深度对比分析.md)

---

**文档更新记录**：
- 2026-01-24 v1.0: 初始版本（技术选型：Tiptap/BlockNote）
- 2026-01-24 v1.1: 技术选型改为 **Novel (Fork)**，更新开发计划