AGILE TEAM
AGILE TEAM

Appearance

打印报表平台 — 运维操作手册 ​

📝 作者
祥
朱祥
朱祥平台室
工号：025877

从建目录到前端挂载的完整操作流程（九步）。配套前端封装见 打印报表接入指南。

项内容
需求编号REQ-20260903-01
文档版本V1.0
编制日期2026-09-03
适用环境http://172.28.99.180（派克新能 UAT / 生产同构）
适用对象报表实施人员、运维人员、前端二开人员
配套系统JH4J 微服务平台 · 打印报表（jh4j-cloud-report）

1 文档说明 ​

1.1 适用范围 ​

本手册覆盖打印报表从"零"到"能在业务页面上打印出来"的全部操作，共九步：

步骤操作执行角色所在位置
第一步创建报表目录实施/运维报表管理 → 报表目录
第二步创建数据源实施/DBA报表管理 → 数据源管理
第三步新建报表模板实施报表管理 → 新增
第四步配置数据集实施行操作 → 数据集
第五步配置报表参数实施行操作 → 参数
第六步设计报表版面实施行操作 → 设计
第七步预览验证实施行操作 → 预览 / HTML预览
第八步发布报表实施/运维批量发布
第九步前端挂载前端开发业务工程 .vue 组件

⚠ 第一至第八步在页面上完成，无需改代码；只有第九步（把报表接到业务按钮上）需要前端开发介入。

1.2 访问入口 ​

入口地址
报表管理http://172.28.99.180/lowCode/printreport/printReport
报表设计器http://172.28.99.180/reportDesigner?id={报表ID}（由"设计"按钮新开）
PDF 预览页http://172.28.99.180/report_pdfPreview?tempId={报表ID}&{参数}（由"预览"按钮新开）

1.3 术语 ​

术语含义
报表目录报表的分类文件夹，支持多级
报表模板一张报表的完整定义＝版面 + 数据集 + 参数，唯一标识是"报表ID"（tempId）
报表编码人工维护的业务编码，同一环境内唯一；导入判重先看 ID 再看编码
数据源一条数据库连接（MySQL/Oracle/SQLServer/达梦/openGauss），供 SQL 数据集使用
数据集报表的取数单元，一张报表可挂多个；分"SQL 数据库"与"接口"两类，用编码 ds1、ds2 区分
报表参数渲染时由调用方传入的变量（如工艺卡 id），在数据集 SQL 中以 #{参数名} 引用
发布状态草稿 / 已发布。发布后模板才对业务前端稳定可用
tempId报表ID，前端挂载时传给报表组件的关键值；跨环境导入导出保持不变

2 报表管理主界面 ​

左侧是报表目录树，右侧是该目录下的报表列表。所有操作都从这一屏出发。

图 1 报表管理主界面

2.1 工具条按钮 ​

按钮作用前置条件
新增在当前选中目录下新建报表模板必须先在左树选中一个具体目录
批量发布把勾选的草稿报表置为已发布勾选行中至少一条可发布
批量删除删除勾选的报表勾选至少一条
导出把勾选报表打包成 ZIP 下载（含数据集、参数、数据源）勾选至少一条
导入导入 ZIP 报表定义包，自动探测同编码冲突—
数据源管理维护数据库连接—

2.2 行操作按钮 ​

按钮作用
设计新标签页打开报表设计器
预览新标签页打开 PDF 预览（真实打印效果，以此为准）
HTML预览弹窗内 HTML 预览，可直接调用浏览器打印
数据集维护该报表的取数定义
参数维护该报表的参数名与默认值
导出 / 编辑 / 删除收在行尾"…"中：单张导出 ZIP、改编码名称、删除报表

⚠ PDF 预览是版面的唯一真相源。HTML 预览为提速做了近似换算，两者若有细微差异，以 PDF 为准。

3 第一步：创建报表目录 ​

目录用于报表分类，报表必须落在某个具体目录下，不能建在"全部"上。

