Visual Paradigm 流水线：全面指南
Visual Paradigm 流水线是 Visual Paradigm 绘图与建模工具与 Visual Paradigm OpenDocs 之间的集中连接层。它使团队能够创建视觉资产，将其作为受管理的云制品进行存储，跟踪其修订版本，并将其嵌入动态文档中，而无需反复导出、上传和替换图像文件。
核心工作流程如下：
创建或生成 → 提交至流水线 → 嵌入 OpenDocs → 审查更改 → 更新文档
流水线旨在随着项目的演进保持图表与文档的同步。它不将图表视为静态的 PNG 或 JPG 文件，而是维护已发布视觉元素与其源资产之间的关系。
1. 流水线的作用
流水线执行四项主要功能：
-
集中式资产存储
它将图表和其他视觉资产存储在共享的云存储库中。 -
工具间流转
它连接了 Visual Paradigm 桌面版、Visual Paradigm 在线版、AI 绘图聊天机器人、VPasCode 和 OpenDocs。 -
修订版本管理
它记录视觉资产的更改，并允许用户查看更新的修订版本或恢复早期版本。 -
动态文档集成
它允许将视觉资产作为受管理元素嵌入 OpenDocs，而非手动上传的图像文件。
通过流水线传输的资产可包括 UML、BPMN、ERD、ArchiMate、流程图、架构图、序列图、翻页书和书架，具体取决于源工具和发布工作流。
2. 流水线生态系统
将流水线理解为三层生态系统最为直观。
生成层
这是创建图表和模型的地方。
-
Visual Paradigm 桌面版：用于高级企业建模、数据库设计、软件架构、UML、BPMN、ERD 及其他专业建模任务。
-
Visual Paradigm 在线版：用于基于浏览器的协作绘图和视觉规划。
-
AI 绘图聊天机器人：将自然语言描述转换为图表和结构化视觉模型。
-
VPasCode：通过基于文本的图表语言（如 PlantUML、Mermaid、Markmap、Graphviz 和 ECharts）创建图表。
AI 聊天机器人可加速初始图表的创建，而 VPasCode 提供了一种更受控、面向代码的方式来完善和维护图表。
流水线层
管道（Pipeline）是传输与管理层。它存储提交的资产，为其分配可识别的引用标识，跟踪修订版本，并向授权用户和连接的工具提供这些资产。
该层尤为宝贵，因为它维护了已发布图表与其源模型之间的关系。当源模型发生变化时，OpenDocs 能够识别出有更新的修订版本可用。
文档层
Visual Paradigm OpenDocs 是创建项目文档、技术手册、系统规范、维基和知识库的目标平台。
通过管道管理的资产可以作为实时或受控的视觉元素插入到 OpenDocs 中。因此，文档可以包含解释性文本以及与其源保持关联的链接视觉模型。
3. 为什么要使用管道？
传统文档通常遵循以下模式：
-
创建图表。
-
将其导出为 PNG、JPG、SVG 或 PDF 格式。
-
将其上传到维基或文档中。
-
手动插入该图像。
-
稍后修改原始图表。
-
再次导出。
-
在所有出现的位置替换旧图像。
这会导致多个问题：
-
同一图表可能存在多个副本。
-
文档可能过时。
-
团队可能不清楚哪个修订版本是权威的。
-
源文件与导出的图像可能会分离。
-
元数据、关系和模型智能可能会丢失。
-
在多个文档中更新图表会消耗管理时间。
管道用源资产与文档之间的受控连接取代了这一过程。结果是更可靠的单一事实来源用于视觉信息。
4. 核心概念
受控资产
受控资产是通过管道存储的视觉制品，而非作为普通图像手动上传。它可以具有名称、源、修订历史以及与一个或多个文档的关系。
示例包括：
-
系统架构图
-
用户旅程流程图
-
数据库模型
-
API 序列图
-
业务流程模型
-
产品路线图
-
组织架构图
-
数字翻页书
-
书架与知识集合
修订版
修订版是资产的一个已保存版本。当用户修改图表并提交或发布更新时，可能会创建新的修订版。
修订历史记录有助于团队：
-
查看变更内容
-
识别谁进行了更新
-
审查变更顺序
-
比较当前状态与先前状态
-
在必要时还原早期版本
实时文档
实时文档包含与受管源资产保持关联的可视化内容。当源图表发生变化时，相应的 OpenDocs 内容可提示有更新可用。作者随后可以决定何时应用新版本修订。
单一事实来源
流水线降低了关于应使用哪张图表的不确定性。团队无需在邮件附件、共享驱动器、幻灯片和维基中维护独立副本，而是可以引用集中管理的资产。
5. 标准流水线工作流程
步骤 1：创建可视化资产
从最适合该任务的工具开始。
例如：
-
使用桌面版进行详细的企业架构设计。
-
使用在线版进行协作式流程映射。
-
使用 AI 聊天机器人，根据自然语言描述生成初始系统流程图。
-
当需要基于文本、类似代码的图表定义时，请使用 VPasCode。
一个有用的 AI 提示词可能是：
为涉及客户、Web 应用、支付服务、库存服务和订单数据库的在线订购流程创建序列图。
展示支付成功、支付失败和库存不可用三种场景。
如果使用 VPasCode，结果可以通过图表代码进行细化。例如：
@startuml
标题：在线订单流程
参与者：客户
参与者“Web 应用”为 Web
参与者“支付服务”为 Payment
参与者“库存服务”为 Inventory
数据库“订单数据库”为 DB
客户 -> Web: 提交订单
Web -> Payment: 授权支付
Payment --> Web: 支付已批准
Web -> Inventory: 预留商品
Inventory --> Web: 商品已预留
Web -> DB: 创建订单
DB --> Web: 订单 ID
Web --> 客户: 显示确认信息
@endumlVPasCode 支持“以代码形式绘制图表”的工作流，其中文本定义可被渲染为可视化图表，并在发布前进行优化。
步骤 2：审查并优化资源
在将资源提交至流水线之前，请检查以下内容：
-
图表标题
-
术语与标签
-
关系的方向
-
缺失的参与者或系统
-
布局与可读性
-
敏感或受限信息
-
可视化内容是否与当前系统设计一致
-
目标受众是否能够理解
AI 生成的图表应仔细审查。AI 可以加速图表创建，但领域专家应验证架构、关系、假设和术语。
步骤 3：将资源发送或提交至流水线
审查图表后，请在源应用程序中使用相关的导出、发布、保存或提交操作将其发送至流水线。
随后，流水线将该资源作为可复用的云资源进行管理。根据工作流的不同，流水线可以存储该资源、为其分配可识别的引用，并记录其初始版本。
此时，团队应提供有用的元数据，例如：
-
清晰的资源名称
-
项目或产品名称
-
资源类型
-
负责人
-
业务或技术领域
-
状态，例如草稿、已审查或已批准
-
描述
-
相关系统或服务
-
变更摘要
一个好的名称应：
支付平台 - 结账授权流程
一个不合适的名称是：
diagram-final-v3-new
步骤 4：将资源插入 OpenDocs
在 OpenDocs 中：
-
打开现有文档或创建新文档。
-
导航到该可视化内容所属的章节。
-
使用可视化资源插入命令或相关的图表插入选项。
-
搜索由 Pipeline 管理的资源。
-
选择所需的资源和修订版本。
-
添加周围的说明性文字。
图表很少应脱离上下文出现。请包含以下内容：
-
图表的目的
-
范围
-
关键假设
-
重要参与者或组件
-
非常规流程的说明
-
日期或审查状态
-
负责人或责任团队
例如：
本图表描述了卡支付的授权流程。
支付服务负责授权，而订单服务仅在支付获批后才创建订单。支付失败的请求将返回至 Web 应用程序，且不会创建订单记录。
该资源作为受管理的可视化内容嵌入，而非作为独立上传的截图。
步骤 5：发布或共享文档
文档经审核后，可用作：
-
软件需求规格说明书
-
架构参考
-
API 指南
-
项目维基
-
入职培训资源
-
培训手册
-
合规或审计参考
-
面向客户的产品手册
当团队需要结构化、更广泛地访问文档集合时，OpenDocs 内容也可以通过翻页书或书架等格式进行分发。
步骤 6：更新源资源
当系统发生变更时，请在其原始源工具中更新该图表。
例如，如果登录流程中添加了多因素认证：
-
在 Desktop 或 VPasCode 中打开原始图表。
-
添加 MFA 服务及相关交互。
-
审查更新后的布局。
-
将新版本保存或提交到流水线。
-
添加有意义的变更说明。
一条有用的变更说明可能如下：
在认证服务与 MFA 服务之间添加了 OTP 验证。
更新了过期和无效代码的失败路径。
步骤 7：在 OpenDocs 中审查更新
当有新版本可用时，OpenDocs 中的链接可视化元素可以显示更新指示器。文档作者随后可以审查该变更，并决定是否更新嵌入的可视化元素。
这种方法保留了编辑控制权。每次编辑源模型时，文档不一定需要立即更改；作者可以先审查修订版，并在适当时应用它。
步骤 8：必要时进行回滚
如果新版本引入了错误或尚未准备好发布，请审查资源历史记录，并在支持的情况下恢复或选择更早的版本。
在以下情况下，回滚非常有用：
-
图表被过早更新。
-
提交了实验性设计。
-
某项变更引入了错误的关系。
-
文档必须暂时反映之前已批准的状态。
-
审计需要审查之前的设计。
6. 使用流水线配合不同工具
Visual Paradigm Desktop
Desktop 适用于复杂建模和企业级工作。
典型的工作流程如下：
-
在 Desktop 中打开项目。
-
创建或更新模型。
-
审查模型以确保其结构正确性。
-
将图表或选定的视觉资源发送至流水线。
-
OpenDocs 用户插入或更新受管资源。
此工作流适用于以下场景：
-
企业架构
-
大型 UML 模型
-
数据库工程
-
BPMN 流程库
-
应用架构
-
系统工程
-
架构审查文档
Visual Paradigm Online
当团队需要基于浏览器的协作时，在线模式非常有用。
典型工作流如下：
-
在在线工作区中创建图表。
-
邀请协作者进行审查或编辑。
-
完成图表。
-
将其通过流水线发送。
-
将其插入 OpenDocs。
此方法在以下场景中尤为有效：
-
产品规划
-
流程研讨会
-
用户旅程
-
团队协作
-
路线图
-
早期解决方案设计
AI 绘图聊天机器人
AI 聊天机器人适用于快速构思和起草初稿。
一个实用的工作流如下：
-
用自然语言描述系统或流程。
-
请求特定类型的图表。
-
审查生成的可视化效果。
-
修正术语和关系。
-
将结果通过流水线发送。
-
如有必要，继续在 VPasCode 或桌面版中进行细化。
-
在 OpenDocs 中发布它。
为了获得更好的结果，请指定：
-
图表符号
-
参与者
-
组件
-
关系
-
主流程和备选流程
-
错误条件
-
所需的详细程度
-
目标受众
示例提示：
为订阅平台创建一个 C4 容器图。
包括客户门户、API 网关、身份服务、计费服务、通知服务、PostgreSQL 数据库
以及外部支付提供商。显示主要数据流，
并为每个关系标注其用途。
AI 生成的可视化效果应被视为初步设计或草稿，直到经过合格团队成员的审查。
VPasCode
VPasCode 适合偏好“图表即代码”的用户。
优势包括：
-
基于文本的图表定义
-
更容易审查结构变更
-
可复用的图表源码
-
与面向代码的工作流程兼容
-
快速迭代
-
文本定义的变更对比更清晰
常见的工作流程如下：
-
生成或编写 PlantUML、Mermaid、Graphviz、Markmap 或其他支持的格式。
-
渲染图表。
-
语法和布局正确。
-
将可视化内容发送至 Pipeline。
-
如果需要更深入的建模，请在 Desktop 中导入或优化它。
-
将其嵌入 OpenDocs。
VPasCode 还可以作为 AI 生成想法与正式 Desktop 建模之间的中间步骤。
7. 常见用例
软件架构文档
架构师可以直接将组件、部署、序列和基础设施图发布到系统文档中。
当服务被添加或移除时，源图会自动更新，OpenDocs 版本可随之刷新，而无需手动替换图像文件。
API 文档
团队可以为以下端点创建序列图：
-
POST /orders -
GET /customers/{id} -
POST /payments -
PUT /subscriptions
每个 API 部分可包含说明文本和当前交互图。这有助于开发人员不仅理解端点参数，还能了解所涉及的服务、数据库和外部系统。
产品需求
产品经理可以创建流程、用户旅程、故事地图和路线图，然后将它们嵌入产品需求文档中。
这确保了功能的可视化表示与书面需求保持一致。
业务流程管理
业务分析师可以建模当前状态和未来状态流程，将其发布到 OpenDocs，并在流程演进过程中维护修订历史。
培训与入职
团队可以结合图表、书面说明、翻页书和书架，为新员工或客户创建结构化的培训材料。
合规与审计准备
Pipeline 可通过保留修订信息和上下文变更说明来支持可追溯性。团队可利用它展示架构、流程或控制模型随时间的变化。
Pipeline 不会取代组织的正式治理流程，但可为审查和历史追踪提供有用的证据。
数据库与数据架构
数据库图和数据流模型可嵌入表描述、所有权信息、数据分类和集成说明旁边。
8. 推荐治理模型
成功的 Pipeline 实施不仅需要工具集成。团队应就资产的命名、审查、批准和更新方式达成一致。
定义所有权
为每个重要资产指定负责人。
示例：
-
企业架构团队负责平台架构图的维护。
-
安全团队负责信任边界图的维护。
-
产品团队负责客户旅程图的维护。
-
数据库团队负责逻辑和物理数据模型的维护。
建立生命周期状态
有用的状态包括：
-
草稿
-
审核中
-
已批准
-
已发布
-
已弃用
-
已归档
使用一致的命名规范
标准命名格式可能如下：
[领域] - [系统或流程] - [图表类型]
示例：
身份认证 - 登录与多因素认证 - 序列图
商务 - 结账 - 活动图
支付 - 授权 - 组件图
要求提供有意义的变更说明
每次重大更新都应说明：
-
变更内容
-
变更原因
-
提出者
-
受影响的系统或需求
-
相关文档是否需要审查
将实验性内容与正式发布区分开
由人工智能生成或用于探索的图表不应自动成为权威文档。在将资产标记为已批准或广泛发布之前，应使用审查流程。
定期审查嵌入式资产
根据风险安排审查：
-
关键架构：每月一次或在重大版本发布后
-
API 图表：每当契约发生变更时
-
业务流程：每季度一次或在政策变更后
-
培训材料：每个发布周期至少一次
-
低风险参考图表：每年一次
9. 实用文档模式
一个优秀的 OpenDocs 页面可遵循以下结构：
# 支付授权流程
## 目的
说明平台在创建订单前如何授权卡片支付。
## 范围
涵盖 Web 应用程序、支付服务、欺诈筛查、订单服务及支付提供商。
## 图表
[由 Pipeline 管理的视觉资源]
## 主流程
1. 客户提交支付信息。
2. Web 应用程序发送授权请求。
3. 支付服务验证该请求。
4. 外部提供商批准或拒绝支付。
5. 订单服务在获得批准后创建订单。
## 失败场景
- 支付信息无效
- 提供商超时
- 欺诈筛查被拒
- 重复的授权请求
## 所有权
支付平台团队
## 变更历史
- 新增欺诈筛查步骤
- 新增提供商超时处理机制
- 更新订单创建序列该格式将人类可读的说明与受管理的视觉源相结合。
10. 需避免的常见错误
将 Pipeline 视为普通文件存储
主要优势并非仅仅将图像存储在云端。其价值在于维护源关系、修订历史和文档关联。
未经审查即发布
图表可能在技术上正确，但仍不适合目标受众。发布前请检查可读性、术语、范围及敏感细节。
创建重复资源
避免将名称不清晰的同一图表的细微差异副本发送至 Pipeline。如可能，请更新现有的权威资源。
使用模糊的变更说明
“已更新图表”价值有限。请描述实际的架构或流程变更。
嵌入图表但未附说明
视觉内容应配有足够的文字，以便读者理解其目的、边界及重要决策。
自动将 AI 输出视为权威内容
AI 在生成初稿方面效果显著，但架构、安全、合规性及业务逻辑应由领域专家进行验证。
忽视文档更新指示
即使图表受管理，若从未审查可用修订版，仍可能过时。请指定专人负责检查并应用更新。
11. 衡量效益
团队可使用以下实用指标评估 Pipeline：
-
在多个文档中更新图表所需的时间
-
审查中发现的过时图表数量
-
重复资源的数量
-
导出和重新上传视觉素材所花费的时间
-
拥有明确负责人的主要图表所占百分比
-
链接至已批准素材的文档页面所占百分比
-
回滚或修订审查事件的数量
-
新团队成员入职所需时间
-
由过时视觉素材导致的文档缺陷数量
最重要的成果并非存储的图表数量，而是缩小当前系统设计与用于理解该设计的文档之间的差距。
12. 推荐采用计划
第一阶段：从单一工作流开始
选择一个高价值场景，例如：
-
软件架构文档
-
API 序列图
-
产品需求流程
-
数据库文档
第二阶段：定义标准
达成一致：
-
命名规范
-
所有权
-
修订说明
-
审查状态
-
发布权限
-
更新职责
第三阶段：转换现有文档
用由流水线管理的素材替换频繁过时的屏幕截图。从更新频繁或由多个团队使用的文档开始。
第四阶段：引入 AI 和图表即代码工作流
使用 AI 聊天机器人进行构思，使用 VPasCode 进行基于文本的细化。当模型需要更深入的企业分析时，使用桌面版。
第五阶段：建立持续审查机制
将流水线素材审查纳入：
-
发布规划
-
架构评审委员会
-
冲刺或迭代收尾
-
变更管理流程
-
文档质量检查
结论
Visual Paradigm 流水线将图表管理从文件处理任务转变为连贯的文档工作流程。团队可以在桌面版、在线版、AI 聊天机器人或 VPasCode 中创建图表，将其提交至集中式仓库，嵌入 OpenDocs，并通过受跟踪的版本进行更新。
其最重要的优势在于连续性。图表始终与文档保持关联，文档始终更贴近当前系统，团队在导出、裁剪、上传、替换和查找正确版本上花费的时间更少。
推荐的运营模式是：
谨慎创建，审慎提交，附带上下文进行文档记录，审查修订版本，仅发布经批准的更新。
