Bitzsoft.Integrations.Search 1.0.0-alpha.10

Bitzsoft.Integrations.Search

全文检索引擎抽象层 — 统一接口定义、三段式检索上下文、业务规则矩阵与弱词过滤抽象。

功能特性

• 引擎核心抽象：ISearchEngine 覆盖索引全生命周期（实时 Upsert/Delete、keyset 分页全量 Rebuild、三段式 Search、GetStatistics）
• 全量重建数据源：ISearchIndexDataSource 采用 keyset（游标式）分页迭代，避免深分页 O(n) 性能退化
• 三段式检索上下文：SearchPerformInput 将 Query / Filter / Rule 职责分离，一套模型支持利冲审查、列表过滤、关键字检索等多场景
• 业务规则矩阵：BusinessRuleScopeBuilder 按「场景 × 关键词角色」生成二维约束（关键字允许命中的利冲方类型 / 允许搜索的字段），内置 6 种 SearchScenario
• 分级关键词匹配：KeywordMatchStrategy 按关键词数量自动切换算法（SmallSet / MediumSet / LargeSet / CachedTrie），>=500 使用 AhoCorasick 双数组 Trie + SHA256 缓存
• 结果聚合管道：SearchPipeline 基于 Channel + ConcurrentDictionary 按 (BusinessId, BusinessType) 聚合命中项，背压有界（容量 10000）
• 命中等级计算：HitLevelCalculator 按我方/对方/第三方角色分组计算红(3)/黄(2)/绿(1)/无(0) 四级冲突
• 弱词过滤抽象：ISegmentWordStore（LegalSuffix 实体法定后缀 / OrgWeak 弱组织词 / GeoWeak 弱地理词）、IStopWordProvider、IExtensionWordProvider
• 索引目录存储抽象：ISearchIndexCatalogStore 管理多场景索引元数据（DirectoryName / 状态 / 版本 / 文档数），连接器包零 DB 依赖由宿主实现持久化

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Search

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Search" Version="1.0.0" />

配置

本包为纯抽象层，不读取任何配置节点。宿主项目通过实现下述抽象接口提供运行时数据：

注册服务

本包仅定义抽象契约，不提供 DI 注册扩展方法。宿主项目需配合具体实现包（如 Bitzsoft.Integrations.Search.Lucene）注册引擎，并自行注册上述存储抽象的实现：

// 1. 注册 Lucene 引擎实现
services.AddBitzsoftLuceneSearch(opt => opt.BasePath = "/data/lucene");

// 2. 注册宿主实现的存储抽象
services.AddScoped<ISearchIndexCatalogStore, MyCatalogStore>();
services.AddScoped<ISegmentWordStore, MySegmentWordStore>();
services.AddScoped<IStopWordProvider, MyStopWordProvider>();

使用示例

实现全量重建数据源

using Bitzsoft.Integrations.Search;

public sealed class CaseConflictDataSource : ISearchIndexDataSource
{
    public async Task<IReadOnlyList<IndexDocumentBatch>> GetBatchAsync(
        string tenantId, string? lastCursor, int pageSize,
        CancellationToken cancellationToken = default)
    {
        // keyset 分页：按 Id 游标推进，避免深分页性能退化
        var rows = await _db.Cases
            .Where(c => c.TenantId == tenantId && c.Id.CompareTo(lastCursor) > 0)
            .OrderBy(c => c.Id)
            .Take(pageSize)
            .ToListAsync(cancellationToken);

        return rows.Select(c => new IndexDocumentBatch(
            c.Id.ToString(),
            new Dictionary<string, string?>
            {
                ["Name"] = c.Name,
                ["ForeignName"] = c.ForeignName,
                ["FormerName"] = c.FormerName,
                ["ConflictKeyword"] = c.Keyword
            },
            c.Id.ToString())).ToList();
    }
}

调用引擎写入与检索

using Bitzsoft.Integrations.Search;

public sealed class SearchService(ISearchEngine engine)
{
    // 实时增量写入
    public Task UpsertAsync(string caseId, string name, string tenantId, CancellationToken ct)
        => engine.UpsertAsync(
            indexKey: "conflict",
            tenantId: tenantId,
            documentId: caseId,
            fields: new Dictionary<string, string?>
            {
                ["Name"] = name,
                ["EntityType"] = "CaseMatter"
            },
            cancellationToken: ct);

    // 全量重建（原子替换，不中断检索服务）
    public Task<RebuildResult> RebuildAsync(ISearchIndexDataSource dataSource, string tenantId,
        CancellationToken ct) => engine.RebuildAsync("conflict", tenantId, dataSource, ct);

    // 三段式检索（利冲审查）
    public async Task<IReadOnlyList<SearchHitItem>> SearchConflictsAsync(
        string tenantId, string keyword, CancellationToken ct)
    {
        var input = new SearchPerformInput
        {
            IndexKey = "conflict",
            TenantId = tenantId,
            BusinessName = "ConflictCheck",
            Query = new SearchQueryContext
            {
                SearchFieldWordsDict = new()
                {
                    ["Name"] = new() { keyword },
                    ["FormerName"] = new() { keyword }
                },
                Mode = SearchMode.Fuzzy,
                MultiFieldCombineMode = FieldCombineMode.Should
            },
            Filter = new SearchFilterContext { ExcludeSourceBusinessId = true },
            Rule = new SearchRuleContext
            {
                Scenario = SearchScenario.ProcessRoleOpposing,
                Categories = new PartyCategories
                {
                    OurPartyCategories = { "Client" },
                    OppositePartyCategories = { "Opponent" },
                    ThirdPartyCategories = { "ThirdParty" }
                }
            }
        };

        var output = await engine.SearchAsync(input, ct);
        return output.Hits; // 已按 HitLevel 降序、按 BusinessId 聚合
    }
}

构建业务规则约束矩阵

// 根据场景 × 角色，生成每个关键字允许命中的利冲方类型与字段
var scope = BusinessRuleScopeBuilder.Build(
    scenario: SearchScenario.PreProcessRoleOpposing,
    categoryKeywordMap: new() { ["Client"] = new() { "张三" } },
    categories: new PartyCategories
    {
        OurPartyCategories = { "Client" },
        OppositePartyCategories = { "Opponent" }
    });

// scope.KeywordCategoryScopeMap：关键字 → 允许命中的利冲方类型
// scope.KeywordFieldScopeMap：关键字 → 允许搜索的字段

关键词匹配策略（离线/预检场景）

// 按关键词数量自动选择 SmallSet / MediumSet / LargeSet / CachedTrie
var strategy = KeywordMatchStrategy.Create(
    searchFieldWordsDict: new() { ["Name"] = new() { "张三", "李四" } },
    mode: SearchMode.Fuzzy);

var hits = strategy.Match(new() { ["Name"] = "张三的合同" });
// hits: (Keyword=张三, Field=Name) → "张三的合同"

核心类型一览

依赖

相关包

• Bitzsoft.Integrations.Search.Lucene -- Lucene.NET 全文检索引擎实现（拼音分词、NGram、索引生命周期、三段式检索编排）