标准列表查询内核与 QueryShape

// 1. 声明数据源与行投影，锁定全局唯一 QueryShape 标识
[ReadModelQuery<CaseMatter, CaseMatterListRow>("Case.MatterList")]
// 2. 声明默认多级稳定排序规则
[ReadModelSort(nameof(SubmittedOn), Descending = true, Priority = 0)]
[ReadModelSort(nameof(MatterId), Descending = true, Priority = 1)]
public sealed partial class CaseMatterListInput : IDeclareQueryShape
{
    // 3. 声明模糊搜索字段，映射为 SQL Contains 谓词
    [QueryField(SourcePath = nameof(CaseMatter.Title), DefaultOperator = FilterOperator.Contains)]
    public string? SearchText { get; init; }

    // 4. 声明精确匹配状态字段
    [QueryField(SourcePath = nameof(CaseMatter.Status), DefaultOperator = FilterOperator.Equal)]
    public MatterStatus? Status { get; init; }

    // 5. 标准分页参数
    public int PageIndex { get; init; }
    public int PageSize { get; init; }
}

// 危险：强耦合当前查询特定的 Join 顺序与别名 t4
[AdvancedWhere(FieldNames = new[] { "t4", nameof(CaseMatterRelatedParty.OppositeName) })]
public string? OppositeName { get; set; }

// 声明属于主表或关联实体属性，无需关心任何物理 SQL 别名
[QueryField(SourcePath = nameof(CaseMatter.ClientName))]
public string? ClientName { get; init; }

[QueryField(SourcePath = nameof(CaseMatterRelatedParty.OppositeName))]
public string? OppositeName { get; init; }

public async Task<Result<PagedResult<CaseMatterSummaryDto>>> SearchMattersAsync(
    CaseMatterListFields fields,
    PaginationParams paging,
    string currentLawyerId,
    bool includeRestrictedArchive,
    CancellationToken cancellationToken = default)
{
    var input = CaseMatterListInput.From(fields, paging);

    // 针对单源查询：注入强类型单表谓词
    return await input.ExecutePageAsync(
        executorFactory,
        static row => new CaseMatterSummaryDto(row.MatterId, row.Title, row.ClientName, row.Status),
        basePredicate: matter =>
            // 1. 用户所属案件范围隔离
            matter.LeadLawyerId == currentLawyerId
            // 2. 状态机动态逻辑（按权限排除归档案件）
            && (includeRestrictedArchive || matter.Status != MatterStatus.Archived),
        cancellationToken: cancellationToken).ConfigureAwait(false);
}

// 针对双源联查：直接使用双参数 Lambda，享受完全的类型安全
return await joinInput.ExecutePageAsync<CaseMatter, CaseMatterRelatedParty, CaseMatterSummaryDto>(
    joinExecutorFactory,
    static (matter, party) => new CaseMatterSummaryDto(matter.Id, matter.Title, party.OppositeName),
    // 手写跨表业务条件：完全强类型，无需任何 t / t1 别名
    basePredicate: (matter, party) =>
        matter.OfficeId == currentOfficeId
        && (party.IsActive || party.RiskLevel < RiskLevel.High),
    cancellationToken: cancellationToken).ConfigureAwait(false);

using BitzOrcas.Application.Abstractions;
using BitzOrcas.Application.Authorization;
using BitzOrcas.Case.Contracts;
using BitzOrcas.Domain.Abstractions.Queries;
using BitzOrcas.Domain.Results;
using BitzOrcas.Endpoint.Attributes;
using Mediator;

namespace BitzOrcas.Case.Application.Queries;

/// <summary>
/// 案件列表分页检索查询信封
/// </summary>
[GenerateEndpoint(
    HttpRoute.Query,
    "/api/cases/matters",
    Tag = "CaseMatter",
    QueryShapeName = "Case.MatterList")]
public sealed record ListCaseMattersQuery(
    CaseMatterListFields Fields,
    PaginationParams Paging,
    SortRequest? Sort = null) :
    IQuery<Result<PagedResult<CaseMatterSummaryDto>>>,
    IAuthorizedRequest,
    IPaginatedRequest
{
    // 权限元数据绑定
    public ResourceDescriptor Resource { get; } = new(CasePermissions.Module, CasePermissions.MatterResource);
    public AuthorizationAction Action { get; } = AuthorizationAction.Read;
}

/// <summary>
/// 列表入参业务规则校验器 (Tier 1 基础验证)
/// </summary>
public sealed class ListCaseMattersQueryRule : IRequestRule<ListCaseMattersQuery>
{
    public ValueTask<Result> ValidateAsync(ListCaseMattersQuery request, CancellationToken cancellationToken)
    {
        // 校验搜索关键字长度，防止超长文本导致慢查询
        if (request.Fields.SearchText is { Length: > CaseMatterListFields.SearchTextMaxLength })
        {
            return ValueTask.FromResult(Result.Failure(CaseErrors.SearchTextTooLong));
        }

        // 校验分页页码必须大于等于 1
        if (request.Paging.PageIndex < 1)
        {
            return ValueTask.FromResult(Result.Failure(CaseErrors.InvalidPageIndex));
        }

        return ValueTask.FromResult(Result.Success());
    }
}

