mint/api-v13/app/Http/Controllers/V3/SearchSuggestController.php

<?php

// api-v8/app/Http/Controllers/SearchSuggestController.php

namespace App\Http\Controllers\V3;

use App\Http\Controllers\Controller;
use App\Services\OpenSearchService;
use Illuminate\Http\Request;

/**
 * 搜索自动建议控制器
 *
 * 返回示例：
 *
 * 请求：GET /api/v3/search-suggest?q=dhamma&fields=title,content&limit=10
 *
 * 返回：
 * {
 *   "success": true,
 *   "data": {
 *     "query": "dhamma",
 *     "suggestions": [
      {
        "text": "dhammacakkapavattanasutta",
        "source": "content",
        "score": 1,
        "resource_type": "term",
        "language": "zh",
        "doc_id": "term_69258244-bccd-40ed-bfaa-ddef4ae5ae4c",
        "category": [],
        "granularity": null
      },
      {
        "text": "dhammacakkappavattanasutta",
        "source": "content",
        "score": 1,
        "resource_type": "term",
        "language": "zh-hans",
        "doc_id": "term_bcb14399-ea80-4a8a-aeab-a4c927e45fdd",
        "category": [],
        "granularity": null
      }
 *     ],
 *     "total": 2
 *   }
 * }
 */
class SearchSuggestController extends Controller
{
    protected $searchService;

    /**
     * 构造函数，注入 OpenSearchService
     */
    public function __construct(OpenSearchService $searchService)
    {
        $this->searchService = $searchService;
    }

    /**
     * # 1. 查询所有字段（默认）
GET /api/v2/suggest?q=dhamma&limit=10

# 2. 只查询标题
GET /api/v2/suggest?q=dhamma&fields=title&limit=10

# 3. 查询标题和内容
GET /api/v2/suggest?q=dhamma&fields=title,content&limit=10

# 4. 查询页面引用，带语言过滤
GET /api/v2/suggest?q=M.1&fields=page_refs&language=pali&limit=5

# 5. 数组形式传递多个字段
GET /api/v2/suggest?q=dhamma&fields[]=title&fields[]=content&limit=10
     */
    /**
     * 搜索建议（自动补全）
     *
     * 按前缀给出补全候选，供搜索框实时提示。每个字段各自返回一组建议。
     * q 为空时返回 400。
     *
     * @unauthenticated
     *
     * @queryParam q string required 已输入的查询文本
     * @queryParam fields string 在哪些字段上补全，逗号分隔；不传则全查。
     *             Enum: title,content,page_refs
     * @queryParam language string 语言过滤。Example: pali
     * @queryParam limit integer 每个字段返回的建议数，上限 50。Default: 10
     */
    public function index(Request $request)
    {
        // 验证必填参数
        $query = $request->input('q', '');
        if (empty($query)) {
            return response()->json([
                'success' => false,
                'error' => '缺少参数 q（查询文本）',
            ], 400);
        }

        // 解析 fields 参数
        $fields = $this->parseFields($request->input('fields'));

        // 获取其他参数
        $language = $request->input('language', null);
        $limit = min(50, max(1, (int) $request->input('limit', 10)));

        try {
            // 调用搜索服务
            $rawSuggestions = $this->searchService->suggest(
                $query,
                $fields,
                $language,
                $limit
            );

            // 格式化返回结果
            $suggestions = $this->formatSuggestions($rawSuggestions);

            return response()->json([
                'success' => true,
                'data' => [
                    'query' => $query,
                    'suggestions' => $suggestions,
                    'total' => count($suggestions),
                ],
            ]);
        } catch (\InvalidArgumentException $e) {
            return response()->json([
                'success' => false,
                'error' => '无效的字段参数：'.$e->getMessage(),
                'hint' => '有效的字段值：title, content, page_refs',
            ], 400);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => '搜索建议失败：'.$e->getMessage(),
            ], 500);
        }
    }

    /**
     * 解析 fields 参数
     *
     * @param  mixed  $fields
     * @return string|array|null
     */
    protected function parseFields($fields)
    {
        if ($fields === null) {
            return null;  // 查询所有字段
        }

        if (is_string($fields)) {
            // 如果是逗号分隔的字符串，转换为数组
            if (strpos($fields, ',') !== false) {
                $fieldsArray = array_map('trim', explode(',', $fields));

                return $fieldsArray;
            }

            // 单个字段
            return $fields;
        }

        if (is_array($fields)) {
            return $fields;
        }

        return null;
    }

    /**
     * 格式化建议结果
     */
    protected function formatSuggestions(array $rawSuggestions): array
    {
        return collect($rawSuggestions)->map(function ($item) {
            $docSource = $item['doc_source'] ?? [];

            return [
                'text' => $item['text'] ?? '',
                'source' => $item['source'] ?? null,
                'score' => round($item['score'] ?? 0, 2),
                'resource_type' => $docSource['resource_type'] ?? null,
                'language' => $docSource['language'] ?? null,
                'doc_id' => $item['doc_id'] ?? null,
                // 可选：添加更多元数据
                'category' => $docSource['category'] ?? null,
                'granularity' => $docSource['granularity'] ?? null,
            ];
        })->all();
    }
}