升鲜宝供应链管理系统生成图片、生成 PDF、生成分享码通用组件功能设计文档(一）---升鲜宝生鲜配送供应链管理系统源代码（Spring Boot Vue3 Uniapp )

升鲜宝供应链管理系统

生成图片、生成 PDF、生成分享码

通用组件功能设计文档

 

文档项	内容
文档版本	V1.0 正式设计版
适用系统	升鲜宝供应链管理系统 / 门店商城 / 小程序 / 后台管理
适用技术	Spring Boot、MyBatis-Plus、MySQL 8.0、Vue3、Redis、OSS/MinIO
模块前缀	gen_
设计日期	2024-04-27
文档用途	用于研发评审、数据库设计、接口开发、前后端联调、后续扩展

 

核心结论：本文档将“生成图片、生成 PDF、生成分享码”抽象为升鲜宝的统一生成中心，而不是分散在商品、订单、仓库、财务、商城等模块中重复开发。

 

 

目录

1. 文档定位与建设目标

2. 业务场景与需求范围

3. 总体架构设计

4. 通用组件边界设计

5. 模板中心设计

6. 生成图片组件设计

7. 生成 PDF 组件设计

8. 分享码与二维码组件设计

9. 文件资产与存储设计

10. 统一生成流程与状态机

11. 数据库表结构与数据字典

12. 后端接口设计

13. 后端工程结构与核心代码骨架

14. 前端页面与交互设计

15. 权限、安全、审计设计

16. 异步任务、幂等与重试机制

17. 与业务模块集成方案

18. 配置中心与参数设计

19. 测试验收清单

20. 分阶段落地计划

21. 附录：DDL 与枚举建议

 

1. 文档定位与建设目标

升鲜宝供应链管理系统中，商品、订单、采购、仓库、财务、CRM、商城、小程序等模块都会产生对外展示、打印、下载、扫码访问、客户确认、推广传播等需求。

如果每个业务模块都自行开发图片生成、PDF 生成、二维码生成、文件上传、分享链接、访问日志，会造成大量重复代码，且权限、安全、审计和模板维护不可控。

设计说明：本方案建议建设独立的“生成中心 gen”，统一承载图片、PDF、分享码、二维码、文件资产与访问审计能力。业务模块只负责提供业务数据，生成中心负责模板渲染、文件存储和访问控制。

 

建设目标	说明
统一模板	图片模板、PDF 模板、分享页模板统一维护，按租户、业务、场景隔离。
统一数据适配	通过 sceneCode + bizType + bizId 加载业务数据，避免模板直接查业务表。
统一生成任务	图片、PDF、二维码、分享码统一落任务表，支持异步、重试、追踪。
统一文件资产	生成后的 PNG/JPG/WebP/PDF/二维码统一进入文件资产表，支持 OSS/MinIO/本地存储。
统一分享访问	分享码、短链接、二维码访问统一校验有效期、访问次数、密码、客户绑定、状态。
统一权限审计	生成、下载、访问、扫码、失败原因都可审计，满足企业管理和排查要求。

 

2. 业务场景与需求范围

生成中心需要覆盖后台管理端、移动端、小程序、H5 分享页和外部客户访问场景。以下为第一阶段建议优先支持的核心业务场景。

业务模块	典型生成内容	优先级
商品模块	商品海报、商品标签、商品二维码、客户专属价格图片	高
销售订单	销售单 PDF、销售出库单 PDF、客户确认链接、订单分享二维码	高
采购模块	采购订单 PDF、供应商确认单、采购入库凭证	中
仓库 WMS	入库单、出库单、盘点单、调拨单、配送单 PDF	高
财务模块	客户对账单、供应商对账单、收款凭证、付款通知 PDF	高
CRM 客户	客户报价单、授信通知单、账期提醒单、业务员名片码	中
商城/小程序	门店分享码、商品分享海报、活动海报、推广码	高
配送签收	签收凭证图、签收单 PDF、客户扫码确认页	中

 

2.1 组件能力范围

能力	包含内容	不建议放入生成中心的内容
图片生成	海报、标签、二维码图、条形码图、签收凭证图	业务审批逻辑、库存扣减逻辑
PDF 生成	销售单、采购单、仓库单、对账单、凭证、报价单	单据状态变更、财务记账
分享码	短码、短链接、二维码、访问控制、访问日志	商城商品详情业务逻辑本身
文件资产	存储路径、URL、大小、HASH、过期时间、业务绑定	原始业务附件的全部管理逻辑
模板管理	模板、变量、默认模板、版本、启停、预览	复杂在线设计器的全部图形编辑能力可分阶段建设

 

3. 总体架构设计

生成中心作为公共能力模块，位于业务模块与文件存储之间。业务模块传入生成请求，生成中心根据模板和适配器生成文件或分享入口。

总体架构图

业务模块

  ├─ 商品 PMS

  ├─ 订单 OMS

  ├─ 采购 PUR

  ├─ 仓库 WMS / HWMS

  ├─ 财务 FIN

  ├─ CRM

  └─ 商城 / 小程序

        │

        ▼

