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

> **用途**：统一流程图制作标准，确保任何功能的流程图都能：
> 1. **100% 还原真实业务逻辑**（包括分支、回流、异常路径）
> 2. **清晰展示三端联动**（operate / control / front 的交互与影响）
> 3. **提供完整节点详情**（每个节点的触发条件、执行逻辑、后续分支、涉及数据、代码位置）
> 4. **支持无限扩展**（画布宽高不限，业务有多复杂流程图就撑多大）

---

## 一、流程图核心原则

### 1.1 真实性原则：不折叠、不简化
- ❌ **禁止**把分支写成文字描述："点击后可选 A 或 B"
- ✅ **必须**画出真实的分支路径：主干下方真实分叉，左边一路走 A，右边一路走 B

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

### 1.3 三端联动原则：明确跨端影响
每个操作都要说清楚：
- **本端做了什么**（operate 点了按钮 / control 收到命令 / front 刷新界面）
- **触发了什么**（调接口 / 发 MQTT / 改数据库 / 发 Kafka）
- **影响了哪些端**（其他端的界面变化 / 状态变化 / 行为变化）

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

---

## 二、流程图结构规范

### 2.1 主画布布局
```
┌────────────────────────────────────────────────┐
│  顶部固定栏：标题 + 导航 + 图例               │
├────────────────────────────────────────────────┤
│                                                │
│  流程画布（无限宽高，可滚动）：               │
│    ├─ 节点（圆角矩形，点击弹详情面板）       │
│    ├─ 连线（SVG，不同颜色区分本端/跨端）     │
│    └─ 分支（水平并排 / 树形分叉 / 回流箭头） │
│                                                │
└────────────────────────────────────────────────┘
```

### 2.2 节点样式规范

#### 节点类型与颜色
- **operate 端节点**：蓝色边框 `#4A90E2`，浅蓝背景 `#E3F2FD`，图标 🖥️
- **control 端节点**：橙色边框 `#FF9800`，浅橙背景 `#FFF3E0`，图标 ⚙️
- **front 端节点**：紫色边框 `#9C27B0`，浅紫背景 `#F3E5F5`，图标 💻
- **分支决策节点**：琥珀色边框 `#FFA726`，琥珀背景 `#FFF8E1`，图标 ❓
- **异常节点**：红色边框 `#F44336`，浅红背景 `#FFEBEE`，图标 ⚠️

#### 节点内容
```html
<div class="flow-node" data-node-id="operate-add-dish">
  <div class="node-icon">🖥️</div>
  <div class="node-title">新建患者入箱</div>
  <div class="node-tag">operate 端</div>
</div>
```

### 2.3 连线样式规范

#### 连线类型与颜色
- **本端流程**：实线 `stroke-width: 2px`
  - operate 内部：`#4A90E2` 蓝色
  - control 内部：`#FF9800` 橙色
  - front 内部：`#9C27B0` 紫色
- **跨端调用**：虚线 `stroke-dasharray: 5,5`
  - 调接口/发 MQTT：`#4CAF50` 绿色
  - 同步通知：`#00BCD4` 青色
- **异常路径**：虚线 `stroke-dasharray: 3,3`
  - 报警/失败：`#F44336` 红色

#### 箭头样式
```svg
<marker id="arrowhead" markerWidth="8" markerHeight="6">
  <polygon points="0 0, 8 3, 0 6" fill="继承连线颜色"/>
</marker>
```

---

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

### 3.1 面板结构
点击任意节点，右侧滑出详情面板，必须包含以下板块：

#### 📋 板块 1：节点基本信息
```markdown
【节点标题】新建患者入箱

【所属端】operate 操作端

【这步是什么】
医生在空舱点击，弹窗录入患者信息（夫妻姓名/病例号/周期/受精方式），
选 16 孔位放哪些胚胎，可选先平衡或直接开始培养。
```

#### 🔑 板块 2：前置条件（能进这步的条件）
```markdown
【前置条件】
✓ 舱室状态 = 空舱（无培养皿）
✓ 用户已登录且有操作权限
✓ control 后台已启动、该舱硬件正常（串口/相机/电机正常）
```

