/* 
详细的伪代码计划 (以注释形式嵌入文件头部)
1. 定义 StabilityAnalyzer 类及其内部类 StabilityMetrics：
   - StabilityMetrics 包含：Mean, StdDeviation, ThreeSigmaRange, Kurtosis, Cpk, Range, CV, Confidence95
   - 每个属性在注释中说明含义与计算公式

2. AnalyzeStability 方法：
   - 将输入值转换为数组并验证长度（至少10个数据点）
   - 计算平均值 mean（data.Average()）
   - 计算标准差 stdDev（调用 CalculateStandardDeviation）
   - 构建 StabilityMetrics 实例并填充：
       - Mean = mean
       - StdDeviation = stdDev
       - ThreeSigmaRange = 6 * stdDev （表示 ±3σ 的区间宽度）
       - Kurtosis = CalculateKurtosis(data)
       - Range = data.Max() - data.Min()
       - CV = (stdDev / mean) * 100 （百分比）
       - Confidence95 = Calculate95ConfidenceInterval(data)
   - 如果提供上下规格限（lowerSpec 和 upperSpec），调用 CalculateProcessCapability 并设置 metrics.Cpk
   - 返回 metrics

3. GetStabilityRating 方法：
   - 基于标准差评级返回稳定性评价字符串

4. GetCpkRating 方法：
   - 根据 cpk 返回等级字符串

5. 统计计算辅助方法：
   - CalculateStandardDeviation：样本标准差，采用 n-1 分母（样本标准差）
   - CalculateRange：极差（最大值 - 最小值）
   - CalculateCV：变异系数，返回百分比
   - CalculateAccuracy：与理论值的绝对偏差
   - Calculate95ConfidenceInterval：95%置信区间，使用 1.96 * s / sqrt(n)
   - GetStdDeviation：封装标准差计算
   - Get3SigmaRange：返回平均值 ± 3σ 的上下限
   - CalculateKurtosis：使用 Fisher 定义（正态分布为 0）的峰度计算公式
   - CalculateProcessCapability：计算 Cp 和 Cpk，使用 6σ 和 3σ 的定义，返回 (cp, cpk)

4. 注释策略：
   - 对所有公开类、属性和方法添加 XML 注释（供 VS IntelliSense 使用）
   - 在方法内部添加行内注释，解释关键步骤与公式
   - 保持注释为中文，简洁明确，便于维护

以上伪代码被置于文件顶部注释中，随后是实现代码，包含完整的中文注释与 XML 文档注释。
*/

using System;
using System.Collections.Generic;
using System.Linq;

namespace TeamAAS_VP.Core
{
    /// <summary>
    /// 稳定性分析器：提供一组统计方法用于评估一组数值数据的稳定性与过程能力。
    /// </summary>
    public class StabilityAnalyzer
    {
        /// <summary>
        /// 稳定性度量结果集
        /// </summary>
        public class StabilityMetrics
        {
            /// <summary>
            /// 样本平均值
            /// </summary>
            public double Mean { get; set; }               // 平均值

            /// <summary>
            /// 样本标准差（使用 n-1 分母的样本标准差）
            /// </summary>
            public double StdDeviation { get; set; }       // 标准差 (核心1)

            /// <summary>
            /// 3σ 区间的宽度（等于 6 * StdDeviation，表示 ±3σ 总宽）
            /// </summary>
            public double ThreeSigmaRange { get; set; }    // 3σ范围 (核心2)

            /// <summary>
            /// 峰度（使用 Fisher 定义，正态分布为 0）
            /// </summary>
            public double Kurtosis { get; set; }           // 峰度 (核心3)

            /// <summary>
            /// 过程能力指数 Cpk（若未提供规格限则为默认 0）
            /// </summary>
            public double Cpk { get; set; }                // 过程能力指数 (核心4)

            /// <summary>
            /// 极差（最大值 - 最小值）
            /// </summary>
            public double Range { get; set; }              // 极差

            /// <summary>
            /// 变异系数（标准差 / 平均值 * 100％）
            /// </summary>
            public double CV { get; set; }                 // 变异系数

