@gordon.gan/specflow 1.4.0-beta → 1.4.2-beta

package/skills/database/elasticsearch/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/database/elasticsearch/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: elasticsearch
+description: Provides comprehensive guidance for Elasticsearch including indexing, mappings, query DSL, aggregations, analyzers, cluster management, and ELK Stack integration. Use when the user asks about Elasticsearch, needs to implement search functionality, work with Elasticsearch queries, or manage Elasticsearch clusters.
+license: Complete terms in LICENSE.txt
+---
+
+# Elasticsearch — 分布式搜索与分析引擎
+
+Elasticsearch 是基于 Apache Lucene 的分布式搜索和分析引擎，提供近实时的全文搜索、结构化搜索、聚合分析、地理空间查询和向量搜索能力。
+
+## Workflow — 从数据到搜索的 5 步决策流程
+
+```
+遇到 ES 相关需求时按以下顺序决策:
+
+Step 1: 明确场景
+├── 全文搜索?                    → Step 2
+├── 结构化数据分析 (日志/指标)?   → Step 2
+├── 向量/KNN 搜索?               → references/ 向量搜索
+├── 地理空间查询?                 → references/ 地理查询
+├── 集群运维/性能问题?             → references/ 07-cluster-ops
+└── 数据管道/日志采集?             → references/ 08-elk-integration
+
+Step 2: 设计索引 (Mapping + Analyzer)
+├── 确定字段类型 (text/keyword/date/geo/nested…)
+├── 选择分词器 (standard/ik/pinyin/自定义)
+├── 规划主分片数 (每个分片 20-50GB), 建后不可改
+└── 设置别名用于零停机重建
+
+Step 3: 写入数据
+├── Index API (单条), Bulk API (批量, 5-15MB/批)
+├── _update (部分更新), _update_by_query (条件更新)
+└── Logstash/Filebeat (日志采集管道)
+
+Step 4: 构建查询
+├── 全文搜索: match / multi_match / query_string
+├── 精确过滤: term / terms / range / exists / bool filter
+├── 复合查询: bool (must/should/filter/must_not)
+├── 聚合分析: terms + avg → references/ 聚合专题
+└── 排序/分页: sort / search_after (深度分页) / scroll (导出)
+
+Step 5: 持续优化
+├── 性能问题?  → Profile API + 慢查询日志
+├── 数据增长?  → ILM + Rollover 自动化 (references/ 07-cluster-ops)
+├── Mapping 变更? → Reindex + Alias 零停机 (examples/03)
+└── 查询优化?  → filter 优先 query, 避免 script, 限制 _source
+```
+
+## When to Use / When NOT to
+
+| ✅ 使用 ES | ❌ 不要用 ES |
+|-----------|-------------|
+| **全文搜索** — 商品/文章/文档关键词搜索 | **复杂事务** — 需要 ACID/多表 JOIN, 选 PostgreSQL |
+| **日志/指标分析** — ELK Stack 日志场景 | **键值缓存** — 简单 KV 查询, 选 Redis |
+| **搜索型应用** — 电商/知识库/文档管理 | **强 Schema 约束** — 需要外键/触发器, 选 RDBMS |
+| **聚合/仪表盘** — 实时统计 + Kibana 可视化 | **海量文档存储无需搜索** — 选 MongoDB |
+| **地理空间查询** — 附近的人/POI/地理围栏 | **纯 OLAP 分析** — PB 级离线分析, 选 ClickHouse |
+| **向量搜索** — 语义相似度/RAG 检索 | **消息队列** — 选 Kafka/Pulsar |
+
+**核心原则**：Elasticsearch 是搜索服务器，不是关系型数据库的替代品。
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 |
+|-----------|--------------|---------|
+| 全文搜索、模糊搜索、相关性排序 | 强一致性（ES 是近实时，默认 1s refresh） | 代替关系型数据库做核心业务存储 |
+| 日志/指标聚合分析 (Kibana) | 秒级以下数据可见性（需调 refresh_interval） | 复杂 JOIN 查询（ES 有有限 nested 支持）|
+| 地理空间、自动补全、搜索建议 | 极高写入量（需调优线程池和批量写入） | ACID 事务保证 |
+| 文档搜索、知识库、RAG 检索 | 50+ 节点大集群（需专用协调节点） | 存储二进制大文件（存 OSS 路径） |
+| 时序数据 + ILM 滚动 | PB 级深度分页（需 search_after / PIT） | 强关联约束数据模型 |
+| 向量搜索 (dense_vector + KNN) | 自定义分词器（需先测试分析效果） | 替代 Kafka 做消息队列 |
+
+## 核心概念速查
+
+| 概念 | ES 术语 | 关系型 DB 类比 | 关键说明 | 深度参考 |
+|------|---------|---------------|---------|---------|
+| **Index** | 索引 | Table | 存储文档的逻辑命名空间，名称必须小写 | references/05 |
+| **Document** | 文档 | Row | JSON 格式基本数据单元，不可变（update = delete+index） | — |
+| **Shard** | 分片 | Partition | 水平切分单元，主分片数建后不可改，推荐 20-50GB/分片 | references/07 |
+| **Replica** | 副本 | Replica | 冗余副本提供高可用和读扩展，可动态调整 | references/07 |
+| **Mapping** | 映射 | Schema | 定义字段类型和分词配置，已有字段类型不可修改 | references/05 |
+| **Analyzer** | 分词器 | — | text 字段必须配置，决定搜索质量 | references/06 |
+
+## 查询 DSL 速查
+
+| 查询类别 | 核心查询 | 用途 | 深度参考 |
+|---------|---------|------|---------|
+| **全文查询** | match / match_phrase / multi_match / query_string | 文本分词搜索、短语匹配、多字段搜索 | references/01 |
+| **精确查询** | term / terms / range / exists / ids | keyword 字段精确匹配、范围过滤、存在检查 | references/02 |
+| **复合查询** | bool (must/filter/should/must_not) | 90% 搜索需求可用 bool 实现 | references/02 |
+| **嵌套/父子** | nested / has_child / has_parent | 对象内跨字段关联、父子关系查询 | references/02 |
+| **地理查询** | geo_distance / geo_bounding_box / geo_shape | 附近查询、矩形区域、复杂地理形状 | 见 geospatial 技能 |
+| **向量查询** | knn 参数 / k-NN 插件 | 语义相似度、RAG 检索 | references/05 |
+| **特殊查询** | fuzzy / wildcard / regexp / script / percolate | 模糊纠错、通配符、脚本、反向搜索 | references/02 |
+
+## 聚合速查
+
+| 聚合类型 | 核心聚合 | 类似 SQL | 深度参考 |
+|---------|---------|---------|---------|
+| **指标聚合** | avg / sum / min / max / stats / cardinality / percentiles | AVG / SUM / COUNT(DISTINCT) / PERCENTILE | references/03 |
+| **桶聚合** | terms / date_histogram / histogram / range / filters | GROUP BY / 日期分组 / 区间分组 / 过滤分组 | references/04 |
+| **管道聚合** | derivative / moving_fn / bucket_script / bucket_selector | 环比 / 移动平均 / 子聚合计算 / HAVING | references/04 |
+
+## 集群运维概述
+
+| 运维领域 | 关键要点 | 深度参考 |
+|---------|---------|---------|
+| **节点类型** | Master(3个专用) + Data(SSD) + Coordinating(大查询) | references/07 |
+| **分片管理** | 分配/再平衡/reroute/延迟分配 | references/07 |
+| **快照备份** | S3/FS/GCS 仓库, SLM 自动管理, 增量快照 | references/07 |
+| **ILM 生命周期** | hot → warm → cold → frozen → delete 自动化 | references/07 |
+| **监控命令** | _cluster/health, _cat/nodes, _cat/shards, hot_threads | references/07 |
+| **安全** | RBAC 角色, 字段/文档级安全, TLS, API Key | references/07 |
+
+## Gotchas — 常见陷阱与反模式
+
+| # | 陷阱 | 问题 | 解决方案 |
+|---|------|------|---------|
+| 1 | `term` 查询 `text` 字段 | text 被分词，找不到精确值 | 用 `match` 或 `.keyword` 子字段 |
+| 2 | `from+size` 深度分页 | 越深越慢直至 OOM (限制 10000) | 深翻页用 `search_after`，导出用 `scroll`/PIT |
+| 3 | 建索引后改主分片数 | 建后不可修改 | 提前规划，或重建索引 (reindex) |
+| 4 | 所有字段用 `text` | 聚合/排序报错 | text + keyword 多字段 |
+| 5 | 依赖动态映射 | 时间戳被识别为 long 等 | 生产环境显式 mapping |
+| 6 | 嵌套对象用普通查询 | 跨字段关联条件误匹配 | 必须用 `nested` 查询 |
+| 7 | 分片过多或过少 | 过多→管理开销大，过少→无法扩展 | 每个分片 20-50GB |
+| 8 | 大批量写入不做优化 | 频繁 refresh 产生大量小段 | 关闭 refresh (-1), Bulk API, 副本=0 |
+| 9 | 忽略 filter 缓存 | 重复计算，性能差 | 不需要算分的条件放 filter |
+| 10 | wildcard/regexp 前缀搜索 | 不利用倒排索引，性能极差 | 用 `prefix` 或 edge_ngram |
+| 11 | 脚本查询滥用 | 不可缓存，性能差，调试困难 | 用 ingest pipeline 预处理 |
+| 12 | 集群角色不做分离 | Master 因 Data GC 失联 | 专用 3 个 Master 节点 |
+| 13 | 日志索引无 ILM | 索引无限增长 | ILM 自动化滚动/压缩/删除 |
+| 14 | 忽略 `ignore_above` | keyword 超长导致索引失败 | 设置 `ignore_above: 256` |
+| 15 | 在 text 字段开 `fielddata` | 内存消耗大 | 用 `.keyword` 多字段替代 |
+
+## FAQ
+
+**Q1: ES 是关系型数据库的替代品吗？**
+不是。ES 是搜索服务器，不支持 ACID 事务、外键、复杂 JOIN。正确架构：业务数据存 RDBMS，ES 做搜索和聚合。
+
+**Q2: 数据写入后多久能查到？**
+近实时。写入先到 buffer，默认 1s refresh 后才可搜索。可调 `refresh_interval` 或加 `?refresh` 参数。
+
+**Q3: text 和 keyword 字段区别？**
+text：分词后索引，支持 match 搜索，不支持排序/聚合。keyword：完整值索引，支持 term 搜索、排序、聚合。
+
+**Q4: 主分片数为什么不能修改？**
+路由规则 `hash(_id) % shards`，修改后已有数据无法定位。变更需 reindex。
+
+**Q5: 如何选择分片数？**
+每个分片 20-50GB。500GB 原始数据 → 10-25 个主分片。每个节点 ≤25 分片/GB 堆内存。
+
+**Q6: ES 为什么搜索快？**
+倒排索引：将每个词项映射到文档列表，查找直接定位。加分片并行 + filter 缓存。
+
+**Q7: 聚合 (Aggregation) 是什么？**
+Bucket = GROUP BY 分组，Metric = AVG/SUM/COUNT，Pipeline = 聚合结果的再分析。详见 references/03, references/04。
+
+**Q8: Green/Yellow/Red 状态？**
+Green=全正常，Yellow=主分片正常但副本未分配，Red=主分片丢失。
+
+**Q9: 如何零停机重建索引？**
+Alias + Reindex：创建新索引 → Reindex 数据 → 原子切换 Alias → 删除旧索引。见 examples/03。
+
+**Q10: ES 和 Solr 怎么选？**
+ES 集群管理内置、近实时搜索 1s、聚合强大、ELK 生态完整。Solr 依赖 ZK，配置复杂。
+
+**Q11: Mapping 可以修改吗？**
+可新增字段，不可修改已有字段类型（如 text→keyword），需重建索引。
+
+**Q12: search_after 和 from+size 区别？**
+from+size 深度分页 OOM（限制 10000）。search_after 基于排序值翻页，性能与深度无关。
+
+**Q13: 数据备份怎么做？**
+Snapshot API 备份到 S3/GCS/FS。推荐 SLM 自动管理。增量快照只存变化。
+
+**Q14: 查询慢如何排查？**
+Profile API → 慢查询日志 → filter vs query → segments 数量 → GC 日志。
+
+**Q15: ILM 能解决什么问题？**
+自动滚动（大小/时间阈值）、自动迁移（热→温→冷）、自动压缩、自动删除。
+
+## Keywords
+
+elasticsearch, ES, 搜索引擎, 全文搜索, 倒排索引, Lucene, index, mapping, document, shard, replica, analyzer, ik, pinyin, 查询 DSL, match, term, bool, filter, range, multi_match, query_string, nested, geo, aggregation, 聚合, terms, date_histogram, avg, sum, cardinality, percentiles, pipeline, reindex, bulk, scroll, search_after, ILM, rollover, force_merge, alias, snapshot, cluster, ELK, Logstash, Kibana, Filebeat, KNN, dense_vector, 向量搜索, painless, ingest pipeline, RBAC, profile API, 慢查询, zero downtime
+
+## References
+
+- references/01-query-dsl-fulltext.md — 全文查询（match/multi_match/query_string）
+- references/02-query-dsl-term.md — 精确查询与复合查询（term/range/bool）
+- references/03-aggregations-metric.md — 指标聚合（avg/sum/stats/cardinality/percentiles）
+- references/04-aggregations-bucket.md — 桶聚合（terms/date_histogram/range）
+- references/05-mapping-types.md — 映射与字段类型详解
+- references/06-analyzers.md — 分词器（标准/IK/pinyin/自定义）
+- references/07-cluster-ops.md — 集群运维（分片/监控/快照/ILM）
+- references/08-elk-integration.md — Logstash/Filebeat/Kibana 配置
+- examples/01-fulltext-search.md — 全文搜索实战
+- examples/02-aggregation-report.md — 聚合报表实战
+- examples/03-reindex-zero-downtime.md — 零停机重建索引
+- examples/04-cluster-monitoring.md — 集群监控实战