生成中心 GEN

  ├─ 模板中心

  ├─ 变量中心

  ├─ 业务数据适配器

  ├─ 图片渲染器

  ├─ PDF 渲染器

  ├─ 二维码 / 条码渲染器

  ├─ 分享码服务

  ├─ 文件资产中心

  ├─ 异步任务中心

  ├─ 权限校验

  └─ 访问审计

        │

        ▼

文件存储 / 访问入口

  ├─ 本地文件

  ├─ MinIO

  ├─ 阿里云 OSS

  ├─ CDN

  └─ H5 / 小程序分享页

 

3.1 推荐模块命名

项目层级	推荐命名	说明
后端模块	sxb-generator 或 sxb-gen	公共生成中心模块。
包名	com.sxb.generator	集中管理生成相关代码。
表前缀	gen_	生成中心统一表前缀。
场景编码	sceneCode	如 GOODS_POSTER、SALE_ORDER_PDF。
业务类型	bizType	如 GOODS、OMS_ORDER、WMS_STOCKIN。
业务主键	bizId	绑定业务记录主键。

 

4. 通用组件边界设计

4.1 核心设计原则

原则	说明
业务与渲染解耦	业务模块不直接生成图片/PDF，只提供业务数据或实现适配器。
模板与数据解耦	模板只引用变量，不直接绑定 SQL。
同步与异步兼容	小文件可同步返回，大文件和批量任务必须支持异步。
文件资产化	任何生成产物都进入 gen_asset，便于追踪、复用、清理和分享。
分享受控	分享码必须支持状态、过期、访问次数、密码、客户绑定和访问日志。
租户隔离	模板、任务、资产、分享码都需要 tenant_id。
幂等优先	同一业务同一模板同一版本可复用已生成文件，避免重复生成。

 

4.2 统一调用模型

统一调用模型

输入：

  tenantId

  sceneCode

  bizType

  bizId

  templateCode

  extraParams

 

输出：

  taskNo

  assetId

  fileUrl

  shareCode

  shareUrl

  qrCodeUrl

  status

 

5. 模板中心设计

模板中心负责管理图片模板、PDF 模板和分享页模板。模板与业务数据通过变量映射关系绑定。

模板类型	用途	推荐渲染方式
IMAGE	商品海报、门店海报、标签、签收凭证图	HTML 截图、Canvas、Java2D
PDF	销售单、采购单、出入库单、对账单	HTML + OpenHTMLToPDF / Freemarker
SHARE_PAGE	扫码后的 H5 页面、小程序落地页	Vue3 页面模板 + API 数据

 

5.1 模板变量设计

变量类型	示例	说明
TEXT	${goods.goodsName}	普通文本。
AMOUNT	${order.totalAmount}	金额，可按小数位和舍入规则格式化。
DATE	${order.billDate}	日期时间，支持格式化。
IMAGE	${goods.mainImageUrl}	商品图、门店 Logo、签名图片。
QRCODE	${share.qrCodeUrl}	二维码图片。
BARCODE	${goods.barcode}	条形码图片。
TABLE	${details}	PDF 明细表格循环数据。

 

5.2 模板版本建议

正式使用后，模板应增加版本管理能力。第一阶段可在 gen_template 中用 template_code + is_default 管理；第二阶段可以扩展 gen_template_version 表，实现模板历史回滚和灰度。

版本策略	说明
默认模板	每个 tenantId + sceneCode 保持一个默认启用模板。
复制模板	编辑前复制旧模板，避免影响线上单据。
模板预览	使用样例数据渲染预览图或 PDF。
上线发布	模板编辑后需发布才能被业务使用。
历史回滚	出现排版问题可回滚到上一个版本。

 

6. 生成图片组件设计

图片生成组件主要用于商品海报、活动海报、门店海报、商品标签、客户报价图、配送签收凭证图等。

场景编码	场景名称	业务绑定
GOODS_POSTER	商品分享海报	pms_goods / pms_goods_sku
GOODS_LABEL	商品标签	pms_goods_sku / 条码
STORE_POSTER	门店分享海报	mall_shop
ACTIVITY_POSTER	营销活动海报	营销活动表
CUSTOMER_PRICE_IMAGE	客户报价图片	客户 + 商品价格
DELIVERY_SIGN_IMAGE	配送签收凭证图	配送单 / 签收记录
PROMOTION_INVITE_POSTER	推广邀请海报	员工 / 客户推广关系

 

6.1 图片生成流程

图片生成流程

用户选择业务数据

  ↓

选择图片模板

  ↓

生成中心读取模板变量

  ↓

业务数据适配器加载数据

  ↓

生成二维码 / 条码 / 水印

  ↓

渲染图片 PNG / JPG / WebP

  ↓

上传 OSS / MinIO / 本地文件

  ↓

写入 gen_asset 与 gen_render_task

  ↓

返回 imageUrl / assetId

 

6.2 图片渲染技术建议

