aivfo-tl-3.0/项目文档/业务流程图/流程图制作规范-可复用模板.md

时差培养箱业务流程图制作规范（可复用模板）

用途：统一流程图制作标准，确保任何功能的流程图都能：

1. 100% 还原真实业务逻辑（包括分支、回流、异常路径）
2. 清晰展示三端联动（operate / control / front 的交互与影响）
3. 提供完整节点详情（每个节点的触发条件、执行逻辑、涉及数据、代码位置）
4. 自动布局不重叠（用 dagre 自动分层，不手写坐标，杜绝线条/元素重叠交叉）
5. 可拖拽 + 记忆位置（节点可拖动，位置自动存 localStorage，刷新后恢复）
6. 支持无限扩展（画布宽高不限，业务有多复杂流程图就撑多大）

⚠ 本规范 v2（2026-06-24 重写）：吸取第一版"手写坐标导致重叠乱"的教训， 改为 dagre 自动布局；分支从"藏在面板文字里"改为"真实画进图"；新增拖拽+localStorage。 标杆参考实现见第九章「参考示例」。

---

〇、最重要的三条铁律（先记这个）

1. 分支必须真实画进图——决策点（平衡vs开始、移植/冷冻/删除/作废）要在画布上真分叉成多个节点多条线，绝不能写成一个笼统节点 + 面板里一段"后续分支"文字。
2. 布局必须自动算（dagre），不手写坐标——手写 x/y 节点一多必然重叠交叉。用 dagre 分层布局打底，保证 0 重叠；用户再拖拽微调。
3. 右侧面板只放"本节点自己的细节"——不放分支（分支已经画在图上了）。面板=这步是什么/前置/触发/步骤/后端/数据/三端联动/代码位置。

---

一、流程图核心原则

1.1 真实性原则：不折叠、不简化

• ❌ 禁止把分支写成文字描述："点击后可选 A 或 B"
• ❌ 禁止把分支塞进详情面板的"后续分支"板块（v1 的错误做法，已废弃该板块）
• ✅ 必须在画布上画出真实的分支节点和分叉连线：决策节点下真分出多个子节点

1.2 完整性原则：覆盖所有路径

• 正常路径：用户正常操作的主流程（如：入箱→培养→拍照→看图→标记→结束）
• 分支路径：业务决策点的不同选择（如：平衡 vs 直接开始、移植 vs 冷冻 vs 删除 vs 作废）
• 异常路径：错误、失败、超时、权限不足等场景（如：硬件异常、校验失败、MQTT 超时）
• 回流路径：回到前面某步重新走（如：对焦失败→重新对焦、拍照失败→重试）

1.3 三端联动原则：明确跨端影响

每个操作都要说清楚：

• 本端做了什么（operate 点了按钮 / control 收到命令 / front 刷新界面）
• 触发了什么（调接口 / 发 MQTT / 改数据库 / 发 Kafka）
• 影响了哪些端（其他端的界面变化 / 状态变化 / 行为变化）

1.4 无限画布原则：不限宽高

• 流程往哪延伸就往哪画（上下左右+斜向都可以）
• 画布尺寸根据内容自动撑开（CSS 不设 max-width / max-height）
• 浏览器出现滚动条是正常的（不强制塞进一屏）

---

二、流程图结构规范

2.0 文件结构（4 个文件，必须同目录）

为了好维护、避免单文件过大被截断，拆成 4 个文件放同一目录：

文件	作用	大小参考
xxx流程图.html	骨架：顶栏+图例+画布+详情面板 DOM + 全部 CSS	~10KB
flow-data.js	数据：NODES（节点数组）+ EDGES（连线数组）	随业务
flow-render.js	引擎：dagre 布局 + 渲染 + 拖拽 + localStorage + 折线 + 面板	~14KB
dagre.min.js	自动布局库（离线内置，约 278KB，自包含 graphlib）	278KB

HTML 末尾按顺序引用：

