diff --git a/docs/web-patches/sswflow-run-center.md b/docs/web-patches/sswflow-run-center.md new file mode 100644 index 0000000..a8cb565 --- /dev/null +++ b/docs/web-patches/sswflow-run-center.md @@ -0,0 +1,79 @@ +# sswflow Run Center — SSE 带鉴权 + 运行中心 composable + +> 记录日期: 2026-08-01 (sswflow M1 Task 14) +> 关联任务: design §5.3 + §10.3 + 红线 #14 (SSE 鉴权) + +## 背景 + +`useRunStream` 是 sswflow 专业前端运行中心的关键 composable. 必须满足: + +1. **红线 #14**: 禁止把 bearer token 拼到 SSE URL. 浏览器原生 EventSource 不支持自定义 header, 必须用 fetch streaming + Authorization header. +2. **断点续拉**: 连接前先调 `getEvents(lastSeq)` 补齐断开时漏的事件. +3. **去重排序**: 按 sortCode 单调递增, 重复 sortCode 不重复入列. +4. **终态关闭**: SUCCESS/FAILED/STOPPED 自动 stop. +5. **单连接**: start 之前自动 stop 旧连接. +6. **卸载关闭**: Vue `onScopeDispose` 触发自动 stop. + +## 源文件 → 镜像文件 + +| 维度 | 文件 | 备注 | +|------|------|------| +| SSE composable | `web/apps/jnpf-web-apps-main/src/views/ssw/sswflow/composables/useRunStream.ts` | fetch streaming + header 鉴权 | +| SSE 测试 | `web/apps/jnpf-web-apps-main/src/views/ssw/sswflow/__tests__/useRunStream.test.ts` | 7/7 vitest PASS (含红线 #14 源码 grep) | +| 鉴权来源 | JNPF access store (cookie 透传) + `getRealJnpfAppEnCode()` (header) | 通过 options 注入 hook, 不在 composable 内部读 store | + +## URL / Header 契约 + +``` +GET /api/ssw/FlowRun/{runId}/Stream +Headers: + Accept: text/event-stream + Cache-Control: no-cache + X-Jnpf-AppCode: + Authorization: Bearer (有 token 时) + credentials: include (cookie 透传, JNPF 内部 cookie) +``` + +## 解析契约 + +``` +SSE block 形如: + data: {"id":"e1","sortCode":3,"level":"INFO","message":"...",...} + +按 \n\n 切块; 每块取 data: 行, JSON.parse 后入列. +解析失败的事件忽略 (不让单条坏事件阻断 stream). +``` + +## 验证 + +```bash +# 7/7 vitest PASS +pnpm exec vitest run apps/jnpf-web-apps-main/src/views/ssw/sswflow + +# 红线 #14 源码扫描: useRunStream.ts 不含 token 拼 URL 模式 +rg -n 'token=|access_token=' apps/jnpf-web-apps-main/src/views/ssw/sswflow/composables/useRunStream.ts +# → 期望 0 命中 +``` + +## 升级重放 + +JNPF / Vue / 浏览器 fetch API 升级时: + +1. **fetch ReadableStream 兼容性**: 现代浏览器 OK; IE 不支持 (SSW 不支持 IE). +2. **AbortController**: 现代浏览器 OK; polyfill 在 ssw-common 不提供, 若需兼容老浏览器需评估. +3. **JNPF 内部 cookie/access store 改名**: 用 hook 注入 (getAppCode / getAccessToken), 不直读, 解耦. +4. **SSE 协议变更**: 后端流式格式若加 event:/id:/retry: 等字段, 解析器需扩展 (v1 仅 data:). + +## 不修改的内容 + +- 不绕 axios (Task 12 同) +- 不写独立 store +- 不引入第三方 SSE 客户端 (eventsource-polyfill 等), 全部原生 fetch + ReadableStream +- 不读 localStorage token (依赖 JNPF cookie/store) + +## 关联文件 + +- `web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/run.ts` (run.ts 提供 getEvents / SSE URL prefix) +- `web/apps/jnpf-web-apps-main/src/api/ssw/sswflow/types.ts` (RunEventEntity) +- `docs/sswflow/design.md` §5.3 (事件和 SSE) + §10.3 (专业前端浏览器链路) +- `dacli/docs/web-patches/sswflow-api-client.md` (上游 API 契约) \ No newline at end of file