方案	适用场景	优点	注意事项
Java2D	商品标签、简单二维码图、签收凭证	稳定、部署简单、性能可控	复杂排版开发成本高。
HTML 截图	复杂海报、门店推广图	与前端样式一致，灵活	需要 Headless Chrome 或截图服务。
Canvas 前端生成	移动端海报预览、用户手动保存	体验好，所见即所得	服务端留档需回传文件。
Puppeteer	HTML 转图片、批量海报	对复杂 CSS 支持好	需要 Node 服务或容器环境。

 

7. 生成 PDF 组件设计

PDF 生成组件用于业务正式单据、客户对账、财务凭证、配送单、采购单、销售单等。建议以 HTML 模板为主，后端渲染为 PDF。

场景编码	场景名称	核心数据
SALE_ORDER_PDF	销售订单 PDF	订单主表、订单明细、客户、金额汇总
SALE_OUTBOUND_PDF	销售出库单 PDF	出库主表、出库明细、仓库、经办人
PURCHASE_ORDER_PDF	采购订单 PDF	采购主表、供应商、采购明细
PURCHASE_INBOUND_PDF	采购入库单 PDF	入库主表、入库明细、批次、仓库
WMS_STOCKTAKE_PDF	仓库盘点单 PDF	盘点主表、盘点明细、盈亏数据
CUSTOMER_BILL_PDF	客户对账单 PDF	客户、账期、订单、收款、应收余额
SUPPLIER_BILL_PDF	供应商对账单 PDF	供应商、采购、付款、应付余额
DELIVERY_ORDER_PDF	配送单 PDF	配送任务、客户地址、商品明细、签收信息

 

7.1 PDF 标准结构

区域	内容
页眉	公司名称、门店名称、单据名称、单据编号、打印时间。
基础信息区	客户、供应商、仓库、经办人、业务日期、联系方式。
明细表格区	商品名称、规格、单位、数量、单价、金额、备注。
汇总区	数量合计、金额合计、优惠、应收/应付、实收/实付。
签名区	制单人、审核人、客户签字、供应商签字、司机签收。
页脚	页码、系统说明、公司联系方式。
水印	草稿、已审核、已作废、内部使用。

 

7.2 PDF 生成流程

PDF 生成流程

用户点击导出 PDF

  ↓

校验业务查看权限和导出权限

  ↓

加载默认模板或指定模板

  ↓

业务数据适配器加载主表 + 明细 + 汇总

  ↓

格式化金额、数量、日期、小数位

  ↓

渲染 HTML

  ↓

HTML 转 PDF

  ↓

上传文件存储

  ↓

写入 gen_asset

  ↓

返回下载地址或预览地址

 

7.3 PDF 技术选型建议

技术	推荐程度	说明
Freemarker + OpenHTMLToPDF	推荐	Java 体系常用，HTML 模板易维护，适合业务单据。
Thymeleaf + OpenHTMLToPDF	推荐	与 Spring Boot 结合好，适合模板复杂场景。
iText	谨慎	能力强，但授权和商业合规需要确认。
Flying Saucer	一般	传统方案，可作为兼容方案。
前端 print + 浏览器导出	辅助	适合临时打印，不适合作为正式归档文件。

 

8. 分享码与二维码组件设计

分享码组件不仅是生成二维码，还需要管理短码、分享链接、访问策略、有效期、访问次数、访问日志和业务绑定关系。

分享类型	示例场景	访问对象
GOODS	商品详情分享、商品报价分享	客户、游客、业务员
STORE	门店商城分享、总部多门店通用提货入口	客户、会员
ORDER	销售订单分享、客户确认订单	客户
BILL	对账单分享、账期提醒	客户、供应商
ACTIVITY	活动海报、优惠活动链接	客户、会员
PROMOTION	推广码、邀请奖励码	客户、员工
PICKUP	自提码、门店提货凭证	客户、门店人员
DELIVERY	配送签收确认码	客户、司机

 

8.1 分享码结构

组成	示例	说明
短码	SXBA8K29	对外展示和扫码访问的唯一编码。
分享链接	https://domain.com/s/SXBA8K29	H5 或后台解析入口。
二维码	二维码图片 URL	二维码内容通常是分享链接。
访问策略	PUBLIC / LOGIN / PASSWORD / CUSTOMER	控制外部访问方式。
业务绑定	bizType + bizId	用于回查真实业务数据。
安全签名	sign + timestamp	防止链接被篡改。

 

8.2 分享码校验规则

分享码访问校验流程

访问 /s/{shareCode}

  ↓

查询 gen_share_code

  ↓

校验状态是否启用

  ↓

校验是否过期

  ↓

校验访问次数是否超限

  ↓

校验访问方式：

    PUBLIC：直接访问

    LOGIN：需要登录

    PASSWORD：需要输入密码

    CUSTOMER：必须绑定指定客户

  ↓

写入 gen_share_access_log

  ↓

跳转 H5 / 小程序 / 后台预览页

 

9. 文件资产与存储设计

所有生成文件必须进入 gen_asset 表统一管理。业务表只保存 assetId 或 fileUrl 的引用，不建议在业务模块重复维护文件元数据。