<script src="dagre.min.js"></script>
<script src="flow-data.js"></script>
<script src="flow-render.js"></script>

dagre.min.js 来源：https://cdnjs.cloudflare.com/ajax/libs/dagre/0.8.5/dagre.min.js， 下载后放同目录即可离线用（已验证可用）。flow-render.js 里调 dagre.graphlib.Graph / dagre.layout。

2.1 主画布布局

┌────────────────────────────────────────────────┐
│  顶部固定栏：标题 + 图例 + [重置布局][适应屏幕][已保存] │
├────────────────────────────────────────────────┤
│  画布视口 viewport（可平移/滚轮缩放）：        │
│    world（transform 平移缩放）：              │
│      ├─ svg（直角折线连线，在节点下层）       │
│      └─ 节点（绝对定位，dagre 算坐标，可拖拽） │
│  右下角：缩放控制 [＋][百分比][－]            │
└────────────────────────────────────────────────┘
   右侧滑出：详情面板（点节点弹出）

2.2 节点样式规范（颜色 = 标杆实现实际用色）

类型	type	边框色	背景色	图标	说明
起止	start	#16A085	#E8F8F5	🥚/🔚	流程起点终点
operate	operate	#4A90E2	#EAF3FC	🖥️	操作端动作
control	control	#F39C12	#FEF5E7	⚙️	后台动作
front	front	#9B59B6	#F5EEF8	💻	管理端动作
判断分支	branch	#E67E22	#FDF2E9	❓	决策点（虚线边框）
异常	error	#E74C3C	#FDEDEC	⚠️	报警/失败

节点结构（由 JS 生成，宽度固定 200px，高度由内容自动量）：

<div class="flow-node operate" id="node-op-add">
  <div class="node-head"><span class="node-icon">🖥️</span><span class="node-title">新建患者入箱</span></div>
  <span class="node-tag">operate 操作端</span>
  <div class="node-brief">录入患者信息 + 选 16 孔位 + 受精方式</div>  <!-- 一句话摘要，画布上直接可见 -->
</div>

node-brief 很重要：画布上每个节点直接显示一句话摘要，不用点开就懂大概；点开才看完整详情。

2.3 连线样式规范（直角折线 + 4 种类型）

type	含义	颜色	线型
internal	本端内部流程	#7F8C8D 灰	实线
cross	跨端调用（API/MQTT/Kafka/DB同步）	#16A085 绿	虚线 6,5
error	异常/报警路径	#E74C3C 红	点线 2,4
loop	回流（回到前面某步/下一轮循环）	#E67E22 橙	点线 2,4

• 一律用直角折线（电路图风格），不用曲线：M sx,sy L sx,midY L ex,midY L ex,ey
• 连线在节点下层（z-index：svg=1，node=2），不遮挡节点
• 连线带文字标签（label），标签加白底矩形避免被线穿过
• 箭头用 SVG <marker>，每种 type 一个对应颜色的箭头

---

三、节点详情面板规范（右侧滑出）

v2 变更：从 10 个板块精简为 8 个。删掉了"后续分支"（分支改画进图）。 面板宽度 640px，从右滑出，点遮罩/ESC/×关闭。面板只讲这一个节点自己的事。

每个节点的 detail 对象字段（flow-data.js 里）与面板板块一一对应：

字段	面板板块	内容
desc	📋 这步是什么	一段大白话，说清这个节点干什么
pre	🔑 前置条件	数组，能进这步要满足的条件
trigger	🎯 触发方式	哪个界面哪个按钮 / 什么 MQTT / 什么循环触发
steps	🔄 操作步骤	数组，用户做什么 或 系统自动执行的步骤
backend	⚙️ 后端逻辑	代码层面做了什么（调接口/发MQTT/落库）
data	💾 数据/状态变化	数组，DB哪些表、内存哪些变量、UI怎么变
cross	🌐 三端联动	对象 {from, via, to[]}，没有跨端则 null（面板不显示该块）
code	📍 代码位置	数组，文件:行号 方法名 / 表名 / topic

