电商集成方案

集成全景

图模工坊不抢电商系统的”商品 / 订单 / 支付 / 物流”主路，它只插在一个明确位置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

[ 电商主站 / 小程序 / APP ]
          │
          │ ① 选品 / 加购 / 下单（你既有的逻辑）
          │
          ▼
[ 电商订单系统 ]
          │
          │ ② 创建订单后调 pf-service：
          │    POST /api/app/orders   传入 orderNo / userId / 商品规格
          │
          ▼
[ 图模工坊 (Printing Factory) ]
          │
          │ ③ 跳转 H5 工坊：
          │    https://pf.example.com/?orderNo=xxx&token=xxx
          │
          ▼
[ 用户在 pf-app 选模板、传图、编辑、提交 ]
          │
          │ ④ 后台自动合成
          │
          ▼
[ 电商订单系统 ] ← ⑤ pf-service 回调通知合成结果
          │
          │ ⑥ 管理员在 pf-manage 审核
          │
          ▼
[ 打印生产 / 物流 ]

集成的本质是三个边界：账号、订单、回调。下面分别说明。

接口路径均以 /api/* 为前缀（/api/manage、/api/app、/api/download…），历史文档里的 /pf-manage、/shared 前缀已废弃。下方接口中订单同步/回调部分为集成方案建议，当前订单主要由 pf-manage 侧按商品规格批量创建；确切接口以 pf-service 的 Swagger（/docs）为准。

边界一：账号与跳转

方案 A — 共享账号（推荐）

电商主站的会员体系作为唯一身份源；pf-service 暴露 POST /api/manage/auth/exchange 接收主站签的临时 token，校验后下发 pf-service 的 access token。

1
2
3
4
5

小程序/H5
  → 主站接口生成 ticket
  → 跳转 https://pf.example.com/app/?ticket=xxx&orderNo=...
  → pf-app 启动时 POST /api/manage/auth/exchange { ticket }
  → 拿到 pf-service token + 用户上下文

方案 B — 独立账号 + 嵌入登录

用户在主站登录，pf-app 内嵌登录页（手机号验证码 / 微信授权）；适合主站和工坊在不同主体或想沉淀工坊侧独立用户。

方案 C — 完全嵌入 iframe

主站把 pf-app 以 iframe 嵌入；通过 postMessage 互传订单上下文与回调。

边界二：订单与商品

订单层只需要解决一件事：告诉工坊”这单要做什么”。工坊侧订单当前主要由 pf-manage 按商品规格创建；若要主站直接推送，可约定如下同步接口（以实际 Swagger 为准）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

POST /api/app/orders
Content-Type: application/json
Authorization: Bearer <主站签发或共享的 token>

{
  "orderNo": "2025001234567",
  "userId": 1001,
  "goodsName": "70P 8寸方册",
  "goodsNum": 1,
  "albumId": 42,
  "albumSizeId": 7,
  "albumPageCountId": 4,
  "totalAmount": 19900,
  "expireAt": "2025-06-01T23:59:59Z"
}

• orderNo — 主站订单号，工坊端只读
• albumId / albumSizeId / albumPageCountId — 选品阶段已确定
• totalAmount — 仅记录便于追溯，工坊不重新计价（存最小货币单位「分」）
• expireAt — 编辑窗口截止时间，过期工坊禁用编辑

订单创建后，工坊会为其生成一次性订单访问令牌（orders.orderAccessTokenHash），终端用户凭 ?orderNo=&token= 进入 pf-app，无需登录账号。

边界三：合成结果回调

合成完成（成功或失败）后，pf-service 向主站推：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

POST {你的回调地址}
Content-Type: application/json
X-PF-Signature: <hmac-sha256>

{
  "event": "submission.completed",     // 或 submission.failed
  "orderNo": "2025001234567",
  "submissionId": 8801,
  "status": "completed",
  "items": [
    {
      "templateId": 12,
      "composedImageUrls": [
        "https://minio.internal/pf-bucket/outputs/2025001234567/1.png",
        "..."
      ]
    }
  ],
  "timestamp": 1700000000000
}

主站收到后更新本地订单状态、推送用户、入打印队列。

回调可靠性

• 失败重试：1m / 5m / 30m / 2h / 12h 五次退避
• 签名校验：X-PF-Signature = HMAC_SHA256(secret, body)
• 幂等：用 submissionId 做唯一键去重

一个典型集成场景

「在某电商小程序里上架”全家福相册”」的最小集成：

1. 配置阶段（一次性）

   • 在 pf-manage 配好相册 family-album，关联 4 种尺寸 / 3 种 P 数 / 若干内页模板
   • 在主站商品后台勾选”图模工坊定制”，绑定 albumId

2. 用户下单

   • 小程序选品 → 选尺寸 → 选 P 数 → 下单 → 支付
   • 主站创建订单后调 POST /api/app/orders 把订单同步到 pf-service

3. 跳转编辑

   • 主站打开 H5：https://pf.example.com/app/?orderNo=...&token=...
   • 用户在工坊批量传图、调整顺序、加字、预览
   • 点”提交” → POST /api/app/order-templates/submission

4. 合成与回调

   • 后台 Job 自动合成
   • 合成完成 → 回调主站
   • 主站推送用户：”您的相册已制作完成”

5. 审核与生产

   • 管理员在 pf-manage 抽检
   • 通过 → 下载高清 PDF → 进打印队列
   • 不通过 → 驳回 → 通知用户重做

数据所有权

集成清单

接入前确认这 8 项：

• 账号方案（A / B / C）
• 共用 token 或独立 token 的签发流程
• orderNo 主站规则
• 商品 → albumId/templateId 的映射表
• 编辑窗口 expireAt 策略
• 合成完成的回调地址 + 签名密钥
• 失败处理（驳回/重新合成/退款）流程
• 高清成品的归档/取回策略

接口速查

完整接口字段以 pf-service Swagger（http://host:3000/docs）为准；上表的订单同步/回调为集成方案建议，实际以仓库实现为准。

下一步

• 想看库表结构 → 数据模型
• 想看后端入口 → pf-service 后端
• 想拉起来联调 → 快速开始