资产类型	文件扩展名	使用场景
IMAGE	png / jpg / webp	海报、标签、签收图。
PDF	pdf	业务单据、对账单、凭证。
QRCODE	png / svg	分享码二维码、门店二维码。
BARCODE	png / svg	商品条形码、箱码。

 

9.1 文件目录建议

文件目录结构

/gen

  /image

    /goods

    /order

    /store

  /pdf

    /sale

    /purchase

    /wms

    /finance

  /qrcode

    /share

  /barcode

    /goods

 

9.2 文件命名规则

文件命名规则

{sceneCode}_{bizNo或bizId}_{yyyyMMddHHmmss}.{ext}

 

示例：

SALE_ORDER_PDF_SO202604270001_20260427093015.pdf

GOODS_POSTER_10001_20260427093015.png

SHARE_QRCODE_SXBA8K29_20260427093015.png

 

10. 统一生成流程与状态机

10.1 生成任务状态机

生成任务状态机

待生成 WAITING

  ↓

生成中 PROCESSING

  ↓

生成成功 SUCCESS

  │

  └─ 文件资产有效，可下载、可分享

 

生成中 PROCESSING

  ↓

生成失败 FAILED

  ↓

可重试 RETRY

  ↓

生成中 PROCESSING

 

任意状态

  ↓

已取消 CANCELED

 

10.2 失败原因分类

失败类型	说明	处理方式
TEMPLATE_NOT_FOUND	模板不存在或未启用	提示配置模板。
BIZ_DATA_NOT_FOUND	业务数据不存在或无权限	检查 bizId 和权限。
VARIABLE_MISSING	模板必填变量未提供	补充变量映射。
RENDER_FAILED	HTML、图片或 PDF 渲染失败	记录错误堆栈，允许重试。
UPLOAD_FAILED	文件上传失败	检查 OSS/MinIO 配置，自动重试。
ACCESS_DENIED	无业务查看或导出权限	禁止生成并记录日志。

 

11. 数据库表结构与数据字典

生成中心第一阶段建议至少建设以下 6 张核心表。后续可按需要扩展模板版本表、模板分组表、批量任务表和访问统计汇总表。

表名	中文名称	用途
gen_template	模板主表	管理图片、PDF、分享页模板。
gen_template_variable	模板变量表	定义模板可使用变量及数据路径。
gen_render_task	生成任务表	记录图片、PDF、二维码生成过程。
gen_asset	文件资产表	统一保存生成文件元数据。
gen_share_code	分享码表	管理短码、分享链接、访问策略。
gen_share_access_log	分享访问日志表	记录扫码、访问、失败原因。

 

 gen_template 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
template_code	VARCHAR(64)	模板编码，租户内唯一
template_name	VARCHAR(128)	模板名称
template_type	VARCHAR(32)	IMAGE/PDF/SHARE_PAGE
biz_type	VARCHAR(64)	业务类型
scene_code	VARCHAR(64)	场景编码
render_engine	VARCHAR(32)	HTML/CANVAS/FREEMARKER/VUE_TEMPLATE
template_content	LONGTEXT	模板内容
template_config	JSON	模板配置
preview_image_url	VARCHAR(500)	预览图
width/height	INT	图片宽高
page_size	VARCHAR(32)	PDF 页面大小
status	TINYINT	0禁用，1启用
is_default	TINYINT	是否默认模板
deleted	TINYINT	逻辑删除

 

 gen_template_variable 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
template_id	BIGINT	模板ID
variable_code	VARCHAR(64)	变量编码
variable_name	VARCHAR(128)	变量名称
variable_type	VARCHAR(32)	TEXT/IMAGE/QRCODE/BARCODE/AMOUNT/DATE/TABLE
data_path	VARCHAR(255)	数据路径，如 order.customerName
default_value	VARCHAR(500)	默认值
required	TINYINT	是否必填
format_rule	VARCHAR(255)	格式化规则

 

 gen_render_task 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
task_no	VARCHAR(64)	生成任务编号
render_type	VARCHAR(32)	IMAGE/PDF/QRCODE/BARCODE/SHARE
biz_type	VARCHAR(64)	业务类型
scene_code	VARCHAR(64)	场景编码
biz_id/biz_no	BIGINT/VARCHAR	业务主键与业务单号
template_id	BIGINT	模板ID
request_param	JSON	请求参数
render_data	JSON	渲染数据
status	TINYINT	0待生成，1生成中，2成功，3失败，4取消
retry_count	INT	已重试次数
error_message	TEXT	错误信息
asset_id	BIGINT	生成文件ID
idempotent_key	VARCHAR(128)	幂等键

 

 gen_asset 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
