Files
ssw-mpc-flow/README.md
T
admin ee8c6c5e64 feat(engine): 执行底座改用 ssw-mpc 版本二进制包 + 运行时能力降级
上游已按版本发布 mpc 单二进制到 Gitea Release,本项目不再从源码构建,
改为下载版本包并做双重校验:
- scripts/install-mpc.sh:按 uname 选产物、比对 Release 的 SHA256SUMS、
  装完再跑 mpc selfcheck 让二进制自报摘要对账;落 <项目根>/.mpc/bin/<tag>/mpc
- mpc-client.ts:二进制解析顺序改为 MPC_BIN → 版本包(取语义化版本最高)
  → 仓库 release/debug 构建 → PATH;新增 binSource 字段与中文标签
- engine-registry / mpc-engine / mpc-operator-map:新增 probeCliSubcommands()
  逐个探测子命令,缺哪个就把对应算子 native → partial 并写明原因
  (applyRuntimeCapability),Engine/Info 的 cliProbe 字段如实给出探测结果

★ 版本包不含 secure feature ⇒ mpc sql/sql-plan/sql-join/pg 不存在
  (实测 exit=2 + 「未知命令: sql」),相关算子按实降级为 partial。

门禁复跑全绿:check-module 219/0 + 21/0 + 21/0、perm-smoke 32/0、
sswflow-smoke 46/0,后端/前端 tsc 0 错。实测 mpc selfcheck 通过
(sha256 394fc5fd… 与 manifest 一致)。
2026-11-10 17:02:19 +08:00

