/**
 * 元素定位 API
 *
 * 提供本地元素定位功能，通过 Playwright 访问被测页面，
 * 提取可交互元素，匹配步骤描述，返回候选定位器列表。
 *
 * @module api/elementLocate
 * @author czj
 * @date 2026-08-03
 */

import request from '@/utils/request'

/**
 * 元素定位请求参数
 */
export interface LocateRequest {
  /** 步骤描述，如"输入用户名" */
  step_description: string
  /** 目标页面 URL */
  page_url: string
  /** 预期结果（可选） */
  expected?: string
  /** 是否自动登录（默认 true） */
  auto_login?: boolean
}

/**
 * 定位候选
 */
export interface LocateCandidate {
  /** 定位类型: css/xpath/text/id/name */
  locator_type: string
  /** 定位值 */
  locator_value: string
  /** 置信度 0-1 */
  confidence: number
  /** 元素信息 */
  element_info: Record<string, any>
}

/**
 * 元素定位响应
 */
export interface LocateResponse {
  /** 是否成功 */
  success: boolean
  /** 候选定位器列表（按置信度降序） */
  candidates: LocateCandidate[]
  /** 消息 */
  message: string
  /** 页面截图（base64，可选） */
  screenshot?: string
}

/**
 * 元素定位 API
 */
export const elementLocateApi = {
  /**
   * 执行元素定位
   *
   * @param data - 定位请求参数
   * @returns 定位结果
   *
   * @example
   * const result = await elementLocateApi.locate({
   *   step_description: '输入用户名',
   *   page_url: 'https://192.168.5.44/',
   *   auto_login: true,
   * })
   *
   * if (result.success && result.candidates.length > 0) {
   *   const best = result.candidates[0]
   *   console.log(`定位成功: ${best.locator_value} (${best.confidence})`)
   * }
   */
  async locate(data: LocateRequest): Promise<LocateResponse> {
    const response = await request.post('/api/element/locate', data, {
      timeout: 60000,  // 60秒超时（Playwright 启动较慢）
    })
    return response.data
  },
}