BPM 打印平台

RuoYi Office 基于 hiprint 构建了一体化打印平台， 支持拖拽式模板设计、主子表、条码 / 二维码、多纸张方向，并通过 SPI 方式向任意业务模块（流程、OA、CRM、资产…） 提供统一的数据接入。取代了旧版基于 TinyMCE HTML 的 printTemplateSetting 方案。

1. 整体架构

┌────────────────────────┐       ┌──────────────────────────┐
│  hiprint 模板设计器     │──────▶│ bpm_print_template 模板表 │
│ （PC 端 Vben Admin）    │       │  （JSON 存储，租户隔离）    │
└────────────────────────┘       └──────────────┬───────────┘
                                                │ CRUD / 查询
                                                ▼
┌────────────────────────┐       ┌──────────────────────────┐
│  业务详情页 / 移动端     │──────▶│  /bpm/print/data 统一接口 │
│  打印入口（PrintModal） │       │  PrintDataDispatcher       │
└────────────────────────┘       └──────────────┬───────────┘
                                                │ 按 businessType 分发
            ┌─────────────────┬─────────────────┼─────────────────┐
            ▼                 ▼                 ▼                 ▼
  BpmProcessProvider   SealApplyProvider  SupplyApplyProvider  ...更多 Provider
  (流程 / 审批记录)    (OA 用印申请)       (OA 物品申领含明细)    (实现 PrintDataProvider)

2. 数据库与菜单

变更脚本：ruoyi-office-db/20260417_update/bpm_print_platform.sql

• 新增 bpm_print_template 表（template_json / data_schema / paper_type / orientation…）
• 新增菜单：「流程中心 → 打印模板」（权限前缀 bpm:print-template:*，含复制、查看、设计器页面）
• 迁移存量：把每条 printTemplateSetting.enable=true 的旧流程自动生成一条 legacy_{key} 占位模板 （空白 A4），管理员进入设计器重绘即可，原 HTML 模板不再使用

3. 设计器（PC 端）

页面：ruoyi-office-vben/apps/web-antd/src/views/bpm/printTemplate

• index.vue：模板列表，支持新建 / 编辑 / 删除 / 复制 / 导入 / 导出（JSON）
• designer.vue：独立全屏页，基于 components/bpm-print/print-designer.vue 封装
• 设计器左侧提供两组可拖拽元素：
  • 业务数据：根据后端 getSchema(businessType) 动态注入的字段 / 主子表列
  • 通用元素：自定义文本、条形码、二维码、图片、横线 / 竖线、长文本等

模板 JSON 完全遵循 hiprint 协议，可直接复制到任意 hiprint 环境使用。

4. 运行时（业务详情打印入口）

前端组件：components/bpm-print

import { usePrint } from '#/components/bpm-print';
const { PrintModal, openPrint } = usePrint();

openPrint({
  businessType: 'oa_seal_apply', // 业务类型（后端 Provider 的 getBusinessType）
  businessId: id,                // 业务主键
  businessData: { ... },         // 可选：前端覆盖字段（优先级高于后端）
  businessDetails: { items: [] } // 可选：前端覆盖明细数据
});

BasicForm 已经内置了这一逻辑：业务页面只需传入 printBusinessType、printBusinessId、 printBusinessData 即可。如下为「用印申请单」的示例：

<BasicForm
  :header-data="{ ...formData, processDefinitionKey: PROCESS_DEFINITION_KEY }"
  print-business-type="oa_seal_apply"
  :print-business-id="id"
  :print-business-data="{ sealName, keeperName, creatorName }"
/>

当 printBusinessType === 'process_instance' 且该流程未配置 hiprint 模板时，BasicForm 会自动回退到旧版 process-print.vue（浏览器 v-print），实现平滑迁移。

5. 后端 SPI：新增业务类型

只需在模块里实现 cn.iocoder.yudao.module.bpm.api.print.spi.PrintDataProvider 并 @Component 注册即可被 PrintDataDispatcher 自动发现：

@Component
public class MyBillPrintDataProvider implements PrintDataProvider {

    @Override public String getBusinessType() { return "my_bill"; }

    @Override
    public Map<String, Object> loadData(Object businessId) {
        MyBillDO bill = service.get(Long.valueOf(String.valueOf(businessId)));
        Map<String, Object> m = new HashMap<>();
        m.put("billCode", bill.getBillCode());
        m.put("amount", bill.getAmount());
        return m;
    }

    @Override
    public Map<String, List<Map<String, Object>>> loadDetails(Object businessId) {
        // 明细 / 主子表，key 为 hiprint 模板里 tableList 的数据源名
        return Map.of("items", itemRows);
    }

    @Override
    public PrintDataSchema getSchema() {
        return PrintDataSchema.builder()
                .fields(List.of(
                        FieldNode.builder().field("billCode").title("单据编号").type("string").build(),
                        FieldNode.builder().field("amount").title("金额").type("number").build()))
                .tables(List.of(
                        TableNode.builder().tid("items").title("明细").columns(itemCols).build()))
                .build();
    }
}

内置 Provider：

businessType	说明	实现位置
process_instance	流程实例 + 审批记录	yudao-module-bpm-server BpmProcessPrintDataProvider
oa_seal_apply	OA 用印申请单	yudao-module-oa-server SealApplyBillPrintDataProvider
oa_supply_apply	OA 物品申领（含明细）	yudao-module-oa-server SupplyApplyBillPrintDataProvider
oa_business_trip	OA 出差申请（含行程）	yudao-module-oa-server BusinessTripPrintDataProvider

6. 统一接口

接口	说明
GET /bpm/print/business-types	列出所有已注册的 businessType
GET /bpm/print/schema	获取指定业务的字段 Schema（设计器字段列表用）
GET /bpm/print/data	获取模板 + 主数据 + 明细（运行时渲染用）
GET /bpm/print-template/*	模板 CRUD（列表 / 新建 / 编辑 / 复制 / 删除）

7. 移动端（uniapp / H5）

通过 web-view 嵌入 PC 端独立预览路由 /#/bpm/print-view?businessType=xxx&businessId=xxx：

• 页面：ruoyi-office-vben/apps/web-antd/src/views/bpm/printTemplate/view.vue
• uniapp 入口：pages-bpm/processInstance/detail/print-view/index.vue
• 审批详情页右上角的 🖨 图标即会跳转到该 webview 页面
• 环境变量：VITE_WEB_H5_BASEURL 指向 PC 端 H5 部署地址

8. 废弃说明

• 旧版自定义打印模板（BpmProcessDefinitionInfoDO.printTemplateSetting + TinyMCE HTML 编辑器） 已在流程设置页面停用。进入「流程中心 → 打印模板」使用全新的 hiprint 设计器即可
• 旧版 process-print.vue 仅作为无 hiprint 模板时的回退使用，后续将逐步移除