VPasCode（以代码形式绘制图表）用于 SysML 需求图——全面指南

1. 什么是需求图？

一个需求图是 SysML 的一种图表类型，其唯一目的是将需求作为一等模型元素进行捕获，并使其关系明确且可追溯。与需求文档（仅是一个列表）不同，需求图是一个图：需求是节点，它们之间的关系——包含、派生、满足、验证和追溯——是边。

核心理念是可追溯性。在 IT 系统中，需求并非孤立存在。干系人的需求驱动系统需求；该需求由一个架构块来满足；测试用例对其进行验证；它还可能被细化为子需求。需求图使所有这些链接都可见且可审计。这正是将扁平的电子表格转化为模型的关键。

为何在 IT 系统中使用它？

IT 项目以需求漂移而闻名——范围蔓延、未受控的变更，以及“我们构建了它，但没人要求它”的问题。需求图之所以有用，是因为它允许你：

• 向后追溯——“为什么这个组件存在？”→ 跟随满足链接追溯至需求，并派生链接追溯至业务需求。

• 向前追溯——“该需求是否已验证？”→ 跟随验证链接至测试用例。

• 评估变更影响——“如果此需求发生变更，还会影响什么？”→ 跟随所有入边和出边。

• 证明覆盖率——每个需求都应通过某事物 并由 验证某事物。孤立需求会立即显示出来。

2. 关键概念与符号

2.1 需求元素

需求被绘制为一个矩形，包含一个名称、一个唯一标识符（通常为层次结构，如1.2.3)，以及需求文本。构造型为«需求».

需求可包含属性——形式化建模的属性，例如来源, 风险, 优先级, 状态，或验证方法。这些使需求可衡量的而不是模糊的。

2.2 关系（图表的核心）

关键规则：关系永远不会绘制到需求的”ID 字符串”上ID 字符串”——它绘制到元素的”别名”。如果需求 A”包含”需求 B，则您必须”不”再绘制一条”«derive»"它们之间的任何方向；对于同一对元素，包含与派生是互斥的。

2.3 模块、测试用例和细化来源

