commit b7d1d907a29f2669ea5f87bf95182f3bf1633a96 Author: fuzhongyun <1272174219@qq.com> Date: Wed Sep 16 15:18:13 2026 +0800 上传文件至 / diff --git a/营销系统下线迁移方案-会议版.html b/营销系统下线迁移方案-会议版.html new file mode 100644 index 0000000..c4309a3 --- /dev/null +++ b/营销系统下线迁移方案-会议版.html @@ -0,0 +1,598 @@ + + + + + +营销系统下线与易码通迁移方案 + + + + + +
+
+

营销系统下线与易码通迁移方案

+
关停创建入口 · 能力对比 · 客户分类 · 中转网关 · 回调处理 · 执行路线
+
+ 存量数据快照：2026-09-07（主库 market 只读副本） + 文档时间：2026-09-16 + 75 张表 / ≈1.1TB +
+
+
+ +
+
+ 1. 总 · 关停与对比 + 2. 系统现状 + 3. 客户对接分析 + 4. OpenAPI 中转 + 5. 回调处理 + 6. 后台创建能力 + 7. 执行路线 + 8. 总结 +
+
+ +
+ + +
+
01关停与能力对比
+ +
+

1.1 既定目标（基调）

+
    +
  • 新的业务不再接入当前系统 —— 关闭营销系统所有创建入口（后台新建计划/批次、OpenAPI 发码写接口、分销商后台入口）。
    • +
  • 老业务继续跑，服务不停 —— 只停入口，不停服务：存量计划的核销、C 端访问、立减金发放、回调接收、财务对账全部保留。
    • +
  • 涉及对接的客户迁往易码通；若用户不愿迁移，由我们开发中转项目反向对接用户。
    • +
  • 易码通需支持营销系统后台的创建能力：创建分销商、应用、计划、批次、key 码。
    • +
+
+ +
+

