基础数据同步：仓库/员工/往来单位同步实现一、同步架构设计三个基础档案（仓库、员工、往来单位）数据量较小，采用全量 Q

一、同步架构设计

三个基础档案（仓库、员工、往来单位）数据量较小，采用全量 Query → UPSERT 模式，共享同一套同步框架。

graph TB

二、仓库同步 (sync_warehouse.php)

2.1 API 接口

POST https://openapi.chanjet.com/tplus/api/v2/warehouse/Query
Headers:
  appKey: {appKey}
  appSecret: {appSecret}
  openToken: {accessToken}
Content-Type: application/json

{
    "param": {
        "SelectFields": "ID,Code,Name,WarehouseType.Code,WarehouseType.Name,Memo,Address,Admin.Code,Admin.Name,TS"
    }
}

2.2 数据字段映射

API 字段路径	数据库列	类型	说明
`ID`	`tplus_id`	INT	T+ 内部 ID
`Code`	`code`	VARCHAR(50)	仓库编码（唯一键）
`Name`	`name`	VARCHAR(100)	仓库名称
`WarehouseType.Code`	`type_code`	VARCHAR(50)	仓库类型编码
`WarehouseType.Name`	`type_name`	VARCHAR(50)	仓库类型名称
`Memo`	`memo`	VARCHAR(500)	备注
`Address`	`address`	VARCHAR(200)	仓库地址
`Admin.Code`	`admin_code`	VARCHAR(50)	负责人编码
`Admin.Name`	`admin_name`	VARCHAR(50)	负责人名称
`TS`	`ts`	VARCHAR(50)	时间戳（预留增量）

2.3 同步代码核心逻辑

function syncWarehouse() {
    $config    = loadConfig();
    $openToken = getValidToken($config);
    $pdo       = getDB($config['db']);

    $url  = 'https://openapi.chanjet.com/tplus/api/v2/warehouse/Query';
    $body = [
        'param' => [
            'SelectFields' => implode(',', [
                'ID', 'Code', 'Name',
                'WarehouseType.Code', 'WarehouseType.Name',
                'Memo', 'Address',
                'Admin.Code', 'Admin.Name', 'TS'
            ])
        ]
    ];

    $res  = callTplusApi($config['appKey'], $config['appSecret'], $openToken, $url, $body);
    $rows = extractRows($res);

    $stmt = $pdo->prepare("
        INSERT INTO tplus_warehouse (...) VALUES (...)
        ON DUPLICATE KEY UPDATE ...
    ");

    foreach ($rows as $r) {
        $stmt->execute([...]);
    }
}

三、员工同步 (sync_employee.php)

3.1 API 接口

POST https://openapi.chanjet.com/tplus/api/v2/person/Query
Content-Type: application/json

{
    "dto": {
        "SelectFields": "ID,Code,Name,Department.Code,Department.Name,
                         MobilePhoneNo,IsSalesMan,Position,Disabled,
                         Gender,EmailAddr,IdentityNo,TS"
    }
}

3.2 数据字段映射

字段	数据库列	说明
`ID`	`tplus_id`	员工 ID
`Code`	`code`	员工编码（唯一键）
`Name`	`name`	员工姓名
`Department.Code`	`department_code`	部门编码
`Department.Name`	`department_name`	部门名称
`MobilePhoneNo`	`mobile_phone`	手机号
`IsSalesMan`	`is_salesman`	是否业务员
`Position`	`position`	职位
`Disabled`	`disabled`	是否停用
`Gender`	`gender`	性别
`EmailAddr`	`email`	邮箱
`IdentityNo`	`id_number`	身份证号

3.3 注意事项

员工 API 请求体使用 dto 而非 param 包裹参数，这是畅捷通不同接口的细微差异：

// 员工 API 使用 dto
$body = ['dto' => ['SelectFields' => $selectFields]];

// 仓库 API 使用 param
$body = ['param' => ['SelectFields' => $selectFields]];

四、往来单位同步 (sync_partner.php)

4.1 API 接口

POST https://openapi.chanjet.com/tplus/api/v2/partner/Query
Content-Type: application/json

{
    "dto": {
        "SelectFields": "ID,Code,Name,Shorthand,PartnerAbbName,
                         PartnerType.Code,PartnerType.Name,
                         PartnerClass.Code,PartnerClass.Name,
                         Contact,MobilePhone,Address,Disabled,TS"
    }
}

4.2 往来单位类型

畅捷通 T+ 中往来单位分三种性质：

类型	partner_type_code	说明
客户	`00`	销售客户
供应商	`01`	采购供应商
客户/供应商	`02`	既是客户也是供应商

4.3 数据字段映射

graph LR

五、同步模式总结

flowchart TD

三模块对比

特性	仓库	员工	往来单位
API URL	`/warehouse/Query`	`/person/Query`	`/partner/Query`
请求体包裹	`param`	`dto`	`dto`
唯一键	`code`	`code`	`code`
数据量	少量（~18）	少量（~48）	中等（~100）
子对象字段	✅ Type/Admin	✅ Department	✅ Type/Class

通用 UPSERT 模式

所有同步模块统一使用 INSERT ... ON DUPLICATE KEY UPDATE 实现幂等写入：

INSERT INTO tplus_warehouse (code, name, type_code, ...)
VALUES (:code, :name, :type_code, ...)
ON DUPLICATE KEY UPDATE
    name = VALUES(name),
    type_code = VALUES(type_code),
    sync_time = NOW()

这样无论是首次同步还是重复执行，都不会产生重复数据，且会自动更新变更记录。