openapi: 3.0.3
info:
  title: AI Service API
  description: |
    Python AI 服务对外提供的接口契约（Provider）。

    目标：100% 覆盖并对齐 Java 端 Consumer-First 依赖契约 `java/openapi.deps.yaml`。
    - 路径与方法必须一致
    - non-streaming JSON 响应 schema 必须一致（reply/confidence/shouldTransfer 等）

    额外扩展：支持 SSE 流式输出（Accept: text/event-stream）。
  version: 1.0.0
  x-contract-level: L0
  x-provider: "python-ai-service"
  x-consumer: "java-main-framework"

servers:
  - url: http://ai-service:8080
    description: AI 服务地址

tags:
  - name: AI Chat
    description: 对话生成
  - name: Health
    description: 健康检查

paths:
  /ai/chat:
    post:
      operationId: generateReply
      summary: 生成 AI 回复
      description: |
        根据用户消息和会话历史生成 AI 回复。

        non-streaming：返回 application/json（ChatResponse）。
        streaming：当请求头包含 `Accept: text/event-stream` 时，以 SSE 推送事件流。

        覆盖验收标准（来自 Java 侧契约描述）：
        - AC-MCA-04: 主框架通过 HTTP POST 调用 AI 服务
        - AC-MCA-05: 响应包含 reply、confidence、shouldTransfer 字段
        - AC-MCA-06: AI 服务不可用时的降级处理（主框架侧实现）
        - AC-MCA-07: 超时处理（主框架侧实现）
      tags:
        - AI Chat
      x-requirements:
        - AC-MCA-04
        - AC-MCA-04-REQ
        - AC-MCA-04-OPT
        - AC-MCA-05
        - AC-MCA-06
        - AC-MCA-07
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          description: 租户ID（多租户隔离必填，便于网关/拦截器统一处理）
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          description: |
            内容协商。
            - 设置为 text/event-stream 时返回 SSE 事件流
            - 其他情况返回 application/json
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            example:
              sessionId: "kf_001_wx123456_1708765432000"
              currentMessage: "我想了解产品价格"
              channelType: "wechat"
              metadata:
                channelUserId: "wx123456"
                extra: "..."
      responses:
        '200':
          description: |
            成功生成回复。

            注意：
            - non-streaming：响应 Content-Type 为 application/json
            - streaming：当请求头 Accept: text/event-stream 时，服务端可返回 text/event-stream（见下方 200 的第二种 content 描述）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
              example:
                reply: "您好，我们的产品价格根据套餐不同有所差异。"
                confidence: 0.92
                shouldTransfer: false
            text/event-stream:
              schema:
                type: string
                description: |
                  SSE 事件流（按行文本）。事件模型：

                  1) event: message
                     - data: {"delta": "..."}
                     - 返回时机：模型生成过程中多次发送，用于增量渲染。

                  2) event: final
                     - data: ChatResponse（完整结构化结果，字段至少包含 reply/confidence/shouldTransfer）
                     - 返回时机：生成结束时发送一次，随后关闭连接。

                  3) event: error
                     - data: ErrorResponse（结构化错误，至少 code/message，可含 details）
                     - 返回时机：发生错误时发送一次，随后关闭连接。

                  示例（片段）：
                  event: message\n
data: {"delta":"您好，"}\n

                  event: final\n
data: {"reply":"...","confidence":0.9,"shouldTransfer":false}\n
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /ai/health:
    get:
      operationId: healthCheck
      summary: 健康检查
      description: 检查 AI 服务是否正常运行
      tags:
        - Health
      responses:
        '200':
          description: 服务正常
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '503':
          description: 服务不健康

components:
  schemas:
    ChatRequest:
      type: object
      required:
        - sessionId
        - currentMessage
        - channelType
      properties:
        sessionId:
          type: string
          description: 会话ID（AC-MCA-04-REQ 必填）
        currentMessage:
          type: string
          description: 当前用户消息（AC-MCA-04-REQ 必填）
        channelType:
          type: string
          description: 渠道类型（AC-MCA-04-REQ 必填）
          enum:
            - wechat
            - douyin
            - jd
        history:
          type: array
          description: 历史消息列表（AC-MCA-04-OPT 可选）
          items:
            $ref: '#/components/schemas/ChatMessage'
        metadata:
          type: object
          description: 扩展元数据（AC-MCA-04-OPT 可选）
          additionalProperties: true

    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          type: string

    ChatResponse:
      type: object
      required:
        - reply
        - confidence
        - shouldTransfer
      properties:
        reply:
          type: string
          description: AI 回复内容（AC-MCA-05 必填）
        confidence:
          type: number
          format: double
          description: 置信度评分 0.0-1.0（AC-MCA-05 必填）
        shouldTransfer:
          type: boolean
          description: 是否建议转人工（AC-MCA-05 必填）
        transferReason:
          type: string
          description: 转人工原因（可选）
        metadata:
          type: object
          description: 响应元数据（可选）
          additionalProperties: true

    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误代码
        message:
          type: string
          description: 错误消息
        details:
          type: array
          description: 详细错误信息（可选）
          items:
            type: object
            additionalProperties: true