营销与消息 API
营销与消息 API
本文归纳营销活动中心、优惠券、卡券钱包、Banner、广告、公告、消息、订阅、偏好、待办、派发和统计接口。
使用场景
| 场景 | 主要接口 | 说明 |
|---|---|---|
| 平台营销活动 | 平台活动、商户报名、活动范围、平台券、平台预算、平台活动价、补贴确认 | 平台管理端维护活动、报名、预算和补贴治理 |
| 商户营销活动 | 商户活动、平台活动报名、商户券、商户预算、商户活动价、成本日报 | 商户端维护店铺营销和成本数据 |
| 消费者领券 | 卡券钱包、可领取优惠券、领取优惠券 | 个人用户领取平台券和商户券 |
| 订单优惠 | 订单可用券、带券下单、支付用券、取消释放 | 订单链路接入优惠券锁定、使用和释放 |
| 首页运营 | Banner、Banner 分组、广告位、广告位分组 | 管理端配置，小程序端展示 |
| 平台公告 | 公告接口 | 平台发布、取消发布和置顶公告 |
| 消息配置 | 模板、内容、路由规则 | 管理消息内容和接收规则 |
| 用户触达 | 站内信、订阅、偏好 | 个人、商户、员工分别接收消息 |
| 待办协同 | 个人待办、商户待办、员工待办、平台待办 | 承接需要人工处理的业务事项 |
| 派发追踪 | 派发计划、派发日志、统计 | 查看消息计划、发送结果和数据 |
事件触达建议
| 业务事件 | 推荐接收人 | 推荐能力 |
|---|---|---|
| 商户入驻审核结果 | 商户 | 商户消息、商户待办 |
| 商品上架审核结果 | 商户 | 商户消息 |
| 订单支付成功 | 商户、消费者 | 商户待办、个人消息 |
| 商户发货完成 | 消费者 | 个人消息 |
| 物流状态变更 | 消费者、商户 | 个人消息、商户消息 |
| 售后申请 | 商户、平台管理员 | 商户待办、平台待办 |
| 结算批次生成 | 商户 | 商户消息 |
| 提现审核结果 | 商户 | 商户消息 |
| 优惠券即将过期 | 消费者 | 个人消息 |
| 活动低预算预警 | 平台管理员、商户 | 平台待办、商户消息 |
| 营销补贴待确认 | 平台管理员 | 平台待办 |
后端营销和消息逻辑
营销和消息不是同一套业务，但它们在运营场景中经常衔接。营销模块负责产生活动、优惠和成本数据，消息模块负责把需要人工处理或用户感知的事件触达对应角色。
| 事件来源 | 业务结果 | 推荐消息能力 |
|---|---|---|
| 用户领券 | 个人卡券新增 | 可选个人消息，不建议强提醒 |
| 卡券即将过期 | 卡券仍未使用 | 个人消息或待办 |
| 活动预算不足 | 预算池余额低于阈值 | 平台消息、商户消息、待办 |
| 补贴待确认 | 订单支付后生成待确认补贴 | 平台待办 |
| 活动成本日报生成 | 成本数据可查询 | 平台消息或商户消息 |
| 活动到期结束 | 活动停止参与价格和领券 | 平台消息、商户消息 |
消息配置应优先使用模板、订阅、偏好和路由规则，业务模块不要硬编码固定文案。强提醒类事件需要忽略用户偏好时，应单独定义业务规则。
营销活动中心接口
营销活动中心接口按角色拆分。平台管理端负责平台级活动和治理，商户端负责商户自有活动和成本数据，消费者端负责领券和卡券钱包，订单端负责把优惠真正应用到交易。
通用约定：
| 约定 | 说明 |
|---|---|
| 分页查询 | 多数 GET /page 接口接收 MarketingCommonQuery，按活动、商户、店铺、SKU、状态、时间等条件筛选 |
| 详情查询 | GET /{id} 类接口通常会调用 findByIdAndVerify，不存在时返回业务异常 |
| 权限控制 | 平台接口使用 admin:marketing:* 权限，商户接口使用 client:merchant:marketing-* 权限，个人卡券使用 client:user:coupon-wallet:* 权限 |
| 商户归属 | 商户端接口会按当前登录商户账号校验归属，前端不应传入其他商户的业务 ID |
| 业务动作 | 启动、暂停、恢复、结束、结算、取消、充值、退回、补贴确认都属于业务动作，不应当用普通编辑接口替代 |
平台管理端
基础路径：/api/v1/marketing/admin。后端 Controller：AdminPlatformMarketingActivityController、AdminPlatformMarketingScopeController、AdminPlatformMarketingCouponController、AdminPlatformMarketingBudgetController、AdminPlatformMarketingPriceController、AdminMarketingSubsidyController。
| 接口名称 | 方法 | 子路径 | 权限标识 | 主要用途 |
|---|---|---|---|---|
| 平台活动 | GET /page、GET /{activityId}、POST、PUT /{activityId}、DELETE /{activityId} |
/platform/activity |
admin:marketing:platform-activity:* |
平台活动分页、详情、创建、修改和删除 |
| 平台活动状态 | PUT /{activityId}/start、PUT /{activityId}/pause、PUT /{activityId}/resume、PUT /{activityId}/end、PUT /{activityId}/close-unused-coupon、PUT /{activityId}/settle、PUT /{activityId}/cancel |
/platform/activity |
admin:marketing:platform-activity:edit |
启动、暂停、恢复、结束、关闭未使用券、结算归档和取消活动 |
| 平台活动商户报名 | GET /page、GET /{participationId}、POST /invite/batch、PUT /{participationId}/approve、PUT /{participationId}/reject |
/platform/activity-participation |
admin:marketing:platform-activity-scope:* |
查询报名、批量邀请商户、审核通过或拒绝报名 |
| 平台活动店铺范围 | GET /page、GET /{relId}、POST、POST /batch、PUT /{relId}、DELETE /{relId} |
/platform/activity-shop-rel |
admin:marketing:platform-activity-scope:* |
维护平台活动参与店铺 |
| 平台活动 SKU 范围 | GET /page、GET /{relId}、POST、POST /batch、PUT /{relId}、DELETE /{relId} |
/platform/activity-sku-rel |
admin:marketing:platform-activity-scope:* |
维护平台活动参与 SKU |
| 活动公告关联 | GET /page、GET /{relId}、POST、PUT /{relId}、DELETE /{relId} |
/activity-announcement-rel |
admin:marketing:activity-announcement-rel:* |
维护活动与公告的关联 |
| 平台优惠券组 | GET /page、GET /{groupId}、POST、PUT /{groupId}、DELETE /{groupId} |
/platform/coupon-group |
admin:marketing:platform-coupon-group:* |
维护平台券组 |
| 平台优惠券 | GET /page、GET /{couponId}、POST、PUT /{couponId}、DELETE /{couponId} |
/platform/coupon |
admin:marketing:platform-coupon:* |
维护平台券定义 |
| 平台券使用策略 | GET /page、GET /{strategyId}、POST、PUT /{strategyId}、DELETE /{strategyId} |
/platform/coupon-strategy |
admin:marketing:platform-coupon-strategy:* |
维护平台券适用规则 |
| 平台券策略目标 | GET /page、GET /{targetId}、POST、DELETE /{targetId} |
/platform/coupon-strategy-target |
admin:marketing:platform-coupon-strategy-target:* |
维护平台券适用目标 |
| 平台券池 | GET /page、GET /{poolId}、POST、PUT /{poolId}、DELETE /{poolId}、POST /{poolId}/grant |
/platform/coupon-pool |
admin:marketing:platform-coupon-pool:* |
维护券池并后台发券 |
| 优惠券记录 | GET /page、GET /{recordId} |
/platform/coupon-issue、/platform/coupon-use、/platform/coupon-allocation、/merchant/coupon-issue、/merchant/coupon-use、/merchant/coupon-allocation |
admin:marketing:*:query |
查询平台券和商户券发放、使用、分摊记录 |
| 平台预算池 | GET /page、GET /{poolId}、POST、PUT /{poolId}、DELETE /{poolId} |
/platform/budget-pool |
admin:marketing:platform-budget:* |
维护平台活动预算池 |
| 平台预算流水 | GET /page、GET /{transactionId} |
/platform/budget-transaction |
admin:marketing:platform-budget-transaction:query |
查询平台预算流水 |
| 平台预算账务 | POST /{poolId}/accounting、POST /{poolId}/recharge、POST /{poolId}/return-remaining、POST /{poolId}/post-settlement-adjust |
/platform/budget-pool |
admin:marketing:platform-budget:edit |
平台预算充值、调账、退回和结算后调整 |
| 活动成本日报 | GET /page、GET /{reportId} |
/activity-cost-report |
admin:marketing:activity-cost-report:query |
查询营销活动成本日报 |
| 平台活动价 | GET /page、GET /{strategyId}、POST、PUT /{strategyId}、DELETE /{strategyId} |
/platform/price-strategy |
admin:marketing:platform-price:* |
维护平台活动价格策略 |
| 活动价记录 | GET /page、GET /{recordId} |
/platform/price-cost-confirm、/activity-price-allocation |
admin:marketing:*:query |
查询平台活动价成本确认和活动价分摊记录 |
| 补贴确认 | GET /page、GET /{recordId}、POST /{recordId}/confirm、POST /{recordId}/cancel、POST /{recordId}/adjust-required、POST /{recordId}/manual-adjust、POST /{recordId}/abnormal-close |
/subsidy-confirm |
admin:marketing:subsidy-confirm:* |
查询、确认、作废、标记需调账、人工调账完成或异常结案营销补贴 |
| 补贴动作 | GET /page、GET /{actionId} |
/subsidy-confirm-action |
admin:marketing:subsidy-confirm-action:query |
查询补贴确认动作记录 |
| 补贴结算推进 | GET /page、GET /{advanceId}、POST /settlement/{settlementId} |
/subsidy-advance |
admin:marketing:subsidy-advance:* |
查询和推进补贴结算入账 |
平台管理端典型调用链：
- 创建平台活动：
POST /api/v1/marketing/admin/platform/activity。 - 批量邀请商户：
POST /api/v1/marketing/admin/platform/activity-participation/invite/batch，或手工绑定活动参与店铺和 SKU。 - 商户报名后，审核通过：
PUT /api/v1/marketing/admin/platform/activity-participation/{participationId}/approve。 - 配置平台券或活动价：调用
/platform/coupon*或/platform/price-strategy。 - 创建平台预算池并充值：
POST /platform/budget-pool、POST /platform/budget-pool/{poolId}/recharge。 - 启动活动：
PUT /platform/activity/{activityId}/start。 - 活动中查看发券、用券、分摊、成本日报和预算流水。
- 活动结束后关闭未使用券、执行补贴确认、剩余预算退回和结算归档。
平台端重点请求对象：
| 请求对象 | 主要字段 | 用途 |
|---|---|---|
PlatformMarketingActivity |
activityName、activityCode、activityStatus、startTime、endTime |
创建和维护平台活动 |
PlatformMarketingActivityShopRel |
activityId、merchantAccountId、merchantShopId |
绑定平台活动参与店铺 |
PlatformMarketingActivitySkuRel |
activityId、merchantAccountId、merchantShopId、productSpuId、productSkuId |
绑定平台活动参与 SKU |
PlatformActivityCouponPool |
activityId、couponId、budgetPoolId、issueStartTime、issueEndTime、totalQuantity、perUserLimit |
配置平台券发放池 |
ActivityBudgetAccountingRequest |
transactionType、amount、businessType、businessId、remark |
预算充值、冻结、解冻、人工调账和结算后调整 |
MarketingCouponGrantRequest |
personalAccountId、requestNo |
后台按券池给个人用户发放平台券 |
MarketingSubsidyConfirmRequest |
confirmAmount、remark |
人工确认营销补贴金额 |
MarketingSubsidyGovernanceRequest |
reason、remark |
作废补贴确认、标记需调账、人工调账完成或异常结案 |
商户端
基础路径：/api/v1/merchant/marketing。后端 Controller：MerchantMarketingActivityController、MerchantMarketingScopeController、MerchantMarketingCouponController、MerchantMarketingBudgetController、MerchantMarketingPriceController、MerchantMarketingSubsidyController。
| 接口名称 | 方法 | 子路径 | 权限标识 | 主要用途 |
|---|---|---|---|---|
| 商户活动 | GET /page、GET /{activityId}、POST、PUT /{activityId}、PUT /{activityId}/start、PUT /{activityId}/pause、PUT /{activityId}/resume、PUT /{activityId}/end、PUT /{activityId}/close-unused-coupon、PUT /{activityId}/settle、PUT /{activityId}/cancel |
/activity |
client:merchant:marketing-activity:* |
当前商户活动维护和状态流转 |
| 平台活动报名 | GET /page、POST /apply |
/platform/activity-participation |
client:merchant:marketing-activity-scope:* |
当前商户查看平台活动报名记录并提交报名 |
| 商户活动范围 | GET /page、GET /{relId}、POST、PUT /{relId}、DELETE /{relId} |
/activity-shop-rel、/activity-sku-rel |
client:merchant:marketing-activity-scope:* |
维护商户活动参与店铺和 SKU |
| 商户优惠券 | GET /page、GET /{couponId}、POST、PUT /{couponId}、DELETE /{couponId} |
/coupon-group、/coupon |
client:merchant:marketing-coupon*:* |
维护商户券组和商户券 |
| 商户券策略 | GET /page、POST、PUT /{strategyId}、DELETE /{strategyId}、POST /coupon-pool/{poolId}/grant |
/coupon-strategy、/coupon-strategy-target、/coupon-pool |
client:merchant:marketing-coupon*:* |
维护用券策略、券池和商户发券 |
| 商户券记录 | GET /page、GET /{recordId} |
/coupon-issue、/coupon-use、/coupon-allocation |
client:merchant:marketing-coupon-*:query |
查询商户券发放、使用和分摊记录 |
| 商户预算 | GET /page、GET /{poolId}、POST、PUT /{poolId}、DELETE /{poolId}、POST /{poolId}/accounting、POST /{poolId}/recharge、POST /{poolId}/return-remaining、POST /{poolId}/post-settlement-adjust |
/budget-pool |
client:merchant:marketing-budget:* |
商户活动预算池维护、充值、退回和调账 |
| 商户预算流水 | GET /page、GET /{transactionId} |
/budget-transaction |
client:merchant:marketing-budget-transaction:query |
查询商户预算流水 |
| 商户活动价 | GET /page、GET /{strategyId}、POST、PUT /{strategyId}、DELETE /{strategyId} |
/price-strategy |
client:merchant:marketing-price:* |
维护商户活动价格策略 |
| 商户活动价记录 | GET /page、GET /{recordId} |
/price-allocation、/platform-price-cost-confirm |
client:merchant:marketing-*:query |
查询活动价分摊和平台活动价成本确认 |
| 商户成本与补贴 | GET /page、GET /{id} |
/cost-report、/subsidy-confirm、/subsidy-confirm-action、/subsidy-advance |
client:merchant:marketing-*:query |
查询活动成本日报、补贴确认和结算推进记录 |
商户端典型调用链：
- 商户创建活动：
POST /api/v1/merchant/marketing/activity。 - 维护活动参与店铺和 SKU：
POST /activity-shop-rel、POST /activity-sku-rel。 - 如参与平台活动，提交报名：
POST /platform/activity-participation/apply，等待平台审核通过。 - 配置商户券、券池和用券策略，或配置商户活动价。
- 创建预算池并充值：
POST /budget-pool、POST /budget-pool/{poolId}/recharge。 - 启动商户活动：
PUT /activity/{activityId}/start。 - 活动中查看发券记录、用券记录、活动价分摊、预算流水和成本日报。
- 活动结束后查看补贴确认、补贴动作和结算推进记录。
商户端访问控制：
| 控制点 | 说明 |
|---|---|
| 活动归属 | 查询详情和修改活动时会校验活动的 merchantAccountId |
| 店铺归属 | 创建活动和活动价时会校验店铺是否允许当前商户营销 |
| 预算归属 | 预算池、预算流水、充值、退回和调账必须属于当前商户 |
| 记录归属 | 用券记录、成本日报、补贴确认和结算推进只能查看当前商户数据 |
| 平台活动价成本确认 | 商户只能维护自己相关的平台活动价成本确认记录 |
消费者端
基础路径：/api/v1/user/personal/coupon-wallet。后端 Controller：PersonalCouponWalletController。
| 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 |
|---|---|---|---|---|
| 我的卡券钱包 | GET |
/api/v1/user/personal/coupon-wallet |
client:user:coupon-wallet:query |
查询或创建当前个人账户卡券钱包 |
| 我的卡券 | GET /item/page、GET /item/{walletItemId} |
/api/v1/user/personal/coupon-wallet |
client:user:coupon-wallet:item:query |
查询个人卡券列表和详情 |
| 卡券流水 | GET /log/page、GET /log/{logId} |
/api/v1/user/personal/coupon-wallet |
client:user:coupon-wallet:log:query |
查询卡券领取、锁定、使用、释放和过期流水 |
| 可领取优惠券 | GET /claimable/platform/page、GET /claimable/merchant/page |
/api/v1/user/personal/coupon-wallet |
client:user:coupon-wallet:claimable |
查询可领取平台券和商户券 |
| 领取优惠券 | POST /claim/platform/{couponPoolId}、POST /claim/merchant/{couponPoolId} |
/api/v1/user/personal/coupon-wallet |
client:user:coupon-wallet:claim |
领取平台券和商户券 |
消费者端查询口径：
| 查询 | 筛选口径 |
|---|---|
| 可领取平台券 | 活动有效、券池在发放时间内、券池数量未超限、用户未超过领取限制、券适用范围满足查询条件 |
| 可领取商户券 | 在平台券条件基础上，还需要满足商户和店铺范围 |
| 我的卡券 | 按当前个人账户筛选，不允许跨个人账户查看 |
| 卡券流水 | 按当前个人账户筛选，可用于展示领取、锁定、使用、释放、过期和退回过程 |
领取接口请求体可为空。传入 MarketingCouponClaimRequest.requestNo 时可用于幂等追踪，前端建议在重复点击和网络重试场景传入稳定请求号。
订单优惠接口
基础路径：/api/v1/personal/order。后端 Controller：PersonalOrderTransactionController。
| 接口名称 | 方法 | 路径 | 主要用途 |
|---|---|---|---|
| 购物车订单可用券查询 | POST |
/api/v1/personal/order/cart/available-coupon |
根据购物车订单试算结果查询可用优惠券 |
| 单商品订单可用券查询 | POST |
/api/v1/personal/order/available-coupon |
根据单商品订单试算结果查询可用优惠券 |
| 购物车带券下单 | POST |
/api/v1/personal/order/cart/create |
创建购物车订单并锁定所选优惠券 |
| 单商品带券下单 | POST |
/api/v1/personal/order/create |
创建单商品订单并锁定所选优惠券 |
| 订单支付用券 | POST |
/api/v1/personal/order/{orderId}/payment |
支付前校验锁券，支付成功后标记优惠券已使用 |
订单优惠请求字段：
| 接口 | 字段 | 说明 |
|---|---|---|
| 购物车预览、购物车创建 | cartItemIds 或 cartItems |
指定购物车项，cartItems.quantity 可临时调整下单数量 |
| 购物车预览、购物车创建 | accountAddressId |
参与运费和可用券门槛计算 |
| 购物车预览、购物车创建 | platformCouponWalletItemId |
本单使用的平台券钱包项 ID |
| 购物车预览、购物车创建 | merchantCouponWalletItems[].merchantShopId |
商户券所属店铺 |
| 购物车预览、购物车创建 | merchantCouponWalletItems[].walletItemId |
商户券钱包项 ID |
| 单商品预览、单商品创建 | skuId、quantity、accountAddressId |
指定 SKU、数量和地址 |
| 单商品预览、单商品创建 | platformCouponWalletItemId、merchantCouponWalletItems |
与购物车用券字段一致 |
订单优惠返回字段：
| 字段 | 说明 |
|---|---|
totalPrice |
商品原总金额 |
totalDiscountPrice |
商品价格策略或活动价优惠 |
couponDiscountAmount |
优惠券优惠金额 |
platformCouponAmount |
平台承担优惠金额 |
merchantCouponAmount |
商户承担优惠金额 |
totalPayPrice |
用户最终应付金额 |
orderSubs |
按店铺聚合的子单试算结果 |
orderSubItems[].productCurrentPrice |
当前价格快照，包含活动价、运费和营销快照 |
联调用券顺序建议：
- 调用订单预览接口，不传优惠券，拿到基础金额和店铺拆单结果。
- 调用可用券查询接口，展示平台券和商户券。
- 用户选择优惠券后，再调用预览接口，传入所选券，展示优惠后金额。
- 用户确认下单，调用创建接口，后端锁定优惠券。
- 用户支付，调用支付接口，后端校验锁券并标记已使用。
- 若取消或支付失败，重新查询卡券钱包，确认卡券状态和流水是否恢复或释放。
错误处理关注点：
| 场景 | 前端表现建议 |
|---|---|
| 所选卡券不存在或不属于当前用户 | 提示优惠券不可用，并引导重新选择 |
| 卡券已过期、已锁定或已使用 | 清空本地选择，重新拉取可用券 |
| 商户券店铺不匹配 | 提示该优惠券不适用于当前店铺 |
| 优惠券金额超过可优惠金额 | 以后端返回金额为准，不在前端自行截断 |
| 支付前锁券校验失败 | 提示订单优惠已失效，返回订单确认页重新试算 |
营销接口
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | Banner | GET /list、GET /page、GET /{bannerId}、POST、PUT、DELETE |
/api/v1/market/banner |
*:market:banner:* |
Banner 维护和展示查询 | admin、client |
BannerController |
| shared | Banner 分组 | GET /list、GET /page、GET /{bannerGroupId}、GET /market-code/{marketCode}、POST、PUT、DELETE、POST /{bannerGroupId}/add-banners、DELETE /{bannerGroupId}/del-banners |
/api/v1/market/banner/group |
*:market:banner:group:* |
Banner 分组和绑定 | admin、client |
BannerGroupController |
| shared | 广告位 | GET /list、GET /page、GET /{advertiseId}、POST、PUT、DELETE |
/api/v1/market/advertise |
*:market:advertise:* |
广告位维护和查询 | admin、client |
AdvertiseController |
| shared | 广告位分组 | GET /list、GET /page、GET /{advertiseGroupId}、GET /market-code/{marketCode}、POST、PUT、DELETE、POST /{advertiseGroupId}/add-advertises、DELETE /{advertiseGroupId}/del-advertises |
/api/v1/market/advertise/group |
*:market:advertise:group:* |
广告分组和绑定 | admin、client |
AdvertiseGroupController |
| shared | 公告 | GET /list、GET /page、GET /{id}、POST、PUT、PUT /{id}/publish、PUT /{id}/unpublish、PUT /{id}/sticky、DELETE |
/api/v1/message/announcement |
*:message:announcement:* |
公告维护、发布、置顶和展示 | admin、client |
MessageAnnouncementController |
消息接口
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| admin | 消息模板 | GET /list、GET /page、GET /{templateId}、POST、PUT、DELETE |
/api/v1/message/template |
admin:message:template:* |
消息模板维护 | admin |
MessageTemplateController |
| admin | 消息内容 | GET /list、GET /page、GET /{contentId}、POST、PUT、DELETE |
/api/v1/message/content |
admin:message:content:* |
消息内容维护 | admin |
MessageContentController |
| admin | 消息路由规则 | GET /list、GET /page、GET /{ruleId}、POST、PUT、DELETE |
/api/v1/message/route-rule |
admin:message:route-rule:* |
消息接收和路由规则 | admin |
MessageRouteRuleController |
| admin | 消息订阅 | GET /list、GET /page、GET /{subscriptionId}、POST、PUT、DELETE |
/api/v1/message/subscription |
admin:message:subscription:* |
订阅配置管理 | admin |
MessageSubscriptionController |
| admin | 消息偏好 | GET /list、GET /page、GET /{preferenceId}、POST、PUT、DELETE |
/api/v1/message/preference |
admin:message:preference:* |
用户消息偏好管理 | admin |
MessagePreferenceController |
| admin | 站内信 | GET /list、GET /page、GET /{inboxId}、PUT /{inboxId}/read、DELETE |
/api/v1/message/inbox |
admin:message:inbox:* |
平台站内信管理 | admin |
MessageInboxController |
| admin | 派发计划 | GET /list、GET /page、GET /{planId}、POST、PUT、DELETE、PUT /{planId}/start、PUT /{planId}/stop |
/api/v1/message/dispatch-plan |
admin:message:dispatch-plan:* |
消息派发计划 | admin |
MessageDispatchPlanController |
| admin | 派发日志 | GET /list、GET /page、GET /{logId} |
/api/v1/message/dispatch-log |
admin:message:dispatch-log:* |
消息派发记录 | admin |
MessageDispatchLogController |
| admin | 消息统计 | GET、GET /scene、GET /channel |
/api/v1/message/statistics |
admin:message:statistics:* |
消息统计分析 | admin |
MessageStatisticsController |
| admin | 待办管理 | GET /list、GET /page、GET /{todoId}、POST、PUT、DELETE |
/api/v1/message/todo |
admin:message:todo:* |
平台待办管理 | admin |
MessageTodoController |
| client | 个人消息 | GET /page、GET /unread-count、GET /{messageInboxId}、PUT /{messageInboxId}/read、PUT /batch/read、PUT /read-all、PUT /{messageInboxId}/pin、PUT /batch/pin、PUT /{messageInboxId}/unpin、PUT /batch/unpin、PUT /{messageInboxId}/important、PUT /batch/important、PUT /{messageInboxId}/unimportant、PUT /batch/unimportant、DELETE /{messageInboxId}、PUT /batch/delete |
/api/v1/personal/message |
client:personal:message:* |
消费者站内信 | client |
PersonalMessageController |
| client | 个人消息订阅 | POST /sku/{skuId}/arrival、DELETE /sku/{skuId}/arrival、GET /sku/{skuId}/arrival/status、POST /sku/{skuId}/price-drop、DELETE /sku/{skuId}/price-drop、GET /sku/{skuId}/price-drop/status、POST /shop/{shopId}/new-product、DELETE /shop/{shopId}/new-product、GET /shop/{shopId}/new-product/status、GET /page |
/api/v1/personal/message/subscription |
client:personal:message:subscription:* |
SKU 到货、SKU 降价、店铺上新订阅和订阅分页 | client |
PersonalMessageSubscriptionController |
| client | 个人消息偏好 | GET /scene、PUT /scene |
/api/v1/personal/message/preference |
client:personal:message:preference:* |
个人消息偏好 | client |
PersonalMessagePreferenceController |
| client | 个人待办 | GET /page、GET /pending-count、GET /{todoId}、PUT /{todoId}/start、PUT /{todoId}/complete、PUT /{todoId}/cancel |
/api/v1/personal/todo |
client:personal:todo:* |
消费者待办 | client |
PersonalTodoController |
| client | 商户消息 | GET /page、GET /unread-count、GET /{messageInboxId}、PUT /{messageInboxId}/read、PUT /batch/read、PUT /read-all、PUT /{messageInboxId}/pin、PUT /batch/pin、PUT /{messageInboxId}/unpin、PUT /batch/unpin、PUT /{messageInboxId}/important、PUT /batch/important、PUT /{messageInboxId}/unimportant、PUT /batch/unimportant、DELETE /{messageInboxId}、PUT /batch/delete |
/api/v1/merchant/message |
client:merchant:message:* |
商户站内信 | ops |
MerchantMessageController |
| client | 商户消息偏好 | GET /scene、PUT /scene |
/api/v1/merchant/message/preference |
client:merchant:message:preference:* |
商户消息偏好 | ops |
MerchantMessagePreferenceController |
| client | 商户待办 | GET /page、GET /pending-count、GET /{todoId}、PUT /{todoId}/start、PUT /{todoId}/complete、PUT /{todoId}/cancel |
/api/v1/merchant/todo |
client:merchant:todo:* |
商户待办 | ops |
MerchantTodoController |
| client | 员工消息 | GET /page、GET /unread-count、GET /{messageInboxId}、PUT /{messageInboxId}/read、PUT /batch/read、PUT /read-all、PUT /{messageInboxId}/pin、PUT /batch/pin、PUT /{messageInboxId}/unpin、PUT /batch/unpin、PUT /{messageInboxId}/important、PUT /batch/important、PUT /{messageInboxId}/unimportant、PUT /batch/unimportant、DELETE /{messageInboxId}、PUT /batch/delete |
/api/v1/employee/message |
client:employee:message:* |
员工站内信 | ops |
EmployeeMessageController |
| client | 员工消息偏好 | GET /scene、PUT /scene |
/api/v1/employee/message/preference |
client:employee:message:preference:* |
员工消息偏好 | ops |
EmployeeMessagePreferenceController |
| client | 员工待办 | GET /page、GET /pending-count、GET /{todoId}、PUT /{todoId}/start、PUT /{todoId}/complete、PUT /{todoId}/cancel |
/api/v1/employee/todo |
client:employee:todo:* |
员工待办 | ops |
EmployeeTodoController |
前端封装
admin/src/api/announcementApi.ts、messageApi.ts、noticeApi.ts、operation.ts、marketingApi.ts、adminResourceRegistry.ts。client/api/index.js的banner、message、messagePreference、messageSubscription、todo、announcement、couponWallet分组。
营销中心当前管理端通过 MarketingResources、MarketingService 和泛资源页面承接标准列表、详情、新增、修改、删除和业务动作；商户营销路径使用 apiNamespace = client，需要走客户端入口。
维护注意事项
- 营销活动中心的接口数量较多，管理端标准资源优先走泛资源配置；非标准动作应显式配置动作路径、方法、确认文案和请求体字段。
- 平台券、商户券、活动价和原价格策略可能同时存在，最终金额必须以后端试算结果为准。
- 券池库存、预算余额和卡券状态都可能被并发请求改变，创建订单和支付前必须重新以后端校验为准。
- 商户端接口必须保持当前商户账号隔离，列表接口即使带查询参数也不应放宽商户范围。
- 补贴确认和结算推进是运营动作，需要保留操作人、操作时间、业务单号和备注。
- Banner 和广告位需要区分分组、投放位置和启停状态，避免前端拿到无效资源。
- 公告发布、取消发布和置顶是业务动作，建议保留操作日志。
- 消息模板变更不应影响已发送消息的历史内容展示。
- 订阅和偏好应优先尊重用户设置，强提醒类消息需要单独定义。个人消息订阅不是简单场景开关，当前按 SKU 到货、SKU 降价、店铺上新三个目标类型独立维护。
- 待办必须有明确处理状态，避免同一事项在多个角色下长期悬挂。