企业官网建设流程全解析

1. 项目概述：这不是画图，是构建可演进的系统表达语言

“diagram-design”这个词组乍看像一个工具功能按钮，但在我过去十年带团队做技术方案评审、系统架构推演、跨职能协作落地的过程中，它早已不是“用Visio拖几个框”的代名词。它是一套以图形为载体的系统化表达方法论，核心目标是让复杂逻辑、数据流向、组件关系、状态变迁这些抽象概念，在一张纸上就能被不同背景的人——开发、测试、产品、运维甚至客户——同步理解、快速对齐、持续验证。我见过太多项目在需求评审会上争论三小时没结论，只因为一张流程图里“用户提交后是否立即返回成功”这个节点没标清楚；也经历过线上故障复盘时，发现最初设计图里压根没画出缓存失效路径，导致所有人按错误假设排查。真正的 diagram-design，解决的从来不是“怎么画得好看”，而是“如何让图本身成为可执行、可验证、可迭代的活文档”。它适用于所有需要多人协同理解复杂结构的场景：微服务间调用链路设计、IoT设备数据上报状态机、SaaS平台权限模型可视化、甚至非技术领域如供应链物流节点责任划分。如果你正在写PRD、画架构图、做UML建模、或者只是想把脑子里那个“大概逻辑”变成别人能一眼看懂的共识，那么你不是在学画图技巧，而是在掌握一种降低协作熵值的关键能力。

2. 内容整体设计与思路拆解：从“静态快照”到“动态契约”的范式迁移

2.1 为什么传统绘图方式在现代协作中频频失效？

十年前，我给某高校实验室做系统集成支持，他们用PlantUML画类图，用draw.io画部署拓扑，看起来很规范。但上线后问题频发：开发说“图里没写数据库连接池大小，我们按默认值配的”，运维说“图上标了‘高可用’，但没说明是主备还是双活，我们按单点部署了”，测试说“状态流转图里缺了网络超时分支，用例没覆盖”。问题根源不在工具，而在设计范式——我们习惯把 diagram 当作一次性交付的静态快照，画完就归档，后续变更靠口头同步或零散备注。这种模式在单体应用、小团队、低频迭代时代尚可维持，但在今天，一个中型服务日均发布3次、接口文档由Swagger自动生成、CI/CD流水线自动校验API契约的环境下，手动画的图如果不能和代码、配置、测试用例实时联动，它就天然成为信息孤岛和信任黑洞。

2.2 Diagram-Design 的核心设计哲学：三层契约驱动

我后来在多个跨团队项目中验证并固化了一套三层驱动模型，它彻底改变了我们对待图表的态度：

• 第一层：语义契约（Semantic Contract）
  这是图的“灵魂”。每个图形元素（矩形、菱形、箭头）必须绑定明确、无歧义的语义定义。比如，一个“圆角矩形”不能简单叫“服务”，而应标注为“OrderService v2.3—— 提供订单创建、查询、取消接口，SLA 99.95%，依赖UserService和PaymentGateway”。这要求我们在绘图前先完成轻量级领域建模，用统一术语表（Glossary）约束命名。我试过直接用Mermaid语法写注释，但发现团队新人容易忽略，后来强制要求所有关键节点旁添加[语义标签]，例如[核心业务服务]、[第三方异步回调]、[最终一致性补偿点]。实测下来，评审会时间平均缩短40%，因为争议点从“这个框代表什么”变成了“这个SLA指标是否合理”。

• 第二层：行为契约（Behavioral Contract）
  这是图的“肌肉”。箭头不再只是“有连接”，而必须声明交互行为：是同步RPC调用（HTTP POST /order）、异步消息（Kafka Topic: order-created）、还是定时轮询（Cron: */5 * * * *）？更重要的是，要标注失败处理策略。我在某电商促销系统设计中，强制要求所有出向箭头旁标注[重试3次+降级返回兜底数据]或[告警+人工介入]。当大促期间支付网关超时，运维直接对照这张图定位到“订单创建”节点的失败策略是“降级”，立刻跳过支付环节生成待支付单，避免整个下单链路雪崩。这种设计让图从“描述现状”升级为“指导应急”。

