From 4ffee511656131f28ab305a0f70ed43d03a17db9 Mon Sep 17 00:00:00 2001 From: ssw Date: Sat, 1 Aug 2026 02:05:18 +0800 Subject: [PATCH] docs(sswflow): record web API client adapter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - types/flow/run/operator.ts: webapps/jnpf-web-apps-main/src/api/ssw/sswflow/* (12/12 vitest PASS) - 算子目录端点不走 defHttp, 走原生 fetch (后端原始 JSON) - 红线 #14 SSE 鉴权: useRunStream 用 fetch + Authorization header, 不拼 URL token - 已知约束: apps/** gitignore, web 仓不跟踪; vitest/typecheck/build 即视为前端契约成立 Co-Authored-By: Claude --- docs/web-patches/sswflow-api-client.md | 91 ++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/web-patches/sswflow-api-client.md diff --git a/docs/web-patches/sswflow-api-client.md b/docs/web-patches/sswflow-api-client.md new file mode 100644 index 0000000..03a3072 --- /dev/null +++ b/docs/web-patches/sswflow-api-client.md @@ -0,0 +1,91 @@ +# 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 ', 'X-Jnpf-AppCode': '' } })` +- 解析 `ReadableStream` SSE 事件 +- 终态 (SUCCESS/FAILED/STOPPED) 关闭 stream + +不暴露任何拼接 `?token=...` 的 URL. + +## 验证命令 + +```bash +# 单元测试 (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 " 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 \ No newline at end of file