ice-entity-designer 0.0.17 → 0.0.19

package/README.md

@@ -76,6 +76,12 @@ IED（ice entity designer）是基于 [ice-render](https://github.com/ice-render
 
 <img src="./tests/assets/editor.png" alt="交互式编辑器与 TypeORM Schema" />
 
+同一套内核也能承载**流程图**（`tests/flowchart-editor.html`）：四类节点（开始/结束、处理、判定、输入/输出，
+其中判定菱形与输入输出平行四边形是自定义 `ICEPath` 形状）、正交/贝塞尔连线 + 分支标签（是/否）、
+拖拽 / 连线 / 撤销重做 / 快照存取：
+
+<img src="./tests/assets/flowchart-editor.png" alt="流程图编辑器示例" />
+
 ## 4. 快速开始
 
 ```bash
@@ -88,6 +94,7 @@ npm run build
 | 示例 | 说明 |
 |---|---|
 | `tests/entity-editor.html` | 交互式编辑器：实时编辑字段、创建/删除实体与关系、校验与保存加载；右侧面板含「TypeORM Schema」标签页 |
+| `tests/flowchart-editor.html` | 流程图编辑器：四类节点形状、拖拽、连线（含分支标签）、撤销重做、localStorage 存取与 JSON 导出；纯 DOM 面板，只依赖 `dist` 产物 |
 | [`ice-entity-designer-react-demo`](../ice-entity-designer-react-demo) | 独立的 React 集成示例工程（webpack + TypeScript），涵盖 ref / hook / onChange / 受控模式 |
 
 ```bash
@@ -122,10 +129,17 @@ const issues = designer.validate(); // 校验问题列表
 
 // 项目存取与历史
 const snapshot = designer.serializeProject();
-designer.loadProject(snapshot);
+const report = designer.loadProject(snapshot); // 非法 / 版本不兼容的快照会抛错，且不会改动当前项目与历史栈
+// report = { loaded, entities, relations, unknownTypes, skipped }
 designer.undo();
 ```
 
+#### 5.1 项目快照契约
+
+- 快照带 `schemaVersion`（当前 `1`）与每个节点的 `typeId`；载入时**按 `typeId` 分派构造函数**（走 ICE 注册表，下游 `ice.registerType()` 注册的领域图元同样可载入）。旧快照没有 `typeId` 时，按所在数组归位（`entities[]` → `Entity`，`relations[]` → `Relation`）。
+- **容错加载**：遇到未注册的 `typeId` 只跳过该节点并记录（`report.unknownTypes` / `report.skipped`），不会让整份数据打不开——与引擎 `Deserializer` 的语义一致。
+- **自洽保证**：`serializeProject()` 的产物永远能通过 `loadProject()` 的结构校验（结构契约见 `src/utils/project-snapshot.schema.json`）；载入失败时当前项目与 `undo`/`redo` 栈都不会被改动。
+
 也支持更底层的组件式用法：
 
 ```js
@@ -141,6 +155,36 @@ import { EntitySchema } from 'typeorm';
 const schemas = designer.toSchemaObject().map((obj) => new EntitySchema(obj));
 ```
 
+#### 5.2 流程图（FlowDesigner）
+
+包内除 ER 之外还内置了一套**流程图**领域图元与应用层（同一个 `ice` 实例即可承载）：
+
+```js
+import { ICE, FlowDesigner } from 'ice-entity-designer';
+
+const ice = new ICE().init('canvas-1');
+const flow = new FlowDesigner(ice);
+
+const start = flow.createNode('terminator', { title: '开始' });
+const check = flow.createNode('decision', { title: '库存充足？' });
+flow.createEdge({ sourceId: start.state.id, targetId: check.state.id, sourcePort: 'B', targetPort: 'T' });
+
+flow.fitViewport(); // 适应视图
+flow.serialize(); // 流程图快照（version / kind / nodes / edges）
+flow.undo(); // 100 步历史
+```
+
+| 能力 | API |
+|---|---|
+| 节点类型 | `createNode('terminator' \| 'process' \| 'decision' \| 'io', props)`；预设尺寸 / 配色见 `FLOW_NODE_KINDS` |
+| 连线 | `createEdge({ sourceId, targetId, sourcePort, targetPort, label, linkShape })`；插槽位置 `T/R/B/L/C`，节点拖动时连线自动跟随 |
+| 增删改查 | `nodes` / `edges` / `selected` / `select()` / `updateNode()` / `updateEdge()` / `remove()`（删节点级联删连线）/ `clear()` |
+| 历史与快照 | `undo()` / `redo()` / `canUndo()` / `canRedo()`、`serialize()` / `toSnapshot()` / `load()`（返回 `{ loaded, nodes, edges, skipped }`） |
+| 视图与订阅 | `fitViewport(padding)`、`subscribe()`、`dispose()` |
+
+自定义形状（判定菱形 / 输入输出平行四边形）在 `src/flow/flow_shapes.ts`，走的是引擎的 `ICEPath` 子类机制。
+可运行的完整示例见 `tests/flowchart-editor.html`；AI Agent 生成流程图的 JSON DSL 见 `ice-entity-designer-dsl`。
+
 ## 6. 在 React 中使用
 
 包内置 React 绑定（子路径导出 `ice-entity-designer/react`），不需要自己写 ref / effect 胶水代码。
@@ -194,6 +238,7 @@ export default function App() {
 | `value` | `string` | **受控**：项目快照，变化时同步进画布（内部变更经 `onChange` 上报，带循环保护） |
 | `defaultValue` | `string` | **非受控**：初始项目快照 |
 | `onChange` | `(payload: { snapshot, schema }) => void` | 模型变更（增删改 / 载入 / undo / redo）后触发，`snapshot` 可直接用于自动保存 |
+| `onError` | `(payload: { phase, snapshot, error }) => void` | 快照载入失败（非法 / 版本不兼容）时触发，默认 `console.error`；组件内部已捕获，不会把异常抛进渲染树 |
 | `onReady` | `(handle) => void` | 实例就绪，回调里拿到命令式句柄 |
 | `width` / `height` | `number` | 画布尺寸，默认 `1200 × 800` |
 | `renderMode` | `'dirty-rect' \| 'full'` | 渲染模式，默认 `dirty-rect` |
@@ -238,6 +283,11 @@ const session = createDesignerSession(canvasEl);
 ```
 src/
 ├── designer/EntityDesigner.ts     # 应用层：选择 / 增删改 / 连接 / 校验 / 历史 / 项目存取 / 变更订阅
+├── flow/                          # 流程图（与 ER 并列的第二类领域图元）
+│   ├── flow_shapes.ts             # 自定义形状：判定菱形 / 输入输出平行四边形
+│   ├── FlowNode.ts                # 节点：四类预设（起止 / 处理 / 判定 / 输入输出）+ 居中标题
+│   ├── FlowEdge.ts                # 连线：正交 / 贝塞尔 + 箭头 + 分支标签，插槽吸附
+│   └── FlowDesigner.ts            # 应用层：建节点/连线、选择、增删改、历史、快照存取、适应视图
 ├── er-component/
 │   ├── Entity.ts                  # 实体：表头 + 字段列表 + 约束标记 + TypeORM 序列化
 │   └── Relation.ts                # 关系：基数 / 箭头 / 标签语义 / 连接槽位
@@ -262,6 +312,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 pretty` | Prettier 格式化源码 |
 
 ## 9. 环境要求与依赖