VWCG-1072 滨州一卡通对接本地沉淀

日期：2026-07-13；商户编号：zhct_bzjk；目标项目：zhctproject/store。

核心结论

配置统一存放在 ydy_config.config_key = one_card，不写 PHP 配置文件。
同步顺序为 identity -> department -> account -> balance，card 已合并到 account。
业务接口 token 必须放 URL query：?access_token=...，Header Access-Token 无效。
人员手机号不使用一卡通 phoneNo，统一按 accNum 生成或复用虚拟手机号。
余额同步只请求本地确认有效的正常卡：acc_status_num=1，且本地 ydy_staff_card.card_status=1、未注销、未删除。

接口链路

同步项	接口	作用
认证	`GET /api/token`	获取 access_token，支持 expires_in=0 永久 token。
身份	`POST /api/common/queryaccclass`	同步一卡通身份类别到 `ydy_identity_type` 和 `ydy_one_card_identity_map`。
部门版本	`POST /api/common/systemdocking/getaccdepfixid`	获取部门最新版本。
部门增量	`POST /api/common/systemdocking/getaccdepinfobyfixid`	同步部门到 `ydy_department` 和部门映射表。
人员版本	`POST /api/common/systemdocking/getaccfixid`	获取人员账户最新版本。
人员与当前主卡	`POST /api/common/systemdocking/getaccinfobyfixid`	同步人员、用户、部门关系、当前主卡和账户映射。
余额	`POST /api/common/infoqueryservice/getewallet`	按 `accNum` + `cardAccNum` 查询钱包余额。

关键字段映射

来源	目标	说明
`accNum`	`ydy_one_card_account_map.acc_num`	一卡通账户唯一键。
`perCode`	`ydy_staff.personnel_umber` / `ydy_user.account`	人员编号优先来源。
`accName`	`ydy_staff.name` / `ydy_user.name`	人员姓名。
`accDepNum`	`ydy_one_card_account_map.acc_dep_num`	再映射到本地部门 UUID。
`clsNum`	`ydy_one_card_account_map.cls_num`	再映射到本地身份类别 ID。
`decimalismCardSid/cardSid`	`ydy_staff_card.card_id`	当前主卡物理卡号。
`accStatusNum`	`ydy_one_card_account_map.acc_status_num`	不驱动 `ydy_staff.status/job_status`。
`balance`	`ydy_one_card_account_map.balance` / `ydy_user.balance` / `yoshop_user.balance`	余额快照。

手机号规则

不使用一卡通 phoneNo。
优先复用 ydy_one_card_account_map.sync_mobile。
accNum 为 11 位以内纯数字时左补 0 到 11 位，mobile_source=2。
其他情况用 sha256(business:accNum:salt) 生成 9 开头 11 位手机号，最多尝试 10000 个 salt，mobile_source=3。

卡状态规则

一卡通状态	本地状态
`accStatusNum=1` 且卡正常	`1` 正常
`cardStatus=2`	`2` 挂失
`accStatusNum=3` 或 `4`	`3` 冻结
`accStatusNum=0` 或 `cardStatus=0`	`5` 注销
`recFlag != 1`	`4` 退卡

余额失败样例

POST http://144.123.151.2:38080/easytong_app/api/common/infoqueryservice/getewallet?access_token=<masked>

accNum=26
cardAccNum=49
eWalletId=1
epId=1
sign=FA80446255F3961FF02089DA5A8E7E8A

返回：
{"code":"41004","msg":"钱包无数据"}

本地映射显示该账户 accStatusNum=0，属于销户账户。代码已按业务规则跳过这类无效卡，不再请求钱包接口。

已验证数据

重新同步人员：account total=192 created=192 updated=0 fix_id=0->542。
人员、用户、账户映射各 192 条。
手机号空、人员编号空、内部手机号重复、部门映射缺失、身份映射缺失均为 0。
卡记录 190 条：正常 182、冻结 1、注销 7。
余额 dry-run：balance total=182 created=0 updated=182 fix_id=0->0，只请求 182 张有效正常卡。
AI 侧按 store 的 ai_user_id 反查有 192 条 user/staff/bind，但 business 取系统 BUSINESS 常量。

详细 Markdown

完整技术记录见同目录 Markdown：one-card-binzhou-integration-record.md。