#### 🎯 板块 3：触发方式 / 界面位置
```markdown
【触发方式】
- operate 主界面（A2）点某个空舱格 → 弹 AddDishWindowView 弹窗
- 或 front 设备管理（D3）点空舱格 → 弹 AddDishWindow
```

#### 🔄 板块 4：交互步骤（用户做什么）
```markdown
【交互步骤】
1. 在 16 孔圆周上点选要放胚胎的孔位（可多选）
2. 填写表单：病例号、周期、女方/男方姓名、出生年月日、受精时间、受精方式
3. 可选：勾选"重点关注"（VIP）
4. 底部两个按钮：
   - 【平衡】→ 先启动平衡流程（见分支 A）
   - 【保存（开始培养）】→ 直接开始培养（见分支 B）
```

#### ⚙️ 板块 5：后端逻辑（代码做了什么）
```markdown
【后端逻辑】
1. operate 前端校验：必填项非空、孔位至少选一个、受精时间合法
2. 调接口：StartDishApi（POST /api/dish/start）
   - 参数：舱号、患者信息、选中孔位列表、是否 VIP
   - 后端落库：dish 表（培养皿）、embryo 表（胚胎，每个选中孔一条）
3. 发 MQTT 命令：topic `tl/command/{tlSn}`, type=StartDish
   - control 后台收到 → AppData.StartDish → 舱状态改"培养中"
   - 启动对焦+拍照节拍（见 C6 舱主循环）
```

#### 💾 板块 6：涉及数据 / 状态变化
```markdown
【涉及数据】
- 数据库：dish 表插入一条（status=培养中），embryo 表插入 N 条
- 内存：HouseBin.CurrentDish 设为新 dishId，IsWorking=true
- 舱室状态：空闲 → 培养中（主界面该舱格变色+显示患者信息）
```

#### 🌐 板块 7：三端联动影响（核心）
```markdown
【三端联动影响】
本端动作：operate 点"开始培养"按钮
    ↓ 触发
后端/中间件：StartDishApi → dish 表插入 → MQTT 发 StartDish 命令
    ↓ 通知
control 后台：收到 MQTT → AppData.StartDish → HouseBin 状态改"培养中" → 启动对焦拍照循环
    ↓ 同步到
front 管理端：
  - D3 设备管理首页：该舱格状态变"培养中"，显示患者信息
  - D7 培养记录列表：新增一条记录
    ↓ 反向影响
本端界面：A2 主界面该舱格变色+显示患者姓名
```

#### 🔀 板块 8：后续分支（接下来会走哪）
```markdown
【后续分支】
→ 分支 A：点了"平衡"
   → 启动平衡流程（换气若干轮，duration 可配置）
   → 手动点"结束平衡"
   → 再点"开始培养"
   → 进入分支 B

→ 分支 B：点了"保存（开始培养）"
   → control 收到 StartDish
   → 进入 C6 舱主循环（温压监测 → 判断是否对焦 → 判断是否拍照）
```

#### ⚠️ 板块 9：异常分支 / 边界情况
```markdown
【异常分支】
- 若该舱硬件异常（串口断/相机丢失）→ 前端提示"该舱室不可用"，操作失败
- 若 control 后台未启动 → 前端提示"设备离线"
- 若正在平衡中又点"开始培养" → 校验失败，提示"请先结束平衡"
```

#### 📍 板块 10：代码位置
```markdown
【代码位置】
- operate 前端：AddDishWindowView.xaml.cs:451 StartDish_Click
- operate 接口调用：StartDishApi (Urls.cs + ApiService)
- control 后台：AppData.cs:1102 StartDish → HouseBin.cs:614 MainThread
- 数据库表：dish、embryo、house_state
- MQTT topic：tl/command/{tlSn}
```

---

## 四、分支绘制规范

### 4.1 水平并排分支（两条平行路径）
```
         主干
          ↓
    ┌─────┴─────┐
    ↓           ↓
  分支A       分支B
  (冷冻)      (鲜胚移植)
    ↓           ↓
  [节点]      [节点]
```

**适用场景**：两条独立且平行的路径（如冷冻 vs 鲜胚移植）

