SpringBoot中实现文档生成与电子合同创建的完整指南

// 发票渲染所需的数据结构
@data
public class invoicerenderdata {
    private string invoiceno;          // 发票号
    private string buyername;          // 购方名称
    private string sellername;         // 销方名称
    private bigdecimal totalamount;    // 总金额
    private string issuedate;          // 开票日期
    private list<invoiceitem> items;   // 商品明细行
}

@data
public class invoiceitem {
    private string productname;        // 商品名
    private integer quantity;          // 数量
    private bigdecimal unitprice;      // 单价
    private bigdecimal amount;         // 金额
}

// 从数据库查出原始数据
order order = orderrepository.findbyid(orderid);
list<orderitem> orderitems = orderitemrepository.findbyorderid(orderid);
customer customer = customerrepository.findbyid(order.getcustomerid());

// 转换为渲染数据结构
invoicerenderdata renderdata = new invoicerenderdata();
renderdata.setinvoiceno(generateinvoiceno());
renderdata.setbuyername(customer.getname());
renderdata.setsellername("xx科技有限公司");
renderdata.settotalamount(order.gettotalamount());
renderdata.setissuedate(localdate.now().tostring());

list<invoiceitem> items = orderitems.stream().map(oi -> {
    invoiceitem item = new invoiceitem();
    item.setproductname(oi.getproductname());
    item.setquantity(oi.getquantity());
    item.setunitprice(oi.getunitprice());
    item.setamount(oi.getunitprice().multiply(bigdecimal.valueof(oi.getquantity())));
    return item;
}).collect(collectors.tolist());
renderdata.setitems(items);

/**
 * 使用jasperreports将数据渲染为pdf.
 *
 * @param renderdata 业务数据
 * @return pdf的字节数组
 */
public byte[] renderpdf(invoicerenderdata renderdata) {
    // 1. 加载预编译的模板文件（.jasper 是编译后的二进制模板）
    //    模板文件定义了页面布局、表格结构、字体、页眉页脚等
    classpathresource template = new classpathresource("templates/invoice.jasper");

    // 2. 设置模板参数（全局变量，如公司logo路径、子报表路径等）
    map<string, object> parameters = new hashmap<>();
    parameters.put("company_logo", "templates/logo.png");

    // 3. 将java对象集合转换为报表数据源
    //    jasperreports 会遍历这个数据源，每条数据生成一行
    jrdatasource datasource = new jrbeancollectiondatasource(
        collections.singletonlist(renderdata)
    );

    // 4. 填充模板：模板 + 参数 + 数据 → 内存中的报表对象
    jasperprint jasperprint = jasperfillmanager.fillreport(
        template.getinputstream(), parameters, datasource
    );

    // 5. 导出为pdf字节数组
    bytearrayoutputstream out = new bytearrayoutputstream();
    jrpdfexporter exporter = new jrpdfexporter();
    exporter.setexporterinput(new simpleexporterinput(jasperprint));
    exporter.setexporteroutput(new simpleoutputstreamexporteroutput(out));
    exporter.exportreport();

    return out.tobytearray();
}

/**
 * 上传文件到oss，返回公网可访问的url.
 *
 * @param pdfbytes 文件内容
 * @return 文件的公网url
 */
public string uploadtooss(byte[] pdfbytes) {
    // 将字节数组包装为输入流
    bytearrayinputstream inputstream = new bytearrayinputstream(pdfbytes);

    // 调用oss客户端上传
    // 内部会：生成唯一文件名 → 上传到oss bucket → 返回文件路径
    uploadresult result = ossclient.uploadfile(inputstream, "pdf");

    if (result == null || result.getfilepath() == null) {
        throw new runtimeexception("文件上传失败");
    }

    // 拼接完整url：域名 + 文件路径
    // 例如：https://cdn.example.com/files/2026/07/abc123.pdf
    string fullurl = ossbaseurl + "/" + result.getfilepath();
    return fullurl;
}

/**
 * 组装调用签约平台"创建合同"接口的参数.
 */
