feat(api-contracts): 新增 SSE 事件流端点和 Schema 形式化
- ai/openapi.yaml: 将 SSE stream 响应从描述文本替换为正式 Schema ($ref SSEChunkEvent 等) - ai/openapi.yaml: 新增 SSEChunkEvent/SSEQualityCheckEvent/SSEDoneEvent/SSEErrorEvent Schema - events/openapi.yaml: 新增统一事件流端点 GET /app-api/muse/events (支持 lastEventId 重连) - events/openapi.yaml: 定义 SSE 事件类型 Schema 和 SSENotificationEvent (跨模块通知)
This commit is contained in:
zizi
parent
e03f9f3954
commit
3114f661c4
@ -1222,13 +1222,11 @@ paths:
|
||||
content:
|
||||
text/event-stream:
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
事件类型:
|
||||
- chunk: { "content": "文本片段", "sequenceNo": 1 }
|
||||
- quality_check: { "dimension": "fluency", "score": 0.92, "passed": true }
|
||||
- done: { "taskId": "uuid", "suggestionId": "uuid" }
|
||||
- error: { "code": "...", "message": "..." }
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/SSEChunkEvent'
|
||||
- $ref: '#/components/schemas/SSEQualityCheckEvent'
|
||||
- $ref: '#/components/schemas/SSEDoneEvent'
|
||||
- $ref: '#/components/schemas/SSEErrorEvent'
|
||||
|
||||
# ---------- 候选(Suggestion)管理 ----------
|
||||
'400':
|
||||
@ -2868,3 +2866,101 @@ components:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 可选，关联的异步任务 ID
|
||||
|
||||
# ==================================================================
|
||||
# SSE 事件流 Schema（Fix 7: 将 SSE 流形式化为可引用 Schema）
|
||||
# ==================================================================
|
||||
|
||||
SSEChunkEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [chunk]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [content, sequenceNo]
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
description: AI 生成的文本片段
|
||||
sequenceNo:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: 片段序号，从 1 递增
|
||||
|
||||
SSEQualityCheckEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [quality_check]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [dimension, score, passed]
|
||||
properties:
|
||||
dimension:
|
||||
type: string
|
||||
description: 质量维度名称（如 fluency, coherence, safety）
|
||||
score:
|
||||
type: number
|
||||
format: double
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
description: 质量评分（0-1）
|
||||
passed:
|
||||
type: boolean
|
||||
description: 该维度是否通过阈值
|
||||
|
||||
SSEDoneEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [done]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [taskId, suggestionId]
|
||||
properties:
|
||||
taskId:
|
||||
type: integer
|
||||
format: int64
|
||||
description: AI 任务 ID
|
||||
suggestionId:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 生成的候选 ID
|
||||
summary:
|
||||
type: string
|
||||
description: 任务完成摘要
|
||||
|
||||
SSEErrorEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [error]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: 错误码，格式 MUSE-AI-XXX-XXXX
|
||||
message:
|
||||
type: string
|
||||
description: 人类可读的错误描述
|
||||
detail:
|
||||
type: string
|
||||
description: 详细错误信息（仅开发环境返回）
|
||||
retryable:
|
||||
type: boolean
|
||||
description: 是否可重试
|
||||
|
||||
192
docs/api-contracts/events/openapi.yaml
Normal file
192
docs/api-contracts/events/openapi.yaml
Normal file
@ -0,0 +1,192 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Muse Events SSE API
|
||||
version: 1.0.0
|
||||
license:
|
||||
name: Proprietary
|
||||
description: |
|
||||
Muse 统一事件流 SSE 端点，供前端建立单一 SSE 连接以接收跨模块实时事件。
|
||||
AI 模块有独立的 /app-api/muse/ai/tasks/{taskId}/stream 端点用于任务级 AI 流式输出。
|
||||
|
||||
servers:
|
||||
- url: /
|
||||
description: 同源 API 网关
|
||||
|
||||
paths:
|
||||
/app-api/muse/events:
|
||||
get:
|
||||
tags: [Events]
|
||||
summary: 统一事件流 SSE
|
||||
description: |
|
||||
建立 SSE 长连接接收跨模块实时事件。客户端通过 lastEventId 支持断线重连。
|
||||
事件类型包括 AI chunk、质量检测、任务完成、系统通知等。
|
||||
operationId: streamEvents
|
||||
security:
|
||||
- appBearerAuth: []
|
||||
parameters:
|
||||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||||
- name: lastEventId
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
SSE Last-Event-ID，用于断线重连时指定从哪个事件之后恢复。
|
||||
不传则从当前时刻开始推送。
|
||||
responses:
|
||||
'200':
|
||||
description: SSE 事件流
|
||||
content:
|
||||
text/event-stream:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/SSEChunkEvent'
|
||||
- $ref: '#/components/schemas/SSEQualityCheckEvent'
|
||||
- $ref: '#/components/schemas/SSEDoneEvent'
|
||||
- $ref: '#/components/schemas/SSEErrorEvent'
|
||||
- $ref: '#/components/schemas/SSENotificationEvent'
|
||||
'401':
|
||||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
appBearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: 用户端认证 scheme，仅用于 /app-api/** 接口，app-api token 与 admin-api token 不互通。
|
||||
|
||||
schemas:
|
||||
# SSE 事件类型 — 与 ai/openapi.yaml 中的定义保持一致
|
||||
|
||||
SSEChunkEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [chunk]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [content, sequenceNo]
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
description: AI 生成的文本片段
|
||||
sequenceNo:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: 片段序号，从 1 递增
|
||||
|
||||
SSEQualityCheckEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [quality_check]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [dimension, score, passed]
|
||||
properties:
|
||||
dimension:
|
||||
type: string
|
||||
description: 质量维度名称
|
||||
score:
|
||||
type: number
|
||||
format: double
|
||||
minimum: 0
|
||||
maximum: 1
|
||||
description: 质量评分（0-1）
|
||||
passed:
|
||||
type: boolean
|
||||
description: 该维度是否通过阈值
|
||||
|
||||
SSEDoneEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [done]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [taskId, suggestionId]
|
||||
properties:
|
||||
taskId:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 任务 ID
|
||||
suggestionId:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 相关候选 ID（如有）
|
||||
summary:
|
||||
type: string
|
||||
description: 任务完成摘要
|
||||
|
||||
SSEErrorEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [error]
|
||||
description: SSE 事件类型
|
||||
data:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: 错误码
|
||||
message:
|
||||
type: string
|
||||
description: 人类可读的错误描述
|
||||
detail:
|
||||
type: string
|
||||
description: 详细错误信息（仅开发环境返回）
|
||||
retryable:
|
||||
type: boolean
|
||||
description: 是否可重试
|
||||
|
||||
SSENotificationEvent:
|
||||
type: object
|
||||
required: [event, data]
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
enum: [notification]
|
||||
description: 系统通知事件
|
||||
data:
|
||||
type: object
|
||||
required: [type, message]
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [source_status_change, knowledge_projection_done, governance_action, quota_alert]
|
||||
description: 通知类型
|
||||
message:
|
||||
type: string
|
||||
description: 通知消息
|
||||
resourceRef:
|
||||
type: object
|
||||
properties:
|
||||
resourceType:
|
||||
type: string
|
||||
description: 关联资源类型
|
||||
resourceId:
|
||||
type: integer
|
||||
format: int64
|
||||
description: 关联资源 ID
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 事件发生时间
|
||||
|
||||
tags:
|
||||
- name: Events
|
||||
description: 统一事件流 SSE 端点
|
||||
Loading…
x
Reference in New Issue
Block a user