第一章：产品概览与适用指南
促销规则配错了，后果有多严重？满减和折扣叠加后一单亏掉利润——大促高峰期的配置失误，一晚就可能吞掉整场活动的利润；退款金额和财务对不上，月底加班手动核对，大促的功劳变成了跨部门扯皮的消耗；活动上线了顾客却享受不到优惠，客服电话被打爆。
这些问题，很多时候不是单纯的运营失误，而是因为缺少一个能同时把促销规则"算清楚、管清楚、追溯清楚"的系统。MyPromotion 就是来解决这个问题的——它不负责交易闭环，只专注一件事：让每一笔优惠都算得清、管得住、追溯得到。
1.1 MyPromotion 能帮你做什么？
MyPromotion 是一个促销规则计算引擎。你的业务系统（小程序、App、POS、OMS 等）只需传入商品和用户信息，引擎就会根据你配置好的规则，自动算出最优优惠组合和商品级分摊明细，并留下完整的计算凭证。
简单来说，它解决了促销领域的三个核心痛点：
- 规则管理混乱：满减、满折、阶梯价、秒杀等规则在 Admin 后台统一配置，支持有效期、优先级、互斥与叠加，告别 Excel 和代码硬编码。
- 计算结果不确定：同样的购物车，不同的人算出来金额不一样？引擎通过标准 API 统一计算，结果可预期、可复现。
- 退款对不上账：结算阶段引擎生成计算凭证（trace），把当时的请求、计算结果和分摊明细永久保存。退款时直接读取该凭证，不再重新计算，从根本上消除偏差。
如果你只需要一个简单的"全场8折"，在代码中直接固定可能更快；但如果你需要多种规则叠加、按人群/商品定向、退款要能精确回退，MyPromotion 的价值才会显现。
1.2 这本手册适合谁？
| 角色 | 主要使用场景 | 推荐阅读章节 |
|---|---|---|
| 运营/活动配置人员 | 创建满减/满折/特价活动，管理商品池和用户分群 | 第一章 → 第三章 → 第五章 |
| 业务分析师 | 查看活动效果、分析优惠占比、排查异常订单 | 第一章 → 第三章（任务监控） → 第五章（FAQ） |
| 研发/架构师 | 将 MyPromotion 接入现有订单/购物车系统 | 第一章 → 第四章（集成指南） → 第六章（词汇表） |
| 财务/审计人员 | 核对优惠金额、追溯规则变更、导出 API 调用日志 | 第一章 → 第三章（日志查询） → 第六章 |
| 系统管理员 | 管理租户、配置外部数据源、监控系统状态 | 全章通读 |
没有。MyPromotion 采用多租户架构，按租户隔离数据和规则。无论是单一品牌的初创团队，还是多品牌、多门店的大型集团，只要具备订单/购物车系统 + 商品信息，就可以接入。小到一场限时秒杀，大到全年大促矩阵，都能支持。
1.3 核心能力一览
MyPromotion 当前版本支持以下促销类型和配套能力：
| 能力分类 | 具体支持 | 对应 Admin 菜单 |
|---|---|---|
| 基础促销规则 | 满减、满折、满赠、阶梯价（阶梯满减/阶梯折扣）、特价、秒杀、免运费、买赠、优惠券、积分抵扣、余额抵扣、预售等 | 促销规则 |
| 标签促销 | 按标签（场景、品类、活动主题）批量圈选规则 | 标签管理 |
| 智能促销 | 基于用户分群、商品池等条件自动筛选适用规则，并从中找出最划算的组合；规则太多时会自动切换为按优先级匹配 | 智能促销 |
| 商品池 | 按 SKU、类目、品牌、标签圈选活动商品 | 商品池 |
| 用户分群 | 按会员等级、消费频次、标签等圈选人群 | 用户分群 |
| 消费券 | 券模板管理（面额/门槛/总量定义）、可用性检查；退款时按券类型自动匹配分摊模型（比例分摊/阶梯重算/优先扣除），可为每种券类型选择处理方式（自动分摊/人工审核/不退回）；平台不直接发券/核券，实际发放和核销由外部券系统完成 | 消费券 |
| 价格保护 | 成本价保护、普通会员价保护、VIP会员价保护；计算时自动拦截或警告低于保护线的促销结果 | 价格保护 |
| 退款分摊 | 按比例/按规则分摊已优惠金额到子项 | 退款策略 |
| 售后策略 | 定义退款时的优惠回退方式（比例分摊/优惠不退/优惠全退），并在正向计算时固化商品级分摊明细，确保退款可追溯 | 售后规则 |
| 外部数据源 | 同步商品、用户画像、消费券模板/实例等外部数据；支持 Pull 拉取、Push/Webhook 推送、Excel 文件导入三种方式 | 数据源 |
| 多租户 | 按租户隔离规则、数据、API Key | 租户管理 |
| 策略关联配置 | 为每种策略类型设定允许使用的条件、动作、范围类型；创建规则时选项自动过滤，避免配置错误 | 策略关联配置 |
| 审计与 Trace | 规则变更审计、API 调用统计、慢接口分析 | 审计日志 / Trace |
1.4 能力边界：✅ 支持与 ❌ 不支持
在接入前请务必确认以下边界，避免将不适用于 MyPromotion 的场景强行对接。
✅ 明确支持的场景
- 丰富的促销策略：支持满减、满折、阶梯价、特价、秒杀、预售、积分抵扣等 15 种核心策略，运营后台直接配置即可上线。详见 1.5 策略选型指南。
- 标签聚合与批量管理：通过标签将多个规则绑定到特定场景（如"618大促"、"新店开业"），前端按标签一键调用，批量上下线。
- 自动筛选与最优组合：基于用户身份、购物车、商品池等条件，自动筛选适用规则并找出最划算的组合；规则数量过多时，自动切换为按优先级排序匹配。
- 购物车实时算价：购物车阶段调用引擎实时计算优惠金额，让用户随时看到「用了哪些规则、省了多少钱」；同时返回「还差 XX 元可享满减」等凑单建议作为辅助参考。用户修改购物车后可再次调用。
- 消费券叠加：促销规则与消费券可叠加使用，支持配置互斥策略；券模板和实例状态同步后即可参与计算。
- 价格保护：计算时自动检测促销价是否低于成本价或会员价，触发拦截或警告，防止卖亏或损害会员权益。
- 退款优惠回退：支持按原优惠比例分摊回退、优惠不退、优惠全退等多种售后策略。
- 消费券退款处理：退款时按券类型自动匹配分摊模型（金额减免/折扣券/无门槛券按比例分摊，阶梯券阶梯重算，特价券优先扣除），可为每种券类型选择处理方式（自动分摊/人工审核/不退回）。实际返券操作由外部券系统执行。
- 计算凭证追溯：每笔订单生成不可篡改的计算快照（trace），正向分摊明细永久固化；退款时直接读取快照，不再重新计算，杜绝正向逆向金额不一致。
- 多租户隔离：不同品牌、门店、业务线之间数据完全隔离，共用同一套引擎，集团可统一审计。
- 实时计算：标准 API 响应通常在 50ms ~ 200ms 内（P95），适合在线交易场景。
⚠️ 当前版本暂不支持（部分已纳入路线图）
- 级联促销计算：暂不支持"先打9折，折后金额再参与满减"这种前序规则改变金额后、后序规则重新判断门槛的级联逻辑。当前多条规则同时生效时，是各算各的再叠加。📋 已纳入路线图，中期版本将升级为显式 Pipeline 计算管线。
- 多主体分账：暂不支持区分平台出资、商家出资、品牌出资，引擎当前只计算"总优惠金额"。📋 长期规划中，将引入分账主体模型，支持正向分摊与逆向拆分。
- 定金膨胀：预售策略本身支持，但"定金100抵200"这类膨胀倍数计算需由外部系统处理。
- 秒杀抢购的库存控制：库存锁定、队列削峰、防超卖由外部秒杀系统负责，引擎只负责秒杀价格计算。
- 跨店凑单：多个独立租户/店铺的商品合并计算满减（当前仅支持单租户内凑单；门店场景可短期通过"一门店一租户"变通）。
- 动态定价/实时竞价：基于实时销量、库存、竞品数据自动调价，属于价格管理系统范畴，非促销引擎职责。
- 纯积分兑换 / 虚拟货币支付：积分余额查询、扣减和虚拟货币全额支付需由外部系统处理（引擎支持积分抵扣计算）。
- 复杂的分销返佣：多级分销、裂变返佣等营销玩法，不在促销计算引擎范围内。
- 全渠道库存实时分配：库存扣减和分配由业务系统或仓储系统负责，促销计算不介入库存域。
如果你的业务场景涉及上述项目，不必直接排除 MyPromotion。标注 📋 已纳入路线图 的能力可联系产品团队了解进展；其余项目通常可通过业务系统前置处理 + MyPromotion 标准计算的组合方案实现。
1.5 策略选型指南
面对不同促销需求，该选哪种规则类型？以下决策树帮助你快速定位：
| 你的需求 | 推荐规则类型 | 关键配置 |
|---|---|---|
| 全场/部分商品满 X 元减 Y 元 | 满减 / 阶梯满减 | 阈值、优惠额、商品池、用户分群 |
| 全场/部分商品满 X 件打 Y 折 | 满折 / 阶梯满折 | 阈值、折扣率、商品池 |
| 指定 SKU 固定低价 | 特价 | 目标价格、生效时间 |
| 指定人群享受额外折扣 | 折扣 + 用户分群 | 折扣率、分群条件 |
| 大促期间多个活动统一管理 | 标签促销 | 创建标签 → 绑定规则 → 前端按标签调用 |
| 不确定该用哪个规则，让系统自动筛选 | 智能促销 | 用户分群、商品池、候选规则集；显式开启 optimal 模式才启用最优组合枚举 |
| 发放可领取的优惠券 | 消费券 | 券类型、发放总量、有效期、适用商品池 |
| 买X件送Y件 / 满额送赠品 | 买赠 / 满赠 | 购买数量门槛、赠品 SKU、赠送数量 |
| 支持积分或余额抵现 | 积分抵扣 / 余额抵扣 | 抵扣比例上限、与促销规则的互斥配置 |
| 退款时需要精确回退优惠金额 | 退款分摊策略 | 分摊方式（比例/优惠不退/优惠全退）、Fallback 兜底配置、退款计算 API |
1.6 接入前必读
如果你是非技术角色，只想快速体验促销配置，不用读完本章。确认你已在 Admin 后台拥有账号和租户后，直接跳到 第二章：5分钟快速入门，用预置的测试数据完成第一次促销配置。正式接入时，再将本章转交给你的研发同事。
⚙️ 我要正式接入（研发/技术负责人）
请依次完成以下检查和步骤，确保业务系统与引擎顺利对接。
前提条件
- 你的系统具备订单创建能力（MyPromotion 是计算引擎，不处理交易闭环）。
- 商品基础数据（SKU、价格、类目等）可同步至引擎，或通过 Admin 后台手动维护。
- 引擎部署环境与业务系统网络互通，API 延迟建议小于 500ms。
- 已为你的业务线创建独立租户，并获取
access_key和secret_key。 - 订单系统有能力保存引擎返回的
trace_id——这是后续退款和对账的唯一凭证。
接入四步走
- 环境准备：确认租户信息、获取 API 凭证、验证业务服务器可访问引擎服务。
- 数据同步：导入商品、用户、消费券等基础数据（支持接口同步、Excel 导入），数据量较小时也可直接在 Admin 后台手动配置。
- 规则联调：在 Admin 后台配置促销规则，调用促销计算接口验证结果，使用测试中心辅助调试。
- 上线观察：通过 Trace 看板监控调用量、成功率、P95 耗时，观察至少一个完整活动周期。
详细的技术规范、接口契约和集成时序图，请参阅 第四章：系统集成指南。
第二章：5分钟快速入门
假设你是某电商平台的运营，想做一个"全场满300减50"的活动。本章带你从零开始，10步之内让活动上线并验证效果。
操作步骤
618满300减50。设置生效时间范围。
页面路径：/admin/promotions/promotionrule/add/
截图保存至：images/quick-01-type.png
300，优惠金额填 50。即"满300元减50元"。
• 规则详情页「测试」：单条规则调试，草稿和生效中状态都能测，未命中会自动分析原因。适合快速验证刚创建的规则。
• 促销测试中心：测试所有「生效中」规则的叠加效果，适合验证多条规则同时存在时的计算结果。
系统提供 5 种状态，核心区别如下：
• 草稿：仅保存，不参与计算，可随时修改。
• 待生效：已确认配置，但生效时间还没到（如明天才开始）。到达生效时间后，系统自动转为「生效中」。
• 生效中：正在生效，参与促销计算。可直接从「草稿」切换，也可由「待生效」自动流转。
• 已过期：到达失效时间后，系统自动标记，不再参与计算。
• 已禁用 / 已暂停：手动停用，立即停止参与计算，可重新激活。
一句话建议：活动立即开始 → 选「生效中」；活动未来开始 → 选「待生效」更省心。
很多用户创建完规则就以为活动上线了，其实状态还是「草稿」。顾客下单时系统不会命中这条规则。创建后务必检查状态。
页面路径：/admin/promotions/promotionrule/test/smart/
截图保存至：images/quick-02-test.png
在规则详情页点击「测试」，如果你能看到"应付金额 = 原价 - 50元"，说明规则配置正确。接下来把规则编码告诉开发，让他们接入 API 即可。
第三章：核心任务指南
如何创建一场满减/满折/特价活动？
你运营一家服装店，打算做"春上新满300减50"和"全场满99包邮"两个活动。满减和包邮不在同一互斥组，可以同时生效。下面分步操作。
第一步：创建满减活动
春上新满300减50- 生效时间：2026-06-01 至 2026-6-30
- 优先级：
10（数字越大越优先，建议重要活动设高一些）
300，优惠金额填 50。
页面路径：/admin/promotions/promotionrule/add/
截图保存至：images/task-01-full-reduction.png
第二步：创建包邮活动
春上新包邮- 策略类型：「包邮」
- 门槛：
99（满99元免运费）- 优先级：
5（低于满减）
系统预设「基础折扣互斥组」包含满减、满折、特价三种策略类型。这三种优惠默认不能同时生效。如果你想做"满减+折扣"叠加，需要先把满折和满减从互斥组中移除（或创建新的互斥组替代）。新手建议先用"满减+包邮"这种不互斥的组合。
金额/数量门槛型：
「满减」= 满X元减Y元 「满折」= 满X元打Y折 「满赠」= 满X元送赠品
「阶梯价」= 多档阶梯优惠（如满100减10、满200减30、满300减60）
价格直降型：
「秒杀」= 限时固定低价（通常配合高优先级 + 互斥组实现）
「特价」= 指定商品固定成交价（通过「固定价格」动作实现）
费用减免型：
「包邮」= 满X元免运费 「优惠券」= 领券后抵扣（满减券/折扣券）
资产抵扣型：
「积分抵扣」= 用积分抵现 「余额抵扣」= 用账户余额抵现
营销玩法型：
「买赠」= 买X件送Y件 「预售」= 定金预售模式
组合场景：通过「用户分群 + 商品池 + 策略类型」可组合出无限场景，如「新用户首单立减」「会员专享折扣」「指定渠道支付优惠」等
打开「促销测试中心」，构造一个350元的购物车，提交后查看结果：应同时命中满减和包邮两条规则。如果只看到一条命中，检查另一条的状态是否为「生效中」、是否被互斥组拦截。
多个优惠叠加会亏吗？如何设置互斥？
你同时在做"全场满300减50"和"新用户首单立减20元"两个活动。如果新用户买了350元的商品，两个优惠同时生效：350-50-20=280元，利润空间太薄。你只想让用户享受其中一个。
操作步骤
页面路径：/admin/promotions/mutexgroup/
截图保存至：images/task-02-mutex-list.png
discount_exclusive（英文唯一标识符，可自定义）- 组名：
基础折扣互斥组- 互斥策略类型：勾选「满减」和「首单优惠」
- 优先级：
50
创建互斥组后默认是启用的，但如果你之前手动停用过，或者复制了一条禁用的记录，规则就不会互斥。在互斥组列表页检查「是否启用」列。
互斥是按「策略类型」匹配的，不是按规则名称。如果你的规则类型是「满减」，互斥组里就必须选「满减」。如果规则实际是「阶梯价」，互斥组选了「满减」就不生效。
秒杀商品通常不与任何优惠叠加。建议创建一个「秒杀互斥组」，策略类型勾选「秒杀」+「满减」+「满折」+「优惠券」等所有可能叠加的类型，优先级设为最高（如100）。这样秒杀规则命中后，其他所有规则都被跳过。
在促销测试中心中，同时满足两个互斥规则的条件，提交后应只看到一条规则被应用。如果两条都命中，检查互斥组的策略类型是否与规则的实际类型匹配。
如何按活动场景（双11/年货节）管理规则？
2026年双11大促即将来临，你计划同时上线「满300减50」和「满199送赠品」两条规则。日常还有「新用户首单立减」在跑。你希望双11期间业务系统只计算双11相关的规则，不要混在一起；活动结束后也能一键批量下线。
操作步骤
double11_2026（编码用于 API 调用，建议英文+数字）- 标签名称：
2026双11大促
页面路径：/admin/promotions/promotiontag/add/
截图保存至：images/task-03-tag-create.png
2026双11大促：• 规则B（满赠）：策略类型选「满赠」，门槛199元，赠品选「双11限定礼品」，同样绑定双11标签。
tag_code: "double11_2026"。引擎只会筛选该标签下「生效中」的规则参与计算，不会把日常的「新用户首单立减」也算进去。
用法一（活动隔离）：大促期间传入 tag_code，只计算指定活动的规则，避免与日常促销混算。
用法二（批量管理）：按标签筛选后批量启停，活动上线/下线只需操作一次。
用法三（效果统计）：数据统计支持按标签聚合，快速查看「双11」整体投入和产出。
在促销规则列表按「2026双11大促」标签筛选，应同时看到满减和满赠两条规则。然后在促销测试中心传入 tag_code: "double11_2026" 测试，结果应只命中这两条双11规则。
怎么确认规则计算结果正确？
你刚配置了一条复杂的阶梯满减规则（满100减10、满200减30、满300减60），但不确定不同金额的购物车会命中哪一档。你想在正式上线前验证清楚。
操作步骤
页面路径：/admin/promotions/promotionrule/test/smart/
截图保存至：images/task-04-test-page.png
页面路径：/admin/promotions/promotionrule/1/debug/
截图保存至：images/task-04-rule-debug.png
cart_items。例如测试150元购物车：{"sku":"SKU001","quantity":1,"price":"150.00"}
页面路径：/admin/promotions/promotionrule/test/smart/
截图保存至：images/task-04-test-result.png
促销测试中心调用的是真实计算引擎，只匹配状态为「生效中」的规则。
如果你的规则设置了「仅限指定商品」，测试时也要传入对应的用户属性或商品 SKU，否则规则因条件不匹配而被跳过。
手动计算一遍预期结果，和系统输出对比。例如 150元购物车 + 满100减10 = 应付140元。如果系统输出一致，说明配置正确。
活动上线后，如何查看效果数据？
双11活动已经上线3天了，老板问你：这个活动带来了多少订单？优惠了多少钱？有多少订单取消或退款了？你需要快速给出数据。
查看汇总数据
页面路径：/admin/trace/dashboard/promotion-usage/
截图保存至：images/task-05-dashboard.png
• 快捷范围：点击「近1天/近3天/近7天/近30天」按钮，系统会自动填充起始和结束日期并刷新数据。
• 自定义日期：手动选择起始日期和结束日期，支持跨月统计，修改后自动刷新。
• 月度营销预算：在筛选栏输入本月营销预算金额，页面会显示独立的预算进度条（达成率、预估月末支出）。预算数据始终按自然月统计。
• 预算进度条：本月优惠花了多少 vs 预算目标，以及按当前速度预估月末是否超支。预算始终按自然月统计，不受上方时间筛选影响。
• 风险状态灯：损耗率、退款率、取消率三色警示。绿=正常，黄=注意，红=危险。
• 核心 KPI 六宫格：带动 GMV（促销拉动的订单总金额）、实付总额（用户实际支付）、优惠总金额（促销减免）、优惠渗透率（优惠力度）、覆盖用户/订单。均只统计已成交订单，每张卡片带环比变化。
• 转化漏斗：订单从「未成交」→「已成交」→「取消/退款」的全链路分布。超过 7 天未成交的订单会自动视为已成交。
• 损耗分析：促销优惠最终没生效的订单。损耗 = 取消 + 退款。
• 趋势分析：每日/每小时的优惠金额和订单数走势。同一天自动展示小时粒度。
• 策略效能矩阵：哪种策略花钱多、订单少（识别高投入低产出）。
• 状态分布：已成交 / 取消 / 退款的金额占比。
• Top 促销排行：哪条规则优惠金额最多，以及与上期对比。
• 促销明细表格：每条规则的 GMV、优惠金额、命中率等。
查看逐笔明细
数据统计来源于「使用留痕接口」。业务系统在订单完成后需调用该接口上报数据。如果页面暂无数据，说明技术团队尚未接入或暂无订单。
如果数据与业务系统对不上，通常是因为：1）部分订单未调用使用留痕接口上报；2）同一订单多次计算产生了多条记录，但业务系统未绑定最后一次的记录。
正确做法：业务系统需维护「订单 → 计算凭证」的映射关系。用户修改购物车后重新调用促销计算接口会生成新的凭证；业务系统应始终用最新凭证覆盖旧值，确保一个订单最终只对应一个有效凭证。订单支付完成后，使用最终凭证调用使用留痕接口上报。
促销使用记录默认只保留 90 天热数据。超过 90 天的记录会自动按订单ID聚合归档，释放数据库空间，同时保留完整数据用于财务审计。
如需查询 90 天前的历史记录，请联系平台技术人员，提供订单号及大致时间范围，技术人员可从归档存储中协助调取。
如何用模板快速创建一场活动？
你需要创建一场「满减」活动，但从零开始填写门槛条件、优惠动作、适用范围等参数比较繁琐。系统预置了常用场景的模板，能不能直接选用并快速生成？
操作步骤
页面路径：/admin/promotions/promotionrule/template-library/
截图保存至：images/task-06-template-lib.png
模板只帮你预填参数，创建后就是一条独立的规则，和模板再无关联。修改这条规则不会影响模板，修改模板也不会影响已创建的规则。
使用模板创建规则后，进入规则详情页，确认策略类型和参数与预期一致。
如何检查规则之间是否有冲突？
你同时运营着十几个活动，担心它们之间会互相冲突：比如两个规则的条件范围重叠，导致系统不知道用哪个；或者互斥组配置遗漏，导致不该叠加的优惠被叠加了。
操作步骤
页面路径：/admin/promotions/promotionrule/conflicts/
截图保存至：images/task-07-conflict.png
冲突检测主要检查「静态配置冲突」（条件重叠、互斥遗漏），不检查「动态业务冲突」（如商品库存不足导致实际未命中）。上线前仍需通过促销测试中心验证实际计算结果。
冲突检测报告显示「未检测到冲突」后，再用促销测试中心构造边界场景验证一次，双重保险。
配置字段：分群和商品池的字段从哪里来？
你想按「会员等级」给用户分群，按「品牌」筛选商品池，但配置时看不到这些字段。因为字段必须先经过「字段定义管理」启用和配置，才能在分群、商品池、退款规则中使用。
操作步骤
页面路径：/admin/metadata/metadatafield/
截图保存至：images/task-fields-list.png
• 实体类型：选择「用户画像」或「商品信息」
• 字段列表：系统会自动扫描数据源表（如 UserProfile、Product）的所有字段，排除系统字段（id、created_at 等）后展示业务字段
• 已配置的字段会标记为「已配置」，未配置的为「待配置」
• 勾选需要的字段，点击确认
页面路径：/admin/metadata/metadatafield/select-fields/
截图保存至：images/task-fields-select.png
• 显示名称：对外展示的中文名，如「会员等级」「累计消费金额」
• 字段类型：
- 枚举：离散值（如会员等级 = 普通 / VIP / SVIP），系统会自动从数据源抓取所有值，可启用/禁用特定值、设置显示别名
- 数值：范围筛选（如消费金额 0 ~ 10000），可配置区间范围、大于等于、小于等于等
- 日期时间：时间筛选（如注册时间、最后消费时间），支持绝对时间区间、相对时间（近N天/月/年）
• 数组筛选逻辑：JSON 数组字段（如 tags）支持「包含任意（OR）」或「包含全部（AND）」
页面路径：/admin/metadata/metadatafield/configure/<id>/
截图保存至：images/task-fields-config.png
配置完成的字段会出现在以下模块的筛选条件中：
- 用户分群：用户画像字段（会员等级、消费金额、注册时间等）
- 商品池：商品信息字段（品类、品牌、售价、上架时间等）
- 退款规则：用于退款策略的条件判断
枚举字段的值是从数据源实时同步的。如果业务系统新增了会员等级（如新增了「黑卡」），但字段定义管理中没看到这个值，回到字段定义管理列表页，勾选该字段，从顶部 action 下拉中选择「🔄 同步字段值」，点击执行即可手动刷新。
配置完成后，进入「动态用户分群」创建页面，查看字段下拉列表中是否出现了刚配置的字段。如果没有，检查字段是否已启用以及实体类型是否匹配。
如何给特定人群发优惠？
你想给「VIP会员」发一张专属9折券，给「近30天未下单用户」发一张召回满减券。不同人群享受不同优惠，怎么配置？
操作步骤
页面路径：/admin/user_segment/usersegmentrule/add/
截图保存至：images/task-08-segment.png
VIP会员- 条件：用户等级 = VIP，或消费金额 ≥ 5000元
- 条件支持组合：and（同时满足）/ or（满足其一）
分群条件的字段来自「字段定义管理」。如果字段列表为空，说明用户画像字段尚未配置。路径：数据配置 → 字段定义管理，选择「用户画像」实体类型，启用需要的字段（如会员等级、消费金额）。详见上文「配置字段：分群和商品池的字段从哪里来？」
用户分群的数据通常定时同步（如每小时一次）。刚成为 VIP 的用户可能需要等下次同步后才能享受优惠。如需实时生效，联系技术团队调整同步频率。
在促销测试中心中，构造一个满足分群条件的用户（如 user_id 对应 VIP 用户），提交后应命中该规则。再换一个不满足条件的用户测试，应不命中。
如何限制活动只针对部分商品？
你只想让「春季新品」参与满减活动，其他商品不参与。或者想给「清仓商品」单独做特价活动，不影响正价商品。
操作步骤
页面路径：/admin/product_pool/productpoolrule/add/
截图保存至：images/task-09-pool.png
春季新品- 条件：品类 = 春装，或 上架时间 ≥ 2026-03-01，或 SKU 在白名单中
- 支持按品类、品牌、价格区间、上架时间、SKU列表等多种维度筛选
可以实现精细化的定向优惠：「春季新品（商品池）+ VIP会员（用户分群）= 只有VIP用户买春季新品才享受满减」。两者条件同时满足时才命中。
在促销测试中心中，购物车同时放入池内商品和池外商品，提交后查看：池内商品享受优惠，池外商品不参与优惠计算。
如何创建和管理消费券？
除了系统自动计算的促销规则，你还想给顾客发「可领取的优惠券」：如「新人注册领50元券」「满200减30通用券」。顾客在结算时手动选择使用。
操作步骤
页面路径：/admin/coupons/couponpooltemplate/add/
截图保存至：images/task-10-coupon.png
新人注册礼50元- 券类型：满减券 / 折扣券 / 无门槛券
- 门槛和优惠金额：如满100减50
- 发放总量：10000张
- 每人限领：1张
- 有效期：领取后7天内有效
促销规则：系统自动计算，顾客无感知。如满300减50，购物车满足条件自动减。
消费券：顾客主动领取/使用，有感知。如领取优惠券后在结算页勾选使用。
两者可以叠加：先算促销规则，再算消费券（分层计算）。
促销规则（自动）+ 消费券（手动）叠加后，可能出现优惠过多、利润为负的情况。建议在「促销测试中心」中模拟「促销后金额 + 消费券」的组合场景，确保叠加后仍有利润空间。
进入「消费券统计」页面，查看券的领取量、使用量、核销率。路径：数据统计 → 消费券统计。
如何配置退款时的分摊策略？
顾客买了两件商品享受了"满300减50"，现在想退其中一件。退款时应该退多少钱？是退原价还是按比例扣除优惠？如果退款金额太大，要不要转人工审核？
操作步骤
页面路径：/admin/promotions/refundconfigtemplate/add/
截图保存至：images/task-11-refund.png
- 「优惠不退」：部分退款时保持优惠不退还，由商家/平台承担损失。适用于首单礼金、新客专享等营销场景。
- 「优惠全退」：退该商品时，该规则给该商品的全部优惠都收回（不按数量比例）。适用于严格促销场景。
- 「兜底人工审核」：当退款满足特定条件时自动转人工，如退款金额超过阈值、退款比例过高（如超过80%）、同一订单多次退款（如第3笔起）、或所有退款一律转人工。
1. 金额减免（满X减Y）：按比例分摊——按订单实付比例分摊券面额，退款时按商品金额占比退回对应券额
2. 百分比折扣（X折）：按比例分摊——按订单实付比例分摊折扣金额，退款时按商品金额占比退回对应折扣
3. 无门槛直抵（立减Y）：按比例分摊——按订单实付比例分摊直抵金额，退款时按商品金额占比退回对应直抵额
4. 阶梯减免（每满X减Y）：阶梯重算——退款后订单金额低于阶梯门槛时，重新计算适用的阶梯档位并退回差额券
5. 特价券（指定价）：优先扣除——退款时优先扣除券优惠部分，剩余部分按实付比例退回
每种券类型可选择三种处理方式之一：
• 自动分摊（默认）：按上述分摊模型自动计算退款
• 人工审核：该类型券退款一律转人工处理
• 不退回：该类型券在退款时作废不退
注意：平台只给出返券建议，实际返券/退券操作需由外部券系统执行。
- 「金额超限」：退款金额超过阈值（如超过1000元）
- 「退款比例超限」：退款比例过高（如超过80%）
- 「多次退款」：同一订单多次退款（如第3笔起）
- 「全量人工」：所有退款一律转人工
售后策略修改后，只影响新订单，不影响已生成的计算凭证（trace）。这是设计上的「凭证固化」机制——正向计算时写入 trace 的数据永久不可变更，确保退款时不受模板后续变更的影响。历史订单无法按新策略退款，技术上不支持回刷或重写。
如业务上确需处理历史订单，建议通过业务层面解决：线下补差价、单独发放补偿券、或引导用户重新下单后按新策略退款。
在「促销测试中心」中执行一次计算，查看结果中是否包含商品级优惠分摊明细（item_discounts）。然后进入「促销计算凭证」（Admin 菜单中显示为「促销计算快照」）列表，找到对应的 trace_id，查看凭证中的商品分摊明细是否正确。
如何查看规则变更和API调用记录？
有同事说某个活动突然失效了，你想查是谁改动了规则。或者技术团队说API响应慢，你想看看最近的调用量和错误率。
查看规则变更记录
页面路径：/admin/trace/ruleauditlog/
截图保存至：images/task-12-audit.png
查看API调用记录
- API调用记录（路径：数据统计 → API调用记录）：逐笔明细，展示每次调用的请求参数、响应结果、耗时。
页面路径：/admin/trace/dashboard/api-calls/
截图保存至：images/task-12-api-stats.png
规则意外变更、活动突然失效、计算结果异常 —— 先看审计日志确认是否有人改了配置，再排查其他原因。
修改一条规则后保存，等待1-2分钟，进入规则审计日志，应能看到刚才的操作记录。
如何把外部系统的商品、用户和券数据接进来？
你刚接入 MyPromotion 系统，外部数据同步是可选增强，不是强制要求。平台的核心促销计算能力（满减、满折、阶梯价、秒杀等）不需要任何外部数据同步即可正常工作。
不接入外部数据时，你可以这样使用平台：
• 条件配置：金额门槛、数量门槛、时间段、星期几、用户分组（请求传入）、购买渠道（请求传入）、支付方式（请求传入）、首单用户（请求传入）、指定 SKU / 品类 / 标签（在规则配置中直接指定）
• 范围配置：全部商品、指定 SKU 列表、指定品类 ID 列表、指定标签列表、排除 SKU 列表
• 动作配置：固定金额减免、百分比折扣、固定价格、免运费、赠送积分
• 请求要求：必须在 cart_items 中传入商品 SKU、数量、价格；条件相关的字段（如 category_id、tags、user_group、channel、payment_method、is_first_order 等）需在 context 中传入
接入外部数据后，才能使用以下高级功能：
① 商品数据 → 配置动态商品池（用可视化规则自动筛选商品，池内成员自动更新），替代手动维护 SKU 列表的方式
② 用户画像 → 配置动态用户分群（用 RFM、标签、行为等多维度规则自动筛选用户），替代手动维护用户分组的方式
③ 消费券模板 → 促销规则「赠送优惠券」动作时选择券模板；用户用券计算时自动查询可用券
④ 消费券实例 → 退款计算时读取券实例状态，按券类型匹配分摊模型并选择处理方式给出返券建议
系统支持三种接入方式，根据你的业务需求选择最适合的一种。
方式一 Pull（平台拉取）：外部系统有开放 API，平台定时主动去拉数据。适合商品、用户画像、券模板等批量数据。
方式二 Push/Webhook（推送接收）：外部系统能主动推送数据到本平台。适合对实时性要求高的数据，强烈建议用于消费券实例同步。
方式三 文件导入：手动上传 Excel 文件。适合券模板初始化、历史数据一次性迁移。
即使不接入任何外部数据同步，外部系统在调用促销计算 API 时，也必须在请求体中传入以下数据：
cart_items（必填）：每个商品需包含 sku、quantity、price。如果规则用到品类/标签/品牌范围，还需传入 category_id、tags、brand_id。
context（按需）：如果规则配置了对应条件，需传入 user_group（用户分组）、channel（渠道）、payment_method（支付方式）、shipping_method（配送方式）、is_first_order（是否首单）、user_info.birthday（用户生日）等。
平台不会主动查询外部系统获取这些字段，全靠请求体传入。传入什么，平台就用什么做计算。
为什么需要同步券数据？
如果不同步券数据，以下功能无法使用，但基础促销计算不受影响：
• 促销规则配置「买赠 → 赠送优惠券」时，下拉列表为空，无法选择券模板
• 用户用券计算时，无法按 coupon_codes（精确匹配券实例）或 coupon_template_ids（自动匹配可用实例）查询并使用券
• 订单退款时，无法查询券实例状态，系统无法按券类型匹配分摊模型，返券建议可能不准确
券模板 vs 券实例的区别：
• 券模板 = 券的"定义"（如「满100减20」这张券的规则）。用于促销买赠配置和用户用券计算。数据量小，变化少，Pull 或文件导入均可。
• 券实例 = 用户实际领取的"一张张券码"（如用户A领取了码 COUPON_001）。用于退款计算和用户用券自动匹配。数据量大、状态变化频繁（领取/使用/过期），强烈建议用 Push/Webhook 实时同步。
重要：平台不发放券，也不负责核销券。券的创建、发放、使用核销均由外部券系统负责。平台只是读取同步过来的券数据用于计算和退款建议。促销计算用券成功后，平台不会更新券实例状态（不会把 unused 改成 used），必须由外部券系统同步最新状态到平台。
方式一：Pull 拉取同步
https://api.mall.example.com），选择认证方式（AccessKey / OAuth2 / Bearer Token），填入对应的密钥。点击「测试连接」确认能正常连通。
页面路径：/admin/datasources/datasource/add/
截图保存至：images/task-13-datasource.png
- 数据类型：选择商品 / 用户画像 / 消费券模板 / 消费券实例
- 数据源：选择刚才创建的数据源
- API 端点：填写外部系统提供的接口路径（如商品列表接口）
- 请求方法：GET
- 批次大小：每次拉取多少条（默认100条）
• 商品 / 用户画像 / 券模板：适合 Pull，定时同步即可。
• 券实例：也可以用 Pull，但频率建议设高一点（如每5分钟），否则退款时可能读到旧状态。
页面路径：/admin/datasources/datasyncconfig/
截图保存至：images/task-13-sync-task.png
product_name → 平台的 name，sale_price → price。字段映射支持自动识别，也可以手动调整。outer_id（券码）、status（unused/used/expired/returned/frozen）、used_amount（已使用金额）、use_order_id（使用订单号），这些直接影响退款计算结果。
方式二：Push/Webhook 推送接收（券实例强烈推荐）
- 签名密钥：系统会自动生成一个密钥，用于验证推送请求的来源合法性。把这个密钥提供给外部系统的技术团队。
/webhook/v1/product）。把这个完整 URL 提供给外部系统的技术团队，他们配置好后，数据变更时会自动推送到本平台。
页面路径：/admin/datasources/datasyncconfig/add/
截图保存至：images/task-13-push.png
方式三：文件导入
页面路径：/admin/datasources/datasyncconfig/file-import/
截图保存至：images/task-13-import.png
199.00，不能写 199元）。上传后系统先进行预检查，列出格式错误和具体位置，修正后重新上传。查看同步状态
页面路径：/admin/datasources/datasyncsession/
截图保存至：images/task-13-sync-log.png
创建数据源后务必点击「测试连接」。如果连不上，检查：1）API 地址是否正确；2）密钥是否过期；3）外部系统的 IP 白名单是否放行了本平台的出口 IP。
同步任务显示"成功"但数据资产页面看不到数据，通常是字段映射配错了。例如外部系统字段叫 product_name，但你映射成了 name，而平台实际期望的字段是 title。对照模板中的标准字段名逐一核对。
如果外部系统说已推送但平台没收到，检查：1）IP 白名单是否包含了对方服务器的 IP；2）签名密钥是否一致；3）Webhook 地址是否完整（包括域名和路径）。可以在 API 调用记录中筛选 webhook 路径，查看是否有请求进来。
sku 和用户 ID 是唯一键。模板中有重复值或值已存在于系统中时，导入会跳过或报错。导入前先在 Excel 中检查重复项。
如果外部系统已经核销了某张券，但平台还没同步到最新状态，退款时会误判为"未使用"而建议返券，造成资损。券实例务必用 Push/Webhook 实时同步；如果用 Pull，频率不能低于 5 分钟，且退款前务必确认同步时间戳。
配置促销规则 → 动作选择「赠送优惠券」时，下拉列表为空，通常是因为消费券模板没有同步。券模板是"可选赠品列表"的数据来源，务必先完成同步，再配置促销规则。
Pull：外部系统有 API → 配置一次，自动定时同步 → 适合商品、用户画像、券模板
Push：外部系统能推数据 → 实时接收，无延迟 → 强烈推荐用于消费券实例
文件导入：无 API 或历史数据迁移 → 手动上传 Excel，操作简单 → 适合券模板初始化、一次性导入
同步完成后，进入对应的数据资产页面查看：商品数据（数据资产 → 商品数据）、用户画像（数据资产 → 用户画像）、券模板/实例（数据资产 → 券模板/券实例）。确认数据已正确显示，字段内容无乱码、无空值。
特别验证券实例：找一张外部系统已使用的券，查看平台中该券实例的 status 是否为 used，use_order_id 是否正确，确保与外部系统一致。
第四章：系统集成指南——不同架构如何接入促销计算
如果你是技术负责人或运维人员，想知道「我们的系统该怎么接促销引擎」，本章用几张流程图帮你理清：下单时（正向）怎么调接口、退款时（逆向）谁来调接口、不同系统架构能拿到什么价值。看完就能给研发团队写接入方案。
第一步：先判断你属于哪一类
促销引擎的价值能兑现多少，80% 取决于你的「商城系统」和「售后/OMS 系统」是自研的还是第三方的。回答下面 3 个问题，10 秒定位。
| 问题 | 你的情况 | 你属于 | 建议动作 |
|---|---|---|---|
| Q1：你的商城（小程序/APP/官网）是自研的吗？ | 用有赞/微盟等 SaaS → | E 类 | 当前不适合，选完整电商 SaaS |
| Q2：你的 OMS/售后系统是自研还是外包/第三方？ | 自研或外包定制 → | A / B 类 | 可直接 POC 全流程 |
| 用旺店通/百胜等标准产品 → | D 类 | 优先验证正向 + 对账追溯 | |
| Q3：你是 SaaS 服务商（向客户提供软件）？ | 是 → | C 类 | 最理想的落地场景 |
引擎的「正向逆向一致性」价值，只有在「正向计算结果能被退款环节读取」时才能兑现。商城自研 + OMS 可控（A/B/C 类）= 价值最大化；商城自研 + 第三方 OMS（D 类）= 至少做对账追溯。
第二步：正向计算链路（下单时）—— 所有类型都一样
正向计算就是「用户下单时，引擎算优惠金额」。不管你的系统架构是哪一类，正向计算的调用方都是商城系统，链路完全相同。
展示价格
POST /api/v1/promotions/calculate/
preview = true
用户勾选/取消促销或券
POST /api/v1/promotions/calculate/
preview = false（默认）
trace 永久固化
到订单表
按应付金额扣款
POST /api/v1/promotions/usage/ status=pending
优惠预占，KPI 不计入
pending（待确认）。此时优惠已预占但未正式生效，核心 KPI 不计入。POST /api/v1/promotions/usage/ status=confirmed
优惠正式生效，计入 KPI
confirmed（已确认），促销优惠正式生效，核心 KPI 只统计此状态。若业务系统不主动更新，pending 超过 7 天引擎自动乐观确认为 confirmed。POST /api/v1/promotions/usage/ status=cancelled
优惠作废，释放预占
cancelled（已取消），促销使用作废并释放预占配额。引擎不会自动感知订单取消。发货前取消只需将 usage 更新为 cancelled 释放优惠预占；退款资金如何处理（原路退回、退到余额、退到卡券等）由业务系统自行决定，不经过引擎 refund 链路。只有用户「收到货后申请退货退款」（可能部分退、可能多次退）才需要调用 refund/calculate + refund/execute。
正向计算返回的 trace_id 是后续退款、对账、客服争议处理的唯一钥匙。如果商城没保存，退款时引擎找不到原始分摊记录，只能按「本地比例」兜底计算，偏差又会回来。
第三步：逆向计算链路（售后退款时）—— 这才是差异所在
逆向计算针对「用户收到货后申请退货退款」的场景（可能是部分退），引擎读取正向计算保存的计算凭证（trace），返回该退多少钱。发货前的「整单取消」不走此链路，由业务系统自行处理。不同架构的「谁来调引擎退款接口」差别很大，直接决定了你能拿到什么价值。
你的自研系统
POST /api/v1/refund/calculate/
读取 trace 中 item_discounts 商品级分摊
POST /api/v1/refund/execute/
按引擎金额原路退回
退款链路采用「先扣减引擎可退余额，后调用支付网关」的顺序，目的是利用引擎乐观锁防止并发超退。若支付网关调用失败：
1. OMS 应重试支付网关：同一 refund_no 重复请求 refund/execute 引擎不会重复扣减（幂等），但也不要重复调用引擎，只需重试支付网关；
2. 多次重试仍失败时标记异常：由人工介入处理，引擎状态已是 executed，不可回滚；
3. 对账依据：通过计算凭证查询（GET /api/v1/traces/{trace_id}/）核对引擎退款记录与实际支付流水。
财务对账可建 T+1 自动化脚本；客服零介入（退款金额精确计算）；超退风险归零（乐观锁 + 累计金额校验）。
外包系统
代理调用引擎
POST /api/v1/refund/calculate/
POST /api/v1/refund/execute/
外包 OMS 团队必须愿意配合：1）接收商城推送的退款金额；2）或允许商城代调引擎后把结果写回 OMS。如果外包团队不配合，价值退化为 D 类（仅正向 + 对账追溯）。
与 A 类相同，B 类也是先执行 refund/execute 扣减引擎可退余额，再由 OMS 调用支付网关。若支付网关调用失败：OMS 应重试支付网关（不要重复调引擎），多次失败标记异常人工介入，引擎状态不可回滚。
月末对账不再抽调专人核对促销退款异常；争议退款处理从数分钟/笔降至秒级调取 trace 凭证；消除按比例退款的系统性偏差。
你产品中的一部分
POST /api/v1/refund/calculate/
返回退款金额
POST /api/v1/refund/execute/
按引擎金额原路退回
SaaS 平台接入引擎前通常会有两方面顾虑：1）服务依赖——引擎故障或延迟会直接影响 SaaS 平台的退款链路，即使私有化部署也需考虑引擎服务的运维和升级成本；2）定制灵活性——引擎的促销模型是标准化的，平台自有业务逻辑（如特殊会员体系、平台补贴规则）需要额外适配。数据安全方面，SaaS 平台通常选择私有化部署，订单数据不出内网，合规风险可控。建议先用隔离环境做 PoC 验证，确认性能和模型适配度满足要求后再全面接入。
与 A 类相同，SaaS 先执行 refund/execute 扣减引擎可退余额，再调用支付网关。若支付网关调用失败：重试支付网关（不要重复调引擎），多次失败标记异常人工介入，引擎状态不可回滚。
省去自研促销引擎的研发和运维成本；产品竞争力从「没有促销」跃升为「支持满减、阶梯价、秒杀、优惠券」；正向逆向完全闭环。
POST /api/v1/promotions/calculate/
作为正向计算凭证
旺店通/百胜等
比例均摊/固定规则
GET /api/v1/traces/{trace_id}/
第三方 OMS 的核心商业模式是按订单量收费，其售后模块是产品闭环的一部分，没有动力为单一客户接入外部退款 API。引擎无法强迫 OMS 改变退款逻辑，但「有凭证可依」本身就能显著节省争议排查时间。
偏差定位：过去月末对账是「大海捞针」，现在引擎保存了完整正向分摊明细，可导出后与 OMS 退款明细比对，自行标记偏差订单。客服仲裁：消费者质疑退款金额时，客服可调取 trace_id 原始凭证，给出有据可依的解释。
第四步：四种架构对比一览
| 对比维度 | A. 双自研 | B. 商城+外包OMS | C. SaaS 服务商 | D. 商城+第三方OMS |
|---|---|---|---|---|
| 正向计算精度 | ✅ 引擎直接计算 | ✅ 引擎直接计算 | ✅ 引擎直接计算 | ✅ 引擎直接计算 |
| 退款自动化 | ✅ OMS 直接调引擎，全自动 | ⚠️ 商城代理推送，取决于 OMS 配合度 | ✅ SaaS 自身统一调用，全自动 | ❌ OMS 不接入引擎，只能追溯 |
| 对账效率 | ✅ 凭证完整，可建 T+1 自动比对 | ✅ 凭证完整，可建 T+1 自动比对 | ✅ 凭证完整，可建 T+1 自动比对 | ⚠️ 正向凭证完整，逆向数据受限于 OMS |
| 核心价值 | 全流程自动化，价值最大化 | 消除系统性偏差 + 释放对账人力 | 产品竞争力跃升，直接影响收入 | 至少实现对账追溯和偏差定位 |
| 落地阻力 | 低（自己说了算） | 中（需外包团队配合） | 低（自己说了算） | 高（第三方不配合） |
第五步：接入关键检查清单
trace_id 必须写入订单表（如 order.promotion_trace_id），并随订单持久化。这是后续退款和对账的唯一凭证。item_discounts 商品级分摊明细。POST /api/v1/promotions/calculate/ —— 传入显式规则编码列表，精确控制参与计算的规则。• 标签计算：
POST /api/v1/promotions/tags/<tag_code>/calculate/ —— 按活动标签批量触发，适合大促场景（如"双11"标签下的所有规则）。• 智能计算：
POST /api/v1/promotions/calculate/smart/ —— 支持 auto/tags/explicit 三种子模式，系统自动匹配可用规则。• 计算调试：
POST /api/v1/promotions/calculate/debug/ —— 查看互斥检查详情，用于排查规则未命中的原因。
trace 计算凭证读取分摊明细，不是重新计算促销。POST /api/v1/promotions/usage/ 异步上报（非阻塞），状态流转：pending → confirmed / cancelled。用于运营看板的 GMV、优惠渗透率等核心指标统计。正向计算 = 商城调引擎算优惠，保存 trace_id。逆向计算 = 谁能读 trace_id 谁就调引擎退款 API；OMS 不配合时，引擎至少当「账本」用，对账和客服争议不再空口无凭。
第五章：常见问题与排查
最可能的原因：业务系统没有调用促销计算 API，或者调用时传了显式编码（promotion_codes）但没有包含你的规则编码。
排查步骤：1）让技术团队确认下单流程是否调用了促销计算接口（标准计算、标签计算、智能计算均可）；2）检查请求参数中是否传了 promotion_codes 限制了规则范围；3）在「促销测试中心」中用同样的参数测试，看能否命中。
不可以。状态为「生效中」的规则，所有字段（包括规则名称、描述、门槛、优惠金额、时间范围等）均会被锁定，只能修改状态（改为「已暂停」或「已禁用」）。这是为了防止影响正在进行的订单。
如果需要修改规则内容：请先将状态改为「已暂停」或「已禁用」，修改完成后再重新激活。也可以停用旧规则后创建一条新规则。
原因：金额计算涉及 Decimal 精度舍入（四舍五入到分），多层计算可能产生 ±0.01 元的误差。这是正常情况。
建议：业务系统在处理金额时，允许 ±0.01 元的误差范围。如果误差超过这个范围，联系技术支持排查。
取决于互斥组配置。如果两个规则的策略类型在同一个互斥组内，只能享受其中一个（优先级高的）。如果不在同一互斥组，默认可以同时叠加。
常见可叠加组合：满减 + 包邮（通常是不同策略类型，不互斥）；满减 + 折扣（如果在同一互斥组则互斥）。
创建一个互斥组：编码填 seckill（英文唯一标识符），策略类型勾选「秒杀」+「满减」+「满折」+「优惠券」+「阶梯价」，优先级设为最高（如100）。秒杀规则命中后，其他所有规则都会被跳过。
数据统计依赖使用留痕接口上报的数据。业务系统需要在订单完成后调用该接口传入 trace_id 和 order_id。如果还没接入或没有真实订单，页面就是空的。
trace_id 是每次促销计算生成的唯一凭证 ID，用于退款时读取计算凭证。如果丢了，退款计算会失败（返回错误码 TRACE_NOT_FOUND，未找到计算凭证）。
建议：让技术团队在创建订单时把 trace_id 和订单一起持久化保存。计算凭证在热库保留90天，超期后自动转入 OSS 归档存储；如需查询超过90天的凭证，请联系促销引擎平台技术支持线下处理。
常见原因有以下几种，按排查顺序检查：
1）规则状态不同：促销测试中心只测试「生效中」的规则，而实际下单时如果规则状态是「草稿」或「已暂停」，不会命中。
2）显式编码限制：实际下单时业务系统可能传了 promotion_codes 参数，只让特定规则参与计算。测试中心默认不限制编码，会匹配所有生效中规则。
3）时间/用户/商品条件不同：测试中心传入的 context 和 cart_items 与实际下单参数不一致（如用户等级、商品品类等），导致条件匹配结果不同。
4）消费券差异：测试中心通常不测试消费券叠加，而实际下单时用户可能使用了优惠券，导致最终金额不同。
建议：用「规则调试测试」（单条规则详情页的测试按钮）验证单条规则的命中逻辑；同时让技术团队对比测试中心和生产环境的请求参数是否一致。
这是衡量 API 响应时间稳定性的分位值（Percentile），比「平均值」更能反映真实用户体验：
• P50（中位数）：50% 的请求响应时间低于该值，代表典型情况。
• P95：95% 的请求响应时间低于该值，代表绝大多数用户的体验。如果 P95 突然升高，说明有少部分请求变慢，需要排查。
• P99：99% 的请求响应时间低于该值，代表最差情况。P99 飙高通常意味着有极端慢查询或网络抖动。
MyPromotion 的标准计算 API 正常 P95 应在 50ms ~ 200ms 之间。如果持续超过 500ms，请联系技术团队排查。
修改规则：状态为「生效中」或「待生效」的规则不能直接编辑。你需要先将状态改为「已暂停」或「已禁用」，修改后再重新激活。修改后的规则只影响后续的新订单。
历史订单：历史订单的促销计算结果由当时的计算凭证（trace）固化保存，不受规则后续修改的影响。退款时读取的是凭证中的原始分摊明细，不是最新规则配置。这是设计上的「凭证固化」机制，确保退款金额与下单时一致。
第六章：词汇表与参考
| 术语 | 一句话解释 |
|---|---|
| 促销规则 | 定义「在什么条件下给什么优惠」的配置单元，如"满300减50" |
| 策略类型 | 优惠的计算方式，如满减、满折、特价、秒杀、包邮等 |
| 优先级 | 规则之间的排序依据，数字越大越优先，同优先级时先创建的先应用 |
| 互斥组 | 一组策略类型的集合，组内规则不能同时生效 |
| 标签 | 规则的分类维度，用于批量管理和按标签触发计算 |
| trace_id | 促销计算的唯一凭证 ID，用于退款时读取计算凭证 |
| 计算凭证（Trace / 快照） | 一次促销计算的完整上下文（请求参数、响应结果、商品级分摊明细）。凭 trace_id 查询，热库保留90天，超期后转入 OSS 归档。退款时直接读取凭证中的分摊明细，不再重新计算。在 Admin 后台菜单中也称为「促销计算快照」 |
| 使用留痕 | 订单完成后上报促销使用记录的过程，用于数据统计 |
| 促销测试中心 | 后台调试工具，测试所有「生效中」规则的计算结果，支持显式编码/标签/智能三种测试模式 |
| 规则调试测试 | 单条规则的调试页面，可测试「草稿」和「生效中」状态，未命中时自动诊断原因 |
| 分层计算 | 把优惠分为「平台促销层」和「外部券层」，明确各方职责 |
| 模板库 | 预置的促销规则模板，用于快速复用常见活动配置 |
| 规则冲突检测 | 自动检查多条规则之间是否存在条件重叠、互斥遗漏等冲突 |
| 动态用户分群 | 按用户属性（等级、消费金额等）划分人群，用于规则定向 |
| 动态商品池 | 按商品属性（品类、品牌、SKU等）划分商品集合，用于规则定向 |
| 消费券 | 顾客主动领取/使用的优惠券，区别于系统自动计算的促销规则 |
| 消费券池 | 消费券的模板管理中心，定义券的面额、门槛、发放总量等 |
| 组合规则 | 控制多张消费券之间能否叠加使用的配置 |
| 售后策略 | 定义退款时分摊方式、兜底人工处理的配置模板 |
| item_discounts | 商品级优惠分摊明细，退款时直接读取，不再重新计算 |
| 价格保护 | 防止促销后售价低于成本价或会员价的保护机制 |
| 策略关联配置 | 定义每种促销策略允许使用的条件类型、动作类型和范围类型。创建规则时系统据此自动过滤可选项，避免给满减策略配了秒杀专属动作这类错误 |
| 规则审计日志 | 记录促销规则的每一次增删改操作，用于追溯变更 |
| 数据源 | 外部系统（电商平台/ERP/CRM等）的API连接配置，供同步任务使用 |
| 数据同步 | 自动或手动将外部系统的商品/用户/券数据同步到本平台 |
| Pull（拉取） | 平台定时调用外部系统的 API 主动拉取数据，适合有开放接口的系统 |
| Push（Webhook 推送） | 外部系统主动推送数据到本平台的接收端点，适合有推送能力的 ERP/CRM |
| 文件导入 | 通过上传 Excel 文件批量导入数据，支持商品、用户、券等类型 |
| 同步日志 | 记录每次数据同步/导入任务的执行详情，包括成功/失败条数 |
| preview 模式 | 促销计算的预览模式（preview=true），只返回优惠金额、不生成 trace_id，用于购物车凑单展示 |
| promotion_codes | API 请求参数，显式指定要参与计算的促销规则编码列表。不传则系统从所有生效中规则自动筛选 |
| order_id | 业务系统的订单号，结算阶段调用计算接口时必须传入，用于绑定 trace_id 和订单 |
| cost_price / member_price | 商品成本价和会员价，用于价格保护 POC 测试，未传时自动从商品库补全 |
| P50 / P95 / P99 | API 响应时间的分位值。P95 表示 95% 的请求响应时间低于该值，是衡量接口稳定性的核心指标 |
| access_key / secret_key | 租户级别的 API 身份凭证，业务系统调用接口时用于鉴权。不同租户完全隔离 |
| 购物车实时算价 | 购物车阶段调用引擎实时计算优惠金额（preview 模式），让用户随时看到用了哪些规则、省了多少钱；同时返回凑单提示作为辅助参考 |
| 最优组合计算 | 系统枚举所有合法规则子集，选出优惠力度最大的组合。规则数≤15且子集数≤500时精确枚举，超出时降级为贪心优先级模式 |
| 强制叠加 force_stackable | 规则级配置，开启后该规则强制与其他规则叠加，不受互斥组限制 |
| 叠加白名单/黑名单 | stackable_with（白名单，指定可叠加的促销编码）和 mutex_with（黑名单，指定不可叠加的促销编码） |
| Fallback 兜底 | 退款时的降级策略：当退款满足金额超限、比例超限、多次退款等条件时，自动转人工审核 |
| refund_version | 退款执行时的乐观锁版本号，防止同一笔退款被重复执行（幂等控制） |
| 券售后策略 | 按券类型自动匹配分摊模型（金额减免/折扣券/无门槛券→按比例分摊，阶梯券→阶梯重算，特价券→优先扣除），可为每种券类型选择处理方式：自动分摊/人工审核/不退回 |
| 测试用例 | 在促销测试中心保存的固定测试参数组合，支持增删改查和自动 Payload 生成 |
MyPromotion 促销引擎 · 用户手册 · 最后更新：2026-05-03
遇到问题？点击页面右上角头像 → 「用户反馈」提交问题