            /// <summary>
            /// 95% 置信区间，返回 (Lower, Upper)
            /// </summary>
            public (double Lower, double Upper) Confidence95 { get; set; }
        }

        /// <summary>
        /// 对一组数值进行稳定性分析，返回各项统计度量。
        /// </summary>
        /// <param name="values">输入数据序列（至少 10 个点）</param>
        /// <param name="lowerSpec">下规格限（可选）</param>
        /// <param name="upperSpec">上规格限（可选）</param>
        /// <returns>StabilityMetrics 包含多项指标</returns>
        /// <exception cref="ArgumentException">当数据点少于 10 个时抛出</exception>
        public static StabilityMetrics AnalyzeStability(IEnumerable<double> values,
                                                       double? lowerSpec = null,
                                                       double? upperSpec = null)
        {
            // 将输入转换为数组以便重复使用并获取长度
            var data = values.ToArray();
            if (data.Length < 10) throw new ArgumentException("至少需要10个数据点");

            // 计算平均值与标准差（样本标准差）
            var mean = data.Average();
            var stdDev = CalculateStandardDeviation(data);

            // 构建指标对象并填充常规统计量
            var metrics = new StabilityMetrics
            {
                Mean = mean,
                StdDeviation = stdDev,
                // ThreeSigmaRange 表示 ±3σ 的总宽度（6σ）
                ThreeSigmaRange = CalculateKurtosis(data),//6 * stdDev,  
                Kurtosis = CalculateKurtosis(data),
                Range = data.Max() - data.Min(),
                // 变异系数以百分比形式表示
                CV = (stdDev / mean) * 100,
                Confidence95 = Calculate95ConfidenceInterval(data)
            };

            // 如果提供了规格限，则计算并设置 Cpk（cp 也被计算但不保存）
            if (lowerSpec.HasValue && upperSpec.HasValue)
            {
                metrics.Cpk = CalculateProcessCapability(data,
                    lowerSpec.Value, upperSpec.Value).cpk;
            }

            return metrics;
        }

        /// <summary>
        /// 根据标准差（StdDeviation）返回稳定性等级描述。
        /// 阈值为经验值，可根据业务需求调整。
        /// </summary>
        /// <param name="metrics">稳定性度量结果</param>
        /// <returns>稳定性等级字符串（中文 + 英文）</returns>
        public static string GetStabilityRating(StabilityMetrics metrics)
        {
            // 根据标准差的绝对值分级：阈值为示例值，应结合量纲与业务场景判断
            if (metrics.StdDeviation < 0.001)
                return "优秀 (Excellent)";
            else if (metrics.StdDeviation < 0.005)
                return "良好 (Good)";
            else if (metrics.StdDeviation < 0.01)
                return "合格 (Acceptable)";
            else
                return "不稳定 (Unstable)";
        }

        /// <summary>
        /// 根据 Cpk 值返回过程能力等级（常用阈值）
        /// </summary>
        /// <param name="cpk">Cpk 值</param>
        /// <returns>等级描述（中文）</returns>
        public static string GetCpkRating(double cpk)
        {
            if (cpk >= 1.67) return "卓越";
            if (cpk >= 1.33) return "良好";
            if (cpk >= 1.00) return "可接受";
            if (cpk >= 0.67) return "不足";
            return "严重不足";
        }

        /// <summary>
        /// 计算样本标准差（除以 n-1），适用于样本数据的离散程度估计。
        /// 公式：sqrt( Sum((x - mean)^2) / (n - 1) )
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>样本标准差</returns>
        public static double CalculateStandardDeviation(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            var n = vals.Length;
            if (n < 2) return 0.0;

            var avg = vals.Average();
            var sumSq = vals.Sum(v => Math.Pow(v - avg, 2));
            // 使用样本标准差（除以 n-1）
            return Math.Sqrt(sumSq / (n - 1));
        }

        /// <summary>
        /// 计算极差（最大值 - 最小值）
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>极差</returns>
        public static double CalculateRange(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            if (vals.Length == 0) return 0.0;
            return vals.Max() - vals.Min();
        }

