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:
1 parent
4ffee51165
commit
eb519cf579
1 file changed
+79
@@ -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 契约)
|
||||
Reference in new issue
Block a user