营销活动中心功能说明

更新日期：2026-05-22。

本文记录后端服务在 WinTradeCloudService 中的营销活动中心能力。当前代码主要分布在 wt-market、wt-business、wt-user、wt-client、wt-admin、wt-message 和 wt-quartz。

功能范围

营销活动中心把平台运营、商户经营、消费者领券、订单优惠、预算核算和补贴结算串成一条业务链路。

设计目标

多端入口

业务分层

营销活动中心不是单一 Controller，而是跨 wt-market、wt-business、wt-user、wt-message 和 wt-quartz 的组合能力。

推荐按以下顺序理解代码：

1. 先看 AdminPlatformMarketingActivityController 和 MerchantMarketingActivityController，确认平台和商户活动主档状态流转。
2. 再看 AdminPlatformMarketingScopeController 和 MerchantMarketingScopeController，确认平台邀请、商户报名、审核和活动范围。
3. 再看 PersonalCouponWalletController，确认消费者如何领取和查看卡券。
4. 再看 OrderAbstractServiceImpl 和 MarketingCouponOrderComponent，确认优惠券如何接入订单。
5. 最后看 MarketingBudgetAccountingComponent、MarketingSubsidyConfirmComponent 和定时任务，确认成本、预算和补贴如何闭环。

关键状态

营销活动中心新增多个状态枚举，联调时建议前端按后端枚举展示，不要在前端自行推断状态。

活动状态建议按下面口径使用：

平台管理能力

平台管理端新增的营销接口用于运营人员统一维护平台营销活动。

平台运营推荐通过 营销中心 / 平台营销活动配置向导 按以下顺序配置：

1. 创建平台活动，录入活动名称、活动编码、活动时间、活动状态、活动说明和 1:1、16:9、2:1 三张主宣传图。
2. 按需手工补录活动参与店铺和 SKU。标准报名流程可以跳过，等商户报名审核通过后自动生成范围。
3. 先保存预算池，确保后续券池有明确预算来源。
4. 如活动包含优惠券，创建券组、券定义、用券策略和券池，券池必须绑定已保存的预算池。
5. 如活动包含平台活动价，创建平台活动价策略，并确认成本承担方和商户确认规则；没有平台预选 SKU 时可以先跳过，等报名生成 SKU 范围后再补充。
6. 批量邀请目标商户，报名页面地址使用 /merchant-marketing/platform-activity-apply-workflow。
7. 商户报名后，平台审核通过，系统会把商户填报的店铺和 SKU 同步进入平台活动范围。
8. 发布前检查预算池、券池、优惠券池预算绑定、审核通过报名或手工 SKU 范围，再启动活动。
9. 活动运行期间查看发券记录、用券记录、活动价分摊、成本日报和预算流水。
10. 活动结束后关闭未使用券、执行补贴确认、剩余预算退回、结算后调整和活动归档。

平台端需要重点控制两个边界：

商户经营能力

商户端新增营销接口用于商户自主管理店铺营销。

商户运营推荐配置顺序：

1. 如参与平台活动，进入 商户营销 / 平台活动报名向导，先选择 已邀请 的平台活动。
2. 在向导中创建新的商户活动，或选择已有商户活动；创建时会带入平台活动和店铺信息。
3. 选择本店参与活动的 SKU 并提交报名，报名必须包含 SKU。
4. 等待平台审核通过；通过后系统会把店铺和报名 SKU 写入平台活动范围。
5. 如活动以优惠券为主，创建商户券、券池和用券策略。
6. 如活动以价格折扣为主，创建商户活动价策略。
7. 给商户活动预算池充值，充值资金来自商户钱包。
8. 启动活动，并在活动期内查看领券、用券、预算流水和成本日报。
9. 活动结束后查看补贴确认和结算推进记录，核对实际承担成本。

商户侧所有查询和写入都必须限制在当前商户账号下。接口已经在 Controller 中调用 getMerchantAccountId() 并校验归属，前端仍然需要避免把其他商户 ID 混入请求。

消费者卡券能力

个人用户新增卡券钱包，优惠券生命周期从领取进入钱包开始。

消费者卡券生命周期：

卡券展示建议至少包含：券名称、优惠类型、优惠金额或折扣、适用范围、有效期、状态、来源活动、所属商户店铺、是否即将过期。

订单接入逻辑

订单链路现在支持平台券和商户券。

1. 订单预览时，前端可以传入 platformCouponWalletItemId 和 merchantCouponWalletItems。
2. 后端先完成商品价格、库存、运费和地址试算。
3. MarketingCouponOrderComponent 在试算结果上叠加优惠券优惠金额。
4. 创建正式订单时，系统锁定本次使用的优惠券。
5. 支付前会校验已锁定优惠券仍然有效，校验失败会在新事务中释放优惠券。
6. 支付成功后，优惠券标记为已使用，并生成用券记录和分摊记录。
7. 订单取消、支付失败、待支付超时或退款完成时，系统按释放原因处理优惠券。
8. 支付成功后会创建待确认营销补贴，后续由补贴确认和结算推进流程处理。

涉及字段：

订单请求约束：

订单金额口径：

活动价计算

商品当前价格计算新增活动价优先逻辑。

1. 查询 SKU 所属 SPU、店铺货架和库存。
2. 先通过 MarketingActivityPriceComponent 查找匹配的平台活动价或商户活动价。
3. 若命中活动价，则写入活动价、优惠金额、结算基数和 promotionData。
4. 若未命中活动价，则回退到原有会员价、阶梯价、促销价等价格策略。
5. 最后叠加国内和国际运费，得到 totalPayPrice。

活动价会记录成本承担方、结算扣减规则和活动来源，便于后续预算核算和补贴处理。

活动价匹配建议按以下维度排查：

预算和补贴

营销预算用于控制活动成本，补贴用于承接商户结算中的营销补偿。

预算流水建议按业务类型核对：

补贴治理建议：

1. 支付成功后生成待确认补贴记录。
2. 平台查看补贴确认列表，核对订单、订单项、活动、预算池、商户、店铺和应收补贴金额。
3. 金额无误时执行确认，写入确认人、确认时间和确认流水。
4. 金额异常但仍需人工追踪时执行作废或异常结案，并记录治理说明。
5. 补贴确认完成后，执行补贴结算推进，把补贴纳入店铺级结算入账。
6. 后续发生退款或复核差异时，通过结算后调整记录成本冲销。

定时任务

定时任务联调时需要确认调度参数和运行频率。当前任务类只提供可被 Quartz 调用的方法，具体 cron 表达式需要在系统定时任务配置中维护。

数据模型概览

新增数据模型分布在 wt-market、wt-user 和 wt-business。

数据关系

核心关系说明：

联调注意事项

• 这次后端提交新增了大量实体和 Repository，需要确认数据库迁移脚本已经同步，否则可能出现缺表或缺字段。
• 前端下单必须区分平台券和商户券，跨店订单每个店铺最多传一张商户券。
• 商品价格展示应以后端当前价格接口为准，不要在前端自行重算活动价或优惠券金额。
• 预算充值和剩余预算退回会影响钱包和预算流水，联调时需要同时核对钱包流水、预算流水和活动成本数据。
• 补贴确认是人工治理流程，作废和异常结案不会自动释放结算入账，需要运营明确后续处理口径。

验收清单

待完善事项