本仓 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,未来以本仓历史为主
4.7 KiB
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>' } })- 解析
ReadableStreamSSE 事件 - 终态 (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 升级时:
- 后端 controller 路径变化: 路径前缀
/api/ssw/*是 SSW 平台自有契约, 不应跟 JNPF 通用前缀混淆. 升级时优先观察boot/ssw-common/SSWController基类是否变化. - Operator Catalog spec 版本变更: 后端 catalog spec 从
ssw-op/1.0升到1.x时, 前端需同步更新OperatorCatalogResp.specVersion类型和useOperatorCatalog消费方. - 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