nmWTAI-Platform/Include/nmNum/nmData/nmNumericalResultPersistence.h

#ifndef NMNUMERICALRESULTPERSISTENCE_H
#define NMNUMERICALRESULTPERSISTENCE_H

#include "nmData_global.h"

#include <QMap>
#include <QString>
#include <QVector>

#include <vtkSmartPointer.h>

class QFile;
class vtkUnstructuredGrid;

/** @brief v3 清单中对一个不可变文件的长度和 SHA-1 引用。 */
struct NM_DATA_EXPORT nmNumericalFileReference
{
    /** @brief 初始化空文件引用。 */
    nmNumericalFileReference();

    /** @brief 相对于所属窗口目录或成果根目录的正斜杠路径。 */
    QString m_sRelativePath;
    /** @brief 文件的精确字节长度。 */
    quint64 m_nLength;
    /** @brief 小写十六进制 SHA-1，固定为 40 个字符。 */
    QString m_sSha1;

    /** @brief 返回三个引用字段是否满足基本格式。 */
    bool isValid() const;
};

/** @brief 一口实时井在 v3 成果中的冻结历史曲线。 */
struct NM_DATA_EXPORT nmNumericalWellHistoryData
{
    /** @brief 压力历史曲线。 */
    QVector<QVector<double> > m_vecPressure;
    /** @brief 双对数历史曲线。 */
    QVector<QVector<double> > m_vecLogLog;
    /** @brief 半对数历史曲线。 */
    QVector<QVector<double> > m_vecSemiLog;
};

/** @brief 一个窗口主 JSON 引用的全部外部载荷。 */
struct NM_DATA_EXPORT nmNumericalWindowPayloadReferences
{
    /** @brief 当前输入网格是否存在。 */
    bool m_bHasCurrentGrid;
    /** @brief 当前输入网格文件引用。 */
    nmNumericalFileReference m_oCurrentGrid;
    /** @brief 按实时井 UUID 保存的历史曲线文件引用。 */
    QMap<QString, nmNumericalFileReference> m_mapWellHistories;
    /** @brief 最后成功结果快照是否存在。 */
    bool m_bHasSnapshot;
    /** @brief 快照元数据 JSON 文件引用。 */
    nmNumericalFileReference m_oSnapshot;

    /** @brief 初始化为不含网格和快照的窗口引用。 */
    nmNumericalWindowPayloadReferences();
};

/**
 * @brief v3 持久化共用的路径、哈希、网格和小型二进制工具。
 *
 * 大文件始终分块处理；JSON 可以由调用方在受限文件大小校验后读取。
 */
class NM_DATA_EXPORT nmNumericalResultPersistence
{
public:
    /** @brief 返回当前数值成果格式版本。 */
    static int projectVersion();
    /** @brief 返回单个二进制载荷的初始损坏拒绝阈值。 */
    static quint64 maximumBinaryPayloadBytes();

    /** @brief 校验相对路径，并返回规范化后的正斜杠路径。 */
    static bool normalizeRelativePath(const QString& sPath,
                                      QString& sNormalizedPath);
    /** @brief 将相对路径安全解析到指定根目录内。 */
    static bool resolveReferencedPath(const QString& sRootDirectory,
                                      const QString& sRelativePath,
                                      QString& sAbsolutePath);
    /** @brief 流式计算文件长度和 SHA-1。 */
    static bool buildFileReference(const QString& sAbsolutePath,
                                   const QString& sRelativePath,
                                   nmNumericalFileReference& oReference);
    /** @brief 校验引用格式、路径边界、文件长度和流式 SHA-1。 */
    static bool validateFileReference(const QString& sRootDirectory,
                                      const nmNumericalFileReference& oReference,
                                      QString* pAbsolutePath = NULL,
                                      QString* pError = NULL);

    /** @brief 写入一口实时井的三组历史曲线，不构造整文件缓冲。 */
    static bool writeWellHistory(
            const QString& sFilePath,
            const nmNumericalWellHistoryData& oHistory,
            QString* pError = NULL);
    /** @brief 在数量和剩余字节校验后读取一口井的历史曲线。 */
    static bool readWellHistory(
            const QString& sFilePath,
            nmNumericalWellHistoryData& oHistory,
            QString* pError = NULL);

    /** @brief 以二进制 VTU 写出网格并检查 VTK 返回值和文件存在性。 */
    static bool writeGrid(vtkUnstructuredGrid* pGrid,
                          const QString& sFilePath,
                          QString* pError = NULL);
    /** @brief 从 VTU 读取网格；调用方接管返回的 VTK 引用。 */
    static bool readGrid(const QString& sFilePath,
                         vtkSmartPointer<vtkUnstructuredGrid>& pGrid,
                         QString* pError = NULL);

private:
    /** @brief 禁止实例化纯静态工具类。 */
    nmNumericalResultPersistence();
};

#endif // NMNUMERICALRESULTPERSISTENCE_H