package com.njcn.gather.tools.report.service;

import java.io.InputStream;
import java.util.Map;

/**
 * Word报告生成接口
 *
 * @author hongawen
 * @version 1.0
 * @data 2025/9/5 10:13
 */
public interface IWordReportService {

    /**
     * 替换Word文档中的占位符
     *
     * @param templateInputStream 模板文档输入流
     * @param placeholderMap 占位符替换映射表，key为占位符标识，value为替换值
     * @return 处理后的文档输入流，调用方可根据需要进行下载、上传等操作。
     *         <p>
     *         <b>资源管理契约：</b>当前实现返回 {@link java.io.ByteArrayInputStream}，
     *         其 {@code close()} 为空操作、内部仅持有 byte 数组、不占用文件句柄等 native 资源，
     *         调用方<strong>不强制</strong>用 try-with-resources 包裹该返回流；
     *         若未来该方法的实现改为返回底层依赖文件 / 网络 / 临时文件的真实流，
     *         必须先改造所有调用方按 try-with-resources 关流后再合并实现，
     *         以避免句柄泄漏。
     * @throws Exception 处理异常
     */
    InputStream replacePlaceholders(InputStream templateInputStream, Map<String, String> placeholderMap) throws Exception;

}
