实战：业务模块接入全局搜索与索引治理

// 模块内投影助手中的常量（Tracker 范例）
internal const string EntityType = "TrackerItem";

// <模块>.Application/Support/XxxSearchIndexProjection.cs
public static class XxxSearchIndexProjection
{
    internal const string EntityType = "XxxItem"; // 与宿主配置 BusinessType 逐字一致

    /// <summary>发布创建/更新快照（Created/Updated）</summary>
    public static Task PublishUpsertAsync(
        IIntegrationEventPublisher<SearchIndexChangedIntegrationEvent> events,
        XxxItem item,
        SearchIndexAction action,
        DateTimeOffset occurredAt,
        CancellationToken cancellationToken)
    {
        var owners = new[] { item.ReporterId, item.AssigneeId }
            .Where(owner => !string.IsNullOrWhiteSpace(owner))
            .Distinct(StringComparer.Ordinal)
            .ToArray();

        var fields = new Dictionary<string, string?>(StringComparer.Ordinal)
        {
            ["Subject"] = item.Subject,          // 标题字段：命中后展示
            ["Description"] = item.Description,  // 摘要/检索字段
            // Own DataScope 所有者：报告人/经办人可见性的索引侧依据
            [GlobalSearchStoredFields.OwnerUserId] = item.ReporterId,
            [GlobalSearchStoredFields.OwnerUserIds] = string.Join(
                GlobalSearchStoredFields.MultiValueSeparator, owners)
        };

        return events.PublishAsync(
            new SearchIndexChangedIntegrationEvent(
                GlobalSearchIndexKeys.XxxItems,   // 来源键
                item.Id,                           // 业务主键（非存储 Id）
                item.TenantId,                     // 租户事实只来自聚合
                EntityType,
                action,
                occurredAt.UtcTicks,
                occurredAt,
                JsonSerializer.Serialize(fields)),
            cancellationToken);
    }
}

// 创建命令（Tracker 范例：CreateTrackerItem.cs）
var saved = await items.SaveAsync(item, cancellationToken).ConfigureAwait(false);
if (saved.IsFailure)
{
    return Result.Failure<TrackerItemSummaryDto>(saved.Error);
}

collector.Track(item);
// 与业务写同事务发布 Search 增量索引事件，保证新文档创建后立即可被全局搜索命中。
await TrackerItemSearchIndexProjection.PublishUpsertAsync(
    searchIndexEvents, item, SearchIndexAction.Created, clock.UtcNow, cancellationToken);

// TrackerItemLifecycle.cs 的 PersistAsync 接缝（简化）
private async Task<Result> PersistAsync(TrackerItem item, Result mutation, CancellationToken ct)
{
    if (mutation.IsFailure) return mutation;
    var saved = await items.SaveAsync(item, ct).ConfigureAwait(false);
    if (saved.IsFailure) return saved;

    collector.Track(item);
    if (item.IsDeleted)
    {
        // 软删除发布 Deleted 动作：引擎按存储 Id 移除文档
        await searchIndexEvents.PublishAsync(
            new SearchIndexChangedIntegrationEvent(
                GlobalSearchIndexKeys.TrackerItems, item.Id, item.TenantId,
                TrackerItemSearchIndexProjection.EntityType,
                SearchIndexAction.Deleted, clock.UtcNow.UtcTicks, clock.UtcNow, "{}"),
            ct);
    }
    else
    {
        // 编辑（主题/描述）、指派（所有者字段）等都经此刷新快照
        await TrackerItemSearchIndexProjection.PublishUpsertAsync(
            searchIndexEvents, item, SearchIndexAction.Updated, clock.UtcNow, ct);
    }
    return Result.Success();
}

// Contracts：端口方法（Tracker 范例：ITrackerItemReadModelStore）
Task<Result<IReadOnlyList<TrackerItemSearchIndexRecord>>> ListForSearchIndexAsync(
    BatchReadRequest batch, CancellationToken cancellationToken);

// Contracts：批次行记录（只含索引字段）
public sealed record TrackerItemSearchIndexRecord(
    string ItemId, string Subject, string Description,
    string ReporterId, string? AssigneeId);

// <模块>.Application/Support/XxxSearchIndexRebuildSource.cs
[RegisterScopedEnumerable<ISearchIndexRebuildSource>]]
public sealed class XxxSearchIndexRebuildSource(IXxxReadModelStore readModels)
    : ISearchIndexRebuildSource
{
    private const string EntityType = "XxxItem";

    public string IndexKey => GlobalSearchIndexKeys.XxxItems;

    public async Task<IReadOnlyList<SearchIndexRebuildDocument>> GetBatchAsync(
        string tenantId, string? lastCursor, int pageSize, CancellationToken ct)
    {
        var offset = ParseCursor(lastCursor);
        var recordsResult = await readModels.ListForSearchIndexAsync(
            new BatchReadRequest(offset, pageSize), ct).ConfigureAwait(false);
        if (recordsResult.IsFailure)
        {
            // 读模型不可用必须失败关闭：静默返回空批次会让治理页误判"0 文档已完成"
            throw new InvalidOperationException(
                $"Xxx search rebuild source is unavailable: {recordsResult.Error.Code}.");
        }

        return recordsResult.GetValueOrThrow()
            .Select((record, index) => new SearchIndexRebuildDocument(
                record.ItemId,
                EntityType,
                BuildFields(record),               // 字段与增量投影完全同构！
                (offset + index + 1).ToString(CultureInfo.InvariantCulture)))
            .ToArray();
    }

    private static int ParseCursor(string? cursor)
        => int.TryParse(cursor, NumberStyles.None, CultureInfo.InvariantCulture, out var v) && v >= 0
            ? v
            : throw new InvalidOperationException("Xxx search rebuild cursor is invalid.");
}

{
  "IndexKey": "tracker.item",
  "DisplayName": "工单",
  "Module": "tickets",
  "ResourceType": "ticket",
  "BusinessType": "TrackerItem",
  "NavigationTemplate": "/tickets/{id}",
  "TitleField": "Subject",
  "SubtitleField": "Description",
  "RequiresAuthoritativeAccessEvaluation": true,
  "SearchFields": ["Subject", "Description"]
}

[RegisterScopedEnumerable<IGlobalSearchHitAccessEvaluator>]]
public sealed class XxxGlobalSearchAccessEvaluator(
    IXxxRepository items,
    XxxAuthorizationService authorization,
    ICurrentUser currentUser): IGlobalSearchHitAccessEvaluator
{
    // 必须与宿主配置 IndexKey 一致，目录据此路由复核
    public string SourceKey => GlobalSearchIndexKeys.XxxItems;

    public async ValueTask<bool> IsAllowedAsync(
        GlobalSearchHitAccessContext context, CancellationToken ct)
    {
        var user = currentUser.User;
        if (!string.Equals(context.SourceKey, SourceKey, StringComparison.Ordinal)
            || !string.Equals(context.TenantId, user.TenantId, StringComparison.Ordinal))
        {
            return false;
        }

        // 回源权威数据 + 统一授权决策，绝不信任索引字段
        var item = await items.FindAsync(context.BusinessId, ct).ConfigureAwait(false);
        return item.IsSuccess
            && (await authorization.EnsureCanViewAsync(user, item.GetValueOrThrow(), ct)).IsSuccess;
    }
}