using System.Threading.Tasks;
using XP.ReportEngine.Models;

namespace XP.ReportEngine.Interfaces
{
    /// <summary>
    /// 报告服务接口（门面）| Report service interface (Facade)
    /// 提供完整的报告生成流程，外部模块通过此接口调用报告功能
    /// Provides complete report generation workflow for external modules
    /// </summary>
    /// <remarks>
    /// 使用示例 | Usage example:
    /// <code>
    /// var request = new ReportRequest
    /// {
    ///     ProcessorOutputs = processorOutputs,
    ///     Metadata = new ReportMetadata
    ///     {
    ///         SampleName = "PCB-001",
    ///         OperatorName = "Operator",
    ///         InspectionDate = DateTime.Now
    ///     }
    /// };
    /// var result = await _reportService.GenerateAsync(request);
    /// </code>
    /// </remarks>
    public interface IReportService
    {
        /// <summary>
        /// 生成报告 | Generate report
        /// 执行完整流程：生成报告ID → 数据适配 → 上下文组装 → 管线生成 → 文件保存
        /// Executes full workflow: generate report ID → data adaptation → context assembly → pipeline generation → file saving
        /// </summary>
        /// <param name="request">报告生成请求 | Report generation request</param>
        /// <returns>报告生成结果 | Report generation result</returns>
        Task<ReportServiceResult> GenerateAsync(ReportRequest request);

        /// <summary>
        /// 预热报告引擎（建议在应用启动后台调用）| Warm up report engine (recommended to call in background on app startup)
        /// 触发 iText7 初始化、字体加载、JIT 编译等一次性开销，避免首次生成报告时卡顿
        /// Triggers iText7 initialization, font loading, JIT compilation to avoid first-run latency
        /// </summary>
        Task WarmUpAsync();
    }
}