openapi: 3.1.0
info:
  title: "AI Service Admin API"
  description: "AI 中台管理类接口契约（Provider: ai-service），支持 ai-service-admin 模块进行知识库、Prompt 及 RAG 调试管理。"
  version: "0.7.0"
  x-contract-level: L1
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: "总页数"
    # v0.6.0 新增 schemas
    KnowledgeBaseInfo:
      type: object
      properties:
        id:
          type: string
          description: "知识库ID"
        name:
          type: string
          description: "知识库名称"
        kbType:
          type: string
          description: "知识库类型"
          enum: [product, faq, script, policy, general]
        description:
          type: string
          description: "描述"
        priority:
          type: integer
          description: "优先级权重"
        isEnabled:
          type: boolean
          description: "是否启用"
        docCount:
          type: integer
          description: "文档数量"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    KnowledgeBaseCreate:
      type: object
      required: [name, kbType]
      properties:
        name:
          type: string
        kbType:
          type: string
          enum: [product, faq, script, policy, general]
        description:
          type: string
        priority:
          type: integer
          default: 0
    KnowledgeBaseUpdate:
      type: object
      properties:
        name:
          type: string
        kbType:
          type: string
          enum: [product, faq, script, policy, general]
        description:
          type: string
        priority:
          type: integer
        isEnabled:
          type: boolean
    PromptTemplateInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: "模板名称"
        scene:
          type: string
          description: "场景标签"
        description:
          type: string
        isDefault:
          type: boolean
        publishedVersion:
          type: integer
          description: "当前发布版本号"
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PromptTemplateCreate:
      type: object
      required: [name, scene, systemInstruction]
      properties:
        name:
          type: string
        scene:
          type: string
        description:
          type: string
        systemInstruction:
          type: string
          description: "系统指令内容，支持 {{variable}} 占位符"
        variables:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              default:
                type: string
              description:
                type: string
    PromptTemplateDetail:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        scene:
          type: string
        description:
          type: string
        currentVersion:
          type: object
          properties:
            version:
              type: integer
            status:
              type: string
              enum: [draft, published, archived]
            systemInstruction:
              type: string
            variables:
              type: array
              items:
                type: object
        versions:
          type: array
          items:
            type: object
            properties:
              version:
                type: integer
              status:
                type: string
                enum: [draft, published, archived]
              createdAt:
                type: string
                format: date-time
    IntentRuleInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: "意图名称"
        keywords:
          type: array
          items:
            type: string
        patterns:
          type: array
          items:
            type: string
        priority:
          type: integer
        responseType:
          type: string
          enum: [flow, rag, fixed, transfer]
        targetKbIds:
          type: array
          items:
            type: string
          nullable: true
        flowId:
          type: string
          nullable: true
        fixedReply:
          type: string
          nullable: true
        transferMessage:
          type: string
          nullable: true
        isEnabled:
          type: boolean
        hitCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    IntentRuleCreate:
      type: object
      required: [name, responseType]
      properties:
        name:
          type: string
        keywords:
          type: array
          items:
            type: string
        patterns:
          type: array
          items:
            type: string
        priority:
          type: integer
          default: 0
        responseType:
          type: string
          enum: [flow, rag, fixed, transfer]
        targetKbIds:
          type: array
          items:
            type: string
        flowId:
          type: string
        fixedReply:
          type: string
        transferMessage:
          type: string
    ScriptFlowInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        stepCount:
          type: integer
        isEnabled:
          type: boolean
        linkedRuleCount:
          type: integer
          description: "关联意图规则数"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ScriptFlowCreate:
      type: object
      required: [name, steps]
      properties:
        name:
          type: string
        description:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/FlowStep"
    FlowStep:
      type: object
      required: [stepNo, content]
      properties:
        stepNo:
          type: integer
        content:
          type: string
          description: "话术内容"
        waitInput:
          type: boolean
          default: true
        timeoutSeconds:
          type: integer
          default: 120
        timeoutAction:
          type: string
          enum: [repeat, skip, transfer]
          default: repeat
        nextConditions:
          type: array
          items:
            type: object
            properties:
              keywords:
                type: array
                items:
                  type: string
              pattern:
                type: string
              gotoStep:
                type: integer
        defaultNext:
          type: integer
          nullable: true
    ForbiddenWordInfo:
      type: object
      properties:
        id:
          type: string
        word:
          type: string
        category:
          type: string
          enum: [competitor, sensitive, political, custom]
        strategy:
          type: string
          enum: [mask, replace, block]
        replacement:
          type: string
          nullable: true
        fallbackReply:
          type: string
          nullable: true
        isEnabled:
          type: boolean
        hitCount:
          type: integer
        createdAt:
          type: string
          format: date-time
    ForbiddenWordCreate:
      type: object
      required: [word, category, strategy]
      properties:
        word:
          type: string
        category:
          type: string
          enum: [competitor, sensitive, political, custom]
        strategy:
          type: string
          enum: [mask, replace, block]
        replacement:
          type: string
        fallbackReply:
          type: string
    BehaviorRuleInfo:
      type: object
      properties:
        id:
          type: string
        ruleText:
          type: string
          description: "行为约束描述"
        category:
          type: string
          enum: [compliance, tone, boundary, custom]
        isEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
    BehaviorRuleCreate:
      type: object
      required: [ruleText, category]
      properties:
        ruleText:
          type: string
        category:
          type: string
          enum: [compliance, tone, boundary, custom]

    # v0.7.0 新增 schemas - 测试与监控
    FlowExecutionStep:
      type: object
      description: "流程执行步骤详情"
      properties:
        step:
          type: integer
          description: "步骤编号（1-12）"
        name:
          type: string
          description: "步骤名称"
        status:
          type: string
          enum: [success, failed, skipped]
          description: "执行状态"
        durationMs:
          type: integer
          description: "执行耗时（毫秒）"
        input:
          type: object
          description: "步骤输入数据"
        output:
          type: object
          description: "步骤输出数据"
        error:
          type: string
          nullable: true
          description: "错误信息（如果失败）"
        metadata:
          type: object
          description: "步骤元数据"

    FlowExecutionResult:
      type: object
      description: "完整流程执行结果"
      properties:
        executionId:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/FlowExecutionStep"
        totalDurationMs:
          type: integer
        finalReply:
          type: string
        confidence:
          type: number
          format: float
        shouldTransfer:
          type: boolean

    IntentRuleTestResult:
      type: object
      description: "意图规则测试结果"
      properties:
        matched:
          type: boolean
          description: "是否命中该规则"
        matchedKeywords:
          type: array
          items:
            type: string
          description: "匹配的关键词列表"
        matchedPatterns:
          type: array
          items:
            type: string
          description: "匹配的正则表达式列表"
        priority:
          type: integer
          description: "规则优先级"
        priorityRank:
          type: integer
          description: "在所有规则中的优先级排名"
        conflictRules:
          type: array
          items:
            type: object
            properties:
              ruleId:
                type: string
              ruleName:
                type: string
              priority:
                type: integer
          description: "同时命中的其他规则列表"
        reason:
          type: string
          nullable: true
          description: "未命中原因"

    IntentRuleStats:
      type: object
      description: "意图规则监控统计"
      properties:
        ruleId:
          type: string
        ruleName:
          type: string
        hitCount:
          type: integer
          description: "命中次数"
        hitRate:
          type: number
          format: float
          description: "命中率"
        avgResponseTime:
          type: number
          format: float
          description: "平均响应时间（毫秒）"
        lastHitTime:
          type: string
          format: date-time
          nullable: true
        responseType:
          type: string
          enum: [flow, rag, fixed, transfer]

    IntentRuleHitRecord:
      type: object
      description: "意图规则命中记录"
      properties:
        conversationId:
          type: string
        sessionId:
          type: string
        userMessage:
          type: string
        matchedKeywords:
          type: array
          items:
            type: string
        matchedPatterns:
          type: array
          items:
            type: string
        responseType:
          type: string
        executionResult:
          type: string
          enum: [success, failed]
        hitTime:
          type: string
          format: date-time

    PromptTemplatePreview:
      type: object
      description: "Prompt 模板预览结果"
      properties:
        templateId:
          type: string
        templateName:
          type: string
        version:
          type: integer
        rawContent:
          type: string
          description: "原始模板内容"
        variables:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
          description: "变量列表及当前值"
        renderedContent:
          type: string
          description: "渲染后的完整 Prompt"
        estimatedTokens:
          type: integer
          description: "预估 Token 数量"

    PromptTemplateStats:
      type: object
      description: "Prompt 模板监控统计"
      properties:
        templateId:
          type: string
        templateName:
          type: string
        scene:
          type: string
        usageCount:
          type: integer
        avgTokens:
          type: number
          format: float
        avgPromptTokens:
          type: number
          format: float
        avgCompletionTokens:
          type: number
          format: float
        lastUsedTime:
          type: string
          format: date-time
          nullable: true

    ScriptFlowSimulation:
      type: object
      description: "话术流程模拟执行结果"
      properties:
        simulationId:
          type: string
        flowId:
          type: string
        flowName:
          type: string
        currentStep:
          type: integer
        stepContent:
          type: string
        waitForInput:
          type: boolean
        nextConditions:
          type: array
          items:
            type: object
            properties:
              keywords:
                type: array
                items:
                  type: string
              nextStep:
                type: integer

    ScriptFlowStats:
      type: object
      description: "话术流程监控统计"
      properties:
        flowId:
          type: string
        flowName:
          type: string
        activationCount:
          type: integer
        completionCount:
          type: integer
        completionRate:
          type: number
          format: float
        avgCompletionTime:
          type: number
          format: float
          description: "平均完成时长（秒）"
        interruptionCount:
          type: integer
        interruptionRate:
          type: number
          format: float

    ScriptFlowExecution:
      type: object
      description: "话术流程执行记录"
      properties:
        executionId:
          type: string
        sessionId:
          type: string
        activationTime:
          type: string
          format: date-time
        currentStep:
          type: integer
        status:
          type: string
          enum: [in_progress, completed, interrupted]
        interruptionReason:
          type: string
          nullable: true
        completionTime:
          type: string
          format: date-time
          nullable: true

    GuardrailTestResult:
      type: object
      description: "输出护栏测试结果"
      properties:
        originalText:
          type: string
        processedText:
          type: string
        detectedWords:
          type: array
          items:
            type: object
            properties:
              word:
                type: string
              category:
                type: string
              position:
                type: integer
              strategy:
                type: string
                enum: [mask, replace, block]
        isBlocked:
          type: boolean
        blockReason:
          type: string
          nullable: true

    GuardrailStats:
      type: object
      description: "输出护栏监控统计"
      properties:
        wordId:
          type: string
        word:
          type: string
        category:
          type: string
        blockCount:
          type: integer
        replaceCount:
          type: integer
        maskCount:
          type: integer
        lastBlockTime:
          type: string
          format: date-time
          nullable: true

    GuardrailBlockRecord:
      type: object
      description: "禁词拦截记录"
      properties:
        blockId:
          type: string
        sessionId:
          type: string
        originalText:
          type: string
        processedText:
          type: string
        strategy:
          type: string
          enum: [mask, replace, block]
        blockTime:
          type: string
          format: date-time

    ConversationRecord:
      type: object
      description: "对话追踪记录"
      properties:
        conversationId:
          type: string
        sessionId:
          type: string
        userMessage:
          type: string
        aiReply:
          type: string
        triggeredRules:
          type: array
          items:
            type: string
          description: "触发的意图规则 ID 列表"
        usedTemplate:
          type: string
          nullable: true
          description: "使用的 Prompt 模板 ID"
        usedFlow:
          type: string
          nullable: true
          description: "使用的话术流程 ID"
        executionTime:
          type: integer
          description: "执行耗时（毫秒）"
        createdAt:
          type: string
          format: date-time

