# 质控系统 UI 与 LLM 格式优化开发计划

> **版本：** v1.0  
> **创建日期：** 2026-02-08  
> **基于讨论：** 团队技术方案评审 + 产品原型对比分析  
> **决策确认：** 方案 A（渐进式改进）

---

## 一、背景与目标

### 1.1 现状问题

1. **LLM 格式问题**：当前使用简单 JSON 格式返回数据，LLM 理解力有限，容易产生幻觉
2. **UI 展示缺失**：管理端只有批量操作按钮，无法直观查看质控结果和录入进度
3. **入口层级深**：IIT 管理嵌套在运营管理端中，质控监控功能不够突出

### 1.2 参考文档

| 文档 | 路径 | 核心内容 |
|------|------|----------|
| CRA Agent 深度设计方案 | `docs/03-业务模块/IIT Manager Agent/01-需求分析/CRA Agent (临床监查) 深度设计与展现方案.md` | 变量分组、双层质控、临床切片格式 |
| 质控管理原型图 | `docs/03-业务模块/IIT Manager Agent/01-需求分析/质控管理原型图.html` | 风险热力图、统计卡片、智能诊断抽屉 |

### 1.3 目标

1. **提升 AI 回答准确性**：采用 XML 临床切片格式，减少 LLM 幻觉
2. **提升运营效率**：提供可视化质控驾驶舱，一眼看穿数据问题
3. **渐进式改进**：不破坏现有架构，逐步增强功能

---

## 二、详细评估表

### 2.1 团队方案 vs 当前代码对比

| 功能点 | 团队方案描述 | 当前状态 | 建议 |
|--------|-------------|---------|------|
| **1. 变量语义标签 (Tagging)** | 为变量打 `#demographics`, `#lab`, `#safety` 等标签，按需加载 | ❌ 未实现 | 🔴 **采纳** - 在 `iit_field_metadata` 表增加 `tags` 字段 |
| **2. 双层质控引擎** | Layer 1: HardRuleEngine, Layer 2: AI Logic Engine | ✅ Layer 1 已完成 | 🟡 Layer 2 可延后 |
| **3. 临床切片格式** | XML + Markdown 结构化提示词，对 LLM 更友好 | ❌ 使用简单 JSON | 🔴 **采纳** - 新增 `PromptBuilder.buildClinicalSlice()` |
| **4. 风险热力图** | 矩阵式受试者 × 访视/表单视图，颜色表示风险等级 | ❌ 未实现 | 🔴 **采纳** - 管理端新增驾驶舱页面 |
| **5. 统计卡片** | 数据质量分、严重违规数、Query 数、方案偏离数 | ❌ 未实现 | 🔴 **采纳** - 驾驶舱页面顶部 |
| **6. 智能诊断抽屉** | 左侧真实数据 + 右侧 AI 诊断，可操作（Query/确认/忽略） | ❌ 未实现 | 🟡 **简化采纳** - 先实现详情弹窗 |
| **7. LLM Trace 视图** | 展示发送给 LLM 的 Prompt 和思考过程 | ❌ 未实现 | 🟢 延后 - 调试阶段使用 |
| **8. 规则配置中心** | Layer 1/2/3 分层配置界面 | ✅ 已有质控规则页面 | ✅ 保持现有 |
| **9. AI 自动提取规则** | 上传 Protocol PDF 自动生成规则 | ❌ 未实现 | 🟢 延后 - 高级功能 |
| **10. qc_logs 审计轨迹** | 质控日志仅新增，保留历史记录 | ✅ 已实现 | ✅ 保持现有 |
| **11. record_summary 汇总** | 录入汇总表 upsert 模式 | ✅ 已实现 | ✅ 保持现有 |
| **12. pg-boss 防抖** | Webhook 去重机制 | ✅ 已实现 | ✅ 保持现有 |

### 2.2 LLM 格式对比

| 维度 | 当前 JSON 格式 | XML 临床切片格式 |
|------|---------------|-----------------|
| **Token 消耗** | 较多（括号、引号、嵌套） | 较少（语义化标签） |
| **LLM 理解力** | 一般（需要解析 JSON 结构） | 极强（医学叙事文本） |
| **上下文切割** | 困难（全量或无） | 简单（按 tag 切片） |
| **推理准确性** | 中等 | 高（有明确任务指令） |
| **调试友好度** | 一般 | 好（XML 结构清晰） |

**当前 JSON 格式示例：**

