openapi: "3.0.3"
info:
  title: "AI Service Retrieval Strategy API"
  version: "0.1.0"
  description: "检索与嵌入策略配置/查询/验证接口"
  x-contract-level: "L1"
servers:
  - url: "/"
paths:
  /strategy/retrieval/current:
    get:
      summary: "获取当前检索策略"
      operationId: getCurrentRetrievalStrategy
      tags:
        - RetrievalStrategy
      responses:
        "200":
          description: "当前策略"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrievalStrategyStatus"
      x-requirements:
        - AC-AISVC-RES-01
  /strategy/retrieval/switch:
    post:
      summary: "切换检索策略"
      operationId: switchRetrievalStrategy
      tags:
        - RetrievalStrategy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetrievalStrategySwitchRequest"
      responses:
        "200":
          description: "切换结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrievalStrategySwitchResponse"
      x-requirements:
        - AC-AISVC-RES-02
        - AC-AISVC-RES-03
        - AC-AISVC-RES-05
  /strategy/retrieval/validate:
    post:
      summary: "验证策略一致性"
      operationId: validateRetrievalStrategy
      tags:
        - RetrievalStrategy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetrievalStrategyValidationRequest"
      responses:
        "200":
          description: "校验结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrievalStrategyValidationResponse"
      x-requirements:
        - AC-AISVC-RES-04
        - AC-AISVC-RES-06
        - AC-AISVC-RES-08
  /strategy/retrieval/rollback:
    post:
      summary: "回退策略"
      operationId: rollbackRetrievalStrategy
      tags:
        - RetrievalStrategy
      responses:
        "200":
          description: "回退结果"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrievalStrategyRollbackResponse"
      x-requirements:
        - AC-AISVC-RES-07
components:
  schemas:
    RetrievalStrategyStatus:
      type: object
      required:
        - active_strategy
        - react_mode
        - rollout
      properties:
        active_strategy:
          type: string
          description: "当前策略"
          enum: ["default", "enhanced"]
        react_mode:
          type: string
          description: "ReAct 模式"
          enum: ["react", "non_react"]
        rollout:
          $ref: "#/components/schemas/RolloutConfig"
    RolloutConfig:
      type: object
      required:
        - mode
      properties:
        mode:
          type: string
          enum: ["off", "percentage", "allowlist"]
        percentage:
          type: number
          minimum: 0
          maximum: 100
        allowlist:
          type: array
          items:
            type: string
    RetrievalStrategySwitchRequest:
      type: object
      required:
        - target_strategy
      properties:
        target_strategy:
          type: string
          enum: ["default", "enhanced"]
        react_mode:
          type: string
          enum: ["react", "non_react"]
        rollout:
          $ref: "#/components/schemas/RolloutConfig"
        reason:
          type: string
    RetrievalStrategySwitchResponse:
      type: object
      required:
        - previous
        - current
      properties:
        previous:
          $ref: "#/components/schemas/RetrievalStrategyStatus"
        current:
          $ref: "#/components/schemas/RetrievalStrategyStatus"
    RetrievalStrategyValidationRequest:
      type: object
      required:
        - strategy
      properties:
        strategy:
          type: string
          enum: ["default", "enhanced"]
        react_mode:
          type: string
          enum: ["react", "non_react"]
        checks:
          type: array
          items:
            type: string
            enum: ["metadata_consistency", "embedding_prefix", "rrf_config", "performance_budget"]
    RetrievalStrategyValidationResponse:
      type: object
      required:
        - passed
        - results
      properties:
        passed:
          type: boolean
        results:
          type: array
          items:
            $ref: "#/components/schemas/ValidationResult"
    ValidationResult:
      type: object
      required:
        - check
        - passed
      properties:
        check:
          type: string
        passed:
          type: boolean
        message:
          type: string
    RetrievalStrategyRollbackResponse:
      type: object
      required:
        - current
        - rollback_to
      properties:
        current:
          $ref: "#/components/schemas/RetrievalStrategyStatus"
        rollback_to:
          $ref: "#/components/schemas/RetrievalStrategyStatus"