openapi: 3.0.3
info:
  title: 元数据职责分层模块 - 外部依赖
  description: |
    本模块依赖的外部 API 契约，用于生成 Mock/SDK。
    
    ## 依赖说明
    - metadata-governance: 元数据字段定义基础能力
    - intent-driven-mid-platform: 中台运行时工具链
  version: 0.1.0
  x-contract-level: L1
  contact:
    name: AI Robot Core Team

servers:
  - url: /api
    description: API Server

tags:
  - name: MetadataGovernance
    description: 元数据治理模块依赖
  - name: MidPlatform
    description: 中台模块依赖

paths:
  /admin/metadata-schemas:
    get:
      summary: 获取元数据字段定义列表（依赖）
      description: 依赖 metadata-governance 模块的元数据字段列表查询能力
      operationId: depsListMetadataSchemas
      tags:
        - MetadataGovernance
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - draft
              - active
              - deprecated
        - name: scope
          in: query
          schema:
            type: string
            enum:
              - kb_document
              - intent_rule
              - script_flow
              - prompt_template
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回字段定义列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetadataFieldDefinition'

  /admin/kb/documents:
    get:
      summary: 获取 KB 文档列表（依赖）
      description: 依赖 KB 文档管理能力，用于验证字段使用情况
      operationId: depsListKbDocuments
      tags:
        - MetadataGovernance
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: kb_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回文档列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KbDocument'

  /mid/dialogue/respond:
    post:
      summary: 中台对话响应（依赖）
      description: 依赖中台对话响应能力，用于工具协同改造验证
      operationId: depsRespondDialogue
      tags:
        - MidPlatform
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DialogueRequest'
      responses:
        '200':
          description: 成功返回对话响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DialogueResponse'

components:
  schemas:
    MetadataFieldStatus:
      type: string
      enum:
        - draft
        - active
        - deprecated

    MetadataScope:
      type: string
      enum:
        - kb_document
        - intent_rule
        - script_flow
        - prompt_template

    MetadataFieldType:
      type: string
      enum:
        - string
        - number
        - boolean
        - enum
        - array_enum

    MetadataFieldDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        field_key:
          type: string
        label:
          type: string
        type:
          $ref: '#/components/schemas/MetadataFieldType'
        required:
          type: boolean
        options:
          type: array
          items:
            type: string
        default_value:
          type: object
        scope:
          type: array
          items:
            $ref: '#/components/schemas/MetadataScope'
        is_filterable:
          type: boolean
        is_rank_feature:
          type: boolean
        status:
          $ref: '#/components/schemas/MetadataFieldStatus'
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    KbDocument:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        kb_id:
          type: string
          format: uuid
        title:
          type: string
        content:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    DialogueRequest:
      type: object
      required:
        - tenant_id
        - user_id
        - session_id
        - user_message
      properties:
        tenant_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        user_message:
          type: string
        context:
          type: object
          additionalProperties: true
          description: 会话上下文，包含槽位信息

    DialogueResponse:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        request_id:
          type: string
          format: uuid
        segments:
          type: array
          items:
            type: object
            properties:
              segment_id:
                type: string
              text:
                type: string
              delay_after:
                type: integer
        trace:
          type: object
          properties:
            mode:
              type: string
              enum:
                - agent
                - micro_flow
                - fixed
                - transfer
            intent:
              type: string
            tool_calls:
              type: array
              items:
                type: object
            fallback_reason_code:
              type: string