ZJMF 上游绑定切换与旧接口下线

背景

旧上游身份 mofang_finance_api 不提供实例控制能力，导致管理端服务绑定页面提示“当前上游接口不支持实例控制”。本次在本地开发库中将可证明的实时供应商、商品和服务路由切换到 zjmf_finance_api，启用 ZJMF 插件，并在所有验证通过后卸载旧插件记录。

范围与验收

• [x] 创建可回滚的完整数据库备份，并在写入前记录支付、开通尝试和插件运行日志基线。
• [x] 仅迁移白名单中的实时绑定、运行快照、连接快照及已确认 JSON 顶层 provider 字段；不进行全库文本替换。
• [x] 安装并启用 upstream/zjmf_finance，保留供应商认证密文不变。
• [x] 验证 163 条受影响服务均可解析为 ZJMF，且均支持 ProvidesConsoleRuntime。
• [x] 确认旧心跳无活动队列项，ZJMF 心跳任务已注册；保留历史失败任务作审计。
• [x] 在实时引用清零后卸载 mofang_finance_api 插件记录，并验证财务与运行历史仍在。

执行摘要

回滚点

• 迁移前已创建完整备份：E:\TuraIDC\idc_backup_rollback_20260723_002149_zjmf_pre_migration.sql。
• 备份 SHA-256：a6bfbf00417ca007a09b188c2bd4d2811dae888c36feb6f916878032a08c477f。

受控实时切换

ZJMF 清单已重新安装并启用。切换通过单事务、锁和逐项断言执行，范围及影响如下：

范围	已切换数量
全局插件绑定	1
供应商插件绑定	2
商品上游绑定	143
服务上游绑定	163
服务运行快照	163
服务连接快照	163
服务、绑定快照和运行快照中的已确认 JSON 顶层 provider/provider_key 字段	455 个字段更新

供应商绑定的 secret_json、服务连接密文、original_provider_key、嵌套 JSON、开通尝试和运行日志均未被重写。

历史与残留处理

• 支付记录保持 303 条（主键和为 46056）。
• 带旧 provider key 的开通尝试保持 221 条；插件卸载后其 plugin_id 按数据库外键规则置空，原 provider key 保留。
• 带旧 plugin key 的运行日志保持 9815 条；插件卸载后其 plugin_id 按数据库外键规则置空，原 plugin key 保留。
• 7 条未关联到可确认实时路由的 services.provision_data 历史快照保留原样，未被猜测改写；它们不属于本次 163 条服务绑定范围。

心跳与旧插件

• PluginScheduledTaskProvider 当前只注册 refresh-zjmf-finance-auth 和 sync-zjmf-finance-inventory-and-services 两条 ZJMF 任务。
• 当前 jobs 中没有旧 Mofang 任务，也没有待执行任务；109 条历史失败任务保留，不重试、不改写其序列化 payload。
• 旧插件在所有实时绑定表中的引用均为 0 后，已由 IntegrationPluginService::uninstall() 卸载。旧插件记录已不存在，ZJMF 保持启用。

验证

• 受控迁移命令 dry-run：6 张实时路由表和 3 类 JSON 白名单均无剩余候选；仅报告上述 7 条未路由历史 JSON。
• 卸载后实时绑定计数：全局 1、供应商 2、商品 143、服务 163、运行快照 163、连接快照 163。
• 卸载后对 163 条服务逐条调用 ProviderResolver::resolveForService()：163 条已解析、163 条为 zjmf_finance_api、163 条支持实例控制；实际能力对象可解析为 ZjmfFinanceAdapter。
• 定向自动化验证：php artisan test tests/Feature/MofangFinanceProviderKeyMigrationTest.php，2 项通过、47 条断言通过。
• 格式验证：vendor\bin\pint --test 已通过受影响的迁移服务、命令和测试文件。

风险与回滚

• 禁止以全库正则或文本替换迁移 provider key；未来重跑必须使用 db:rename-mofang-finance-provider --dry-run --json 审阅受控候选。
• 7 条未路由历史 JSON 为明确保留项；如需处理，必须先补充其服务归属和上游身份的独立证据。
• 如需恢复到迁移前状态，应在维护窗口用上述完整备份恢复本地 idc；该操作会覆盖备份之后的全部本地数据变更，不能作为局部回滚替代。

进度

• [x] 审阅插件生命周期、绑定关系、外键策略和历史基线。
• [x] 建立完整回滚备份。
• [x] 重新安装、配置并启用 ZJMF 插件。
• [x] 按供应商 → 商品 → 服务绑定执行受控切换。
• [x] 验证 163 条服务的 ZJMF 实例控制能力。
• [x] 清理旧心跳的活动来源并保留失败记录。
• [x] 卸载旧插件并完成历史保留复核。

决策日志

日期	决策	原因
2026-07-22	不执行全库泛文本替换。	历史日志、密文和非路由 JSON 不能安全地按文本等值替换。
2026-07-23	仅迁移 6 张实时路由表和 3 类确认的 JSON 顶层字段。	该范围可证明为当前路由，且能保留审计、财务和敏感历史数据。
2026-07-23	7 条无确认实时路由的历史 JSON 不改写。	缺少服务归属或供应商映射时，强行切换会造成错误上游路由。
2026-07-23	不删除 109 条旧心跳失败记录。	它们是可追溯的失败证据，且改写序列化 payload 会破坏其长度校验。
2026-07-23	在 163 条服务解析与任务注册验证后才卸载旧插件。	确保旧记录不再承载任何实时绑定，并由外键 SET NULL 保留历史归属信息。

相关文档

• 从智简魔方财务系统迁移（实验）：业务数据从魔方财务 shd_ dump 导入 turaidc 的实验性迁移器（用户、商品、订单、账单等）。本文档聚焦上游绑定切换，数据迁移器聚焦业务数据导入，两者互补。
• 本地 IDC 数据迁移流程：当前结构内 dump 迁移的正式流程。