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

> **版本**: 2.0  
> **日期**: 2026-01-25  
> **状态**: 规划中  
> **前置依赖**: Pandoc Word 导出已完成 ✅

---

## 一、设计目标

### 1.1 核心理念

```
"关键要素就绪 → 一键生成方案"
```

**解耦设计**：方案生成功能**不依赖** AI 对话流程。无论用户通过 AI 对话收集要素，还是手动填写要素，只要必填项完成即可生成。

### 1.2 用户场景

| 场景 | 用户行为 | 系统响应 |
|------|---------|---------|
| **场景 A** | 用户通过 AI 对话完成 5 阶段 | 自动提示可生成，点击生成 |
| **场景 B** | 用户手动填写关键要素 | 校验通过后，直接点击生成 |
| **场景 C** | 用户对生成内容不满意 | 针对某章节"讨论与优化" |

### 1.3 必填要素校验

| 要素 | 是否必填 | 说明 |
|------|---------|------|
| 科学问题 | ✅ 必填 | 方案的核心目的 |
| PICO | ✅ 必填 | 研究框架基础 |
| 研究设计 | ✅ 必填 | 决定方案结构 |
| 观察指标 | ✅ 必填 | 结局评价依据 |
| 样本量 | ⚪ 可选 | 可后续补充 |

**校验规则**：4/5 必填项完成 → 可生成基础方案

---

## 二、UI 架构设计

### 2.1 双阶段动态布局

```
┌─────────────────────────────────────────────────────────────┐
│                    Protocol Agent Page                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  阶段 A: 要素收集期                                          │
│  ┌─────────────────────────┬───────────────────────────┐    │
│  │      ChatPanel          │     ContextPanel          │    │
│  │        65%              │         35%               │    │
│  │                         │  ┌───────────────────┐    │    │
│  │   [AI 对话区域]         │  │ 科学问题 [✓][✏️]  │    │    │
│  │                         │  │ PICO     [✓][✏️]  │    │    │
│  │                         │  │ 研究设计 [✓][✏️]  │    │    │
│  │                         │  │ 样本量   [○]      │    │    │
│  │                         │  │ 观察指标 [✓][✏️]  │    │    │
│  │                         │  ├───────────────────┤    │    │
│  │                         │  │ 进度: 80% (4/5)   │    │    │
│  │                         │  │ [✨ 一键生成方案] │    │    │
│  │                         │  │ [📥 导出 Word]    │    │    │
│  │                         │  └───────────────────┘    │    │
│  └─────────────────────────┴───────────────────────────┘    │
│                         ↕ 拖拽手柄                           │
│                                                              │
│  阶段 B: 方案生成期                                          │
│  ┌───────────────────┬─────────────────────────────────┐    │
│  │   ChatPanel       │       DocumentPanel             │    │
│  │      35%          │           65%                   │    │
│  │                   │  ┌─────────────────────────┐    │    │
│  │ [正在撰写...]     │  │   [复制] [导出 Word]    │    │    │
│  │ 1. 研究背景 ✓     │  ├─────────────────────────┤    │    │
│  │ 2. 研究目的 ✓     │  │                         │    │    │
│  │ 3. 研究设计 ⟳     │  │   ══ A4 文档预览 ══     │    │    │
│  │                   │  │                         │    │    │
│  │ [修改指令输入]    │  │  1. 研究背景            │    │    │
│  │                   │  │     [讨论与优化]        │    │    │
│  │                   │  │     内容...             │    │    │
│  │                   │  │                         │    │    │
│  │                   │  │  2. 研究目的            │    │    │
│  │                   │  │     [讨论与优化]        │    │    │
│  │                   │  │     内容...             │    │    │
│  │                   │  │                         │    │    │
│  └───────────────────┴─────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 视图切换机制

```typescript
type ViewMode = 'context' | 'document';

// 切换条件
const shouldSwitchToDocument = (event: string) => {
  return event === 'GENERATION_STARTED';
};

