openapi: 3.0.3
info:
  title: AI Service API
  description: |
    Python AI 服务接口契约。
    
    本文件定义主框架对 AI 服务的接口需求（Consumer-First）。
    由主框架作为调用方，Python AI 服务作为提供方实现。
  version: 1.0.0
  x-contract-level: L0
  x-consumer: "java-main-framework"
  x-provider: "python-ai-service"

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

paths:
  /ai/chat:
    post:
      operationId: generateReply
      summary: 生成 AI 回复
      description: |
        根据用户消息和会话历史生成 AI 回复。
        
        覆盖验收标准：
        - 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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            example:
              sessionId: "kf_001_wx123456_1708765432000"
              currentMessage: "我想了解产品价格"
              channelType: "wechat"
      responses:
        '200':
          description: 成功生成回复
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
              example:
                reply: "您好，我们的产品价格根据套餐不同有所差异。"
                confidence: 0.92
                shouldTransfer: false
        '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