### 4.2 树形分叉（多条分支）
```
         主干
          ↓
    ┌─────┼─────┐
    ↓     ↓     ↓
  分支A  分支B  分支C
  (移植) (冷冻) (删除)
```

**适用场景**：三条及以上分支（如胚胎去向：移植/冷冻/删除/作废）

### 4.3 回流路径（回到前面某步）
```
  [对焦] → [拍照]
     ↑        ↓
     └←─[失败重试]
```

**适用场景**：失败重试、循环逻辑（如对焦失败→重新对焦）

### 4.4 条件分支（if-else）
```
       [判断条件]
         ↙   ↘
    [条件成立]  [条件不成立]
```

**适用场景**：业务判断（如：是否首次对焦、是否到达拍照时间）

---

## 五、交互规范

### 5.1 节点点击
- **默认状态**：节点显示标题+图标+标签
- **hover 状态**：节点放大 1.05 倍，出现阴影 `box-shadow: 0 4px 12px rgba(0,0,0,0.15)`
- **激活状态**：节点放大 1.12 倍，边框加粗，右侧滑出详情面板

### 5.2 详情面板
- **滑出动画**：从右侧滑入，transition 0.3s ease
- **面板宽度**：固定 `600px`（不遮挡主画布）
- **关闭方式**：点击面板外区域 / 按 ESC 键 / 点右上角 × 按钮

### 5.3 连线绘制
- **使用 SVG**：动态计算节点中心点坐标，绘制路径
- **路径算法**：
  - 直线：`M x1,y1 L x2,y2`
  - 折线：`M x1,y1 L x1,midY L x2,midY L x2,y2`（适用跨模块）
  - 曲线：`M x1,y1 Q cpX,cpY x2,y2`（适用回流）

---

## 六、代码结构规范

### 6.1 HTML 结构
```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>时差培养箱 - [功能名]业务流程图</title>
  <style>
    /* CSS 变量定义颜色 */
    :root {
      --operate-color: #4A90E2;
      --control-color: #FF9800;
      --front-color: #9C27B0;
      --branch-color: #FFA726;
      --error-color: #F44336;
    }
    /* 流程图容器：无限宽高 */
    .flow-container {
      position: relative;
      min-width: 100vw;
      min-height: 100vh;
      padding: 100px;
    }
  </style>
</head>
<body>
  <!-- 顶部固定栏 -->
  <header class="top-bar">
    <h1>时差培养箱 - [功能名]业务流程图</h1>
    <nav><!-- 导航按钮 --></nav>
  </header>
  
  <!-- 流程画布 -->
  <div class="flow-container" id="flowContainer">
    <svg id="svgLines"></svg>
    <!-- 节点由 JS 动态生成 -->
  </div>
  
  <!-- 详情面板 -->
  <div class="detail-panel" id="detailPanel">
    <!-- 动态填充 -->
  </div>
  
  <script>
    // 节点数据 + 绘制逻辑
  </script>
</body>
</html>
```

### 6.2 节点数据结构
```javascript
const flowData = {
  nodes: [
    {
      id: 'operate-add-dish',
      type: 'operate',  // operate / control / front / branch / error
      title: '新建患者入箱',
      icon: '🖥️',
      x: 200,  // 绝对坐标
      y: 100,
      detail: {
        description: '医生在空舱点击，弹窗录入患者信息...',
        preconditions: ['舱室状态=空舱', '用户已登录'],
        trigger: 'operate 主界面点空舱格',
        steps: ['选孔位', '填表单', '点保存'],
        backend: 'StartDishApi → dish表插入 → MQTT发StartDish',
        dataChanges: ['dish表插入', 'HouseBin.CurrentDish设值'],
        crossPlatform: {
          from: 'operate 点按钮',
          to: ['control 收到MQTT启动对焦拍照', 'front 界面显示新记录']
        },
        nextBranches: ['平衡流程', '直接开始培养'],
        exceptions: ['硬件异常', 'control离线'],
        codeLocation: ['AddDishWindowView.xaml.cs:451', 'AppData.cs:1102']
      }
    }
  ],
  edges: [
    {
      from: 'operate-add-dish',
      to: 'control-start-dish',
      type: 'mqtt',  // internal / api / mqtt / sync / error
      label: 'MQTT StartDish'
    }
  ]
};
```