• 模块” («block»"）：满足需求的设计元素。在 IT 上下文中，这是您的架构组件——服务、模块或 API。

• 测试用例” («testCase»"）：验证单元。

• 细化来源”：用例、活动或任何用于细化需求的模型元素。

符号说明：关系箭头具有特定的箭头头（例如，”«satisfy»"箭头，例如，指向被满足的需求）。在正文中描述这些内容时，始终引用构造型——请写作”`«satisfy»`"——以免被读者的 Markdown 解析器吞掉。

3. 图表示例

示例 1——基础需求层次结构

此示例展示了包含关系和派生关系，这是每个需求图的基础骨架。顶层性能需求可分解为可衡量的子需求。

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title 车辆性能需求层次结构

$requirement("车辆性能", ReqVehiclePerf, "1", "车辆应在标称运行条件下满足指定的性能目标。")
$requirement("加速性能", ReqAccel, "1.1", "车辆应在 6 秒内从 0 加速至 100 km/h。")
$requirement("最高车速", ReqTopSpeed, "1.2", "车辆应达到至少 220 km/h 的最高车速。")
$requirement("制动性能", ReqBraking, "1.3", "车辆应在干燥路面上从 100 km/h 减速至停止，制动距离不超过 38 米。")
$requirement("燃油经济性", ReqFuel, "1.4", "车辆应在综合工况下实现至少 15 km/l 的燃油经济性。")

$containment(ReqVehiclePerf, ReqAccel)
$containment(ReqVehiclePerf, ReqTopSpeed)
$containment(ReqVehiclePerf, ReqBraking)
$containment(ReqVehiclePerf, ReqFuel)
$deriveReqt(ReqBraking, ReqVehiclePerf)
@enduml

解读如下： 加速性能, 最高车速, 制动性能、和 燃油经济性均属于 组成部分的总括性 车辆性能需求（包含关系）。制动性能也 派生自，意味着它被分解为一个具体、可衡量的目标。

示例 2 — 满足与验证（设计符合需求）

此部分增加了设计侧内容。架构组件 满足需求，而测试用例 验证它们。这是在设计评审中展示的图表。

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title 支付系统 — 满足与验证

$requirement("PCI-DSS 合规性", ReqPci, "3", "系统不得存储卡验证值，并应对静态持卡人数据进行加密。")
$requirement("处理支付", ReqPay, "3.1", "系统应在 3 秒内授权客户支付。")
$requirement("幂等计费", ReqIdem, "3.2", "系统在重试时不得对客户重复计费。")

$block("PaymentService", PaymentService)
$block("VaultService", VaultService)

$testCase("PCI 审计", TAudit)
$testCase("延迟测试", TLatency)
$testCase("幂等性测试", TIdem)

$containment(ReqPci, ReqPay)
$containment(ReqPci, ReqIdem)

$satisfy(PaymentService, ReqPay)
$satisfy(VaultService, ReqPci)

$verify(TAudit, ReqPci)
$verify(TLatency, ReqPay)
$verify(TIdem, ReqIdem)
@enduml

解读如下： PaymentService 满足 支付处理需求，而 VaultService 满足 更广泛的 PCI-DSS 需求。每个需求均 经过验证 由测试用例验证。请注意箭头方向：`«satisfy»` 从模块指向其满足的需求；`«verify»` 从测试用例指向其验证的需求。

示例 3 — 完整的 IT 系统可追溯链

这是您用于追溯 业务需求直至验证的图表 — 经典的“这段代码为何存在？”问题。

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title 电子商务系统 — 需求可追溯性

$requirement("业务：降低购物车放弃率", ReqBiz, "B1", "业务方应在两个季度内将购物车放弃率降低 15%。")
$requirement("结账用户体验", ReqUx, "S1", "系统应允许访客在 5 步内完成结账。")
$requirement("一键重购", ReqReorder, "S2", "系统应允许回头客通过一次操作重购过往订单。")
$requirement("数据驻留", ReqResidency, "S3", "系统应将欧盟客户数据存储于欧盟区域内。")

$block("CheckoutUI", CheckoutUI)
$block("ReorderService", ReorderService)
$block("RegionalDatastore", RegionalDatastore)

$testCase("结账流程测试", TCheckout)
$testCase("重购测试", TReorder)
$testCase("驻留审计", TResidency)

$containment(ReqBiz, ReqUx)
$containment(ReqBiz, ReqReorder)
$deriveReqt(ReqUx, ReqBiz)
$deriveReqt(ReqReorder, ReqBiz)

$satisfy(CheckoutUI, ReqUx)
$satisfy(ReorderService, ReqReorder)
$satisfy(RegionalDatastore, ReqResidency)

$verify(TCheckout, ReqUx)
$verify(TReorder, ReqReorder)
$verify(TResidency, ReqResidency)

$trace(ReqResidency, ReqBiz)
@enduml

解读如下： 业务需求 B1 是核心基础。系统需求 S1 和 S2 是 源自 它（即“为什么”），而 S3（数据驻留）是 可追溯的 约束仅通过 `«追溯»`。每个系统需求都 由组件满足 并由 测试验证。如果 B1发生变化，此图可立即告知您哪些组件和测试在范围内。

4. 如何构建（实用工作流程）

1. 从顶层需求开始。 通常是业务或干系人需求。为其分配清晰的 ID 空间（例如 B* 代表业务， S* 代表系统）。

2. 通过包含关系向下分解。 将大需求分解为更小的、 可衡量的 需求。良好的需求文本应包含具体数值（如“少于 3 秒”、“15%”、“在欧盟区域内”）。”

3. 在子项是对父项的具体重述时，添加派生链接 而不仅仅是部分。请记住：一对关系可通过包含关系连接 或 派生关系连接，但绝不可同时使用两者。

4. 使用“满足”将设计与需求进行映射满足.每个架构块应至少满足一项需求。不满足任何需求的架构块可考虑删除；未被任何架构块满足的需求则构成覆盖缺口。

5. 使用“验证”将测试与需求进行映射验证.每项需求都需要一条验证路径。未被任何内容验证的需求是不可测试的——这是一个危险信号。

6. 仅在别无他法时使用“追踪”追踪仅在别无他法时使用“追踪”它是处理松散关联的逃生通道；过度使用会稀释其价值。

7. 将其控制在约24个元素以内。大型图表会变得难以阅读。应按子系统或需求类别（安全、性能、功能）进行拆分。

三个覆盖问题

对每张需求图执行以下检查清单：

• 每项需求是否都得到满足？（如果是系统需求，必须有内容来实现它）

• 每项需求是否都得到验证？（必须有内容来证明它）

• 每项需求是否都能追溯到某项需求？（不存在无业务依据的孤立需求）

任何“否”均为发现的问题。

5. 将其应用于IT系统——模式与陷阱

良好实践

• 在视觉上区分需求“类型”类型在视觉上区分需求“类型”您可以对需求进行构造型标记（«功能», «性能», «安全性», «可用性») 以便非功能性需求与功能性需求区分开来。

• 保持 ID 层级的意义性。 2.3.4应让读者明白该需求位于模块 2、功能 3、子功能 4 之下。图表之间以及您使用的 ALM 工具中的一致性至关重要。

• 对来源进行建模。添加一个来源属性（监管要求、干系人名称、市场需求文档）。追溯至起源通常比追溯至设计更为重要。

• 一张图表，一个关注点。满意度图（设计评审）和验证图（测试评审）面向不同的受众。切勿将两者连同整个层级结构塞进同一张图中。

常见陷阱

• 推导与包含关系的混淆。它们看起来相似，但含义不同。包含关系是结构分解；推导关系是意图的逻辑演进。将两者混用（或在两个元素之间同时绘制两种关系）会导致模型无效。

• 使用 ID 而非别名进行引用。在工具中，关系绑定到元素的别名，而非人类可读的 ID 字符串。若别名设置错误，关系将 silently 指向空对象。

• 将追踪 作为 满足. 追踪链接并不声称目标满足了任何内容。如果您想表达“此组件实现了此需求”，请使用 `«满足»`.

• 无编号的需求。 “系统应快速”无法被验证。没有可测量阈值的需求只是愿望，而非需求。

• 让图表成为规范。 图表显示 关系；需求 文本和属性承载详细信息。保持文本精确，并附加属性（状态、优先级、风险），以便模型可被查询。

6. 工具

您可以使用 VPasCode — 粘贴代码，图表将立即渲染。之后您还可以导出或对其进行优化。

快速参考：元素和关系宏

$requirement("名称", 别名, "ID", "需求文本")
$block("块名称", 别名)
$testCase("测试用例名称", 别名)

$containment(父别名, 子别名)
$deriveReqt(子别名, 父别名)
$satisfy(块别名, 需求别名)
$verify(测试用例别名, 需求别名)
$refine(模型别名, 需求别名)
$trace(源别名, 目标别名)
$copy(源别名, 目标别名)

摘要

需求图是 可追溯性的骨干 的模型。对于 IT 系统，它回答了每次审计、设计评审和变更请求都会提出的三个问题： 为什么存在它？什么实现了它？什么证明了它？ 使用得当——具备可测量的需求文本、正确的关系语义以及严格的覆盖检查——它可将需求从静态文档转变为活生生的、可查询的模型，确保设计、代码和测试与业务意图保持一致。

参考

1. VPasCode：基于 PlantUML、Mermaid 和 Graphviz 的 AI 辅助图表即代码：官方指南，涵盖 AI 辅助图表生成、修改工作流以及多领域特定语言（DSL）支持，包括 PlantUML、Mermaid 和 Graphviz。
2. Visual Paradigm VPasCode：综合指南: VPasCode 功能详解、目标用户（开发人员、架构师、分析师）及其在敏捷文档工作流中的角色概述。
3. 欢迎使用 Visual Paradigm VPasCode：迈向“以代码绘图”（DaC）: 统一平台介绍，阐述文本转图表工作流的优势及自动化布局工程。
4. 60 秒快速入门指南 | VPasCode 文本转图表指南: 使用带实时预览的浏览器编辑器创建、自定义和导出图表的分步指南。
5. VPasCode 新功能：AI UML 配置文件图生成器: 产品更新，介绍利用自然语言提示生成 AI 驱动的 UML 配置文件图，并提供医疗数据隐私合规示例。
6. Visual Paradigm VPasCode 中的原生 AI 图表生成功能: 宣布在编辑器内直接通过自然语言提示生成、修改和修复图表的嵌入式 AI 能力。
7. AI 驱动图表生成器与生产力工具 | VPasCode: VPasCode 与 AI 聊天机器人、Visual Paradigm 桌面版及 OpenDocs 的集成概述，以优化文档流程。
8. 最佳 PlantUML 替代方案及免费“以代码绘图”编辑器: PlantUML 替代方案对比矩阵，突出 VPasCode 的多 DSL 支持、AI 功能及基于浏览器的零配置方法。
9. 以代码绘图编辑器：即时将文本转换为图表: 功能概述，涵盖自动格式检测、实时渲染及多格式导出选项（SVG、PNG、PDF）。
10. Visual Paradigm 生态系统指南: 说明何时使用 VPasCode 与 VP 桌面版，并提供版本控制图表维护及与活文档集成的指导。