4. 用户需求规格（URS）

说到用户需求规格，很多人第一反应是「写一堆文档给甲方看」。其实不完全是。URS 是整个验证流程的起点，也是你后续所有测试、验证、变更管理的基础。我个人习惯，在项目启动前就搭好 URS 框架，哪怕细节后面再填。

什么是 URS？说白了就是一份正式文档，用来定义「你希望生信流程能干什么、不能干什么、在什么环境下跑、跑成什么样算合格」。受监管环境下，URS 不是可选项，它是监管核查时翻出来的第一份材料。

4.1 URS 的定位与结构

URS 不是技术设计文档，也不是操作手册。它回答的是「为什么做」和「做到什么程度」，而不是「具体怎么实现」。你想想看，如果需求写得太细，反而限制了后续的设计空间。

我自己的 URS 模板一般长这样：

• 文档控制信息：编号、版本、作者、审批人、生效日期
• 项目背景与范围：这个流程用来解决什么问题
• 功能需求：输入、处理、输出、参数、异常处理
• 非功能需求：性能、安全、可用性、兼容性、数据完整性
• 监管合规需求：GDP、GLP、GCP、21 CFR Part 11 等
• 环境与接口需求：OS、硬件、依赖软件、上下游系统
• 可测性声明：每一条需求如何验证

我在项目中遇到过好几次，URS 写得像个研发方案，满篇都是「用 Python 3.9、调用 BWA、输出 BAM 文件」。这是误解。URS 应该写「给定 FASTQ 输入，流程应准确比对到参考基因组，输出比对结果文件」，具体用什么工具，那是设计规格的事。

4.2 功能需求怎么写

功能需求是 URS 里最见真功夫的部分。生信流程说白了就是一条数据流水线：输入数据 → 处理 → 输出结果。每一条功能需求都应该能映射到流水线上的某个环节。

举个例子，一个变异检测流程的 URS 功能需求可能长这样：

URS-FUNC-001：流程应支持双末端 FASTQ 格式输入。
URS-FUNC-002：流程应提供参考基因组索引配置接口。
URS-FUNC-003：流程应执行序列比对，输出 SAM/BAM 文件。
URS-FUNC-004：流程应完成碱基质量分数重校准（BQSR）。
URS-FUNC-005：流程应输出 VCF 格式的变异列表。
URS-FUNC-006：流程应支持用户指定的最小测序深度过滤参数。

如果你觉得这些太基本，那我加一条避坑经验：千万别忘了写异常处理需求。我曾经遇到一个流程，输入文件格式不规范就悄悄跳过不报错，导致下游分析全用了错误数据。那以后我每条 URS 都会加这两条：

URS-FUNC-007：流程在输入数据格式不正确时应终止运行并输出明确错误信息。
URS-FUNC-008：流程应在关键步骤失败时保留中间结果，以便调试。

4.3 非功能需求，被低估的成本

说实话，很多生信项目翻车都翻在非功能需求上。性能不够、内存溢出、磁盘写满、同一份数据不同批次跑出不同结果。这些在 URS 阶段不写清，后面全是坑。

我建议非功能需求至少覆盖以下几个方面：

类别	示例需求	验证方法示例
性能	处理 50× WGS 样本应在 48 小时内完成	基准测试 + 时间戳日志
可重复性	同一输入数据三次运行应输出完全一致的 VCF	MD5 校验或 diff 比较
数据完整性	传输过程中无数据损坏	校验和验证（md5sum）
并发	支持同时运行最多 10 个独立分析任务	压力测试 + 资源监控
审计追踪	所有参数变更和执行日志应被记录	审查日志文件完整性

我遇到过最典型的一个案例：团队花半年搭了一个肿瘤变异检测流程，URS 里性能需求写的「合理时间内完成」。结果验证时才发现，一个样本要跑 72 小时，根本赶不上临床报告周期。最后改需求、换工具、重验证，又拖了三个月。你想想看，如果当初 URS 里写清楚「48 小时内完成」，这些事在选工具阶段就能发现。

# 非功能需求示例：性能指标
URS-NFUNC-001：对于常规 WES（100×，FASTQ 共 20 GB），
               流程从原始数据到 VCF 输出的总运行时间不超过 24 小时。
