ice-entity-designer 0.0.29 → 0.0.31

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="120" src="./tests/assets/ice-entity-designer.png" alt="ice entity designer" />
+  <img width="120" src="./examples/assets/ice-entity-designer.png" alt="ice entity designer" />
 </p>
 
 <h1 align="center">IED · ice entity designer</h1>
@@ -54,9 +54,8 @@ IED（ice entity designer）是基于 [ice-render](https://github.com/ice-render
 ### 编辑器内核能力（继承自 ice-render）
 
 - 画布滚轮缩放、空白处拖拽平移。
-- 每个域包示例页统一接入上面这套视口交互（`tests/canvas-interactions.js`）：canvas 铺满可视区，
+- 每个域包示例页统一接入上面这套视口交互（`examples/canvas-interactions.js`）：canvas 铺满可视区，
   滚轮以光标为锚点缩放，空白处左键 / 任意位置中键拖拽平移，工具栏带「适应视图 / 复位视图」。
-  老示例把 canvas 写死成 1800×1100 而可视区更小，`fitViewport()` 是按 canvas 尺寸算的 —— 图会被切在屏幕外。
 - 拖拽对齐辅助线与磁吸效果。
 - Undo / Redo（基于项目快照，最多 100 步）。
 - 项目级保存 / 加载（`serializeProject()` / `loadProject()`）。
@@ -80,31 +79,31 @@ IED（ice entity designer）是基于 [ice-render](https://github.com/ice-render
 
 完整的 ER 模型（电商交易 + 用户权限）：
 
-<img src="./tests/assets/overview.png" alt="ER 模型总览" />
+<img src="./examples/assets/overview.png" alt="ER 模型总览" />
 
 实体字段与约束标记：
 
-<img src="./tests/assets/fields.png" alt="实体字段与约束" />
+<img src="./examples/assets/fields.png" alt="实体字段与约束" />
 
 关系语义：自引用、多对多、一对一：
 
-<img src="./tests/assets/relations.png" alt="关系语义" />
+<img src="./examples/assets/relations.png" alt="关系语义" />
 
 交互式编辑器（右侧面板可直接切换到「TypeORM Schema」查看导出结果）：
 
-<img src="./tests/assets/editor.png" alt="交互式编辑器与 TypeORM Schema" />
+<img src="./examples/assets/editor.png" alt="交互式编辑器与 TypeORM Schema" />
 
-同一套内核也能承载**流程图**（`tests/flowchart-editor.html`）：四类节点（开始/结束、处理、判定、输入/输出，
+同一套内核也能承载**流程图**（`examples/flowchart-editor.html`）：四类节点（开始/结束、处理、判定、输入/输出，
 其中判定菱形与输入输出平行四边形是自定义 `ICEPath` 形状）、正交/贝塞尔连线 + 分支标签（是/否）、
 拖拽 / 连线 / 撤销重做 / 快照存取：
 
-<img src="./tests/assets/flowchart-editor.png" alt="流程图编辑器示例" />
+<img src="./examples/assets/flowchart-editor.png" alt="流程图编辑器示例" />
 
-再加一层业务记法就是 **BPMN 2.0**（`tests/bpmn-editor.html`）：池 / 泳道真嵌套（拖动银行池，内部泳道、
+再加一层业务记法就是 **BPMN 2.0**（`examples/bpmn-editor.html`）：池 / 泳道真嵌套（拖动银行池，内部泳道、
 任务和连线一起平移）、事件 / 网关 / 任务角标 / 数据对象 / 注释、顺序流 + 条件与默认流标记、
 跨池的消息流，右侧面板按图元类型给出网关类型、事件种类、任务类型等属性，并内置语义校验与 BPMN 2.0 XML 导出：
 
-<img src="./tests/assets/bpmn-editor.png" alt="BPMN 2.0 编辑器示例（信用卡申请审批）" />
+<img src="./examples/assets/bpmn-editor.png" alt="BPMN 2.0 编辑器示例（信用卡申请审批）" />
 
 ## 4. 快速开始
 
@@ -113,17 +112,20 @@ npm install
 npm run build
 ```
 
-可运行的示例（`tests/` 下的页面会加载同级 `dist` 与 `node_modules`，建议通过静态服务器打开）：
+可运行的示例（`examples/` 下的页面加载上一级 `dist` 与本仓 `node_modules`，建议通过静态服务器打开）：
 
 | 示例 | 说明 |
 |---|---|
-| `tests/entity-editor.html` | 交互式编辑器：实时编辑字段、创建/删除实体与关系、校验与保存加载；右侧面板含「TypeORM Schema」标签页 |
-| `tests/flowchart-editor.html` | 流程图编辑器：四类节点形状、拖拽、连线（含分支标签）、撤销重做、localStorage 存取与 JSON 导出；纯 DOM 面板，只依赖 `dist` 产物 |
-| `tests/bpmn-editor.html` | BPMN 2.0 编辑器：信用卡申请审批案例（两个池 / 三条泳道）、八类图元、条件与默认流标记、语义校验、BPMN 2.0 XML 导入导出 |
+| `examples/entity-editor.html` | 交互式编辑器：实时编辑字段、创建/删除实体与关系、校验与保存加载；右侧面板含「TypeORM Schema」标签页 |
+| `examples/flowchart-editor.html` | 流程图编辑器：四类节点形状、拖拽、连线（含分支标签）、撤销重做、localStorage 存取与 JSON 导出；纯 DOM 面板，只依赖 `dist` 产物 |
+| `examples/bpmn-editor.html` | BPMN 2.0 编辑器：信用卡申请审批案例（两个池 / 三条泳道）、八类图元、条件与默认流标记、语义校验、BPMN 2.0 XML 导入导出 |
+| `examples/uml-editor.html` | UML 类图编辑器：三段式类框、六种关系、语义校验、矢量导出、PlantUML / Mermaid 文本互操作 |
+| `examples/statechart-editor.html` | 状态机编辑器：伪状态 / 普通状态 / 复合状态容器、转移标签 `事件 [守卫] / 动作` |
+| `examples/gantt-editor.html` | 甘特编辑器：时间轴与按天吸附、依赖线、自动排程、关键路径、资源冲突校验、矢量导出 |
 | [`ice-entity-designer-react-demo`](../ice-entity-designer-react-demo) | 独立的 React 集成示例工程（webpack + TypeScript），涵盖 ref / hook / onChange / 受控模式 |
 
 ```bash
-python3 -m http.server 8899   # 然后访问 http://localhost:8899/tests/entity-editor.html
+python3 -m http.server 8899   # 然后访问 http://localhost:8899/examples/entity-editor.html
 ```
 
 ## 5. 使用方式
@@ -214,7 +216,7 @@ flow.undo(); // 100 步历史
 自定义形状（判定菱形 / 输入输出平行四边形）在 `src/flow/flow_shapes.ts`，走的是引擎的 `ICEPath` 子类机制。
 流程图节点是**复合组件**（形状 + 标题由 kind/标题/配色派生）：它们实现了引擎的 `hasDerivedChildren()`，
 内部子组件不写进文档、载入时由构造函数按 state 重建——避免重复挂载，也让同一份数据的两次序列化结果保持一致。
-可运行的完整示例见 `tests/flowchart-editor.html`；React 用法见 [6.6](#66-流程图的-react-绑定)；
+可运行的完整示例见 `examples/flowchart-editor.html`；React 用法见 [6.6](#66-流程图的-react-绑定)；
 AI Agent 生成流程图的 JSON DSL 见 `ice-entity-designer-dsl`。
 
 #### 5.3 BPMN 2.0（`BpmnDesigner`）
@@ -273,7 +275,7 @@ const svg = IED.exportSvg(ice, { scale: 2 });
 const { svg, width, height } = IED.exportSvgResult(ice, { padding: 12 });
 ```
 
-`tests/bpmn-editor.html` 与 `tests/flowchart-editor.html` 上都有「导出 SVG」按钮，点一下即可下载
+`examples/bpmn-editor.html` 与 `examples/flowchart-editor.html` 上都有「导出 SVG」按钮，点一下即可下载
 （BPMN 案例导出的池/泳道/事件/网关/连线/标签都是矢量）。服务端出图见引擎的 `ICE.headless()`。
 
 限制（与引擎一致）：阴影用 `feDropShadow` 近似（模糊观感不会与画布逐像素相同）；SVG 与 canvas 的
@@ -281,59 +283,63 @@ const { svg, width, height } = IED.exportSvgResult(ice, { padding: 12 });
 只保留当前相位）。
 
 #### 5.5 甘特图（`GanttDesigner`）
-+
-+排期场景：横轴是**时间**（`start` 日期 × 持续天数 × 每日像素）、纵轴是行，任务条**按天吸附**拖动，
-+依赖线从「前置任务的结束」指向「后置任务的开始」。
-+
-+```js
-+import { ICE, GanttDesigner } from 'ice-entity-designer';
-+
-+const ice = new ICE().init('canvas-1');
-+const gantt = new GanttDesigner(ice);
-+
-+const review = gantt.createTask({ title: '需求评审', start: '2026-03-02', days: 4, progress: 1 });
-+const design = gantt.createTask({ title: '交互设计', start: '2026-03-05', days: 6, progress: 0.8 });
-+gantt.createDependency({ sourceId: review.state.id, targetId: design.state.id });
-+
-+gantt.setDayWidth(36);        // 时间轴缩放：所有任务与依赖一起重排
-+gantt.validateGantt();        // 依赖成环 / 进度越界 / 持续天数非法
-+const svg = gantt.toSvg({ background: '#ffffff' });
-+```
-+
-+与其它域包同一套机制：任务条是复合组件（条 + 进度覆盖 + 文字由 state 派生）、依赖复用引擎折线
-+（插槽吸附 / 正交路由 / 跟随宿主）、快照与矢量导出全部继承。两条甘特特有的能力：
-+
-+| 能力 | 说明 |
-+|---|---|
-+| 时间轴 | `dayWidth` / `originDate` / `labelColumnWidth` 统一换算；框架（左列任务名 + 日期刻度 + 行线）由派生的 `GanttRuler` 渲染，模型一变就重建 |
-+| 按天吸附 | `GanttTask.setPosition()` 把 x 吸附到整天的格子并反推 `start`（排期不会出现「13:47 开工」） |
-+
-+可运行示例：`tests/gantt-editor.html`（移动端 2.0 发布排期，含依赖、进度、**自动排程**与**关键路径**按钮）。
+
+排期场景：横轴是**时间**（`start` 日期 × 持续天数 × 每日像素）、纵轴是行，任务条**按天吸附**拖动，
+依赖线从「前置任务的结束」指向「后置任务的开始」。
+
+```js
+import { ICE, GanttDesigner } from 'ice-entity-designer';
+
+const ice = new ICE().init('canvas-1');
+const gantt = new GanttDesigner(ice);
+
+const review = gantt.createTask({ title: '需求评审', start: '2026-03-02', days: 4, progress: 1 });
+const design = gantt.createTask({ title: '交互设计', start: '2026-03-05', days: 6, progress: 0.8 });
+gantt.createDependency({ sourceId: review.state.id, targetId: design.state.id });
+
+gantt.setDayWidth(36);        // 时间轴缩放：所有任务与依赖一起重排
+gantt.validateGantt();        // 依赖成环 / 进度越界 / 持续天数非法
+const svg = gantt.toSvg({ background: '#ffffff' });
+```
+
+与其它域包同一套机制：任务条是复合组件（条 + 进度覆盖 + 文字由 state 派生）、依赖复用引擎折线
+（插槽吸附 / 正交路由 / 跟随宿主）、快照与矢量导出全部继承。两条甘特特有的能力：
+
+| 能力 | 说明 |
+|---|---|
+| 时间轴 | `dayWidth` / `originDate` / `labelColumnWidth` 统一换算；框架（左列任务名 + 日期刻度 + 行线）由派生的 `GanttRuler` 渲染，模型一变就重建 |
+| 按天吸附 | `GanttTask.setPosition()` 把 x 吸附到整天的格子并反推 `start`（排期不会出现「13:47 开工」） |
+
+可运行示例：`examples/gantt-editor.html`（移动端 2.0 发布排期，含依赖、进度、**自动排程**与**关键路径**按钮）。
+
+文本互操作：`IED.toMermaidGantt(designer)` / `IED.fromMermaidGantt(text, designer)` 走 Mermaid gantt 语法子集 ——
+`section` 对应负责人（`resource`），单前置依赖写成 `after`（Mermaid 自己画依赖箭头）；
+多前置、或带 buffer 的排期写成显式日期 + `%% task` 注释（Mermaid 只忽略注释，渲染不受影响）。
 
 #### 5.6 BPMN 令牌仿真（`BpmnSimulator`）
-+
-+「流程怎么走」可以直接演示出来：令牌从开始事件出发，沿顺序流前进、在任务上停留、在排他网关选一条分支、
-+在并行网关一分为多，到达结束事件后消失。
-+
-+```js
-+import { BpmnSimulator } from 'ice-entity-designer';
-+
-+const simulator = new BpmnSimulator(bpmn, { nodeDuration: 500, edgeDuration: 700 });
-+simulator.start();      // 每个开始事件一个令牌；浏览器里由引擎帧事件驱动
-+simulator.step(50);     // 也可以手动推进（测试/单步调试用，确定性）
-+simulator.stop();       // 清空令牌
-+```
-+
-+| 能力 | 说明 |
-+|---|---|
-+| 令牌 | 工具层组件（`ice.toolNodes`）：**不进文档、不影响快照与 BPMN XML 导出**，停止即干净退场 |
-+| 路由 | 令牌位置在连线的**实际折点**上按弧长插值，所以始终贴在画出来的线上（含正交绕线） |
-+| 语义 | 排他网关优先走带 `condition` 的流、其次走非默认流；并行/包容网关分裂成多条令牌；结束事件上令牌消亡 |
-+| 推进 | `step(dtMs)` 显式推进（测试可断言）；`start()` 后自动挂帧循环 |
-+
-+可运行示例：`tests/bpmn-editor.html` 的「仿真 / 停止」按钮（案例是信用卡申请审批）。
-+
-+#### 5.7 UML 类图（域包示例）
+
+「流程怎么走」可以直接演示出来：令牌从开始事件出发，沿顺序流前进、在任务上停留、在排他网关选一条分支、
+在并行网关一分为多，到达结束事件后消失。
+
+```js
+import { BpmnSimulator } from 'ice-entity-designer';
+
+const simulator = new BpmnSimulator(bpmn, { nodeDuration: 500, edgeDuration: 700 });
+simulator.start();      // 每个开始事件一个令牌；浏览器里由引擎帧事件驱动
+simulator.step(50);     // 也可以手动推进（测试/单步调试用，确定性）
+simulator.stop();       // 清空令牌
+```
+
+| 能力 | 说明 |
+|---|---|
+| 令牌 | 工具层组件（`ice.toolNodes`）：**不进文档、不影响快照与 BPMN XML 导出**，停止即干净退场 |
+| 路由 | 令牌位置在连线的**实际折点**上按弧长插值，所以始终贴在画出来的线上（含正交绕线） |
+| 语义 | 排他网关优先走带 `condition` 的流、其次走非默认流；并行/包容网关分裂成多条令牌；结束事件上令牌消亡 |
+| 推进 | `step(dtMs)` 显式推进（测试可断言）；`start()` 后自动挂帧循环 |
+
+可运行示例：`examples/bpmn-editor.html` 的「仿真 / 停止」按钮（案例是信用卡申请审批）。
+
+#### 5.7 UML 类图（域包示例）
 
 UML 是**域包（domain pack）**的第一个完整示例：形状 + 应用层 + 语义校验，其余（选择/增删改/连线/
 撤销重做/快照/适应视图/矢量导出）全部沿用引擎与 `FlowDesigner`。
@@ -368,7 +374,44 @@ const svg = uml.toSvg({ background: '#ffffff', padding: 16 });
 可见性/静态/泛型都由文本表达 —— 与 PlantUML/Mermaid 的通行写法一致，AI 生成不必学另一套结构化语法；
 接口与枚举带构造型，抽象类标 «abstract»；**框高随成员自动增长**，成员不会被画到框外。
 
-可运行示例：`tests/uml-editor.html`（电商支付的类模型：继承 / 实现 / 组合 / 关联 / 依赖）。
+可运行示例：`examples/uml-editor.html`（电商支付的类模型：继承 / 实现 / 组合 / 关联 / 依赖）。
+
+文本互操作：`IED.toPlantUml(designer)` / `IED.fromPlantUml(text, designer)` 走 PlantUML / Mermaid
+类图语法子集（三段式类框 + 六种关系的连接符），导出可直接贴进 Wiki / Markdown / 代码评审。
+
+#### 5.8 状态机（`StatechartDesigner`）
+
+状态机是**域包（domain pack）**的第二个完整示例：伪状态（初始 / 终止）、普通状态、
+**复合状态是容器**（内部可放子状态，拖动父状态子状态跟着走），转移标签是 `事件 [守卫] / 动作`。
+
+```js
+import { ICE, StatechartDesigner } from 'ice-entity-designer';
+
+const ice = new ICE().init('canvas-1');
+const statechart = new StatechartDesigner(ice);
+
+const initial = statechart.createState({ kind: 'initial', left: 120, top: 120 });
+const pending = statechart.createState({ title: '待支付', left: 240, top: 100 });
+const paid = statechart.createState({ title: '已支付', left: 620, top: 100 });
+
+statechart.createTransition({ sourceId: initial.state.id, targetId: pending.state.id });
+statechart.createTransition({
+  sourceId: pending.state.id,
+  targetId: paid.state.id,
+  event: '支付成功',
+  guard: '金额 > 0',
+  action: '生成订单',
+});
+
+statechart.validateStatechart();   // 缺初始 / 终止有出边 / 孤立状态 / 从初始不可达
+const svg = statechart.toSvg({ background: '#ffffff' });
+```
+
+文本互操作：`IED.toPlantUmlState(designer)` / `IED.fromPlantUmlState(text, designer)` 走 PlantUML 状态图语法子集 ——
+伪状态映射成 `[*]`，复合状态成 `state 订单处理 { ... }` 嵌套块（块的嵌套就是容器归属），
+转移标签导入时拆回事件 / 守卫 / 动作三段（`IED.splitTransitionLabel(label)` 是这一步的公开口径）。
+
+可运行示例：`examples/statechart-editor.html`（订单状态机，含复合状态与 PlantUML 导入导出）。
 
 ## 6. 在 React 中使用
 
@@ -514,8 +557,8 @@ React 里可沿用 `createFlowSession` 的模式自建一层封装。
 
 ### 7.1 一个「域包（domain pack）」由什么组成
 
-域包 = **一个领域的记法 + 应用层 + 语义校验**，跑在同一套引擎与同一套应用层机制上。已落地的三个
-域（ER / 流程图 / BPMN）再加 UML，边际成本主要在「记法本身」，不在编辑器：
+域包 = **一个领域的记法 + 应用层 + 语义校验**，跑在同一套引擎与同一套应用层机制上。现已落地
+6 类文档：ER、流程图、UML 类图、状态机、甘特、BPMN 2.0 —— 边际成本主要在「记法本身」，不在编辑器：
 
 | 组成 | 复用什么 | 以 UML 为例 |
 |---|---|---|
@@ -524,8 +567,8 @@ React 里可沿用 `createFlowSession` 的模式自建一层封装。
 | 应用层 | `FlowDesigner`（选择 / 增删改 / 连线 / 撤销重做 / 快照 / 适应视图 / 订阅 / `toSvg`） | `UmlDesigner` 只重写「建什么图元 + 类型过滤」 |
 | 语义校验 | 结构校验之外的部分自写，规则直白 | `validateUml()`：重名类 / 悬空关系 / 继承成环 |
 | 文档格式 | 引擎序列化（typeId 注册表 + `hasDerivedChildren`），零登记 | 类与关系统统自动往返 |
-| 互操作 | 有标准格式的域就做（BPMN 2.0 XML 已有） | UML 的 XMI / PlantUML 互操作待补 |
-| 交付物 | 示例页 + e2e + README + （可选）JSON DSL 与技能 | `tests/uml-editor.html` + `e2e/uml-editor.spec.ts` |
+| 互操作 | 有标准格式的域就做 | BPMN 2.0 XML（导入 + 导出，含 BPMNDI 布局）；UML 类图与状态机的 PlantUML 文本互操作；甘特的 Mermaid gantt 文本互操作 |
+| 交付物 | 示例页 + e2e + README + （可选）JSON DSL 与技能 | `examples/uml-editor.html` + `e2e/uml-editor.spec.ts` |
 
 新开一个域包时，按这张表从上往下填即可；**不要**在域包里另造序列化、另造选择/历史、另造导出。
 
@@ -543,12 +586,12 @@ src/
 │   ├── UmlClass.ts                # 复合组件：类名 / 属性 / 方法三段，构造型，框高随成员增长
 │   ├── UmlRelation.ts             # 六种关系 = 线型 + 端点标记（三角/菱形/开放箭头，标记进路径点集）
 │   └── UmlDesigner.ts             # FlowDesigner 薄扩展：建 UML 图元 + 类型过滤 + validateUml()
-+├── gantt/                         # 甘特图（第三个 domain pack：时间轴 + 按天吸附 + 依赖）
-+│   ├── gantt_date.ts              # 日期工具（UTC 口径，YYYY-MM-DD ↔ 天数）
-+│   ├── GanttTask.ts               # 任务条（复合组件）+ setPosition 按天吸附
-+│   ├── GanttRuler.ts              # 图表框架：左列任务名 + 日期刻度 + 行线（派生重建）
-+│   ├── GanttDependency.ts         # 依赖线（完成 → 开始）
-+│   └── GanttDesigner.ts           # 时间轴换算 + syncChrome + validateGantt
+├── gantt/                         # 甘特图（第三个 domain pack：时间轴 + 按天吸附 + 依赖）
+│   ├── gantt_date.ts              # 日期工具（UTC 口径，YYYY-MM-DD ↔ 天数）
+│   ├── GanttTask.ts               # 任务条（复合组件）+ setPosition 按天吸附
+│   ├── GanttRuler.ts              # 图表框架：左列任务名 + 日期刻度 + 行线（派生重建）
+│   ├── GanttDependency.ts         # 依赖线（完成 → 开始）
+│   └── GanttDesigner.ts           # 时间轴换算 + syncChrome + validateGantt
 ├── bpmn/                          # BPMN 2.0（FlowDesigner 之上的业务记法）
 │   ├── BpmnSimulator.ts           # 令牌仿真：沿顺序流推进、网关分叉、结束消亡（令牌在工具层）
 │   ├── bpmn_shapes.ts             # 形状：事件圆 / 网关菱形 / 任务角标 / 子流程标记 / 数据对象 / 注释 / 池泳道
@@ -579,7 +622,7 @@ src/
 | `npm run build` | 清理并完整构建（类型声明 + JS 产物） |
 | `npm run types:check` | 仅做 TypeScript 类型检查 |
 | `npm test` | 运行单元测试（Jest） |
-| `npm run test:e2e` | 浏览器端到端回归（Playwright，覆盖 `tests/entity-editor.html` 与 `tests/flowchart-editor.html`） |
+| `npm run test:e2e` | 浏览器端到端回归（Playwright，覆盖 `examples/entity-editor.html` 与 `examples/flowchart-editor.html`） |
 | `npm run pretty` | Prettier 格式化源码 |
 
 ## 9. 环境要求与依赖