public contractcreateparam buildcontractparam(string pdfurl, invoicerenderdata renderdata) {
    contractcreateparam param = new contractcreateparam();

    // 合同基本信息
    param.setcontractname("电子发票-" + renderdata.getinvoiceno());
    param.setfileurl(pdfurl);            // pdf的公网链接（关键！）
    param.setfilename("发票.pdf");

    // 签署方a：卖方（我方，先盖章）
    contractsigner sellersigner = new contractsigner();
    sellersigner.setrole(1);             // 甲方
    sellersigner.setname(renderdata.getsellername());
    sellersigner.setsignposition("销方签章"); // 在pdf中寻找这个关键字定位盖章位置
    sellersigner.setsignorder(1);        // 第1个签

    // 签署方b：买方（客户，后签）
    contractsigner buyersigner = new contractsigner();
    buyersigner.setrole(2);              // 乙方
    buyersigner.setname(renderdata.getbuyername());
    buyersigner.setsignposition("购方签章");
    buyersigner.setsignorder(2);         // 第2个签

    param.setsigners(arrays.aslist(sellersigner, buyersigner));
    param.setsignorderly(true);          // 顺序签署（a签完b才能签）

    return param;
}

/**
 * 调用签约平台http接口创建合同.
 *
 * @param param 创建参数
 * @return 合同id（签约平台分配）
 */
public integer createcontractonplatform(contractcreateparam param) {
    // http post 调用签约平台
    httpresponse response = httpclient.post(
        "https://sign-platform.example.com/api/contract/create",
        jsonutil.tojson(param)
    );

    platformresult result = jsonutil.fromjson(response.getbody(), platformresult.class);

    if (result.issuccess()) {
        return result.getcontractid();  // 签约平台返回的合同id
    } else {
        throw new runtimeexception("创建合同失败: " + result.geterrormsg());
    }
}

@service
public class invoiceserviceimpl {

    /**
     * 完整流程：阶段1（事务内，同步）.
     * 准备数据 + 生成pdf + 上传 + 组装参数 + 注册事务后回调.
     */
    @transactional(rollbackfor = exception.class)
    public void issueinvoice(integer orderid) {

        // ======== 1. 组装数据 ========
        invoicerenderdata renderdata = this.buildrenderdata(orderid);

        // ======== 2. 渲染pdf ========
        byte[] pdfbytes = this.renderpdf(renderdata);

        // ======== 3. 上传到oss ========
        string pdfurl = this.uploadtooss(pdfbytes);

        // ======== 4. 组装签约平台参数 ========
        contractcreateparam contractparam = this.buildcontractparam(pdfurl, renderdata);

        // ======== 5. 本地写库（状态改为"处理中"） ========
        invoice invoice = new invoice();
        invoice.setorderid(orderid);
        invoice.setinvoiceno(renderdata.getinvoiceno());
        invoice.setstatus(invoicestatus.creating);  // 创建中
        invoice.setpdfurl(pdfurl);
        invoicerepository.save(invoice);

        // ======== 6. 注册事务后回调 → 发mq ========
        aftercommitactioncollector collector = new aftercommitactioncollector();
        transactionsynchronizationmanager.registersynchronization(collector);
        collector.addaction(
            () -> invoicecreatemqsender.send(contractparam, invoice.getid())
        );
    }

    /**
     * 完整流程：阶段2（mq消费后，独立事务）.
     * 调用签约平台 + 更新本地状态.
     */
    @transactional(propagation = propagation.requires_new)
    public void callsignplatform(contractcreateparam param, integer invoiceid) {

        invoice invoice = invoicerepository.findbyid(invoiceid).orelse(null);
        if (invoice == null) return;

        try {
            // 调用签约平台
            integer contractid = this.createcontractonplatform(param);

            // 成功：保存合同id，状态改为"待签署"
            invoice.setcontractid(contractid);
            invoice.setstatus(invoicestatus.waiting_sign);

        } catch (exception e) {
            // 失败：状态回退
            invoice.setstatus(invoicestatus.create_failed);
            log.warn("创建合同失败", e);
        }
        invoicerepository.save(invoice);
    }
}