AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.AiDOP/Controllers/S0/Quality/AdoS0QmsSpecAggregateGuard.cs

using Admin.NET.Plugin.AiDOP.Dto.S0.Quality;
using Admin.NET.Plugin.AiDOP.Entity.S0.Quality;

namespace Admin.NET.Plugin.AiDOP.Controllers.S0.Quality;

/// <summary>
/// 检验规范聚合（主单 + 检验明细）的必填契约守卫。
///
/// 契约来源：UAT-S0-10 拍板（2026-09-02）。此前四张检规表在前端表单、后端 DTO、DB 列三层
/// 都只约束「文件编号」，导致只填文件编号即可落库空壳检规。本守卫是该契约的唯一实现处，
/// Create / Import 两条写入入口共用，避免再次出现「导入宽于表单」。
///
/// 两条入口的规则不同，刻意分成两个方法：
/// · 新增（Create / Import）——必填字段必须全部有值，且至少 1 条有内容的检验明细；
/// · 编辑（Update）——「历史兼容、禁止劣化」：历史记录原本就缺的字段允许继续为空，
///   但原本有值的必填字段不允许被清空；原本 0 明细允许保持 0，原本有明细不允许删空。
///
/// 【为什么四张检规表的 DTO 上一个 [Required] 都不留】
/// Create 与 Update 共用同一个 UpsertDto。任何 [Required] 都会在 MVC 模型绑定阶段先于本守卫触发，
/// 把 Update 直接挡成 400，从而绕过并破坏 ValidateUpdate(existing, incoming) 的历史兼容语义
/// ——实测 qms_gcjygf 有 3 行 wjbh 为空，正是被遗留的 FileNumber[Required] 锁死不可编辑。
/// 因此「文件编号」的新增必填也统一迁到本守卫，特性层不再承担任何必填职责。
///
/// 【明细归一化】全空明细是 UI 占位行 / Excel 空行，不是业务明细，一律不落库。
/// Create / Update / Import 三条入口都必须先经 Meaningful(...) 过滤，再用过滤结果做数量校验与写入，
/// 保证「校验看到的」与「写进库的」是同一份数据。
/// </summary>
public static class AdoS0QmsSpecAggregateGuard
{
    /// <summary>新增校验。返回 null 表示通过，否则为面向用户的错误文案。</summary>
    public static string? ValidateCreate(IReadOnlyList<(string Label, string? Value)> requiredFields, int meaningfulItemCount)
    {
        foreach (var (label, value) in requiredFields)
        {
            if (string.IsNullOrWhiteSpace(value)) return $"{label}不能为空";
        }
        return meaningfulItemCount > 0 ? null : "检验明细至少需要 1 条";
    }

    /// <summary>编辑校验（历史兼容、禁止劣化）。返回 null 表示通过，否则为面向用户的错误文案。</summary>
    public static string? ValidateUpdate(
        IReadOnlyList<(string Label, string? Existing, string? Incoming)> requiredFields,
        int existingMeaningfulItemCount,
        int incomingMeaningfulItemCount)
    {
        foreach (var (label, existing, incoming) in requiredFields)
        {
            // 原本为空 → 放行（不强制本次补齐）；原本有值 → 不允许清空。
            if (!string.IsNullOrWhiteSpace(existing) && string.IsNullOrWhiteSpace(incoming))
                return $"{label}原本已有值，不允许清空";
        }
        // 两侧都按 meaningful 计：历史若本就 0 条有内容的明细，允许继续保持 0。
        if (existingMeaningfulItemCount > 0 && incomingMeaningfulItemCount == 0)
            return $"该检规原有 {existingMeaningfulItemCount} 条检验明细，不允许全部删除";
        return null;
    }

    // ==================== 明细归一化 ====================
    //
    // 两个不同的集合，不可混用：
    //
    // · Meaningful(...)     —— 「有业务内容」的明细。用于 Create 的写入集，以及三条入口的**数量校验**。
    // · ForUpdateWrite(...) —— Update 的写入集 = Meaningful ∪ 已持久化行（带 Id）。
    //
    // 为什么 Update 需要单独一个写入集：Update 的明细是 **delete-all + 全量重建** 语义
    // （`AsDeleteable().Where(MasterId==id)` 后逐条 Insert，且 SyncXxxEntriesAsync 不回填 item.Id）。
    // 若直接拿 Meaningful 去重建，用户只是编辑一次头字段，库里**历史已存在的空明细就会被静默删掉**
    // ——实测 aidopdev 有 10 条这样的空明细，分布在 9 张真实业务主单上（如 W00-1-80 的 69 条明细里有 2 条）。
    // 本轮不是历史数据清洗批次，因此按 detail identity 区分：
    //   带 Id  = 库里已有的行 → 即使为空也照原样写回，不主动删除；
    //   无 Id  = 本次 UI/Excel 新补的空占位 → 丢弃，不新增空记录。
    //
    // ⚠️ 已知既有局限（非本轮引入）：重建会让所有明细拿到新的雪花 Id，明细身份本就不跨 Update 保持。
    //    这里只保证**内容**不被顺手清理；若将来要真正保持身份，需另开批次改成按 Id diff 的增量更新。