paths:
  /admin/kb/documents:
    get:
      summary: "查询文档列表"
      operationId: "listDocuments"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-08", "AC-AISVC-23"]
      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", "AC-AISVC-21", "AC-AISVC-22"]
      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", "AC-AISVC-24"]
      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", "AC-AISVC-25", "AC-AISVC-26"]
      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", "AC-AISVC-27"]
      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", "AC-AISVC-28"]
      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"

  # ========== v0.6.0 新增 paths ==========

  /admin/kb/knowledge-bases:
    get:
      summary: "查询知识库列表"
      operationId: "listKnowledgeBases"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-29", "AC-AISVC-59"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: kbType
          in: query
          required: false
          schema:
            type: string
            enum: [product, faq, script, policy, general]
          description: "知识库类型筛选"
        - name: isEnabled
          in: query
          required: false
          schema:
            type: boolean
          description: "启用状态筛选"
      responses:
        '200':
          description: "知识库列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/KnowledgeBaseInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "创建知识库"
      operationId: "createKnowledgeBase"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-30", "AC-AISVC-59"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KnowledgeBaseCreate"
      responses:
        '201':
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBaseInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/kb/knowledge-bases/{kbId}:
    put:
      summary: "更新知识库"
      operationId: "updateKnowledgeBase"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-32", "AC-AISVC-61"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: kbId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KnowledgeBaseUpdate"
      responses:
        '200':
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnowledgeBaseInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    delete:
      summary: "删除知识库"
      operationId: "deleteKnowledgeBase"
      tags:
        - KB Management
      x-requirements: ["AC-ASA-33", "AC-AISVC-62"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: kbId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: "删除成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/prompt-templates:
    get:
      summary: "查询 Prompt 模板列表"
      operationId: "listPromptTemplates"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-23", "AC-AISVC-57"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: scene
          in: query
          required: false
          schema:
            type: string
          description: "场景标签筛选"
      responses:
        '200':
          description: "模板列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PromptTemplateInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "创建 Prompt 模板"
      operationId: "createPromptTemplate"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-24", "AC-AISVC-52"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PromptTemplateCreate"
      responses:
        '201':
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptTemplateInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/prompt-templates/{tplId}:
    get:
      summary: "查询 Prompt 模板详情"
      operationId: "getPromptTemplateDetail"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-28", "AC-AISVC-58"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "模板详情（含版本历史）"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptTemplateDetail"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    put:
      summary: "更新 Prompt 模板（自动创建新版本）"
      operationId: "updatePromptTemplate"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-25", "AC-AISVC-53"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PromptTemplateCreate"
      responses:
        '200':
          description: "更新成功，返回新版本信息"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptTemplateInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/prompt-templates/{tplId}/publish:
    post:
      summary: "发布 Prompt 模板指定版本"
      operationId: "publishPromptTemplateVersion"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-26", "AC-AISVC-54"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                version:
                  type: integer
                  description: "要发布的版本号"
      responses:
        '200':
          description: "发布成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/prompt-templates/{tplId}/rollback:
    post:
      summary: "回滚 Prompt 模板到指定版本"
      operationId: "rollbackPromptTemplate"
      tags:
        - Prompt Management
      x-requirements: ["AC-ASA-27", "AC-AISVC-55"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                version:
                  type: integer
                  description: "要回滚到的版本号"
      responses:
        '200':
          description: "回滚成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/intent-rules:
    get:
      summary: "查询意图规则列表"
      operationId: "listIntentRules"
      tags:
        - Intent Rules
      x-requirements: ["AC-ASA-34", "AC-AISVC-65"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: responseType
          in: query
          required: false
          schema:
            type: string
            enum: [flow, rag, fixed, transfer]
          description: "响应类型筛选"
        - name: isEnabled
          in: query
          required: false
          schema:
            type: boolean
          description: "启用状态筛选"
      responses:
        '200':
          description: "规则列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/IntentRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "创建意图规则"
      operationId: "createIntentRule"
      tags:
        - Intent Rules
      x-requirements: ["AC-ASA-35", "AC-AISVC-66"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntentRuleCreate"
      responses:
        '201':
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntentRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/intent-rules/{ruleId}:
    put:
      summary: "更新意图规则"
      operationId: "updateIntentRule"
      tags:
        - Intent Rules
      x-requirements: ["AC-ASA-36", "AC-AISVC-67"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IntentRuleCreate"
      responses:
        '200':
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntentRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    delete:
      summary: "删除意图规则"
      operationId: "deleteIntentRule"
      tags:
        - Intent Rules
      x-requirements: ["AC-ASA-36", "AC-AISVC-68"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: "删除成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/script-flows:
    get:
      summary: "查询话术流程列表"
      operationId: "listScriptFlows"
      tags:
        - Script Flows
      x-requirements: ["AC-ASA-37", "AC-AISVC-71"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: isEnabled
          in: query
          required: false
          schema:
            type: boolean
          description: "启用状态筛选"
      responses:
        '200':
          description: "流程列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScriptFlowInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "创建话术流程"
      operationId: "createScriptFlow"
      tags:
        - Script Flows
      x-requirements: ["AC-ASA-38", "AC-AISVC-72"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScriptFlowCreate"
      responses:
        '201':
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/script-flows/{flowId}:
    get:
      summary: "查询话术流程详情"
      operationId: "getScriptFlowDetail"
      tags:
        - Script Flows
      x-requirements: ["AC-ASA-39", "AC-AISVC-73"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "流程详情（含完整步骤定义）"
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                  isEnabled:
                    type: boolean
                  steps:
                    type: array
                    items:
                      $ref: "#/components/schemas/FlowStep"
                  linkedRuleCount:
                    type: integer
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    put:
      summary: "更新话术流程"
      operationId: "updateScriptFlow"
      tags:
        - Script Flows
      x-requirements: ["AC-ASA-38", "AC-AISVC-72"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScriptFlowCreate"
      responses:
        '200':
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/guardrails/forbidden-words:
    get:
      summary: "查询禁词列表"
      operationId: "listForbiddenWords"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-41", "AC-AISVC-78"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum: [competitor, sensitive, political, custom]
          description: "类别筛选"
        - name: isEnabled
          in: query
          required: false
          schema:
            type: boolean
          description: "启用状态筛选"
      responses:
        '200':
          description: "禁词列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ForbiddenWordInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "添加禁词"
      operationId: "createForbiddenWord"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-42", "AC-AISVC-79"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForbiddenWordCreate"
      responses:
        '201':
          description: "添加成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenWordInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/guardrails/forbidden-words/{wordId}:
    put:
      summary: "更新禁词"
      operationId: "updateForbiddenWord"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-42", "AC-AISVC-80"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: wordId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForbiddenWordCreate"
      responses:
        '200':
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenWordInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    delete:
      summary: "删除禁词"
      operationId: "deleteForbiddenWord"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-42", "AC-AISVC-81"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: wordId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: "删除成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/guardrails/behavior-rules:
    get:
      summary: "查询行为规则列表"
      operationId: "listBehaviorRules"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-43", "AC-AISVC-84"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum: [compliance, tone, boundary, custom]
          description: "类别筛选"
      responses:
        '200':
          description: "行为规则列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/BehaviorRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    post:
      summary: "添加行为规则"
      operationId: "createBehaviorRule"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-44", "AC-AISVC-85"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BehaviorRuleCreate"
      responses:
        '201':
          description: "添加成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BehaviorRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/guardrails/behavior-rules/{ruleId}:
    put:
      summary: "更新行为规则"
      operationId: "updateBehaviorRule"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-43", "AC-AISVC-85"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BehaviorRuleCreate"
      responses:
        '200':
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BehaviorRuleInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
    delete:
      summary: "删除行为规则"
      operationId: "deleteBehaviorRule"
      tags:
        - Guardrails
      x-requirements: ["AC-ASA-43", "AC-AISVC-85"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: "删除成功"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  # v0.7.0 新增 paths - 测试与监控
  /admin/test/flow-execution:
    post:
      summary: "完整流程测试"
      operationId: "testFlowExecution"
      tags:
        - Testing
      x-requirements: ["AC-ASA-49", "AC-AISVC-93", "AC-AISVC-94", "AC-AISVC-95"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  description: "测试消息"
                sessionId:
                  type: string
                  description: "会话 ID（可选）"
                compareConfigs:
                  type: array
                  description: "对比配置列表"
                  items:
                    type: object
                    properties:
                      templateId:
                        type: string
                      kbIds:
                        type: array
                        items:
                          type: string
                      retrievalParams:
                        type: object
      responses:
        '200':
          description: "流程执行结果"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/FlowExecutionResult"
                  - type: object
                    properties:
                      comparisons:
                        type: array
                        items:
                          $ref: "#/components/schemas/FlowExecutionResult"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/intent-rules/{ruleId}/test:
    post:
      summary: "测试意图规则"
      operationId: "testIntentRule"
      tags:
        - Testing
      x-requirements: ["AC-ASA-53", "AC-AISVC-96"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  description: "测试消息"
      responses:
        '200':
          description: "测试结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntentRuleTestResult"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
  /admin/monitoring/intent-rules:
    get:
      summary: "查询意图规则监控统计"
      operationId: "getIntentRuleStats"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-54", "AC-AISVC-97"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          schema:
            type: string
            format: date-time
        - name: responseType
          in: query
          schema:
            type: string
            enum: [flow, rag, fixed, transfer]
      responses:
        '200':
          description: "规则统计列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/IntentRuleStats"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/intent-rules/{ruleId}/hits:
    get:
      summary: "查询意图规则命中记录"
      operationId: "getIntentRuleHits"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-55", "AC-AISVC-98"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: ruleId
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: "命中记录列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/IntentRuleHitRecord"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/prompt-templates/{tplId}/preview:
    post:
      summary: "预览 Prompt 模板"
      operationId: "previewPromptTemplate"
      tags:
        - Testing
      x-requirements: ["AC-ASA-56", "AC-AISVC-99"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: tplId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  description: "变量测试值（key-value 对）"
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: "预览结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptTemplatePreview"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/prompt-templates:
    get:
      summary: "查询 Prompt 模板监控统计"
      operationId: "getPromptTemplateStats"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-58", "AC-AISVC-100"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: scene
          in: query
          schema:
            type: string
          description: "场景标签筛选"
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: "模板统计列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PromptTemplateStats"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/script-flows/{flowId}/simulate:
    post:
      summary: "模拟执行话术流程"
      operationId: "simulateScriptFlow"
      tags:
        - Testing
      x-requirements: ["AC-ASA-59", "AC-AISVC-101"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: flowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "模拟执行结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowSimulation"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/script-flows/{flowId}/simulate/{simulationId}/next:
    post:
      summary: "推进话术流程模拟"
      operationId: "simulateScriptFlowNext"
      tags:
        - Testing
      x-requirements: ["AC-ASA-59", "AC-AISVC-102"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: flowId
          in: path
          required: true
          schema:
            type: string
        - name: simulationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userInput]
              properties:
                userInput:
                  type: string
                  description: "用户模拟输入"
      responses:
        '200':
          description: "下一步结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowSimulation"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/script-flows:
    get:
      summary: "查询话术流程监控统计"
      operationId: "getScriptFlowStats"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-60", "AC-AISVC-103"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: "流程统计列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScriptFlowStats"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/script-flows/{flowId}/executions:
    get:
      summary: "查询话术流程执行记录"
      operationId: "getScriptFlowExecutions"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-61", "AC-AISVC-104"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: flowId
          in: path
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [in_progress, completed, interrupted]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: "执行记录列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScriptFlowExecution"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/guardrails/test:
    post:
      summary: "测试输出护栏"
      operationId: "testGuardrail"
      tags:
        - Testing
      x-requirements: ["AC-ASA-62", "AC-AISVC-105"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  description: "测试文本"
      responses:
        '200':
          description: "测试结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuardrailTestResult"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/guardrails:
    get:
      summary: "查询输出护栏监控统计"
      operationId: "getGuardrailStats"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-63", "AC-AISVC-106"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: category
          in: query
          schema:
            type: string
            enum: [competitor, sensitive, political, custom]
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: "护栏统计列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/GuardrailStats"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/guardrails/{wordId}/blocks:
    get:
      summary: "查询禁词拦截记录"
      operationId: "getGuardrailBlocks"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-64", "AC-AISVC-107"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: wordId
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: "拦截记录列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/GuardrailBlockRecord"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/conversations:
    get:
      summary: "查询对话追踪列表"
      operationId: "getConversations"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-65", "AC-AISVC-108"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          schema:
            type: string
            format: date-time
        - name: ruleId
          in: query
          schema:
            type: string
          description: "意图规则 ID 筛选"
        - name: templateId
          in: query
          schema:
            type: string
          description: "Prompt 模板 ID 筛选"
        - name: flowId
          in: query
          schema:
            type: string
          description: "话术流程 ID 筛选"
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: "对话记录列表"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ConversationRecord"
                  pagination:
                    $ref: "#/components/schemas/PageInfo"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/conversations/{conversationId}:
    get:
      summary: "查询对话执行链路详情"
      operationId: "getConversationDetail"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-66", "AC-AISVC-109"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
        - name: conversationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "对话执行链路详情"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlowExecutionResult"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"

  /admin/monitoring/conversations/export:
    post:
      summary: "导出对话记录"
      operationId: "exportConversations"
      tags:
        - Monitoring
      x-requirements: ["AC-ASA-68", "AC-AISVC-110"]
      parameters:
        - $ref: "#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [json, csv]
                  default: json
                startTime:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
                filters:
                  type: object
                  properties:
                    ruleId:
                      type: string
                    templateId:
                      type: string
                    flowId:
                      type: string
      responses:
        '200':
          description: "导出文件"
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloadUrl:
                    type: string
                    description: "下载链接"
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"