openapi: 3.1.0
info:
  title: "AI Service Admin API"
  description: "AI 中台管理类接口契约（Provider: ai-service），支持 ai-service-admin 模块进行知识库、Prompt 及 RAG 调试管理。"
  version: "0.1.0"
  x-contract-level: L0 # 初始占位/可 Mock 级别
components:
  parameters:
    XTenantId:
      name: X-Tenant-Id
      in: header
      required: true
      schema:
        type: string
      description: "租户ID，用于物理隔离知识库与数据"
  responses:
    Unauthorized:
      description: "未认证（缺少或无效的认证信息）"
    Forbidden:
      description: "无权限（当前身份无权访问该资源）"

paths:
  /admin/kb/documents:
    post:
      summary: "上传/导入文档"
      operationId: "uploadDocument"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-01"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                kbId:
                  type: string
      responses:
        '202':
          description: "已接受上传请求，异步启动索引任务"
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                  status:
                    type: string
                    enum: [pending, processing]
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
  /admin/kb/index/jobs/{jobId}:
    get:
      summary: "查询索引任务详情"
      operationId: "getIndexJob"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-02"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "任务状态详情"
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                  status:
                    type: string
                    enum: [pending, processing, completed, failed]
                  progress:
                    type: integer
                    minimum: 0
                    maximum: 100
                  errorMsg:
                    type: string
                    nullable: true
  /admin/config/prompt-templates/{tplId}/publish:
    post:
      summary: "发布指定版本的 Prompt 模板"
      operationId: "publishPromptTemplate"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-03"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
      responses:
        '200':
          description: "发布成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
  /admin/rag/experiments/run:
    post:
      summary: "触发 RAG 调试实验"
      operationId: "runRagExperiment"
      tags:
        - RAG Lab
      x-requirements: ["AC-ASA-05"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                kbIds:
                  type: array
                  items:
                    type: string
                params:
                  type: object
                  description: "检索参数集"
      responses:
        '200':
          description: "实验结果"
          content:
            application/json:
              schema:
                type: object
                properties:
                  retrievalResults:
                    type: array
                    items:
                      type: object
                      properties:
                        content:
                          type: string
                        score:
                          type: number
                          format: float
                        source:
                          type: string
                  finalPrompt:
                    type: string
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
  /admin/sessions/{sessionId}:
    get:
      summary: "获取会话详情"
      operationId: "getSessionDetail"
      tags:
        - Session Monitoring
      x-requirements: ["AC-ASA-07"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "全链路会话详情"
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                  messages:
                    type: array
                    items:
                      type: object
                  trace:
                    type: object
                    description: "含检索、工具调用等追踪信息"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"