• 第三层：演化契约（Evolutionary Contract）
  这是图的“生命线”。每张图必须自带版本号、最后更新时间、关联的代码仓库分支（如git commit: a1b2c3d）和变更原因（如#234 增加风控服务校验节点）。我们不用任何“图管理平台”，而是把.mmd（Mermaid）文件和.drawio文件直接放在项目根目录的/docs/diagrams/下，和README.md同级。CI流水线增加一步：git diff --name-only $PREV_COMMIT $CURRENT_COMMIT | grep 'docs/diagrams/' && echo "Diagram changed, trigger review"。这样，图的每一次修改都像代码一样走PR流程，评审人必须确认语义、行为、演化三要素是否完备。去年一个支付模块重构，因图中[旧版加密服务]节点未及时标记[已废弃，见v3.0]，导致两个团队并行开发冲突，这次教训让我们把“演化契约”写进了团队协作守则第一条。

2.3 工具选型逻辑：为什么放弃“全能型”绘图软件，拥抱文本即图？

很多人第一反应是打开PowerPoint或Lucidchart，但我坚持用Mermaid、PlantUML这类文本化工具，理由非常实际：

• 可追溯性：.mmd文件是纯文本，git blame能精准定位“谁在什么时候改了这个状态转移条件”，而二进制.drawio文件只能看到“binary file changed”，历史全黑盒。
• 可编程性：我们有个Python脚本，自动扫描代码中的@api.route('/order')装饰器，提取接口路径、参数、返回码，生成Mermaid序列图骨架，开发者只需补全业务逻辑注释。这比手动拖拽快5倍，且零遗漏。
• 可验证性：用mermaid-cli将.mmd转成PNG的同时，用正则校验图中是否包含[SLA]、[失败策略]等必填标签，不满足则CI失败。这相当于给图加了编译器检查。
• 可嵌入性：.mmd代码可直接粘贴进Confluence、GitLab Wiki、甚至GitHub README，渲染后就是图，无需导出再上传。某次客户演示，我直接在PR评论里贴Mermaid代码，对方点开链接就看到最新架构图，省去邮件传附件的麻烦。

当然，文本工具不适合画UI原型或精细布局，但diagram-design的核心战场是逻辑、关系、流程，而非像素级美观。我把UI设计交给Figma，把架构图交给Mermaid，各司其职，效率翻倍。

3. 核心细节解析与实操要点：从一张混乱的草图到可执行契约的7个关键动作

3.1 动作一：用“三问法”清洗原始需求，拒绝模糊输入

拿到一个“画个订单流程图”的需求，我绝不马上打开编辑器。而是拉着产品经理、开发负责人，用白板进行15分钟“三问法”清洗：

• 问实体：“这个流程里，核心业务实体有哪些？（如Order、User、Payment）每个实体的关键属性是什么？（如Order.status、Order.created_at）”
• 问动作：“触发这个流程的初始事件是什么？（如用户点击‘提交订单’按钮）过程中有哪些关键决策点？（如库存是否充足、用户余额是否足够）每个决策点的判断依据和输出分支是什么？”
• 问边界：“这个流程的起点和终点在哪里？（如从‘用户提交’开始，到‘返回订单号’结束）哪些外部系统参与？（如调用风控服务、发送短信）它们的响应时间、失败率、重试机制已知吗？”

这三问产出的不是图，而是一份结构化需求清单，它直接决定后续图的颗粒度。比如，如果风控服务响应时间未知，图中就必须标注[风控调用：超时阈值待定，当前设为800ms]，而不是画个模糊的“调用风控”框。我试过跳过这步，结果画完图才发现“库存校验”环节需要区分“实时库存”和“预占库存”，不得不返工重画三次。

3.2 动作二：选择正确的图类型，不是越多越好，而是恰到好处

Mermaid支持10+种图，但日常80%的场景只需3种，选错类型等于从源头制造误解：

• 流程图（Flowchart TD）：用于线性、确定性步骤。适合描述单个请求的完整生命周期，如“用户下单→校验库存→扣减库存→创建订单→支付→发货”。它的优势是时序清晰，劣势是难以表达并发或循环。我曾用它画消息队列消费流程，结果满屏loop和end，开发看得头晕，后来换成序列图立刻清爽。

• 序列图（Sequence Diagram）：用于多角色、异步交互。当你需要明确“谁在什么时候调用了谁，传递了什么，期望什么响应”时，它是唯一选择。比如支付回调流程：Alipay → WebServer → OrderService → NotificationService，每个箭头旁必须写清POST /callback?sign=xxx和HTTP 200 OK。某次排查支付失败，我们直接对照序列图，发现WebServer到OrderService的调用缺少幂等性头X-Request-ID，这就是图暴露的问题。

