2
0

SearchController.php 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123
  1. <?php
  2. namespace App\Http\Controllers\V3;
  3. use App\Http\Controllers\Concerns\ResolvesCurrentUser;
  4. use App\Http\Controllers\Controller;
  5. use App\Http\Requests\V3\IndexSearchRequest;
  6. use App\Http\Resources\V3\SearchHitResource;
  7. use App\Services\V3\SearchService;
  8. use Illuminate\Http\Request;
  9. /**
  10. * 全文检索(OpenSearch)
  11. *
  12. * 曾叫 `SearchPlusController`,2026-11-19 按 v3 规范重写:FormRequest 校验入参、
  13. * 响应改成 `{data, meta}`(不再透出 OpenSearch 原始响应)、失败走 Problem Details。
  14. * 与 v2 的 `SearchController`(`/v2/search`,PostgreSQL 全文检索)是两套实现,互不替代。
  15. */
  16. class SearchController extends Controller
  17. {
  18. use ResolvesCurrentUser;
  19. public function __construct(private readonly SearchService $search) {}
  20. /**
  21. * 全文检索
  22. *
  23. * 底层走 OpenSearch。同样的参数也可以用 `POST /v3/search` 放在请求体里提交。
  24. * 翻页深度受 OpenSearch 限制:`page × per_page` 不能超过 10000,超出 422。
  25. * 搜索服务连不上或超时回 503(`search-unavailable`)。
  26. *
  27. * @unauthenticated
  28. *
  29. * @queryParam q string required 检索词
  30. * @queryParam search_mode string 检索模式:fuzzy 多词模糊(默认)、exact 词形精确、semantic 语义向量、hybrid 模糊 + 语义、definition 黑体定义优先。Enum: fuzzy,exact,semantic,hybrid,definition Default: fuzzy
  31. * @queryParam resource_type string 资源类型:tipitaka 三藏(段落与整章)、original_text 原文分段、term 术语。Enum: tipitaka,original_text,term
  32. * @queryParam resource_id string 限定某个资源 id
  33. * @queryParam granularity string 文档颗粒度。Enum: book,chapter,session,paragraph
  34. * @queryParam language string 文档语言,如 pi、zh、en
  35. * @queryParam category string 分类,逗号分隔,须全部命中。Example: sutta,mūla
  36. * @queryParam tags string 标签,逗号分隔,命中任一
  37. * @queryParam page_refs array 页码标记,命中任一。Example: ["V3.81","M3.58"]
  38. * @queryParam related_id array 关联 id(经文段落是 `{book}-{para}`),命中任一。Example: ["93-5"]
  39. * @queryParam author string 作者或译者
  40. * @queryParam channel string 来源 channel 的 uuid
  41. * @queryParam facets boolean 是否在 `meta.facets` 里返回按 resource_type / language / category / granularity 的分面计数。Default: false
  42. * @queryParam page integer 页码。Default: 1
  43. * @queryParam per_page integer 每页条数,上限 100。Default: 20
  44. *
  45. * @responseStatus 503 搜索服务暂不可用
  46. *
  47. * @meta current_page integer 当前页
  48. * @meta per_page integer 每页条数
  49. * @meta total integer 命中总数(total_relation 为 gte 时是下限)
  50. * @meta total_relation string eq 精确,gte 表示「至少这么多」(OpenSearch 只精确计数到 10000)
  51. * @meta last_page integer 最后一页(受翻页深度限制)
  52. * @meta facets object 分面计数,只在 facets=true 时出现
  53. */
  54. public function index(IndexSearchRequest $request)
  55. {
  56. $result = $this->search->search($request->validated());
  57. return SearchHitResource::collection($result['items'])->additional(['meta' => $result['meta']]);
  58. }
  59. /**
  60. * 全文检索(POST)
  61. *
  62. * 与 `GET /v3/search` 完全等价,参数放在 JSON 请求体里(数组参数多、URL 放不下时用)。
  63. *
  64. * @unauthenticated
  65. *
  66. * @bodyParam q string required 检索词
  67. * @bodyParam search_mode string 检索模式。Enum: fuzzy,exact,semantic,hybrid,definition Default: fuzzy
  68. * @bodyParam resource_type string 资源类型。Enum: tipitaka,original_text,term
  69. * @bodyParam resource_id string 限定某个资源 id
  70. * @bodyParam granularity string 文档颗粒度。Enum: book,chapter,session,paragraph
  71. * @bodyParam language string 文档语言
  72. * @bodyParam category string 分类,逗号分隔,须全部命中
  73. * @bodyParam tags string 标签,逗号分隔,命中任一
  74. * @bodyParam page_refs array 页码标记,命中任一
  75. * @bodyParam related_id array 关联 id,命中任一
  76. * @bodyParam author string 作者或译者
  77. * @bodyParam channel string 来源 channel 的 uuid
  78. * @bodyParam facets boolean 是否返回分面计数。Default: false
  79. * @bodyParam page integer 页码。Default: 1
  80. * @bodyParam per_page integer 每页条数,上限 100。Default: 20
  81. *
  82. * @responseStatus 503 搜索服务暂不可用
  83. *
  84. * @meta current_page integer 当前页
  85. * @meta per_page integer 每页条数
  86. * @meta total integer 命中总数(total_relation 为 gte 时是下限)
  87. * @meta total_relation string eq 精确,gte 表示「至少这么多」
  88. * @meta last_page integer 最后一页(受翻页深度限制)
  89. * @meta facets object 分面计数,只在 facets=true 时出现
  90. */
  91. public function store(IndexSearchRequest $request)
  92. {
  93. $result = $this->search->search($request->validated());
  94. return SearchHitResource::collection($result['items'])->additional(['meta' => $result['meta']]);
  95. }
  96. /**
  97. * 按 id 取单条检索文档
  98. *
  99. * 直接从 OpenSearch 按文档 id 取回,带阅读用的 `display` HTML。
  100. * 整章正文文档(`tipitaka_chapter_{book}-{para}_{channel}`)按它所属 channel 判权限:
  101. * 私有 channel 只有拥有者、团队成员、被共享的人能读(要带 token)。
  102. *
  103. * @unauthenticated
  104. *
  105. * @urlParam search string required OpenSearch 文档 id
  106. *
  107. * @responseStatus 403 整章正文所属的 channel 是私有的,且当前身份看不见
  108. * @responseStatus 503 搜索服务暂不可用
  109. */
  110. public function show(Request $request, string $search): SearchHitResource
  111. {
  112. return SearchHitResource::make($this->search->find($search, $this->currentUserUid($request)));
  113. }
  114. }