```json
{
  "projectName": "test0207",
  "stats": {
    "totalRecords": 13,
    "passedRecords": 0,
    "failedRecords": 13
  },
  "problemRecords": [
    {
      "recordId": "1",
      "status": "FAIL",
      "issues": [...]
    }
  ]
}
```

**XML 临床切片格式示例：**

```xml
<task>核查该患者是否符合研究入排标准</task>

<protocol_criteria>
    1. 年龄 16-35 岁。
    2. 月经周期规律（28±7天）。
    3. VAS 评分 ≥ 4 分。
    4. 签署知情同意书。
</protocol_criteria>

<patient_slice tag="#demographics, #screening">
    - 出生日期：2003-01-07（当前年龄 22 岁）✅
    - 月经周期：45 天 ⚠️ 超出范围
    - VAS 评分：未填写 ⚠️
    - 知情同意：未签署 ❌
</patient_slice>

<instruction>
请一步步推理，对比患者数据与标准。如发现异常，说明具体哪条标准被违反。
</instruction>
```

---

## 三、架构方案确认

### 3.1 方案 A（确认采用）

**核心思路：渐进式改进，增加"质控全览图"按钮**

```
运营管理端 → IIT 项目管理 → 项目详情页
                           │
                           ├── REDCap 配置 (Tab)
                           ├── 质控规则 (Tab)
                           ├── 通知设置 (Tab)
                           ├── 知识库 (Tab)
                           │
                           └── [⚡一键全量质控] [📊一键全量汇总] [🔍质控全览图]
                                                                    │
                                                                    ▼
                                                            全新页面（全屏驾驶舱）
                                                            /admin/iit-projects/:id/cockpit
```

**优势：**
1. 不破坏现有系统架构
2. 配置与监控职责分离
3. 全屏展示更多内容
4. 开发成本可控

### 3.2 驾驶舱页面布局

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ← 返回项目配置   test0207 - CRA 智能监查驾驶舱        ⚡全量质控  📄导出报告 │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐│
│  │ 总体数据质量分  │ │ 严重违规       │ │ 待确认 Query   │ │ 录入完成率     ││
│  │                │ │ (Critical)     │ │ (Major)        │ │                ││
│  │   0 /100      │ │   13 条        │ │   0 条         │ │   14%         ││
│  │ ████░░░░░░░░  │ │ 需立即处理     │ │                │ │ 7个表单/1个完成││
│  └────────────────┘ └────────────────┘ └────────────────┘ └────────────────┘│
├─────────────────────────────────────────────────────────────────────────────┤
│  受试者风险全景图 (Risk Heatmap)                                             │
│  ────────────────────────────────────────────────────────────────────────── │
│  🟢 无异常  🟡 疑问(Query)  🔴 严重违规  ⚪ 未开始                            │
│  ────────────────────────────────────────────────────────────────────────── │
│  记录ID │ 入组状态 │ 人口学信息 │ 病史诊断 │ 知情同意 │ 入排标准 │ CMSS │ ...│
│  ───────┼─────────┼───────────┼─────────┼─────────┼─────────┼──────┼─────│
│  1      │ 入组中  │    🟢     │   ⚪    │   🔴    │   🔴    │  ⚪  │  ⚪ │
│  2      │ 入组中  │    🟢     │   ⚪    │   🔴    │   🔴    │  ⚪  │  ⚪ │
│  3      │ 入组中  │    🟢     │   ⚪    │   🔴    │   🔴    │  ⚪  │  ⚪ │
│  ...    │ ...     │   ...     │  ...    │  ...    │  ...    │ ...  │ ... │
│  13     │ 入组中  │    🟢     │   ⚪    │   🔴    │   🔴    │  ⚪  │  ⚪ │
└─────────────────────────────────────────────────────────────────────────────┘
          │
          │ 点击红色单元格
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 侧滑抽屉：记录 1 - 入排标准详情                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│ 【质控问题】                                                                 │
│ ❌ 年龄不在 25-35 岁范围内（当前：22岁）                                      │
│ ❌ 月经周期不在 21-35 天范围内（当前：45天）                                   │
│ ❌ VAS 评分 < 4 分（当前：空值）                                              │
│ ❌ 未签署知情同意书                                                          │
│                                                                              │
│ 【原始数据】                                                                 │
│ age: 22 | menstrual_cycle: 45 | vas_score: null | informed_consent: 0       │
│                                                                              │
│ [发送 Query] [确认违规] [忽略]                                               │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 四、分阶段开发计划

### 阶段 1：LLM 格式优化（P0 - 优先级最高）

**目标：提升 AI 回答准确性，减少幻觉**