• 状态图（State Diagram）：用于实体状态变迁。订单状态机是经典场景：Created → Paid → Shipped → Delivered → Cancelled。关键在于每个状态转移必须标注触发事件和守护条件。例如Paid --> Shipped : 支付成功 AND 库存充足，而不是简单画个箭头。我们曾因漏标AND 库存充足，导致测试用例没覆盖“支付成功但库存不足”的异常路径，上线后出现脏数据。

提示：永远不要用流程图描述状态机，也不要拿序列图画系统部署。类型错位，图就成了误导源。

3.3 动作三：注入“防御性标注”，让图自己说话

一张合格的 diagram-design，至少30%的面积是文字标注，而非图形。我总结了6类必填标注，缺一不可：

这些标注不是装饰，而是图的“元数据”。我要求团队用固定前缀[ ]包裹，方便正则提取和自动化检查。实测下来，带完整标注的图，一次评审通过率从35%提升到82%。

3.4 动作四：建立“图-代码”双向映射，让设计活起来

图若不能驱动代码，就是废纸。我们实践了两种轻量级映射：

• 正向映射（图→代码）：用Mermaid的classDef和click语法，为节点绑定代码位置。例如：

  flowchart TD A[OrderService] --> B[PaymentGateway] classDef service fill:#4CAF50,stroke:#388E3C,color:white; click A "https://github.com/org/project/blob/main/src/order/service.py" "跳转到OrderService实现"

  开发者点图中节点，直接跳转到对应代码，设计意图和实现零距离。

• 反向映射（代码→图）：在关键函数注释中嵌入Mermaid片段。例如在create_order()函数开头：

  def create_order(): """ 创建订单主流程 ```mermaid flowchart LR A[接收请求] --> B[校验参数] B --> C{库存充足？} C -->|是| D[扣减库存] C -->|否| E[返回错误] ``` """

  文档生成工具（如Sphinx）会自动渲染此片段，确保代码里的设计说明永远最新。

这种双向映射让图不再是独立文档，而是代码的“活索引”和“活说明书”。某次紧急修复，新同学只看create_order()函数的注释图，10分钟就理清了整个流程，没翻一行其他文档。

3.5 动作五：设计“可测试性”节点，为QA铺路

很多图只画“正常流”，结果测试用例覆盖率惨不忍睹。我在设计阶段就强制加入“可测试性”节点：

• 显式标注异常分支：在流程图中，每个菱形判断节点，必须画出所有可能分支，包括[超时]、[网络错误]、[数据校验失败]。例如库存校验，不能只画[库存充足]和[库存不足]，还要画[库存服务不可用]分支，并标注[降级：使用本地缓存库存]。

• 定义可观测点：在序列图中，每个服务节点旁标注[可观测点：记录trace_id, status_code, duration]。这直接告诉QA：“这里可以埋点验证”，也告诉开发：“这里必须打日志”。

• 提供测试数据模板：在图下方附一个极简表格，列出关键节点的测试数据示例：

  节点	正常输入	异常输入	期望输出
  库存校验	sku_id="ABC", qty=1	sku_id="XYZ", qty=100	返回{"code":404}
  支付回调	sign="valid", order_id="123"	sign="invalid", order_id="456"	返回HTTP 400

这张表不是测试用例，而是测试设计的起点。QA拿到图，立刻能基于此表衍生出10+个用例，效率提升数倍。

4. 实操过程与核心环节实现：一个真实电商订单流程图的完整诞生记

4.1 场景设定与初始草图：从白板涂鸦到结构化输入

我们以某电商平台“秒杀订单创建”流程为例。初始需求来自产品PRD：“用户抢购秒杀商品，需快速创建订单并锁定库存”。我召集开发、测试、运维开了30分钟会，用白板完成“三问法”：

• 实体：User(id, token),SeckillItem(id, stock, price),Order(id, user_id, item_id, status)
• 动作：起点用户点击抢购按钮；关键决策库存是否充足、用户是否已抢过、风控是否通过；终点返回订单号或失败原因
• 边界：调用SeckillService(内部)、RiskControlService(外部)、SMSProvider(外部)；已知RiskControlServiceSLA为p95<1s，失败率<0.5%

会后，我整理出结构化输入，作为绘图唯一依据：