URS-NFUNC-002：流程最大内存占用不超过 64 GB。
URS-NFUNC-003：临时存储需求不超过 500 GB，超过应提示用户。

4.4 监管合规需求的落地

受监管环境下，URS 里必须明确引用适用的法规条款。我这里列几个最常见的场景：

• 21 CFR Part 11：如果你要管理电子记录和电子签名，URS 里就要写清楚哪些步骤需要签名、哪些日志不可更改。
• GxP 数据完整性：ALCOA+ 原则，需求里要体现归属性、可读性、同步性、原始性、准确性。
• GDPR 或本地隐私法规：如果流程涉及患者数据，需要写匿名化、访问控制、数据保留期等需求。

写合规需求时，不要直接把法规条文复制粘贴。而是翻译成具体的系统行为。

URS-COMP-001：流程运行完成后应生成不可篡改的审计日志，
              日志内容包含启动时间、输入文件哈希、每一步的执行命令及退出状态。
URS-COMP-002：所有用户操作（启动、停止、修改参数）应记录
              操作者身份、操作时间、操作内容。
URS-COMP-003：VCF 结果文件应包含创建者的用户 ID 和时间戳元数据。

4.5 可测性——URS 的生命线

一条好的 URS 需求，标准很简单：一个测试人员看了，知道怎么设计测试用例来验证它。如果做不到，那就是需求写得太模糊。

我有个习惯，写完每条需求，心里默默过一遍「我怎么证明它是对的？」。比如：

• URS：「流程应正确识别变异。」 → 怎么定义「正确」？没法测。
• URS：「流程在 NA12878 基准样本上，SNP F1-score ≥ 0.99。」 → 能测，用已知突变的参考数据集。

这里强烈推荐在 URS 里单独开辟一节，叫「可测性声明」，把每一条需求的验证策略写出来。不用太详细，一句话就行。

URS-FUNC-005：流程应输出 VCF 格式的变异列表。
  → 验证方式：输入已知结果的参考样本，比对输出 VCF 的变异位点是否与预期一致。

4.6 URS 的版本管理与变更

URS 不是写一次就封存的。项目过程中需求会变，URS 就必须跟着变。但受监管环境下，改 URS 要走正式变更流程。

我建议在 URS 里设一个变更记录表：

版本	日期	变更内容	原因	变更人	审批人
1.0	2024-01-15	初始版本	项目启动	张三	李四
1.1	2024-02-10	URS-NFUNC-001 运行时间从 48h 改为 24h	临床报告周期需求变更	张三	李四
1.2	2024-03-01	新增 URS-COMP-004 关于数据匿名化	合规审计发现	王五	李四

每一版变更，都要重新走审批流程。这听起来繁琐，但审计时这是你证明「系统在受控状态下演进」的硬证据。

4.7 URS 的文档结构图

下面这张图展示了 URS 文档的核心组成和它们之间的关系。先定范围，再拆功能与非功能，再加合规约束，最后用可测性兜底。每一步都有输入输出，缺一不可。

4.8 常见避坑清单

最后，我把这些年踩过的坑浓缩成一张清单。写 URS 前过一遍，能省很多返工成本。

• 需求太多太细：把设计与需求混在一起。记住，URS 管「做什么」，设计文档管「怎么做」。
• 忽视边界条件：流程遇到空文件、非法字符、网络中断怎么办？这些必须写进 URS。
• 用「最好」「尽量」这类词：核查员直接打回。「应」「必须」「支持」才是 URS 该用的动词。
• 忽略输入输出规格：只说「支持 FASTQ」，不写「文件名后缀是什么、质量分格式是什么」，后面联调时一定会扯皮。
• 没写不可变需求：比如流程的参考基因组版本是固定的，不允许用户随意改。这种「锁死」的需求也要明确写出来。
• 版本控制流于形式：URS 改了但变更记录不更新，或者审批人写了但实际没审批。审计时这属于发现项。

嗯，大概就是这些。URS 的质量直接决定了验证流程的质量，花多少时间在上面都不为过。我一般写完 URS 会让业务方、开发、QA 三方坐下来过一遍，有时就过出意想不到的问题。早发现，都是赚的。