邮件标题：20260909-技术评审-券中心-券中心接口调整方案

邮件正文：

孔玮：
已完成针对【券中心接口调整方案】的技术评审，现将评审结论、风险判断及后续执行安排同步如下，便于各方对齐认知并落实执行。

项目名称： 券中心
评审时间： 2026/09/09
参与评审人： 杨建@精明购、孔玮、马奇、刘所广、王建朝、李强@契胜科技、赵敏@契胜科技、林焕纯@精明购、王琪、任同超、梁岩、王军、金策、李明非、陈昊、任铭、李宏伟
评审结果： 通过

一、技术方案背景

• 业务场景：券中心接口为配合计费系统取数、积分兑换券改为"门店+人"发放而做调整，涉及营销助手、智慧门店、积分商城等多端对接，重点解决数据推送字段不全、发放维度变更后查询口径不匹配、跨门店核销校验责任归属三类问题。

二、技术方案要点

• 整体流程：升码/发券接口新增门店人员编码及活动、门店等必传字段 → 券中心仅做记录，在数据推送时回传给计费系统 → 查询接口按入参的发放维度（按门店 / 按门店+人员）直接返回数据、不再做聚合 → 券码详情接口经销商编码按应用方区分必填规则 → 提交核销时按活动配置做门店/经销商校验，积分兑换券的跨门店一致性由计费侧回调自行校验。
• 字段变更：升码接口新增门店人员编码；货款抵扣券发券接口新增活动编码、活动名称、门店编码、门店名称四个必传字段，查询券列表与数据推送列表同步返回；货补券核销推送补充核销经销商名称、核销经销商人员姓名及升码人员编码与名称；立减券核销推送补充升码人员信息与批次类型（由数字改回英文单词以保证跨服务一致）；全量接口文档统一标注经销商编码对应主数据系统的账户编码。
• 查询口径调整：积分兑换券改为"门店+人"发放后，仅传门店编码只能查到发给门店的券，需同时传门店编码与人员编码才能查到发给门店人员的券；智慧门店首页需按"门店"与"门店+人员"两种方式分别调用（两个接口各查 4 次）才能取全数据，批量查询接口需支持同时传入门店编码与人员编码列表。
• 状态入参规则：券列表状态仅支持单值入参，不支持多状态同时查询（避免复杂 SQL 拼接拖垮性能）；状态为 0 表示不限制，由 Java 程序层按时间条件过滤，不做 SQL 层校验。
• 性能与分页：券中心接口已按消费者级最高标准压测，当前 QPS 600 以上，结合游标分页（默认 10 条、最大 50 条）足以支撑门店维度查询；查询接口不做数据聚合，避免上千万至上亿券量下的性能瓶颈。
• 核销校验：券中心支持"仅限发券门店核销 / 同经销商下门店核销 / 跨门店核销"等配置项，提交核销时按活动选项校验；积分兑换券必须本店核销，券中心仅推送真实核销数据，跨门店一致性校验由计费侧在回调时自行实现。

三、决议事项

• 智慧门店按"按门店查询"与"按门店+人员编码查询"两次调用的方式开发，确保券数据完整不遗漏。
• 获取核销码逻辑，SFA 继续传入经销商编码，活动计费管理侧不传入，由各端按需控制。
• 持续评估券列表接口性能压测情况，并关注用户遇到核销状态展示异常（待核销/核销中切换导致券从列表消失）的场景，

四、风险提示

• 状态"0 不限制"的查询由 SQL 层校验改为 Java 程序层过滤，属以后置校验换取性能的妥协，数据量增长后可能带来应用层压力。
• 查询入参不做强制必填、按组合条件返回数据，调用方传参错误会查错数据，存在跨门店数据越权查询的隐患。
• 券中心发券接口本次仅调整货款抵扣券，不影响营销活动中心老活动使用的产品券与立减券，需防止后续误改波及老活动。

五、方案地址

接口文档：https://s.apifox.cn/f229ec37-bcbf-4c01-8346-03df2ee98223

密码：O6jAAkPk