docs(sswflow): record web API client adapter

- 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 <[email protected]>
This commit is contained in:
sswandClaude committed 2026-08-01 02:05:18 +08:00
1 parent a4fec463ca
commit 4ffee51165
1 file changed
+91
+91
View File
@@ -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 <token>', 'X-Jnpf-AppCode': '<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 <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