#ifndef __DATA_LOADER_HPP__
#define __DATA_LOADER_HPP__

#include <string>
#include <vector>

#include "DataTable.hpp"

namespace jdi
{

	/**
	 * @brief 一个文件加载后的**命名分组**（多数格式只有一个，名字取文件名）。
	 */
	struct LoadedSourceGroup
	{
		std::wstring name;		/**< 分组名（空表示"用源文件名"）。 */
		LoadedSource source;	/**< 该分组的数据。 */
	};

	/**
	 * @brief 判断路径是否为应用当前支持的测量文件（按扩展名判断，不访问文件内容）。
	 * @param [IN] filePath 文件路径。
	 * @return 支持返回 true。
	 */
	bool IsSupportedSignalFile(const std::wstring& filePath);

	/**
	 * @brief 供「打开文件」对话框使用的过滤器文本（`GetOpenFileNameW` 的 `lpstrFilter` 格式）。
	 * @return 双 NUL 结尾的过滤器文本。
	 */
	const wchar_t* SignalFileDialogFilter();

	/**
	 * @brief 按扩展名选择加载器并读入一个测量文件（**唯一的文件加载入口**）。
	 *
	 * 上层（数据模型与界面）只依赖本函数返回的 `LoadedSource`，因此新增格式时
	 * **只需新增一个加载器并在这里登记**，其余代码完全不用改。
	 *
	 * 当前支持的格式：
	 * * CSV 文本（`.csv` / `.txt`）：支持多个 `time` 列（多时间轴）与各时间轴不等长；
	 * * ASAM MDF v4（`.mf4` / `.mdf`）：每个通道组（CG）是一个时间轴；
	 * * MATLAB 7.3 `.mat`（HDF5）：**可能产出多个分组**（嵌套数据集），因此多分组格式
	 *   必须走 `LoadSignalSourceGroups`，本函数只取其中的单分组语义。
	 *
	 * @param [IN] filePath 文件完整路径。
	 * @param [OUT] source 解析结果（若干时间轴块）。
	 * @param [OUT] error 失败原因描述（成功时清空）。
	 * @param [IN] progress 进度回调，可为空。
	 * @return 加载成功返回 true。
	 */
	bool LoadSignalSource(const std::wstring& filePath, LoadedSource& source, std::wstring& error,
	                      const LoadProgress& progress = LoadProgress());

	/**
	 * @brief 与 `LoadSignalSource` 相同，但允许一个文件产出**多个命名分组**。
	 *
	 * 绝大多数格式只有一个分组（`groups.size() == 1`，`name` 为空 ⇒ 用文件名）。
	 * `.mat`（MATLAB 7.3）里的嵌套数据集会产生多个分组：分组名由"从顶层数据集到信号"
	 * 的路径用 `-` 连接而成（用户 2026-10-18 要求）。
	 *
	 * @param [IN] filePath 文件完整路径。
	 * @param [OUT] groups 读出的分组（至少一个）。
	 * @param [OUT] error 失败原因描述（成功时清空）。
	 * @param [IN] progress 进度回调，可为空。
	 * @return 加载成功返回 true。
	 */
	bool LoadSignalSourceGroups(const std::wstring& filePath, std::vector<LoadedSourceGroup>& groups,
	                            std::wstring& error,
	                            const LoadProgress& progress = LoadProgress());

} // namespace jdi

#endif // __DATA_LOADER_HPP__