简介

本文件为营销工具模块的API参考文档，覆盖优惠券管理、分销系统、分享推广、VIP会员体系以及促销活动与数据统计等能力。面向营销平台开发者，提供从接口定义到调用流程、数据模型、错误处理与性能保障的系统说明，帮助快速集成与稳定运行。

项目结构

营销相关功能在前后端分离的结构中组织：

• API层：位于 api/controller 与 api/route，负责对外暴露HTTP接口与路由注册。
• 模块层：位于 _'/module/{feature}/api 与 core，封装业务服务与领域逻辑。
• 控制器与服务解耦：API控制器仅做参数校验与响应组装，核心业务由模块服务实现。

graph TB
subgraph "API层"
A["api/route/*"] --> B["api/controller/*Controller"]
end
subgraph "模块层"
C["_'/module/*/api/*ApiController"] --> D["_'/module/*/core/*Service"]
end
B --> C
D --> E["订单/用户/商品等核心域"]

图示来源

• api/route/coupon.php
• api/route/distribution.php
• api/route/share.php
• api/route/vip.php
• api/controller/coupon/CouponController.php
• api/controller/distribution/DistributionController.php
• api/controller/share/ShareController.php
• api/controller/vip/VipController.php
• _'/module/coupon/api/CouponApiController.php
• _'/module/distribution/api/DistributionApiController.php
• _'/module/share/api/ShareApiController.php
• _'/module/vip/api/VipApiController.php

核心组件

• 优惠券模块：提供发放、领取、使用、核销、查询等能力，支撑满减、折扣、兑换等场景。
• 分销模块：提供分销商管理、佣金计算、推广链接生成、结算统计等能力。
• 分享推广模块：提供分享链接生成、分享统计、邀请奖励等能力。
• VIP会员模块：提供等级管理、权益配置、积分获取与兑换、续费/到期管理等能力。
• 促销与活动：通过优惠券与分销/分享联动，支持限时折扣、满减、团购等组合策略（以优惠券规则为核心）。
• 数据分析：围绕上述能力的曝光、领取、使用、转化、收益等指标进行统计与报表输出。

架构总览

整体采用“API控制器 + 模块服务”的分层架构，保证高内聚低耦合：

• 路由层将URL映射到API控制器。
• API控制器负责鉴权、参数校验、调用模块服务并返回统一响应。
• 模块服务封装领域逻辑，协调订单、用户、库存、支付等子系统。
• 数据一致性通过事务与幂等键保障；热点读通过缓存提升性能。

sequenceDiagram
participant Client as "客户端"
participant Route as "路由"
participant Ctrl as "API控制器"
participant Svc as "模块服务"
participant Core as "核心域(订单/用户/商品)"
Client->>Route : HTTP请求
Route->>Ctrl : 分发到控制器
Ctrl->>Ctrl : 鉴权/参数校验
Ctrl->>Svc : 调用业务方法
Svc->>Core : 读写数据/执行业务
Core-->>Svc : 结果
Svc-->>Ctrl : 业务结果
Ctrl-->>Client : JSON响应

图示来源

• api/controller/coupon/CouponController.php
• _'/module/coupon/api/CouponApiController.php
• _'/module/coupon/core/CouponService.php

详细组件分析

优惠券管理API

• 能力范围
  • 发放：批量/定向发放，设置有效期、适用商品、门槛、面额/折扣类型。
  • 领取：用户领取，限制每人限领次数、库存扣减、防刷。
  • 使用：下单时选择可用券，计算优惠金额，锁定券状态。
  • 核销：线下或线上核销，记录核销流水与审计。
  • 查询：按条件分页查询券列表、个人券包、使用记录。
• 典型调用序列（领取）

  sequenceDiagram
  participant U as "用户"
  participant C as "CouponController"
  participant A as "CouponApiController"
  participant S as "CouponService"
  U->>C : POST /coupon/claim
  C->>A : 转发至模块API
  A->>S : claim(userId, couponId, params)
  S-->>A : {success, couponInstanceId}
  A-->>C : 统一响应
  C-->>U : 领取结果