3.1 节点数据完整示例（flow-data.js 里一个节点）

{
  id: 'op-start-dish', type: 'operate', icon: '▶️', title: '开始培养（保存）',
  brief: '落库 dish+embryo → 发 MQTT 通知 control',   // 画布上直接显示的一句话
  detail: {
    desc: '入箱的核心动作。前端校验后调 StartDishApi，后端把培养皿+每个胚胎落库，再发 MQTT StartDish 通知 control。',
    pre: ['表单校验通过（孔位≥1、必填非空）', '舱室=空闲', 'control 在线'],
    trigger: 'operate 入箱窗点【保存=开始培养】→ StartDish_Click',
    steps: ['前端校验必填项', '调 StartDishApi', '后端落库 dish 表+embryo 表', '后端发 MQTT StartDish'],
    backend: 'StartDish_Click → StartDishApi → dish/embryo 落库 → MqttSendRpc 发 MQTT StartDish',
    data: ['DB：dish 表插1条(培养中)，embryo 表插N条(state=0)', '舱状态：空闲→培养中'],
    cross: {
      from: 'operate 点【开始培养】',
      via: 'StartDishApi → dish/embryo 落库 → MQTT StartDish',
      to: ['control 收 MQTT → HouseBin.StartDish → 启动舱主循环',
           'front 设备管理：舱格变"培养中"',
           'operate 主界面：舱格变色+显示患者']
    },
    code: ['operate AddDishWindowView.xaml.cs:451 StartDish_Click',
           'control AppData.cs:1102 StartDish', 'DB dish/embryo 表']
  }
}

3.2 三端联动板块（cross）渲染成

本端：operate 点【开始培养】
  ↓ StartDishApi → dish/embryo 落库 → MQTT StartDish
影响：
  ▸ control 收 MQTT → HouseBin.StartDish → 启动舱主循环
  ▸ front 设备管理：舱格变"培养中"
  ▸ operate 主界面：舱格变色+显示患者

---

四、分支绘制规范（用数据表达，dagre 自动布局）

核心：分支不靠手画，而是在 EDGES 里写好"从哪个节点连到哪些节点"， dagre 自动算出分叉布局。你只管把分支的节点和连线定义对，图形自动成型。

4.1 二选一分支（如：先平衡 / 直接开始）

加一个 branch 类型判断节点，从它连出两条边到两个不同节点：

// 节点
{ id: 'br-balance-or-start', type: 'branch', title: '判断：先平衡？还是直接开始？', ... }
// 连线：判断节点 → 两条路
{ from: 'br-balance-or-start', to: 'op-balance',   type:'internal', label:'①点【平衡】' },
{ from: 'br-balance-or-start', to: 'op-start-dish', type:'internal', label:'②点【开始培养】' },

4.2 多路分支（如：移植/冷冻/删除/作废）

判断节点连出 N 条边到 N 个并排节点，dagre 自动把它们排成一排：

{ from: 'br-destination', to: 'op-transplant', type:'internal', label:'移植' },
{ from: 'br-destination', to: 'op-freeze',     type:'internal', label:'冷冻' },
{ from: 'br-destination', to: 'op-delete',     type:'internal', label:'删除' },
{ from: 'br-destination', to: 'op-invalid',    type:'internal', label:'作废' },
// 四个去向再汇合到"结束培养"
{ from: 'op-transplant', to: 'op-end', type:'internal' },
{ from: 'op-freeze',     to: 'op-end', type:'internal' },
{ from: 'op-delete',     to: 'op-end', type:'internal' },
{ from: 'op-invalid',    to: 'op-end', type:'internal' },

4.3 回流（如：换气完→回主循环、舱位释放→回主界面）

用 type:'loop'（橙色点线），从后面节点连回前面节点：

