实时通知与流式请求
本文说明 art-design-pro-ui 中两类流式能力：通知中心的实时推送，以及 AI 助手的流式回复。它适合在排查长连接、通知角标、AI 回复中断或代理缓冲问题时阅读。
两类流式能力
| 能力 | 前端入口 | 后端接口 |
|---|---|---|
| 通知实时推送 | src/store/modules/notification.ts | /api/v1/notifications/stream |
| AI 助手流式回复 | src/api/ai-assistant.ts、src/utils/ai-assistant-stream.ts | /api/v1/ai-assistant/chat/stream |
它们都基于 SSE，但接入方式不同：
- 通知流使用
EventSource，适合服务端主动推送轻量事件。 - AI 助手使用
fetch读取ReadableStream，适合带请求体、鉴权头和签名头的流式 POST 请求。
通知流链路
通知流不直接把 Access Token 放到 EventSource 请求头中，而是先申请短期访问令牌：
sequenceDiagram
participant UI as 前端通知 Store
participant API as 通知接口
participant SSE as 通知流
UI->>API: POST /notifications/stream-token
API-->>UI: 返回短期 streamToken
UI->>SSE: GET /notifications/stream?streamToken=...
SSE-->>UI: connected
SSE-->>UI: notification
UI->>API: GET /notifications/inbox 和 /notifications/stats前端主要逻辑在 src/store/modules/notification.ts：
| 逻辑 | 说明 |
|---|---|
fetchInbox | 拉取收件箱列表，并同步未读数 |
refreshUnreadCount | 刷新未读统计 |
connectStream | 获取短期令牌并创建 EventSource |
disconnectStream | 主动关闭通知流 |
scheduleReconnect | 通知流异常后按固定间隔重连 |
refreshBellData | 收到通知事件后刷新角标和弹窗提示 |
当前实现中，通知流最多连续重试 3 次，每次间隔 5 秒。超过次数后会停止自动重连，避免异常环境下持续请求。
AI 助手流式链路
AI 助手请求需要携带 JSON 请求体、登录态和接口签名，因此没有使用 EventSource，而是通过 fetch 读取后端返回的 SSE 数据块：
sequenceDiagram
participant Page as 聊天页面
participant API as streamAiAssistantReply
participant Parser as requestAiAssistantStream
participant Server as 后端 AI 接口
Page->>API: 提交 messages
API->>API: 读取 accessToken 并追加签名头
API->>Server: POST /ai-assistant/chat/stream
Server-->>Parser: meta
Server-->>Parser: delta
Server-->>Parser: done 或 error
Parser-->>Page: 分发回调requestAiAssistantStream 会解析下面几类事件：
| 事件 | 说明 |
|---|---|
meta | 当前供应商、模型等运行时信息 |
delta | 增量回复内容，用于逐段追加 |
done | 本轮回复结束，并返回完整内容 |
error | 流式回复失败 |
ping | 心跳事件，前端会忽略 |
与接口安全的关系
AI 助手流式请求会通过 applyApiSecurityHeaders 生成接口安全头，并使用 Authorization 传递 Access Token。通知流由于 EventSource 无法自定义请求头，改为使用短期 streamToken 建链。
这意味着排查时要分开看：
| 问题 | 优先检查 |
|---|---|
| 通知流 401 | stream-token 是否成功返回、streamToken 是否过期 |
| 通知流能连上但没有新通知 | 后端是否发布了通知事件，前端是否收到 notification 事件 |
| AI 接口签名失败 | applyApiSecurityHeaders 是否执行，Access Token 是否存在 |
| AI 回复中断 | 浏览器 Network 是否显示流被代理或服务端中断 |
代理配置注意事项
SSE 对代理缓冲比较敏感。如果生产环境使用 Nginx 或其他网关，需要确认流式接口没有被完整缓冲后再返回。现象通常是：
- 通知弹窗延迟很久才出现；
- AI 回复不是逐字或逐段出现，而是最后一次性显示；
- 浏览器 Network 中请求一直挂起但页面没有收到事件。
排查时优先检查响应头是否包含 Content-Type: text/event-stream，并确认代理没有对对应路径启用响应缓冲。
常见问题
通知角标不会更新
先检查 POST /api/v1/notifications/stream-token 是否成功，再检查 GET /api/v1/notifications/stream 是否建立连接。如果连接正常，继续看是否收到 notification 事件，以及 fetchInbox 是否请求成功。
通知流反复重连
检查 Access Token 是否临近过期、短期 streamToken 是否创建成功、代理是否主动关闭长连接。如果连续失败达到上限，前端会停止自动重连。
AI 助手一直没有回复
检查 POST /api/v1/ai-assistant/chat/stream 是否返回 text/event-stream，以及后端 AI 配置是否完整。若 Network 中接口立即失败，先看响应错误；若接口长时间挂起但没有 delta，再看上游 AI 服务和代理缓冲。
AI 回复到一半中断
优先检查浏览器是否主动取消请求、页面是否触发了 AbortController、后端是否返回 error 事件，以及代理是否限制了长连接时长。