        /// <summary>
        /// 计算变异系数（标准差 / 平均值 * 100%）
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>变异系数的百分比表示</returns>
        public static double CalculateCV(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            var stdDev = CalculateStandardDeviation(vals);
            var mean = vals.Average();
            if (Math.Abs(mean) < double.Epsilon) return double.NaN; // 避免除以 0
            return (stdDev / mean) * 100;  // 百分比
        }

        /// <summary>
        /// 计算与理论值的绝对偏差（常用于评估准确性）
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <param name="theoreticalValue">理论或目标值</param>
        /// <returns>平均值与理论值的绝对差</returns>
        public static double CalculateAccuracy(IEnumerable<double> values, double theoreticalValue)
        {
            var mean = values.Average();
            return Math.Abs(mean - theoreticalValue);
        }

        /// <summary>
        /// 计算 95% 置信区间（基于正态近似，使用 z=1.96）
        /// 置信区间 = mean ± 1.96 * s / sqrt(n)
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>置信区间下限与上限</returns>
        public static (double lower, double upper) Calculate95ConfidenceInterval(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            var n = vals.Length;
            if (n == 0) return (0, 0);

            var mean = vals.Average();
            var stdDev = CalculateStandardDeviation(vals);
            var margin = 1.96 * stdDev / Math.Sqrt(n);  // 1.96 对应 95% 置信度（正态分布近似）

            return (mean - margin, mean + margin);
        }

        /// <summary>
        /// 便捷方法：返回样本标准差
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>样本标准差</returns>
        public static double GetStdDeviation(IEnumerable<double> values)
        {
            return CalculateStandardDeviation(values);
        }

        /// <summary>
        /// 返回平均值 ± 3σ 的上下限（约包含 99.73% 的正态分布数据）
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>(lower, upper)</returns>
        public static (double lower, double upper) Get3SigmaRange(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            if (vals.Length == 0) return (0, 0);

            var mean = vals.Average();
            var stdDev = CalculateStandardDeviation(vals);
            return (mean - 3 * stdDev, mean + 3 * stdDev);
        }

        /// <summary>
        /// 计算峰度（Kurtosis），使用 Fisher 定义（返回值在正态分布时为 0）
        /// 公式（简化样本版本）： (n * sum((x-mean)^4)) / (sum((x-mean)^2)^2) - 3
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <returns>峰度值</returns>
        public static double CalculateKurtosis(IEnumerable<double> values)
        {
            var vals = values.ToArray();
            var n = vals.Length;
            if (n < 4) return 0.0; // 数据过少时峰度意义不大

            var mean = vals.Average();
            var sum4 = vals.Sum(v => Math.Pow(v - mean, 4));
            var sum2 = vals.Sum(v => Math.Pow(v - mean, 2));

            if (Math.Abs(sum2) < double.Epsilon) return 0.0;

            // Fisher 峰度（正态分布为 0）
            return (n * sum4) / Math.Pow(sum2, 2) - 3;
        }

        /// <summary>
        /// 计算过程能力指标 Cp 与 Cpk
        /// Cp = (USL - LSL) / (6 * sigma)
        /// Cpk = min( (USL - mean) / (3 * sigma), (mean - LSL) / (3 * sigma) )
        /// </summary>
        /// <param name="values">输入数据序列</param>
        /// <param name="lowerSpec">下规格限（LSL）</param>
        /// <param name="upperSpec">上规格限（USL）</param>
        /// <returns>(cp, cpk)</returns>
        public static (double cp, double cpk) CalculateProcessCapability(
            IEnumerable<double> values,
            double lowerSpec,
            double upperSpec)
        {
            var vals = values.ToArray();
            var stdDev = CalculateStandardDeviation(vals);
            var mean = vals.Average();

            if (stdDev <= 0) return (double.NaN, double.NaN); // 避免除以 0

            // Cp 反映公差带相对于总体变异的宽度
            var cp = (upperSpec - lowerSpec) / (6 * stdDev);

            // Cpk 考虑均值偏移，取靠近任一边的能力
            var cpu = (upperSpec - mean) / (3 * stdDev);
            var cpl = (mean - lowerSpec) / (3 * stdDev);
            var cpk = Math.Min(cpu, cpl);

            return (cp, cpk);
        }
    }
}