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);
    }
}