3.1 操作步骤 ​

  1. 在左侧「报表目录」标题右边点击「新增」；

  2. 若新增前已在树上选中某个目录，则新建的是它的子目录；未选中则建在根级；

  3. 填写下表字段后点「确定」；

  4. 目录建好后，点击目录名即可选中，右侧列表随之过滤。

图 2 新增目录弹窗

3.2 字段说明 ​

字段必填说明
目录编码是同级唯一，建议用英文/拼音短码，如 production、quality
目录名称是树上显示的名称，如"生产"、"质量"
继承权限否是否继承父目录的配置，保持缺省的"继承"即可
排序号否同级排序，数字小的在前
备注否可为空

3.3 目录规划建议 ​

  • 按业务域一级分类（生产、质量、采购、物流计量、能碳），与现网保持一致；
  • 同一业务的一组报表（如冶炼浇注工艺卡的封面 + 各工序）放同一目录，便于批量导出迁移；
  • 临时验证类报表统一放 demo 目录，上线前清理。

4 第二步：创建数据源 ​

数据源是一条数据库连接，供"SQL 数据库"型数据集使用。若报表只用接口取数，本步可跳过。

4.1 操作步骤 ​

  1. 点工具条「数据源管理」打开维护弹窗；

  2. 上半部填写连接信息，点「测试连接」验证连通；

  3. 测试通过后点「新增」保存，下方列表出现该数据源；

  4. 已有数据源可在列表行上「编辑」「测试」「删除」。

图 3 数据源管理弹窗

4.2 字段说明 ​

字段必填说明
编码是唯一，数据集选数据源时按此识别，如 mes_db
名称否中文说明，如 MES 生产库
类型是MySQL / Oracle / SQLServer / 达梦 / openGauss
主机是IP 或域名
端口是MySQL 3306、Oracle 1521、SQLServer 1433 等
数据库是MySQL/SQLServer/openGauss 填库名；Oracle 填服务名；达梦填模式名
用户名 / 密码否密码加密存储，列表与编辑均不回显；改密码需重新输入
连接属性否追加参数，见下方常用写法

4.3 连接属性常用写法 ​

场景连接属性
MySQL 关闭 SSL、指定编码useSSL=false&characterEncoding=utf8
Oracle 老库用 SID 而非服务名connMode=sid
表结构不在默认模式下metaSchema=模式名

⚠ metaSchema 只影响"表结构"树的读取范围，不改变 SQL 的实际执行模式；SQL 里跨模式查询仍需写全限定名。

⚠ 数据库账号建议使用只读账号。数据集侧已强制"仅允许单条 SELECT"，但只读账号是第二道闸门。

5 第三步：新建报表模板 ​

5.1 操作步骤 ​

  1. 在左树点击一个具体目录（不能停在"全部"，否则提示"请先选择具体报表目录"）；

  2. 点工具条「新增」；

  3. 填写编码与名称，点「确定」；

  4. 列表中出现该报表，发布状态为"草稿"。

图 4 新增报表弹窗

5.2 字段说明 ​

字段必填说明
编码是同环境唯一。建议"业务域-用途"，如 SaleTrTransportRequire、冶炼浇注工艺卡-LF
名称是中文名称，列表与预览标题显示

⚠ 编码是导入导出判重的第二依据（第一依据是报表 ID）。一组要一起迁移的报表，编码务必在各环境保持一致。

6 第四步：配置数据集 ​

数据集决定报表"从哪儿拿数"。一张报表可以配多个数据集，在版面上用 {ds1.字段名} 引用。

6.1 SQL 数据库型 ​

  1. 在报表行上点「数据集」打开维护弹窗；

  2. 类型选「SQL 数据库」；

  3. 填数据集编码（ds1、ds2…）、名称，选数据源；

  4. 左侧「表结构」树点表名/列名可直接插入到 SQL 编辑器；SQL 编辑器支持表名、列名、schema 的自动补全；

  5. 编写 SQL（仅允许单条 SELECT）；

  6. 填「预览参数」（JSON，仅预览用），点「预览取列」验证 SQL 与字段；

  7. 点「新增」保存；已有数据集用行上的「编辑」「删除」「同步」维护。

