搜索建模、Index 与 Mapping：业务模型怎样变成可检索结构
为什么不能把数据库实体原样复制为搜索文档？ 这不是某个 DSL 参数没调好，而是数据身份、索引结构、分布式执行与资源治理没有被放进同一张设计图。搜索索引是可丢弃、可重建的查询投影，不是第二事实源。建模必须从查询、过滤、排序、聚合和更新频率反推文档边界，并用 businessId 与 sourceVersion 保住事实身份。
先守住搜索系统的三个事实
第二，可搜索不等于已提交。text 字段经 analyzer 形成 term 与 postings，keyword 保留完整值，doc values 为排序和聚合提供列式访问。写入经 routing 定位主分片，进入内存缓冲区与 translog，refresh 后形成可搜索 segment；这解释了近实时可见而非事务提交即刻可见。 因而需要分别观测“事实源已提交”“投影事件已消费”“索引已接收”“refresh 后可见”四个水位。只报一个写入成功率，不能证明用户已经能搜到新状态。
一条记录怎样跨过事实、投影和查询边界
投影事件至少携带 businessId、sourceVersion、eventId、occurredAt、schemaGeneration 和 traceId。businessId 回答“这是哪个事实”，sourceVersion 回答“哪个状态更新”，eventId 回答“这次投递是否重复”，generation 回答“写进哪一代结构”。时间戳只能辅助诊断，不能替代单调版本，因为跨进程时钟、补录和重放都可能让到达时间与业务先后顺序分离。
先列字段职责矩阵：检索、精确过滤、排序、聚合、展示、权限、版本。高基数字段是否聚合、数组对象是否要求元素内关联、租户是否需要物理隔离，都要用测量结果决定，而不是依赖默认 dynamic mapping。
动态对象会制造 mapping explosion；nested 会把一个业务文档展开为多条 Lucene 文档；错误 analyzer 无法靠修改配置重写既有 segment；乱序 CDC 若没有外部版本保护，会让旧事件覆盖新状态。
这类错误的危险之处在于，正常样本往往完全正确。只有在动态字段持续增长、事件乱序、深页访问、某个 shard 变慢或迁移追平时，隐藏的复杂度才突然显现。架构验证因此必须制造反向实验，而不是只跑 happy path。
运行链不是黑盒：从入口到 Segment
text 字段经 analyzer 形成 term 与 postings，keyword 保留完整值，doc values 为排序和聚合提供列式访问。写入经 routing 定位主分片，进入内存缓冲区与 translog，refresh 后形成可搜索 segment；这解释了近实时可见而非事务提交即刻可见。
[ Disk_{peak} ge Source imes IndexRatio imes (Primary+Replica) imes GenerationOverlap + MergeReserve ]
公式不提供通用常数。IndexRatio 要由真实 analyzer、mapping 和样本数据测量；GenerationOverlap 取决于迁移策略；MergeReserve 要结合 segment 规模和磁盘水位压测。重要的是让每个放大项可以被观测和复算。
查询放大要在请求进入集群之前计算
[ CandidateAmplification = rac{Shards imes (from + size)}{size} ]
两层失败必须分开处理
可运行模型一：把放大或局部失败变成数字
javac --release 17 -Xlint:all -Werror MappingExplosionDemo.java
java MappingExplosionDemo预期输出：
documents=100 dynamicKeysPerDoc=20 mappedFields=2000 limit=1000 rejected=true flattenedFields=1 safe=true可运行模型二：证明乱序、重放或切换仍收敛
运行 VersionedDocumentDemo.java：
javac --release 17 -Xlint:all -Werror VersionedDocumentDemo.java
java VersionedDocumentDemo预期输出：
businessId=p-17 events=[5, 3, 6] accepted=[5, 6] rejectedStale=1 finalVersion=6 finalStatus=ONLINE第二个模型故意制造反向条件：重复、乱序、并发插入、漏投影或引擎误路由。只要 invariant 依赖“事件总会顺序到达”或“迁移期间不会写入”，它就不是工程约束。可交付的机制必须在反向输入下拒绝旧版本、保持稳定视图、补齐差异或明确降级。
新鲜度不是一个平均延迟
观测必须能回答“哪个边界坏了”
安全、删除与审计不能交给查询约定
脚本查询、正则、通配符、runtime field 和高亮都属于受控能力。它们应按接口白名单开放，设置超时、复杂度和并发预算。让外部调用者提交任意 Query DSL，相当于把集群 CPU、heap 与数据访问边界一起交给客户端。
Schema 演进必须以 generation 为单位
回滚也不能只把 alias 指回旧索引。如果切换后新写入只进入新 generation，旧索引已经落后。可回滚方案要么保持旧代增量同步，要么能根据切换水位重放缺口。所谓“旧索引还在”不等于“旧索引可安全接流”。
架构决策记录应该留下什么
一份可复审的记录至少包含：主查询形状、数据事实源、文档身份、版本规则、字段职责矩阵、分片与 routing 依据、峰值容量测量、查询预算、失败分类、降级语义、迁移状态机、回滚窗口和数据删除路径。每个数字标明样本、压测方法或监控来源。
搜索索引是可丢弃、可重建的查询投影，不是第二事实源。建模必须从查询、过滤、排序、聚合和更新频率反推文档边界，并用 businessId 与 sourceVersion 保住事实身份。 对这个主题，最终必须守住的条件是：字段空间有明确上界，任意乱序写入都不能把索引文档倒退到旧业务版本。如果团队无法通过运行模型、指标和核对账本证明它，就还没有完成架构设计。
查询限制覆盖 shard fan-out、深分页、bucket、脚本、超时、并发和响应体。所有查询、聚合、suggest、导出和缓存路径执行同一权限约束。指标能区分事实水位、消费水位、索引接收与 refresh 可见水位。
新旧索引以版本、缺失主键和摘要核对，不只比较文档数量。降级响应标明来源与新鲜度，不把派生结果冒充权威事实。旧 generation 保留到回滚窗口结束，删除与隐私擦除覆盖全部副本。
两个 Java 17 模型通过严格编译并产生与文中一致的输出。
以下资料用于核对 API 语义和引擎数据结构；架构结论仍需结合实际版本、数据分布与压测结果验证：