// File_.d.ts
export = File_;

declare class File_ {
  constructor(hg: any);

  /** 生成当前时间文件夹名：yyyy-MM-dd_HH-mm-ss */
  getCurrentTimeFolderName(): string;

  /**
   * 网络下载文件并上传到租户空间
   * @param url 网络文件地址
   * @param fileName 上传到租户空间的文件名
   * @param header 可选请求头
   * @returns 上传后的文件信息
   */
  downloadFileToUpload(
    url: string,
    fileName: string,
    header?: Record<string, string>
  ): Promise<FileInfo>;

  /**
   * 下载租户空间的文件到环境 tmp 目录
   * @param file_info 文件元数据
   * @param file_path 本地存储路径（可选）
   * @returns 本地文件路径
   */
  downloadFileToTmp(
    file_info: FileInfo,
    file_path?: string
  ): Promise<string>;

  /**
   * 使用 token 下载文件到环境 tmp 目录
   * @param file_info 必须包含 token 与 mime_type
   * @param file_path 本地存储路径（可选）
   * @returns 本地文件路径
   */
  downloadFileByToeknToTmp(
    file_info: Pick<FileInfo, 'token' | 'mime_type'>,
    file_path?: string
  ): Promise<string>;

  /**
   * 将数据追加写入文件
   * @param data 写入内容
   * @param fileName 文件名（可选）
   */
  saveDataToEnv(data: string, fileName?: string): void;

  /**
   * 读取 CSV 文件（依赖 csv-parser）
   * @param path 文件路径
   * @param callback 每行回调，返回 void 时一次性返回所有行
   * @returns 无回调时返回全部行
   */
  csvRead<T = Record<string, any>>(
    path: string,
    callback: (row: T, index: number) => void
  ): Promise<void>;
  csvRead<T = Record<string, any>>(path: string): Promise<T[]>;

  /**
   * 读取 Excel 文件（依赖 xlsx@0.18.5）
   * @param filePath 文件路径
   * @returns 工作表第一页的全部数据
   */
  xlsxReaderAll(filePath: string): any[];

  /**
   * 导出数据到 Excel 文件（依赖 exceljs@4.0.1）
   * @param records 列配置列表，每个对象包含：
   * @param fields 需要导出的字段名列表（需与 records 中的 key 对应）
   *   - key: 列唯一标识（对应数据字段名）
   *   - header: 列表头显示文本
   *   - render: (可选) 自定义渲染函数 (value, record) => any
   *   - enums: (可选) 枚举配置 [{ name: [{ language_code, text }], api_alias }]
   *   - type: 列类型（可选 | 'Date' | 'Float' | 'Region'）
   * @param fileName 导出的文件名（可选 | 导出文件.xlsx）
   * @param sheetName 工作表名称（可选 | Sheet 1）
   * @returns 导出的文件信息
   */
  exportExcelFile(records: any[], fields: string[], fileName?: string, sheetName?: string): Promise<FileInfo>;

  /**
   * 导出数据到 Excel 格式 前置处理
   * @param records 导出的记录
   * @param fields 需要导出的字段名列表（需与 records 中的 key 对应）
   *   - key: 列唯一标识（对应数据字段名）
   *   - header: 列表头显示文本
   *   - render: (可选) 自定义渲染函数 (value, record) => any
   *   - enums: (可选) 枚举配置 [{ name: [{ language_code, text }], api_alias }]
   *   - type: 列类型（可选 | 'Date' | 'Float' | 'Region'）
   * @returns 导出的 Excel 数据（Buffer）
   */
  exportExcelData(records: any[], fields: string[]): Promise<any[]>;
}

/* ── 依赖类型 ─────────────────────────────── */
interface FileInfo {
  id?: string;
  token?: string;
  mime_type: string;
  name?: string;
  [key: string]: any;
}