#ifndef NMPEBIRESULTSNAPSHOTBUILDER_H
#define NMPEBIRESULTSNAPSHOTBUILDER_H

#include "nmData_global.h"
#include "nmPebiResultSnapshot.h"

#include <QSharedPointer>
#include <QString>

/**
 * @brief 在发布前独占填充和校验 PEBI 结果快照。
 *
 * Builder 是一次性对象：任一写入失败或 finalize() 完成后均不可继续填充，
 * 防止半成品被修补后误发布。
 */
class NM_DATA_EXPORT nmPebiResultSnapshotBuilder
{
public:
    /** @brief 创建一个新的可写候选；内存不足时进入失败状态。 */
    nmPebiResultSnapshotBuilder();
    /** @brief 销毁尚未被 takeCandidate() 转交的候选。 */
    ~nmPebiResultSnapshotBuilder();

    /** @brief v3 加载时恢复已保存的快照 UUID；求解候选可使用自动生成值。 */
    bool setSnapshotId(const QString& sSnapshotId);
    /** @brief 设置候选创建时对应的网格输入版本和求解输入版本。 */
    bool setInputRevisions(quint64 nGridInputRevision,
                           quint64 nResultInputRevision);
    /** @brief 成功后接管网格且清空调用方智能指针，不执行 DeepCopy。 */
    bool takeResultGrid(
            vtkSmartPointer<vtkUnstructuredGrid>& pResultGrid);
    /** @brief 成功后接管压力数组且清空调用方智能指针，不复制整帧数据。 */
    bool addPressureFrame(
            double dTime,
            vtkSmartPointer<vtkDoubleArray>& pPressure);
    /** @brief 设置全部压力帧的全局最小值和最大值。 */
    bool setScalarRange(double dMinimum, double dMaximum);
    /** @brief 按求解器顺序追加一个冻结槽位。 */
    bool addSolverSlot(const nmPebiResultSolverSlot& oSlot);
    /** @brief 追加一口包含元数据和曲线的冻结结果井。 */
    bool addWell(const nmPebiResultWellSnapshot& oWell);
    /** @brief 转移一口井的字符串和曲线容器，避免提交阶段复制整套曲线。 */
    bool takeWell(nmPebiResultWellSnapshot& oWell);
    /** @brief 设置结果井下拉框使用的有序井 UUID 列表。 */
    bool setDisplayWellInstanceIds(const QStringList& listWellInstanceIds);
    /** @brief 设置求解时冻结的储层参数。 */
    bool setReservoirParameters(
            const nmPebiResultReservoirParameters& oParameters);
    /** @brief 设置求解时冻结的常量 PVT 和完整变化 PVT 数组。 */
    bool setPvtParameters(const nmPebiResultPvtParameters& oParameters);
    /** @brief 设置求解时冻结的网格、时间步和求解器配置。 */
    bool setSolverSettings(const nmPebiResultSolverSettings& oSettings);

    /** @brief 完成全部结构校验并封闭候选，失败后该 Builder 不可继续使用。 */
    bool finalize(QString* pError = NULL);
    /**
     * @brief 仅返回已封闭候选，同时清空 Builder 中的可写别名。
     * @note 调用方发布为 const 快照后也必须立即清除最后一个可写引用。
     */
    QSharedPointer<nmPebiResultSnapshot> takeCandidate();
    /** @brief 返回最近一次失败原因；尚未失败时返回空字符串。 */
    QString getLastError() const;

private:
    /** @brief 判断候选是否仍允许写入，并在不可写时记录错误。 */
    bool canWrite();
    /** @brief 将 Builder 永久置为失败状态并输出错误信息。 */
    bool fail(const QString& sError, QString* pError = NULL);
    /** @brief 校验候选全部结构，并移除基础网格的压力标量。 */
    bool validate(QString* pError);

private:
    // 这些标志区分“字段未设置”和“字段合法地等于默认值”。
    /** @brief Builder 独占的可写候选。 */
    QSharedPointer<nmPebiResultSnapshot> m_pCandidate;
    /** @brief 候选是否已经成功封闭。 */
    bool m_bFinalized;
    /** @brief Builder 是否已经发生不可恢复的错误。 */
    bool m_bFailed;
    /** @brief 调用方是否显式设置过标量范围。 */
    bool m_bHasScalarRange;
    /** @brief 调用方是否显式设置过储层参数。 */
    bool m_bHasReservoirParameters;
    /** @brief 调用方是否显式设置过 PVT 参数。 */
    bool m_bHasPvtParameters;
    /** @brief 调用方是否显式设置过求解设置。 */
    bool m_bHasSolverSettings;
    /** @brief 最近一次失败的英文内部诊断文本。 */
    QString m_sLastError;
};

#endif // NMPEBIRESULTSNAPSHOTBUILDER_H