openapi: 3.1.0
info:
  title: "Intent-Driven Script Flow API Extension"
  description: |
    [AC-IDS-02] 意图驱动话术流程的 API 扩展规范

    本文档描述对现有 ScriptFlow API 的扩展，增加意图驱动话术生成能力。
    这是对 `spec/ai-service/openapi.admin.yaml` 的向后兼容扩展。

    **变更摘要**:
    - 扩展 `FlowStep` schema，增加意图驱动字段
    - 所有新字段均为可选（optional），确保向后兼容
    - 复用现有的 CRUD 接口，无需新增接口

    **影响接口**:
    - POST /admin/script-flows
    - PUT /admin/script-flows/{id}
    - GET /admin/script-flows/{id}
  version: "1.0.0"
  x-contract-level: L1
  x-extends: "../ai-service/openapi.admin.yaml"

components:
  schemas:
    # [AC-IDS-01] 扩展的 FlowStep Schema
    FlowStepExtended:
      type: object
      required: [stepNo, content]
      properties:
        # === 原有字段（保持不变）===
        stepNo:
          type: integer
          description: "步骤序号（从1开始）"
          example: 1

        content:
          type: string
          description: |
            话术内容。根据 script_mode 的不同有不同含义：
            - fixed 模式：固定话术文本
            - flexible 模式：fallback 话术（LLM 生成失败时使用）
            - template 模式：话术模板（包含 {变量名} 占位符）
          example: "您好，请问怎么称呼您？"

        waitInput:
          type: boolean
          default: true
          description: "是否等待用户输入"

        timeoutSeconds:
          type: integer
          default: 120
          description: "等待超时时间（秒）"
          minimum: 10
          maximum: 600

        timeoutAction:
          type: string
          enum: [repeat, skip, transfer]
          default: repeat
          description: |
            超时后的动作：
            - repeat: 重复当前步骤
            - skip: 跳过进入下一步
            - transfer: 转人工

        nextConditions:
          type: array
          description: "条件跳转配置"
          items:
            type: object
            properties:
              keywords:
                type: array
                items:
                  type: string
                description: "关键词列表"
              pattern:
                type: string
                description: "正则表达式模式"
              gotoStep:
                type: integer
                description: "跳转到的步骤号"

        defaultNext:
          type: integer
          nullable: true
          description: "默认下一步（null 表示顺序执行）"

        # === 新增字段（意图驱动）===
        script_mode:
          type: string
          enum: [fixed, flexible, template]
          default: fixed
          description: |
            [AC-IDS-01] 话术模式：
            - fixed: 固定话术（向后兼容，默认模式）
            - flexible: 灵活话术（AI 根据意图和上下文生成）
            - template: 模板话术（AI 填充变量）
          example: "flexible"

        intent:
          type: string
          nullable: true
          description: |
            [AC-IDS-01] 步骤意图（flexible 模式必填）
            描述这一步要达到的目的，而不是具体说什么话。
          example: "获取用户真实姓名"

        intent_description:
          type: string
          nullable: true
          description: |
            [AC-IDS-01] 意图详细说明（可选）
            提供更详细的上下文信息，帮助 AI 更好地理解意图。
          example: "需要获取用户的真实姓名用于后续身份确认，如果用户已经说了姓名则直接确认，如果没说则礼貌询问"

        script_constraints:
          type: array
          items:
            type: string
          nullable: true
          description: |
            [AC-IDS-01] 话术约束条件（flexible 模式推荐配置）
            对生成话术的限制条件，例如语气、风格、长度等。
          example:
            - "必须礼貌"
            - "语气自然，不要生硬"
            - "如果用户已经说了姓名，直接确认即可"
            - "如果用户拒绝，不要强迫"

        expected_variables:
          type: array
          items:
            type: string
          nullable: true
          description: |
            [AC-IDS-01] 期望提取的变量（可选）
            这一步期望从用户输入中提取的变量名称。
          example: ["user_name"]

    # 扩展的 ScriptFlowCreate（用于创建流程）
    ScriptFlowCreateExtended:
      type: object
      required: [name, steps]
      properties:
        name:
          type: string
          description: "流程名称"
          example: "客户信息收集流程"

        description:
          type: string
          nullable: true
          description: "流程描述"
          example: "收集客户姓名、电话、需求等基本信息"

        steps:
          type: array
          description: "流程步骤列表"
          items:
            $ref: "#/components/schemas/FlowStepExtended"

        isEnabled:
          type: boolean
          default: true
          description: "是否启用"

    # 扩展的 ScriptFlowDetail（用于返回流程详情）
    ScriptFlowDetailExtended:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "流程ID"

        name:
          type: string
          description: "流程名称"

        description:
          type: string
          nullable: true
          description: "流程描述"

        steps:
          type: array
          description: "流程步骤列表"
          items:
            $ref: "#/components/schemas/FlowStepExtended"

        isEnabled:
          type: boolean
          description: "是否启用"

        stepCount:
          type: integer
          description: "步骤数量"

        linkedRuleCount:
          type: integer
          description: "关联的意图规则数量"

        createdAt:
          type: string
          format: date-time
          description: "创建时间"

        updatedAt:
          type: string
          format: date-time
          description: "更新时间"

  examples:
    # 示例1：固定话术模式（向后兼容）
    FixedModeStep:
      summary: "固定话术步骤（传统模式）"
      value:
        stepNo: 1
        content: "您好，请问您贵姓？"
        waitInput: true
        timeoutSeconds: 60
        script_mode: "fixed"

    # 示例2：灵活话术模式
    FlexibleModeStep:
      summary: "灵活话术步骤（意图驱动）"
      value:
        stepNo: 1
        script_mode: "flexible"
        intent: "获取用户真实姓名"
        intent_description: "需要获取用户的真实姓名用于后续身份确认，如果用户已经说了姓名则直接确认，如果没说则礼貌询问"
        script_constraints:
          - "必须礼貌"
          - "语气自然，不要生硬"
          - "如果用户已经说了姓名，直接确认即可"
          - "如果用户拒绝，不要强迫"
        expected_variables:
          - "user_name"
        content: "您好，请问怎么称呼您？"  # fallback 话术
        waitInput: true
        timeoutSeconds: 60

    # 示例3：模板话术模式
    TemplateModeStep:
      summary: "模板话术步骤"
      value:
        stepNo: 2
        script_mode: "template"
        content: "好的{user_name}，请问您{inquiry_style}？"
        intent: "询问用户需求"
        script_constraints:
          - "根据用户姓名调整称呼方式"
          - "询问方式要自然"
        expected_variables:
          - "user_requirement"
        waitInput: true

    # 示例4：完整流程（混合模式）
    MixedModeFlow:
      summary: "混合模式流程（包含固定、灵活、模板三种步骤）"
      value:
        name: "客户信息收集流程"
        description: "收集客户基本信息并了解需求"
        steps:
          - stepNo: 1
            script_mode: "fixed"
            content: "您好，欢迎咨询！"
            waitInput: false

          - stepNo: 2
            script_mode: "flexible"
            intent: "获取用户姓名"
            intent_description: "礼貌询问用户姓名"
            script_constraints:
              - "必须礼貌"
              - "语气自然"
            content: "请问怎么称呼您？"
            waitInput: true
            expected_variables: ["user_name"]

          - stepNo: 3
            script_mode: "template"
            content: "好的{user_name}，请问您有什么需要帮助的吗？"
            intent: "询问用户需求"
            waitInput: true
            expected_variables: ["user_requirement"]