---

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

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

### 7.2 节点设计
- [ ] 每个操作/判断/事件都抽象成一个节点
- [ ] 给每个节点定义唯一 ID（格式：`端-功能-动作`，如 `operate-add-dish-save`）
- [ ] 给每个节点填写完整的 10 个板块内容（见第三章）
- [ ] 确认每个节点的前驱节点和后继节点

### 7.3 分支设计
- [ ] 列出所有决策点（用户选择 / 业务判断 / 异常分叉）
- [ ] 每个决策点画出真实的分支路径（不折叠成文字）
- [ ] 确认分支的汇合点（是否回到主干 / 各走各的 / 结束流程）

### 7.4 连线设计
- [ ] 用不同颜色区分本端流程 / 跨端调用 / 异常路径
- [ ] 回流路径用曲线 + 箭头清晰标注方向
- [ ] 跨模块连线用折线（避免直线穿过其他节点）

### 7.5 三端联动设计
- [ ] 每个跨端操作都明确：谁触发 → 经过什么 → 影响谁
- [ ] 在详情面板的"三端联动影响"板块写清楚完整链路
- [ ] 用不同颜色连线体现三端关系

### 7.6 测试与验收
- [ ] 点击每个节点，详情面板能正常弹出
- [ ] 详情面板的 10 个板块内容都完整
- [ ] 所有分支路径都画出来了（没有折叠成文字）
- [ ] 异常路径、回流路径都标注清楚
- [ ] 三端联动的影响都写明白了
- [ ] 画布能正常滚动（宽高没限制死）

---

## 八、常见错误与纠正

### ❌ 错误 1：把分支写成文字
```
[入箱] → [点击后可选：平衡 或 直接开始培养] → [开始培养]
```
**纠正**：必须画出真实分支
```
         [入箱]
          ↓
    ┌─────┴─────┐
    ↓           ↓
 [平衡]    [直接开始培养]
    ↓           ↓
[结束平衡]      ↓
    ↓           ↓
    └─────┬─────┘
          ↓
     [开始培养]
```

### ❌ 错误 2：详情面板内容不完整
**常见缺失**：
- 缺前置条件（不知道什么时候能进这步）
- 缺三端联动（不知道影响了哪些端）
- 缺异常分支（不知道失败了怎么办）
- 缺代码位置（不知道去哪改）

**纠正**：严格按第三章的 10 个板块填写

### ❌ 错误 3：连线颜色不区分
**所有连线都一个颜色** → 看不出哪些是本端流程、哪些是跨端调用

**纠正**：按第 2.3 节规范，用不同颜色 + 线型区分

### ❌ 错误 4：画布限制死宽高
```css
.flow-container {
  width: 1920px;  /* ❌ 限死了 */
  height: 1080px; /* ❌ 限死了 */
  overflow: hidden; /* ❌ 超出部分被裁 */
}
```

**纠正**：使用 `min-width` / `min-height` + 允许滚动
```css
.flow-container {
  min-width: 100vw;
  min-height: 100vh;
  /* 不设 max-width / max-height */
}
```

---

## 九、参考示例

### 示例 1：完整的"入箱→培养→拍照→看图→标记→结束"流程图
- 文件：`时差培养箱-培养全流程详图.html`（本次制作）
- 特点：覆盖正常路径、分支路径、异常路径、回流路径、三端联动

### 示例 2：参考模板（flow-click.html）
- 位置：`C:/Users/AIVFO/Desktop/flow-click.html`
- 特点：点击节点弹浮动面板、多条并行分支、SVG 连线

---

## 十、总结

✅ **记住这三点，流程图就不会出错**：
1. **分支必须真实画出来**（不折叠成文字）
2. **详情面板必须写全 10 个板块**（不漏掉任何一项）
3. **三端联动必须说清楚**（谁触发→经过什么→影响谁）

📌 **每次制作前，先读这份规范，制作时对照清单逐项检查。**