/// <summary>
/// 案件列表查询处理器
/// </summary>
public sealed class ListCaseMattersQueryHandler(ICaseMatterReadModelStore store)
    : IQueryHandler<ListCaseMattersQuery, Result<PagedResult<CaseMatterSummaryDto>>>
{
    public async ValueTask<Result<PagedResult<CaseMatterSummaryDto>>> Handle(
        ListCaseMattersQuery request,
        CancellationToken cancellationToken)
    {
        // 委托给只读窄端口执行，业务 Handler 不碰任何 ORM
        return await store.SearchAsync(
            request.Fields,
            request.Paging,
            request.Sort,
            cancellationToken).ConfigureAwait(false);
    }
}

using BitzOrcas.Domain.Abstractions.Queries;
using BitzOrcas.Domain.Results;

namespace BitzOrcas.Case.Contracts;

/// <summary>
/// 案件只读检索窄端口（禁止暴露宽仓储或 IQueryable）
/// </summary>
public interface ICaseMatterReadModelStore
{
    Task<Result<PagedResult<CaseMatterSummaryDto>>> SearchAsync(
        CaseMatterListFields fields,
        PaginationParams paging,
        SortRequest? sort,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// 案件筛选字段业务包
/// </summary>
public sealed record CaseMatterListFields(
    string? SearchText = null,
    string? ClientName = null,
    MatterStatus? Status = null,
    DateRange? SubmittedRange = null)
{
    public const int SearchTextMaxLength = 200;
}

/// <summary>
/// 案件列表只读 DTO
/// </summary>
public sealed record CaseMatterSummaryDto(
    string MatterId,
    string SerialId,
    string Title,
    string ClientName,
    MatterStatus Status,
    DateTimeOffset SubmittedOn);

using BitzOrcas.Application.Abstractions.Tenancy;
using BitzOrcas.Case.Contracts;
using BitzOrcas.Case.Domain;
using BitzOrcas.DI.Attributes;
using BitzOrcas.Domain.Abstractions.Queries;
using BitzOrcas.Domain.Results;
using BitzOrcas.Infrastructure.Queries;

namespace BitzOrcas.Case.Infrastructure;

[RegisterPersistenceAdapter<ICaseMatterReadModelStore>]
public sealed class CaseMatterReadModelStore(
    IQueryShapeExecutorFactory executorFactory,
    ICurrentTenant currentTenant) : ICaseMatterReadModelStore
{
    public async Task<Result<PagedResult<CaseMatterSummaryDto>>> SearchAsync(
        CaseMatterListFields fields,
        PaginationParams paging,
        SortRequest? sort,
        CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(fields);
        ArgumentNullException.ThrowIfNull(paging);

        // 验证当前租户上下文
        if (!currentTenant.Tenant.IsAvailable)
        {
            return Result.Failure<PagedResult<CaseMatterSummaryDto>>(CaseErrors.TenantRequired);
        }

        // 1. 在 From 中完成唯一的单点分页归一化
        var input = CaseMatterListInput.From(fields, paging);

        // 2. 执行 QueryShape 投影下推查询，并注入业务基础谓词
        return await input.ExecutePageAsync(
            executorFactory,
            static row => new CaseMatterSummaryDto(
                row.MatterId,
                row.SerialId,
                row.Title,
                row.ClientName,
                row.Status,
                row.SubmittedOn),
            basePredicate: matter => matter.Status != MatterStatus.DeletedDraft,
            sorts: sort.WithTieBreaker(nameof(CaseMatterListInput.MatterId)),
            cancellationToken: cancellationToken).ConfigureAwait(false);
    }
}

/// <summary>
/// 案件列表 QueryShape 声明模型
/// </summary>
[ReadModelQuery<CaseMatter, CaseMatterListRow>("Case.MatterList")]
[ReadModelSort(nameof(SubmittedOn), Descending = true, Priority = 0)]
[ReadModelSort(nameof(MatterId), Descending = true, Priority = 1)]
public sealed partial class CaseMatterListInput : IDeclareQueryShape
{
    public static CaseMatterListInput From(CaseMatterListFields fields, PaginationParams paging)
    {
        // 核心规范：单点安全归一化
        var normalized = paging.Normalize();
        return new CaseMatterListInput
        {
            SearchText = string.IsNullOrWhiteSpace(fields.SearchText) ? null : fields.SearchText.Trim(),
            ClientName = string.IsNullOrWhiteSpace(fields.ClientName) ? null : fields.ClientName.Trim(),
            Status = fields.Status,
            SubmittedFrom = fields.SubmittedRange?.From,
            SubmittedTo = fields.SubmittedRange?.To,
            PageIndex = normalized.PageIndex,
            PageSize = normalized.PageSize,
        };
    }

    [QueryField(SourcePath = nameof(CaseMatter.Title), Default = true, DefaultOperator = FilterOperator.Contains)]
    public string? SearchText { get; init; }

    [QueryField(SourcePath = nameof(CaseMatter.ClientName), DefaultOperator = FilterOperator.Contains)]
    public string? ClientName { get; init; }

    [QueryField(SourcePath = nameof(CaseMatter.Status), DefaultOperator = FilterOperator.Equal)]
    public MatterStatus? Status { get; init; }

    [QueryField(SourcePath = nameof(CaseMatter.SubmittedOn), DefaultOperator = FilterOperator.GreaterThanOrEqual)]
    public DateTimeOffset? SubmittedFrom { get; init; }

    [QueryField(SourcePath = nameof(CaseMatter.SubmittedOn), DefaultOperator = FilterOperator.LessThanOrEqual)]
    public DateTimeOffset? SubmittedTo { get; init; }

    [QueryField(Filterable = false, Visible = false)]
    public DateTimeOffset SubmittedOn { get; init; }

    [QueryField(SourcePath = nameof(CaseMatter.Id), Filterable = false, Visible = false)]
    public string? MatterId { get; init; }

    public int PageIndex { get; init; }
    public int PageSize { get; init; }
}

/// <summary>
/// 纯标量投影行模型（按需生成 SELECT 列表，杜绝宽实体拉取）
/// </summary>
internal sealed record CaseMatterListRow
{
    [ReadModelProjection(nameof(CaseMatter.Id))]
    public string MatterId { get; init; } = string.Empty;

    public string SerialId { get; init; } = string.Empty;

    public string Title { get; init; } = string.Empty;

    public string ClientName { get; init; } = string.Empty;

    public MatterStatus Status { get; init; }

    public DateTimeOffset SubmittedOn { get; init; }
}

using System.Linq.Expressions;
using BitzOrcas.Case.Contracts;
using BitzOrcas.Case.Domain;
using BitzOrcas.Case.Infrastructure;
using BitzOrcas.Domain.Abstractions.Queries;
using BitzOrcas.Infrastructure.Queries;
using Shouldly;
using Xunit;

namespace BitzOrcas.Unit.Tests.Case;

public sealed class CaseMatterQueryShapeTests
{
    [Fact]
    public void CaseMatterListInput_Should_Declare_Accurate_QueryDescriptor_Without_Reflection()
    {
        // 1. 验证编译期生成的 IDeclareQueryShape 描述符
        var descriptor = ((IDeclareQueryShape)new CaseMatterListInput()).QueryDescriptor;
        descriptor.ShouldNotBeNull();
        descriptor.Shape.Name.ShouldBe("Case.MatterList");

        // 2. 验证字段白名单与操作符生成
        var titleField = descriptor.Shape.Fields.FirstOrDefault(f => f.InputField == nameof(CaseMatterListInput.SearchText));
        titleField.ShouldNotBeNull();
        titleField.Allows(FilterOperator.Contains).ShouldBeTrue();

        // 3. 验证强类型访问器直接可用
        var accessor = descriptor.ResolveAccessor("item", nameof(CaseMatter.Title));
        accessor.IsSuccess.ShouldBeTrue();
    }

    [Fact]
    public void BasePredicate_Should_Correctly_Filter_Deleted_Draft_Matters()
    {
        // 验证手写条件 basePredicate 的表达式逻辑
        Expression<Func<CaseMatter, bool>> basePredicate = matter => matter.Status != MatterStatus.DeletedDraft;
        var compiled = basePredicate.Compile();

        var activeMatter = new CaseMatter { Status = MatterStatus.Active };
        var draftMatter = new CaseMatter { Status = MatterStatus.DeletedDraft };

        // 断言业务过滤行为正确
        compiled(activeMatter).ShouldBeTrue();
        compiled(draftMatter).ShouldBeFalse();
    }
}

{
  "fields": {
    "searchText": "知识产权诉讼",
    "status": "Active",
    "submittedRange": {
      "from": "2026-01-01T00:00:00Z",
      "to": "2026-12-31T23:59:59Z"
    }
  },
  "paging": {
    "pageIndex": 1,
    "pageSize": 20
  },
  "sort": {
    "field": "submittedOn",
    "descending": true
  }
}

{
  "isSuccess": true,
  "data": {
    "items": [
      {
        "matterId": "matter-01912a3b-4c5d-7e8f-9a0b-1c2d3e4f5a6b",
        "serialId": "CASE-2026-0889",
        "title": "跨国专利侵权知识产权诉讼一审",
        "clientName": "某高新科技股份有限公司",
        "status": "Active",
        "submittedOn": "2026-08-20T14:30:00Z"
      }
    ],
    "totalCount": 1,
    "pageIndex": 1,
    "pageSize": 20,
    "totalPages": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

public sealed record PaginationParams(
    int PageIndex = 1,
    int PageSize = PagingLimits.DefaultPageSize)
{
    // 执行安全截断与硬边界归一化
    public PaginationParams Normalize()
        => new(
            PagingLimits.NormalizePageIndex(PageIndex),
            PagingLimits.NormalizePageSize(PageSize));
}