docs(sswflow): record useRunStream (SSE with auth, no token-in-URL)

- fetch + ReadableStream + Authorization header + X-Jnpf-AppCode header
- 鉴权通过 hook 注入 (getAppCode/getAccessToken), 不直读 JNPF store
- 7/7 vitest PASS: 暴露状态/补拉/去重排序/单连接/stop + 红线 #14 源码 grep
- 红线 #14: SSE URL 不含 token, 仅 Stream 路径

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-08-01 02:08:33 +08:00
1 parent 4ffee51165
commit eb519cf579
1 file changed
+79
+79
View File
@@ -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: <getRealJnpfAppEnCode()>
Authorization: Bearer <access_token> (有 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 契约)