图 5 SQL 数据集维护

6.2 SQL 中的参数写法 ​

写法含义使用建议
#绑定变量，防注入推荐，凡是值传参一律用它
$文本替换，可替换任意 SQL 片段注入风险自担，仅在必须动态拼表名/字段时用
动态 SQL：参数为空时自动去掉该条件可选条件全部用它，避免写一堆 or 判空

动态 SQL 常用范式：

-- 判空去条件（最常用）
{if(isEmpty(#id), "", "and id = #{id}")}
-- 模糊查询
{if(#name == "", "", "and name like concat('%', #{name}, '%')")}
-- 多值 in
  • 公式内字符串一律用双引号，单引号不认；
  • 需要输出字面的 { 时写 {（如 JSON 字符串、正则量词 {3}）；
  • 预览时务必填「预览参数」模拟真实入参，否则动态条件全被去掉，看不出真实结果。

6.3 接口型 ​

取数走后端已有的 HTTP 接口，不直连数据库。适合数据需要经过业务逻辑加工的场景。

图 6 接口型数据集

字段必填说明
数据集编码 / 名称是同 SQL 型
接口路径是点「选择」从已注册接口中挑选，不手写
参数否入参映射，写法 id={id}&name={name}，等号右侧 {} 内是报表参数名

6.4 字段与"同步" ​

  • 「预览取列」/「字段预览」会把 SQL 或接口的返回列固化成字段快照，设计器的数据树读的就是这份快照；
  • 当 SQL 改了列、或接口返回结构变了，必须在数据集行上点「同步」刷新快照，否则设计器里看不到新字段；
  • 未被版面引用的数据集在渲染时会被自动跳过，不产生取数开销。

⚠ 数据集编码一旦被版面引用（{ds1.XXX}），就不要再改名，改名会让版面上所有引用失效。

7 第五步：配置报表参数 ​

参数是调用方（业务前端、预览页）传进来的变量，是"同一张模板打不同单据"的关键。

7.1 操作步骤 ​

  1. 在报表行上点「参数」；

  2. 填参数名称与默认值，点「新增」；

  3. 参数名要与数据集 SQL 中 #{} 内的名字完全一致（区分大小写）。

图 7 报表参数维护

7.2 参数的三段链路 ​

环节写法示例
前端传入报表组件 params 属性:params="{ id: pcId }"
报表参数表此处登记参数名id
数据集 SQL#where PC_ID = #
  • 默认值仅用于"预览"和"HTML预览"——点预览时系统自动带上默认值，方便实施自测；
  • 业务前端真实调用时以传入值为准，默认值不生效；
  • 模板中还可直接引用 $params.参数名 取请求参数（忽略大小写，缺失时为空串）。

⚠ 参数没登记也能在 SQL 里写 #{x}，但预览时无处填值。规范做法是每个参数都登记一行并给出可用的默认值。

8 第六步：设计报表版面 ​

在报表行上点「设计」，新标签页打开设计器。左为画布、右为属性面板、顶部为菜单栏。

图 8 报表设计器主界面

8.1 菜单栏 ​

菜单内容
开始对齐、层级
插入文本、富文本、图片、条形码、二维码、图表、列表、子报表、网格布局、图形
页面纸张大小、页面重复方式、新增页面、删除当前页、重命名页面
工具自动吸附、编辑页眉/页脚、自动缩放、导入 Word/Excel、清空
预览 / 保存右上角。预览走真实渲染管线；保存后才落库

图 9 插入菜单：可用组件

图 10 页面菜单：纸张与分页

图 11 工具菜单：页眉页脚与 Word/Excel 导入

8.2 最短可用路径（画一张能出数的报表） ​

  1. 「页面 → 纸张大小」先定纸张（A4 纵向/横向），版面按版心边界排；

  2. 「插入 → 网格布局」放表头等静态内容，双击单元格输入文字；

  3. 「插入 → 列表」放明细区，列表会按数据集行数自动向下延伸并跨页；

  4. 选中单元格 → 右侧属性面板「数据设置」→ 从数据集树中双击字段，插入 {ds1.字段名}；

  5. 在属性面板调位置尺寸、行高列宽；在「样式」页签调字体、对齐、边框；

  6. 「工具 → 编辑页眉/页脚」放页码、单位名称等每页重复内容；

  7. 点右上角「保存」，再点「预览」核对。

图 12 数据设置：绑定数据集字段

8.3 数据设置弹窗的四个页签 ​

页签用途
表达式直接书写/查看最终表达式
数据集按数据集列出可用字段，双击插入；[_index] 是行序号
系统变量页码、总页数、当前日期、$params.* 等
公式内置函数（求和、判空、格式化、去重等）

8.4 常用要点 ​

需求做法
明细表跨页用「列表」组件，超出版心自动分页；表头行设"是否重复（每页）"
每页都要的抬头/页脚工具 → 编辑页眉/页脚，放在专属区
一张单据打多份页面 → 页面重复方式，设每页重复 2~5 份
已有 Word/Excel 版式工具 → 导入 Word/Excel，导入后再微调
嵌入另一张报表插入 → 子报表，选择子模板并传参
条码/二维码插入 → 条形码 / 二维码，内容绑定数据集字段

⚠ 设计器与报表列表是两个标签页。设计器里保存后，回列表页需要刷新才能看到更新时间变化。

9 第七步：预览验证 ​

9.1 两种预览的分工 ​

方式打开方式特点适用
预览（PDF）新标签页走后端真实渲染管线，所见即打印所得版面验收，以此为准
HTML预览弹窗内前端渲染，快；带导出、打印、PDF 窗口按钮快速自测、直接打印

图 13 HTML 预览弹窗

⚠ HTML 预览只在报表管理的弹窗内使用，本环境没有可直接访问的 HTML 预览 URL（弹窗内的「新窗口打开」按钮不可用）。业务页面要嵌预览，一律以组件形式挂载，见第 11 章。

图 14 PDF 预览页

9.2 验收清单 ​

  • 数据是否取到（空白多半是参数没传或 SQL 条件被判空去掉）；
  • 分页是否正确，跨页时表头是否重复；
  • 页眉页脚、页码、总页数是否正确；
  • 字体字号是否与纸质要求一致，有无被裁切或溢出版心；
  • 条码/二维码能否被扫码枪识别；
  • 多份重复打印时份数与内容是否正确。

9.3 导出格式 ​

HTML 预览弹窗的「导出」下拉，以及行操作"…→导出"，支持 PDF、图片、HTML、Excel、Word。Word/Excel 为兼容性输出，复杂版面仍以 PDF 为准。

10 第八步：发布报表 ​

  1. 在列表勾选要发布的报表（草稿状态）；

  2. 点工具条「批量发布」，确认；

  3. 发布状态变为"已发布"。

状态含义业务前端可用性
草稿尚在设计调整中技术上可预览，但不应对外挂载
已发布版面与取数已验收可交付业务前端挂载使用

⚠ 发布是流程闸门，不是技术开关——挂载用的是报表 ID，未发布的模板同样能被渲染。所以"先验收再发布再挂载"必须靠制度保证。

11 第九步：前端挂载 ​

报表以模块联邦（Module Federation）远程组件的形式提供给业务前端。业务侧不复刻任何报表逻辑，只负责"给一个 tempId 和一组参数"。

11.1 可用的远程组件 ​

组件名暴露路径用途
reportPreviewjh4j-cloud-report/reportPreview报表预览（推荐）：翻页、缩放、导出、打印一体
reportHtmlPreviewjh4j-cloud-report/reportHtmlPreviewHTML 快照预览 + 打印直连
reportFilljh4j-cloud-report/reportFill填报运行页
filePreviewjh4j-cloud-report/filePreview通用文件在线预览（PDF/Word/Excel/图片）
richtextDesigner / richtextPreviewjh4j-cloud-report/richtext*独立富文本编辑/只读渲染

模块名固定为 jh4j-cloud-report，与部署路径 /sub/jh4j-cloud-report/ 一一对应。

11.2 reportPreview 的属性契约 ​

属性类型默认说明
temp-idstring | string[]必填报表ID。逗号串 "A,B,C" 或数组＝多模板按序拼接成一叠
furniture-temp-idstring—公共页眉页脚模板ID，兼水印源；不传则各模板用自己的
paramsRecord<string,string>{}报表参数，键名与"报表参数"登记的名字一致
heightstring100vh容器高度，弹窗内一般写 calc(100vh - 206px)
auto-loadbooleantrue是否挂载即渲染
show-export / show-print / show-pdf-windowbooleantrue三个工具栏按钮的显隐

事件：loaded(pageCount) 渲染完成、error(message) 渲染失败。

11.3 最小可用写法 ​

<script setup lang="ts">
import lowcodeEnv from "@jhlc/common-core/src/store/lowcode-env";
// 第三个参数 true = 异步加载远程组件
const ReportPreview = lowcodeEnv().fetchComp(
"jh4j-cloud-report",
"jh4j-cloud-report/reportPreview",
true
);
</script>
<template>
<ReportPreview
:temp-id="tempId"
:params="{ id: bizId }"
height="calc(100vh - 206px)"
/>
</template>

11.4 完整范例：冶炼浇注工艺卡 ​

文件：pn-mes-ui/packages/common/src/components/product/biz/pp-process-card/pp-process-card.vue

这是现网在跑的挂载范例，一个组件管两种预览：不传工序＝整卡（封面 + 本卡走到的每道工序各一页）；传了工序＝封面 + 点名的那几道。

（1）取模板ID —— 不在前端写死

// pp-process-card.api.ts
import { getAction } from "@jhlc/common-core/src/api/action";
export interface PpProcessCardReportRef {
id: string; // 工艺卡ID，作为报表参数下发
tempId: string; // 模板ID串，逗号隔开，首个恒为封面
}
export async function getProcessCardReportRef(mpNo: string, processSecNo?: string) {
const response = await getAction<PpProcessCardReportRef>(
"/product/ppProcessCardReport/reportRef",
{ mpNo, processSecNo: processSecNo || undefined }
);
return response.data;
}

（2）渲染

<ReportPreview
v-else-if="tempId"
:key="tempId"
:temp-id="tempId"
furniture-temp-id="2090685779428237314"
:params="params" <!-- { id: 工艺卡id } -->
:dpi="120"
height="calc(100vh - 206px)"
/>

⚠ 范例中的 :dpi="120" 不在 reportPreview 的属性契约内（组件未声明该 prop），属现网遗留的无效写法，新接入不必照抄。

（3）打开时先清空再请求

async function load(): Promise<void> {
tempId.value = ""; // 不清空会先按旧模板渲染一遍，换卡时闪旧内容
pcId.value = "";
const ref = await getProcessCardReportRef(mpNo, processSecNo);
pcId.value = ref?.id ?? "";
tempId.value = ref?.tempId ?? "";
}

11.5 模板ID 的配置位置（关键） ​

工艺卡这条链路把"哪道工序打哪张模板"做成了配置，新增工序模板不用改代码：

环节存放位置说明
工序模板ID字典 product_process_sec_full 的 STR_VALUE3一道工序一行，STR_KEY＝二级工序代码
封面模板IDPpProcessCardReportService.COVER_TEMP_ID 常量封面不属于任何工序，故未进字典，改动需发版
页眉页脚模板IDpp-process-card.vue 的 furniture-temp-id前端属性，改动需发版

新增/更换一道工序的报表模板，标准动作：

  1. 在报表管理里设计好该工序的模板并发布，记下报表ID；

  2. 在字典维护里找到 product_process_sec_full，定位 STR_KEY＝该工序代码的那一行；

  3. 把报表ID填入 STR_VALUE3，保存；

  4. 打开工艺卡预览验证。

⚠ STR_VALUE3 是 NCLOB 字段，值两端不能带空格——字典界面里若存了空格占位，会拼出一个空模板ID把整串报表带崩。后端已做 trim，但维护时仍应填干净值。

⚠ 字典里没配模板的工序不会报错，只会在整卡预览里"少一页"，并在后端日志中被点名。整卡页数不对时先查日志。

12 跨环境迁移（导入 / 导出） ​

12.1 导出 ​

  1. 勾选要迁移的报表（可跨目录多选）；

  2. 点「导出」，浏览器下载 ZIP；

  3. ZIP 内含报表定义、数据集、参数以及所引用的数据源定义。

12.2 导入 ​

  1. 在目标环境点「导入」，选择 ZIP；

  2. 系统先做一次探测，识别"同编码已存在"的冲突；

  3. 有冲突时弹窗三选一：覆盖（更新既有报表内容）／跳过（只导入无冲突的新报表）／关闭弹窗中止；

  4. 导入结束给出成功、跳过、失败三项计数，失败项带原因且不自动关闭，需人工读完。

12.3 迁移要点 ​

要点说明
报表ID 保持不变导出包里带原ID，导入后仍是同一个ID。因此字典/代码里配的 tempId 迁移后无需修改
判重顺序先按报表ID，再按报表编码。编码在各环境保持一致是迁移可预期的前提
数据源随包迁移。目标环境已存在同编码数据源时会被跳过（报表本身仍导入成功，提示为警告级）
连接信息数据源密码不导出，目标环境需重新填写并测试连接
迁移后动作核对数据源连通 → 预览验证 → 发布

13 常见问题排查 ​

现象优先排查
点「新增」没反应，提示"请先选择具体报表目录"左树停在"全部"上，需点具体目录
预览空白、有版面无数据① 参数没传或名字不一致；② 动态 SQL 判空把条件全去掉了；③ 数据集未被版面引用（{ds1.X} 写错）
设计器里看不到新加的字段数据集改了 SQL 后没点「同步」/「预览取列」刷新字段快照
数据源测试连接失败① 主机端口网络不通；② Oracle 服务名/SID 写反（老库需 connMode=sid）；③ 账号密码错（密码不回显，编辑时需重填）
表结构树里找不到表表不在默认模式下，连接属性补 metaSchema=模式名
HTML 预览与 PDF 有细微差异以 PDF 为准。HTML 为提速做了近似换算
整卡预览少一页该工序在字典 product_process_sec_full 的 STR_VALUE3 没配模板ID，查后端日志被点名的工序
业务页面报"没查到工艺卡报表模板"同上，字典未配置
换单据后仍显示上一张的内容前端 load() 未先清空 tempId，或未给组件加 :key="tempId"
导入后全 0、看着像成功看失败计数与原因（失败提示不自动关闭）；常见为目标库缺表或数据源冲突
SQL 报"仅允许单条 SELECT"数据集只接受单条查询，多语句、DML、存储过程一律拒绝
实体打印机打出来缩小/错乱浏览器纸张配置与模板纸张不一致，PDF 本身无误——核对打印对话框的纸张与缩放

附录 A 路由与接口速查 ​

用途地址
报表管理/lowCode/printreport/printReport
报表设计器/reportDesigner?id=
PDF 预览页/report_pdfPreview?tempId={报表ID}&
导出报表定义POST /report/codePrintReport/exportDefinition（body＝ID数组）
导入报表定义POST 同上 importDefinition（multipart：file + strategy）
工艺卡预览入参GET /product/ppProcessCardReport/reportRef?mpNo=&processSecNo=

附录 B 文档信息 ​

项内容
需求编号REQ-20260903-01
取材环境http://172.28.99.180（截图为实机抓取，2026-09-03）
代码依据print-report-ui/packages/main/src/views/report-list.vue、report-preview.vue、vite/index.ts；pn-mes-ui .../pp-process-card.vue；pn-mes .../PpProcessCardReportService.java
版本V1.0

You may not distribute, modify, or sell this software without permission.

Copyright © 2026 金恒科技 AGILE TEAM