实时通知与流式请求

本文适用于 Java / Nest.js 配套的 art-design-pro-x-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，携带 JSON 请求体与 Bearer 登录态，按后端配置决定是否附加签名头。

通知流链路

通知流不直接把 Access Token 放到 EventSource 请求头中，而是先申请短期访问令牌：

mermaid

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 请求体和登录态，因此通过 fetch 读取后端返回的 SSE 数据块。请求签名按后端安全配置决定，不是使用流式 POST 的必备条件：

mermaid

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 助手流式请求通过 Authorization 传递 Access Token，并调用 applyApiSecurityHeaders 根据 /api/v1/crypto/security-config 决定是否生成签名头。Java 当前返回 signatureRequired: false，因此不附加请求签名；Nest.js 按其公开配置处理。通知流由于 EventSource 无法自定义请求头，使用短期 streamToken 建链。

这意味着排查时要分开看：

问题	优先检查
通知流 401	`stream-token` 是否成功返回、`streamToken` 是否过期
通知流能连上但没有新通知	后端是否发布了通知事件，前端是否收到 `notification` 事件
后端要求签名但校验失败	先核对安全配置，再检查 `applyApiSecurityHeaders`、登录态与时钟
AI 回复中断	浏览器 Network 是否显示流被代理或服务端中断

Java 版 AI 助手范围

Java 沿用上述流式接口与事件名称。需要在后端外置 YAML 中配置模型服务，不配置密钥时 AI 接口返回 503，其他业务仍可启动。AI 助手只提供对话，不执行业务操作、不读取业务表，也不持久化对话历史；它与 Java 版不包含的 AI 代码生成器是不同功能。

Java 的模型参数见 Java 实时通知与 AI 助手，不要照搬 Nest.js 的环境变量配置方式。

代理配置注意事项

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 事件，以及代理是否限制了长连接时长。

实时通知与流式请求 ​

两类流式能力 ​

通知流链路 ​

AI 助手流式链路 ​

与接口安全的关系 ​

Java 版 AI 助手范围 ​

代理配置注意事项 ​

常见问题 ​

通知角标不会更新 ​

通知流反复重连 ​

AI 助手一直没有回复 ​

AI 回复到一半中断 ​

相关阅读 ​