package/skills/database/elasticsearch/examples/01-fulltext-search.md

@@ -0,0 +1,215 @@
+# 示例: 全文搜索实战 — 电商商品搜索
+
+## 场景
+
+构建一个电商商品搜索功能，支持关键词搜索、多字段搜索、价格筛选、分页。
+
+## 步骤
+
+### 1. 创建索引与 Mapping
+
+```json
+PUT /products
+{
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 1
+  },
+  "mappings": {
+    "dynamic": "strict",
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "description": {
+        "type": "text",
+        "analyzer": "ik_max_word"
+      },
+      "category": { "type": "keyword" },
+      "brand": { "type": "keyword" },
+      "price": { "type": "float" },
+      "tags": { "type": "keyword" },
+      "status": { "type": "keyword" },
+      "created_at": { "type": "date" },
+      "stock": { "type": "integer" }
+    }
+  }
+}
+```
+
+### 2. 导入示例数据
+
+```bash
+POST /products/_bulk
+{"index":{"_id":1}}
+{"title":"Apple MacBook Pro 16英寸 M3 Pro","description":"Apple M3 Pro芯片, 18GB统一内存, 512GB存储","category":"笔记本","brand":"Apple","price":19999,"tags":["electronics","laptop","apple"],"status":"active","stock":50,"created_at":"2024-01-15T10:30:00Z"}
+{"index":{"_id":2}}
+{"title":"华为 MateBook X Pro 2024","description":"13.9英寸 3K触控屏, 32GB内存, 1TB SSD","category":"笔记本","brand":"华为","price":14999,"tags":["electronics","laptop","huawei"],"status":"active","stock":30,"created_at":"2024-01-20T14:00:00Z"}
+{"index":{"_id":3}}
+{"title":"iPhone 15 Pro Max 256GB","description":"A17 Pro芯片, 4800万像素主摄, 钛金属设计","category":"手机","brand":"Apple","price":9999,"tags":["electronics","phone","apple"],"status":"active","stock":100,"created_at":"2024-02-01T09:00:00Z"}
+{"index":{"_id":4}}
+{"title":"Samsung Galaxy S24 Ultra","description":"Snapdragon 8 Gen 3, 200MP相机, S Pen","category":"手机","brand":"Samsung","price":12999,"tags":["electronics","phone","samsung"],"status":"active","stock":80,"created_at":"2024-02-10T11:00:00Z"}
+{"index":{"_id":5}}
+{"title":"机械革命 极光Pro 游戏本","description":"RTX4060显卡, i7-12650H, 15.6英寸165Hz","category":"笔记本","brand":"机械革命","price":6999,"tags":["electronics","laptop","gaming"],"status":"active","stock":20,"created_at":"2024-03-01T16:00:00Z"}
+{"index":{"_id":6}}
+{"title":"Apple MacBook Air M2","description":"M2芯片, 13.6英寸, 8GB内存, 256GB存储","category":"笔记本","brand":"Apple","price":8999,"tags":["electronics","laptop","apple"],"status":"inactive","stock":0,"created_at":"2023-06-01T10:00:00Z"}
+```
+
+### 3. 基本关键词搜索
+
+```bash
+# 搜索"笔记本" (精确匹配标题)
+GET /products/_search
+{
+  "query": {
+    "match": {
+      "title": "笔记本"
+    }
+  }
+}
+# 返回: MacBook Pro, MateBook X Pro, 极光Pro
+
+# 多字段搜索 (标题+描述)
+GET /products/_search
+{
+  "query": {
+    "multi_match": {
+      "query": "苹果笔记本 M3",
+      "fields": ["title^3", "description"],
+      "type": "best_fields"
+    }
+  }
+}
+# title 权重 3 倍, MacBook Pro 排最前
+```
+
+### 4. 综合搜索 (关键词 + 筛选 + 分页)
+
+```bash
+# 搜索"笔记本", 过滤价格 5000-15000, 只返回 active 商品
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "match": { "title": "笔记本" } }
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "range": { "price": { "gte": 5000, "lte": 15000 } } }
+      ]
+    }
+  },
+  "sort": [
+    { "price": { "order": "asc" } }
+  ],
+  "_source": ["title", "brand", "price", "stock"]
+}
+# 返回: 极光Pro (6999), MacBook Air (8999), MateBook X Pro (14999)
+```
+
+### 5. 搜索建议 (Completion Suggester)
+
+```json
+PUT /products/_mapping
+{
+  "properties": {
+    "title_suggest": {
+      "type": "completion"
+    }
+  }
+}
+
+POST /products/_update/1
+{
+  "doc": {
+    "title_suggest": ["Apple MacBook Pro", "MacBook Pro"]
+  }
+}
+
+POST /products/_update/3
+{
+  "doc": {
+    "title_suggest": ["iPhone 15 Pro Max", "iPhone 15"]
+  }
+}
+
+# 搜索建议
+GET /products/_search
+{
+  "suggest": {
+    "product_suggest": {
+      "prefix": "mac",
+      "completion": {
+        "field": "title_suggest",
+        "size": 5
+      }
+    }
+  }
+}
+# 返回: ["Apple MacBook Pro", "MacBook Pro"]
+```
+
+### 6. 高亮显示
+
+```bash
+GET /products/_search
+{
+  "query": {
+    "match": { "title": "笔记本" }
+  },
+  "highlight": {
+    "fields": {
+      "title": {},
+      "description": {}
+    },
+    "pre_tags": ["<em>"],
+    "post_tags": ["</em>"]
+  }
+}
+# title 中"笔记本"会被 <em> 标签包裹
+```
+
+## 完整搜索 API 示例
+
+```bash
+# 前端搜索框调用的完整 API
+GET /products/_search
+{
+  "query": {
+    "bool": {
+      "must": [
+        { "multi_match": {
+          "query": "笔记本",
+          "fields": ["title^3", "description", "brand"],
+          "type": "best_fields"
+        }}
+      ],
+      "filter": [
+        { "term": { "status": "active" } },
+        { "terms": { "category": ["笔记本", "平板"] }},
+        { "range": { "price": { "gte": 3000, "lte": 20000 } }},
+        { "term": { "brand": "Apple" }}
+      ],
+      "should": [
+        { "term": { "tags": "hot" }},
+        { "term": { "is_new": true }}
+      ]
+    }
+  },
+  "sort": [
+    { "_score": { "order": "desc" }},
+    { "created_at": { "order": "desc" }}
+  ],
+  "from": 0,
+  "size": 20,
+  "_source": ["title", "brand", "price", "stock", "category"],
+  "highlight": {
+    "fields": { "title": { "number_of_fragments": 0 } }
+  }
+}
+```