ai-robot-core/spec/ai-service/openapi.admin.yaml

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: "无权限（当前身份无权访问该资源）"
  schemas:
    DocumentInfo:
      type: object
      properties:
        docId:
          type: string
          description: "文档ID"
        kbId:
          type: string
          description: "知识库ID"
        fileName:
          type: string
          description: "文件名"
        status:
          type: string
          description: "文档状态"
          enum: [pending, processing, completed, failed]
        createdAt:
          type: string
          format: date-time
          description: "创建时间"
        updatedAt:
          type: string
          format: date-time
          description: "更新时间"
    SessionInfo:
      type: object
      properties:
        sessionId:
          type: string
          description: "会话ID"
        status:
          type: string
          description: "会话状态"
          enum: [active, closed, expired]
        startTime:
          type: string
          format: date-time
          description: "开始时间"
        endTime:
          type: string
          format: date-time
          description: "结束时间"
        messageCount:
          type: integer
          description: "消息数量"
    PageInfo:
      type: object
      properties:
        page:
          type: integer
          description: "当前页码"
        pageSize:
          type: integer
          description: "每页大小"
        total:
          type: integer
          description: "总记录数"
        totalPages:
          type: integer
          description: "总页数"

paths:
  /admin/kb/documents:
    get:
      summary: "查询文档列表"
      operationId: "listDocuments"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-08"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: kbId
          in: query
          required: false
          schema:
            type: string
          description: "知识库ID"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, processing, completed, failed]
          description: "文档状态"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: "页码"
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: "每页大小"
      responses:
        '200':
          description: "文档列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DocumentInfo"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    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:
    get:
      summary: "查询会话列表"
      operationId: "listSessions"
      tags:
        - Session Monitoring
      x-requirements: ["AC-ASA-09"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [active, closed, expired]
          description: "会话状态"
        - name: startTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: "开始时间"
        - name: endTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: "结束时间"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: "页码"
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: "每页大小"
      responses:
        '200':
          description: "会话列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SessionInfo"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '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"