asset_no	VARCHAR(64)	文件资产编号
asset_type	VARCHAR(32)	IMAGE/PDF/QRCODE/BARCODE
biz_type/scene_code	VARCHAR	业务类型与场景编码
biz_id/biz_no	BIGINT/VARCHAR	业务绑定
file_name	VARCHAR(255)	文件名
file_ext	VARCHAR(32)	文件扩展名
mime_type	VARCHAR(128)	MIME 类型
file_size	BIGINT	文件大小
storage_type	VARCHAR(32)	LOCAL/OSS/MINIO/COS
storage_path	VARCHAR(500)	存储路径
file_url	VARCHAR(1000)	访问地址
file_hash	VARCHAR(128)	文件 HASH
expire_time	DATETIME	文件过期时间
status	TINYINT	0无效，1有效

 

 gen_share_code 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
share_code	VARCHAR(64)	分享短码
share_title	VARCHAR(128)	分享标题
share_type	VARCHAR(32)	GOODS/ORDER/BILL/STORE/ACTIVITY/PROMOTION
biz_type/biz_id/biz_no	VARCHAR/BIGINT	绑定业务对象
target_url	VARCHAR(1000)	目标访问地址
qr_asset_id	BIGINT	二维码文件ID
cover_asset_id	BIGINT	分享封面文件ID
access_mode	VARCHAR(32)	PUBLIC/LOGIN/PASSWORD/CUSTOMER
access_password	VARCHAR(128)	访问密码，加密保存
max_access_count	INT	最大访问次数
access_count	INT	已访问次数
expire_time	DATETIME	过期时间
status	TINYINT	0禁用，1启用，2过期，3作废

 

 gen_share_access_log 数据字典

字段名	类型	说明
id	BIGINT	主键ID
tenant_id	BIGINT	租户ID
share_code	VARCHAR(64)	分享短码
share_id	BIGINT	分享ID
visitor_id	BIGINT	访问用户ID
visitor_type	VARCHAR(32)	CUSTOMER/STAFF/ANONYMOUS
visitor_ip	VARCHAR(64)	访问 IP
user_agent	VARCHAR(500)	浏览器 UA
device_type	VARCHAR(32)	PC/H5/MINI_APP/APP
referer	VARCHAR(500)	来源地址
access_result	TINYINT	0失败，1成功
fail_reason	VARCHAR(255)	失败原因

 

12. 后端接口设计

12.1 模板管理接口

接口	方法	说明
/admin/gen/template/create	POST	新增模板
/admin/gen/template/update	PUT	编辑模板
/admin/gen/template/detail	GET	模板详情
/admin/gen/template/page	GET	模板分页
/admin/gen/template/enable	POST	启用模板
/admin/gen/template/disable	POST	禁用模板
/admin/gen/template/setDefault	POST	设置默认模板
/admin/gen/template/preview	POST	模板预览

 

12.2 图片生成接口

接口	方法	说明
/admin/gen/image/generate	POST	生成单张图片
/admin/gen/image/preview	POST	图片预览
/admin/gen/image/batchGenerate	POST	批量生成图片
/admin/gen/image/task/{taskNo}	GET	查询生成任务

 

图片生成请求示例

{

  "sceneCode": "GOODS_POSTER",

  "bizType": "GOODS",

  "bizId": 10001,

  "templateCode": "goods_poster_default",

  "forceRefresh": false,

  "extraParams": {

    "showPrice": true,

    "showQrCode": true

  }

}

 

12.3 PDF 生成接口

接口	方法	说明
/admin/gen/pdf/generate	POST	生成 PDF
/admin/gen/pdf/preview	POST	PDF 预览
/admin/gen/pdf/batchGenerate	POST	批量生成 PDF
/admin/gen/pdf/merge	POST	合并 PDF
/admin/gen/pdf/download/{assetNo}	GET	下载 PDF

 

PDF 生成请求示例

{

  "sceneCode": "SALE_ORDER_PDF",

  "bizType": "OMS_ORDER",

  "bizId": 20001,

  "templateCode": "sale_order_a4_default",

  "watermark": "已审核",

  "forceRefresh": false

}

 

12.4 分享码接口

接口	方法	说明
/admin/gen/share/create	POST	创建分享码
/admin/gen/share/disable	POST	禁用分享码
/admin/gen/share/refreshQrCode	POST	刷新二维码
/admin/gen/share/detail	GET	分享码详情
/admin/gen/share/page	GET	分享码分页
/s/{shareCode}	GET	外部分享访问入口

 

分享码创建请求示例

{

  "shareType": "ORDER",

  "bizType": "OMS_ORDER",

  "bizId": 20001,

  "shareTitle": "销售订单 SO202604270001",

  "targetUrl": "/h5/order/detail?id=20001",

  "accessMode": "PUBLIC",

  "expireTime": "2026-05-27 23:59:59",

  "maxAccessCount": 100

}

 

13. 后端工程结构与核心代码骨架

推荐工程目录

com.sxb.generator

├── controller

│   ├── GenTemplateController.java

│   ├── GenRenderController.java

│   ├── GenShareController.java

│   └── GenAssetController.java

├── service

│   ├── GenTemplateService.java

│   ├── GenRenderTaskService.java

│   ├── GenImageRenderService.java

│   ├── GenPdfRenderService.java

│   ├── GenShareCodeService.java

│   ├── GenAssetService.java