# 接口路径说明（复用现有接口，无需新增）
paths:
  /admin/script-flows:
    post:
      summary: "创建话术流程"
      description: |
        [AC-IDS-02] 创建新的话术流程。
        支持意图驱动的步骤配置（通过 FlowStepExtended schema）。
      operationId: createScriptFlow
      parameters:
        - $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScriptFlowCreateExtended"
            examples:
              mixedMode:
                $ref: "#/components/examples/MixedModeFlow"
      responses:
        "201":
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowDetailExtended"
        "400":
          description: "请求参数错误"
        "401":
          $ref: "../ai-service/openapi.admin.yaml#/components/responses/Unauthorized"

  /admin/script-flows/{id}:
    get:
      summary: "获取话术流程详情"
      description: |
        [AC-IDS-02] 获取指定流程的详细信息。
        返回包含意图驱动字段的完整步骤配置。
      operationId: getScriptFlow
      parameters:
        - $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: "获取成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowDetailExtended"
        "404":
          description: "流程不存在"

    put:
      summary: "更新话术流程"
      description: |
        [AC-IDS-02] 更新现有流程的配置。
        支持修改步骤的话术模式和意图配置。
      operationId: updateScriptFlow
      parameters:
        - $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScriptFlowCreateExtended"
      responses:
        "200":
          description: "更新成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScriptFlowDetailExtended"
        "404":
          description: "流程不存在"

# 向后兼容性说明
x-compatibility:
  backward-compatible: true
  migration-required: false
  notes: |
    本扩展完全向后兼容：

    1. **数据兼容性**
       - 所有新字段均为可选（nullable）
       - 未指定 script_mode 时默认为 'fixed'
       - 现有流程数据无需迁移即可正常工作

    2. **API 兼容性**
       - 复用现有接口，无需修改接口路径
       - 请求体向后兼容（新字段可选）
       - 响应体向后兼容（新字段可能为 null）

    3. **客户端兼容性**
       - 旧版客户端可以忽略新字段
       - 新版客户端可以处理缺失的新字段

    4. **执行兼容性**
       - 未指定 script_mode 的步骤按 fixed 模式执行
       - 保持与现有流程完全相同的行为

# 验收标准映射
x-acceptance-criteria:
  - id: AC-IDS-01
    description: "扩展 ScriptFlow 数据模型"
    schema: FlowStepExtended
    status: defined

  - id: AC-IDS-02
    description: "扩展 Admin API 契约"
    paths:
      - POST /admin/script-flows
      - PUT /admin/script-flows/{id}
      - GET /admin/script-flows/{id}
    status: defined