![\"ice](\"./examples/assets/ice-entity-designer.png\")
\n\n \n
基于 ice-render 的可视化建模工具集：一套引擎承载 9 个域包 —— ER、流程图、BPMN 2.0、UML 类图、状态机、甘特、电力一次、电力二次、给水排水。
\n\n> 变更日志见 [CHANGELOG.md](./CHANGELOG.md)。\n\n\n ![\"license\"](\"https://img.shields.io/badge/license-MIT-047857.svg\"){kind=icon}
\n ![\"engine](\"https://img.shields.io/badge/engine-bundled-047857.svg\"){kind=icon}
\n ![\"domain](\"https://img.shields.io/badge/domain%20packs-9-047857.svg\"){kind=icon}
\n ![\"tests\"](\"https://img.shields.io/badge/jest-398%20passed-047857.svg\"){kind=icon}
\n ![\"typescript\"](\"https://img.shields.io/badge/TypeScript-4.6-3178c6.svg\"){kind=icon}
\n
![\"ER](\"./examples/assets/overview.png\")
\n\n实体字段与约束标记：\n\n![\"实体字段与约束\"](\"./examples/assets/fields.png\")
\n\n关系语义：自引用、多对多、一对一：\n\n![\"关系语义\"](\"./examples/assets/relations.png\")
\n\n交互式编辑器（右侧面板可直接切换到「TypeORM Schema」查看导出结果）：\n\n![\"交互式编辑器与](\"./examples/assets/editor.png\")
\n\n同一套内核也能承载**流程图**（`examples/flowchart-editor.html`）：四类节点（开始/结束、处理、判定、输入/输出，\n其中判定菱形与输入输出平行四边形是自定义 `ICEPath` 形状）、正交/贝塞尔连线 + 分支标签（是/否）、\n拖拽 / 连线 / 撤销重做 / 快照存取：\n\n![\"流程图编辑器示例\"](\"./examples/assets/flowchart-editor.png\")
\n\n再加一层业务记法就是 **BPMN 2.0**（`examples/bpmn-editor.html`）：池 / 泳道真嵌套（拖动银行池，内部泳道、\n任务和连线一起平移）、事件 / 网关 / 任务角标 / 数据对象 / 注释、顺序流 + 条件与默认流标记、\n跨池的消息流，右侧面板按图元类型给出网关类型、事件种类、任务类型等属性，并内置语义校验与 BPMN 2.0 XML 导出：\n\n![\"BPMN](\"./examples/assets/bpmn-editor.png\")
\n\n同一套引擎继续承载 **UML 类图**（`examples/uml-editor.html`）—— 三段式类框、六种关系、继承成环校验，\n以及 PlantUML / Mermaid 类图文本互操作：\n\n![\"UML](\"./examples/assets/uml-editor.png\")
\n\n**状态机**（`examples/statechart-editor.html`）—— 伪状态、普通状态、**复合状态容器**（拖动父容器时子状态跟随），\n转移标签写作 `事件 [守卫] / 动作`：\n\n![\"状态机编辑器示例\"](\"./examples/assets/statechart-editor.png\")
\n\n**甘特图**（`examples/gantt-editor.html`）—— 时间轴与按天吸附、依赖线、自动排程与关键路径、\n资源冲突校验、Mermaid gantt 文本互操作：\n\n![\"甘特编辑器示例\"](\"./examples/assets/gantt-editor.png\")
\n\n**电力一次系统图**（`examples/power-editor.html`）—— 110kV 双母线 + 10kV 单母线分段、69 台设备；\n开关分合、带电分析与电压色标、五防相关校验、SVG / JSON 导出：\n\n![\"电力一次系统图（单线图）编辑器示例\"](\"./examples/assets/power-editor.png\")
\n\n**电力二次回路**（`examples/secondary-editor.html`）—— 保护电流回路：CT 二次绕组 → 三相电流回路 →\n端子排 → 保护装置，N 侧接地；端子排是真容器 —— 拖动跟随、快照往返不丢：\n\n![\"电力二次回路编辑器示例\"](\"./examples/assets/secondary-editor.png\")
\n\n**给水排水工艺流程图**（`examples/water-editor.html`）—— 10 万 m³/d 市政污水厂 AAO 案例：\n进水 → 格栅 → 曝气沉砂池 → 初沉池 → 厌氧 / 缺氧 / 好氧 → 二沉池 → 混凝沉淀 → 滤池 → 消毒 → 在线监测 → 排放，\n再加混合液内回流、污泥回流与剩余污泥线（浓缩 → 脱水 → 外运）。管线按介质着色并标注管径，\n右侧「工艺校验」查进出线 / 介质管径 / 在线监测 / 污泥出路 / 内回流，「流径分析」看关阀之后通不通：\n\n![\"给水排水工艺流程图编辑器示例（市政污水厂](\"./examples/assets/water-editor.png\")
\n\n## 4. 快速开始\n\n```bash\nnpm install\nnpm run build\n```\n\n可运行的示例（`examples/` 下的页面加载上一级 `dist` 与本仓 `node_modules`，建议通过静态服务器打开）：\n\n| 示例 | 说明 |\n|---|---|\n| `examples/entity-editor.html` | 交互式编辑器：实时编辑字段、创建/删除实体与关系、校验与保存加载；右侧面板含「TypeORM Schema」标签页 |\n| `examples/flowchart-editor.html` | 流程图编辑器：四类节点形状、拖拽、连线（含分支标签）、撤销重做、localStorage 存取与 JSON 导出；纯 DOM 面板，只依赖 `dist` 产物 |\n| `examples/bpmn-editor.html` | BPMN 2.0 编辑器：信用卡申请审批案例（两个池 / 三条泳道）、八类图元、条件与默认流标记、语义校验、BPMN 2.0 XML 导入导出 |\n| `examples/uml-editor.html` | UML 类图编辑器：三段式类框、六种关系、语义校验、矢量导出、PlantUML / Mermaid 文本互操作 |\n| `examples/statechart-editor.html` | 状态机编辑器：伪状态 / 普通状态 / 复合状态容器、转移标签 `事件 [守卫] / 动作` |\n| `examples/gantt-editor.html` | 甘特编辑器：时间轴与按天吸附、依赖线、自动排程、关键路径、资源冲突校验、矢量导出 |\n| `examples/power-editor.html` | 电力一次系统图（单线图）编辑器：110kV 变电站案例（**110kV 双母线 + 10kV 单母线分段**两级电压，两回进线 / 两台主变 / 母联 / 母线 PT / 4 条 10kV 出线 / 电容器组 / 站用变，共 69 台设备），开关分合、带电分析与色标、五防相关校验 |\n| `examples/water-symbols.html` | 给排水符号图例：38 种符号一页看全（位号在上 / 名称在下 / 图形居中），可导出 SVG 作交底或评审用 |\n| `examples/water-editor.html` | 给水排水工艺流程图：市政污水厂 AAO 工艺（19 个符号 / 21 条管线），介质 + 管径标注、工艺校验（进出线 / 在线监测 / 污泥出路 / 内回流）、流径分析与阀门工况、矢量导出 |\n| `examples/secondary-editor.html` | 电力**二次回路**（简化版）：110kV 线路保护电流回路 —— CT 三个二次绕组 → 三相电流回路（A411/B411/C411 + N411）→ 端子排（201～204）→ 线路保护装置，N 侧接地；二次校验（回路编号 / 三相成组 / 端子号唯一 / 必须接地） |\n| `examples/power-symbols.html` | 电力符号表：23 种一次设备符号（记法对齐 JB/T 5872-1991 与 GB/T 4728.1/3/4/6），可缩放平移、导出 SVG |\n| [`ice-entity-designer-react-demo`](../ice-entity-designer-react-demo) | 独立的 React 集成示例工程（webpack + TypeScript），涵盖 ref / hook / onChange / 受控模式 |\n\n```bash\npython3 -m http.server 8899 # 然后访问 http://localhost:8899/examples/entity-editor.html\n```\n\n## 5. 使用方式\n\n`EntityDesigner` 是 Entity / Relation 之上的轻量应用层，负责把建模交互闭环串起来：\n\n```js\nimport { ICE, EntityDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst designer = new EntityDesigner(ice);\n\n// 建模：创建实体与关系\nconst user = designer.createEntity({ entityName: 'User' });\nconst role = designer.createEntity({ entityName: 'Role' });\ndesigner.createRelation({\n sourceId: user.state.id,\n targetId: role.state.id,\n relationType: 'many-to-many',\n joinTableName: 'user_roles',\n linkShape: 'bezier', // 连线形态：'visio'（默认，正交折线）| 'bezier'（贝塞尔曲线）\n});\n\n// 导出与校验\nconst schema = designer.toSchemaObject(); // TypeORM Schema（对象）\nconst schemaText = designer.toSchemaString(); // TypeORM Schema（JSON 字符串）\nconst issues = designer.validate(); // 校验问题列表\n\n// 项目存取与历史\nconst snapshot = designer.serializeProject();\nconst report = designer.loadProject(snapshot); // 非法 / 版本不兼容的快照会抛错，且不会改动当前项目与历史栈\n// report = { loaded, entities, relations, unknownTypes, skipped }\ndesigner.undo();\n```\n\n#### 5.1 项目快照契约\n\n- 快照带 `schemaVersion`（当前 `1`）与每个节点的 `typeId`；载入时**按 `typeId` 分派构造函数**（走 ICE 注册表，下游 `ice.registerType()` 注册的领域图元同样可载入）。旧快照没有 `typeId` 时，按所在数组归位（`entities[]` → `Entity`，`relations[]` → `Relation`）。\n- 快照带 `createTime`（ISO 8601 UTC，如 `2026-09-13T07:15:45.655Z`）= 这份项目**首次创建**的时刻：\n 首次写出即定下并记在 `ice.documentMeta` 上（因此同一会话反复 `serializeProject()` 结果稳定，undo/redo 的快照回放依赖这一点），\n 载入别人的快照时读回来，于是「打开 → 编辑 → 保存」不会被改写；缺失 / 脏值（例如旧的\n `2022/1/1 00:00:00`）会归一化成 ISO 或回退到当前时刻。**没有 `lastModifyTime`**——每次写出都会变，\n 留着会破坏「两次序列化结果相同」的契约。\n- **`typeId` 一律是 `namespace:Type` 格式**（2026-09-13 起）：本包的领域图元统一用 `ice-entity-designer:*`\n （`ice-entity-designer:Entity`、`ice-entity-designer:FlowNode`、`ice-entity-designer:GanttTask`…），\n 与引擎内置的 `ice-render:*`、图表的 `ice-chart:*` 分属不同命名空间，因此**跨包不会撞名**。\n 注册走 `registerIEDType()`（`src/utils/type-registry.ts`）；**不做旧名兼容**（家族仍在发布初期），\n 旧快照里的 `Entity`、`FlowNode` 之类无 namespace 值会被当作未注册类型跳过并记入 `report.unknownTypes`。\n 判型不要拿字面量与 `typeId` 比：用 `x instanceof FlowNode` 或 `selected.constructor.typeId === FlowNode.typeId`。\n- **容错加载**：遇到未注册的 `typeId` 只跳过该节点并记录（`report.unknownTypes` / `report.skipped`），不会让整份数据打不开——与引擎 `Deserializer` 的语义一致。\n- **自洽保证**：`serializeProject()` 的产物永远能通过 `loadProject()` 的结构校验（结构契约见 `src/utils/project-snapshot.schema.json`）；载入失败时当前项目与 `undo`/`redo` 栈都不会被改动。\n- **唯一字段定义**：快照写什么、校验查什么，都由 `src/utils/project_codec.ts` 的一份定义驱动（不再 snapshot 一份、validator 一份）。新增 state 字段却忘了登记时，`tests/designer/codec-completeness.test.ts` 会以「未覆盖的 state 键」直接报红。\n- **自定义 JSON 透传**：应用层把业务元数据挂在 `node.state.data` 上即可，它会原样写进快照并在载入时回填（与引擎序列化对 `state` 的处理一致）。\n\n也支持更底层的组件式用法：\n\n```js\nconst schema = IED.toSchemaObject(ice.childNodes);\nconst schemaText = IED.toSchemaString(ice.childNodes);\n```\n\n导出的对象可直接构造 TypeORM 实体：\n\n```js\nimport { EntitySchema } from 'typeorm';\n\nconst schemas = designer.toSchemaObject().map((obj) => new EntitySchema(obj));\n```\n\n#### 5.2 流程图（FlowDesigner）\n\n包内除 ER 之外还内置了一套**流程图**领域图元与应用层（同一个 `ice` 实例即可承载）：\n\n```js\nimport { ICE, FlowDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst flow = new FlowDesigner(ice);\n\nconst start = flow.createNode('terminator', { title: '开始' });\nconst check = flow.createNode('decision', { title: '库存充足？' });\nflow.createEdge({ sourceId: start.state.id, targetId: check.state.id, sourcePort: 'B', targetPort: 'T' });\n\nflow.fitViewport(); // 适应视图\nflow.serialize(); // 流程图快照（version / kind / nodes / edges）\nflow.undo(); // 100 步历史\n```\n\n| 能力 | API |\n|---|---|\n| 节点类型 | `createNode('terminator' \\| 'process' \\| 'decision' \\| 'io', props)`；预设尺寸 / 配色见 `FLOW_NODE_KINDS` |\n| 连线 | `createEdge({ sourceId, targetId, sourcePort, targetPort, label, linkShape })`；插槽位置 `T/R/B/L/C`，节点拖动时连线自动跟随 |\n| 样式 | 节点：`fillColor` / `strokeColor` / `textColor` / `fontSize`（`updateNode` 即时生效）；连线：`style.strokeStyle`（线色，同时作为箭头填充）/ `style.lineWidth`、`labelStyle.fillStyle`（标签颜色），全部随快照存取 |\n| 增删改查 | `nodes` / `edges` / `selected` / `select()` / `updateNode()` / `updateEdge()` / `remove()`（删节点级联删连线）/ `clear()` |\n| 历史与快照 | `undo()` / `redo()` / `canUndo()` / `canRedo()`、`serialize()` / `toSnapshot()` / `load()`（返回 `{ loaded, nodes, edges, skipped }`）。文档 **v2 直接复用引擎的序列化机制**：`{ version: 2, kind: 'flowchart', scene: <引擎 Serializer 产物> }`，因此自定义 `data` 与任何新增 state 字段自动往返；v1（`nodes`/`edges` 数组）仍可读，导出统一为 v2 |\n| 导出 | `toSvg(options)` —— 导出**矢量** SVG（放大不糊、可进设计工具/打印）；与画布同一口径 |\n| 视图与订阅 | `fitViewport(padding)`、`subscribe()`、`dispose()` |\n| 程序化高亮 | `setHighlights(ids, options)` / `highlight(id)` / `clearHighlights()` / `getHighlightedIds()` —— 给\"指着讲\"、教程、演示用。描边环落在**工具层**：**不进快照**、**不参与命中**、图元被拖动或删除时**自动跟随**；默认色取引擎主题主色，可传 `{ color, lineWidth, padding, radius, fill }` 覆盖（`fill` 默认关：工具层整体画在图元之上，填充会盖住位号与名称） |\n\n自定义形状（判定菱形 / 输入输出平行四边形）在 `src/flow/flow_shapes.ts`，走的是引擎的 `ICEPath` 子类机制。\n流程图节点是**复合组件**（形状 + 标题由 kind/标题/配色派生）：它们实现了引擎的 `hasDerivedChildren()`，\n内部子组件不写进文档、载入时由构造函数按 state 重建——避免重复挂载，也让同一份数据的两次序列化结果保持一致。\n可运行的完整示例见 `examples/flowchart-editor.html`；React 用法见 [6.6](#66-流程图的-react-绑定)；\nAI Agent 生成流程图的 JSON DSL 见 `ice-entity-designer-dsl`。\n\n#### 5.3 BPMN 2.0（`BpmnDesigner`）\n\n`BpmnDesigner` 继承 `FlowDesigner`，只补 BPMN 特有的事：顺序流上的条件 / 默认流标记（派生装饰，\n放在工具层、不进文档）与语义校验。其余能力（建节点 / 连线、选择、增删改、撤销重做、快照、适应视图、订阅）全部沿用：\n\n```js\nimport { ICE, BpmnDesigner, toBpmnXml, fromBpmnXml } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst bpmn = new BpmnDesigner(ice);\nice.alignmentGuide.enable({ threshold: 6 }); // 引擎自带的对齐标尺，BPMN 场景同样开启\n\n// 池 / 泳道也是节点；节点按几何**自动嵌进最内层容器**（泳道优先于池）\nconst bank = bpmn.createNode('bpmnPool', { title: '银行', left: 60, top: 60, width: 1180, height: 340 });\nbpmn.createNode('bpmnLane', { title: '受理岗', left: 60, top: 92, width: 1180, height: 150 });\nconst submit = bpmn.createNode('bpmnEvent', { title: '申请提交', eventKind: 'start', left: 240, top: 120 });\nconst verify = bpmn.createNode('bpmnTask', { title: '身份核验', taskType: 'service', left: 400, top: 100 });\nconst gateway = bpmn.createNode('bpmnGateway', { title: '是否通过', gatewayType: 'exclusive', left: 880, top: 255 });\n\nbpmn.createEdge({ sourceId: submit.state.id, targetId: verify.state.id, label: '受理' });\nbpmn.createEdge({ sourceId: verify.state.id, targetId: gateway.state.id, condition: '评分 >= 600', isDefault: true });\n\nbpmn.validateBpmn(); // BPMN 语义问题列表（每个池一个开始事件、顺序流不跨池…）\nconst xml = toBpmnXml(bpmn); // BPMN 2.0 XML + BPMNDI 布局\nconst report = fromBpmnXml(xml, bpmn); // 导入并重建（含池 / 泳道容器）\n```\n\n| 能力 | API |\n|---|---|\n| 节点类型 | `createNode('bpmnEvent' \\| 'bpmnTask' \\| 'bpmnGateway' \\| 'bpmnSubprocess' \\| 'bpmnDataObject' \\| 'bpmnAnnotation' \\| 'bpmnPool' \\| 'bpmnLane', props)`；预设见 `FLOW_NODE_KINDS` |\n| 语义属性 | 事件 `eventKind`（start / intermediate / end）+ `trigger`；网关 `gatewayType`；任务 / 子流程 `taskType` —— `updateNode()` 改完立即重建形状与角标 |\n| 连线 | `createEdge({ sourceId, targetId, flowType: 'sequence' \\| 'message' \\| 'association', label, condition, isDefault, linkShape })`；线型与箭头由 `flowType` 派生 |\n| 容器 | 池 `bpmnPool`（顶部 32px 标题带，标题横排）、泳道 `bpmnLane`（左侧 32px 标题带，标题**旋转 -90° 竖排**、居中，过长按名称带截断加省略号）；建节点时按几何自动嵌套，拖动容器时内部图元与连线一起走 |\n| 校验与互操作 | `validateBpmn()`、`toBpmnXml(designer)`、`fromBpmnXml(xml, designer)` |\n| 其余 | 与 `FlowDesigner` 完全相同：`nodes` / `edges` / `select()` / `updateNode()` / `updateEdge()` / `remove()` / `undo()` / `redo()` / `serialize()` / `load()` / `fitViewport()` / `subscribe()` |\n\nBPMN 节点同样是**复合组件**（形状 + 角标 + 标记由 state 派生），内部子组件不写进文档、载入时重建。\nAI Agent 生成 BPMN 的 JSON DSL（`kind: 'bpmn'`）见 `ice-entity-designer-dsl`。\n\n#### 5.4 导出：矢量 SVG（与画布同一口径）\n\n画布的 `toDataURL()` 是**光栅快照**（分辨率写死、放大就糊）。需要出图给文档、打印或设计工具时用\n**矢量导出** —— 它复用引擎的 `exportSvg()`，从组件树 + 路径命令流重新生成 SVG，与画布逐像素同一口径\n（绘制顺序、世界矩阵、样式合并、透明度、祖先裁剪、虚线、渐变、阴影、连线标签）：\n\n```js\n// 流程图 / BPMN（应用层，FlowDesigner 与 BpmnDesigner 都有）\nconst svg = designer.toSvg(); // 内容自适应 + 透明背景\nconst svg = designer.toSvg({ background: '#ffffff', padding: 16 });\nconst svg = designer.toSvg({ area: 'viewport' }); // 当前视口所见即所导\n\n// 任何场景（ER / 流程图 / BPMN 都能用，含 `{ svg, width, height }` 版本）\nconst svg = IED.exportSvg(ice, { scale: 2 });\nconst { svg, width, height } = IED.exportSvgResult(ice, { padding: 12 });\n```\n\n`examples/bpmn-editor.html` 与 `examples/flowchart-editor.html` 上都有「导出 SVG」按钮，点一下即可下载\n（BPMN 案例导出的池/泳道/事件/网关/连线/标签都是矢量）。服务端出图见引擎的 `ICE.headless()`。\n\n限制（与引擎一致）：阴影用 `feDropShadow` 近似（模糊观感不会与画布逐像素相同）；SVG 与 canvas 的\n字形栅格化是两套实现，文字位置**对齐口径一致、逐像素允许微差**；导出的是**静态瞬间**（蚂蚁线动画\n只保留当前相位）。\n\n#### 5.5 甘特图（`GanttDesigner`）\n\n排期场景：横轴是**时间**（`start` 日期 × 持续天数 × 每日像素）、纵轴是行，任务条**按天吸附**拖动，\n依赖线从「前置任务的结束」指向「后置任务的开始」。\n\n```js\nimport { ICE, GanttDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst gantt = new GanttDesigner(ice);\n\nconst review = gantt.createTask({ title: '需求评审', start: '2026-03-02', days: 4, progress: 1 });\nconst design = gantt.createTask({ title: '交互设计', start: '2026-03-05', days: 6, progress: 0.8 });\ngantt.createDependency({ sourceId: review.state.id, targetId: design.state.id });\n\ngantt.setDayWidth(36); // 时间轴缩放：所有任务与依赖一起重排\ngantt.validateGantt(); // 依赖成环 / 进度越界 / 持续天数非法\nconst svg = gantt.toSvg({ background: '#ffffff' });\n```\n\n与其它域包同一套机制：任务条是复合组件（条 + 进度覆盖 + 文字由 state 派生）、依赖复用引擎折线\n（插槽吸附 / 正交路由 / 跟随宿主）、快照与矢量导出全部继承。两条甘特特有的能力：\n\n| 能力 | 说明 |\n|---|---|\n| 时间轴 | `dayWidth` / `originDate` / `labelColumnWidth` 统一换算；框架（左列任务名 + 日期刻度 + 行线）由派生的 `GanttRuler` 渲染，模型一变就重建 |\n| 按天吸附 | `GanttTask.setPosition()` 把 x 吸附到整天的格子并反推 `start`（排期不会出现「13:47 开工」） |\n\n可运行示例：`examples/gantt-editor.html`（移动端 2.0 发布排期，含依赖、进度、**自动排程**与**关键路径**按钮）。\n\n文本互操作：`IED.toMermaidGantt(designer)` / `IED.fromMermaidGantt(text, designer)` 走 Mermaid gantt 语法子集 ——\n`section` 对应负责人（`resource`），单前置依赖写成 `after`（Mermaid 自己画依赖箭头）；\n多前置、或带 buffer 的排期写成显式日期 + `%% task` 注释（Mermaid 只忽略注释，渲染不受影响）。\n\n#### 5.6 BPMN 令牌仿真（`BpmnSimulator`）\n\n「流程怎么走」可以直接演示出来：令牌从开始事件出发，沿顺序流前进、在任务上停留、在排他网关选一条分支、\n在并行网关一分为多，到达结束事件后消失。\n\n```js\nimport { BpmnSimulator } from 'ice-entity-designer';\n\nconst simulator = new BpmnSimulator(bpmn, { nodeDuration: 500, edgeDuration: 700 });\nsimulator.start(); // 每个开始事件一个令牌；浏览器里由引擎帧事件驱动\nsimulator.step(50); // 也可以手动推进（测试/单步调试用，确定性）\nsimulator.stop(); // 清空令牌\n```\n\n| 能力 | 说明 |\n|---|---|\n| 令牌 | 工具层组件（`ice.toolNodes`）：**不进文档、不影响快照与 BPMN XML 导出**，停止即干净退场 |\n| 路由 | 令牌位置在连线的**实际折点**上按弧长插值，所以始终贴在画出来的线上（含正交绕线） |\n| 语义 | 排他网关优先走带 `condition` 的流、其次走非默认流；并行/包容网关分裂成多条令牌；结束事件上令牌消亡 |\n| 推进 | `step(dtMs)` 显式推进（测试可断言）；`start()` 后自动挂帧循环 |\n\n可运行示例：`examples/bpmn-editor.html` 的「仿真 / 停止」按钮（案例是信用卡申请审批）。\n\n#### 5.7 UML 类图（域包示例）\n\nUML 是**域包（domain pack）**的第一个完整示例：形状 + 应用层 + 语义校验，其余（选择/增删改/连线/\n撤销重做/快照/适应视图/矢量导出）全部沿用引擎与 `FlowDesigner`。\n\n```js\nimport { ICE, UmlDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst uml = new UmlDesigner(ice);\n\nconst entity = uml.createClass({ kind: 'class', className: 'Entity', abstract: true, methods: ['+ save(): void'] });\nconst user = uml.createClass({ className: 'User', attributes: ['- email: string'], methods: ['+ placeOrder(): Order'] });\nconst payable = uml.createClass({ kind: 'interface', className: 'Payable', methods: ['+ pay(amount: number): void'] });\n\numl.createRelation({ sourceId: user.state.id, targetId: entity.state.id, relationKind: 'inheritance' });\numl.createRelation({ sourceId: payable.state.id, targetId: user.state.id, relationKind: 'realization' });\n\numl.validateUml(); // 重名类 / 悬空关系 / 继承成环\nconst svg = uml.toSvg({ background: '#ffffff', padding: 16 });\n```\n\n| 记法 | 线型 + 端点标记 |\n|---|---|\n| `inheritance` 继承 | 实线 + 空心三角（指向父类） |\n| `realization` 实现 | 虚线 + 空心三角（指向接口） |\n| `association` 关联 | 实线 |\n| `aggregation` 聚合 | 实线 + **空心菱形**（整体一侧） |\n| `composition` 组合 | 实线 + **实心菱形**（整体一侧） |\n| `dependency` 依赖 | 虚线 + 开放箭头 |\n\n类框是**三段式**（类名 / 属性 / 方法）：成员是自由文本（`- id: string`、`+ pay(): void`），\n可见性/静态/泛型都由文本表达 —— 与 PlantUML/Mermaid 的通行写法一致，AI 生成不必学另一套结构化语法；\n接口与枚举带构造型，抽象类标 «abstract»；**框高随成员自动增长**，成员不会被画到框外。\n\n可运行示例：`examples/uml-editor.html`（电商支付的类模型：继承 / 实现 / 组合 / 关联 / 依赖）。\n\n文本互操作：`IED.toPlantUml(designer)` / `IED.fromPlantUml(text, designer)` 走 PlantUML / Mermaid\n类图语法子集（三段式类框 + 六种关系的连接符），导出可直接贴进 Wiki / Markdown / 代码评审。\n\n#### 5.8 状态机（`StatechartDesigner`）\n\n状态机是**域包（domain pack）**的第二个完整示例：伪状态（初始 / 终止）、普通状态、\n**复合状态是容器**（内部可放子状态，拖动父状态子状态跟着走），转移标签是 `事件 [守卫] / 动作`。\n\n```js\nimport { ICE, StatechartDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst statechart = new StatechartDesigner(ice);\n\nconst initial = statechart.createState({ kind: 'initial', left: 120, top: 120 });\nconst pending = statechart.createState({ title: '待支付', left: 240, top: 100 });\nconst paid = statechart.createState({ title: '已支付', left: 620, top: 100 });\n\nstatechart.createTransition({ sourceId: initial.state.id, targetId: pending.state.id });\nstatechart.createTransition({\n sourceId: pending.state.id,\n targetId: paid.state.id,\n event: '支付成功',\n guard: '金额 > 0',\n action: '生成订单',\n});\n\nstatechart.validateStatechart(); // 缺初始 / 终止有出边 / 孤立状态 / 从初始不可达\nconst svg = statechart.toSvg({ background: '#ffffff' });\n```\n\n文本互操作：`IED.toPlantUmlState(designer)` / `IED.fromPlantUmlState(text, designer)` 走 PlantUML 状态图语法子集 ——\n伪状态映射成 `[*]`，复合状态成 `state 订单处理 { ... }` 嵌套块（块的嵌套就是容器归属），\n转移标签导入时拆回事件 / 守卫 / 动作三段（`IED.splitTransitionLabel(label)` 是这一步的公开口径）。\n\n可运行示例：`examples/statechart-editor.html`（订单状态机，含复合状态与 PlantUML 导入导出）。\n\n#### 5.9 电力一次系统图（单线图）\n\n面向电力行业的第一块垂直切片：**一次设备符号库 + 应用层 + 拓扑 + 语义校验**。\n记法对齐 **JB/T 5872-1991《高压开关设备电气图形及文字符号》**（QF 断路器 / QS 隔离开关 /\nQL 负荷开关 / QE 接地开关 / TA 电流互感器 / TV 电压互感器 / TM 变压器 / FU 熔断器 / F 避雷器 /\nL 电抗器 / E 接地），通用规则遵循 GB/T 4728（等同 IEC 60617）。符号依据与默认口径见\n`docs/power-symbol-spec.md`。\n\n```js\nimport { ICE, PowerDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst power = new PowerDesigner(ice);\n\nconst line = power.createSymbol('generator', { name: '线路1', voltageLevel: '110kV' });\nconst qf = power.createSymbol('breaker', { name: '1101', voltageLevel: '110kV' });\nconst bus = power.createSymbol('busbar', { name: '#1M', voltageLevel: '110kV', width: 720 });\npower.createLine({ sourceId: line.state.id, targetId: qf.state.id });\npower.createLine({ sourceId: qf.state.id, targetId: bus.state.id });\n\npower.setEnergizedSource(line.state.id, true); // 标电源点\npower.setSwitchState(qf.state.id, 'closed'); // 运行态：合闸\npower.applyTopology(); // 带电分析 → 写回各设备，供色标使用\npower.validatePower(); // 编号唯一 / 电压等级一致 / 母线进线 / 断路器两侧隔离开关 / 五防\nconst svg = power.toSvg({ background: '#ffffff' });\n```\n\n| 能力 | 说明 |\n|---|---|\n| 符号库 | 15 种一次设备；每个派生部件带稳定 `role`（blade / arcMark / contactBar / winding / coil…），测试按 role 认记法 |\n| 电压等级色标 | `setVoltageColors({ '110kV': '#xxxxxx' })` 覆盖；默认值见规格文档 |\n| 运行态 | `setSwitchState(id, 'open' / 'closed')`：刀臂形状 + 分合标签 + 带电范围一起更新 |\n| 拓扑 | `topology()` 返回带电设备与电气连通域；`applyTopology()` 把带电状态写回节点（不带电自动变灰） |\n| 记法不可变换 | 所有符号 `transformable: false`：**只能拖动**，没有缩放/旋转手柄（尺寸与朝向是记法的一部分）；母线长度、柜体宽高在属性面板里用数值改；图纸整体缩放走滚轮视图缩放 |\n| 母线 T 接 | `attachToBus(device, bus, { centerX })`：设备记 `attachedBusId` 并把顶部引线贴住母线（隐式等电位，不用画绕行导体）；`detachFromBus()` / 拖离几何范围即断开；拖动母线时挂上去的间隔整体跟随 |\n| 语义校验 | 设备编号唯一、直接相连的电压等级一致（变压器两侧例外）、母线要有进线、断路器两侧应有隔离开关，以及**带电合接地刀闸 / 带接地线合闸送电**这两条五防相关规则 |\n\n可运行示例：`examples/power-editor.html`（110kV 变电站：双母线 + 母联 + 两回进线 + 两台主变）；\n符号表页：`examples/power-symbols.html`。\n\n#### 5.10 电力二次回路（简化版）\n\n一次图是**单线图**，二次图是**回路图**：一条线 = 一个具体回路，线上标**回路编号**（A411/B411/C411/N411）、\n端子带**端子号**（201…）、电缆带**电缆编号**（1D1…）。记法与范围见 `docs/power-secondary-spec.md`\n（图种清单、IEEE C37.2 功能编号对照、来源）。\n\n```js\nimport { ICE, SecondaryDesigner } from 'ice-entity-designer';\n\nconst ice = new ICE().init('canvas-1');\nconst secondary = new SecondaryDesigner(ice);\n\nconst winding = secondary.createSymbol('ctWinding', { name: '1LHa' });\nconst { strip, terminals } = secondary.createTerminalStrip({ title: '1D 端子排', terminals: [{ no: '201' }, { no: '202' }] });\nconst device = secondary.createSymbol('relayDevice', { name: '线路保护', tag: 'RCS-941A' });\nsecondary.createWire({ sourceId: winding.state.id, targetId: terminals[0].state.id, circuitNo: 'A411', cableNo: '1D1' });\nsecondary.createWire({ sourceId: terminals[0].state.id, targetId: device.state.id, circuitNo: 'A411' });\nsecondary.validateSecondary(); // 回路编号 / 三相成组 / 端子号唯一 / 必须接地\nconst svg = secondary.toSvg({ background: '#ffffff' });\n```\n\n| 能力 | 说明 |\n|---|---|\n| 元件库 | 常开/常闭接点、按钮、切换开关、压板、信号灯、保护装置方框、互感器二次绕组、端子、接地（记法按 GB/T 4728.7，文字符号用 C37.2 功能编号） |\n| 端子排 | 容器：端子是真实子节点 —— 拖动端子排端子跟着走，端子各自可接线，**快照往返不丢端子** |\n| 回路编号 | `createWire({ circuitNo })`：线就是回路，编号画在线上；电缆编号是数据字段 |\n| 二次校验 | 导线必须有回路编号、三相电流回路编号成组（缺相报错）、端子号唯一、二次回路必须接地 |\n\n可运行示例：`examples/secondary-editor.html`（110kV 线路保护电流回路，简化版）。\n\n## 6. 在 React 中使用\n\n包内置 React 绑定（子路径导出 `ice-entity-designer/react`），不需要自己写 ref / effect 胶水代码。\n\n```bash\nnpm install ice-entity-designer ice-render react react-dom\n```\n\n```tsx\nimport { useRef } from 'react';\nimport { EntityDesignerCanvas, useEntityDesigner } from 'ice-entity-designer/react';\nimport type { EntityDesignerHandle } from 'ice-entity-designer/react';\n\n// 子树内可以取到同一个 EntityDesigner 实例\nfunction Stats() {\n const designer = useEntityDesigner();\n return {designer ? `${designer.entities.length} 个实体` : '初始化中…'};\n}\n\nexport default function App() {\n const ref = useRef