1.2 能力全景对比（易码通 vs 营销系统）

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
能力域结论说明
后台 · 创建分销商 / 客户✅ 已覆盖易码通 POST /admin/v1/merchant/create。注意：易码通 merchant = 营销系统的分销商(reseller)，自带余额/授信/冻结账户，并保留 direct_reseller_id 老系统映射。
后台 · 创建应用(app_id)✅ 已覆盖易码通 POST /admin/v1/merchant/app/create，含 app_id、商户RSA公钥、notify_url、sign_type，支持事件订阅与密钥重置。
后台 · 创建计划✅ 已覆盖易码通 POST /admin/v1/activity/create（计划≈活动 activity），含 key 总量、有效期、结算方式、绑定客户。⚠️ 需过钉钉审批才能生效、生效后才能建批次（见 6.2）。
后台 · 创建批次 / key 码✅ 已覆盖易码通 POST /admin/v1/key_batch/create（导码任务，单次 ≤10 万），生成 zip+密码，可下载/邮件。key 作废/延时/核销/统计均有接口。
OpenAPI · A 类 券包下单✅ 已覆盖营销系统 /openapi/v1/market/AlipayCoupon/*（无验签）→ 易码通 key/order、key/query，协议需更换。
OpenAPI · B 类 key 发码✅ 已覆盖营销系统 send/discard/query → 易码通 order/batch_order/discard/query/batch_query/renew/exchange，验签体系需转换。
OpenAPI · B 类 批量生成+文件回传🔧 需开发营销系统 generate/postbank、lock/postbank、pushDataFile（邮储批量生成 key 文件回传）——易码通 openapi 无对应接口（内部有导码能力，缺开放通道），需开发或中转层补齐。
立减金（券）体系
主体/商品/批次/订单/核销		✅ 已覆盖易码通具备完整立减金能力：券主体（支付宝/微信/云闪付）、券商品与批次（activity/goods/voucher）、券订单（order/voucher），接口普遍标注 [迁移来源] 老系统 Order.OrderVoucher.*；后台管理 /admin/v1/coupon/*。详见 5.1。
OpenAPI · C 类 立减金核销回调✅ 存量留守C 类 = 行方把支付宝立减金核销通知推给我们、更新券码状态。该链路只改存量券状态、不触发新创建 → 留守老系统，接口不动。易码通已具备同等能力（/v1/order/voucher/notify，含 NotifyVoucher/Used/Expired/Refunded），仅当新业务改在易码通发立减金券时才需迁移，届时把行方报文适配到该统一入口。
OpenAPI · D 类 主动通知🔄 需中转易码通已具备事件订阅与通知重试能力（merchant_notify list/retry），但向行方推送的报文结构 / 签名（国密）/ 幂等语义与老系统差异大，且行方不改造接收端 → 由中转层把易码通事件翻译成行方既有格式再推送。
验签体系🔄 中转 + 需开发易码通现有统一 RSA-SHA256 + AES-256-ECB-PKCS7（每商户一套密钥）。银行渠道（兴业/邮储国密）走中转层国密↔RSA 转换；分销商/普通客户因易码通客户来自 CRM、与营销系统分销商不对齐，考虑在易码通新增 basic_auth 验签类型统一承接新接入方（其 reseller_api_setting 表已预留 secret_key/sign/IP 白名单/接口授权等分销商级鉴权模型）。
资金账户 / 结算✅ 无需迁移余额已查实（2026-09-16 连库核对）：营销系统内没有分销商预充值余额池 —— 无余额表、无充值流水，发码表 merchant_key_send 无任何金额字段（发码不扣款）。结算链路大部分已废弃：结算导出 settlement_export_record 停更 2024-12、月度对账 summaryresellerorder 停更 2024-07、settlement_order 99.9%（272 万条）停在 2024-12-31，仅邮储一家（type=5，约 704 条/月）仍活跃。计价规则在 key_batch.key_cost_price/key_official_price；易码通已有更完整体系（成本价/合同价/官方价 + 4 种结算方式）。
+ +
重要背景：易码通并非"另一套系统"，而是营销系统的重构承接平台 —— 其代码中大量接口标注 [迁移来源] Order.OrderVoucher.* 等老系统方法名，老系统能力正按模块迁移到易码通。本次工作的实质是加速并收口这条既定迁移线。
+
一句话结论：易码通后台创建能力、立减金（券）体系、发码主链路均已覆盖，C 类核销回调留守老系统不动；需补齐三块 —— ① 邮储批量生成文件回传（开发开放通道）、② 银行国密验签（走中转）、③ 分销商 basic_auth 验签（易码通新增验签类型）。
+
+
+ + +
+
02系统现状（存量盘点）
+ +
+
75
数据表
+
1.1TB
磁盘占用
+
9130
计划总数
+
1394
未结束计划
+
9008
未结束 key 批次
+
2224万
待发 key 库存
+
137
活跃分销商（180 天）
+
6
API 对接客户
+
+ +
+ + + + + + + + + + +
维度数值说明
表数量 / 磁盘占用75 张 / ≈1.1TB主库 market（阿里云成都 RDS 只读副本，MySQL 5.7.28）
计划总数9130未删除 8893，未结束 1394
未结束 key 批次9008近 180 天新建 4100+
待发 key 库存2224 万计划生成 key 总量 2230 万
活跃分销商（180 天）137 家银行 30+ 家 / 商业地产约 40 家 / 普通企业若干 / 测试约 10 家
对接客户 merchant_id全库 12 个 / 活跃 6 家4 家 key 类 + 2 家券包类（详见第 3 章）
服务状态仍在活跃运行 核心表分钟级写入：发码、事件通知、券批次、审批、结算
超大表 Top5order_detail 468GB · order_voucher 255GB · event_notify 197GB · order 62GB · key_period_recharge 16GB
+
关键风险：兴业银行有 568 个未结束计划，最晚到期 2031-12-31。若不处理，老系统至少要再运行 5 年 —— 这决定了"存量消化"阶段的时间下限。
+
+
+ + +
+
03客户对接分析与分类方案
+ +
+

3.1 角色层级（先分清两种客户）

+ + + + + + + + + + + + + + +
层级定义数量与迁移的关系
reseller（分销商）签合同/开账号的上游客户，用后台 + C 端建计划、批次、导 key137 家活跃绝大多数不走开放 API。迁移动作 = 新分销商直接在易码通开通（basic_auth 接入）；存量分销商因易码通客户来自 CRM、与营销系统不对齐，需先建 映射表（营销 reseller ↔ CRM/易码通客户） 或按 CRM 重新开通。
merchant（API 对接商户）通过开放 API 发码/作废/查询 + 收事件推送的系统级对接方全库 12 / 活跃 6迁移 / 中转的真实对象，即本文重点。
+
137 家分销商与 6 家对接客户不是同一件事：前者 90% 以上只是用后台建活动，停掉入口后自然流向易码通；真正需要技术处理的是 6 家 API 对接方。
+
+ +
+

3.2 API 对接客户清单与分类（6 家）

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
客户merchant_id归属分销商接口类型发码量 / 事件量活跃度方案
蓝星严选（连续包月）——A 券包下单券包订单（同日见 openapi_order 与 order）🟢存量中转 + 新业务直连
存量业务中转层代签兜底；新业务直接对接易码通（免中转）
阅璟——A 券包下单券包订单🟢存量中转 + 新业务直连
同上
四川天府银行TFYH00001924 四川天府B key 发码8583 张🟡 较活跃
(2026-07)		中转（首个试点）
量小、风险低，作为中转网关首批灰度对象
兴业银行LSXD001500 兴业B key 发码 + 推送发码 93 万 / 事件 8.6 万🟢中转
国密证书+独立加解密；老系统已有实现，可复用
邮储银行总行lansexiongdi666606 邮储总行B key 发码 + 推送 + 批量生成发码 700 万 / 事件 3556 万🟢中转
量大 + 父子券/白调逻辑易码通暂未实现 + 批量 key 文件回传
邮储茶饮YCCY001714 邮储茶饮B key 发码5102 张🟢 (2026-09)中转
随邮储体系一并中转；不在事件推送表，但发码活跃
+
统一原则：已对接客户（行方）对稳定的业务不会再次改动对接 → 存量业务一律由中转网关承接（行方零改造）；新增业务可直接对接易码通（重新对接即换用易码通协议，免中转）。
+
A 类特例：蓝星/阅璟为券包下单客户（非银行强耦合），且新业务理论上均为直接发券——存量业务继续中转兜底，新业务直接对接易码通（其 openapi 发券主链路已就绪）。
+
+
+

新业务直连易码通

+
  • 蓝星严选（券包）
  • 阅璟（券包）
+
无银行强耦合，换易码通协议免中转；存量仍走中转兜底
+
+
+

中转 · 首个灰度

+
  • 四川天府银行（发码 8583）
+
量小、风险低，先跑通全链路
+
+
+

中转 · 国密验签

+
  • 兴业银行（发码 93 万 / 事件 8.6 万）
+
国密证书 + 独立加解密，复用老系统实现
+
+
+

中转 · 邮储专项

+
  • 邮储总行（发码 700 万 / 事件 3556 万）
  • 邮储茶饮（发码 5102）
+
父子券 / 白调 / 批量文件回传 / 结算登记承接
+
+
+
另有 8 个 merchant_id 已停/测试（如 LSXD000001/2、jianxingjinke 等），无需处理，随老系统归档。
+
+ +
+

3.3 分销商（reseller）分类处置

+ + + + + + +
分类数量处置方案
银行客户（兴业/邮储/浙商/新网/众邦等）30+ 家发通知函 + 基于 CRM 映射开通易码通账户；对接型银行（兴业/邮储）走中转，其余按计划自然到期
商业地产（华润/万象系/亚奥等购物中心）约 40 家通知函 + 开通引导（basic_auth），量级小、无 API 依赖
普通企业（申朴/迈戈/淘天/oppo 等）若干同上，按活跃度分批触达
测试账号约 10 家直接停用/归档
+
+
+ + +
+
04OpenAPI 中转方案
+ +
+

4.1 总体架构

+
+
+
银行 / 商户客户端
保持原协议不变
+
+
↓ 原协议（A 无验签 / B 国密）
+
+
中转网关（新开发）
验签转换 · 协议翻译 · 路由 · 幂等
+
+
↓ 易码通统一协议（RSA-SHA256 + AES）
+
+
易码通 OpenAPI
key/order · query · discard · batch · settlement
+
+
+
定位：中转网关是存量老客户的专属通道（保持老协议不变），不是所有流量的必经之路 —— 新客户/新业务直连易码通（分销商用 basic_auth、A 类客户用标准协议）。
+

中转网关核心职责

+
    +
  • 验签转换：国密（SM2/SM4）↔ 易码通 RSA/AES。兴业/邮储国密实现老系统已有，可整体迁入中转层复用；A 类无验签客户由中转层代签。
    • +
  • app_id 映射：维护 老app_id → 易码通app_id 映射表，老客户 app_id 不变、客户端零改造（行方接收端因此完全不用动）。
    • +
  • 幂等透传：out_biz_no 原样透传给易码通（易码通有 Redis 幂等锁），保证中转重试不重复发码。
    • +
  • 计划级路由：复用老系统已有 RequestRedirect 中间件思路 —— 按计划编号分流：老计划 → 老系统 DB（只读查询），新计划 → 易码通。老存量不动、新业务全进易码通。
    • +
  • 通知/回调转换：D 类事件通知由易码通事件 → 行方既有报文格式/签名/幂等语义转换后推送；C 类核销回调存量留守老系统（见第 5 章）。
    • +
+
+ +
+

4.2 四类接口在中转层的处理

+ + + + + + + +
接口类营销系统路由易码通对应中转层动作
A · 券包下单/openapi/v1/market/AlipayCoupon/order、querykey/order、key/query代签 + 字段翻译 + 幂等透传；老客户无感
B · key 发码/openApi/v1/market/key/send、discard、queryorder/batch_order、discard、query/batch_query、renew、exchange国密验签 → 易码通验签转换；字段映射；out_biz_no 透传
B · 批量生成需开发generate/postbank、lock/postbank、pushDataFile无对应易码通内部有导码能力（key_batch 出 zip），缺开放通道 —— 中转层实现"客户文件交互"并桥接到易码通内部接口，或易码通补开放接口
C · 立减金回调存量留守/openApi/v1/callback/voucher/*（4 家）仅更新存量券状态，无新创建
（新业务可迁易码通 /v1/order/voucher/notify）		存量留守老系统，不动；仅当新业务在易码通发立减金券时再做渠道适配
D · 主动通知/notify/industrialBankmerchant_app 事件订阅 + merchant_notify 重试易码通事件 → 行方既有报文格式/国密签名/幂等语义转换后推送，行方接收端不变
+
+ +
+

4.3 密钥与安全注意点

+
    +
  • 一套协议、每商户一套密钥：易码通每个 app 独立 app_id/RSA/AES/notify_url，新商户接入成本低，中转层为每个老客户申请独立 app，密钥隔离。
    • +
  • 时间戳窗口：易码通验签时间戳窗口默认 3 分钟，中转层转发需避免时钟偏差导致签名失效。
    • +
  • 回滚能力：中转层做灰度开关（按客户/按计划），出问题一键切回老系统。
    • +
+
+
+ + +
+
05回调与通知处理
+ +
+

5.1 两类回调的现状

+ + + + + + + + + + + + + + +
类型方向数量处理方案
C 类 · 立减金核销回调银行/渠道 → 营销系统
/openApi/v1/callback/voucher/*		4 家性质 = 行方把支付宝立减金核销通知推给我们，用于更新券码状态。只改存量券状态、不触发新创建 → 留守老系统，接口不动。易码通虽具备同等能力（NotifyVoucher/Used/Expired/Refunded），但无需为此迁移；仅当新业务改在易码通发立减金券时才需把 4 家渠道适配过去。
D 类 · 主动事件通知营销系统 → 银行
/notify/industrialBank		3 家
(邮储/兴业/天府)		易码通具备 merchant_app 事件订阅 + merchant_notify 通知重试（能力底子），但报文结构 / 国密签名 / 幂等语义与行方既有接收端不一致，行方不改 → 必须由中转层转换后推送，并复刻老系统补推工具（pushKeySupplement 类）。
+ +

5.2 关键量级提示

+ + + + + +
merchant180 天事件量最近通知含义
lansexiongdi666（邮储总行）3556 万条2026-09-07分钟级推送峰值，中转层需具备高吞吐 + 幂等 + 失败重试队列，且通知不能丢（涉及银行侧积分到账）
LSXD001（兴业）8.6 万条2026-09-07国密加密报文，中转层解/加密
TFYH00001（天府）4043 条2026-07-09量小，作中转网关首个灰度对象；推送格式转换逻辑与兴业共用
+
+
+ + +
+
06后台创建能力对照与缺口
+ +
+

6.1 能力映射（易码通 admin 已具备）

+ + + + + + + +
营销系统（关闭的能力）易码通对应接口要点
创建分销商 resellerPOST /admin/v1/merchant/create即易码通 merchant，带资金账户 + direct_reseller_id 老系统映射
创建应用（app_id/密钥）POST /admin/v1/merchant/app/createRSA 密钥、notify_url、事件订阅、密钥重置
创建计划POST /admin/v1/activity/createkey 总量/有效期/结算方式/绑定客户
创建批次 / 导 keyPOST /admin/v1/key_batch/create单次 ≤10 万，zip+密码，可下载/邮件
key 管理PUT /admin/v1/key/discard|delay|use作废 / 延时 / 标记已使用 / 统计
+
+ +
+

6.2 五个落地注意点

+ + + + + + + +
注意点问题建议
① 审批流易码通活动创建后为"待审核"，需钉钉审批，生效后才能建批次存量计划批量导入时走免审/直连通道，或确认审批流程可配置
② 资金账户易码通 merchant 有余额/授信/冻结，营销系统 137 家分销商余额是否迁移先定"余额是否平移"，否则下游发码结算会断；建议迁移后按易码通账户体系重新授信
③ 批次上限易码通单批次 ≤10 万且不超活动 key_total_num；老系统尚有 2224 万待发 key新建活动时 key_total_num 按存量+新量规划，或按活动多次建批次
④ key 格式易码通 key 有 key_style(1/2/3)、key_unit、区间导码参数核对老系统 key 生成规则（前缀/长度/分段）能否用易码通参数配出，否则老客户依赖的 key 形态会变
⑤ 存量处置1394 未结束计划、9008 未结束批次（2224 万 key）不动存量，按 end_time 自然到期；停入口后 C 端核销链路自闭环即可
+
+
+ + +
+
07执行路线（四阶段）
+ +
+ + + + + + + + + + + + + + + + + + + + + + +
阶段动作判定完成标准
阶段 1
停入口		管理后台写接口（新建计划/批次）禁用
OpenAPI 写接口（send/discard/generate/lock/pushDataFile）停用
分销商后台登录入口关闭
保留：查询接口、核销、C 端、回调接收、财务导出		每日新建 plan < 1
阶段 2
存量消化		1394 个未结束计划自然到期；9008 批次消耗 2224 万待发 key
关键任务：通知 137 家分销商 + 建立 CRM 映射，在易码通开通账户（basic_auth 接入）		存量计划全部过期 / 分销商完成引导
阶段 3
银行对接处理		统一由中转网关承接存量，行方零改造：
① 天府 → 首个灰度（量小）；② 蓝星/阅璟 → 存量中转（代签），新业务直连易码通；③ 兴业 → 国密验签转换；④ 邮储总行/茶饮 → 大流量 + 父子券/白调 + 批量文件回传 + 结算登记（settlement_order type=5）承接；⑤ D 类推送格式转换
易码通侧并行：新增 basic_auth 验签类型、建立分销商 CRM 映射		6 家对接客户全部切换完成，行方无改造
阶段 4
下线归档		老系统保留查询与 C 类核销回调接收（存量券生命周期走完）；1.1TB 归档冷存储（OSS 冷归档）
保留财务对账所需表		停服验收通过
+ +

工作量与复杂度评估（技术侧）

+ + + + + + + + +
工作项工作量复杂度
停入口（前后端双禁用）小低
分销商通知 + CRM 映射开通（137 家）中中
中转网关（验签/协议转换 · app_id 映射 · 幂等 · D 类推送格式转换）大高
易码通新增 basic_auth 验签类型（复用 reseller_api_setting 模型）小低
邮储专项（父子券/白调/批量 key 文件回传/3556万事件/结算登记承接）大高
老系统数据归档（1.1TB）中中
+
+
+ + +
+
08总结
+ +
+

核心结论（一句话）

+

停入口、留服务、存量自然消化；6 家已对接客户的存量业务一律由中转网关承接（行方零改造），新业务直连易码通（A 类券包客户可直接对接）；137 家分销商经 CRM 映射迁入易码通（basic_auth 接入）。C 类核销回调留守老系统不动。

+ +
+
+

✔ 已就绪

+
    +
  • 易码通后台创建能力：分销商 / 应用 / 计划 / 批次 / key —— 全部已覆盖
    • +
  • OpenAPI 发码主链路（A 券包 + B key send/discard/query）—— 已覆盖，协议/验签由中转层转换
    • +
  • 立减金（券）体系：主体（支付宝/微信/云闪付）+ 券商品/批次/订单 + 核销状态更新 —— 已覆盖（存量回调留守老系统即可）
    • +
  • D 类事件订阅 + 通知重试（merchant_notify）—— 能力底子已具备，对外推送格式由中转层转换
    • +
+
+
+

🔧 需开发 / 决策

+
    +
  • 中转网关（核心工程）：验签/协议转换 · app_id 映射 · 幂等透传 · 计划级路由 · D 类推送格式转换
    • +
  • 易码通新增 basic_auth 验签类型（可复用 reseller_api_setting 的分销商鉴权模型）
    • +
  • 邮储批量生成 + 文件回传（generate/lock/pushDataFile）开放通道
    • +
  • 分销商 CRM 映射表（营销 reseller ↔ 易码通/CRM 客户）
    • +
  • 历史结算数据归档（供财务对账）：结算导出/月度对账均已停用，仅需保留查询能力
    • +
  • 存量计划导入的审批免审通道
    • +
+
+
+

🔄 必须中转（存量业务）

+
    +
  • 蓝星 / 阅璟：存量中转（代签兜底），新业务直连易码通
    • +
  • 天府：首个灰度试点（量小、风险低）
    • +
  • 兴业：国密验签 + 独立加解密
    • +
  • 邮储总行 / 茶饮：大流量（700万发码 / 3556万事件）+ 父子券 / 白调 + 批量文件回传 + 结算登记承接
    • +
  • 原则：行方存量业务不改造任何对接，中转层 100% 兼容老协议；新业务直连易码通，不过中转
    • +
+
+
+

⚠ 主要风险

+
    +
  • 兴业 568 个未结束计划最晚到期 2031-12-31 → 存量消化下限 5 年
    • +
  • 邮储 3556 万事件通知不可丢（银行侧积分到账）
    • +
  • 行方零改造 → 中转层必须完整复刻国密/报文/幂等语义，兼容性风险集中在中转层
    • +
  • 2224 万待发 key 与易码通批次上限（≤10万）的承接规划
    • +
  • 邮储结算登记（settlement_order type=5，704 条/月）已确认纳入邮储中转范围，落地时若漏项将导致邮储结算断档
    • +
+
+
+

📌 下一步行动项

+
    +
  • 1) 启动中转网关设计：验签转换、app_id 映射、幂等、D 类推送格式（复用老系统国密实现）
    • +
  • 2) 天府作为首个灰度（量小、风险低），跑通"老协议 → 中转 → 易码通"全链路
    • +
  • 3) 易码通新增 basic_auth 验签 + 建分销商 CRM 映射表
    • +
  • 4) 邮储专项：批量生成文件回传 + 结算登记（settlement_order type=5，704 条/月）承接（已确认纳入中转范围）；历史结算数据存档供财务对账
    • +
  • 5) A 类客户（蓝星/阅璟）新业务直连易码通 → 提供接入文档与联调支持
    • +
  • 6) 通知 137 家分销商，按 CRM 映射开通易码通账户
    • +
  • 7) 确认 C 类留守边界（存量券生命周期）与历史订单保留年限
    • +
+
+
+
+ +
+ 数据来源：营销系统主库 market 只读副本（2026-09-07 快照）· 易码通源码（app/admin、app/openapi、grpc proto，2026-09-16 核对）
+ 本方案为会议讨论稿，涉及金额、合同、商务策略的内容需业务侧确认后修订。 +
+
+ +
+ +