EC ↔ 金蝶云星辰双向数据同步 Skill

功能概述

支持 EC（六度人和）与金蝶云星辰之间的双向数据同步：

方向一：EC → 金蝶（每小时）

客户同步：从 EC 拉取全部客户 → 写入金蝶云星辰客户资料
订单同步：从 EC 拉取已结单订单（status=3）→ 写入金蝶销售订单
增量同步：每次同步后记录时间戳，下次只拉取变更数据
去重逻辑：用 EC 的 crmId 作为金蝶客户编码 number，已存在则更新、不存在则新增

方向二：金蝶 → EC（每日凌晨1点）

商品分类同步：从金蝶拉取商品分类列表 → 写入 EC 产品
增量同步：基于分类修改时间，只同步变更数据
去重逻辑：本地映射表 + EC 产品名称匹配，避免重复创建

触发方式

当用户提到以下需求时触发此 Skill：

"同步 EC 数据到金蝶"
"执行客户同步"
"同步订单"
"EC 数据同步"
"同步金蝶商品分类"
"金蝶分类同步到 EC"
"sync ec to jdy"
"sync jdy products"

使用方式

1. 配置凭证

确保 .env 文件已配置（技能目录下的 .env），包含 EC 和金蝶的 API 密钥：

EC_APP_ID=900333116588032000
EC_APP_SECRET=9PUNq53k2RzwesWr9eJ
EC_CID=请填写企业唯一标识ID
JDY_APP_KEY=S4aaVJSF
JDY_APP_SECRET=336fdd32c484b0f6d238619862cc0b2e7ad59272
JDY_CLIENT_ID=267904
JDY_CLIENT_SECRET=dcdd1a0348f476f43331c614e754f666
JDY_INSTANCE_ID=293477853998223360

2. 执行同步

EC → 金蝶（客户+订单）：

cd /Users/menghu/.workbuddy/skills/ec-to-jdy-sync && python3 scripts/sync.py

金蝶 → EC（商品分类→产品）：

cd /Users/menghu/.workbuddy/skills/ec-to-jdy-sync && python3 scripts/sync_products.py

全量同步：

python3 scripts/sync.py --full        # EC→金蝶 全量
python3 scripts/sync_products.py --full  # 金蝶→EC 全量

3. 定时自动执行

已配置两个 Automation：

每小时：EC → 金蝶客户+订单同步
每日凌晨1点：金蝶 → EC 商品分类同步

脚本架构

ec-to-jdy-sync/
├── SKILL.md              # 本文件
├── .env                  # API 密钥配置
├── state.json            # 同步状态（自动生成，含映射表）
└── scripts/
    ├── sync.py           # EC→金蝶 主同步脚本（客户+订单）
    ├── sync_products.py  # 金蝶→EC 商品分类同步脚本
    ├── ec_client.py      # EC API 客户端
    ├── jdy_client.py     # 金蝶 API 客户端
    ├── state.py          # 同步状态管理（含分类→产品映射）
    └── config.py         # 配置加载

字段映射

方向一：客户映射（EC → 金蝶）

| EC 字段 | 金蝶字段 | 说明 | |---------|----------|------| | crmId | number | 客户编码（唯一键，用于去重） | | name / company | name | 客户名称（企业用 company，个人用 name） | | mobile | mobile | 手机号 | | phone | telephone | 座机 | | email | email | 邮箱 | | prefecture | region_name | 地区 | | companyAddress | address | 地址 | | memo | remark | 备注 | | crmType | customer_type | 客户类型（0→person, 1→company） |

方向一：销售订单映射（EC → 金蝶）

| EC 字段 | 金蝶字段 | 说明 | |---------|----------|------| | code | billno | 订单编码（加 EC- 前缀） | | crmId | customerid_id | 关联金蝶客户编码 | | money | material_entity[].price | 订单金额 | | productId | material_entity[].materialid_id | 物料编码（关联已有物料） | | createTime / dealDate | billdate | 订单日期 | | productDes + remark | remark | 订单备注 |

方向二：商品分类映射（金蝶 → EC）

| 金蝶字段 | EC 字段 | 说明 | |----------|---------|------| | id | 本地映射表记录 | 用于去重判断 | | name | productName | 分类名称 → 产品名称 | | number | 附加信息 | 编码可拼接至产品名 | | — | productUnit | 默认「个」 | | — | money | 默认 0.00 | | — | onOff | 默认 0（上架） | | — | specs | 默认 0（无规格） | | — | optUserId | 操作用户 3446438 |

同步流程

方向一：EC → 金蝶（sync.py）

1. 获取金蝶 app-token（HMAC-SHA256 签名认证）
2. 读取上次同步时间（state.json）
3. 从 EC 拉取变更的客户列表（modifyTime >= last_customer_sync）
   ├── 对每个客户：检查金蝶是否存在（number = crmId）
   │   ├── 存在 → 更新
   │   └── 不存在 → 新增
4. 从 EC 拉取已结单订单列表（creatTime >= last_order_sync, status=3）
   ├── 先确保对应客户已同步到金蝶
   ├── 检查订单是否已存在（billno）
   │   └── 不存在 → 新增
5. 更新同步时间到 state.json
6. 输出同步报告

方向二：金蝶 → EC（sync_products.py）

1. 获取金蝶 app-token
2. 读取上次同步时间（state.json）
3. 从金蝶拉取变更的商品分类（modify_start_time >= last_product_sync）
4. 拉取 EC 已有产品列表（用于名称匹配去重）
5. 对每个分类：
   ├── 查本地映射表，已存在 → 跳过
   ├── 按 productName 匹配 EC 产品，已存在 → 记录映射、跳过
   └── 不存在 → 调用 EC addProduct 创建
6. 更新映射表和同步时间到 state.json
7. 输出同步报告

依赖

Python 3.9+
requests 库（标准安装）

首次使用请确保安装 requests：

pip install requests

注意事项

EC getSales 接口 creatTime 间隔不超过31天，批量同步时需注意
金蝶 app-token 24小时有效，脚本自动缓存和刷新
增量同步：首次执行会从已有数据开始增量，如需全量用 --full
产品映射：EC 的 productId 直接作为金蝶物料编码 materialid_id，需确保金蝶中已存在对应物料
字段映射调整：如需修改字段对应关系，编辑 sync.py 中的 map_ec_customer_to_jdy() 和 map_ec_order_to_jdy() 函数