• 关键约束
  • 并发领取需加锁或原子扣减，避免超发。
  • 使用阶段需校验券状态、适用范围、门槛与剩余可用次数。
  • 核销需幂等，防止重复核销。

分销系统API

• 能力范围
  • 分销商管理：申请、审核、等级、绑定关系、上下级关系。
  • 佣金计算：按订单金额、品类、分销等级、活动叠加规则计算佣金。
  • 推广链接：生成带分销标识的推广链接，追踪来源与转化。
  • 结算与提现：佣金冻结、解冻、可提现余额、提现申请与打款。
• 典型调用序列（生成推广链接）

  sequenceDiagram
  participant D as "分销商"
  participant DC as "DistributionController"
  participant DA as "DistributionApiController"
  participant DS as "DistributionService"
  D->>DC : GET /distribution/link?product_id=...
  DC->>DA : 转发
  DA->>DS : generateLink(distributorId, productId, params)
  DS-->>DA : {shortUrl, trackingCode}
  DA-->>DC : 统一响应
  DC-->>D : 推广链接

• 关键约束
  • 佣金计算需考虑退货、取消、退款等逆向流程。
  • 推广链接需具备唯一性与防篡改校验。
  • 结算需对账与审计，确保资金安全。

分享推广API

• 能力范围
  • 分享链接生成：为商品/活动/内容生成可追踪的分享链接。
  • 分享统计：曝光、点击、注册、下单等漏斗指标。
  • 邀请奖励：被邀请人完成指定行为后，给邀请人发放奖励（积分、券、现金等）。
• 典型调用序列（分享统计上报）

  sequenceDiagram
  participant App as "前端/小程序"
  participant SC as "ShareController"
  participant SA as "ShareApiController"
  participant SS as "ShareService"
  App->>SC : POST /share/report (exposure/click)
  SC->>SA : 转发
  SA->>SS : report(eventType, shareId, userId, meta)
  SS-->>SA : 成功
  SA-->>SC : 统一响应
  SC-->>App : 成功

• 关键约束
  • 上报需去重与限流，避免刷量。
  • 事件时序需可回溯，便于归因分析。

VIP会员体系API

• 能力范围
  • 等级管理：等级规则、升级条件、保级规则。
  • 权益管理：专属折扣、免邮、生日礼、优先客服等权益发放与校验。
  • 积分体系：获取、消耗、过期、兑换商城。
  • 续费与到期：自动续费、到期提醒、降级策略。
• 典型调用序列（积分兑换）

  sequenceDiagram
  participant M as "会员"
  participant VC as "VipController"
  participant VA as "VipApiController"
  participant VS as "VipService"
  M->>VC : POST /vip/point/redeem
  VC->>VA : 转发
  VA->>VS : redeemPoints(userId, itemId, points)
  VS-->>VA : {orderId, status}
  VA-->>VC : 统一响应
  VC-->>M : 兑换结果

• 关键约束
  • 积分变动需事务与流水记录，保证可追溯。
  • 权益发放需幂等，避免重复发放。

促销活动接口（与优惠券联动）

• 限时折扣：通过优惠券或价格策略实现，结合时间窗口与库存控制。
• 满减活动：基于优惠券门槛与品类/店铺维度计算。
• 团购活动：多人成团后触发优惠券或专属价，结合分享推广拉新。
• 活动效果：通过分享统计、优惠券使用率、转化率等指标评估。

营销活动效果分析与数据统计

• 指标维度
  • 曝光、点击、注册、领券、用券、下单、复购、ROI。
  • 渠道来源、活动ID、商品类目、地域、设备类型。
• 数据源
  • 分享上报、优惠券日志、订单流水、用户行为埋点。
• 输出形式
  • 实时看板、离线报表、导出接口、订阅推送。

依赖关系分析

• 控制器与服务
  • API控制器依赖模块API控制器，后者再调用核心服务，形成清晰分层。
• 外部依赖
  • 订单、用户、商品、支付、短信、存储等核心域。
