pjt222 编写验证文档
为计算机化系统创建完整的 IQ/OQ/PQ 验证文档。
适用场景
- 为受监管用途验证 R 或其他软件
- 准备法规审计
- 记录计算环境的确认
- 创建或更新验证协议和报告
输入
- 必填：待验证的系统/软件（名称、版本、用途）
- 必填：定义范围和策略的验证计划
- 必填：用户需求规范
- 可选：现有 SOP 模板
- 可选：以往验证文档（用于重新确认）
步骤
第 1 步：编写安装确认（IQ）协议
# 安装确认协议
**系统**：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）协议
# 操作确认协议
**文档 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）协议
# 性能确认协议
**文档 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 步：编写确认报告
执行协议后，记录结果：
# 安装确认报告
**文档 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 步：尽量自动化
创建生成证据的自动化测试脚本：
# 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— 输出验证方法