本文引用的文件
搜索模块 search 是后端全文检索能力,提供文档索引、增量写入、查询服务和启动初始化器。它通过 Elasticsearch 对清洗后的案件数据、Agent 附件内容、知识库片段等文本进行加速检索,替代了早期基于嵌入式 Lucene 的实现。
该模块的核心职责包括:
zsjz_search 的 Elasticsearch 索引。/search/list,返回前端可直接渲染的高亮内容。需要明确的是:当前搜索模块仅使用传统全文索引(text + wildcard),没有集成向量检索。 向量检索由知识文档和清洗模板等其他模块单独处理,不应与本模块混为一谈。
章节来源
搜索模块位于 ai-server 的 Java 包下,采用领域对象、仓库、服务、控制器分层组织:
graph TB
subgraph "搜索模块"
domain["领域模型<br/>SearchDoc"]
repo["仓库接口<br/>SearchDocRepository"]
initializer["启动初始化器<br/>SearchIndexInitializer"]
indexService["写入服务<br/>SearchDocIndexService"]
queryService["查询服务<br/>SearchQueryService"]
controller["对外控制器<br/>SearchController"]
dto["查询结果 DTO<br/>SearchDTO"]
settings["ES 分词配置<br/>search-settings.json"]
end
controller --> queryService
queryService --> repo
queryService --> settings
indexService --> repo
indexService --> settings
initializer --> indexService
domain --> repo
图表来源
章节来源
| 组件 | 职责 | 关键行为 |
|---|---|---|
SearchDoc |
全文检索文档领域模型 | 定义 zsjz_search 索引字段、分词字段、业务标识、时间戳、文件名、工作表名等 |
SearchDocRepository |
Spring Data Elasticsearch 仓库 | 暴露批量保存方法,内部走 ES _bulk |
SearchDocIndexService |
索引写入与容错 | 按案件攒批、批量提交、刷新、按文件/案件删除、ES 熔断 |
SearchQueryService |
查询与高亮 | 关键词 wildcard 匹配、caseId 过滤、高亮片段拼接、时间倒序、最多 500 条 |
SearchIndexInitializer |
应用启动时创建索引 | 幂等创建,ES 不可用只记日志 |
SearchController |
REST 入口 | GET /search/list,接收关键词并返回搜索结果 |
SearchDTO |
查询结果传输对象 | 包含行 id、文件信息、表名、时间、高亮内容 |
search-settings.json |
ES 分词器配置 | 使用 pattern 分词器按 \x1F 切分,再转小写 |
章节来源
搜索模块以 Spring Boot 服务形式运行,对外暴露 HTTP 接口,对内通过 Spring Data Elasticsearch 访问 Elasticsearch。
sequenceDiagram
participant FE as "前端或调用方"
participant Controller as "SearchController"
participant Query as "SearchQueryService"
participant Repo as "SearchDocRepository"
participant ES as "Elasticsearch"
FE->>Controller: "GET /search/list?keyword=xxx"
Controller->>Query: "search(keyword)"
Query->>Query: "解析案件上下文 caseId"
Query->>Repo: "NativeQuery wildcard 匹配 content"
Repo->>ES: "执行搜索"
ES-->>Repo: "返回命中文档"
Repo-->>Query: "SearchHit"
Query->>Query: "高亮 content 片段"
Query-->>Controller: "List<SearchDTO>"
Controller-->>FE: "Result<List<SearchDTO>>"
图表来源
SearchDoc 是全文检索文档的唯一实体。它直接映射到 Elasticsearch 中的 zsjz_search 索引。
关键字段含义如下:
| 字段 | 类型 | 用途 |
|---|---|---|
| docId | keyword | ES 文档 _id,格式为 caseId|tableName|rowId,保证同表同记录幂等覆盖 |
| caseId | keyword | 案件隔离字段,所有写入和删除必须带此条件 |
| rowId | keyword | 原始业务行主键,不能命名为 id,否则与 Spring Data 的 @Id 冲突 |
| sheetId | keyword | 工作表标识 |
| fileId | keyword | 上传文件标识 |
| tableName | keyword | 源数据表名 |
| fileName | keyword | 源文件名 |
| sheetName | keyword | 工作表名称 |
| dateTime | date | 业务时间,用于排序和展示 |
| content | text | 全字段拼接文本,使用自定义分词器 unit_separator |
content 字段的设计非常关键:它不是普通自然语言文本,而是把多个实体的字符串表示用分隔符 \x1F 拼接后存储。ES 分词器会按该分隔符切分,再做小写处理。查询时对 token 做 wildcard 子串匹配,因此语义上更接近“按片段模糊匹配”,而不是完整的中文语义检索。
classDiagram
class SearchDoc {
+string docId
+string caseId
+string rowId
+string sheetId
+string fileId
+string tableName
+string fileName
+string sheetName
+LocalDateTime dateTime
+string content
}
图表来源
章节来源
写入服务负责索引构建、批量提交、刷新、删除和容错。它是整个搜索模块中最复杂、也最重要的组件。
flowchart TD
Start(["add(doc)"]) --> RequireCase["校验案件上下文"]
RequireCase --> SetFields["设置 caseId 和 docId"]
SetFields --> BreakerCheck{"是否处于熔断期"}
BreakerCheck -->|是| Drop["丢弃并累计计数"]
BreakerCheck -->|否| Buffer["按 caseId 攒批"]
Buffer --> BatchFull{"是否达到批次大小"}
BatchFull -->|是| SaveBatch["saveAll 批量提交"]
BatchFull -->|否| EndAdd(["返回"])
SaveBatch --> Success{"是否成功"}
Success -->|是| RecordSuccess["重置失败计数"]
Success -->|否| RecordFailure["记录失败并可能熔断"]
RecordSuccess --> EndAdd
RecordFailure --> EndAdd
图表来源
关键设计点:
docId = caseId|tableName|rowId,重复清洗不会产生重复文档。flush() 会提交尾批并对索引执行 refresh,使新数据立即可被搜索。add() 直接跳过,不再承受 ES 超时。旁路容错:ES 异常不会上抛给清洗主链路,只会记录日志并累计丢弃数量。
flowchart TD
FStart(["ES 写入失败"]) --> IncFail["连续失败批数加一"]
IncFail --> CheckThreshold{"是否达到阈值"}
CheckThreshold -->|否| LogWarn["记录失败日志"]
CheckThreshold -->|是| OpenBreaker["打开熔断截止时间"]
LogWarn --> FEnd(["返回"])
OpenBreaker --> FEnd
图表来源
SearchIndexInitializer 实现 ApplicationRunner,在应用启动时调用 ensureIndex()。如果 ES 不可用,只记录错误日志,不阻断应用启动;首次写入时会再次尝试创建索引。
章节来源
查询服务提供关键词搜索、高亮和排序能力。
核心规则:
caseId,否则跳过检索。*keyword* 匹配 content 字段。caseId filter,防止跨案件泄漏。dateTime 降序排序。content 字段进行高亮,使用 <em class="search-highlight"> 标签包裹。高亮片段超过限制时用 ... 拼接。
sequenceDiagram
participant Svc as "SearchQueryService"
participant Ctx as "CaseContextHolder"
participant Ops as "ElasticsearchOperations"
Svc->>Svc: "检查 keyword 是否为空"
Svc->>Ctx: "获取 caseId"
Svc->>Svc: "构造 wildcard 查询"
Svc->>Ops: "执行 NativeQuery"
Ops-->>Svc: "SearchHit 列表"
Svc->>Svc: "高亮 content 片段"
Svc-->>Svc: "转换为 SearchDTO"
图表来源
章节来源
控制器暴露单一接口:
| 方法 | 路径 | 参数 | 返回值 |
|---|---|---|---|
| GET | /search/list |
keyword |
Result<List<SearchDTO>> |
该接口没有分页参数,也没有独立的权重字段控制。分页和更多筛选应放在调用方或上层业务中处理。
章节来源
ES 索引配置定义了一个自定义分词器:
\x1F。这意味着 content 字段不是按中文词语分词,而是按业务约定的分隔符拆成片段,然后统一小写。搜索时也是对这些片段做通配匹配。
flowchart TD
Input["原始 content<br/>多字段用 \\x1F 拼接"] --> Tokenizer["pattern 分词器<br/>按 \\x1F 切分"]
Tokenizer --> Lower["lowercase 过滤器"]
Lower --> Tokens["token 列表"]
Tokens --> Wildcard["wildcard *keyword* 匹配"]
图表来源
章节来源
搜索模块依赖以下外部或跨模块能力:
注意:搜索模块本身不依赖向量检索相关代码。项目中还存在其他模块(如知识文档、清洗模板)使用 pgvector 或向量索引,但它们与 search 模块是独立实现的。
graph LR
SearchModule["搜索模块 search"] --> ES["Elasticsearch"]
SearchModule --> SpringDataES["Spring Data Elasticsearch"]
SearchModule --> CaseContext["CaseContextHolder"]
SearchModule --> SpringBoot["Spring Boot"]
OtherVector["其他模块向量检索<br/>pgvector/向量索引"] -. 不共用 .-> SearchModule
图表来源
章节来源
| 维度 | 当前实现 | 说明 |
|---|---|---|
| 索引结构 | 单索引 zsjz_search |
所有案件共享同一索引,靠 caseId 隔离 |
| 分词方式 | pattern 按 \x1F 切分 + lowercase |
不是标准中文分词器,也不是向量语义检索 |
| 查询方式 | wildcard 模糊匹配 | 适合片段查找,不适合复杂布尔语法 |
| 排序 | 按 dateTime 降序 |
未提供多字段排序 |
| 分页 | 硬编码最大 500 条 | 不支持页码、每页大小 |
| 写入批量 | 1000 条/批 | 按案件缓冲,满批触发 _bulk |
| 刷新 | flush 时 refresh | 增量清洗完成后使数据可搜 |
| 容错 | 连续 3 批失败熔断约 60 秒 | 清洗主链路不受影响 |
| 并发安全 | ConcurrentHashMap + buffer synchronized | 多虚拟线程写同一案件时同步缓存 |
优化建议:
content 约定是 \x1F 分隔的业务片段。SearchDoc 扩展字段并在查询中增加 filter,但需注意这会改变现有契约。章节来源
调用方发送请求:
/search/listkeyword后端行为:
CaseContextHolder 读取案件 ID。content 字段执行 wildcard 查询。caseId 过滤。dateTime 降序返回最多 500 条。content 进行高亮,返回 SearchDTO。注意事项:
章节来源
搜索已经内置案件隔离:
caseId。caseId filter。caseId 清理。这意味着调用方无法绕过案件隔离进行搜索。这是重要的安全边界。
章节来源
当前 SearchDoc 没有用户字段,SearchController 也没有用户过滤参数。若需要按用户维度过滤,推荐做法:
SearchDoc 新增用户标识字段。SearchQueryService 增加用户过滤参数。当前版本不建议在查询层直接通过 tableName、fileId 等方式模拟用户维度,因为这不是设计意图。
章节来源
高亮逻辑:
content。<em class="search-highlight">。</em>。content。前端可直接渲染 HTML 片段,无需自行高亮。
章节来源
典型场景:
SearchDoc。SearchDocIndexService.add() 按案件攒批。saveAll。flush(),提交尾批并 refresh。如果清洗过程中 ES 失败:
add() 丢弃文档但不抛异常。章节来源
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 搜索无结果 | 没有案件上下文 | 确认调用链绑定了 CaseContextHolder |
| 搜索无结果 | 关键词为空 | 前端不要发送空关键词 |
| 搜索无结果 | ES 尚未创建索引 | 检查启动日志和首次写入日志 |
| 写入很慢 | ES 连接超时或慢查询 | 查看 ES 健康状态和集群负载 |
| 清洗链路变慢 | ES 持续失败导致频繁重试 | 检查熔断日志,确认是否进入熔断期 |
| 数据不一致 | flush 前 ES 失败 | 使用按案件重建索引补偿 |
| 搜索结果过多 | wildcard 匹配过宽 | 缩小关键词或在上层增加过滤条件 |
| 高亮样式异常 | 前端未渲染 HTML | 确认前端使用富文本渲染高亮字段 |
重要容错原则:
章节来源
搜索模块 search 是一个围绕 Elasticsearch 的传统全文检索子系统。它通过统一文档模型、案件隔离、批量写入、刷新和高亮能力,为案件数据、Agent 内容和清洗结果提供关键词检索。其核心优势在于:
caseId 作为强制隔离条件。需要注意的限制:
在 Agent RAG 集成方面,应将本模块与向量检索模块区分开:本模块适合“快速定位业务片段”,向量检索适合“语义相似召回”。两者可以互补,但不应混用同一个索引或同一个查询语义。