📚 课程目录第4章报告需求分析与模板抽象

4. 报告需求分析与模板抽象

在生物实验自动报告工程中，最容易出问题的环节往往不是绘图或排版，而是需求没有说清楚。科研人员说“我要一份测序质控报告”，临床人员说“我要一份符合规范的检测报告”，质控人员说“我要能看出这批样本有没有漂移”，这三句话背后对应的字段、图表、结论口径和合规要求完全不同。本章的任务，就是把这些自然语言需求，转化为一份可复用的报告规格说明书。

一、先分清场景，再谈字段

报告需求分析的第一步不是列字段，而是识别场景。生物实验报告通常落在三类场景中：

科研场景：关注可重复性、原始数据可追溯、图表可再分析。字段常包括样本编号、实验批次、仪器型号、试剂批号、原始读数、归一化方法、统计检验结果。
临床场景：关注结果判读、参考区间、阴阳性判定、报告时限和可审计性。字段常包括患者标识（脱敏后）、样本类型、检测方法、检测限、参考范围、结果值、判定结论、审核人。
质控场景：关注过程稳定性、趋势和失控判断。字段常包括质控品批号、靶值、标准差、CV、Levey-Jennings 位置、Westgard 规则触发情况。

同一份实验数据，在三种场景下会生成三份不同的报告。因此，需求分析必须先把“谁看、看什么、看完要做什么决定”问清楚，再进入字段抽象。

二、从自然语言到结构化字段

把自然语言需求转成结构化模板，可以按“对象—属性—约束—呈现”四步走。以一句真实需求为例：

“我需要一份 qPCR 实验结果报告，能看出每个样本的 Ct 值、熔解曲线是否单峰，还要标出内参是否稳定，最后给出相对表达量。”

拆解后得到：

对象：样本、靶基因、内参基因、反应孔。
属性：Ct 值、熔解温度 Tm、熔解曲线峰数、内参 Ct 均值与标准差、相对表达量 2^-ΔΔCt。
约束：Ct > 35 视为未检出；熔解曲线峰数 ≠ 1 标记为可疑；内参 Ct 标准差 > 0.5 提示内参不稳定。
呈现：Ct 表格、熔解曲线图、内参稳定性条形图、相对表达量柱状图。

这四类信息一旦确定，模板的骨架就出来了。字段不是拍脑袋想的，而是从需求句子里“拆”出来的。

三、报告规格说明书的核心结构

一份可复用的报告规格说明书，建议包含以下部分：

模块	内容	示例
报告标识	报告名称、版本、适用场景	qPCR 相对表达量报告 v1.2 / 科研
输入数据	数据来源、文件格式、必需列	仪器导出 CSV，含 Well、Sample、Target、Ct、Tm
字段定义	字段名、类型、单位、是否必填、取值范围	Ct：浮点，无单位，必填，0–45
计算规则	归一化、统计、判定公式	ΔCt = Ct_靶 − Ct_内参；ΔΔCt = ΔCt_样本 − ΔCt_对照
图表规格	图表类型、X/Y 轴、分组、标注	柱状图：X=样本，Y=2^-ΔΔCt，误差棒=SD
结论规则	自动结论的触发条件与措辞	内参 SD > 0.5 → “内参稳定性不足，结果仅供参考”
合规要求	审计、脱敏、签名、留存	临床报告需审核人签名，原始数据留存 5 年

这张表本身就是规格说明书的目录。填写完成后，开发人员可以据此实现模板，实验人员可以据此核对报告是否完整。

四、需求到模板的转化路径

下图展示了从三类场景的自然语言需求，经过字段抽象、规则定义、图表映射，最终汇聚为一份可复用报告规格说明书的完整路径。图中同时标出了各场景特有的关键字段与合规约束，便于对照理解。

五、实操：写一份可执行的规格说明书

下面以 qPCR 相对表达量报告为例，给出一份可直接参考的规格说明书片段。示例参数为教学假设，实际使用时需按实验室 SOP 调整。

报告名称：qPCR 相对表达量报告
版本：v1.2
适用场景：科研（可扩展至临床前验证）

输入数据：
  文件格式：CSV（仪器导出）
  必需列：Well, Sample, Target, Ct, Tm, PeakCount
  可选列：Replicate, Batch, Operator

字段定义：
  Sample      字符串  必填  样本编号
  Target      字符串  必填  靶基因/内参基因名称
  Ct          浮点    必填  0–45，>35 标记为未检出
  Tm          浮点    必填  熔解温度，单位 ℃
  PeakCount   整数    必填  熔解曲线峰数，≠1 标记可疑
  RefCt_SD    浮点    计算  内参 Ct 标准差，>0.5 提示不稳定

计算规则：
  ΔCt   = Ct(靶基因) − Ct(内参)
  ΔΔCt  = ΔCt(样本) − ΔCt(对照组)
  相对表达量 = 2^(−ΔΔCt)

图表规格：
  图1：熔解曲线（X=Tm，Y=荧光强度，按 Target 分组）
  图2：内参稳定性（X=样本，Y=内参 Ct，误差棒=SD）
  图3：相对表达量（X=样本，Y=2^-ΔΔCt，误差棒=SD）

结论规则：
  若 RefCt_SD > 0.5 → “内参稳定性不足，结果仅供参考”
  若 PeakCount ≠ 1 → “样本 X 熔解曲线异常，建议复检”
  若 Ct > 35 → “样本 X 靶基因未检出”

合规要求：
  原始数据留存 ≥ 5 年
  报告需实验人、审核人双签名
  临床场景需脱敏患者标识

这份说明书的价值在于：开发人员可以直接照着实现模板，实验人员可以逐项核对报告是否完整，审核人员可以依据结论规则判断报告是否可信。它把“我要一份报告”这种模糊需求，变成了可执行、可验证、可复用的工程规格。

需求分析阶段多花一小时把字段和规则写清楚，后续开发和返工至少省一天。规格说明书不是文档负担，而是报告自动化的第一道质量关卡。

六、常见陷阱与检查要点

在实际项目中，需求转化最容易踩三个坑。第一，字段缺失：只写了 Ct 值，忘了记录试剂批号和仪器型号，导致结果无法追溯。第二，规则模糊：写了“内参不稳定时提示”，但没定义什么叫不稳定，开发只能猜。第三，场景混用：把科研报告的字段直接套到临床报告上，缺少审核签名和参考区间，合规审查直接不通过。

检查一份规格说明书是否合格，可以问四个问题：每个字段是否有明确的类型和取值范围？每条结论规则是否写成了可执行的判断条件？每张图表是否指定了坐标轴、分组和标注？合规要求是否覆盖了签名、脱敏和留存？四个问题都能回答“是”，这份说明书才具备可复用性。

完成需求分析与模板抽象后，下一阶段才是模板的代码实现与数据绑定。但在此之前，请确保规格说明书已经过实验人员、开发人员和审核人员三方确认——这份文档的质量，直接决定了自动报告系统能否真正落地。