// 布局比例
const LAYOUT_RATIO = {
  context: { chat: 65, right: 35 },
  document: { chat: 35, right: 65 },
};
```

### 2.3 视图切换按钮

顶部 Header 区域添加视图切换：
```
[视图: 关键要素] [视图: 完整方案]
```

---

## 三、功能模块详细设计

### 3.1 ContextPanel (要素面板) - 已有，需增强

**现有功能**：
- ✅ 五阶段卡片展示
- ✅ 完成状态编辑按钮
- ✅ 导出 Word 按钮

**需新增**：
1. **一键生成按钮位置调整**：移到面板顶部醒目位置
2. **生成条件提示**：显示 `已完成 4/5 必填项，可生成方案`
3. **手动添加要素入口**：未完成阶段也显示 [➕ 添加] 按钮

### 3.2 DocumentPanel (文档面板) - 新增

**核心功能**：
- A4 纸张预览效果（宋体、首行缩进、分节标题）
- 流式输出 + 打字机光标
- 分章节"讨论与优化"按钮
- 顶部工具栏：复制、导出 Word

**章节结构**：
```markdown
# 研究方案标题

## 1. 研究背景 (Background)
## 2. 研究目的 (Objectives)
## 3. 研究设计 (Study Design)
## 4. 研究对象 (Subjects)
## 5. 样本量估算 (Sample Size)
## 6. 研究实施步骤 (Implementation)
## 7. 观察指标 (Endpoints)
## 8. 数据管理与质量控制
## 9. 统计分析计划
## 10. 伦理与知情同意
## 11. 研究时间表
## 12. 参考文献
```

### 3.3 "讨论与优化" 功能

**交互流程**：
1. 用户点击某章节的 [讨论与优化] 按钮
2. 左侧 Chat 自动切换到"章节讨论模式"
3. AI 理解上下文，针对该章节进行对话
4. 用户可发送修改建议
5. AI 重新生成该章节内容
6. 右侧文档实时更新

**技术实现**：
```typescript
interface SectionContext {
  sectionId: string;           // 如 'background', 'objectives'
  sectionTitle: string;        // 如 '研究背景'
  currentContent: string;      // 当前内容
  conversationMode: 'section'; // 章节讨论模式
}
```

### 3.4 动态布局组件

```typescript
// ResizableSplitPane.tsx
interface ResizableSplitPaneProps {
  defaultRatio: number;        // 默认比例 (0-100)
  minRatio: number;            // 最小比例
  maxRatio: number;            // 最大比例
  onRatioChange: (ratio: number) => void;
  leftPanel: React.ReactNode;
  rightPanel: React.ReactNode;
}
```

---

## 四、开发计划 (分阶段)

### Phase 1: 核心功能 MVP (5天)

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 1 | 动态布局组件 | `ResizableSplitPane` + 视图切换按钮 |
| Day 2 | DocumentPanel 基础 | A4 预览 + 流式渲染 + 打字机效果 |
| Day 3 | 生成 API 对接 | 分章节流式生成 + 前后端联调 |
| Day 4 | 生成按钮 & 校验 | 必填项校验 + 双位置生成按钮 |
| Day 5 | 集成测试 & Bug Fix | 端到端测试 |

**Phase 1 交付标准**：
- [x] 用户可从 ContextPanel 点击生成
- [x] 方案在 DocumentPanel 流式展示
- [x] 布局可根据阶段自动切换
- [x] Word 导出功能正常

### Phase 2: "讨论与优化" (3天)

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 6 | 章节按钮 UI | 每个章节显示 [讨论与优化] 按钮 |
| Day 7 | 章节对话模式 | Chat 切换到章节讨论模式 + API |
| Day 8 | 章节重新生成 | 单章节流式更新 + 文档同步 |

**Phase 2 交付标准**：
- [x] 用户点击章节按钮，左侧进入讨论模式
- [x] AI 理解当前章节上下文
- [x] 重新生成的内容替换原章节

### Phase 3: 体验优化 (2天)

| 天数 | 任务 | 交付物 |
|------|------|--------|
| Day 9 | 手动添加要素 | 未完成阶段的 [➕ 添加] 入口 |
| Day 10 | 拖拽 & 记忆 | 拖拽手柄 + localStorage 记忆比例 |

---

## 五、技术要点

### 5.1 流式渲染方案

```typescript
// 使用现有 useAIStream hook
const { streamingContent, isStreaming } = useAIStream({
  onChunk: (chunk) => {
    // 实时更新 DocumentPanel
    updateDocumentContent(chunk);
  },
  onComplete: (fullContent) => {
    // 保存完整方案
    saveProtocol(fullContent);
  },
});
```

### 5.2 章节解析

```typescript
// 将流式 Markdown 解析为章节
const parseMarkdownSections = (markdown: string): Section[] => {
  const sections: Section[] = [];
  const regex = /^## (\d+)\. (.+)$/gm;
  // ... 解析逻辑
  return sections;
};
```

### 5.3 状态管理

```typescript
interface ProtocolGenerationState {
  viewMode: 'context' | 'document';
  layoutRatio: number;
  generationStatus: 'idle' | 'generating' | 'completed';
  currentSection: string | null;  // 当前讨论的章节
  sections: Section[];
  canGenerate: boolean;           // 基于必填项校验
}
```

---

## 六、文件结构

```
frontend-v2/src/modules/aia/protocol-agent/
├── components/
│   ├── ProtocolAgentPage.tsx      # 主页面 (修改)
│   ├── ChatPanel.tsx              # 聊天面板 (已有)
│   ├── StatePanel.tsx             # 要素面板 (修改)
│   ├── DocumentPanel.tsx          # 文档面板 (新增)
│   ├── ResizableSplitPane.tsx     # 可拖拽分栏 (新增)
│   ├── SectionRenderer.tsx        # 章节渲染器 (新增)
│   └── ViewSwitcher.tsx           # 视图切换器 (新增)
├── hooks/
│   ├── useProtocolGeneration.ts   # 方案生成 hook (新增)
│   └── useLayoutRatio.ts          # 布局比例 hook (新增)
├── styles/
│   ├── protocol-agent.css         # 主样式 (修改)
│   └── document-panel.css         # 文档面板样式 (新增)
└── types/
    └── index.ts                   # 类型定义 (修改)
