实时通知与 AI 助手

本文说明 art-design-pro-server 中两类长连接能力：通知实时推送和 AI 助手流式回复。它适合在配置 AI 服务、排查 SSE 连接、确认通知推送链路或调整代理策略时阅读。

能力入口

能力	主要文件	说明
通知管理接口	src/modules/notifications/notifications.controller.ts	通知增删改查、发布、撤回、收件箱、已读状态
通知实时推送	src/modules/notifications/notifications.realtime.service.ts	维护在线 SSE 连接并向指定用户推送事件
通知业务逻辑	src/modules/notifications/notifications.service.ts	收件箱、未读数、发布规则和短期 streamToken
AI 流式接口	src/modules/ai-assistant/ai-assistant.controller.ts	建立 SSE 响应、心跳、请求方断开处理
AI 服务适配	src/modules/ai-assistant/ai-assistant.service.ts	读取 AI 配置、请求上游、转发流式片段

通知推送链路

通知流使用短期访问令牌建链，避免直接把用户 Access Token 放在查询参数里：

sequenceDiagram
  participant UI as 前端
  participant Auth as 通知接口
  participant Stream as 通知 SSE
  participant Service as 通知服务

  UI->>Auth: POST /api/v1/notifications/stream-token
  Auth-->>UI: streamToken
  UI->>Stream: GET /api/v1/notifications/stream?streamToken=...
  Stream->>Service: addClient(userId, response)
  Service-->>UI: connected / ping / notification

关键点：

• stream-token 需要登录态和通知收件箱列表权限。
• stream 接口会校验短期 streamToken，校验失败返回 401。
• 建链成功后，服务端会写入 connected 事件。
• 服务端会定期写入 ping 心跳，避免中间代理过早关闭连接。
• 请求关闭时会移除当前用户的 SSE 连接并结束响应。

通知相关配置

变量	说明
NOTIFICATION_STREAM_TOKEN_SECRET	通知流短期令牌签名密钥
NOTIFICATION_STREAM_TOKEN_EXPIRES_IN	通知流短期令牌有效期，默认示例为 60s

生产环境应配置独立的 NOTIFICATION_STREAM_TOKEN_SECRET。如果为空或长期沿用示例值，通知流令牌的安全性会降低。

AI 助手流式链路

AI 助手接口使用后端作为中转层。前端只请求本系统接口，后端再请求上游 OpenAI 兼容接口，并把上游流式片段转换为本系统自己的 SSE 事件：

flowchart TD
  A["POST /api/v1/ai-assistant/chat/stream"] --> B["JwtGuard 校验登录态"]
  B --> C["AiAssistantService 读取 AI 配置"]
  C --> D["请求上游 chat completions stream"]
  D --> E["解析上游 SSE 数据块"]
  E --> F["输出 meta / delta / done / error"]

当前流式事件约定：

事件	说明
meta	输出当前供应商、展示名和模型
delta	输出增量文本
done	输出完整文本和结束原因
error	输出错误信息
ping	心跳事件

当浏览器端断开连接时，控制器会中止上游请求，避免继续占用上游连接资源。

AI 相关配置

变量	说明
AI_PROVIDER	供应商标识，默认示例为 deepseek
AI_PROVIDER_LABEL	供应商展示名称
AI_BASE_URL	上游服务基础地址
AI_CHAT_ENDPOINT	上游聊天接口路径，默认示例为 /chat/completions
AI_API_KEY	上游服务访问密钥
AI_MODEL	使用的模型名称
AI_SYSTEM_PROMPT	系统提示词
AI_MAX_CONTEXT_MESSAGES	最多保留的上下文消息数
AI_REQUEST_TIMEOUT_MS	上游请求超时时间

如果 AI_API_KEY、AI_BASE_URL 或 AI_MODEL 不完整，后端会返回 AI 服务配置不完整相关错误。排查时不要把上游密钥写入前端环境变量。

与网关和代理的关系

通知流和 AI 流式回复都依赖 text/event-stream。经过 Nginx、负载均衡或 API 网关时，需要确认代理没有缓冲对应响应。

常见现象：

现象	可能原因
AI 回复最后一次性显示	代理缓冲了 SSE 响应
通知流经常断开	网关长连接超时过短
浏览器显示 200 但页面收不到事件	响应头或代理转发策略不正确
本地正常、生产异常	生产网关对流式路径做了不同处理

优先确认响应头包含 Content-Type: text/event-stream; charset=utf-8，并检查代理是否对 /api/v1/notifications/stream 和 /api/v1/ai-assistant/chat/stream 做了特殊处理。

排查顺序

通知流异常

1. 检查 POST /api/v1/notifications/stream-token 是否返回短期令牌。
2. 检查 GET /api/v1/notifications/stream 是否返回 connected。
3. 检查发布通知后是否触发 notification 事件。
4. 检查前端是否重新请求收件箱和未读统计。
5. 检查代理是否关闭或缓冲长连接。

AI 回复异常

1. 检查 AI 环境变量是否完整。
2. 检查后端是否能访问上游 AI_BASE_URL。
3. 检查响应事件是否包含 meta、delta、done 或 error。
4. 检查上游服务是否返回 OpenAI 兼容流式响应。
5. 检查代理是否缓冲或截断 SSE。

相关阅读

• 环境变量
• 认证与接口安全
• 前端实时通知与流式请求