ERP 数据对接 | 杭州高晟生物科技有限公司

Architecture

同步链路

ERP 是唯一数据源，官网只做展示与查询，不产生第二份产品数据。

ERP 系统产品档案 / 价格 / 库存

→

同步接口REST API · 每 30 分钟

→

官网数据层字段映射 · 清洗 · 缓存

→

前端展示产品中心 / 搜索 / 详情

容错设计：接口不可用时，官网自动回落到上一次成功同步的缓存数据并标注状态，确保任何情况下产品页都不会出现空白。缓存有效期 30 分钟，过期后自动重试接口。

Modes

三种接入模式，按现有条件选

不同企业的 ERP 开放程度差别很大，所以接入方式不强制统一。

API 直连（推荐）

ERP 开放 REST 接口，官网按分页拉取产品列表，库存与价格实时性最好。

适合：金蝶 / 用友 / 管家婆等有开放接口的 ERP
同步频率：可配置，默认 30 分钟
优点：无需人工干预，数据最新

mode: "erp"

定时导出 JSON

ERP 定时导出产品表为 JSON 文件，由脚本转换后覆盖到网站数据目录。

适合：无开放接口、但可定时导表的 ERP
同步频率：随导出计划，通常每日一次
优点：改动小，不涉及 ERP 二次开发

mode: "static"

混合兜底

优先走 API，失败时自动使用静态 JSON 或缓存，兼顾实时性与稳定性。

适合：接口稳定性一般、或有内网限制的环境
同步频率：接口优先 + 每日兜底
优点：单点故障不影响网站可用

mode: "hybrid"（默认）

Field Mapping

字段映射表

不同 ERP 的字段命名各不相同（金蝶 FNumber、用友 code、自研系统 goods_sn…）。接入时只需在配置里补齐字段别名，页面代码完全不用改。

官网字段	类型	可识别的 ERP 字段名	必填
`sku` 产品编码	string	sku, code, itemCode, FNumber, product_code, goods_sn	必填
`name` 产品名称	string	name, itemName, FName, product_name, goods_name	必填
`cat` 所属分类	string	cat, category, categoryId, FGroup, cat_id, type	选填
`spec` 规格型号	string	spec, specification, model, FModel, 规格	选填
`unit` 包装单位	string	unit, unitName, FUnit, 单位	选填
`price` 销售价格	number	price, salePrice, retailPrice, sale_price, 价格	选填
`stock` 库存数量	number	stock, qty, quantity, inventory, FQty, 库存	选填
`brand` 品牌	string	brand, brandName, FBrand, manufacturer	选填
`storage` 保存条件	string	storage, storageCondition, store_temp, 保存条件	选填
`desc` 产品说明	string	desc, description, remark, FNote, 描述	选填
`tags` 标签	string[]	tags, labels, keywords, 标签（逗号分隔）	选填
`status` 上下架	bool/int	status, state, isActive, 上架	选填
`updatedAt` 更新时间	string	updatedAt, updateTime, FModifyDate, modify_time	选填

价格字段说明：未返回价格、或价格为空的产品，官网显示为「面议」而非 0 元，避免误导客户。库存小于 50 标注「库存紧张」，库存为 0 标注「询价」。

方法	路径	说明
GET	`/api/v1/products`	产品列表，支持 `page`、`pageSize` 分页参数
GET	`/api/v1/products/{sku}`	按产品编码查询单品详情
GET	`/api/v1/categories`	产品分类列表（可选）
POST	`/api/v1/webhook/stock`	库存变更主动推送（可选，实现近实时同步）

认证方式

支持 Bearer Token、API Key（自定义 Header）与 Basic Auth 三种。出于安全考虑，建议通过服务端代理转发请求，不在前端代码中硬编码密钥。

# Bearer Token
Authorization: Bearer <token>

# API Key
X-API-Key: <your-api-key>

# Basic Auth
Authorization: Basic <base64(user:pass)>

官网兼容多种常见响应结构：数组、{data:[]}、{list:[]}、{items:[]}、{records:[]}，以及带 total 的分页结构，无需改动 ERP 现有输出格式。

{
  "total": 128,
  "page": 1,
  "pageSize": 100,
  "data": [
    {
      "sku": "GS-MB-1001",
      "name": "2× Taq PCR MasterMix",
      "cat": "分子生物学试剂",
      "spec": "1mL×5",
      "unit": "盒",
      "price": 320.00,
      "stock": 268,
      "storage": "-20℃",
      "tags": ["含染料", "即用型"],
      "status": 1,
      "updatedAt": "2026-11-05 09:30:00"
    }
  ]
}

配置文件位于 assets/js/api.js 顶部的 CONFIG 对象。切换到真实 ERP 只需修改这里。

const CONFIG = {
  // 数据源模式：'static' | 'erp' | 'hybrid'
  mode: "hybrid",

  staticUrl: "data/products.json",

  erp: {
    baseUrl: "https://erp.gaosheng-bio.com/api/v1",
    productPath: "/products",
    authType: "bearer",        // bearer | apikey | basic | none
    token: "",                  // 建议由服务端代理注入
    pageMode: "page",            // page | all
    pageSize: 100,
    timeout: 8000
  },

  cacheTTL: 1000 * 60 * 30          // 缓存 30 分钟
};

字段别名扩展

假如你的 ERP 用 goods_sn 表示编码、retailPrice 表示价格，只需把它们加入数组即可，数组越靠前优先级越高。

const FIELD_MAP = {
  sku:   ["sku", "code", "goods_sn"],
  price: ["price", "retailPrice", "salePrice"]
  // ...其余字段同理
};

项目内提供了一个本地模拟 ERP 服务，可以在不接真实系统的情况下完整验证同步流程。

# 1. 启动模拟 ERP 服务（默认端口 8787）
node tools/mock-erp.mjs

# 2. 另开一个终端，启动网站静态服务
node tools/serve.mjs

# 3. 浏览器打开
http://localhost:5173/erp.html

# 4. 验证接口本身
curl http://localhost:8787/api/v1/products?page=1&pageSize=3

验证要点：产品页顶部的同步状态条会显示当前数据源（ERP / STATIC / CACHE）。把模拟服务停掉后刷新，状态条应自动变为橙色并提示"缓存数据"，说明容错机制生效。

Onboarding

接入流程

通常 3–5 个工作日可以完成从字段梳理到上线的全过程。

01

梳理字段

确认 ERP 中产品档案的字段名、分类体系与价格口径，形成映射表。

02

联调接口

配置地址与认证方式，拉取样本数据，处理分类归并与异常值。

03

核对数据

抽样比对官网展示与 ERP 实际值，确认价格、单位、库存口径一致。

04

上线监控

切换正式数据源，配置同步频率与失败告警，进入日常运维。

需要技术人员对接？

把 ERP 类型和接口文档发过来，我们评估后给出具体对接方案。

联系技术对接查看同步效果

产品数据，一次维护，全站同步