```

---

## 七、风险与应对

| 风险 | 影响 | 应对措施 |
|------|------|---------|
| 长文档流式渲染性能 | 卡顿 | 虚拟滚动 + 分片渲染 |
| 章节解析复杂性 | 解析错误 | 规范化 Markdown 模板 |
| 布局切换体验 | 突兀 | CSS transition 平滑过渡 |

---

## 八、验收标准

### MVP (Phase 1)

- [ ] 4/5 必填项完成后，生成按钮可点击
- [ ] 点击生成后，自动切换到文档视图 (35:65)
- [ ] 文档以 A4 纸样式流式展示
- [ ] 生成完成后可导出 Word

### 完整版 (Phase 1+2+3)

- [ ] 每个章节有"讨论与优化"按钮
- [ ] 章节可单独重新生成
- [ ] 未完成阶段可手动添加要素
- [ ] 布局比例可拖拽调整并记忆

---

## 九、附录

### A. 参考原型

- `AIclinicalresearch/docs/03-业务模块/AIA-AI智能问答/00-系统设计/研究方案一键生成.html`

### B. 相关文档

- `UI_Layout_Ratio_Analysis.md` - 布局比例分析
- `基于对话流的文档生成与导出技术方案.md` - 技术方案

### C. 已完成依赖

- ✅ Pandoc 系统安装 (3.8.3)
- ✅ pypandoc Python 包
- ✅ Python `/api/convert/docx` 端点
- ✅ Node.js `ProtocolExportService`
- ✅ 前端导出按钮