| 任务 | 描述 | 工作量 | 优先级 |
|------|------|--------|--------|
| 1.1 创建 PromptBuilder 类 | 实现 `buildClinicalSlice()` 方法，生成 XML 格式 | 2h | P0 |
| 1.2 修改 ChatService | 在质控查询时使用 PromptBuilder 格式化数据 | 1.5h | P0 |
| 1.3 添加自然语言摘要 | 返回结果增加 `summary` 字段，便于 LLM 直接引用 | 1h | P0 |
| 1.4 测试验证 | 企业微信端测试 AI 回答准确性 | 1h | P0 |

**技术实现：**

```typescript
// backend/src/modules/iit-manager/services/PromptBuilder.ts

export class PromptBuilder {
  /**
   * 构建 XML 临床切片格式
   */
  static buildClinicalSlice(params: {
    task: string;
    criteria: string[];
    patientData: Record<string, any>;
    tags?: string[];
    instruction?: string;
  }): string {
    const { task, criteria, patientData, tags = [], instruction } = params;
    
    return `
<task>${task}</task>

<protocol_criteria>
${criteria.map((c, i) => `  ${i + 1}. ${c}`).join('\n')}
</protocol_criteria>

<patient_slice${tags.length > 0 ? ` tag="${tags.join(', ')}"` : ''}>
${Object.entries(patientData)
  .map(([k, v]) => `  - ${k}: ${v ?? '未填写'}`)
  .join('\n')}
</patient_slice>

${instruction ? `<instruction>\n${instruction}\n</instruction>` : ''}
    `.trim();
  }

  /**
   * 构建质控结果摘要（自然语言）
   */
  static buildQcSummary(stats: {
    projectName: string;
    totalRecords: number;
    passRate: number;
    topIssues: Array<{ issue: string; count: number }>;
  }): string {
    const { projectName, totalRecords, passRate, topIssues } = stats;
    
    const issueText = topIssues
      .slice(0, 3)
      .map(i => `${i.issue}（${i.count}条）`)
      .join('、');

    return `项目 ${projectName} 共有 ${totalRecords} 条记录，` +
      `质控通过率 ${passRate.toFixed(1)}%。` +
      (topIssues.length > 0 ? `主要问题包括：${issueText}。` : '暂无质控问题。');
  }
}
```

---

### 阶段 2：管理端 UI 增强（P0）

**目标：提供可视化质控驾驶舱**

| 任务 | 描述 | 工作量 | 优先级 |
|------|------|--------|--------|
| 2.1 添加"质控全览图"按钮 | 在 IitProjectDetailPage 增加按钮 | 0.5h | P0 |
| 2.2 创建驾驶舱页面骨架 | IitQcCockpitPage.tsx + 路由配置 | 1h | P0 |
| 2.3 实现统计卡片组件 | 4 个卡片：质量分、违规数、Query 数、完成率 | 1.5h | P0 |
| 2.4 实现风险热力图组件 | 矩阵式表格，颜色表示风险等级 | 3h | P0 |
| 2.5 实现详情抽屉组件 | 点击单元格展示问题详情 | 2h | P1 |
| 2.6 后端 API：热力图数据 | 按记录×表单聚合质控状态 | 1.5h | P0 |

**新增文件清单：**

```
frontend-v2/src/modules/admin/
├── pages/
│   └── IitQcCockpitPage.tsx      # 驾驶舱主页面
├── components/
│   ├── QcStatCards.tsx            # 统计卡片组件
│   ├── RiskHeatmap.tsx            # 风险热力图组件
│   └── QcDetailDrawer.tsx         # 详情抽屉组件

backend/src/modules/admin/iit-projects/
├── iitQcCockpitController.ts      # 驾驶舱数据 API
└── iitQcCockpitRoutes.ts          # 路由定义
```

---

### 阶段 3：变量标签系统（P1）

**目标：支持按语义标签切片数据**

| 任务 | 描述 | 工作量 | 优先级 |
|------|------|--------|--------|
| 3.1 扩展数据库表 | `iit_field_metadata` 增加 `tags` 字段 | 0.5h | P1 |
| 3.2 管理端标签编辑 | 质控规则页面支持为字段打标签 | 2h | P1 |
| 3.3 REDCap 同步时自动打标签 | 根据表单名推断默认标签 | 1.5h | P2 |
| 3.4 PromptBuilder 按标签切片 | 只加载指定标签的字段 | 1h | P1 |

**数据库变更：**

