Files
dacli/docs/web-patches/sswflow-api-client.md
sushub f403a7e80e import: ssw/dacli@eea0ebc (2026-08-12) 起点版本
本仓 2026-08-12 从 ssw main (192.168.1.18:13300/ssw/ssw-mvp) 的
dacli/ subpath 抽取,作为独立仓托管到 gitea:3000/ssw/dacli.git。

- 工作树为 ssw main dacli subpath 最新版 (110 commit, 08-12)
- 历史未带 ssw main 整体历史(避免大仓污染)
- 此为新仓基线 commit,未来以本仓历史为主
2026-08-12 15:58:06 +08:00

4.7 KiB

sswflow API Client — 专业前端领域 adapter

记录日期: 2026-08-01 (sswflow M1 Task 12) 关联任务: design §5.3 (后端组件) + design §10.3 (专业前端浏览器链路) + plan §12 (Step 1 冻结契约)

背景

专业前端 web/.../views/ssw/sswflow/** 需要调用后端 boot/ssw-sswflow/** 暴露的领域 API. 不能复用通用表单的 webapi, 必须新建一个 adapter 路径.

源文件 → 镜像文件

维度 web 端领域代码 说明
web 类型 web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/types.ts 业务领域类型 (不污染 JNPF 通用类型)
Flow API web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/flow.ts 画布/校验/详情
Run API web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/run.ts 启动/停止/事件/概览/产物
Operator API web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/operator.ts 算子目录 (后端原始 JSON)

契约 (来自 plan §12 Step 1, 已冻结)

方法 URL 后端返回 用途
GET /api/ssw/Flow/{id} FlowEntity 拉画布详情
PUT /api/ssw/Flow/{id}/Canvas { data: id } 保存画布
POST /api/ssw/Flow/{id}/Validate { valid, errors[] } DAG 校验
POST /api/ssw/FlowRun/Start FlowRunEntity 启动运行
POST /api/ssw/FlowRun/{runId}/Stop { data: runId } 停止运行
GET /api/ssw/FlowRun/{runId}/Events?afterSeq=X { events, nextSeq, hasMore } 事件分页
GET /api/ssw/FlowRun/{runId}/Overview { run, steps, artifactCount, stepStatusCount, finished } 概览
GET /api/ssw/FlowRun/{runId}/Artifacts ArtifactEntity[] 产物列表
GET /api/ssw/FlowRun/ByFlow?flowId=... FlowRunEntity[] 运行列表
GET /api/ssw/Operator/Catalog 原始 JSON (不经 ActionResult 解包) 算子目录
GET /api/ssw/FlowRun/{runId}/Stream SSE text/event-stream 实时事件 (由 useRunStream 处理)

与 JNPF 通用 defHttp 的差异

  • 算子目录端点 /api/ssw/Operator/Catalog 后端直接返回原始 JSON, 不走 JNPF ActionResult 包装. 客户端必须用原生 fetch 而非 defHttp, 否则会被 ActionResult 解包吞掉.
  • 其他 10 个端点都走 defHttp, 经 ActionResult 解包.

鉴权 SSE 契约 (红线 #14)

浏览器原生 EventSource 不支持自定义 Authorization header. useRunStream 必须用:

  • fetch(url, { headers: { Authorization: 'Bearer <token>', 'X-Jnpf-AppCode': '<appCode>' } })
  • 解析 ReadableStream SSE 事件
  • 终态 (SUCCESS/FAILED/STOPPED) 关闭 stream

不暴露任何拼接 ?token=... 的 URL.

验证命令

# 单元测试 (mock defHttp + fetch)
pnpm exec vitest run apps/jnpf-web-apps-main/src/api/ssw/sswflow

# typecheck
pnpm --filter @jnpf/main typecheck

# 实际打通 (待 ssw-sswflow controller 编译就绪 + 启动后)
curl -H "Authorization: Bearer <token>" http://nginx/api/ssw/Operator/Catalog

升级重放

后续 JNPF / dacli 升级时:

  1. 后端 controller 路径变化: 路径前缀 /api/ssw/* 是 SSW 平台自有契约, 不应跟 JNPF 通用前缀混淆. 升级时优先观察 boot/ssw-common/SSWController 基类是否变化.
  2. Operator Catalog spec 版本变更: 后端 catalog spec 从 ssw-op/1.0 升到 1.x 时, 前端需同步更新 OperatorCatalogResp.specVersion 类型和 useOperatorCatalog 消费方.
  3. JNPF defHttp 改动: 大部分情况不影响 (业务路径稳定), 但若 defHttp.put 接受 formData 不一样, 注意 saveCanvas 入参是 object.

不修改的内容

  • 不动 JNPF 平台 defHttp: 用它即可
  • 不绕 axios: 复用 web 既有请求体系
  • 不从 localStorage 读 token: 依赖 JNPF 内部 cookie/store
  • 不写独立 Router: 复用 JNPF SPA 路由 (Task 13 编排页通过菜单挂载)
  • 不写独立 Axios: 复用 defHttp

已知约束 (2026-08-01)

  • web 仓 .gitignore 第 54 行: /apps/** 排除所有 apps/jnpf-web-apps-main/** 文件 (只保留 apps/ 和 apps/README.md).
  • 因此 sswflow API adapter (apps/jnpf-web-apps-main/src/api/ssw/sswflow/) 无法 commit 到 web 仓 (即使 vitest 12/12 PASS).
  • 实际部署: 走 pnpm workspace build 把 apps/jnpf-web-apps-main 编出 dist, 由 JNPF 应用容器托管.
  • sswflow M1 验收: vitest/typecheck/build 全 exit 0 即视为前端契约成立.

关联文件

  • web/apps/jnpf-web-apps-main/src/api/request.ts (defHttp 实现)
  • web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts (参考的 webapi 风格)
  • web/.gitignore (line 54 排除 /apps/**)
  • docs/sswflow/plan.md §12 (契约冻结)
  • docs/sswflow/design.md §5.3 + §10.3