{ from: 'ctl-airswap', to: 'ctl-loop', type:'loop', label:'换气完→下轮' },
{ from: 'op-back-main', to: 'op-main', type:'loop', label:'舱位释放·可放下一个' },

4.4 异常旁路（如：拍照失败→报警）

用 type:'error'（红色点线），从主流程节点旁拉出到异常节点：

{ from: 'ctl-photo',  to: 'err-alarm', type:'error', label:'拍照失败' },
{ from: 'err-alarm',  to: 'op-main',   type:'error', label:'报警显示' },

4.5 跨端调用（如：operate→control）

用 type:'cross'（绿色虚线），表示经 API/MQTT/Kafka 到另一个端：

{ from: 'op-start-dish', to: 'ctl-recv', type:'cross', label:'MQTT StartDish' },
{ from: 'ctl-photo', to: 'op-detail', type:'cross', label:'Kafka→DB→轮询' },

要点：分支汇合点（如四去向都→结束培养）也用边表达，dagre 会自动收拢。 你不需要算任何坐标，只要边写对，图就对。

---

五、交互规范

5.1 节点交互

• 默认：显示图标+标题+类型标签+一句话摘要(brief)
• hover：阴影加深，z-index 提升
• 激活（点击）：边框高亮光圈，右侧滑出详情面板
• 拖拽：按住可拖动，连线实时跟随重绘；拖动距离>3px 算拖拽（不触发点击）

5.2 拖拽 + localStorage 记忆（v2 新增·关键）

• 每个节点可鼠标拖动，松手后自动存 localStorage（键名带版本号如 tl-flow-positions-v2）
• 下次打开自动恢复上次拖好的位置（没存过则用 dagre 初始布局）
• 顶栏 「重置布局」 按钮：清 localStorage + 重跑 dagre + 适应屏幕（拖乱了能救回来）
• 顶栏 「适应屏幕」 按钮：整图居中缩放到刚好看全
• 顶栏 「已自动保存」 状态提示：拖完闪一下"✓ 已保存位置"

5.3 画布平移 + 缩放

• 空白处按住拖动 = 平移整个画布
• 鼠标滚轮 = 以鼠标位置为中心缩放（0.3~2 倍）
• 右下角 [＋][－] 按钮 + 百分比显示
• 缩放/平移用 world 元素的 transform: translate() scale()

5.3 详情面板

• 从右侧滑出，宽 640px（max-width 92vw 适配小屏）
• 关闭：点遮罩 / 按 ESC / 点右上角 ×
• 标题带类型徽章（颜色=节点类型色）

5.4 连线绘制（直角折线）

• SVG 在节点渲染后动态读取节点真实坐标再画（保证对齐）
• 直角折线：M sx,sy L sx,midY L ex,midY L ex,ey
• A 在 B 上方 → A 底部出、B 顶部进；B 在 A 上方（回流）→ 反向；同层 → 走侧边
• 拖动节点时实时重绘所有连线（renderEdges()）

---

六、代码结构规范

6.1 三文件职责

• flow-data.js：只放数据，导出 NODES 和 EDGES 两个数组（见 3.1 / 第四章示例）
• flow-render.js：IIFE 包裹，按 8 步走：
  1. computeLayout()——dagre 算每个节点 {x,y}（先临时渲染量节点高度）
  2. loadSaved()——读 localStorage 覆盖坐标
  3. renderNodes()——绝对定位渲染节点 + 绑拖拽 + 绑点击
  4. renderEdges()——SVG 直角折线 + 箭头 + 标签
  5. makeDraggable()——拖拽 + 拖完 savePositions()
  6. 平移/缩放（wheel + 空白拖动 + 缩放按钮）
  7. 详情面板（showDetail / closeDetail / detailHTML）
  8. init()——串起来；重置布局/适应屏幕 按钮
• HTML：骨架 DOM（顶栏/viewport/world/svg/缩放/面板）+ 全部 CSS

6.2 节点/连线数据结构（⚠ 不含坐标，dagre 自动算）