│   └── GenAccessLogService.java

├── facade

│   ├── GenImageFacade.java

│   ├── GenPdfFacade.java

│   └── GenShareFacade.java

├── adapter

│   ├── GenBizDataAdapter.java

│   ├── GoodsPosterDataAdapter.java

│   ├── SaleOrderPdfDataAdapter.java

│   ├── CustomerBillDataAdapter.java

│   └── StoreShareDataAdapter.java

├── renderer

│   ├── ImageRenderer.java

│   ├── PdfRenderer.java

│   ├── QrCodeRenderer.java

│   └── BarcodeRenderer.java

├── storage

│   ├── FileStorageService.java

│   ├── LocalFileStorageService.java

│   ├── OssFileStorageService.java

│   └── MinioFileStorageService.java

├── entity

├── mapper

├── dto

├── vo

├── enums

└── config

 

13.1 业务数据适配器接口

GenBizDataAdapter.java

public interface GenBizDataAdapter {

 

    /**

     * 是否支持当前生成场景。

     */

    boolean support(String sceneCode, String bizType);

 

    /**

     * 加载模板渲染所需业务数据。

     */

    Map<String, Object> loadData(GenRenderContext context);

}

 

13.2 生成 Facade 设计

Facade 接口建议

public interface GenPdfFacade {

 

    /**

     * 生成业务 PDF。

     */

    GenRenderResult generate(GenPdfGenerateDTO dto);

 

    /**

     * 预览业务 PDF。

     */

    GenRenderPreviewVO preview(GenPdfPreviewDTO dto);

}

 

public interface GenImageFacade {

 

    /**

     * 生成业务图片。

     */

    GenRenderResult generate(GenImageGenerateDTO dto);

}

 

public interface GenShareFacade {

 

    /**

     * 创建业务分享码。

     */

    GenShareCreateVO createShareCode(GenShareCreateDTO dto);

}

 

14. 前端页面与交互设计

14.1 模板管理页面

区域	字段/按钮	说明
查询区	模板名称、模板类型、业务类型、场景编码、状态	用于筛选模板。
列表区	模板名称、类型、场景、默认、状态、更新时间	展示模板基础信息。
操作区	新增、编辑、复制、设计、预览、设为默认、启用、禁用、删除	模板管理操作。
设计区	背景、文本、图片、二维码、表格、页眉页脚	第二阶段建设拖拽式设计器。

 

14.2 生成记录页面

字段	说明
任务编号	生成任务唯一编号。
生成类型	IMAGE / PDF / QRCODE / SHARE。
业务类型	商品、订单、采购、仓库、财务等。
场景编码	GOODS_POSTER、SALE_ORDER_PDF 等。
业务单号	业务单据编号。
状态	待生成、生成中、成功、失败、取消。
文件大小	生成文件大小。
错误信息	失败时展示简短原因。
操作	查看、下载、重试、删除。

 

14.3 分享码管理页面

字段/按钮	说明
分享标题	对外展示标题。
分享类型	商品、订单、门店、活动、账单。
分享短码	SXBA8K29。
分享链接	支持复制。
二维码	支持预览和下载。
访问方式	公开、登录、密码、指定客户。
有效期	过期后自动禁止访问。
访问次数	当前访问次数和最大访问次数。
操作按钮	复制链接、下载二维码、查看访问记录、禁用分享、刷新二维码。

 

15. 权限、安全、审计设计

15.1 菜单权限

菜单结构建议

系统管理

  └─ 生成中心

      ├─ 模板管理

      ├─ 生成记录

      ├─ 分享码管理

      └─ 访问日志

 

15.2 按钮权限

权限编码	权限说明
gen:template:create	新增模板
gen:template:update	编辑模板
gen:template:delete	删除模板
gen:template:design	设计模板
gen:image:generate	生成图片
gen:pdf:generate	生成 PDF
gen:share:create	生成分享码
gen:share:disable	禁用分享码
gen:asset:download	下载生成文件
gen:task:retry	重试生成任务

 

15.3 安全规则

规则	说明
分享码不暴露业务 ID	外部链接只暴露 shareCode，内部通过 gen_share_code 查业务对象。
敏感分享需要签名	可使用 HMAC_SHA256(shareCode + timestamp + secret) 防篡改。
密码加密保存	access_password 不得明文保存，建议 BCrypt 或系统统一加密组件。
文件下载鉴权	后台下载必须校验登录和业务权限。外部分享下载必须校验分享策略。
访问日志必写	成功和失败都应记录，便于排查和风控。
过期任务清理	过期文件和过期分享需要定时清理或置为无效。

 

16. 异步任务、幂等与重试机制

16.1 幂等键设计

同一业务、同一场景、同一模板、同一版本重复生成时，应优先复用已生成且有效的文件。

幂等键示例

idempotentKey =

tenantId + "_" +

sceneCode + "_" +

bizType + "_" +

bizId + "_" +

templateCode + "_" +

templateVersion

 

示例：

1_GOODS_POSTER_GOODS_10001_goods_default_v1

 

