openapi: 3.0.3
info:
  title: Intent-Driven Mid Platform Provider API
  version: 0.3.0
  x-contract-level: L2
paths:
  /mid/dialogue/respond:
    post:
      operationId: respondDialogue
      summary: 生成中台分段响应
      x-requirements:
        - AC-IDMP-01
        - AC-IDMP-02
        - AC-IDMP-03
        - AC-IDMP-04
        - AC-IDMP-05
        - AC-IDMP-06
        - AC-IDMP-07
        - AC-IDMP-11
        - AC-IDMP-12
        - AC-IDMP-15
        - AC-IDMP-16
        - AC-IDMP-17
        - AC-IDMP-18
        - AC-IDMP-19
        - AC-IDMP-20
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DialogueRequest'
      responses:
        '200':
          description: 成功生成分段响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DialogueResponse'
        '400':
          description: 请求参数错误
        '500':
          description: 服务内部错误

  /mid/messages/report:
    post:
      operationId: reportMessages
      summary: 上报会话消息与事件
      x-requirements:
        - AC-IDMP-08
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageReportRequest'
      responses:
        '202':
          description: 已接受异步处理
        '400':
          description: 请求参数错误

  /mid/sessions/{sessionId}/mode:
    post:
      operationId: switchSessionMode
      summary: 切换会话模式
      x-requirements:
        - AC-IDMP-09
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchModeRequest'
      responses:
        '200':
          description: 模式切换成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwitchModeResponse'
        '400':
          description: 请求参数错误

components:
  schemas:
    DialogueRequest:
      type: object
      required:
        - session_id
        - user_message
        - history
      properties:
        session_id:
          type: string
        user_id:
          type: string
          description: 用于记忆召回与更新的用户标识
        user_message:
          type: string
          minLength: 1
          maxLength: 2000
        history:
          type: array
          description: 仅允许已送达历史
          items:
            $ref: '#/components/schemas/HistoryMessage'
        interrupted_segments:
          type: array
          items:
            $ref: '#/components/schemas/InterruptedSegment'
        feature_flags:
          $ref: '#/components/schemas/FeatureFlags'

    FeatureFlags:
      type: object
      properties:
        agent_enabled:
          type: boolean
          description: 会话级 Agent 灰度开关
        rollback_to_legacy:
          type: boolean
          description: 强制回滚传统链路

    HistoryMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [user, assistant, human]
        content:
          type: string

    InterruptedSegment:
      type: object
      required:
        - segment_id
        - content
      properties:
        segment_id:
          type: string
        content:
          type: string

    DialogueResponse:
      type: object
      required:
        - segments
        - trace
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
        trace:
          $ref: '#/components/schemas/TraceInfo'

    Segment:
      type: object
      required:
        - segment_id
        - text
        - delay_after
      properties:
        segment_id:
          type: string
        text:
          type: string
        delay_after:
          type: integer
          minimum: 0

    TraceInfo:
      type: object
      required:
        - mode
      properties:
        mode:
          type: string
          enum: [agent, micro_flow, fixed, transfer]
        intent:
          type: string
        request_id:
          type: string
        generation_id:
          type: string
        guardrail_triggered:
          type: boolean
        fallback_reason_code:
          type: string
        react_iterations:
          type: integer
          minimum: 0
          maximum: 5
          description: ReAct 实际循环次数
        timeout_profile:
          $ref: '#/components/schemas/TimeoutProfile'
        metrics_snapshot:
          $ref: '#/components/schemas/MetricsSnapshot'
        high_risk_policy_set:
          type: array
          description: 当前启用的高风险最小场景集
          items:
            type: string
            enum: [refund, complaint_escalation, privacy_sensitive_promise, transfer]
        tools_used:
          type: array
          items:
            type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallTrace'

    TimeoutProfile:
      type: object
      properties:
        per_tool_timeout_ms:
          type: integer
          maximum: 2000
        end_to_end_timeout_ms:
          type: integer
          maximum: 8000

    MetricsSnapshot:
      type: object
      properties:
        task_completion_rate:
          type: number
          format: float
        slot_completion_rate:
          type: number
          format: float
        wrong_transfer_rate:
          type: number
          format: float
        no_recall_rate:
          type: number
          format: float
        avg_latency_ms:
          type: number
          format: float

    ToolCallTrace:
      type: object
      required:
        - tool_name
        - duration_ms
        - status
      properties:
        tool_name:
          type: string
        tool_type:
          type: string
          enum: [internal, mcp]
        registry_version:
          type: string
        auth_applied:
          type: boolean
        duration_ms:
          type: integer
          minimum: 0
        status:
          type: string
          enum: [ok, timeout, error, rejected]
        error_code:
          type: string
        args_digest:
          type: string
        result_digest:
          type: string

    MessageReportRequest:
      type: object
      required:
        - session_id
        - messages
      properties:
        session_id:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ReportedMessage'

    ReportedMessage:
      type: object
      required:
        - role
        - content
        - source
        - timestamp
      properties:
        role:
          type: string
          enum: [user, assistant, human, system]
        content:
          type: string
        source:
          type: string
          enum: [bot, human, channel]
        timestamp:
          type: string
          format: date-time
        segment_id:
          type: string

    SwitchModeRequest:
      type: object
      required:
        - mode
      properties:
        mode:
          type: string
          enum: [BOT_ACTIVE, HUMAN_ACTIVE]
        reason:
          type: string

    SwitchModeResponse:
      type: object
      required:
        - session_id
        - mode
      properties:
        session_id:
          type: string
        mode:
          type: string
          enum: [BOT_ACTIVE, HUMAN_ACTIVE]