456 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ssw-mpc-flow · 隐私计算编排
从 `ssw-mvp` 抽出隐私计算编排(sswflow)域,重构为独立项目:
**框架换成 JNPF Lite + NestJS/React,执行底座换成 `ssw-mpc`(Rust)**。
原始 `ssw-mvp` 是 Spring Boot + Vue + 自研 NAX 执行层;本项目保留其业务语义与数据契约,
替换掉框架胶水层和执行引擎。
---
## 快速开始
```bash
./run.sh install # 安装前后端依赖
./run.sh build # 生成 db/schema.sql + 构建前后端
./run.sh mpc # 安装 ssw-mpc **版本二进制包**(上游 Release 产物,自动校验 sha256)
./run.sh dev # 起后端(30000) + 前端(5173)
```
打开 http://127.0.0.1:5173 ,默认账号 `admin` / `123456`。
数据库用嵌入式 **PGlite**(WASM Postgres,零服务进程 / 零 docker),引擎即真 PostgreSQL,
所以 `f_` 列 / `varchar(50)` / Postgres 方言契约完全保留。设 `PGLLITE_DIR=./.pglite` 可持久化。
### 执行底座:版本二进制包(不本地编译 Rust)
上游 `ssw-mpc` 已按版本发布 `mpc` 单二进制(Gitea Release),本项目**直接用版本包**,不在本机编 Rust:
```bash
./run.sh mpc # 装 latest(当前平台)
./run.sh mpc --tag v0.2.0 # 装指定版本
./run.sh mpc --list # 看远端版本 + 本地已装
./run.sh mpc --uninstall # 移除本地已装
```
落盘在 `<项目根>/.mpc/bin/<tag>/mpc`(已 gitignore)。安装时会:
1. 下载 Release 里的 `SHA256SUMS` + 对应平台产物;
2. **校验 sha256**,不符直接拒绝安装;
3. 装完跑一次 `mpc selfcheck`,让二进制自报摘要与 Release 对账。
后端按 `MPC_BIN` → 本地已装版本包 → 仓库构建产物 → PATH 的顺序找二进制,
`GET /api/ssw/sswflow/Engine/Info` 会如实展示**二进制来源与版本号**。
> ⚠️ **版本包与源码构建的能力面不同**:版本包是 `--features vendored` 构建(静态 OpenSSL),
> **不含 `secure` feature** ⇒ `mpc sql / sql-plan / sql-join / pg` 这几个子命令**不存在**。
> 本项目因此在运行时**实测**二进制支持哪些子命令,缺哪个就把对应算子从 `native` 降级为
> `partial` 并写明原因(界面与运行事件里都如实标注,不会把跑不了的算子说成原生支持)。
灌演示数据(幂等,可重复跑):
```bash
node scripts/seed-demo.js # 隐私计算编排:参与方 / 项目 / 数据集 / DAG 流程 / 调度
node scripts/seed-infra.js # 设备注册 + 链上存证:**拉真实数据**(控制面 + 真链),不灌假数据
node scripts/seed-infra.js --list # 只看当前库里有什么
node scripts/seed-infra.js --tx 0x<hash> # 额外查一笔 FISCO 链上出块回执
```
---
## 与原项目的关系
| 层 | ssw-mvp(本项目来源) | ssw-mpc-flow(本项目) |
|---|---|---|
| 后端框架 | Spring Boot + MyBatis-Plus | NestJS + TypeORM |
| 前端框架 | Vue 2 + Element UI | React 18 + Vite |
| 权限底座 | JNPF 底座 + TDS/TDC 胶水 | JNPF Lite 契约自建(轻量、可平移) |
| 执行引擎 | NAX / RemoteNax / TeeComputeEngine | **ssw-mpc** Rust CLI |
| 画布组件 | VueFlow(`@vue-flow/core`) | **React Flow(`@xyflow/react`)**——xyflow 同门,API 一一对应 |
### 被裁掉的东西
- **TDS / TDC 胶水**:跨方 HTTP 转发、SSE 推送、审批待办链。前端改为轮询运行事件(等价物)。
- **NAX 执行层**:整体替换为 `ssw-mpc`。NAX 的 `ComputeEngine` SPI 抽象保留为 `ComputeEngine` 接口,
换底座不用动业务代码。
### 被保留的东西
- **DAG 数据契约**(前后端完全一致):
```ts
steps: [{ stepId, operatorKey, label, x, y, params: {} }]
edges: [{ edgeId, sourceStepId, sourcePort, targetStepId, targetPort }]
```
- **运行状态机**:`run` 与 `step` 的 PENDING → RUNNING → SUCCESS/FAILED/STOPPED/SKIPPED。
- **6 种运行范围**:`FULL / SINGLE / SELECTED / UPSTREAM / DOWNSTREAM / RESUME`。
- **端口级连线语义**:上游产物按端口装配成本节点输入,不是整图广播。
- **JNPF 数据契约**:`f_` 前缀列、`f_id VARCHAR(50)` UUID 主键、`f_delete_mark` 软删、`ActionResult` 返回体。
### 关于画布组件:VueFlow → React Flow
原实现用的是 **VueFlow**(`@vue-flow/core` + `@vue-flow/background` + `@vue-flow/minimap`),
不是 LogicFlow(全仓 0 引用)。
VueFlow 与 **React Flow(`@xyflow/react`)** 是 xyflow 家族的两个前端实现,
核心概念(节点/边/Handle/视口/自定义节点)完全同构,API 几乎一一对应,
所以迁移是**平移**而不是重写:
| VueFlow(原实现) | React Flow(本项目) |
|---|---|
| `<VueFlow v-model:nodes v-model:edges>` | `<ReactFlow nodes edges onNodesChange onEdgesChange>` |
| `useVueFlow()` | `useReactFlow()`(需包 `<ReactFlowProvider>`) |
| `nodeTypes` | `nodeTypes` |
| `defaultEdgeOptions` | `defaultEdgeOptions` |
| `addEdge(params, edges)` | `addEdge(params, edges)`(导入时注意与本地同名函数区分) |
| `<Handle type="target" :position="Position.Left" />` | `<Handle type="target" position={Position.Left} id="left" />` |
| `fitView()` / `zoomIn()` / `zoomOut()` | `fitView()` / `zoomIn()` / `zoomOut()`(`useReactFlow()`) |
| `<Background :gap="16" />` | `<Background variant={BackgroundVariant.Dots} gap={16} />` |
| `<MiniMap />` | `<MiniMap />` |
| `<Panel position="top-right">` | `<Panel position="top-right">` |
| `@connect="onConnect"` | `onConnect={onConnect}` |
| `isValidConnection` / `connection-radius` | `isValidConnection` / `connectionRadius` |
两处值得记录的差异:
- **受控模式**:VueFlow 用 `v-model` 直接双向绑定;React Flow 走 `applyNodeChanges` /
`applyEdgeChanges` 把 change 事件回灌进 React state,本项目在 `Flow.tsx` 中显式实现了
`onNodesChange` / `onEdgesChange`。
- **端口 id 即端口 key**:React Flow 的 `sourceHandle` / `targetHandle` 直接存算子端口 key
(`prep.intersect` 的 `left`/`right`、`model.predict` 的 `model`/`in`),
与后端 `edge.sourcePort` / `edge.targetPort` 逐字对应,无需再做映射表。
**端口锚点比原实现更完整**:原 `SswNode.vue` 只有固定的 `in`/`out` 两个 Handle,
所以 `prep.intersect` 的 `left`/`right`、`model.predict` 的 `in`/`model`
在 UI 上无法区分(后端校验会报「输入端口未连线」)。本项目的 `SswNode.tsx`
按算子 `catalog.json` 的 ports 动态渲染 N 个 Handle,多端口算子的每个端口都能独立拖线。
---
## 目录结构
```
src/backend/ NestJS + TypeORM
src/sswflow/ 业务域(12 张表 + 14 个控制器)
engine/ 执行引擎层
flow-graph.ts DAG 解析 / 校验 / 拓扑排序 / 上下游闭包
compute-engine.ts ComputeEngine SPI(可插拔执行引擎)
engine-registry.ts 引擎选路(mpc / simulation)
mpc-engine.ts ssw-mpc 执行引擎
simulation-engine.ts 本地模拟引擎(无 Rust 依赖时兜底)
mpc-operator-map.ts 19 算子 → ssw-mpc 能力映射 + plan 编译
mpc-client.ts Rust CLI 调用 / 探测 / orch plan 执行
catalog/ 算子协议目录(catalog.json 为唯一事实来源)
src/sswdevice/ 设备注册模块(1 张表 + 1 控制器)—— 对接控制面节点注册表
src/sswchain/ 链上存证模块(1 张表 + 1 控制器)—— 对接 outbox + FISCO 回执
db/schema.sql 18 张表(由 scripts/gen-schema.js 从实体自动生成)
src/frontend/ React 18 + Vite
src/views/Flow.tsx DAG 画布编辑器(算子面板 + 画布 + 属性面板)
src/views/FlowRun.tsx 运行监控(步骤 / 事件 / 产物)
src/views/Device.tsx 设备注册(TEE 节点)—— 数据源:control-plane
src/views/ChainBlock.tsx 链上存证(Receipt)—— 数据源:chain outbox + FISCO
scripts/
gen-schema.js 实体 → schema.sql 生成器(防漂移)
check-module.sh 模块规范检查
perm-smoke.sh 登录 / 菜单权限冒烟
seed-demo.js 隐私计算编排演示数据
seed-infra.js 设备注册 + 链上存证:**触发真源同步**
```
---
## 业务模块一览
| 模块 | appCode | 路径 | 表 | 说明 |
|---|---|---|---|---|
| 隐私计算编排 | `sswflow` | `/sswflow/*` | 12 | DAG 画布、算子目录、可插拔执行引擎、运行监控 |
| 设备注册 | `sswdevice` | `/sswdevice/Device` | 1 | TEE 节点注册表,**真源 = ssw-mpc 控制面 `GET /nodes`**(在线清单,含下线标记) |
| 链上存证 | `sswchain` | `/sswchain/ChainBlock` | 1 | Receipt / FISCO 回执,**真源 = ssw-mpc outbox + 国密链** |
三个模块共用同一套 JNPF-Lite 契约:`f_` 前缀列、`f_id VARCHAR(50)` UUID 主键、
`f_delete_mark` 软删、`ActionResult` 返回体、模式 B 守卫(登录 + 菜单权限),
路径统一为 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`。
---
## 设备注册:对接 ssw-mpc 控制面
**这不是手工登记的设备表**,而是 TEE 节点经 `mpc hostd` 向 `mpc control-plane`
自报后的注册表投影。前端「从控制面同步」调 `POST /api/ssw/sswdevice/Device/Sync`,
后端打 `GET {MPC_CONTROL_PLANE_URL}/nodes` 并 upsert。
### TeeNode 真实字段(23 列,逐一对应)
| 列 | 来源字段 | 实测取值 |
|---|---|---|
| `f_key` | `key` | `site@host`(如 `alice@192.168.1.7`) |
| `f_site` / `f_host` | `site` / `host` | `alice` / `192.168.1.7` |
| `f_platform` | `platform.kind` | `sev-snp`(AMD)/ `hygon-csv`(海光) |
| `f_tcb` | `platform.tcb` | 整数:AMD SNP=5,海光 CSV2=3 |
| `f_capacity` | `capacity` | 并发槽位 |
| `f_last_seen` | `last_seen` | Unix 秒(bigint) |
| `f_device_present` / `f_qemu_present` / `f_firmware_present` / `f_image_present` | 同名 | 能力位,**漏填即被 `admit` 拒绝** |
| `f_kbs_reachable` | `kbs_reachable` | KBS 是否可达 |
| `f_kbc` | `kbc` | `cc_kbc` / `offline_fs_kbc::null`(**不是** online/offline) |
| `f_measurement` | `measurement[32]` | 镜像度量 hex |
| `f_kbs_endpoint` | descriptor 的 `kbs_endpoint` | ★ `node_to_json` **没有**这个字段,只能从 descriptor 解析 |
| `f_descriptor` | `descriptor` | 原始描述符全文(`key=value` 逐行) |
| `f_online` | — | **本表自己算的**:1=此刻在真源清单里 / 0=已掉线 / null=从未同步过 |
| `f_source` / `f_source_reason` | — | `control-plane` / 失败原因 |
### ★ 下线语义:`/nodes` 是「当前在线清单」,不是注册档案
控制面 `ControlPlane::prune_stale()` 会**自动剔除**超过 `node_ttl_secs`
(默认 **90 秒**)未心跳的节点(`crates/mpc-tee/src/control_plane.rs`)。
所以 `GET /nodes` 返回的是**此刻活跃的节点**,不是「注册过的历史档案」。
这带来一个必须处理的问题:**真源里消失的节点,在库里会留下旧行**,
前端会让人误以为该设备还在线。同步逻辑因此区分三态:
| `f_online` | 含义 |
|---|---|
| `1` | 本次同步出现在真源清单里 ⇒ 此刻在线 |
| `0` | 真源里已经没有它(掉线 / TTL 过期)⇒ 同步时自动标出,**不软删、不物理删** |
| `null` | 从未同步过(人工登记)⇒ 前端显示「未登记」 |
同步结果会额外返回 `offline` 计数(本次被标成离线的节点数),前端摘要显示「下线 N 个」。
**★ fail-closed 的延伸**:只有**真源读取成功**(`source !== 'mock'`)时才做下线。
控制面不可达时拿到的 0 条节点**不代表所有设备都掉线** —— 此时标离线就是误报,
所以 `offline` 恒为 0,`f_online` 保持原值。
**★ 人工登记不能篡改真源权威字段**:`save()` 会剥掉 `online` / `source` / `sourceReason`,
人工只能填描述性字段(站点、主机、平台、度量、描述符等),
能力位与在线状态一律来自真源。
### 控制面鉴权口径(`crates/mpc-hostd/src/auth.rs`)
- 配了共享密钥 ⇒ 必须带 `Authorization: Bearer <明文密钥原文>`
(≥32 字节、纯 ASCII、**不许含空白**)。服务端只存 SHA-256 摘要,常量时间比对。
- 没配密钥(回环信任模式)⇒ 不带凭据放行,**带了任何凭据一律拒**。
- ★ 已知坑:下发曾用 `hex_encode(secret)`,节点校验明文 ⇒ 全 401。token 必须是**原文**。
- ★ 对外统一一句「缺少或无效的凭据」,不区分 missing / malformed / mismatch。
### fail-closed
真源读不到 ⇒ 返回 **0 条** + `source=mock` + 原因,**绝不用假数据顶**。
注册表为空时 `GET /nodes` 返回空数组(不是 404)。
---
## 链上存证:对接 outbox + FISCO 国密链
**这不是通用区块浏览器**:`mpc chain` **没有**区块浏览命令,链上对象只有
`Receipt` / `Member` / `PolicyBundleRecord` 三类。所以这里做的是
**链上对象 / Receipt / 回执浏览器**。
### Receipt 二进制布局(`crates/mpc-chain/src/objects.rs`)
outbox 的 payload 是 `canonical_bytes` 的 hex,本项目实现了逆解:
```
"mpc/tee/chain/object/v1" 固定 25 字节,无长度前缀
push_field("receipt") 4 字节大端长度前缀 + "receipt"
"v1" 固定 2 字节
push_field(order_id) 变长
push_field(decision_id) 变长
result_hash[32] / input_hash[32] / user_data[64]
attest: 4 个 u8(user_data_ok / meas_ok / tcb_ok / chip_sig)
push_field(link) 变长(p2p / relay / unknown)
link_binding[32]
(signatures 故意不写 —— 签名是产物不是被签内容)
```
### ★ 「验证通过」必须拆成四句
`user_data_ok` / `meas_ok` / `tcb_ok` / `chip_sig` **分开报**,不许合并成一个 `ok=1`。
`chip_sig = 否` 的含义是「**绑定成立但没做芯片验签**」,不是「没绑定」。
### ★ FISCO 成功判据三件套
```
status == 0 ← TransactionStatus::None = 成功(与 web3 的 0x1 相反)
transactionHash 非空 ← FISCO 自有字段名,不是 txHash
blockNumber > 0 ← 进交易池但没出块时是 0,那只是「已受理未上链」
```
### ★ FISCO 自有 RPC 端点(不是 web3 那套)
| 用途 | 方法 | 参数 |
|---|---|---|
| 查回执 | `getTransactionReceipt` | 4 参 `[groupID, nodeName, txHash, requireProof]` |
| 只读调用 | `call` | 4 参 `[groupID, nodeName, to, data]`(第 5 参是**签名**不是 `"latest"`) |
| 提交交易 | `sendTransaction` | 4 参 `[groupID, nodeName, data(hex), requireProof]` |
| 链高度 | `getBlockNumber` | ★ **只接受 0 参**(`params:[]`) |
真链对 `eth_getTransactionReceipt` / `eth_call` 一律回 `-32601`。
**HTTP 200 ≠ 成功** —— 错误在 body 的 `error` 对象里;`result: null` = 还没出块。
### ★ 实测发现的边界
- **`recordHardRule` 的 `orderId` 长度必须 ≤ 16 字节**:17 字节起 `status=16` revert、
output 为空。根因是 FISCO solidity 编译器对 `bytes.concat` 的长度限制。
- **`chain contract deploy --bin` 参数被忽略**:实际读的是 `--abi` 文件,
且要求 combined.json(`{"contracts":{...}}`)或 `{abi,bin}` 形状,裸 `.bin` 文件不认。
- **合约调用需 `EVM_ABI_CODEC(0x1)` attribute**(写调用 attribute = 0)。
- **selector 是二元数组** `[keccak_u32, sm3_u32]`,国密链调用用 **`SM3(signature)[0..4]`**:
`recordHardRule`=`4461f95a`、`isRecorded`=`a3414302`、`hardRuleSummary`=`73a3d38c`。
### ★ outbox 语义
- 行格式:`v1|key|state|attempts|payload_hex|last_error_hex`(6 段缺一即坏行 → **整表拒绝**)。
- `state`:`P`(Pending) / `C`(Confirmed)。★ **Confirmed 只代表已广播,不代表已出块确认**。
- 幂等键 = `kind:order_id:decision_id`;同键重复提交不新增、**不覆盖**。
### 端点
| 端点 | 说明 |
|---|---|
| `Device/{List,Save,Delete}` | 设备 CRUD |
| `Device/Sync` | 从控制面同步节点注册表 |
| `ChainBlock/{List,Save,Delete}` | 存证 CRUD |
| `ChainBlock/Sync` | 从真链同步(body 可带 `txHash` 查链上出块回执) |
### 环境变量(这两个模块)
| 变量 | 默认 | 说明 |
|---|---|---|
| `MPC_CONTROL_PLANE_URL` | `http://127.0.0.1:3020` | 控制面地址 |
| `MPC_HOSTD_SHARED_SECRET` | — | 共享密钥**原文**(非 hex) |
| `MPC_FISCO_CHAIN_CONFIG` | `../ssw-mpc/tools/fisco-realnode/example.chain.json` | 链配置(rpc_endpoint / group_id) |
| `MPC_FISCO_OUTBOX` | `<stateRoot>/chain-outbox.txt` | outbox 路径 |
| `MPC_FISCO_NODE` | `node0` | FISCO nodeName |
---
## 算子目录(19 个)
`catalog.json` 是画布节点类型 / 端口 / 参数的唯一事实来源,7 个分类:
| 分类 | 数量 | 算子 |
|---|---|---|
| `source` 数据接入 | 1 | `source.dataset` |
| `prep` 数据预处理 | 5 | `prep.intersect` `prep.sample` `prep.split` `prep.fillna` `prep.binning` |
| `stat` 统计分析 | 4 | `stat.profile` `stat.correlation` `stat.iv` `stat.scql` |
| `model` 联合建模 | 6 | `model.lr.train` `model.gbdt.train` `model.mlp.train` `model.fedavg.train` `model.predict` `model.evaluate` |
| `sink` 结果输出 | 1 | `sink.export`(**唯一 terminal**) |
| `tee` 机密计算 | 1 | `tee.privacy_aggregate` |
| `zkp` 零知识证明 | 1 | `zkp.prove` |
### ssw-mpc 能力映射(诚实标注,不粉饰)
| 状态 | 数量 | 含义 |
|---|---|---|
| `native` | 4 | 有对应 Rust CLI 子命令,可真实下发 |
| `partial` | 6 | ssw-mpc 能力部分对齐,回退模拟并写 WARN |
| `local` | 7 | 编排层职责(明文数据准备 / 统计 / 评估 / 导出),无需下发 Rust |
| `unsupported` | 1 | `model.gbdt.train`,ssw-mpc 无对应实现 |
`native` 的 4 个:`prep.intersect`(PSI) `stat.scql`(SQL) `model.lr.train`(LR) `model.fedavg.train`(FedAvg)。
---
## 执行底座:ssw-mpc 适配层
**不修改 `ssw-mpc` 的 Rust 源码。** 原因:
- `mpc-ir` 的 21 个 `Op` 是内部 IR,**无 JSON / serde 序列化**,不能由 NestJS 直接提交。
- `mpc hostd` 只管理 TEE sandbox,**不是 DAG 提交接口**。
- `mpc-demo` 的 HTTP 仅用于单算子参考,**不是生产执行协议**。
因此适配层把画布编译为 **固定 CLI argv**:
```
mpc psi --site alice --sites alice,bob --ids 1,2,3
mpc lr --data-x 1,2,3,4 --data-y 0,1,1,0 --n 4 --d 2 --epochs 10 --lr 0.1
mpc fl --clients 2 --features 4 --per-client 50 --rounds 3
mpc sql --sql "SELECT count(*) FROM t"
```
整图依赖编译为 **`mpc orch run --plan`** 的文本计划:
```text
job A
deps -
expect 35
data alice=1,2,3 bob=4,5,6
```
`orch run` 同步执行,stdout 输出稳定 NDJSON、stderr 输出进度、exit code 表示整体成败;
JSONL / `orch status` 用于崩溃恢复和审计。
### 环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
| `MPC_DRIVER` | `simulation` | `mpc` 时启用 ssw-mpc 引擎并置于选路首位 |
| `MPC_REAL_EXEC` | `0` | `1` 时真实起 Rust 进程;否则只生成命令写进运行事件(可审计),产物标记 `simulated` |
| `MPC_ORCH_EXEC` | `0` | `1` 时真实执行 `mpc orch run` |
| `MPC_SITES` | `alice,bob` | 各方站点名 |
| `MPC_BIN` | 自动探测 | `mpc` 可执行文件路径(不设则按「版本包 → 仓库构建 → PATH」自动找) |
| `MPC_BIN_DIR` | `.mpc/bin` | 已安装版本包的目录(`scripts/install-mpc.sh` 的落盘位置) |
| `MPC_WORK_DIR` | `../ssw-mpc` | ssw-mpc 仓库路径(用于找 chain.json / 合约 ABI 等**素材**,不用于找二进制) |
| `MPC_DEMO_URL` | — | demo HTTP 算子服务地址 |
> ⚠️ `mpc psi` / `lr` 等会话类子命令需要各方 `mpc agent` 进程在场,单进程调用会等到超时。
> 生产部署请配合 ssw-mpc 的 deploy/ 起多方,或用 demo HTTP 算子服务。
>
> ★ **二进制解析顺序**:`MPC_BIN` → 已安装版本包(`.mpc/bin/<tag>/mpc`,取版本号最高的)
> → 仓库 `target/release/mpc` → 仓库 `target/debug/mpc` → PATH。
---
## API 契约
路径形如 `/api/ssw/sswflow/{Entity}/{List|Save|Delete}`,返回统一 `ActionResult`:
```json
{ "code": 200, "msg": "success", "data": { } }
```
前端 `request.ts` 统一解包 `data`,并处理 `600/601/602` → 清 token 跳登录。
sswflow 域主要端点:
| 端点 | 说明 |
|---|---|
| `Flow/{List,Save,Delete}` | 流程 CRUD |
| `Flow/Canvas` | 保存画布(steps/edges 以 JSON 字符串落 `f_steps`/`f_edges`) |
| `Flow/Validate` | DAG 校验(返回 issues + 拓扑序) |
| `Flow/Copy` | 复制流程 |
| `Flow/CompilePlan` | 编译为 ssw-mpc 作业计划(不执行) |
| `Operator/Catalog` | 算子目录 + 每个算子的 ssw-mpc 能力状态 |
| `Engine/Info` | 引擎自检:当前驱动、Rust 二进制探测、19 算子能力分布 |
| `FlowRun/{Start,Stop,Events,Steps,Artifacts}` | 运行生命周期与可观测性 |
菜单权限守卫按 `base_module.f_url_address` 匹配,与前端路由 path 一一对应。
---
## 迁回 JNPF 的路径
1. 关闭 TypeORM `synchronize`,改用 `db/schema.sql` 显式建表(已生成,Postgres 方言,13 张表)。
2. `base_module` 表插入 14 条 sswflow 菜单(见 `sys/seed.service.ts` 的 `menus` 数组,已内置)。
3. 实体类可平移到 JNPF 的 `SuperEntity` 子类,列名与 JNPF 原生 `f_` 契约一致,无需改名。
4. `ActionResult` 与前端 `request.ts` 是 1:1 对应 JNPF `ResultExceptionHand` / `defHttp` 拦截器。
---
## 环境要求
- Node.js ≥ 18
- 无需 Docker、无需独立 PostgreSQL(PGlite 内嵌)
- 可选:`ssw-mpc` **版本二进制包**(仅 `MPC_DRIVER=mpc` + `MPC_REAL_EXEC=1` 时需要)
—— 用 `./run.sh mpc` 装,**不需要本机 Rust 工具链**。
### 附带的 API 端点说明
| 端点 | 说明 |
|---|---|
| `GET /api/ssw/sswflow/Engine/Info` | 引擎自检:驱动、**二进制来源与版本号**、实测子命令可用性、19 算子能力分布 |
> `Engine/Info` 的 `mpc` 字段会如实给出:`binSource`(版本包 / 仓库构建 / PATH)、
> `binSourceLabel`(中文说明)、`releaseTag`(版本包 tag)、`cliProbe`(实测到的子命令可用性)。
> 界面顶部也会显示「执行底座 + 二进制来源 + 版本号」。