```sql
-- 扩展 iit_field_metadata 表
ALTER TABLE iit_schema.field_metadata 
ADD COLUMN tags TEXT[] DEFAULT '{}';

-- 示例数据
UPDATE iit_schema.field_metadata 
SET tags = ARRAY['#demographics', '#screening']
WHERE field_name IN ('age', 'date_of_birth', 'sex');

UPDATE iit_schema.field_metadata 
SET tags = ARRAY['#consent', '#ethics']
WHERE field_name = 'informed_consent';
```

---

### 阶段 4：高级功能（P2 - 延后）

| 任务 | 描述 | 工作量 | 优先级 |
|------|------|--------|--------|
| 4.1 LLM Trace 视图 | 展示发送给 LLM 的 Prompt | 3h | P2 |
| 4.2 AI 自动提取规则 | 上传 Protocol PDF 自动生成规则 | 8h | P3 |
| 4.3 Layer 2 AI 逻辑引擎 | 复杂医学逻辑判断 | 10h | P3 |
| 4.4 导出监查报告 | 生成 PDF/Word 格式报告 | 4h | P2 |

---

## 五、开发优先级总结

| 优先级 | 阶段 | 核心任务 | 预计工时 |
|--------|------|----------|----------|
| **P0** | 阶段 1 | LLM 格式优化（PromptBuilder + ChatService） | 5.5h |
| **P0** | 阶段 2 | 管理端 UI（驾驶舱 + 统计卡片 + 热力图） | 9.5h |
| **P1** | 阶段 3 | 变量标签系统 | 5h |
| **P2** | 阶段 4 | 高级功能（延后） | 25h+ |

**MVP 阶段（阶段 1 + 2）总工时：~15 小时**

---

## 六、验收标准

### 6.1 阶段 1 验收 ✅ **已完成 (2026-02-08)**

- [x] 企业微信问"质控情况"，AI 回答格式清晰、无幻觉
- [x] AI 回答包含具体问题和记录数
- [x] 日志中可看到 XML 格式的 Prompt

**完成的文件：**
- `backend/src/modules/iit-manager/services/PromptBuilder.ts` - XML 临床切片格式构建器
- `backend/src/modules/iit-manager/services/ChatService.ts` - 集成 PromptBuilder，优化 LLM 格式

### 6.2 阶段 2 验收 ✅ **已完成 (2026-02-08)**

- [x] 点击"质控全览图"按钮可进入驾驶舱页面
- [x] 统计卡片正确显示质量分、违规数、完成率
- [x] 热力图正确显示记录×表单的质控状态
- [x] 点击红色单元格可查看问题详情

**完成的文件：**
- `frontend-v2/src/modules/admin/pages/IitQcCockpitPage.tsx` - 驾驶舱主页面
- `frontend-v2/src/modules/admin/pages/IitQcCockpitPage.css` - 驾驶舱样式
- `frontend-v2/src/modules/admin/components/qc-cockpit/QcStatCards.tsx` - 统计卡片组件
- `frontend-v2/src/modules/admin/components/qc-cockpit/RiskHeatmap.tsx` - 风险热力图组件
- `frontend-v2/src/modules/admin/components/qc-cockpit/QcDetailDrawer.tsx` - 详情抽屉组件
- `frontend-v2/src/modules/admin/types/qcCockpit.ts` - 类型定义
- `backend/src/modules/admin/iit-projects/iitQcCockpitService.ts` - 驾驶舱数据服务
- `backend/src/modules/admin/iit-projects/iitQcCockpitController.ts` - 驾驶舱 API 控制器
- `backend/src/modules/admin/iit-projects/iitQcCockpitRoutes.ts` - 驾驶舱路由

### 6.3 阶段 3 验收

- [ ] 字段可配置语义标签
- [ ] PromptBuilder 支持按标签过滤数据
- [ ] AI 查询时只加载相关字段

---

## 七、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 热力图数据量大 | 页面卡顿 | 分页加载、虚拟滚动 |
| XML 格式 Token 计算 | 超出 LLM 上下文限制 | 按标签切片、限制字段数 |
| REDCap 表单结构多变 | 热力图列不固定 | 动态渲染、表单配置 |

---

## 八、相关文档

| 文档 | 说明 |
|------|------|
| [06-实时质控系统开发计划.md](./06-实时质控系统开发计划.md) | 质控后端架构 |
| [CRA Agent 深度设计方案](../01-需求分析/CRA%20Agent%20(临床监查)%20深度设计与展现方案.md) | 技术方案参考 |
| [质控管理原型图](../01-需求分析/质控管理原型图.html) | UI 原型参考 |

---

**文档维护人：** AI Assistant  
**创建时间：** 2026-02-08  
**下次评审：** 阶段 1 完成后