16.2 重试策略

场景	是否重试	建议
模板不存在	否	属于配置问题，直接失败。
业务数据不存在	否	属于业务问题，直接失败。
渲染服务异常	是	最多重试 3 次。
文件上传失败	是	最多重试 3 次，可指数退避。
网络超时	是	重试并记录每次失败原因。
权限不足	否	禁止生成。

 

17. 与业务模块集成方案

业务模块	推荐入口	集成方式
商品管理	商品详情、商品列表	生成商品海报、商品标签、商品二维码。
销售订单	订单详情、审核后操作区	导出销售单 PDF、生成客户确认链接。
采购订单	采购详情	导出采购单 PDF、供应商确认链接。
仓库 WMS	入库单、出库单、盘点单详情	导出 PDF、打印单据、生成分享链接。
财务对账	客户对账单、供应商对账单	生成 PDF、发送分享链接、记录客户访问。
门店商城	门店设置、商城装修	生成门店分享码、商品分享海报。
配送签收	配送任务、签收记录	生成签收凭证图、签收单 PDF。

 

17.1 订单 PDF 集成示例

订单 PDF 集成流程

销售订单详情页点击【导出 PDF】

  ↓

前端调用 /admin/gen/pdf/generate

  ↓

传入 sceneCode=SALE_ORDER_PDF, bizType=OMS_ORDER, bizId=订单ID

  ↓

生成中心校验订单查看权限

  ↓

SaleOrderPdfDataAdapter 加载订单数据

  ↓

PdfRenderer 渲染并上传文件

  ↓

返回 PDF 下载地址

 

18. 配置中心与参数设计

参数	示例值	说明
gen.storage.type	OSS / MINIO / LOCAL	生成文件存储类型。
gen.storage.basePath	/gen	文件根路径。
gen.share.domain	https://sxb.com	分享链接域名。
gen.share.codePrefix	SXB	分享短码前缀。
gen.share.defaultExpireDays	30	默认分享有效天数。
gen.task.maxRetryCount	3	默认最大重试次数。
gen.pdf.defaultPageSize	A4	默认 PDF 页面大小。
gen.image.defaultFormat	png	默认图片格式。
gen.qrcode.defaultSize	400	默认二维码尺寸。

 

19. 测试验收清单

测试类别	验收点
模板测试	新增、编辑、复制、启用、禁用、设默认、预览正常。
变量测试	文本、金额、日期、图片、二维码、表格变量可正确渲染。
图片测试	商品海报、门店海报、标签生成清晰，中文不乱码。
PDF 测试	多页分页正常，表格不截断，水印、页眉页脚正常。
分享码测试	短码唯一，二维码可扫码，过期、密码、访问次数限制有效。
权限测试	无业务查看权限不能生成和下载业务文件。
幂等测试	重复请求返回同一有效资产，不重复创建无意义文件。
重试测试	上传失败、渲染失败可按规则重试并记录失败信息。
审计测试	生成、下载、访问成功/失败均有日志。
兼容测试	后台、H5、小程序、移动端扫码入口正常。

 

20. 分阶段落地计划

阶段	建设内容	建议目标
第一阶段：基础可用版	模板管理、图片生成、PDF 生成、分享码、文件资产、访问日志	支撑商品海报、销售单 PDF、客户对账单、门店分享码。
第二阶段：设计器增强版	拖拽模板设计器、模板版本、模板预览、表格配置、页眉页脚配置	减少开发介入，让运营/实施人员可配置模板。
第三阶段：企业增强版	批量生成、异步队列、自动重试、CDN、访问统计、客户确认回执、模板多语言	支撑多租户、高并发、复杂业务传播场景。

 

20.1 第一阶段建议优先完成清单

序号	任务	交付物
1	创建 gen_ 核心表	DDL、Entity、Mapper。
2	实现文件资产服务	FileStorageService + OSS/MinIO/Local 实现。
3	实现模板管理接口	模板 CRUD、启停、默认模板。
4	实现图片生成	商品海报、门店二维码。
5	实现 PDF 生成	销售订单 PDF、客户对账单 PDF。
6	实现分享码	短码、二维码、访问入口、访问日志。
7	对接业务页面	商品详情、订单详情、对账单详情按钮。

 

21. 附录：DDL 与枚举建议

21.1 核心枚举

枚举建议

public enum GenTemplateTypeEnum {

    IMAGE,

    PDF,

    SHARE_PAGE

}

 

public enum GenRenderTypeEnum {

    IMAGE,

    PDF,

    QRCODE,

    BARCODE,

    SHARE

}

 

public enum GenRenderTaskStatusEnum {

    WAITING(0, "待生成"),

    PROCESSING(1, "生成中"),

    SUCCESS(2, "生成成功"),

    FAILED(3, "生成失败"),

    CANCELED(4, "已取消");

}

 

public enum GenShareAccessModeEnum {

    PUBLIC,

    LOGIN,

    PASSWORD,

    CUSTOMER

}

 

public enum GenShareStatusEnum {

    DISABLED(0, "禁用"),