[起点] 用户发起抢购请求 (HTTP POST /seckill/buy) [步骤1] SeckillService 校验用户Token有效性 [步骤2] SeckillService 查询SeckillItem.stock > 0 [步骤3] SeckillService 调用RiskControlService 校验用户风险等级 [决策A] RiskControlService 返回"通过" → 继续 [决策B] RiskControlService 返回"拒绝" → 跳转至[失败处理] [步骤4] SeckillService 扣减SeckillItem.stock (Redis原子操作) [决策C] 扣减成功 → 创建Order记录，发送SMS [决策D] 扣减失败 → 回滚，返回"库存已抢光" [终点] 返回Order.id 或 错误码

4.2 Mermaid流程图实现：代码即图，标注即契约

基于以上输入，我编写了第一个可运行的Mermaid代码（seckill-flow.mmd），全程12分钟：

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4CAF50', 'edgeLabelBackground':'#fff'}}}%% flowchart TD A[用户发起抢购<br/>POST /seckill/buy] --> B[SeckillService<br/>校验Token] B --> C{Token有效？} C -->|是| D[查询SeckillItem.stock] C -->|否| Z[返回401 Unauthorized] D --> E{stock > 0？} E -->|否| Y[返回400 '库存已抢光'] E -->|是| F[调用RiskControlService<br/>校验风险] F --> G{风控通过？} G -->|是| H[Redis原子扣减stock] G -->|否| X[返回403 '风控拒绝'] H --> I{扣减成功？} I -->|是| J[创建Order记录<br/>发送SMS] I -->|否| Y J --> K[返回201 Created<br/>Order.id] %% === 防御性标注 === classDef service fill:#2196F3,stroke:#0D47A1,color:white; classDef error fill:#f44336,stroke:#b71c1c,color:white; classDef success fill:#4CAF50,stroke:#1B5E20,color:white; class A,B,D,F,H,J,K service; class Z,X,Y error; class K success; click A "https://github.com/ecom/seckill/blob/main/api.py#L23" "查看抢购入口" click B "https://github.com/ecom/seckill/blob/main/service.py#L45" "查看Token校验" click F "https://github.com/ecom/seckill/blob/main/risk_client.py#L12" "查看风控调用" %% === 关键标注 === linkStyle 0 stroke:#2196F3,stroke-width:2px; linkStyle 1 stroke:#2196F3,stroke-width:2px; linkStyle 2 stroke:#2196F3,stroke-width:2px; linkStyle 3 stroke:#f44336,stroke-width:2px; linkStyle 4 stroke:#2196F3,stroke-width:2px; linkStyle 5 stroke:#f44336,stroke-width:2px; linkStyle 6 stroke:#2196F3,stroke-width:2px; linkStyle 7 stroke:#f44336,stroke-width:2px; linkStyle 8 stroke:#2196F3,stroke-width:2px; linkStyle 9 stroke:#2196F3,stroke-width:2px; linkStyle 10 stroke:#2196F3,stroke-width:2px; style A fill:#e3f2fd,stroke:#2196F3; style B fill:#e3f2fd,stroke:#2196F3; style D fill:#e3f2fd,stroke:#2196F3; style F fill:#e3f2fd,stroke:#2196F3; style H fill:#e3f2fd,stroke:#2196F3; style J fill:#e3f2fd,stroke:#2196F3; style K fill:#e8f5e9,stroke:#4CAF50; %% === 标注文本 === A:::service B:::service D:::service F:::service H:::service J:::service K:::success %% [SLA] 标注 A -.->|"[SLA: p95 < 100ms]"| B F -.->|"[SLA: p95 < 1s, 错误率 < 0.5%]"| G H -.->|"[SLA: Redis原子操作 < 5ms]"| I %% [失败策略] 标注 F -.->|"[失败：重试1次+降级为'允许抢购']"| G H -.->|"[失败：回滚+返回400]"| Y %% [数据契约] 标注 A -.->|"[输入: JSON {token, sku_id}]<br/>[输出: 201/400/401/403]"| B %% [演化标记] classDef meta fill:#ffecb3,stroke:#ffc107,color:#212121; K:::meta K -.->|"[v1.2, 2024-05-20, #789 添加风控降级]"| K

这段代码直接渲染为专业流程图，且每一处标注都可被程序解析。CI脚本用grep -q '\[SLA:' seckill-flow.mmd检查必填项，缺失则失败。

4.3 与代码的双向绑定：让图成为开发导航仪

我将上述.mmd文件放入/docs/diagrams/，并在src/seckill/api.py的buy()函数中添加注释：