const NODES = [
  {
    id: 'op-start-dish',          // 唯一ID，格式：端-功能-动作
    type: 'operate',              // start/operate/control/front/branch/error
    icon: '▶️',
    title: '开始培养（保存）',
    brief: '落库 dish+embryo → 发 MQTT 通知 control',  // 画布上直接显示
    detail: { desc, pre[], trigger, steps[], backend, data[], cross|null, code[] }  // 见第三章
  },
  // ... 没有 x/y！坐标由 dagre 算
];

const EDGES = [
  { from: 'op-start-dish', to: 'ctl-recv', type: 'cross', label: 'MQTT StartDish' },
  // type: internal(本端) / cross(跨端) / error(异常) / loop(回流)
  // label 可选
];

6.3 dagre 调用要点

const g = new dagre.graphlib.Graph();
g.setGraph({ rankdir: 'TB', nodesep: 60, ranksep: 90, marginx: 40, marginy: 40 });
g.setDefaultEdgeLabel(() => ({}));
NODES.forEach(n => g.setNode(n.id, { width: 200, height: 量出来的高度 }));
EDGES.forEach(e => g.setEdge(e.from, e.to));
dagre.layout(g);
g.nodes().forEach(id => { const nd = g.node(id); nodePos[id] = { x: nd.x - nd.width/2, y: nd.y - nd.height/2 }; });

---

七、制作清单（每次制作流程图必做）

7.1 前期准备

• 用 codegraph 挖通完整业务链路（从入口到出口，包括所有分支）
• 列出涉及的三端文件（operate / control / front 各有哪些文件参与）
• 列出涉及的数据表（哪些表会增删改查）
• 列出涉及的接口/MQTT（哪些 API / topic 会被调用）

7.2 节点设计

• 每个操作/判断/事件抽象成一个节点（含 branch 判断节点、error 异常节点）
• 唯一 ID（格式 端-功能，如 op-start-dish、ctl-loop、br-destination）
• 填 brief（画布一句话）+ 完整 detail（8 字段，见第三章）
• 不写坐标（dagre 自动算）

7.3 分支设计（画进图，不进面板）

• 每个决策点建一个 branch 节点
• 从决策节点连出多条 EDGES 到不同子节点（见第四章）
• 分支汇合点也用边连（dagre 自动收拢）
• 回流用 loop、异常旁路用 error、跨端用 cross

7.4 连线设计

• 每条边定 type（internal/cross/error/loop）+ 可选 label
• 检查 EDGES 里 from/to 的 id 都在 NODES 里存在（用脚本验，见 7.6）

7.5 三端联动设计

• 每个跨端节点的 detail.cross 写清 {from, via, to[]}
• 跨端用 cross 类型边在图上连出来

7.6 测试与验收（用脚本 + 浏览器双验）

• 脚本验数据：node 跑一遍，检查①边引用的节点都存在 ②id唯一 ③每个节点 detail 8字段齐 ④跑 dagre 布局0 重叠对
• 浏览器验视觉：Edge/Chrome headless 截图，确认布局整齐、分支并排、连线分类、颜色正确
• JS 语法：node --check flow-data.js / node --check flow-render.js
• 交互：点节点弹面板、拖动节点连线跟随、刷新后位置恢复、重置布局可救回
• 4 个文件在同一目录

验数据脚本（复用）：

