用途:面向 UnoPim 商品或分类搜索相关改动,涵盖 Elasticsearch 索引与过滤逻辑。Elasticsearch 在 UnoPim 中是数据库之上的可选派生索引,每个商品过滤器存在 Database 与 ElasticSearch 两个分支,由 config('elasticsearch.enabled') 在运行时选择。
主要能力:指导新增或修改可过滤/可排序字段时同时实现两个分支;解释索引、观察者、映射与导入写入路径;处理“保存后搜不到”“搜索结果陈旧”等索引问题;说明如何通过 --fresh 重建索引;指导新实体独立索引所需的索引命令、观察者、清理步骤与数据库回退。
使用方式:依赖 unopim-standards、unopim-exec、unopim-verify 等背景技能;改过滤器参照 filters.md,改索引参照 indexing.md,并对照列出的示例文件而非转述。项目不使用 Laravel Scout,禁止添加 Searchable、toSearchableArray()、scout:import、scout:flush、Scout 配置或 Product::search();客户端使用 Webkul\Core\Facades\ElasticSearch 门面,索引由三个控制台命令和两个观察者完成。
限制与陷阱:写入不要用裸 UPDATE,否则观察者不触发;仅改已索引列而不更新 updated_at 会被增量索引跳过;ES 近实时,不应在同一请求中断言刚保存即搜索到;查询构建须使用 builder 持有的 ElasticSearchQuery,避免容器单例导致 clause 累积(unopim#559);Observer 的 disable() 需用 try/finally;布尔字段需经 FILTER_VALIDATE_BOOLEAN 转换;索引名为 strtolower(config('elasticsearch.prefix').'_products'),不可由 DB 表前缀推导。搜索本身不新增路由,若新增(如重建按钮)需覆盖 ACL。验证须跑全部关卡,映射或索引载荷变更需在真实集群运行 unopim:product:index --fresh 或在 PR 中说明未运行。