Write Validation Documentation

---
name: write-validation-documentation
description: >
  为受监管环境中的计算机化系统编写 IQ/OQ/PQ 验证文档。涵盖协议、
  报告、测试脚本、偏差处理和审批工作流程。适用于为受监管用途验证
  R 或其他软件、准备法规审计、记录计算环境确认，或为新系统或
  重新确认的系统创建和更新验证协议与报告时使用。
locale: zh-CN
source_locale: en
source_commit: 6f65f316
translator: claude-opus-4-6
translation_date: 2026-03-16
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: compliance
  complexity: advanced
  language: R
  tags: validation, iq-oq-pq, documentation, gxp, qualification
---

# 编写验证文档

为计算机化系统创建完整的 IQ/OQ/PQ 验证文档。

## 适用场景

- 为受监管用途验证 R 或其他软件
- 准备法规审计
- 记录计算环境的确认
- 创建或更新验证协议和报告

## 输入

- **必填**：待验证的系统/软件（名称、版本、用途）
- **必填**：定义范围和策略的验证计划
- **必填**：用户需求规范
- **可选**：现有 SOP 模板
- **可选**：以往验证文档（用于重新确认）

## 步骤

### 第 1 步：编写安装确认（IQ）协议

```markdown
# 安装确认协议
**系统**：R 统计计算环境
**版本**：4.5.0
**文档 ID**：IQ-PROJ-001
**编制人**：[姓名] | **日期**：[日期]
**审核人**：[姓名] | **日期**：[日期]
**批准人**：[姓名] | **日期**：[日期]

## 1. 目标
验证 R 及所需软件包已按规范正确安装。

## 2. 前提条件
- [ ] 服务器/工作站满足硬件要求
- [ ] 操作系统已确认
- [ ] 网络访问可用（用于软件包下载）

## 3. 测试用例

### IQ-001：R 安装
| 字段 | 内容 |
|------|------|
| 要求 | R 4.5.0 已正确安装 |
| 步骤 | 打开 R 控制台，执行 `R.version.string` |
| 预期结果 | "R version 4.5.0 (2025-04-11)" |
| 实际结果 | ______________________ |
| 通过/失败 | [ ] |
| 执行人 | ____________ 日期：________ |

### IQ-002：软件包清单
| 软件包 | 要求版本 | 已安装版本 | 通过/失败 |
|--------|---------|----------|---------|
| dplyr | 1.1.4 | | [ ] |
| ggplot2 | 3.5.0 | | [ ] |
| survival | 3.7-0 | | [ ] |

## 4. 偏差
[记录与预期结果的任何偏差及其解决方案]

## 5. 结论
[ ] 所有 IQ 测试通过——系统安装已验证
[ ] IQ 测试失败——请参见偏差章节
```

**预期结果：** `validation/iq/iq_protocol.md` 已完成，包含唯一文档 ID、目标、前提条件清单、R 安装和每个必需软件包的测试用例、偏差章节及审批字段。

**失败处理：** 若组织要求不同的文档格式，请调整模板以符合现有 SOP，但必须保留关键字段（要求、步骤、预期结果、实际结果、通过/失败）。

### 第 2 步：编写操作确认（OQ）协议

```markdown
# 操作确认协议
**文档 ID**：OQ-PROJ-001

## 1. 目标
验证系统在正常条件下正确运行。

## 2. 测试用例

### OQ-001：数据导入功能
| 字段 | 内容 |
|------|------|
| 要求 | 系统能正确导入 CSV 文件 |
| 测试数据 | validation/test_data/import_test.csv (MD5: abc123) |
| 步骤 | 执行 `read.csv("import_test.csv")` |
| 预期结果 | 包含 100 行 5 列的数据框 |
| 实际结果 | ______________________ |
| 证据 | 截图/日志文件引用 |

### OQ-002：统计计算
| 字段 | 内容 |
|------|------|
| 要求 | t 检验产生正确结果 |
| 测试数据 | 已知数据集：x = c(2.1, 2.5, 2.3), y = c(3.1, 3.5, 3.3) |
| 步骤 | 执行 `t.test(x, y)` |
| 预期结果 | t = -5.000, df = 4, p = 0.00753 |
| 实际结果 | ______________________ |
| 容差 | ±0.001 |

### OQ-003：错误处理
| 字段 | 内容 |
|------|------|
| 要求 | 系统能妥善处理无效输入 |
| 步骤 | 执行 `analysis_function(invalid_input)` |
| 预期结果 | 显示信息性错误消息，系统不崩溃 |
| 实际结果 | ______________________ |
```

**预期结果：** `validation/oq/oq_protocol.md` 包含数据导入、统计计算和错误处理的测试用例，每个用例均有具体测试数据、预期结果（在适用处含容差）和证据要求。