• 潜在循环
  • 通过接口契约与事件解耦，避免强耦合导致的循环依赖。

graph LR
RC["CouponController"] --> MC["CouponApiController"]
MD["DistributionController"] --> MA["DistributionApiController"]
RS["ShareController"] --> MS["ShareApiController"]
RV["VipController"] --> MV["VipApiController"]
MC --> CS["CouponService"]
MA --> DS["DistributionService"]
MS --> SS["ShareService"]
MV --> VS["VipService"]

图示来源

• api/controller/coupon/CouponController.php
• api/controller/distribution/DistributionController.php
• api/controller/share/ShareController.php
• api/controller/vip/VipController.php
• _'/module/coupon/api/CouponApiController.php
• _'/module/distribution/api/DistributionApiController.php
• _'/module/share/api/ShareApiController.php
• _'/module/vip/api/VipApiController.php

性能与实时性保障

• 并发与一致性
  • 领取/使用/核销等写操作采用数据库行级锁或分布式锁，配合幂等键避免重复。
  • 关键路径使用事务包裹，失败回滚保证数据一致。
• 缓存与热点
  • 券模板、活动信息、权益配置等读多写少数据使用缓存，设置合理TTL与失效策略。
  • 热门活动页采用CDN与静态化，降低后端压力。
• 限流与防刷
  • 对领取、上报、登录等敏感接口实施限流与风控策略。
  • 分享上报与统计写入采用异步队列削峰填谷。
• 监控与告警
  • 关键指标（成功率、延迟、错误率、库存余量）接入监控，异常阈值触发告警。
• 数据准确性
  • 所有资金与权益变更必须落库并生成不可变流水，支持对账与审计。
  • 统计口径明确，避免重复计数与漏计。

故障排查指南

• 常见问题定位
  • 领取失败：检查库存、有效期、用户限领次数、并发锁冲突。
  • 使用失败：校验券状态、适用范围、门槛、订单金额。
  • 核销异常：确认幂等键、重复提交、状态机流转。
  • 分销佣金差异：核对订单状态、退货退款、等级比例、活动叠加。
  • 分享统计偏差：检查上报去重、时间戳、归因链路。
• 建议步骤
  • 查看接口日志与错误码，定位失败阶段。
  • 核对入参与上下文（用户ID、活动ID、商品ID、时间）。
  • 检查数据库事务与锁等待情况。
  • 复核缓存一致性与失效策略。
  • 必要时回放事件与流水，还原问题现场。

结论

本API文档围绕优惠券、分销、分享、VIP与促销等营销核心能力，提供了清晰的接口边界、调用流程与保障机制。通过分层架构与严格的一致性策略，确保在高并发与复杂业务场景下的稳定性与可维护性。开发者可据此快速集成并扩展营销能力。

附录：接口清单

以下为各模块主要接口类别与职责说明（具体字段与示例请参考对应控制器与服务实现）：

• 优惠券

  • 发放：创建/批量发放、定向发放、模板管理
  • 领取：领取、查询个人券包、限制校验
  • 使用：下单选择、优惠计算、锁定
  • 核销：核销、撤销、流水查询
  • 统计：使用率、核销率、ROI

• 分销

  • 分销商：申请、审核、等级、关系链
  • 佣金：计算、明细、冻结/解冻、可提现
  • 推广：链接生成、追踪、归因
  • 结算：提现申请、打款、对账

• 分享推广

  • 链接：生成、短链、二维码
  • 统计：曝光、点击、注册、下单漏斗
  • 奖励：邀请奖励发放、规则配置

• VIP会员

  • 等级：规则、升级、保级、降级
  • 权益：配置、发放、校验
  • 积分：获取、消耗、过期、兑换
  • 续费：自动续费、到期提醒

• 促销与活动

  • 限时折扣、满减、团购、拼团
  • 活动报名、成团判定、退单处理

• 数据分析

  • 活动效果、渠道转化、用户生命周期价值
  • 报表导出、订阅推送、看板展示