    public static List<AdoS0QmsRawInspectionSpecEntryDto> Meaningful(IEnumerable<AdoS0QmsRawInspectionSpecEntryDto> items)
        => items.Where(HasValue).ToList();

    public static List<AdoS0QmsProcessInspectionSpecEntryDto> Meaningful(IEnumerable<AdoS0QmsProcessInspectionSpecEntryDto> items)
        => items.Where(HasValue).ToList();

    public static List<AdoS0QmsFqcInspectionSpecEntryDto> Meaningful(IEnumerable<AdoS0QmsFqcInspectionSpecEntryDto> items)
        => items.Where(HasValue).ToList();

    public static List<AdoS0QmsOqcInspectionSpecEntryDto> Meaningful(IEnumerable<AdoS0QmsOqcInspectionSpecEntryDto> items)
        => items.Where(HasValue).ToList();

    public static List<AdoS0QmsRawInspectionSpecEntryDto> ForUpdateWrite(IEnumerable<AdoS0QmsRawInspectionSpecEntryDto> items)
        => items.Where(x => HasValue(x) || x.Id.HasValue).ToList();

    public static List<AdoS0QmsProcessInspectionSpecEntryDto> ForUpdateWrite(IEnumerable<AdoS0QmsProcessInspectionSpecEntryDto> items)
        => items.Where(x => HasValue(x) || x.Id.HasValue).ToList();

    public static List<AdoS0QmsFqcInspectionSpecEntryDto> ForUpdateWrite(IEnumerable<AdoS0QmsFqcInspectionSpecEntryDto> items)
        => items.Where(x => HasValue(x) || x.Id.HasValue).ToList();

    public static List<AdoS0QmsOqcInspectionSpecEntryDto> ForUpdateWrite(IEnumerable<AdoS0QmsOqcInspectionSpecEntryDto> items)
        => items.Where(x => HasValue(x) || x.Id.HasValue).ToList();

    // 实体侧判据：统计库里**现存的 meaningful 明细数**。
    // 「原有 ≥1 明细不许删空」必须按 meaningful 计数，否则一张明细全为空的历史主单
    // 会因 raw count>0 而永远保存不了（被自己的空占位锁死）。

    public static int CountMeaningful(IEnumerable<AdoS0QmsRawInspectionSpecEntry> rows)
        => rows.Count(e => e.Seq.HasValue
            || AnyNotBlank(e.InspectionItem, e.InspectionStandard, e.InspectionMethod, e.ImageCategory,
                e.SamplingScheme, e.Remark, e.Attachment, e.UpperLimit, e.LowerLimit));