**失败处理：** 若测试数据尚不可用，创建具有已知属性的合成测试数据集，并记录数据生成方法以便独立验证结果。

### 第 3 步：编写性能确认（PQ）协议

```markdown
# 性能确认协议
**文档 ID**：PQ-PROJ-001

## 1. 目标
验证系统在真实数据和工作流程中按预期运行。

## 2. 测试用例

### PQ-001：端到端主要分析
| 字段 | 内容 |
|------|------|
| 要求 | 主要终点分析与参考结果一致 |
| 测试数据 | 盲态测试数据集（哈希值：sha256:abc...） |
| 参考结果 | 独立 SAS 计算（报告引用：SAS-001） |
| 步骤 | 执行完整分析流程 |
| 预期结果 | 估计值与参考值偏差在 ±0.001 以内 |
| 实际结果 | ______________________ |

### PQ-002：报告生成
| 字段 | 内容 |
|------|------|
| 要求 | 生成的报告包含所有必需章节 |
| 步骤 | 执行报告生成脚本 |
| 核查清单 | |
| | [ ] 含研究信息的标题页 |
| | [ ] 目录 |
| | [ ] 人口统计汇总表 |
| | [ ] 主要分析结果 |
| | [ ] 包含会话信息的附录 |
```

**预期结果：** `validation/pq/pq_protocol.md` 包含使用真实（或代表性）数据的端到端测试用例，结果与独立参考计算（如 SAS 输出）进行比较，容差已明确定义。

**失败处理：** 若独立参考结果不可用，记录此缺口并以双编程（两个独立 R 实现）作为替代验证方法，同时将 PQ 标记为临时状态，直至完成独立验证。

### 第 4 步：编写确认报告

执行协议后，记录结果：

```markdown
# 安装确认报告
**文档 ID**：IQ-RPT-001
**协议引用**：IQ-PROJ-001

## 1. 摘要
所有 IQ 测试用例于 [日期] 由 [姓名] 执行。

## 2. 结果摘要
| 测试 ID | 描述 | 结果 |
|---------|-----|------|
| IQ-001 | R 安装 | 通过 |
| IQ-002 | 软件包清单 | 通过 |

## 3. 偏差
未发现。

## 4. 结论
R 4.5.0 及相关软件包的安装已验证，满足所有规定要求。

## 5. 审批
| 角色 | 姓名 | 签名 | 日期 |
|------|------|------|------|
| 执行人 | | | |
| 审核人 | | | |
| 批准人 | | | |
```

**预期结果：** 确认报告（IQ、OQ、PQ）已完成，所有测试结果已填写，偏差已记录（或注明"未发现"），结论已陈述，审批签名字段已备妥。

**失败处理：** 若执行过程中出现测试失败，须将每次失败作为偏差记录，包含根本原因分析和解决方案。当观察到失败时，不得将偏差章节留空。

### 第 5 步：尽量自动化

创建生成证据的自动化测试脚本：

```r
# validation/scripts/run_iq.R
sink("validation/iq/iq_evidence.txt")
cat("IQ 执行日期：", format(Sys.time()), "\n\n")

cat("IQ-001：R 版本\n")
cat("结果：", R.version.string, "\n")
cat("状态：", ifelse(R.version$major == "4" && R.version$minor == "5.0",
                    "通过", "失败"), "\n\n")

cat("IQ-002：软件包版本\n")
required <- renv::dependencies()
installed <- installed.packages()
# ... 比较逻辑
sink()
```

**预期结果：** `validation/scripts/` 中的自动化脚本生成含时间戳的证据文件（如 `iq_evidence.txt`），记录每个测试用例的结果，减少手动录入并确保可重现性。

**失败处理：** 若自动化脚本因环境差异而失败，手动运行并使用 `sink()` 捕获输出。在确认报告中记录自动化与手动执行之间的差异。

## 验证清单

- [ ] 所有协议均有唯一文档 ID
- [ ] 协议引用了验证计划
- [ ] 测试用例有明确的通过/失败标准
- [ ] 报告包含所有已执行的测试结果
- [ ] 偏差已记录并附有解决方案
- [ ] 已获得审批签名
- [ ] 文档遵循组织的 SOP 模板

## 常见问题

- **验收标准模糊**："系统运行正常"无法测试，应指定确切预期值
- **缺少证据**：每个测试结果均需支持证据（截图、日志、输出文件）
- **偏差处理不完整**：所有失败均须记录、调查并解决
- **文档无版本控制**：验证文档和代码一样需要变更控制
- **忽略重新确认**：系统更新（R 版本、软件包更新）需要重新确认评估

## 相关技能

- `setup-gxp-r-project` — 已验证环境的项目结构
- `implement-audit-trail` — 电子记录追踪
- `validate-statistical-output` — 输出验证方法