    ENABLED(1, "启用"),

    EXPIRED(2, "已过期"),

    CANCELED(3, "已作废");

}

 

核心 DDL 示例（节选，可直接扩展为完整 SQL 文件）

CREATE TABLE gen_template (

    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',

    tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',

    template_code VARCHAR(64) NOT NULL COMMENT '模板编码',

    template_name VARCHAR(128) NOT NULL COMMENT '模板名称',

    template_type VARCHAR(32) NOT NULL COMMENT '模板类型：IMAGE/PDF/SHARE_PAGE',

    biz_type VARCHAR(64) NOT NULL COMMENT '业务类型',

    scene_code VARCHAR(64) NOT NULL COMMENT '场景编码',

    render_engine VARCHAR(32) NOT NULL COMMENT '渲染引擎',

    template_content LONGTEXT NULL COMMENT '模板内容',

    template_config JSON NULL COMMENT '模板配置JSON',

    preview_image_url VARCHAR(500) NULL COMMENT '模板预览图',

    width INT NULL COMMENT '图片宽度',

    height INT NULL COMMENT '图片高度',

    page_size VARCHAR(32) NULL COMMENT 'PDF页面大小',

    status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：0禁用，1启用',

    is_default TINYINT NOT NULL DEFAULT 0 COMMENT '是否默认模板',

    sort_no INT NOT NULL DEFAULT 0 COMMENT '排序号',

    remark VARCHAR(500) NULL COMMENT '备注',

    create_by BIGINT NULL COMMENT '创建人',

    create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

    update_by BIGINT NULL COMMENT '更新人',

    update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0未删，1已删',

    PRIMARY KEY (id),

    UNIQUE KEY uk_template_code (tenant_id, template_code, deleted),

    KEY idx_scene_code (tenant_id, scene_code),

    KEY idx_template_type (tenant_id, template_type)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='生成中心-模板主表';

 

CREATE TABLE gen_template_variable (

    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',

    tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',

    template_id BIGINT NOT NULL COMMENT '模板ID',

    variable_code VARCHAR(64) NOT NULL COMMENT '变量编码',

    variable_name VARCHAR(128) NOT NULL COMMENT '变量名称',

    variable_type VARCHAR(32) NOT NULL COMMENT '变量类型',

    data_path VARCHAR(255) NULL COMMENT '数据路径',

    default_value VARCHAR(500) NULL COMMENT '默认值',

    required TINYINT NOT NULL DEFAULT 0 COMMENT '是否必填',

    format_rule VARCHAR(255) NULL COMMENT '格式化规则',

    remark VARCHAR(500) NULL COMMENT '备注',

    create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

    update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0未删，1已删',

    PRIMARY KEY (id),

    UNIQUE KEY uk_template_variable (tenant_id, template_id, variable_code, deleted),

    KEY idx_template_id (template_id)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='生成中心-模板变量表';

 

CREATE TABLE gen_render_task (

    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',

    tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',

    task_no VARCHAR(64) NOT NULL COMMENT '生成任务编号',

    render_type VARCHAR(32) NOT NULL COMMENT '生成类型',

    biz_type VARCHAR(64) NOT NULL COMMENT '业务类型',

    scene_code VARCHAR(64) NOT NULL COMMENT '场景编码',

    biz_id BIGINT NULL COMMENT '业务ID',

    biz_no VARCHAR(64) NULL COMMENT '业务单号',

    template_id BIGINT NULL COMMENT '模板ID',

    request_param JSON NULL COMMENT '请求参数',

    render_data JSON NULL COMMENT '渲染数据',

    status TINYINT NOT NULL DEFAULT 0 COMMENT '状态',

    retry_count INT NOT NULL DEFAULT 0 COMMENT '重试次数',

    max_retry_count INT NOT NULL DEFAULT 3 COMMENT '最大重试次数',

    error_message TEXT NULL COMMENT '错误信息',

    asset_id BIGINT NULL COMMENT '生成文件ID',

    start_time DATETIME NULL COMMENT '开始时间',

    finish_time DATETIME NULL COMMENT '完成时间',

    idempotent_key VARCHAR(128) NULL COMMENT '幂等键',

    create_by BIGINT NULL COMMENT '创建人',

    create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',

    update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',

    deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0未删，1已删',

    PRIMARY KEY (id),

    UNIQUE KEY uk_task_no (tenant_id, task_no),

    UNIQUE KEY uk_idempotent_key (tenant_id, idempotent_key, deleted),

    KEY idx_biz (tenant_id, biz_type, biz_id),

    KEY idx_status (tenant_id, status, create_time)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='生成中心-生成任务表';

 

21.2 最终落地结论

结论：升鲜宝应把图片生成、PDF 生成、分享码生成统一建设为 gen 生成中心。业务模块只传 sceneCode + bizType + bizId + templateCode，生成中心统一完成模板渲染、文件存储、分享访问和日志审计。这样后续商品海报、销售单 PDF、客户对账单、门店商城码、活动推广码、配送签收凭证都能复用同一套组件。