活动、秒杀与营销链路

模块职责

活动模块负责 OPS 配置活动，服务站或 E站侧参与活动并生成业务单据。当前代码里活动类型较多，包含销售活动、客户活动、优惠券、赠品活动、预售、秒杀活动等。秒杀是近期最完整的一条链路，覆盖 OPS 管理、OA 审批、服务站商品列表、购物车、下单、采购单、支付和库存释放。

主要入口

• OPS 秒杀活动 API：application/controllers/inner/activity/FlashActivity.php
• 服务站秒杀 API：application/controllers/inner/moveMall/FlashSale.php
• PC 活动入口：application/controllers/scm/FlashSale.php、GiftAct.php
• 市场活动入口：application/controllers/market
• 活动任务：application/controllers/tasks/FlashSaleTask.php、ActivityVisit.php、GiftActivityTask.php

关键 Service

• application/Services/Activity/FlashActivitySer.php：OPS 秒杀活动管理。
• application/Services/Activity/FlashSaleSer.php：服务站秒杀购买链路。
• application/Services/Activity/ActivityOrderSer.php：活动订单。
• application/Services/Activity/SaleActivitySer.php：销售活动。
• application/Services/Activity/ActivityChangeSer.php：活动变更。
• application/Services/Marketing/ClientActivitySer.php：客户活动。
• application/Services/Marketing/ClientCouponSer.php：优惠券。

关键模型

• 秒杀活动主表：application/models/activity/FlashActivityModel.php
• 秒杀活动商品：FlashActivityGoodsModel.php
• 秒杀服务站范围：FlashActivityStationScopeModel.php
• 秒杀购物车：FlashCartModel.php
• 秒杀订单：FlashOrderModel.php
• 秒杀订单明细：FlashOrderDetailModel.php
• 赠品活动：application/models/giftActivity

秒杀活动状态

状态定义在 application/KzData/Enums/FlashActivityEnums.php：

• 活动类型：单品售卖、套包售卖。
• 库存范围：服务站对应仓、指定仓、全局预留。
• 申请状态：草稿、审批中、审批通过、审批驳回。
• 启用状态：草稿、启用、提前结束。
• OA 状态：草稿、审批中、审批通过、审批驳回。
• 页面状态：未开始、进行中、已结束。
• 商品状态：待开始、进行中、已结束、已失效。
• 购物车状态：无效、有效。
• 订单状态：已创建、待支付、已支付、已取消、已关闭。

OPS 秒杀配置流程

运营创建活动
  -> inner/activity/FlashActivity::saveFlashActivity
  -> FlashActivitySer::saveFlashActivity
  -> 校验活动时间、库存范围、价格模式、商品明细
  -> 草稿保存 flash_activity / flash_activity_goods
  -> submitFlashActivity 提交 OA
  -> OA 通过后活动可启用
  -> 服务站侧按活动时间、服务站黑白名单、商品状态展示

主要 API：

• listFlashActivity：OPS 活动列表。
• detailFlashActivity：活动详情。
• listFlashActivityGoods：活动商品明细。
• saveFlashActivity：保存草稿或更新已审批活动。
• importFlashActivityGoods：导入活动商品。
• downloadFlashActivityGoodsTemplate：下载导入模板。
• exportFlashActivityGoods、exportFlashActivity：导出。
• submitFlashActivity：提交审批。
• endFlashActivity：提前结束。

服务站秒杀购买流程

服务站浏览秒杀商品
  -> inner/moveMall/FlashSale::goodsList / goodsDetail
  -> FlashSaleSer 计算活动状态、商品状态、服务站库存、供给仓库存、限购、是否可加购
  -> addCart 或 buy now
  -> orderPreview 生成确认页
  -> submitOrder 创建 flash_order 和 flash_order_detail
  -> 锁定活动商品数量 locked_qty
  -> createPoOrdersForFlashOrder 创建采购单
  -> 采购单待支付
  -> 支付成功 markPaidByPoOrder：locked_qty 转 used_qty，秒杀订单变已支付

服务站 API：

• goodsList：商品列表。
• goodsDetail：商品详情。
• packageGoodsList：套包商品。
• goodsFilters：筛选项。
• getCartCount：购物车数量。
• addCart：加购。
• cartList：购物车列表。
• updateCart：更新数量、选择、删除。
• orderPreview：确认页。
• submitOrder：提交订单。
• orderDetail：订单详情。
• cancelOrder：取消订单。

秒杀订单和采购单的关系

秒杀订单不是最终履约单据，它会转成采购单：

• 秒杀订单主表记录活动快照、金额、来源和过期时间。
• 秒杀订单明细记录商品快照、购买数量、活动商品 ID。
• 采购单使用 PoOrderEnums::ORDERTYPE_FLASH_ORDER。
• 采购单来源使用 PoOrderEnums::SRC_ORDER_TYPE_FLASH_ACTIVITY。
• 采购单的 srcOrderId、srcOrderNo 关联秒杀订单。

秒杀码释放和补偿

秒杀数量有两个关键字段：

• locked_qty：待支付订单锁定数量。
• used_qty：支付成功后真正占用数量。

状态联动：

• 用户取消待支付秒杀单：关闭关联待支付采购单，释放 locked_qty。
• 采购单支付超时：释放 locked_qty，秒杀订单变已关闭。
• 支付成功：locked_qty 减少，used_qty 增加，秒杀订单变已支付。
• 采购未发货关闭：按关闭明细释放已占用或锁定数量。

兜底方法：

• FlashSaleSer::expireWaitPayOrders()：扫描过期待支付秒杀订单。
• FlashSaleSer::compensatePaidOrders()：补偿采购单已支付但秒杀单仍待支付。
• FlashSaleSer::compensateClosedOrders()：补偿采购关闭后秒杀码未释放。
• FlashSaleSer::refreshInvalidCarts()：刷新无效购物车。

活动库存口径

秒杀商品展示库存时要区分：

• 服务站本仓库存。
• 指定仓库存。
• 供给仓库存。
• 套包商品的可售数量。
• 活动总数量、锁定数量、已使用数量。
• 是否在服务站黑白名单范围内。
• 商品是否过期、失效或活动是否结束。

与其他模块的关系

• 采购：秒杀提交后创建采购单，支付和关闭依赖采购状态。
• 支付：支付中心回调后推进秒杀状态。
• OA：OPS 活动审批后才可正式启用。
• 库存：列表库存、锁定库存、已用库存同时影响可买数量。
• 导入导出：活动商品 Excel 导入导出使用 PhpSpreadsheet。

排查建议

• 列表能看到但不能加购：查活动时间、服务站范围、商品状态、库存范围和 can_add_cart。
• 加购成功但下单失败：查购物车有效性、库存快照、活动金额限制、采购单创建。
• 支付成功但秒杀单仍待支付：查 PayCenterNotify 是否调用 markPaidByPoOrder，再跑补偿方法。
• 采购关闭但秒杀码没释放：查 SRC_ORDER_TYPE_FLASH_ACTIVITY 和 FlashSaleSer::releaseByPoOrder。
• OPS 活动不能提交：看 submitFlashActivity 返回的冲突商品和审批状态。