Printing Factory：项目简介

一句话定位

图模工坊（Printing Factory） 是一套电商传图定制集成解决方案——以”模板配置 → 用户传图 → 自动合成 → 成品交付”为主线，把打印电商最痛的素材规格不统一、多端编辑割裂、合成排版重复劳动等问题，打包成一套可私有化部署的中台。

解决一个问题：你正在做或想做”用户上传图片 → 自动套模板 → 后台批量出图”的打印电商业务，但不想从零造轮子。

它解决什么问题

传统打印电商在交付链路上的常见痛点：

素材规格五花八门：用户上传的图片尺寸、DPI、格式各异，前端不校验，后端合成时翻车
多模板批量出图重：相册、海报这类一单几十张图的场景，运营人工排版三小时，出错率高
设计师与开发互掣肘：设计师画 PSD，开发再用代码”还原”，迭代一次设计稿，开发改一次
跨端编辑割裂：手机端用户编辑、PC 端管理员审核，数据模型不一致，重复实现两套
合成 SDK 商用授权贵：Adobe SDK、Cloudinary 这类按量计费，规模一起来成本不可控

图模工坊把以上痛点整体打包：

以 Leafer 渲染引擎 + JSON sceneJson 描述模板——设计师在 pf-editor 中拖拽出版，前后端都直接消费这份 JSON；
**以 Bun + Elysia + Drizzle 构建薄而快的后端 pf-service**——单服务覆盖鉴权、模板、订单、合成、文件、字体、背景库；
以 Puppeteer 无头浏览器做合成——把模板的 sceneJson 直接渲染成图片，所见即所得，零适配；
以 Quasar 双端复用同一份代码——pf-app（H5 用户端）和 pf-editor（管理员模板编辑器）共用组件与 API；
以独立 pf-face-service（FastAPI + InsightFace）做人脸框检测——证件照、写真、相册自动避脸裁剪。

核心价值

1. 全私有化部署。 MySQL / Redis / MinIO / 人脸模型 / 合成引擎全部跑在你自己的机房，用户素材 100% 留内网，符合打印行业普遍的数据合规要求。

2. 一份 sceneJson 走天下。 模板编辑、用户编辑、后台合成、订单审核共用同一份 JSON 描述，不需要”为合成单独画一份”。

3. 工程级合成流水线。 自带订单提交主表 + 明细表 + 后台轮询合成 Job，单条订单几十张图也能稳定推过，失败重试、状态机一应俱全。

4. 移动端体验优先。 用户端 pf-app 基于 Quasar，触控/拍照/相册批量上传/分片上传都按 H5 场景调优，非专业用户也能在手机上完成定制。

5. 模块化能力可裁剪。 人脸检测、字体库、背景库、模板版本控制都是独立模块，业务方可按需启停；后端纯 TypeScript，二开门槛低。

它适合谁

角色	建议读
决策者 / 解决方案架构师	项目简介（本页）、系统架构、电商集成
产品 / 业务方	项目简介、电商集成、FAQ
后端开发	pf-service、数据模型、自动合成
前端开发	模板编辑器、用户端 H5、传图与裁剪
运维 / SRE	快速开始、部署拓扑、配置参考
算法 / 视觉	人脸检测服务

技术栈一览

┌───────────────────────────────────────────────────────────────┐
│  用户端     │  pf-app          (Quasar 2.16 H5, 端口 8000)    │
│  编辑器     │  pf-editor       (Quasar 2.16,    端口 9000)    │
│  管理后台   │  pf-manage       (Naive UI,       端口 9527)    │
├───────────────────────────────────────────────────────────────┤
│  后端 API   │  pf-service      (Bun + Elysia,   端口 3000)    │
│  人脸检测   │  pf-face-service (Python FastAPI, 端口 3010)    │
├───────────────────────────────────────────────────────────────┤
│  数据层     │  MySQL 8.0 (Drizzle ORM)                        │
│             │  Redis 6.x   (缓存/会话/任务)                    │
│             │  MinIO       (素材/成品 S3 兼容对象存储)         │
├───────────────────────────────────────────────────────────────┤
│  渲染/合成  │  Leafer 2.x        (浏览器侧矢量渲染)            │
│             │  Puppeteer 24.x    (后端无头浏览器合成)          │
│             │  InsightFace SCRFD (人脸框检测)                  │
└───────────────────────────────────────────────────────────────┘

包管理器与构建：Bun 1.x 统一驱动 monorepo（apps/* + packages/*）。

项目仓库结构

printing-factory/
├── apps/
│   ├── pf-app/          # 用户端 H5（Quasar，端口 8000）
│   ├── pf-editor/       # 模板编辑器（Quasar，端口 9000）
│   ├── pf-manage/       # 管理后台（Naive UI / soybean-admin，端口 9527）
│   ├── pf-service/      # 后端服务（Elysia + Drizzle，端口 3000）
│   └── pf-face-service/ # 人脸检测（FastAPI + InsightFace，端口 3010）
├── packages/            # 共享包（@sa/* / 内部工具）
│   ├── alova / axios    # 请求库封装
│   ├── color / utils    # 通用工具
│   ├── hooks            # Vue 组合式函数
│   ├── materials        # 素材库内置元件
│   ├── scripts          # 构建脚本
│   └── uno-preset       # UnoCSS 预设
├── docs/                # 项目设计文档
├── AGENTS.md            # 工程规范
└── package.json         # Workspaces 入口