Tutorial: Integrating a Module with Global Search and Index Governance

// Constant in the module's projection helper (Tracker example)
internal const string EntityType = "TrackerItem";

// <Module>.Application/Support/XxxSearchIndexProjection.cs
public static class XxxSearchIndexProjection
{
    internal const string EntityType = "XxxItem"; // verbatim match with host BusinessType

    /// <summary>Publish a Created/Updated snapshot.</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,          // title field: shown on hits
            ["Description"] = item.Description,  // summary/search field
            // Own DataScope owners: the index-side basis for reporter/assignee visibility
            [GlobalSearchStoredFields.OwnerUserId] = item.ReporterId,
            [GlobalSearchStoredFields.OwnerUserIds] = string.Join(
                GlobalSearchStoredFields.MultiValueSeparator, owners)
        };

        return events.PublishAsync(
            new SearchIndexChangedIntegrationEvent(
                GlobalSearchIndexKeys.XxxItems,   // source key
                item.Id,                           // business id (not the storage id)
                item.TenantId,                     // tenant fact comes only from the aggregate
                EntityType,
                action,
                occurredAt.UtcTicks,
                occurredAt,
                JsonSerializer.Serialize(fields)),
            cancellationToken);
    }
}

// Create command (Tracker example: CreateTrackerItem.cs)
var saved = await items.SaveAsync(item, cancellationToken).ConfigureAwait(false);
if (saved.IsFailure)
{
    return Result.Failure<TrackerItemSummaryDto>(saved.Error);
}

collector.Track(item);
// Publish the Search incremental event in the same transaction as the business write,
// so the new document becomes globally searchable immediately after creation.
await TrackerItemSearchIndexProjection.PublishUpsertAsync(
    searchIndexEvents, item, SearchIndexAction.Created, clock.UtcNow, cancellationToken);

// The PersistAsync seam in TrackerItemLifecycle.cs (simplified)
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)
    {
        // Soft delete publishes Deleted: the engine removes the document by storage id
        await searchIndexEvents.PublishAsync(
            new SearchIndexChangedIntegrationEvent(
                GlobalSearchIndexKeys.TrackerItems, item.Id, item.TenantId,
                TrackerItemSearchIndexProjection.EntityType,
                SearchIndexAction.Deleted, clock.UtcNow.UtcTicks, clock.UtcNow, "{}"),
            ct);
    }
    else
    {
        // Edits (subject/description), assignments (owner fields) all refresh the snapshot here
        await TrackerItemSearchIndexProjection.PublishUpsertAsync(
            searchIndexEvents, item, SearchIndexAction.Updated, clock.UtcNow, ct);
    }
    return Result.Success();
}

// Contracts: port method (Tracker example: ITrackerItemReadModelStore)
Task<Result<IReadOnlyList<TrackerItemSearchIndexRecord>>> ListForSearchIndexAsync(
    BatchReadRequest batch, CancellationToken cancellationToken);

// Contracts: batch row record (index fields only)
public sealed record TrackerItemSearchIndexRecord(
    string ItemId, string Subject, string Description,
    string ReporterId, string? AssigneeId);

// <Module>.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)
        {
            // An unavailable read model must fail closed: silently returning an empty batch
            // would make the governance page believe "0 documents, done"
            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),               // fields fully isomorphic with the projection!
                (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
{
    // Must equal the host-configured IndexKey; the catalog routes re-checks by this key
    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;
        }

        // Re-read authoritative data + unified authorization; never trust index fields
        var item = await items.FindAsync(context.BusinessId, ct).ConfigureAwait(false);
        return item.IsSuccess
            && (await authorization.EnsureCanViewAsync(user, item.GetValueOrThrow(), ct)).IsSuccess;
    }
}