AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.AiDOP/Service/S8/Rules/DataAccess/Providers/S8BusinessDatasetDefinitions.cs

namespace Admin.NET.Plugin.AiDOP.Service.S8.Rules.DataAccess.Providers;

/// <summary>
/// S8-RULE01-PURCHASE-DELIVERY-A：业务数据集定义的集中登记处。
///
/// <b>为什么集中一处而不是每个数据集一个 source 类</b>：
/// <see cref="S8DatasetCatalog"/> 对重复 DatasetCode 抛 <c>InvalidOperationException</c>，
/// 而它注册为 <c>AddTransient</c> —— 重复登记的失败形态是「首次解析该服务的那个请求 500」，
/// <b>不是启动崩溃</b>。启动日志干净 ≠ 目录健康。集中在一个数组里，重复项人工一眼可查；
/// 将来新增数据集只加一个元素，不必再改 <c>Startup.cs</c>。
///
/// <b>本类只回答「系统认知中存在哪些数据集、各自能力如何」</b>，不回答「谁供数」——
/// 后者是 <see cref="S8MonitoringDataProviderRegistry"/> 的职责。二者分离才能表达
/// 「数据集已定义、规则可存草稿、但 Provider 未上线因此不可启用」这个必要的中间状态。
/// </summary>
public sealed class S8BusinessDatasetDefinitions : IS8DatasetDefinitionSource
{
    /// <summary>采购交付（订单行级）数据集编码。Provider 与规则的 dataset_code 必须逐字引用本常量。</summary>
    public const string PurchaseDeliveryCode = "PURCHASE_DELIVERY";

    /// <summary>
    /// 采购交付数据集的能力声明。<b>唯一来源</b>：
    /// <see cref="S8PurchaseDeliveryDataProvider"/> 直接引用本字段，不另写一份字面量。
    ///
    /// 目录与 Provider 各写一份会漂移，而漂移只在 <see cref="S8DatasetEnableGate"/> 第 ⑨ 步
    /// （运行期启用时）才被发现，报 <c>dataset_capability_mismatch</c>——那时已经晚了。
    ///
    /// <b>刻意不声明数量类能力</b>（SupportsShortage / HasTargetQty / HasActualQty）：
    /// <c>dwd_supplier_delivery</c> 物理上有 <c>order_qty</c> / <c>remaining_qty</c>，但字段级审计
    /// 已证 <c>remaining_qty</c> 在 781/784 行恒等于 <c>order_qty</c>（收货量在源系统、STD、DWD 三层全断），
    /// 不可作为机制判断依据。Capability 的语义是「当前可可信用于机制判断」，不是「表里有这一列」；
    /// 声明 true 会让 Enable Gate 放行 SHORTAGE 规则，把不可信数据变成可启用能力。
    /// 两列仍随 payload 落盘，仅供排查与后续数据治理观察。
    /// </summary>
    internal static readonly S8DatasetCapabilities PurchaseDeliveryCapabilities = new()
    {
        SupportsTimeout = true,
        SupportsShortage = false,
        SupportsOutOfRange = false,

        HasSourceObjectId = true,
        HasRelatedObjectCode = true,
        HasDueAt = true,
        HasStatus = true,

        HasMeasuredValue = false,
        HasTargetQty = false,
        HasActualQty = false
    };

    public IEnumerable<S8DatasetDefinition> GetDefinitions() => new[]
    {
        new S8DatasetDefinition
        {
            DatasetCode = PurchaseDeliveryCode,
            DisplayName = "采购交付（订单行级）",
            Kind = S8DatasetKind.Object,
            Status = S8DatasetStatus.Defined,
            Capabilities = PurchaseDeliveryCapabilities,
            Description =
                "来源 dwd_supplier_delivery；粒度为采购订单行（po_no + po_line）；" +
                "按 Tenant 最新 stat_date 收敛（factory 不参与本数据集过滤，见 Provider 注释）；" +
                "due_at = COALESCE(need_date, due_date) 为 UAT_EXECUTION_MAPPING，" +
                "业务语义待生产确认，不等同于「正式承诺交期」。"
        }
    };
}