    public static int CountMeaningful(IEnumerable<AdoS0QmsProcessInspectionSpecEntry> rows)
        => rows.Count(e => e.PeelingForce.HasValue
            || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
                e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit));

    public static int CountMeaningful(IEnumerable<AdoS0QmsFqcInspectionSpecEntry> rows)
        => rows.Count(e => e.PeelingForce.HasValue
            || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
                e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit));

    public static int CountMeaningful(IEnumerable<AdoS0QmsOqcInspectionSpecEntry> rows)
        => rows.Count(e => e.PeelingForce.HasValue
            || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
                e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit));

    // ==================== 明细「有内容」判据 ====================
    // 整行全空的明细不计数、不落库，否则前端 openCreate 自动补的那一行空明细
    // 会让「≥1 条」形同虚设，并持续制造新的空明细脏数据。
    //
    // 导入行（ImportRow）的重载与实体侧同语义，只是模板列少了图像分类/备注/附件等非模板列——
    // 判据仍集中在本类，导入侧不再自带一份定义。

    public static bool HasDetailValue(AdoS0QmsRawInspectionSpecImportRow r)
        => r.Seq.HasValue
           || AnyNotBlank(r.InspectionItem, r.InspectionStandard, r.InspectionMethod,
               r.SamplingScheme, r.UpperLimit, r.LowerLimit);

    public static bool HasDetailValue(AdoS0QmsProcessLikeInspectionSpecImportRow r)
        => AnyNotBlank(r.OperationCode, r.OperationName, r.InspectionItem, r.InspectionMethod,
            r.InspectionSpec, r.InspectionFrequency, r.UpperLimit, r.LowerLimit);

    public static bool HasValue(AdoS0QmsRawInspectionSpecEntryDto e)
        => e.Seq.HasValue
           || AnyNotBlank(e.InspectionItem, e.InspectionStandard, e.InspectionMethod, e.ImageCategory,
               e.SamplingScheme, e.Remark, e.Attachment, e.UpperLimit, e.LowerLimit);

    public static bool HasValue(AdoS0QmsProcessInspectionSpecEntryDto e)
        => e.PeelingForce.HasValue
           || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
               e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit);

    public static bool HasValue(AdoS0QmsFqcInspectionSpecEntryDto e)
        => e.PeelingForce.HasValue
           || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
               e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit);

    public static bool HasValue(AdoS0QmsOqcInspectionSpecEntryDto e)
        => e.PeelingForce.HasValue
           || AnyNotBlank(e.OperationCode, e.OperationName, e.InspectionItem, e.InspectionMethod, e.InspectionSpec,
               e.ImageCategory, e.InspectionFrequency, e.TechnicalStandard, e.UpperLimit, e.LowerLimit);

    // ==================== 成品检验规范（qms_ccjygf / qms_ccjygfzb）====================
    // 与上面四组同语义，只是字段集不同：成品检规明细不含工序代号/工序名称/图像分类/检验频次/PeelingForce，
    // 改为承载 S7 检验单快照真正消费的列（序号/录入类型/上下限/技术要求/仪器/条款/抽样方案/记录/尺寸规格）。

    public static List<AdoS0QmsFinishedInspectionSpecEntryDto> Meaningful(IEnumerable<AdoS0QmsFinishedInspectionSpecEntryDto> items)
        => items.Where(HasValue).ToList();

    public static List<AdoS0QmsFinishedInspectionSpecEntryDto> ForUpdateWrite(IEnumerable<AdoS0QmsFinishedInspectionSpecEntryDto> items)
        => items.Where(x => HasValue(x) || x.Id.HasValue).ToList();

    public static int CountMeaningful(IEnumerable<AdoS0QmsFinishedInspectionSpecEntry> rows)
        => rows.Count(e => AnyNotBlank(e.SeqNo, e.InspectionItem, e.ResultType, e.UpperLimit, e.LowerLimit,
            e.TechnicalRequirement, e.InspectionMethod, e.Instrument, e.InspectionClause,
            e.TechnicalStandard, e.SamplingPlan, e.Record, e.SizeSpecifications));

    public static bool HasValue(AdoS0QmsFinishedInspectionSpecEntryDto e)
        => AnyNotBlank(e.SeqNo, e.InspectionItem, e.ResultType, e.UpperLimit, e.LowerLimit,
            e.TechnicalRequirement, e.InspectionMethod, e.Instrument, e.InspectionClause,
            e.TechnicalStandard, e.SamplingPlan, e.Record, e.SizeSpecifications);

    public static bool HasDetailValue(AdoS0QmsFinishedInspectionSpecImportRow r)
        => AnyNotBlank(r.SeqNo, r.InspectionItem, r.ResultType, r.UpperLimit, r.LowerLimit,
            r.TechnicalRequirement, r.InspectionMethod, r.Instrument,
            r.TechnicalStandard, r.SamplingPlan, r.SizeSpecifications);

    /// <summary>
    /// 成品检规明细的**运行期可用性**校验（S0 侧前置，避免把注定生成不了检验单的检规存进库）。
    /// 口径与 `FqcApplyService.GenerateInspection` 的三条兜底一致：
    ///  ① 检验项目非空；② lrlx 仅 NUMERIC/NON_NUMERIC/空；③ NUMERIC 的上下限须是数值且 下限≤上限。
    /// 返回 null 表示通过。
    /// </summary>
    public static string? ValidateFinishedEntries(IReadOnlyList<AdoS0QmsFinishedInspectionSpecEntryDto> items)
    {
        foreach (var e in items)
        {
            if (string.IsNullOrWhiteSpace(e.InspectionItem))
                return "存在未填写「检验项目」的明细行，该检规将无法生成检验单";

            var type = (e.ResultType ?? string.Empty).Trim().ToUpperInvariant();
            if (type.Length > 0 && type != "NUMERIC" && type != "NON_NUMERIC")
                return $"检验项目「{e.InspectionItem}」的录入类型非法，只能是 NUMERIC 或 NON_NUMERIC";

            var upper = (e.UpperLimit ?? string.Empty).Trim();
            var lower = (e.LowerLimit ?? string.Empty).Trim();
            var hasLimit = upper.Length > 0 || lower.Length > 0;

            if (type == "NON_NUMERIC" && hasLimit)
                return $"检验项目「{e.InspectionItem}」是非数值型，不能配置上下限";

            if (!hasLimit) continue;

            if (!decimal.TryParse(upper, out var u) && upper.Length > 0)
                return $"检验项目「{e.InspectionItem}」的上限必须是数值";
            if (!decimal.TryParse(lower, out var l) && lower.Length > 0)
                return $"检验项目「{e.InspectionItem}」的下限必须是数值";
            if (upper.Length > 0 && lower.Length > 0 && l > u)
                return $"检验项目「{e.InspectionItem}」的下限不能大于上限";
        }
        return null;
    }

    private static bool AnyNotBlank(params string?[] values)
    {
        foreach (var v in values)
        {
            if (!string.IsNullOrWhiteSpace(v)) return true;
        }
        return false;
    }
}