AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.AiDOP/DataPlatform/S0Dim/S0DimCatalog.cs

namespace Admin.NET.Plugin.AiDOP.DataPlatform.S0Dim;

/// <summary>
/// S0 主数据维度清单 —— **本模块唯一的业务知识落点**。
///
/// 新增一个维度 = 在此追加一个 <see cref="S0DimDefinition"/>，
/// 不得在 Materializer / Reconciler 中出现按 Key 分支的逻辑。
///
/// 🔴 JsonPath 一律是**源表物理列名**，不是实体属性名。改动前先核对 <c>SHOW CREATE TABLE</c>。
/// </summary>
public static class S0DimCatalog
{
    /// <summary>本库样板源（<c>mdp_source.source_code</c>），入站为只读 SELECT。</summary>
    public const string LocalSourceSystem = "AIDOPDEV_MYSQL";

    /// <summary>
    /// 工作中心。源 <c>WorkCtrMaster</c>（无 company/factory 列，故 dim 也不设 —— 不为统一而发明数据）。
    /// </summary>
    public static readonly S0DimDefinition WorkCenter = new(
        Key: "WORK_CENTER",
        EntityCode: "S0_WORK_CENTER",
        SourceTable: "WorkCtrMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_work_center",
        DimTable: "dim_work_center",
        BusinessKeyColumns: ["tenant_id", "domain_code", "work_center_code"],
        SourceBizKeyColumns: ["Domain", "WorkCtr"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("domain_code",       S0DimValueKind.Str,         "Domain",     Required: true),
            new("work_center_code",  S0DimValueKind.Str,         "WorkCtr",    Required: true),
            new("work_center_name",  S0DimValueKind.Str,         "Descr"),
            new("department_code",   S0DimValueKind.Str,         "Department"),
            new("is_active",         S0DimValueKind.BoolTrue,    "IsActive"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 部门。源 <c>DepartmentMaster</c>。
    /// company/factory 仅作属性透传：实测同一 (tenant, Domain) 下 factory 同时存在 legacy 数值与 SysOrg 雪花两种值，
    /// 与身份正交，本阶段不做组织域治理。
    /// </summary>
    public static readonly S0DimDefinition Department = new(
        Key: "DEPARTMENT",
        EntityCode: "S0_DEPARTMENT",
        SourceTable: "DepartmentMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_department",
        DimTable: "dim_department",
        BusinessKeyColumns: ["tenant_id", "domain_code", "department_code"],
        SourceBizKeyColumns: ["Domain", "Department"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("domain_code",       S0DimValueKind.Str,         "Domain",         Required: true),
            new("department_code",   S0DimValueKind.Str,         "Department",     Required: true),
            new("department_name",   S0DimValueKind.Str,         "Descr"),
            new("is_active",         S0DimValueKind.BoolTrue,    "IsActive"),
            // 源侧 238/239 非空：UATDEMO 的「未分配」行 UpdateTime 恒 NULL。
            // 本 definition 走 FULL（mdp_entity.incr_column = NULL），不生成 "UpdateTime > cursor" 谓词，
            // 因此该行每轮都能进 stg 与 dim；切 INCR 前必须先落 keyset NullTimePhase 两阶段。
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 库位。源 <c>LocationMaster</c> —— **dual-column 复刻表**。
    ///
    /// 🔴 以下 JsonPath 全部是 PascalCase 真列，同表存在同名 snake_case 影子列且**恒空/已发散**，
    /// 取错即静默得到空值：
    /// <c>Domain</c>(真) vs <c>domain_code</c>(132 行全空串) ·
    /// <c>IsActive</c>(真) vs <c>is_active</c>(132 行中仅 1 行与真列相等) ·
    /// <c>PhysicalAddress</c>(42 非空) vs <c>physical_address</c>(0 非空) ·
    /// <c>CreateUser</c>(119 非空) vs <c>create_user</c>(0 非空) ·
    /// <c>RecID</c>(真主键) vs <c>rec_id</c>(恒 0)。
    ///
    /// 身份取 (tenant, domain_code, location_code)：与子表父引用一致，且在源侧索引口径变化时仍成立；
    /// 另用 <see cref="S0DimDefinition.MirrorUniqueColumns"/> 镜像当前源 UK (tenant_id, location)。
    /// </summary>
    public static readonly S0DimDefinition Location = new(
        Key: "LOCATION",
        EntityCode: "S0_LOCATION",
        SourceTable: "LocationMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_location",
        DimTable: "dim_location",
        BusinessKeyColumns: ["tenant_id", "domain_code", "location_code"],
        SourceBizKeyColumns: ["Domain", "location"],
        MirrorUniqueColumns: ["tenant_id", "location_code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id",  Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id",  Required: true),
            new("domain_code",       S0DimValueKind.Str,         "Domain",          Required: true),
            new("location_code",     S0DimValueKind.Str,         "location",        Required: true),
            new("location_name",     S0DimValueKind.Str,         "descr"),
            new("location_type",     S0DimValueKind.Str,         "typed"),
            new("storer",            S0DimValueKind.Str,         "storer"),
            new("physical_address",  S0DimValueKind.Str,         "PhysicalAddress"),
            new("is_active",         S0DimValueKind.BoolTrue,    "IsActive"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 货架（库位子维度）。源 <c>LocationShelfMaster</c>。
    ///
    /// 与 <see cref="Location"/> 共用 <c>mdp_stg_s0_location</c>，靠 <c>source_table</c> 隔离，
    /// 两者是**两个独立 definition**，绝不合并成一次转换。
    ///
    /// 本表**全列 snake_case，没有影子列** —— 不可套用 LocationMaster 的禁用规则。
    /// 另：源 <c>update_time</c> 0/30 非空（无水位）、主键 <c>rec_id</c> 不在通用行标识候选列表中
    /// 且每次父表 FULL Replace 都会变，故物化只认 <c>sync_batch_id</c>，不依赖 source_row_id 稳定性。
    /// 无 is_active —— 源表没有该列，不发明。
    /// </summary>
    public static readonly S0DimDefinition LocationShelf = new(
        Key: "LOCATION_SHELF",
        EntityCode: "S0_LOCATION_SHELF",
        SourceTable: "LocationShelfMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_location",
        DimTable: "dim_location_shelf",
        BusinessKeyColumns: ["tenant_id", "domain_code", "location_code", "shelf_code"],
        SourceBizKeyColumns: ["domain_code", "location", "inv_shelf"],
        ParentDimTable: "dim_location",
        ParentKeyColumns: ["domain_code", "location_code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("domain_code",       S0DimValueKind.Str,         "domain_code",    Required: true),
            new("location_code",     S0DimValueKind.Str,         "location",       Required: true),
            new("shelf_code",        S0DimValueKind.Str,         "inv_shelf",      Required: true),
            new("shelf_name",        S0DimValueKind.Str,         "descr"),
            new("area",              S0DimValueKind.Str,         "area"),
            // 源恒 NULL（0/30），保留列以便源将来启用；不得为了“看起来有值”而回填
            new("source_updated_at", S0DimValueKind.DateTimeSec, "update_time")
        ]);

    /// <summary>
    /// 雇员。源 <c>EmployeeMaster</c>（29 列，无影子列，2026-09-07 实测确认）。
    ///
    /// <para><b>身份 = tenant_id + Employee</b>。<c>Domain</c> 是属性，<b>不是</b>身份 ——
    /// 这条口径不是从旧物理唯一键推的，而是按「当前业务证据优先」重判的结果（2026-09-07）：</para>
    /// <list type="number">
    ///   <item>当前 CRUD 查重是 <c>tenant + FactoryRefId + Employee</c>
    ///         （<c>AdoS0EmployeesController</c>），**根本不含 Domain**；</item>
    ///   <item>其中 <c>FactoryRefId</c> 由 <c>AdoS0OrgScope.ResolveAsync(ctx, tenantId)</c>
    ///         **仅按租户**解析并强制 stamp（payload 值一律覆盖），是 tenant 的函数、零区分力，
    ///         故该查重等价于 <c>tenant + Employee</c>；</item>
    ///   <item>单条定位走 <c>ByIdScopedAsync(id, tenantId)</c>，不经 Domain；</item>
    ///   <item>真实 consumer 一致按工号关联：<c>LEFT JOIN EmployeeMaster e
    ///         ON p.Buyer = e.Employee AND e.tenant_id = p.tenant_id</c>
    ///         （DemandOrderService / OutsourceOrderService / ProcessOutsourceOrderService 共 5 处），
    ///         **无一处用 Domain**；</item>
    ///   <item>数据实测：<c>(tenant_id, Employee)</c> 租户内重复 = <b>0</b>，
    ///         且不存在「同租户同工号不同 Domain」的行。</item>
    /// </list>
    /// <para>租户仍必须入身份：<c>Employee</c> 跨租户碰撞实测 19 组 / 38 行
    /// （<c>G02795</c> / <c>ZHR01</c> / <c>RQTJ993</c> 等工号被多个租户各自使用）。
    /// 旧物理唯一键 <c>uk_EmployeeMaster_domain_employee</c> 含 Domain，属 legacy scope，
    /// 按 Owner 口径「不因存在于旧表/旧 UK 就自动成为 DIM identity」，**不予继承**。</para>
    ///
    /// <para>🔴 <c>sys_user_id</c> <b>只是属性，绝不参与业务键</b>：实测 1105 行中仅 <b>7 行</b>非空（0.6%），
    /// 它是「员工恰好也有系统账号」的可选链接，不是员工身份。把账号 id 当员工主键会让 99.4% 的员工无法标识。</para>
    ///
    /// <para>字段适用性分类：<c>employee_code</c>=CORE；<c>domain_code</c>=ATTRIBUTE
    /// （仍被部门父连接与 CRUD 的部门引用校验 <c>DepartmentExistsInTenantAsync(tenantId, domain, dept)</c> 使用）；
    /// <c>company_id</c>/<c>factory_id</c>=LEGACY_SCOPE（f(tenant)，保留仅为可追溯到 SysOrg 节点）；
    /// <c>sys_user_id</c>=可选 ATTRIBUTE，永远不入键。</para>
    /// </summary>
    public static readonly S0DimDefinition Employee = new(
        Key: "EMPLOYEE",
        EntityCode: "S0_EMPLOYEE",
        SourceTable: "EmployeeMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_employee",
        DimTable: "dim_employee",
        BusinessKeyColumns: ["tenant_id", "employee_code"],
        SourceBizKeyColumns: ["Employee"],
        ParentDimTable: "dim_department",
        ParentKeyColumns: ["domain_code", "department_code"],
        Columns:
        [
            new("tenant_id",          S0DimValueKind.TenantIdColumn),
            new("company_id",         S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",         S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("domain_code",        S0DimValueKind.Str,         "Domain",         Required: true),
            new("employee_code",      S0DimValueKind.Str,         "Employee",       Required: true),
            new("employee_name",      S0DimValueKind.Str,         "Name"),
            // 自由文本软引用：源 813 非空中约 97 在 DepartmentMaster 找不到，另 292 行未分配。
            // 未分配（NULL）不算孤儿，见 S0DimSqlBuilder.OrphanFromWhere。
            new("department_code",    S0DimValueKind.Str,         "Department"),
            new("job_title",          S0DimValueKind.Str,         "JobTitle"),
            new("work_center_code",   S0DimValueKind.Str,         "WorkCtr"),
            new("employment_status",  S0DimValueKind.Str,         "EmploymentStatus"),
            new("date_employed",      S0DimValueKind.DateTimeSec, "DateEmployed"),
            new("date_terminated",    S0DimValueKind.DateTimeSec, "DateTerminated"),
            // 稀疏（7/1105）。允许 NULL 透传，不得回填，也不得据此过滤行。
            new("sys_user_id",        S0DimValueKind.Int,         "sys_user_id"),
            new("is_active",          S0DimValueKind.BoolTrue,    "IsActive"),
            new("source_updated_at",  S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 生产线。源 <c>LineMaster</c>。
    ///
    /// <para><b>身份 = tenant_id + Line</b>。company / factory / Domain 全是属性，<b>不是</b>身份 ——
    /// 同样按「当前业务证据优先」重判（2026-09-07），旧物理唯一键
    /// <c>uk_LineMaster_scope_line(tenant_id, company_ref_id, factory_ref_id, Line)</c> 不予继承：</para>
    /// <list type="number">
    ///   <item>当前 CRUD <b>没有任何查重守卫</b>（<c>AdoS0MfgProductionLinesController</c> 无
    ///         <c>IsAnyAsync</c>/<c>DuplicateCode</c>），单条定位走 <c>ByIdScopedAsync(id, tenantId)</c>；</item>
    ///   <item><c>CompanyRefId</c>/<c>FactoryRefId</c> 在控制器里只是**可选查询筛选**
    ///         （<c>WhereIF(q.CompanyRefId.HasValue, ...)</c>），创建时由
    ///         <c>AdoS0OrgScope.ResolveAsync</c> 按租户强制 stamp，不是用户输入；</item>
    ///   <item>真实 consumer <c>S8MasterDataAdapter.GetLinesAsync</c> 是
    ///         <c>Where(x =&gt; x.TenantId == scope.TenantId).Select(code = x.Line)</c> —— 只有租户 + 产线码；</item>
    ///   <item>数据实测：四个候选（tenant+Line / +Domain / +factory / +company+factory）
    ///         租户内重复<b>全部为 0</b>；且**每个租户在本表只有 1 个 Domain、1 个 company、1 个 factory**
    ///         ⇒ 这三列在租户内是常量，<b>零区分力</b>。</item>
    /// </list>
    /// <para>租户仍必须入身份：<c>Line</c> 跨租户碰撞实测 20 组 / 80 行（如 <c>AE01</c> 在 4 个租户都存在）。</para>
    ///
    /// <para>字段适用性分类：<c>line_code</c>=CORE；<c>line_name</c>/<c>line_type</c>/<c>line_category</c>/
    /// <c>workshop</c>/<c>location_code</c>/<c>is_active</c>=ATTRIBUTE；
    /// <c>domain_code</c>/<c>company_id</c>/<c>factory_id</c>=LEGACY_SCOPE（租户内常量，保留仅为可追溯）。</para>
    ///
    /// <para>🔴 <c>Describe</c> 是真列（169/169 填充、63 distinct）；同表的 <c>line_describe</c>
    /// 是<b>恒空影子列</b>（0/169 填充），取错即静默得到全空的产线名称。
    /// 这是本仓第三例此型双列表（前两例：LocationMaster、StdOpMaster）。</para>
    ///
    /// <para>⚠️ <c>factory_ref_id</c> 参与身份，但**绝不能**设进 <c>MdpPullContext.FactoryId</c>：
    /// <c>MdpStagingWriter</c> 只识别 <c>factory_id</c>/<c>FactoryId</c> 两个列名，
    /// 本表叫 <c>factory_ref_id</c> → 解析为 null → 一旦 <c>ctx.FactoryId &gt; 0</c>，
    /// 比较基准会退化成 1 并让**整批行全部被跳过**（KNOWN-ISSUES I-015）。
    /// S0 的 pullCtx 只设 TenantId，该分支永不进入。</para>
    /// </summary>
    public static readonly S0DimDefinition Line = new(
        Key: "LINE",
        EntityCode: "S0_LINE",
        SourceTable: "LineMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_line",
        DimTable: "dim_line",
        BusinessKeyColumns: ["tenant_id", "line_code"],
        SourceBizKeyColumns: ["Line"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("line_code",         S0DimValueKind.Str,         "Line",           Required: true),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("domain_code",       S0DimValueKind.Str,         "Domain",         Required: true),
            new("line_name",         S0DimValueKind.Str,         "Describe"),
            new("line_type",         S0DimValueKind.Str,         "LineType"),
            new("line_category",     S0DimValueKind.Str,         "LineCategory"),
            new("workshop",          S0DimValueKind.Str,         "Workshop"),
            new("location_code",     S0DimValueKind.Str,         "Location"),
            new("is_active",         S0DimValueKind.BoolTrue,    "IsActive"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 客户。源 <c>CustMaster</c>（32 列，无影子列对；空列极多，只物化有语义且有数据的）。
    ///
    /// <para><b>身份 = tenant_id + Cust</b>。同样按「当前业务证据优先」重判：</para>
    /// <list type="number">
    ///   <item>CRUD 查重 <c>tenant + FactoryRefId + Cust</c>（<c>AdoS0CustomersController:70,117</c>），
    ///         而 <c>FactoryRefId</c> 由 <c>AdoS0OrgScope</c> 仅按租户解析并强制 stamp ⇒ 等价 <c>tenant + Cust</c>；</item>
    ///   <item><c>DomainCode</c> 在控制器里只是**可选列表筛选**（<c>WhereIF(...)</c>），不参与查重；</item>
    ///   <item>单条定位 <c>ByIdScopedAsync(id, tenantId)</c>；</item>
    ///   <item>数据实测：三个候选（tenant+Cust / +Domain / +factory）租户内重复**全部为 0**，
    ///         且 company/factory 在每个租户内均为**单一取值**（常量、零区分力）。</item>
    /// </list>
    /// <para>租户必须入身份：<c>Cust</c> 跨租户碰撞实测 <b>4 个编码</b>。</para>
    ///
    /// <para>🔴 源表另有一条 <b>不含 tenant_id</b> 的旧唯一键 <c>uk_CustMaster_factory_cust(factory_ref_id, Cust)</c>，
    /// 且 <c>factory_ref_id=1000</c> 被两个租户共用 —— 属源表治理缺陷（<c>KNOWN-ISSUES I-016</c>），
    /// **它不能反过来决定 DIM identity**；dim 侧自带 <c>tenant_id</c> 前缀，不受其影响。
    /// 本批不动源表 DDL。</para>
    ///
    /// <para>字段适用性：<c>customer_code</c>=CORE；<c>customer_name</c>/<c>is_active</c>/
    /// <c>is_confirmed</c>/<c>shipping_lead_time</c>=ATTRIBUTE；
    /// <c>domain_code</c>/<c>company_id</c>/<c>factory_id</c>=LEGACY_SCOPE。
    /// 全空列（address / contact / Curr / Salesperson1 / Terms / cust_class / shipping_address 等 13 列，
    /// 填充率 0/1333）与近空列（Class 7 · TaxClass 3 · CustFullName 2 · Remarks 1）
    /// = DROP_FROM_STANDARD，不物化。</para>
    /// </summary>
    public static readonly S0DimDefinition Customer = new(
        Key: "CUSTOMER",
        EntityCode: "S0_CUSTOMER",
        SourceTable: "CustMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_customer",
        DimTable: "dim_customer",
        BusinessKeyColumns: ["tenant_id", "customer_code"],
        SourceBizKeyColumns: ["Cust"],
        Columns:
        [
            new("tenant_id",          S0DimValueKind.TenantIdColumn),
            new("customer_code",      S0DimValueKind.Str,         "Cust",           Required: true),
            new("customer_name",      S0DimValueKind.Str,         "SortName"),
            new("domain_code",        S0DimValueKind.Str,         "Domain"),
            new("company_id",         S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",         S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("shipping_lead_time", S0DimValueKind.Int,         "CustShippingLT"),
            new("is_active",          S0DimValueKind.BoolTrue,    "IsActive"),
            new("is_confirmed",       S0DimValueKind.BoolTrue,    "IsConfirm"),
            new("source_updated_at",  S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 人员技能字典。源 <c>PersonSkill</c>（11 列）—— 是**技能主数据**，不是关系表。
    ///
    /// <para><b>身份 = tenant_id + Code</b>。最强的一条证据来自现有消费方的注释与实现
    /// （<c>AdoS0MfgLinePostsController.ResolvePersonSkillCodesAsync</c>）：
    /// 「PersonSkill 表没有 Domain 列，故不按 Domain 收窄；产线岗位主表也不带
    /// CompanyRefId / FactoryRefId，无法据此再收窄，**因此按 (租户, Code) 解析**并对多义显式报错」——
    /// 即当前业务**已经**把技能码当作租户级字典，并把「同租户跨公司/工厂重码」视为
    /// <b>歧义错误</b>而非两个不同技能。</para>
    /// <para>数据佐证：三个候选（tenant+Code / +Factory / +Company+Factory）租户内重复全部为 0，
    /// company/factory 每租户单一取值。<c>Code</c> 跨租户碰撞 5 个编码 ⇒ 租户必须入身份。</para>
    ///
    /// <para>⚠️ <b>不设父维度</b>：<c>EmpSkills.SkillNo</c> 与本表 <c>Code</c> 同租户实测
    /// 650 行中 <b>632 行对不上</b>（仅 18 命中）—— 两者当前是各自独立的编码体系。
    /// **不因为都叫 Skill 就建立虚假父子关系。**</para>
    ///
    /// <para><c>source_updated_at ← UpdatedAt</c>：源 46 行中 <c>CreatedAt</c> 全非空、
    /// <c>UpdatedAt</c> 仅 5 行非空 —— 这正是「维护时间」的形态（只有被改过的行才有值），
    /// 故映射之，NULL 表示自建以来未修改。**不用 CreatedAt 冒充，也不回填。**</para>
    ///
    /// <para>字段适用性：<c>skill_code</c>=CORE；<c>skill_name</c>/<c>skill_level</c>/
    /// <c>remark</c>/<c>is_active</c>=ATTRIBUTE；<c>company_id</c>/<c>factory_id</c>=LEGACY_SCOPE。</para>
    /// </summary>
    public static readonly S0DimDefinition PersonSkill = new(
        Key: "PERSON_SKILL",
        EntityCode: "S0_PERSON_SKILL",
        SourceTable: "PersonSkill",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_person_skill",
        DimTable: "dim_person_skill",
        BusinessKeyColumns: ["tenant_id", "skill_code"],
        SourceBizKeyColumns: ["Code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("skill_code",        S0DimValueKind.Str,         "Code",         Required: true),
            new("skill_name",        S0DimValueKind.Str,         "Name"),
            new("skill_level",       S0DimValueKind.Str,         "SkillLevel"),
            new("remark",            S0DimValueKind.Str,         "Remark"),
            new("company_id",        S0DimValueKind.Int,         "CompanyRefId", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "FactoryRefId", Required: true),
            new("is_active",         S0DimValueKind.BoolTrue,    "IsEnabled"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdatedAt")
        ]);

    // ════════════════════════════════════════════════════════════════════════════
    // C2 · 参考/配置字典（ref_*）
    //
    // 与 C1 维度同用一套机制，只是语义是「字典」而非「主数据实体」，故目标表用 ref_ 前缀。
    // 身份口径与 C1 完全一致：tenant_id + 业务码；Domain / company / factory 一律 LEGACY_SCOPE。
    //
    // 🔴 本组落地时实测出的两个框架地雷，写在这里免得下次重踩：
    //   ① bit(1) 源列用 Int 会让对账每轮必挂（详见 S0DimValueKind.Int 的说明）。
    //   ② qms 字典的 FSTATUS / FENABLE 是 varchar 且值域含中文与字母
    //      （`已审核` / `已启用` / `A` / `ENABLED` / `INVALID_STATUS`），
    //      用 BoolTrue 会命中可辨识性守卫：4 张表**整表归零**，
    //      而 qms_inspectionfreq.FENABLE 恰好存活 8/13 —— 部分静默丢失，最难发现。
    //      ⇒ 状态列一律 Str 原样透传，语义归一留给下游。
    // ════════════════════════════════════════════════════════════════════════════

    /// <summary>
    /// 标签类型字典。源 <c>BarCodeType</c>。
    ///
    /// <para>身份 = <c>tenant_id + bar_type</c>。CRUD 查重
    /// （<c>AdoS0LabelTypesController</c>）= <c>tenant + FactoryRefId + BarType</c>，
    /// 而 <c>FactoryRefId</c> 由 <c>AdoS0OrgScope</c> 仅按租户解析并强制 stamp ⇒ 等价 <c>tenant + bar_type</c>，
    /// **不含 Domain**。实测 <c>bar_type</c> 跨租户碰撞 6 个编码 ⇒ 租户必须入键。</para>
    ///
    /// <para>⚠️ 本表主键叫 <c>rec_id</c>（带下划线），不在 <c>MdpDbPullExecutor.ResolveSourceRowId</c>
    /// 的候选列表内（<c>rec_id ≠ recid</c>），且本表无 <c>id</c> 列 ⇒ <c>source_row_id</c> 落 GUID 兜底。
    /// 与 <c>LocationShelfMaster</c> 同型，**安全**：物化只认 <c>sync_batch_id</c>，
    /// 且 purge 先于 pull，不依赖 source_row_id 稳定性。</para>
    /// </summary>
    public static readonly S0DimDefinition LabelType = new(
        Key: "LABEL_TYPE",
        EntityCode: "S0_LABEL_TYPE",
        SourceTable: "BarCodeType",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_label_type",
        DimTable: "ref_label_type",
        BusinessKeyColumns: ["tenant_id", "label_type_code"],
        SourceBizKeyColumns: ["bar_type"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("label_type_code",   S0DimValueKind.Str,         "bar_type",       Required: true),
            new("label_class",       S0DimValueKind.Str,         "class"),
            new("input_string",      S0DimValueKind.Str,         "input_string"),
            new("domain_code",       S0DimValueKind.Str,         "domain_code"),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "update_time")
        ]);

    /// <summary>
    /// SOP 文件类型字典。源 <c>ImageType</c>（**只有 5 列**）。
    ///
    /// <para>身份 = <c>tenant_id + image_type_id</c>。控制器
    /// <c>AdoS0MfgSopFileTypesController</c> 无查重守卫，定位走 <c>ByIdScopedAsync(id, tenantId)</c>，
    /// 且已有显式「去 domain 化」注释（S0-DOMAIN-FILTER-REMOVAL-READONLY-1）。</para>
    ///
    /// <para>🔴 <b>本表没有任何时间列</b>（实测 5 列 = id/tenant_id/image_type_id/descr/domain），
    /// 故**不声明 <c>source_updated_at</c>**，ref 表里也不建该列。
    /// 不得为了「标准字段齐整」而回填 —— JsonPath 必须是真实物理列。</para>
    ///
    /// <para>注意物理列名是 <c>domain</c> 而非 <c>domain_code</c>；且其取值在三个租户间口径异构
    /// （<c>S0-F001</c> / 雪花号 / <c>8010</c>），更加坐实它是 LEGACY_SCOPE。</para>
    /// </summary>
    public static readonly S0DimDefinition SopFileType = new(
        Key: "SOP_FILE_TYPE",
        EntityCode: "S0_SOP_FILE_TYPE",
        SourceTable: "ImageType",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_sop_file_type",
        DimTable: "ref_sop_file_type",
        BusinessKeyColumns: ["tenant_id", "file_type_code"],
        SourceBizKeyColumns: ["image_type_id"],
        Columns:
        [
            new("tenant_id",      S0DimValueKind.TenantIdColumn),
            new("file_type_code", S0DimValueKind.Str, "image_type_id", Required: true),
            new("file_type_name", S0DimValueKind.Str, "descr"),
            new("domain_code",    S0DimValueKind.Str, "domain")
        ]);

    /// <summary>
    /// 质量基础类型字典。源 <c>qms_quality_base_type</c>。
    ///
    /// <para>身份 = <c>tenant_id + type_category + type_code</c>，**两段业务码**。
    /// <c>type_code</c> 单列在当前数据里也唯一，但那是运气 —— 代码硬证据：
    /// <c>AdoS0QualityBaseDataControllers</c> 的 Create/Update 两处查重均按
    /// <c>(TypeCategory, TypeCode)</c>，注释亦写明「(TypeCategory, TypeCode) 全局唯一」。
    /// 按「当前业务证据优先」取两段。源表无任何 UK。</para>
    ///
    /// <para>本表无 Domain / company / factory 列 —— 不设、不发明（同 <c>WorkCtrMaster</c> 先例）。
    /// <c>is_active</c> 是 <c>tinyint(1) NOT NULL</c>，在 raw_data 里是 JSON BOOLEAN，可安全走 BoolTrue。</para>
    /// </summary>
    public static readonly S0DimDefinition QualityBaseType = new(
        Key: "QUALITY_BASE_TYPE",
        EntityCode: "S0_QUALITY_BASE_TYPE",
        SourceTable: "qms_quality_base_type",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_quality_base_type",
        DimTable: "ref_quality_base_type",
        BusinessKeyColumns: ["tenant_id", "type_category", "type_code"],
        SourceBizKeyColumns: ["type_category", "type_code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("type_category",     S0DimValueKind.Str,         "type_category", Required: true),
            new("type_code",         S0DimValueKind.Str,         "type_code",     Required: true),
            new("short_name",        S0DimValueKind.Str,         "short_name"),
            new("full_name",         S0DimValueKind.Str,         "full_name"),
            new("remark",            S0DimValueKind.Str,         "remark"),
            new("is_active",         S0DimValueKind.BoolTrue,    "is_active"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "modify_time")
        ]);

    /// <summary>
    /// 抽样方案字典。源 <c>qms_sampscheme</c>。C2-2 qms 字典族共用 <c>mdp_stg_s0_qms_dict</c>，靠 <c>source_table</c> 隔离。
    /// <para>🔴 <c>FSTATUS</c>/<c>FENABLE</c> 必须 <c>Str</c>：实测值域 <c>已审核×8 · DISABLED×1 · INVALID_STATUS×1</c>
    /// 与 <c>已启用×8 · ENABLED×2</c>，用 BoolTrue 会**整表归零**。</para>
    /// </summary>
    public static readonly S0DimDefinition SamplingScheme = new(
        Key: "SAMPLING_SCHEME",
        EntityCode: "S0_SAMPLING_SCHEME",
        SourceTable: "qms_sampscheme",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_qms_dict",
        DimTable: "ref_sampling_scheme",
        BusinessKeyColumns: ["tenant_id", "scheme_code"],
        SourceBizKeyColumns: ["FNUMBER"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("scheme_code",       S0DimValueKind.Str,         "FNUMBER", Required: true),
            new("scheme_name",       S0DimValueKind.Str,         "FNAME"),
            new("sampling_type",     S0DimValueKind.Str,         "FSAMPLINGTYPE"),
            new("inspection_level",  S0DimValueKind.Str,         "FINSPECTIONLEVEL"),
            new("strictness",        S0DimValueKind.Str,         "FSTRICTNESS"),
            new("aql_value",         S0DimValueKind.Str,         "FAQLVALUE"),
            new("inspection_type",   S0DimValueKind.Str,         "FINSPECTIONTYPE"),
            new("status_code",       S0DimValueKind.Str,         "FSTATUS"),
            new("enable_code",       S0DimValueKind.Str,         "FENABLE"),
            new("remark",            S0DimValueKind.Str,         "FCOMMENT"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "FMODIFYTIME")
        ]);

    /// <summary>
    /// 检验项目字典。源 <c>qms_inspectionitems</c>。
    /// <para>⚠️ <c>FCHECKMETHOD</c>/<c>FCHECKBASIS</c> 指向的是**源表代理主键 <c>id</c>**，不是业务键，
    /// 故只作普通 Int 属性透传，**不声明父维度**（框架的孤儿判定按业务键列做 join，对不上）。
    /// 同 <c>dim_employee.sys_user_id</c> 先例。</para>
    /// </summary>
    public static readonly S0DimDefinition InspectionItem = new(
        Key: "INSPECTION_ITEM",
        EntityCode: "S0_INSPECTION_ITEM",
        SourceTable: "qms_inspectionitems",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_qms_dict",
        DimTable: "ref_inspection_item",
        BusinessKeyColumns: ["tenant_id", "item_code"],
        SourceBizKeyColumns: ["FNUMBER"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("item_code",         S0DimValueKind.Str,         "FNUMBER", Required: true),
            new("item_name",         S0DimValueKind.Str,         "FNAME"),
            new("check_method_id",   S0DimValueKind.Int,         "FCHECKMETHOD"),
            new("check_basis_id",    S0DimValueKind.Int,         "FCHECKBASIS"),
            new("status_code",       S0DimValueKind.Str,         "FSTATUS"),
            new("enable_code",       S0DimValueKind.Str,         "FENABLE"),
            new("remark",            S0DimValueKind.Str,         "FCOMMENT"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "FMODIFYTIME")
        ]);

    /// <summary>检验方法字典。源 <c>qms_inspection_method</c>。状态列同族一律 <c>Str</c>。</summary>
    public static readonly S0DimDefinition InspectionMethod = new(
        Key: "INSPECTION_METHOD",
        EntityCode: "S0_INSPECTION_METHOD",
        SourceTable: "qms_inspection_method",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_qms_dict",
        DimTable: "ref_inspection_method",
        BusinessKeyColumns: ["tenant_id", "method_code"],
        SourceBizKeyColumns: ["FNUMBER"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("method_code",       S0DimValueKind.Str,         "FNUMBER", Required: true),
            new("method_name",       S0DimValueKind.Str,         "FNAME"),
            new("control_strategy",  S0DimValueKind.Str,         "FCTRLSTRATEGY"),
            new("status_code",       S0DimValueKind.Str,         "FSTATUS"),
            new("enable_code",       S0DimValueKind.Str,         "FENABLE"),
            new("remark",            S0DimValueKind.Str,         "FCOMMENT"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "FMODIFYTIME")
        ]);

    /// <summary>
    /// 检验频次字典。源 <c>qms_inspectionfreq</c>。
    /// <para>🔴 <b>本表与兄弟表有两处不同，照抄会出错</b>：
    /// ① 备注列叫 <c>FREMARK</c>，**不是** <c>FCOMMENT</c>；
    /// ② <c>FENABLE</c> 的值域是 <c>'1'×8 · ENABLED×5</c> —— 用 BoolTrue 会**存活 8 行、静默丢 5 行**，
    /// 是全族唯一不会整表归零、因而最容易被误判成「通过」的一张。</para>
    /// </summary>
    public static readonly S0DimDefinition InspectionFrequency = new(
        Key: "INSPECTION_FREQUENCY",
        EntityCode: "S0_INSPECTION_FREQUENCY",
        SourceTable: "qms_inspectionfreq",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_qms_dict",
        DimTable: "ref_inspection_frequency",
        BusinessKeyColumns: ["tenant_id", "frequency_code"],
        SourceBizKeyColumns: ["FNUMBER"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("frequency_code",    S0DimValueKind.Str,         "FNUMBER", Required: true),
            new("frequency_name",    S0DimValueKind.Str,         "FNAME"),
            new("remark",            S0DimValueKind.Str,         "FREMARK"),
            new("status_code",       S0DimValueKind.Str,         "FSTATUS"),
            new("enable_code",       S0DimValueKind.Str,         "FENABLE"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "FMODIFYTIME")
        ]);

    /// <summary>
    /// 量检具字典。源 <c>qms_inspectioninstru</c>。
    /// <para>三个运维列是源表自有的 snake_case 列（非 F 前缀）：<c>gauge_category</c> ·
    /// <c>calibration_cycle_days</c>(int) · <c>next_calibration_date</c>。</para>
    /// <para>⚠️ <c>next_calibration_date</c> 源是 <b>varchar(50)</b> 存日期串（如 <c>2027-02-25</c>），
    /// 用 <c>Str</c> 忠实透传而非 <c>DateTimeSec</c>：后者对非 ISO 脏值会让**两侧同时变 NULL**，
    /// checksum 照样相等而数据静默丢失。</para>
    /// </summary>
    public static readonly S0DimDefinition InspectionInstrument = new(
        Key: "INSPECTION_INSTRUMENT",
        EntityCode: "S0_INSPECTION_INSTRUMENT",
        SourceTable: "qms_inspectioninstru",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_qms_dict",
        DimTable: "ref_inspection_instrument",
        BusinessKeyColumns: ["tenant_id", "instrument_code"],
        SourceBizKeyColumns: ["FNUMBER"],
        Columns:
        [
            new("tenant_id",              S0DimValueKind.TenantIdColumn),
            new("instrument_code",        S0DimValueKind.Str,         "FNUMBER", Required: true),
            new("instrument_name",        S0DimValueKind.Str,         "FNAME"),
            new("model",                  S0DimValueKind.Str,         "FMODEL"),
            new("specification",          S0DimValueKind.Str,         "FSPECIFICATION"),
            new("manufacturer",           S0DimValueKind.Str,         "FMANUFACTURER"),
            new("gauge_category",         S0DimValueKind.Str,         "gauge_category"),
            new("calibration_cycle_days", S0DimValueKind.Int,         "calibration_cycle_days"),
            new("next_calibration_date",  S0DimValueKind.Str,         "next_calibration_date"),
            new("status_code",            S0DimValueKind.Str,         "FSTATUS"),
            new("enable_code",            S0DimValueKind.Str,         "FENABLE"),
            new("remark",                 S0DimValueKind.Str,         "FCOMMENT"),
            new("source_updated_at",      S0DimValueKind.DateTimeSec, "FMODIFYTIME")
        ]);

    /// <summary>
    /// 物料。源 <c>ItemMaster</c> —— **S0 的 Item 权威**（2026-09-07 拍板）。
    ///
    /// <para><b>与 <c>mdp_std_item</c> 的关系已封板，不再讨论</b>：那是 Supply/S3 的**多源**物料目录
    /// （实测混入 <c>ic_item</c>，797 租户有 75 个 item_code 只来自 ic_item、在 ItemMaster 里 0 命中），
    /// 且物理上无 <c>Domain</c>、无 <c>ItemMaster.RecID</c>、两个最大租户的 factory/company 100% NULL，
    /// 无法承担 C3 的父维度职责。<c>dim_item</c> 不是第二份权威，是 <c>ItemMaster</c> 的第一次物化，
    /// 二者语义域不相交（消费方实测零重叠）。</para>
    ///
    /// <para><b>身份 = tenant_id + ItemNum</b>。实测：租户内重复 <b>0</b>、空白 <b>0</b>、非法租户 <b>0</b>；
    /// <c>ItemNum</c> 跨租户碰撞 <b>663 码 / 1534 行</b> ⇒ 租户必须入身份。
    /// 旧唯一键 <c>uk_ItemMaster_factory_item</c> 含 <c>factory_ref_id</c>，**不予继承** ——
    /// 它连 f(tenant) 都不是（租户 838257186181189 有 3 个取值，含 <c>0</c>），
    /// 且 <c>8010</c> 被三个租户共用，放进唯一键既无判别力又把身份绑到跨租户共享值上。</para>
    ///
    /// <para>⚠️ <b>单租户最大 16150 行，超过默认 batch_size 5000</b> ——
    /// <c>AssertNoSourceDuplicateAsync</c> 会硬失败。本 entity 的 <c>mdp_entity.batch_size</c> 设 <b>50000</b>。
    /// 该值是 **entity 级**（取自 <c>entity.BatchSize</c>），不影响其它任何维度。</para>
    ///
    /// <para><c>legacy_source_id ← RecID</c> 是**技术属性**，供 C3 的
    /// <c>ProductStructureMaster.ComponentMaterialId</c> 这类 legacy 代理键做对账解析。
    /// **它绝不是身份，也不得用 dim 的代理 id 建立外键** —— 每轮 FULL REPLACE 后 <c>dim_item.id</c> 都会变。</para>
    ///
    /// <para>字段取舍规则（75 列 → 只物化符合以下全部条件的）：**全库填充率 ≥5% 且全库 distinct ≥2**；
    /// 并无条件排除审计列、影子列、<c>bit(1)</c> 列、可空 <c>tinyint(1)</c>。据此排除的典型：
    /// <c>expire_alarm_day</c>（0 填充的影子列，真列是 <c>ExpireAlarmDays</c> 22682）·
    /// <c>SuppWarranty</c>（<c>bit(1)</c> 且含 2 行 NULL —— 用 Int 对账必挂、用 BoolTrue 会滤掉那 2 行）·
    /// <c>DEAControlled</c>（可空 tinyint，2 行 NULL 同样会被 BoolTrue 守卫滤掉）·
    /// <c>Length</c>/<c>Size</c>/<c>Height</c>/<c>Width</c>/<c>cust_supplied</c>/<c>enable_bom_version</c>
    /// （全库 distinct=1，零信息）· <c>Status</c>（7/22684，且真实状态是 <c>IsActive</c>）。</para>
    /// </summary>
    public static readonly S0DimDefinition Item = new(
        Key: "ITEM",
        EntityCode: "S0_ITEM",
        SourceTable: "ItemMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item",
        DimTable: "dim_item",
        BusinessKeyColumns: ["tenant_id", "item_code"],
        SourceBizKeyColumns: ["ItemNum"],
        Columns:
        [
            new("tenant_id",           S0DimValueKind.TenantIdColumn),
            // ── CORE
            new("item_code",           S0DimValueKind.Str,         "ItemNum", Required: true),
            new("item_name",           S0DimValueKind.Str,         "Descr",   Required: true),
            // ── ATTRIBUTE · 描述与分类
            new("item_name_2",         S0DimValueKind.Str,         "Descr1"),
            new("unit",                S0DimValueKind.Str,         "UM"),
            new("pur_mfg",             S0DimValueKind.Str,         "PurMfg"),
            new("item_type",           S0DimValueKind.Str,         "ItemType"),
            new("commodity_code",      S0DimValueKind.Str,         "CommodityCode"),
            new("rev",                 S0DimValueKind.Str,         "Rev"),
            new("drawing",             S0DimValueKind.Str,         "Drawing"),
            new("pkg_code",            S0DimValueKind.Str,         "PkgCode"),
            new("series",              S0DimValueKind.Str,         "Series"),
            new("emt_type",            S0DimValueKind.Str,         "EMTType"),
            new("po_receipt_status",   S0DimValueKind.Str,         "PORcptStatus"),
            new("warranty_code",       S0DimValueKind.Str,         "WarrantyCode"),
            // ── ATTRIBUTE · 库位与人员
            new("default_location",    S0DimValueKind.Str,         "Location"),
            new("buyer",               S0DimValueKind.Str,         "Buyer"),
            new("planner",             S0DimValueKind.Str,         "Planner"),
            // ── ATTRIBUTE · 计量
            new("net_weight",          S0DimValueKind.Dec,         "NetWeight",   Precision: 18, Scale: 5),
            new("net_weight_um",       S0DimValueKind.Str,         "NetWeightUM"),
            // ── ATTRIBUTE · 计划参数（Dec 精度必须与源逐位一致，否则 CAST AS CHAR 后校验和 FAIL）
            new("pur_lead_time",       S0DimValueKind.Int,         "PurLT"),
            new("ins_lead_time",       S0DimValueKind.Int,         "InsLT"),
            new("mfg_lead_time",       S0DimValueKind.Int,         "MfgLT"),
            new("mfg_mttr",            S0DimValueKind.Int,         "MFGMTTR"),
            new("days_between_pm",     S0DimValueKind.Int,         "DaysBetweenPM"),
            new("expire_alarm_days",   S0DimValueKind.Int,         "ExpireAlarmDays"),
            new("min_order_qty",       S0DimValueKind.Dec,         "MinOrd",        Precision: 18, Scale: 5),
            new("max_order_qty",       S0DimValueKind.Dec,         "MaxOrd",        Precision: 18, Scale: 5),
            new("min_order_qty_sales", S0DimValueKind.Dec,         "MinOrdSales",   Precision: 18, Scale: 5),
            new("order_multiple",      S0DimValueKind.Dec,         "OrdMult",       Precision: 18, Scale: 5),
            new("safety_stock",        S0DimValueKind.Dec,         "SafetyStk",     Precision: 18, Scale: 5),
            new("stock_turnover",      S0DimValueKind.Dec,         "StockTurnOver", Precision: 18, Scale: 5),
            // ── ATTRIBUTE · 标志位（全部是 tinyint(1) NOT NULL，可安全走 BoolTrue）
            new("is_active",           S0DimValueKind.BoolTrue,    "IsActive"),
            new("is_confirmed",        S0DimValueKind.BoolTrue,    "IsConfirm"),
            new("key_item",            S0DimValueKind.BoolTrue,    "KeyItem"),
            new("inspect_required",    S0DimValueKind.BoolTrue,    "Inspect"),
            new("issue_policy",        S0DimValueKind.BoolTrue,    "IssuePolicy"),
            new("install",             S0DimValueKind.BoolTrue,    "Install"),
            new("lot_serial_control",  S0DimValueKind.BoolTrue,    "LotSerialControl"),
            new("allocate_single_lot", S0DimValueKind.BoolTrue,    "AllocateSingleLot"),
            new("auto_lot_nums",       S0DimValueKind.BoolTrue,    "AutoLotNums"),
            new("trace_detail",        S0DimValueKind.BoolTrue,    "TraceDetail"),
            new("is_main_master",      S0DimValueKind.BoolTrue,    "IsMainMas"),
            new("mrp_required",        S0DimValueKind.BoolTrue,    "MRPRequired"),
            // ── LEGACY_SCOPE（属性透传，绝不入唯一键）
            new("domain_code",         S0DimValueKind.Str,         "Domain"),
            new("company_id",          S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",          S0DimValueKind.Int,         "factory_ref_id", Required: true),
            // ── 技术属性：供 C3 的 legacy 代理键对账用（见类型注释）
            new("legacy_source_id",    S0DimValueKind.Int,         "RecID",          Required: true),
            new("source_updated_at",   S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 物料-工序-产线产能。源 <c>ProdLineDetail</c>，父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + Part + Op + Line</b>（实测租户内重复 0 组）。
    /// <c>Line</c> **不可省**：去掉后 <c>tenant+Part+Op</c> 有 <b>197 组 / 394 行</b>重复。
    /// <c>Domain</c> 每租户单值（797→8010、824585161322565→2410、838257186181189→8010），
    /// 零判别力 ⇒ LEGACY_SCOPE，不入身份（D-025）。</para>
    ///
    /// <para>🔴 <b>dual-column 陷阱</b>：真列是 <c>InternalEquipmentCode</c>（2430/10646 有值），
    /// 同表的 <c>internal_equipment_type_code</c> 是 <b>0/10646 的死影子列</b>。取错不报错、只会全 NULL。</para>
    ///
    /// <para>🔴 <c>RunCrew</c> 在本表是 <c>varchar(8)</c>，而 <see cref="LinePost"/> 的同名列源自
    /// <c>LineSkillMaster</c> 是 <c>decimal(10,3)</c> —— <b>同名不同型</b>，照抄会当场类型出错。</para>
    ///
    /// <para><c>Line</c> 有 <b>11 行带尾随空格</b>（<c>A01 </c>×2 / <c>BA01 </c>×6 / <c>DC01-1 </c>×1 /
    /// <c>S01 </c>×1 / <c>S02 </c>×1）。<c>utf8mb4_0900_ai_ci</c> 是 NO PAD，这是真实业务键差异，
    /// **原样透传，禁止 TRIM**。</para>
    ///
    /// <para><c>Line</c> / <c>Site</c> 都只作软引用**不设父**：<c>Line→dim_line</c> 同租户孤儿
    /// 8848/10646（租户 824585161322565 的 <c>LineMaster</c> 整体 0 行），<c>Site</c> 更有 5823/10646 为 NULL；
    /// 且 CRUD 写入路径对二者**零存在性校验**（<c>_lineMasterRep</c>/<c>_workCtrRep</c> 只用于列表回显）。
    /// 与 <see cref="LinePost"/> 不挂 <c>dim_line</c> 同源。</para>
    ///
    /// <para>⚠️ <c>Op</c> 是本仓**首个 <c>Int</c> 类型业务键**。三侧渲染已验证一致：
    /// C# <c>((int)1002).ToString()</c> / 源侧 <c>CONCAT_WS(…, a.Op)</c> / dim 侧同 —— 均为 <c>'1002'</c>。</para>
    ///
    /// <para>租户分布 797=5817 / 824585161322565=4823 / 838257186181189=6，
    /// 故 <c>batch_size</c> 取 <b>20000</b>（3.4× 头寸；默认 5000 会被
    /// <c>AssertNoSourceDuplicateAsync</c> 的 <c>sourceCount &gt;= batchSize</c> 直接判失败）。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemOpLine = new(
        Key: "ITEM_OP_LINE",
        EntityCode: "S0_ITEM_OP_LINE",
        SourceTable: "ProdLineDetail",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_op_line",
        DimTable: "bridge_item_op_line",
        BusinessKeyColumns: ["tenant_id", "item_code", "operation_no", "line_code"],
        SourceBizKeyColumns: ["Part", "Op", "Line"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",               S0DimValueKind.TenantIdColumn),
            new("item_code",               S0DimValueKind.Str,         "Part",   Required: true),
            new("operation_no",            S0DimValueKind.Int,         "Op",     Required: true),
            new("line_code",               S0DimValueKind.Str,         "Line",   Required: true),
            new("domain_code",             S0DimValueKind.Str,         "Domain", Required: true),
            new("work_center_code",        S0DimValueKind.Str,         "Site"),
            new("rate",                    S0DimValueKind.Dec,         "Rate",               Precision: 18, Scale: 6),
            new("setup_time",              S0DimValueKind.Dec,         "SetupTime",          Precision: 18, Scale: 6),
            new("overlap_time",            S0DimValueKind.Dec,         "OverlapTime",        Precision: 18, Scale: 6),
            new("sequence_no",             S0DimValueKind.Dec,         "Sequence",           Precision: 18, Scale: 6),
            new("standard_staff_count",    S0DimValueKind.Dec,         "StandardStaffCount", Precision: 18, Scale: 6),
            new("skill_code",              S0DimValueKind.Str,         "SkillNo"),
            // 🔴 真列，**不是**同表 0/10646 的影子列 internal_equipment_type_code
            new("internal_equipment_code", S0DimValueKind.Str,         "InternalEquipmentCode"),
            new("mold_type_code",          S0DimValueKind.Str,         "MoldTypeCode"),
            new("start_marker",            S0DimValueKind.Int,         "Start"),
            new("is_active",               S0DimValueKind.BoolTrue,    "IsActive"),
            new("is_confirmed",            S0DimValueKind.BoolTrue,    "IsConfirm"),
            // 🔴 源 varchar(8)，与 dim_line_post.run_crew 的 decimal(10,3) 同名不同型
            new("run_crew",                S0DimValueKind.Str,         "RunCrew"),
            new("op_type",                 S0DimValueKind.Str,         "OpType"),
            new("bom_code",                S0DimValueKind.Str,         "Bom"),
            new("source_updated_at",       S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 物料工艺路线工序。源 <c>RoutingOpDetail</c>（38806 行，S0 最大的桥），父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + MaterialCode + OperationCode</b>（实测重复 0 组）。
    /// <c>RouteCode</c> 不必要：每租户 <c>COUNT(DISTINCT RouteCode) == COUNT(DISTINCT MaterialCode)</c>
    /// 且两列逐值相同 38805/38806 行。<c>SortNo</c> 也不必要（近乎常量）。
    /// 去掉 <c>OperationCode</c> 则塌陷成 <b>2879 组 / 38677 行</b>重复。</para>
    ///
    /// <para>🔴 <b>本表的时间列叫 <c>UpdatedAt</c> / <c>CreatedAt</c>，不是全仓通用的 <c>UpdateTime</c></b>。
    /// 照抄其它 definition 写 <c>UpdateTime</c> 会**静默取到恒 NULL**（JSON 键不存在 →
    /// <c>JSON_EXTRACT</c> 返回 SQL NULL，不报错）。</para>
    ///
    /// <para>🔴 <b>六组新旧列近重复，取错不会得到 NULL 而是「看起来合法的错值」</b>
    /// （<c>RouteCode</c>/<c>RoutingCode</c>/<c>MaterialCode</c>/<c>RouteName</c> 四列 38805/38806 同值）。
    /// 真列判据 = CRUD 写入路径：<c>RouteCode</c>（非 <c>RoutingCode</c>）·
    /// <c>OperationCode</c>（非旧列 <c>Op</c>）· <c>OperationDescription</c>（非 <c>Descr</c>）。</para>
    ///
    /// <para><b><c>StdOp</c> 不设父</b>：对 <c>StdOpMaster</c> 孤儿 <b>37112/38746</b>（95.8%），
    /// <c>AdoS0ReferenceChecker</c> 无 StdOp 校验、CRUD 的 <c>ApplyUpsert</c> 根本不写该列、UI 无下拉，
    /// 且值域不同构（本表 <c>0010</c>/<c>0020</c> vs <c>StdOpMaster.StdOp</c> 的 <c>1-1/包装</c>，
    /// 仅 1634/38806 偶然命中）。**它与 item 孤儿是两回事** —— item 孤儿只有 <b>44</b>。</para>
    ///
    /// <para>父孤儿 <b>44 行 = ALLOW + WARNING</b>（框架原生：孤儿只告警不阻断）：全在租户 797，
    /// 仅 2 个物料码 <c>A198CABA</c>×18 / <c>918B0238</c>×26，忽略租户后仍是 44
    /// ⇒ 是被引用主数据**全库整体缺失**，不是跨租户错挂。</para>
    ///
    /// <para><b>本轮无法物化的两个业务语义</b>（数据侧问题，非建模问题）：
    /// 「报工工序」—— CRUD 唯一写入的 <c>MilestoneOperation</c> 是 <b>0/38806</b>，
    /// 数据全在 CRUD 从不写的旧列 <c>MilestoneOp</c>，而后者是**可空 <c>tinyint(1)</c>**（1 行 NULL）；
    /// 「启用状态」—— <c>IsEnabled</c> distinct=1 零信息，<c>IsActive</c> 同为可空 <c>tinyint(1)</c>。
    /// 可空 tinyint 用 <c>BoolTrue</c> 会滤掉 NULL 行导致行数对账 FAIL、用 <c>Int</c> 会静默写 0，
    /// 故一律不物化（与 <see cref="Item"/> 排除 <c>DEAControlled</c> 同因）。</para>
    ///
    /// <para><c>Ufld2</c>…<c>Ufld9</c>（8 列）· <c>OverlapUnits</c> · <c>PackingQty</c> ·
    /// <c>ProcessOutDay</c> 全库 distinct=1，零信息，不物化。</para>
    ///
    /// <para>租户分布 797=32309 / 824585161322565=4824 / 838257237606469=1398 /
    /// 838257186181189=156 / 838257212780613=119，故 <c>batch_size</c> 取 <b>100000</b>（3.1× 头寸）。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemRoutingOp = new(
        Key: "ITEM_ROUTING_OP",
        EntityCode: "S0_ITEM_ROUTING_OP",
        SourceTable: "RoutingOpDetail",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_routing_op",
        DimTable: "bridge_item_routing_op",
        BusinessKeyColumns: ["tenant_id", "item_code", "operation_code"],
        SourceBizKeyColumns: ["MaterialCode", "OperationCode"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",             S0DimValueKind.TenantIdColumn),
            new("item_code",             S0DimValueKind.Str,         "MaterialCode",  Required: true),
            // 🔴 新列；旧列 Op(int) 是 38805/38806 的近重复，不得取
            new("operation_code",        S0DimValueKind.Str,         "OperationCode", Required: true),
            new("route_code",            S0DimValueKind.Str,         "RouteCode"),      // 非旧列 RoutingCode
            new("route_name",            S0DimValueKind.Str,         "RouteName"),      // 实存码值而非名称
            new("operation_description", S0DimValueKind.Str,         "OperationDescription"), // 非旧列 Descr
            new("work_center_code",      S0DimValueKind.Str,         "WorkCenterCode"),
            new("std_op",                S0DimValueKind.Str,         "StdOp"),          // NO PARENT，见类型注释
            // Domain 有 1 行 NULL（RecID=106435 的 TEST 行），故不设 Required，否则整行被滤 → 行数对账 FAIL
            new("domain_code",           S0DimValueKind.Str,         "Domain"),
            new("company_id",            S0DimValueKind.Int,         "CompanyRefId",  Required: true),
            new("factory_id",            S0DimValueKind.Int,         "FactoryRefId",  Required: true),
            new("ufld1",                 S0DimValueKind.Str,         "Ufld1"),
            new("udeci1",                S0DimValueKind.Dec,         "UDeci1",  Precision: 18, Scale: 5),
            new("udeci2",                S0DimValueKind.Dec,         "UDeci2",  Precision: 18, Scale: 5),
            new("udeci3",                S0DimValueKind.Dec,         "UDeci3",  Precision: 18, Scale: 5),
            new("udeci4",                S0DimValueKind.Dec,         "UDeci4",  Precision: 18, Scale: 5),
            new("udeci5",                S0DimValueKind.Dec,         "UDeci5",  Precision: 18, Scale: 5),
            // 🔴 源是 (18,6)，与 UDeci* 的 (18,5) 不同，不得统一
            new("run_time",              S0DimValueKind.Dec,         "RunTime", Precision: 18, Scale: 6),
            new("outsourced_lead_time",  S0DimValueKind.Int,         "OutsourcedLeadTime"),
            new("sort_no",               S0DimValueKind.Int,         "SortNo"),
            new("comment_index",         S0DimValueKind.Int,         "CommentIndex"),
            new("parent_op",             S0DimValueKind.Int,         "ParentOp"),
            // 本表唯一可安全物化的布尔：NOT NULL 且 distinct=2
            new("is_confirmed",          S0DimValueKind.BoolTrue,    "IsConfirm"),
            // 🔴 源列名是 UpdatedAt，不是 UpdateTime
            new("source_updated_at",     S0DimValueKind.DateTimeSec, "UpdatedAt")
        ]);

    /// <summary>
    /// 物料工序生产要素。源 <c>ItemOpCondition</c>，父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + ItemNum + CodeType</b>（实测重复 0 组）。</para>
    ///
    /// <para>🔴 <b><c>IsMain</c> 不入身份 —— 但原因不是框架禁令，而是更下游且无法绕过的一层</b>：
    /// 源列是 <c>tinyint(1) NOT NULL</c>，在 <c>raw_data</c> 里是 JSON <b>BOOLEAN</b>（非 1/0）。
    /// 即便放开 <c>Validate()</c> 允许布尔入键仍然会挂 —— staging 的 <c>source_biz_key</c> 由
    /// <c>mdp_entity.biz_key_expr</c> 驱动、走 C# <c>bool.ToString()</c> 产出 <c>"True"</c>/<c>"False"</c>，
    /// 而源侧 checksum 渲染的是 <c>'1'</c>/<c>'0'</c>，四向集合比对必然全量不等价。
    /// 修它要动全实体共享的 <c>MdpStagingWriter.BuildBizKey</c>。
    /// 旁证：全部 <c>mdp_stg_s0_*</c> 的 <c>source_biz_key</c> 中匹配 <c>True|False</c> 的行数 = <b>0</b>，
    /// 布尔入键在本仓从未发生过。故 <c>IsMain</c> 落 <b>属性</b>，且**必须用 <c>BoolTrue</c>** ——
    /// 用 <c>Int</c> 会把 <c>true</c>/<c>false</c> 双双静默压成 0（比 bit(1) 地雷更毒，不报错不为 NULL），
    /// 用 <c>Str</c> 会得到 <c>'true'</c> 而源侧是 <c>'1'</c>，校验和必挂。</para>
    ///
    /// <para><c>CodeType</c> 实测单值 <c>'Prod'</c> 且控制器硬编码写死、无视 DTO 入参，零区分力；
    /// 保留系防不可逆键收缩（同 <see cref="LinePost"/> 的 <c>job_no</c> 先例），不是因为它有用。</para>
    ///
    /// <para>🔴 <c>ItemCode</c>（→ <c>element_code</c>）是**要素编码**，与 <c>ItemNum</c>（物料编码）
    /// **语义不同**：实测两列相等的行数 = <b>0</b>，且 5/10 为空。任何把它当物料码 join 的代码都是 bug。</para>
    ///
    /// <para><c>Op</c> 虽 10/10 填充且 <c>(ItemNum,Op)→RoutingOpDetail</c> 零孤儿，但不在源 UK 内、
    /// DTO 无 <c>[Required]</c> ⇒ 不入键。**不要因为表名叫 ItemOpCondition 就把 Op 塞进身份。**</para>
    ///
    /// <para>⚠️ dim 唯一键严格弱于源 UK（源含 <c>Domain</c> 与 <c>IsMain</c>），且两个控制器
    /// 均无查重守卫，业务**可以**合法插出同 <c>(tenant,ItemNum,'Prod')</c> 的 IsMain=0/1 两行。
    /// 届时 <c>AssertNoSourceDuplicateAsync</c>（在 purge **之前**）会显式失败、零数据被触碰 ——
    /// 失败可见、可定位、不静默。当前实测 0 例。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemOpCondition = new(
        Key: "ITEM_OP_CONDITION",
        EntityCode: "S0_ITEM_OP_CONDITION",
        SourceTable: "ItemOpCondition",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_op_condition",
        DimTable: "bridge_item_op_condition",
        BusinessKeyColumns: ["tenant_id", "item_code", "code_type"],
        SourceBizKeyColumns: ["ItemNum", "CodeType"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("item_code",         S0DimValueKind.Str,         "ItemNum",  Required: true),
            new("code_type",         S0DimValueKind.Str,         "CodeType", Required: true),
            // 🔴 必须 BoolTrue：Int 会把 true/false 双双静默压成 0，Str 会得到 'true' 而源侧是 '1'
            new("is_main",           S0DimValueKind.BoolTrue,    "IsMain"),
            new("op_code",           S0DimValueKind.Str,         "Op"),
            new("line_code",         S0DimValueKind.Str,         "Line"),
            new("typed_code",        S0DimValueKind.Str,         "Typed"),
            // 🔴 要素编码，**不是** ItemNum（实测两列 0 行相等）
            new("element_code",      S0DimValueKind.Str,         "ItemCode"),
            new("descr",             S0DimValueKind.Str,         "Descr"),
            new("domain_code",       S0DimValueKind.Str,         "Domain"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 物料工序 SOP 文件。源 <c>QualitySegmentImage</c>，父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + item_num + op + image_type_id</b>（实测重复 0 组）。
    /// 源 UNIQUE 还含 <c>domain</c>，但它跨租户口径异构（797 用组织雪花号 <c>797403761152069</c>、
    /// 838257186181189 用 legacy <c>8010</c>/<c>2410</c>），坐实 LEGACY_SCOPE，不入身份。</para>
    ///
    /// <para>🔴 <b>源表没有任何时间列</b>（11 列全清单实测），故**不声明 <c>source_updated_at</c>** ——
    /// 与 <see cref="SopFileType"/> / <see cref="LabelType"/> 同型。**不得为字段齐整而回填。**</para>
    ///
    /// <para>⚠️ 源表那个叫 <c>uk_QualitySegmentImage_scope</c> 的索引**不是唯一索引**
    /// （<c>IsUnique=false</c>）；真正的唯一键是 <c>uk_QualitySegmentImage_scope_unique</c>。**别被名字骗了。**</para>
    ///
    /// <para><c>image_type_id</c> 软引用 <see cref="SopFileType"/> 的 <c>file_type_code</c>（实测 0 孤儿），
    /// 但**不设父** —— 框架只能挂一个父，而本桥的主语是「某物料某工序的 SOP 文件」，
    /// <c>image_type_id</c> 只是该文件的分类（闭集字典）。挂 <c>dim_item</c> 才让
    /// 「S0 ITEM AUTHORITY = dim_item」在一处可强制、可审计；且 <c>ref_sop_file_type</c>
    /// 当前只物化了租户 797，选它作父会让别的租户产出纯刷新顺序噪声的 WARN。
    /// 同 <see cref="LinePostSkill"/> 的 <c>skill_code</c> 先例。</para>
    ///
    /// <para>⚠️ <c>item_num</c> / <c>op</c> / <c>image_type_id</c> 在源 DDL 里**均可空**，
    /// 且 upsert DTO 只有 <c>Domain</c> 带 <c>[Required]</c> ⇒ 业务可合法建 NULL 行 →
    /// 被 <c>RowGuards</c> 整行过滤 → <c>dim_count &lt; stg_count</c> → 阻断 FAIL。
    /// 与 <see cref="EmpWorkDuty"/> 同风险类。当前实测 0 NULL / 0 空串。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemOpImage = new(
        Key: "ITEM_OP_IMAGE",
        EntityCode: "S0_ITEM_OP_IMAGE",
        SourceTable: "QualitySegmentImage",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_op_image",
        DimTable: "bridge_item_op_image",
        BusinessKeyColumns: ["tenant_id", "item_code", "op_code", "file_type_code"],
        SourceBizKeyColumns: ["item_num", "op", "image_type_id"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",      S0DimValueKind.TenantIdColumn),
            new("item_code",      S0DimValueKind.Str, "item_num",      Required: true),
            new("op_code",        S0DimValueKind.Str, "op",            Required: true),
            new("file_type_code", S0DimValueKind.Str, "image_type_id", Required: true),
            new("line_code",      S0DimValueKind.Str, "line"),
            new("file_path",      S0DimValueKind.Str, "path"),
            new("descr",          S0DimValueKind.Str, "descr"),
            new("rev",            S0DimValueKind.Str, "rev"),
            // 源是真 int（非 tinyint(1)），走 Int 安全
            new("sort_id",        S0DimValueKind.Int, "sort_id"),
            new("domain_code",    S0DimValueKind.Str, "domain")
            // 🔴 刻意无 source_updated_at：源表零时间列，不得回填
        ]);

    /// <summary>
    /// BOM 结构（父件-子件用量）。源 <c>ProductStructureMaster</c>（62036 行，S0 最大的表），
    /// 父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + ParentItem + ComponentItem</b>（实测重复 0 组）。
    /// <c>LineOp</c> / <c>Op</c> / <c>SequenceNum</c> 加进去**零增益**（仍是 0 组），故不入身份；
    /// 去掉 <c>ComponentItem</c> 则塌陷成 <b>4341 组 / 60494 行</b>重复。
    /// 旧 UK 含 <c>CompanyRefId</c>+<c>FactoryRefId</c>，不予继承 —— 身份不加它们已然唯一（D-025）。</para>
    ///
    /// <para>🔴🔴 <b>legacy 代理键 <c>ComponentMaterialId</c> / <c>ParentMaterialId</c> 是已实证的跨租户泄漏向量</b>
    /// （2026-09-08 实测）：
    /// <list type="bullet">
    /// <item>同租户解析 <c>ComponentMaterialId → ItemMaster.RecID</c>：<b>170 行解析失败</b>；</item>
    /// <item>忽略租户解析：<b>0 行失败</b> —— 看起来「完美」；</item>
    /// <item>而这 <b>170 行恰恰全部挂到了别的租户的 <c>RecID</c> 上</b>。</item>
    /// </list>
    /// <c>ParentMaterialId</c> 同款，量更大（同租户失败 <b>2060</b>、忽略租户 0）。
    /// 也就是说：**去掉租户条件不会报错，只会静默串租户**。
    /// 而同租户能解析的 61866 行里，代理键解出的码与 <c>ComponentItem</c> <b>61866/61866 完全一致</b>
    /// ⇒ **自然键完全可靠，代理键只带来风险**。故本桥一律走自然键
    /// <c>item_code</c> / <c>component_item_code</c>，两个 id 仅作 legacy 技术属性留痕，
    /// **任何消费方解析它们时必须带 <c>tenant_id</c>**。</para>
    ///
    /// <para>父连接：<c>ParentItem</c> 与 <c>ComponentItem</c> 对 <c>ItemMaster</c> 的孤儿
    /// **同租户与忽略租户都是 0/62036**。框架单父，取 <c>ParentItem</c> 作 <c>item_code</c>
    /// （下游「查某物料的 BOM」天然按父件过滤）；<c>ComponentItem</c> 落
    /// <c>component_item_code</c>，同样零孤儿但不设父。</para>
    ///
    /// <para>🔴 <c>IsActive</c> 是 <b><c>bit(1)</c> 且含 1 行 NULL</b> —— 双重地雷，**不物化**：
    /// 用 <see cref="S0DimValueKind.Int"/> 会让对账每轮必挂（<c>CAST(b'1' AS CHAR)</c> 是裸字节），
    /// 用 <see cref="S0DimValueKind.BoolTrue"/> 会把那 1 行 NULL 整行滤掉 → 行数对账 FAIL。
    /// 同理 <c>IsEnabled</c>（distinct=1 零信息）、<c>SequenceNum</c>（distinct=1）、
    /// <c>StructureType</c>（7.2% 填充但 distinct=1）、<c>LineOp</c>/<c>Remark</c>/<c>StartEff</c>/<c>EndEff</c>
    /// （全库 0 填充）一并不物化。</para>
    ///
    /// <para>⚠️ 单租户最大 <b>57199</b> 行（797），<c>batch_size</c> 取 <b>200000</b>（3.5× 头寸）。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemBom = new(
        Key: "ITEM_BOM",
        EntityCode: "S0_ITEM_BOM",
        SourceTable: "ProductStructureMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_bom",
        DimTable: "bridge_item_bom",
        BusinessKeyColumns: ["tenant_id", "item_code", "component_item_code"],
        SourceBizKeyColumns: ["ParentItem", "ComponentItem"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",              S0DimValueKind.TenantIdColumn),
            new("item_code",              S0DimValueKind.Str,         "ParentItem",    Required: true),
            new("component_item_code",    S0DimValueKind.Str,         "ComponentItem", Required: true),
            new("qty",                    S0DimValueKind.Dec,         "Qty",           Precision: 18, Scale: 5),
            new("unit",                   S0DimValueKind.Str,         "UM"),
            new("scrap",                  S0DimValueKind.Dec,         "Scrap",         Precision: 18, Scale: 5),
            new("qty_consumed",           S0DimValueKind.Dec,         "QtyConsumed",   Precision: 18, Scale: 5),
            new("qty_exchanged",          S0DimValueKind.Dec,         "QtyExchd",      Precision: 18, Scale: 5),
            new("refs",                   S0DimValueKind.Str,         "Refs"),
            new("operation_no",           S0DimValueKind.Int,         "Op"),
            new("company_id",             S0DimValueKind.Int,         "CompanyRefId",  Required: true),
            new("factory_id",             S0DimValueKind.Int,         "FactoryRefId",  Required: true),
            // 🔴 legacy 技术属性，解析时**必须带 tenant_id**（见类型注释的跨租户实证）
            new("legacy_parent_item_id",    S0DimValueKind.Int,       "ParentMaterialId",    Required: true),
            new("legacy_component_item_id", S0DimValueKind.Int,       "ComponentMaterialId", Required: true),
            new("source_updated_at",      S0DimValueKind.DateTimeSec, "UpdatedAt")
        ]);

    /// <summary>
    /// 替代料。源 <c>ItemSubstituteDetail</c>，父 = <see cref="Item"/>。
    ///
    /// <para><b>身份 = tenant + ParentItem + ItemNum + SubstituteItem</b>（实测重复 0 组）。
    /// 虽然 <c>tenant+ItemNum+SubstituteItem</c> 当前也是 0 组，但全表仅 <b>16 行</b>，
    /// 这点样本证明不了 <c>ParentItem</c> 可去；而实测 <c>ParentItem</c> 与 <c>ItemNum</c>
    /// <b>16 行无一相等</b>（distinct 9 vs 14），是**真实不同的信息**
    /// —— 去掉即不可逆的键收缩，故保留（同 <see cref="LinePost"/> 的 <c>job_no</c> 先例）。
    /// <c>Domain</c> 在旧 UK 内，按 D-025 落 LEGACY_SCOPE 不入身份。</para>
    ///
    /// <para>三个 item 引用（<c>ParentItem</c> / <c>ItemNum</c> / <c>SubstituteItem</c>）
    /// **全部统一到 <c>dim_item</c> 的自然键 <c>tenant + item_code</c>**，实测孤儿各 0/16。
    /// 框架单父，取被替代的 <c>ItemNum</c> 作 <c>item_code</c>（本行的主语是「这个料有哪些替代」）；
    /// 另两个落 <c>parent_item_code</c> / <c>substitute_item_code</c>，同样零孤儿但不设父。</para>
    /// </summary>
    public static readonly S0DimDefinition ItemSubstitute = new(
        Key: "ITEM_SUBSTITUTE",
        EntityCode: "S0_ITEM_SUBSTITUTE",
        SourceTable: "ItemSubstituteDetail",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_item_substitute",
        DimTable: "bridge_item_substitute",
        BusinessKeyColumns: ["tenant_id", "parent_item_code", "item_code", "substitute_item_code"],
        SourceBizKeyColumns: ["ParentItem", "ItemNum", "SubstituteItem"],
        ParentDimTable: "dim_item",
        ParentKeyColumns: ["item_code"],
        Columns:
        [
            new("tenant_id",            S0DimValueKind.TenantIdColumn),
            new("parent_item_code",     S0DimValueKind.Str,         "ParentItem",     Required: true),
            new("item_code",            S0DimValueKind.Str,         "ItemNum",        Required: true),
            new("substitute_item_code", S0DimValueKind.Str,         "SubstituteItem", Required: true),
            new("substitute_qty",       S0DimValueKind.Dec,         "SubstituteQty",  Precision: 18, Scale: 6),
            new("substitute_type",      S0DimValueKind.Str,         "SubstituteType"),
            new("remark",               S0DimValueKind.Str,         "Remark"),
            new("domain_code",          S0DimValueKind.Str,         "Domain",         Required: true),
            new("source_updated_at",    S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    // ════════════════════════════════════════════════════════════════════════════
    // C3 · 关系 / 明细桥接（bridge_*）
    // ════════════════════════════════════════════════════════════════════════════

    /// <summary>
    /// 员工物料职责桥。源 <c>EmpWorkDutyMaster</c>。
    ///
    /// <para>身份 = <c>tenant_id + Employee + Duty + Location</c>。
    /// <b><c>location_code</c> 不可省</b> —— 实测 <c>tenant+Employee+Duty</c> 有 1 组重复：
    /// 租户 797…229 的 <c>G00308</c> 在同一串 Duty 下有两行，分别是 <c>Location=1001</c>
    /// 与 <c>Location=1000</c>（物料也不同）⇒ 库位是真实的区分维，不是 legacy scope。
    /// 加上 Location 后租户内重复 = 0。</para>
    ///
    /// <para>挂父有业务依据：本表是少数**真正强制父存在性**的 CRUD ——
    /// <c>AdoS0EmpWorkDutiesController</c> 写入前调 <c>EmployeeExistsInTenantAsync</c>。
    /// 实测父孤儿 0/25。父键取 <c>["employee_code"]</c>，与 <c>dim_employee</c> 身份对齐。</para>
    ///
    /// <para>⚠️ CRUD **无查重守卫**且 DTO 的 <c>Duty</c>/<c>Location</c> 是 <c>string?</c> 无 <c>[Required]</c>
    /// ⇒ 业务可以合法建出 NULL 行，而它们是 Required 业务键，会被 RowGuards 整行过滤导致对账 FAIL。
    /// 当前实测 0 NULL / 0 空串，verify 与运行验收都显式断言这一点。</para>
    /// </summary>
    public static readonly S0DimDefinition EmpWorkDuty = new(
        Key: "EMP_WORK_DUTY",
        EntityCode: "S0_EMP_WORK_DUTY",
        SourceTable: "EmpWorkDutyMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_emp_work_duty",
        DimTable: "bridge_employee_work_duty",
        BusinessKeyColumns: ["tenant_id", "employee_code", "duty", "location_code"],
        SourceBizKeyColumns: ["Employee", "Duty", "Location"],
        ParentDimTable: "dim_employee",
        ParentKeyColumns: ["employee_code"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("employee_code",     S0DimValueKind.Str,         "Employee",       Required: true),
            new("duty",              S0DimValueKind.Str,         "Duty",           Required: true),
            new("location_code",     S0DimValueKind.Str,         "Location",       Required: true),
            new("domain_code",       S0DimValueKind.Str,         "Domain",         Required: true),
            new("company_id",        S0DimValueKind.Int,         "company_ref_id", Required: true),
            new("factory_id",        S0DimValueKind.Int,         "factory_ref_id", Required: true),
            new("line_code",         S0DimValueKind.Str,         "ProdLine"),
            new("item_num",          S0DimValueKind.Str,         "ItemNum"),
            new("item_num_from",     S0DimValueKind.Str,         "ItemNum1"),
            new("item_num_to",       S0DimValueKind.Str,         "ItemNum2"),
            new("emp_type",          S0DimValueKind.Str,         "EmpType"),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 产线岗位。源 <c>LineSkillMaster</c>。与 <see cref="LinePostSkill"/> 共用
    /// <c>mdp_stg_s0_line_post</c>，靠 <c>source_table</c> 隔离（同 Location/LocationShelf 范式）。
    ///
    /// <para>身份 = <c>tenant_id + ProdLine + JOBNo</c>，实测租户内重复 0；
    /// <c>Domain</c> 每租户单值 ⇒ LEGACY_SCOPE，不入身份。
    /// <c>JOBNo</c> 当前每租户只有一个取值（<c>102</c>），零区分力，但它是 CRUD 必填的岗位码，
    /// **保留在身份中** —— 去掉会造成不可逆的键收缩，将来多岗位时无法恢复。</para>
    ///
    /// <para><b>不挂父维度</b>，三条理由：① <c>ProdLine → LineMaster.Line</c> 同租户孤儿 28/57，
    /// 且这 28 个码在**任何租户**都不存在（是被引用主数据整体缺失，不是租户错挂）；
    /// ② CRUD 对 <c>ProdLine</c> 不做任何存在性校验（对比 EmpWorkDuty 有 <c>EmployeeExistsInTenantAsync</c>）；
    /// ③ 与既有范式一致 —— <c>dim_line.location_code</c> / <c>dim_employee.work_center_code</c>
    /// 都是同名软引用、不声明父。挂父只会每轮产出无人能闭环的 WARN。</para>
    ///
    /// <para>🔴 源侧 <c>IX_LineSkillMaster</c> 含 <c>Site</c> 而 Site **0/57 全 NULL**，
    /// MySQL UNIQUE 对 NULL 永不判等 ⇒ **源侧当前对本表没有任何唯一性约束**，
    /// 观测到的 0 重复是无守卫的巧合。dim 的唯一键将是第一道真守卫。</para>
    ///
    /// <para>⚠️ 3 行 <c>ProdLine</c> 带尾随空格（<c>'A01 '</c>/<c>'S01 '</c>/<c>'S02 '</c>）。
    /// <c>utf8mb4_0900_ai_ci</c> 是 NO PAD，尾空格参与比较，是真实业务键差异 —— **原样透传，禁止 TRIM**。</para>
    /// </summary>
    public static readonly S0DimDefinition LinePost = new(
        Key: "LINE_POST",
        EntityCode: "S0_LINE_POST",
        SourceTable: "LineSkillMaster",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_line_post",
        DimTable: "dim_line_post",
        BusinessKeyColumns: ["tenant_id", "line_code", "job_no"],
        SourceBizKeyColumns: ["ProdLine", "JOBNo"],
        Columns:
        [
            new("tenant_id",         S0DimValueKind.TenantIdColumn),
            new("line_code",         S0DimValueKind.Str,         "ProdLine", Required: true),
            new("job_no",            S0DimValueKind.Str,         "JOBNo",    Required: true),
            new("domain_code",       S0DimValueKind.Str,         "Domain",   Required: true),
            new("job_name",          S0DimValueKind.Str,         "JOBDescr"),
            // 0/57 全空，但它在源 UK 里 —— 保留可见性，否则将来身份被破坏时看不出原因
            new("site",              S0DimValueKind.Str,         "Site"),
            new("order_by",          S0DimValueKind.Int,         "Orderby"),
            // Precision/Scale 必须与源 decimal(10,3) 逐位相同：对账两侧都走 CAST(expr AS CHAR)，
            // scale 不同会让 '0.000' 与 '0.0' 不等，属性校验和当场 FAIL。
            new("run_crew",          S0DimValueKind.Dec,         "RunCrew", Precision: 10, Scale: 3),
            new("source_updated_at", S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>
    /// 产线岗位技能桥。源 <c>LineSkillDetail</c> —— **本仓第 4 张 dual-column 表，且是最危险的一张**。
    ///
    /// <para>🔴 它的四对双列里有三对是「有值但发散」型（影子列 250/261 非空，
    /// 但与真列**没有一行相等**）—— 取错不会得到 NULL，会得到**看起来合法的错值**：
    /// <c>RecID</c>(真) vs <c>id</c>(影) · <c>LineSkillRecID</c>(真) vs <c>line_skill_master_id</c>(影) ·
    /// <c>PersonSkillId</c>(真) vs <c>person_skill_id</c>(影)。
    /// 第四对是恒空型：<c>StartDate</c>(真, 250/261) vs <c>effective_date</c>(影, **0/261**)。
    /// ⚠️ 本 dim 的目标列**取名** <c>effective_date</c>，而它的源物理列是 <c>StartDate</c> ——
    /// 名字与源表那个影子列同名，是本批最容易取错的一处，已加契约测试钉死。</para>
    ///
    /// <para><b>父连接必须走自然键</b>：代理键已被污染 ——
    /// <c>LineSkillRecID → LineSkillMaster.RecID</c> 同租户孤儿 **210/261**，忽略租户后
    /// **175 行解析到别的租户**；<c>PersonSkillId</c> 更甚，**250/261 属于别的租户**。
    /// 自然键 <c>(tenant, ProdLine, JOBNo)</c> 连父三租户**全 0 孤儿**。
    /// 两个 legacy id 只作留痕列物化，**任何 join 都不得使用**。</para>
    ///
    /// <para><c>SkillNo</c> 同租户在 <c>PersonSkill</c> 不命中 210/261 ——
    /// **不因为都叫 Skill 就建父子关系**（与 <see cref="PersonSkill"/> 已有的同款否决一致）。</para>
    /// </summary>
    public static readonly S0DimDefinition LinePostSkill = new(
        Key: "LINE_POST_SKILL",
        EntityCode: "S0_LINE_POST_SKILL",
        SourceTable: "LineSkillDetail",
        SourceSystem: LocalSourceSystem,
        StagingTable: "mdp_stg_s0_line_post",
        DimTable: "bridge_line_post_skill",
        BusinessKeyColumns: ["tenant_id", "line_code", "job_no", "skill_code"],
        SourceBizKeyColumns: ["ProdLine", "JOBNo", "SkillNo"],
        ParentDimTable: "dim_line_post",
        ParentKeyColumns: ["line_code", "job_no"],
        Columns:
        [
            new("tenant_id",                S0DimValueKind.TenantIdColumn),
            new("line_code",                S0DimValueKind.Str,         "ProdLine", Required: true),
            new("job_no",                   S0DimValueKind.Str,         "JOBNo",    Required: true),
            new("skill_code",               S0DimValueKind.Str,         "SkillNo",  Required: true),
            // 源可空（虽然 261/261 有值）：设 Required 会让未来的 NULL 行被静默滤掉并引发全批 FAIL
            new("domain_code",              S0DimValueKind.Str,         "Domain"),
            new("site",                     S0DimValueKind.Str,         "Site"),
            // 🔴 源物理列是 StartDate，**不是**同表那个 0/261 的影子列 effective_date
            new("effective_date",           S0DimValueKind.DateTimeSec, "StartDate"),
            new("required_level",           S0DimValueKind.Str,         "required_level"),
            new("remark",                   S0DimValueKind.Str,         "remark"),
            new("is_enabled",               S0DimValueKind.BoolTrue,    "is_enabled"),
            // 仅留痕，禁止 join —— 见类型注释
            new("legacy_line_skill_rec_id", S0DimValueKind.Int,         "LineSkillRecID"),
            new("legacy_person_skill_id",   S0DimValueKind.Int,         "PersonSkillId"),
            new("source_updated_at",        S0DimValueKind.DateTimeSec, "UpdateTime")
        ]);

    /// <summary>全部维度，按依赖顺序（父在前，子在后 —— 孤儿判定需要父维度先就绪）。</summary>
    public static readonly IReadOnlyList<S0DimDefinition> All =
    [
        // C1 主数据
        WorkCenter, Department, Location, LocationShelf, Employee, Line, Customer, PersonSkill,
        // C2-1 独立字典
        LabelType, SopFileType, QualityBaseType,
        // C2-2 qms 字典族（共用 mdp_stg_s0_qms_dict）
        SamplingScheme, InspectionItem, InspectionMethod, InspectionFrequency, InspectionInstrument,
        // C1 扩展：物料（S0 Item 权威；后续 6 张 C3 都要挂它作父，故必须排在 C3 之前）
        Item,
        // C3 关系桥（EmpWorkDuty 的父 dim_employee 在前；LinePostSkill 的父 LinePost 紧邻其前）
        EmpWorkDuty, LinePost, LinePostSkill,
        // C3-A 物料桥（父 dim_item，必须排在 Item 之后）
        ItemOpLine, ItemRoutingOp,
        // C3-C 物料桥（父 dim_item）
        ItemOpCondition, ItemOpImage,
        // C3-B 物料桥（父 dim_item）
        ItemBom, ItemSubstitute
    ];

    /// <summary>按 Key 取维度（大小写不敏感）；不存在返回 null。</summary>
    public static S0DimDefinition? Find(string? key) =>
        string.IsNullOrWhiteSpace(key)
            ? null
            : All.FirstOrDefault(d => string.Equals(d.Key, key.Trim(), StringComparison.OrdinalIgnoreCase));

    /// <summary>校验全部声明；任一不合法即抛出（供启动自检与单测使用）。</summary>
    public static void ValidateAll()
    {
        foreach (var d in All) d.Validate();

        var dupDim = All.GroupBy(d => d.DimTable, StringComparer.Ordinal).FirstOrDefault(g => g.Count() > 1);
        if (dupDim is not null)
            throw new InvalidOperationException(
                $"dim 表被多个 definition 共用：{dupDim.Key} —— FULL Replace 按 tenant 整表删除，会互相清空");

        var dupEntity = All.GroupBy(d => d.EntityCode, StringComparer.Ordinal).FirstOrDefault(g => g.Count() > 1);
        if (dupEntity is not null)
            throw new InvalidOperationException($"entity_code 重复：{dupEntity.Key}");

        // 同一 staging 被多个 definition 共用时，source_table 必须互异，否则 purge/物化会互相污染
        foreach (var g in All.GroupBy(d => d.StagingTable, StringComparer.Ordinal).Where(g => g.Count() > 1))
        {
            var tables = g.Select(d => d.SourceTable).ToList();
            if (tables.Distinct(StringComparer.Ordinal).Count() != tables.Count)
                throw new InvalidOperationException($"staging {g.Key} 被多个 definition 共用且 source_table 重复");
        }
    }
}