node -e '
global.dagre=require("./dagre.min.js");
const src=require("fs").readFileSync("./flow-data.js","utf8").replace(/const NODES/,"NODES").replace(/const EDGES/,"EDGES");
global.NODES=[];global.EDGES=[];eval(src);
const ids=new Set(NODES.map(n=>n.id));let bad=0;
EDGES.forEach(e=>{if(!ids.has(e.from)){console.log("X起点:",e.from);bad++}if(!ids.has(e.to)){console.log("X终点:",e.to);bad++}});
const g=new dagre.graphlib.Graph();g.setGraph({rankdir:"TB",nodesep:60,ranksep:90});g.setDefaultEdgeLabel(()=>({}));
NODES.forEach(n=>g.setNode(n.id,{width:200,height:90}));EDGES.forEach(e=>{if(g.hasNode(e.from)&&g.hasNode(e.to))g.setEdge(e.from,e.to)});
dagre.layout(g);
const b=g.nodes().map(id=>{const n=g.node(id);return{id,x:n.x-100,y:n.y-45,w:200,h:90}});let ov=0;
for(let i=0;i<b.length;i++)for(let j=i+1;j<b.length;j++){const a=b[i],c=b[j];if(a.x<c.x+c.w&&a.x+a.w>c.x&&a.y<c.y+c.h&&a.y+a.h>c.y)ov++}
console.log("节点",NODES.length,"边",EDGES.length,"坏引用",bad,"重叠",ov,(ov===0&&bad===0)?"[OK]":"[!]");
'

---

八、常见错误与纠正

❌ 错误 1：把分支写成文字 / 塞进面板（v1 最大的坑）

错：一个"标记胚胎去向"节点，分支写在面板"后续分支"里：移植/冷冻/删除/作废。 纠正：建 br-destination 判断节点，画布上真分出 4 个并排节点 + 4 条边（见 4.2）。

❌ 错误 2：手写节点坐标导致重叠交叉（v1 第二大坑）

错：每个节点写死 x:200, y:100，节点一多线条到处交叉。 纠正：删掉所有坐标，用 dagre 自动分层布局（见 6.3），脚本验证 0 重叠。

❌ 错误 3：详情面板内容不完整

缺前置条件/缺三端联动/缺代码位置。纠正：严格按第三章 8 字段填。

❌ 错误 4：连线颜色/线型不区分

所有线一个样 → 看不出本端还是跨端。纠正：按 2.3 用 4 种 type 区分颜色+线型。

❌ 错误 5：单文件塞太多导致写入被截断

错：节点详情多了，单个 HTML 几千行，一次写容易断。 纠正：拆 4 文件（见 2.0），数据(flow-data.js)和引擎(flow-render.js)分开，分批追加。

---

九、参考示例（标杆实现，照着抄）

标杆：培养全流程图（本规范 v2 配套，桌面）

• 文件（4 个，同目录）：
  • 时差培养箱-培养全流程详图.html（骨架+CSS）
  • flow-data.js（23 节点 + 39 连线）
  • flow-render.js（dagre+拖拽+localStorage+折线+面板）
  • dagre.min.js（布局库）
• 覆盖：入箱→平衡分支/直接开始→control 舱主循环(换气/对焦/拍照三分支)→看图→胚胎去向四分支→结束→回主界面回流；异常报警旁路；front 旁路联动
• 特点：dagre 0 重叠、分支真画进图、可拖拽记忆位置、直角折线、三端配色
• 验证：脚本(0坏引用/0重叠/detail齐) + Edge headless 截图均通过

下次做新功能流程图：复制这 4 个文件，改 flow-data.js 的 NODES/EDGES， HTML 改标题，flow-render.js 基本不用动。改完跑 7.6 的验证脚本。

---

十、总结

✅ 记住这几条，流程图就不会出错：

1. 分支真实画进图（建 branch 节点 + 多条边，不写进面板文字）
2. 坐标交给 dagre（不手写 x/y，杜绝重叠交叉）
3. 详情面板写全 8 字段（desc/pre/trigger/steps/backend/data/cross/code）
4. 三端联动说清楚（cross 字段：谁触发→经过什么→影响谁）
5. 连线分 4 类（internal/cross/error/loop，颜色+线型区分）
6. 拖拽+localStorage（可微调 + 记忆位置 + 重置可救回）
7. 拆 4 文件 + 脚本验证（避免截断，保证 0 重叠 0 坏引用）

📌 每次制作前先读这份规范，制作后跑 7.6 验证脚本。直接复制第九章标杆 4 文件改最省事。