def buy(): """ 秒杀抢购主入口 ```mermaid flowchart TD A[用户发起抢购] --> B[校验Token] B --> C{Token有效？} C -->|是| D[查询库存] C -->|否| Z[返回401] %% ...（此处省略，与.mmd文件一致） ``` @see https://github.com/ecom/seckill/blob/main/docs/diagrams/seckill-flow.mmd """

同时，在Makefile中添加一键同步命令：

# 同步图到代码注释 sync-diagram: python scripts/sync_mmd_to_docstring.py docs/diagrams/seckill-flow.mmd src/seckill/api.py

开发时，IDE（如PyCharm）能直接渲染注释中的Mermaid，点节点跳转代码，形成闭环。

4.4 测试用例生成与验证：从图到自动化脚本

基于图中的标注，QA同事用Excel生成了初始测试矩阵，我将其转化为pytest参数化测试：

import pytest from unittest.mock import patch, MagicMock @pytest.mark.parametrize("risk_response,expected_status", [ ("pass", 201), # 风控通过 ("reject", 403), # 风控拒绝 ("timeout", 201), # 风控超时，按降级策略返回成功 ]) def test_seckill_buy_risk_scenarios(risk_response, expected_status): """测试风控服务不同响应下的订单创建结果""" with patch('seckill.risk_client.call_risk_service') as mock_risk: mock_risk.return_value = {"result": risk_response} response = client.post("/seckill/buy", json={"token": "abc", "sku_id": "123"}) assert response.status_code == expected_status

这个测试用例直接源于图中[失败：重试1次+降级为'允许抢购']的标注。图不仅是设计文档，更是测试规格说明书。

5. 常见问题与排查技巧实录：那些踩过的坑和救急的招数

5.1 问题一：团队成员总说“图太复杂，看不懂”，其实是图没分层

现象：新同学看架构图，抱怨“全是连线，找不到重点”。
根因分析：我们犯了“上帝视角”错误，试图在一张图里塞进所有细节——从物理服务器、容器、服务、数据库、缓存、消息队列到前端组件。这违背了diagram-design的“单一关注点”原则。
解决方案：实施三层分层法

• 战略层（L1）：仅展示核心业务域与外部系统边界。例如电商图只画[用户App] → [电商核心域] → [支付网关]，用云朵图标表示外部系统，不关心内部。
• 战术层（L2）：聚焦核心域内关键服务交互。如[SeckillService] ↔ [InventoryService] ↔ [OrderService]，标注主要协议（gRPC/HTTP）和关键数据流（/seckill/buy,/inventory/deduct）。
• 实现层（L3）：针对单个服务，画其内部组件。如SeckillService内部：[API Gateway] → [Token Filter] → [Seckill Controller] → [Redis Client]，此时才出现具体技术栈（Spring Cloud, Lettuce）。
  实操心得：每次画图前，先问“这张图的目标读者是谁？他们最需要知道什么？”给CTO看L1，给开发看L2，给运维看L3。我们用Mermaid的subgraph语法实现分层，L1图里subgraph 电商核心域，L2图里subgraph SeckillService，层级清晰，切换自如。

5.2 问题二：图更新了，但代码没跟上，导致“图对代码错”

现象：某次上线后发现支付回调地址变了，但图中还是旧URL，测试按图写用例，结果全错。
根因分析：图和代码是两条独立维护线，缺乏强制同步机制。
解决方案：CI驱动的“图-代码一致性检查”
我们编写了一个Python脚本check_diagram_consistency.py，它做三件事：

1. 解析.mmd文件，提取所有click链接（如click A "https://github.com/.../service.py#L45"）；
2. 检查该URL对应的代码文件是否存在，且指定行号是否有函数定义（用AST解析）；
3. 检查图中标注的API路径（如POST /seckill/buy）是否在代码路由中真实存在。
   脚本集成到CI：

- name: Check Diagram Consistency run: python scripts/check_diagram_consistency.py docs/diagrams/ if: github.event_name == 'pull_request'

避坑技巧：脚本失败时，不仅报错，还自动生成修复建议。例如：“seckill-flow.mmd第12行click F指向risk_client.py#L12，但该行是注释，建议改为#L15（def call_risk_service():）”。这比单纯报错友好十倍。

5.3 问题三：多人协作时图版本混乱，不知道哪版是最新

现象：Confluence里有5个“订单流程图”页面，标题都叫“V2”，但内容不同。
根因分析：缺乏中心化、可追溯的存储和发布流程。
解决方案：Git作为唯一真相源 + 自动化发布

• 所有.mmd文件只存于代码仓库/docs/diagrams/，禁止上传到Confluence或邮件。
• 使用GitHub Actions，当/docs/diagrams/下文件变更时，自动：
  1. 渲染为PNG；
  2. 上传到GitHub Pages的/diagrams/目录；
  3. 在Confluence中用{html-include}宏嵌入<img src="https://org.github.io/diagrams/seckill-flow.png">。
     这样，Confluence页面显示的图永远是最新版，且点击图片可跳转到源.mmd文件。
     独家技巧：在每个.mmd文件头部添加YAML Front Matter，记录作者、审核人、生效日期：

--- author: "zhangsan" reviewer: "lisi" effective_date: "2024-05-20" ---

脚本可读取此信息，生成带水印的PNG（如“v1.2 | 张三审核 | 2024-05-20”），杜绝混淆。

5.4 问题四：老板要看“全局视图”，但Mermaid不支持超大图

现象：想画整个公司系统全景图，Mermaid渲染卡死，导出PDF模糊。
根因分析：Mermaid是文本渲染引擎，超大图超出其性能边界。
解决方案：分而治之 + SVG矢量导出

• 将全景图拆分为逻辑域：[用户域]、[交易域]、[履约域]、[数据域]，每个域用单独.mmd文件；
• 主图（system-overview.mmd）只画域间关系，用subgraph引用各域，例如：

  flowchart LR subgraph 用户域 A[App] --> B[Auth Service] end subgraph 交易域 C[Order Service] --> D[Payment Service] end A -->|HTTP| C

• 导出时，用mmdc -i system-overview.mmd -o overview.svg -t neutral生成SVG矢量图，无限缩放不失真，且可导入Figma做进一步美化。
  经验之谈：SVG不是终点，而是起点。我们把SVG上传到在线白板（如Miro），邀请所有干系人实时批注，把“看图”变成“共建图”，协作效率飙升。

5.5 问题五：如何向非技术人员解释 diagram-design 的价值？

现象：向市场、销售同事介绍时，他们觉得“不就是画图嘛，PPT也能画”。
破解之道：用他们的语言，讲他们的痛点
我不谈技术，而是举三个他们熟悉的例子：

• 例1（销售）：“您给客户演示产品时，说‘我们的系统很稳定’，客户问‘怎么稳定？’。如果有一张图，上面标着[订单服务：99.95% uptime]、[支付网关：5s超时自动降级]，客户立刻信服。图是您的技术信任状。”
• 例2（客服）：“用户投诉‘下单没反应’，您查日志要1小时。如果有一张图，标着[用户点击→API网关→订单服务→Redis]，客服按图索骥，5分钟定位到‘Redis连接池耗尽’，这就是您的服务提速器。”
• 例3（市场）：“竞品发布会说‘我们支持秒杀’，您能拿出一张图，清晰展示[10万QPS下，库存扣减、风控、支付如何协同不丢单]，这就是您的差异化武器。”
  效果：去年市场部用此法，成功将技术白皮书转化率提升300%，因为他们终于有了“可感知、可传播”的技术故事。

6. 工具链与生态整合：让 diagram-design 融入研发流水线

6.1 核心工具链：极简主义，拒绝臃肿

我坚持“够用就好”原则，整个工具链只有4个核心组件，全部开源免费：

• 绘图引擎：Mermaid（v10.9+），理由：语法简洁、社区庞大、VS Code插件成熟、CI友好。放弃PlantUML，因其语法更复杂，学习成本高。
• 编辑环境：VS Code + Mermaid Preview插件，实时渲染，Ctrl+Click跳转代码，效率拉满。
• 版本与协作：GitHub/GitLab，.mmd文件即代码，PR评审、git blame、分支管理，一切照旧。
• 发布与共享：GitHub Pages + 自定义CSS，自动渲染所有.mmd为响应式网页，手机也能看。

注意：我们禁用所有“图协作平台”（如Lucidchart在线版），因为它们制造数据孤岛，且无法与代码仓库联动。图必须是代码的一部分。

6.2 CI/CD深度集成：让图成为质量门禁

在GitLab CI中，我们设置了三道质量门禁，图不过，流水线停：

1. 语法门禁：mermaid-cli --validate seckill-flow.mmd，检查语法错误。
2. 契约门禁：python scripts/check_contracts.py seckill-flow.mmd，强制校验[SLA]、[失败策略]等标签是否存在。