活动、秒杀与营销链路

1. 业务目标与边界

活动域负责“运营配置营销规则，服务站按规则购买，最终转成可支付和履约的业务单据”。代码中包含普通销售活动、赠品活动、客户活动、优惠券、预售和秒杀等能力。本篇以当前代码最完整的秒杀链路为主，说明：

• OPS 创建、编辑、导入活动商品、配置服务站范围、提交 OA、审批和提前结束。
• 服务站查看商品、加购物车、确认订单、提交订单和主动取消。
• 秒杀订单怎样转换为采购单，支付回调怎样确认占用量。
• 待支付超时、采购关闭、回调丢失时怎样释放或补偿。

本篇不展开普通销售活动、赠品和优惠券的全部字段；这些能力与秒杀共处活动域，但拥有各自的 Service、模型和状态，不能直接套用秒杀状态。

2. 参与角色与前置条件

3. 代码入口地图

已确认：接口方法和参数来自当前 Controller、Request Entry 和 Service。真实 HTTP 前缀会受网关、环境和 CodeIgniter 路由影响，联调时应从浏览器 Network 或环境路由确认，不能把类路径直接当成固定公网 URL。

4. OPS 接口与请求

4.1 OPS 接口总表

4.2 保存活动请求示例

下面是 Controller 可以识别的结构示例，金额按当前秒杀活动代码以分存储，展示时再格式化为元；fixed_price 的前端具体传值需继续与当前 OPS 页面 Network 核对。

{
  "activity": {
    "id": 0,
    "name": "暑期轮胎秒杀",
    "start_time": "2026-07-20 09:00:00",
    "end_time": "2026-07-20 18:00:00",
    "activity_type": 2,
    "stock_scope": 2,
    "remark": "示例活动"
  },
  "goodsList": [
    {
      "goods_id": 10001,
      "package_group_no": "PKG-001",
      "wms_location_no": "WH001",
      "wms_location_name": "示例仓",
      "qty": 4,
      "price_mode": 1,
      "fixed_price": 19900,
      "discount_rate": 0,
      "date_calc_mode": 2,
      "backward_from": 90,
      "backward_to": 30,
      "sort": 10
    }
  ]
}

关键字段：

4.3 服务站范围请求示例

{
  "activity_id": 100,
  "type": 2,
  "stations": [
    {"sid": 20001, "station_name": "示例服务站"},
    {"sid": 20002, "station_name": "另一服务站"}
  ],
  "page": 1,
  "pageSize": 20
}

• type=1 是黑名单，type=2 是白名单。
• 保存兼容 stations、stationList、station_list、sids、单个 sid。
• 删除兼容名单记录 ids 或服务站 sids，并限制在活动和名单类型内软删。

4.4 提交 OA 请求和分支

{
  "activity_id": 100,
  "is_oa": 1
}

• is_oa=1：构造 OA payload，外部提交成功后把活动更新为审批中并保存 oa_no。
• is_oa=0：必须传 oa_no，按人工确认路径直接置审批通过。
• 提交前会检查商品明细、活动配置和跨活动冲突。
• 有冲突时不是成功提交，返回 can_submit=0、conflict_count、conflictList 和可展示消息。

5. OPS 创建到 OA 生效流程

flowchart TD
    A[OPS 新建或编辑活动] --> B[saveFlashActivity]
    B --> C{活动/时间/商品/价格校验}
    C -- 失败 --> X[返回明确校验错误 不落有效配置]
    C -- 通过 --> D[保存活动主表和商品快照]
    D --> E[配置黑名单或白名单]
    E --> F[submitFlashActivity]
    F --> G{跨活动商品冲突}
    G -- 有冲突 --> H[返回 conflictList 调整后重提]
    G -- 无冲突 --> I{是否走 OA}
    I -- 否 --> J[校验 oa_no 并直接置通过]
    I -- 是 --> K[FlashActivityOaProvider 提交 OA]
    K --> L[活动置审批中 保存 oa_no]
    L --> M[OaNotify 消费 oa_audiat]
    M --> N{审批结果}
    N -- 通过 --> O[审批通过 按活动时间决定启用状态]
    N -- 驳回 --> P[审批驳回 记录 reject_reason]
    O --> Q[同步活动商品状态 服务站可按规则展示]

5.1 OA 系统时序

sequenceDiagram
    participant OPS as OPS 前端
    participant C as FlashActivity Controller
    participant S as FlashActivitySer
    participant DB as MySQL 活动表
    participant OA as OA Provider
    participant MQ as OA MQ
    participant T as OaNotify

    OPS->>C: submitFlashActivity(activity_id,is_oa)
    C->>S: submitFlashActivity(requestData,apiUserHeader)
    S->>DB: 读取活动和商品 校验冲突
    alt 存在冲突
        S-->>OPS: can_submit=0 + conflictList
    else 提交 OA
        S->>OA: submit(template payload)
        OA-->>S: oa_no/requestId
        S->>DB: apply_status=1, oa_status=1
        S-->>OPS: activity_id + oa_no
        OA-->>MQ: oa_audiat(templateCode,status,summaryId)
        MQ->>T: consume
        T->>S: callback20260526(messageData)
        S->>DB: 审批通过或驳回并同步商品状态
    end

6. 服务站接口与请求

PC Controller 和移动商城 Controller 最终都调用 FlashSaleSer，业务口径应保持一致；PC 额外提供 checkAccess。

登录上下文由 Controller 注入或透传：JXCSID/sid 表示服务站，JXCUID 表示用户，JXCUNAME 表示用户名。业务请求不应允许前端用任意 sid 越权读取其他服务站数据。

6.1 加购请求

{
  "activity_goods_id": 30001,
  "qty": 4,
  "packSpecType": 1
}

• qty 最小为 1。
• packSpecType 兼容 pack_spec_type，服务端会换算成基础数量。
• 单品允许加购；套包不进购物车，必须立即购买。
• 同服务站、同活动商品执行 upsert，不重复生成多行购物车。

6.2 批量更新购物车

{
  "items": [
    {"activity_goods_id": 30001, "qty": 8, "selected": 1},
    {"activity_goods_id": 30002, "deleted": 1}
  ]
}

服务端在事务中逐行处理：数量小于等于 0 或 deleted=1 进入删除；改数量时重新校验商品可见性、采购限制和实时库存；只改 selected 时不重算数量。任一行抛错会回滚本次批量修改。

6.3 购物车确认和提交

{
  "source_type": 2,
  "activity_goods": [
    {"activity_goods_id": 30001, "qty": 8},
    {"activity_goods_id": 30002, "qty": 4}
  ]
}

• source_type=1 为立即购买，2 为购物车。
• 购物车未传 activity_goods 时，默认取当前勾选且有效的行。
• activity_goods 可传 JSON 数组，也兼容 JSON 字符串；每行必须有活动商品 ID 和正数量。
• 单品必须先进入购物车；套包立即购买可传 activity_id 和购买套数 qty。
• 确认页只读计算，提交时会再次加行锁并重新校验，不能依赖确认页库存快照。

6.4 套包立即购买

{
  "source_type": 1,
  "activity_id": 100,
  "qty": 1
}

服务端加载套包全部可见明细，将“套数 × 每行配置数量”展开为采购明细数量。当前常量 PACKAGE_PURCHASE_LIMIT=1，套包购买限制和每行可售量还会结合活动商品锁定量、已使用量及供给库存判断。

7. 服务站购买主流程

flowchart TD
    A[服务站进入秒杀专区] --> B[按审批/启用/时间/名单筛选活动]
    B --> C[加载物料 价格 本站库存 在途库存 供给仓库存]
    C --> D{单品还是套包}
    D -- 单品 --> E[查询可购量和包装后加入购物车]
    E --> F[购物车实时刷新有效性和金额门槛]
    F --> G[orderPreview]
    D -- 套包 --> H[直接购买 展开套包明细]
    H --> G
    G --> I{实时校验是否通过}
    I -- 否 --> X[返回库存/状态/金额/权限错误]
    I -- 是 --> J[submitOrder 开启事务]
    J --> K[FOR UPDATE 锁活动商品行]
    K --> L[写秒杀主单和明细]
    L --> M[增加 locked_qty]
    M --> N[创建并提交秒杀来源采购单]
    N --> O{采购单创建成功}
    O -- 否 --> P[事务回滚 秒杀单/锁量/采购草稿不得残留]
    O -- 是 --> Q[删除已结算购物车并提交事务]
    Q --> R[返回秒杀单详情和 po_order_ids]

8. 下单、支付和关闭时序

sequenceDiagram
    participant U as 服务站
    participant C as FlashSale Controller
    participant S as FlashSaleSer
    participant FDB as 秒杀表
    participant PO as 采购域
    participant PDB as 采购表
    participant PAY as 支付中心
    participant CB as PayCenterNotify

    U->>C: submitOrder(source_type,activity_goods)
    C->>S: submitOrder(登录上下文+请求)
    S->>FDB: BEGIN + 锁 t_flash_activity_goods
    S->>FDB: 新增 flash_order/detail
    S->>FDB: 已锁数量增加本次订单数量
    S->>PO: savePoOrder + InvPoFactory::saveOrder
    PO->>PDB: 新增并提交待支付采购单
    alt 采购创建失败
        S->>FDB: ROLLBACK
        S-->>U: 返回提交失败
    else 创建成功
        S->>FDB: 删除已结算购物车 + COMMIT
        S-->>U: 秒杀订单 + po_order_ids
        U->>PAY: 支付采购单
        PAY-->>CB: 支付结果回调
        CB->>PDB: 写付款/明细并推进采购状态
        CB->>S: markPaidByPoOrder
        S->>FDB: 已锁数量减少，已用数量增加
        S->>FDB: flash_order=已支付
    end

关闭路径：

• 待支付主动取消：cancelOrder 找关联采购单；待支付采购单由 PoOrderSer::cancelWaitPayOrder 关闭并触发释放。
• 秒杀单没有关联采购单：秒杀域直接锁订单并释放 locked_qty。
• 采购待支付超时：expireWaitPayOrders 关闭采购单或直接释放，并把秒杀单置已关闭。
• 采购未发货关闭：PoOrderSer/InvPoService 调用 releaseByPoCloseItems，按关闭明细释放已占用数量。
• 支付成功但状态未同步：compensatePaidOrders 根据采购状态补调 markPaidByPoOrder。

9. 状态机

9.1 活动状态

活动有三组相关状态，页面不能只看一个字段：

页面状态还依赖当前时间：只有审批通过、启用、start_time <= now <= end_time 才是进行中。

stateDiagram-v2
    [*] --> 草稿
    草稿 --> 审批中: submitFlashActivity
    审批中 --> 审批通过: OA PASS
    审批中 --> 审批驳回: OA REJECT
    审批驳回 --> 草稿: convertFlashActivityToDraft
    审批通过 --> 未开始: 当前时间早于开始时间
    审批通过 --> 进行中: 启用且进入活动时间
    未开始 --> 进行中: 到达开始时间
    进行中 --> 已结束: 到达结束时间
    未开始 --> 提前结束: endFlashActivity
    进行中 --> 提前结束: endFlashActivity
    已结束 --> [*]
    提前结束 --> [*]

9.2 秒杀订单状态

stateDiagram-v2
    [*] --> 待支付: submitOrder 创建成功
    待支付 --> 已支付: 支付回调或支付补偿
    待支付 --> 已取消: 用户主动取消
    待支付 --> 已关闭: 支付超时或采购关闭
    已支付 --> 已关闭: 采购未发货关闭并按明细释放
    已支付 --> [*]
    已取消 --> [*]
    已关闭 --> [*]

代码常量还保留 0=已创建，但 submitOrder 当前直接写入 1=待支付。维护旧数据时不能把 0 当作当前主流程必经状态。

10. 单号与数据关系

erDiagram
    FLASH_ACTIVITY ||--o{ FLASH_ACTIVITY_GOODS : activity_id
    FLASH_ACTIVITY ||--o{ FLASH_ACTIVITY_STATION_SCOPE : activity_id
    FLASH_ACTIVITY ||--o{ FLASH_CART : activity_id
    FLASH_ACTIVITY ||--o{ FLASH_ORDER : activity_id
    FLASH_ORDER ||--|{ FLASH_ORDER_DETAIL : order_id
    FLASH_ACTIVITY_GOODS ||--o{ FLASH_CART : activity_goods_id
    FLASH_ACTIVITY_GOODS ||--o{ FLASH_ORDER_DETAIL : activity_goods_id
    FLASH_ORDER ||--o{ SCM_PO_ORDER : srcOrderId_srcOrderNo
    SCM_PO_ORDER ||--|{ SCM_PO_ORDER_INFO : orderId

秒杀单到采购单的定位关系：

不能只用 srcOrderId 跨服务站查单，排查和业务更新至少同时带 sid，有条件时再带 srcOrderNo。

11. 核心表读写矩阵

12. 数量、库存和金额口径

12.1 活动数量

• locked_qty：待支付秒杀订单已经锁住、尚未确认支付的基础数量。
• used_qty：支付成功后确认占用的基础数量。
• 支付成功：同一事务语义内执行 locked_qty -= qty、used_qty += qty。
• 待支付取消/超时：释放 locked_qty，不得增加 used_qty。
• 已支付采购关闭：按关闭明细和 closed_qty 释放，避免重复关闭多次扣减。

当前 availableQty() 的代码口径：

• 单品活动返回不受活动数量上限限制的极大值，最终仍受实时供给库存、采购限制等校验。
• 套包单行可售基础数量为 max(0, 行配置数量 × 套包购买限制 - locked_qty - used_qty)。
• 套包整体可买套数还要取所有明细按配比折算后的最小值，并受供给仓库存约束。

因此排查“页面有库存但不能下单”时，不能只查 qty-locked_qty-used_qty；必须同时看活动类型、套包配比、仓库、供给库存、本站库存、在途、最小采购量和金额门槛。

12.2 金额

• 秒杀 Service 内部通过 amountToCent() 和 formatCent() 在元展示值与分存储值之间转换。
• t_flash_order.total_amount/origin_amount/discount_amount 是提交时的订单快照。
• 一口价直接取活动价格；折扣价按服务站采购原价和折扣计算。
• 确认页和提交都会计算金额，提交结果以加锁后重新计算为准。
• 前端传入金额不能作为落库依据；价格、优惠和金额限制由服务端重算。

13. 事务、并发与幂等

高风险边界：submitOrder 在同一数据库连接事务内调用采购保存流程。若后续把采购拆成远程服务，现有数据库事务不能覆盖远程成功/失败，必须重新设计幂等键、状态中间态和补偿。

14. 自动任务和补偿

CLI 入口都在 application/controllers/tasks/FlashSaleTask.php：

执行原则：

1. 先用只读 SQL 确定异常集合和影响数量。
2. 小 limit 执行单项任务，保留任务日志和返回 JSON。
3. 再查秒杀单、采购单、locked_qty/used_qty/closed_qty 是否符合预期。
4. 不要在生产直接手改三个数量字段；手改会绕过订单明细和幂等保护。

15. 按单号排查 SOP

15.1 从秒杀单查采购单

以下 SQL 使用占位符，默认只读；分表或字段大小写以当前环境为准。

SELECT id, bill_no, activity_id, sid, source_type, order_status,
       total_amount, origin_amount, discount_amount, expired_at,
       cancel_reason, create_time, modify_time
FROM t_flash_order
WHERE sid = :sid AND bill_no = :flash_bill_no;

SELECT id, order_id, activity_goods_id, sku_id, inv_id, qty,
       total_amount, closed_qty
FROM t_flash_order_detail
WHERE order_id = :flash_order_id
ORDER BY id;

SELECT id, billNo, sid, billStatus, orderType,
       srcOrderType, srcOrderId, srcOrderNo, paymentTime, modifyTime
FROM t_scm_po_order
WHERE sid = :sid
  AND srcOrderType = 13
  AND srcOrderId = :flash_order_id
  AND srcOrderNo = :flash_bill_no;

判断顺序：

1. 查不到秒杀单：确认提交请求是否真正成功，按服务站、时间和日志继续找。
2. 有秒杀单无采购单：重点查 submitOrder 事务异常和采购创建返回；正常情况下应整体回滚。
3. 秒杀待支付、采购已支付后状态：检查支付回调日志，必要时评估 compensatePaidOrders。
4. 秒杀取消/关闭但 locked_qty 未下降：查采购关闭路径和释放异常。

15.2 核对锁定量和已用量

SELECT g.id, g.activity_id, g.sku_id, g.qty,
       g.locked_qty, g.used_qty, g.status, g.version,
       d.order_id, d.qty AS order_qty, d.closed_qty
FROM t_flash_activity_goods g
LEFT JOIN t_flash_order_detail d ON d.activity_goods_id = g.id
WHERE g.id IN (:activity_goods_ids)
ORDER BY g.id, d.order_id;

核对规则：

• 待支付未取消的订单明细应贡献 locked_qty。
• 已支付且未关闭的订单明细应贡献 used_qty。
• 已取消/已关闭数量不应继续完整占用。
• 汇总差异时要考虑历史数据、部分关闭和同一活动商品的其他订单，不能只拿一个订单明细与总字段直接相等比较。

15.3 代码和日志定位

rg -n "function submitOrder|function cancelOrder|function markPaidByPoOrder" \
  application/Services/Activity application/controllers

rg -n "SRC_ORDER_TYPE_FLASH_ACTIVITY|ORDERTYPE_FLASH_ORDER" application

rg -n "秒杀订单提交失败|秒杀商品锁定数量不足|秒杀待支付超时释放|支付消息通知失败" \
  application storage logs

常用日志分类：FlashSaleTask 的任务方法名、PayCenterNotify 的支付处理日志、OA 消费的 OaNotify/oaAudit。实际日志目录和容器路径见本知识库的本地联调与日志专题。

16. 常见故障决策表

17. 改动风险与回归清单

17.1 高风险改动

• 修改 availableQty、套包数量换算、供给库存选择：可能造成超卖或错误拦截。
• 修改 submitOrder 事务顺序：可能产生无采购单秒杀单、锁量泄漏或重复采购单。
• 修改采购来源字段：会让支付、取消、详情和补偿无法关联秒杀单。
• 修改支付回调事务：可能出现采购已支付但秒杀未转已用。
• 修改关闭释放：可能重复释放、负数或已支付数量长期占用。
• 修改活动审批和启用状态：可能让未审批活动提前对服务站可见。

17.2 最小回归集

• OPS 新增单品草稿、编辑、导入后保存、提交 OA、OA 通过、驳回转草稿。
• OPS 新增套包、指定仓、生产日期规则、白名单、提前结束。
• 跨活动同商品冲突能返回完整冲突清单。
• 无权限/不在名单/未开始/已结束服务站不能看到或购买。
• 单品加购、包装换算、改量、勾选、批量删除、历史购物车失效。
• 套包不能加购物车，只能立即购买；套数展开数量正确。
• 确认页金额、仓库、商品明细和提交结果一致。
• 两个并发请求抢最后库存，不产生超卖或重复采购单。
• 支付成功、重复支付回调、支付超时、主动取消均保持状态和数量一致。
• 采购部分/全部关闭后 closed_qty、locked_qty、used_qty 正确。
• 三项单独补偿和 runCompensate 可重复运行且不重复扣减。
• PC 和移动商城对同一活动返回的业务口径一致。

18. 证据索引与待验证项

已由代码确认

• OPS 请求归一：application/Entries/Activity/FlashActivitySaveRequestEntry.php、FlashActivityActionRequestEntry.php、FlashActivityStationScopeRequestEntry.php。
• OPS/OA：application/Services/Activity/FlashActivitySer.php::submitFlashActivity()、callback20260526()。
• 服务站接口：application/Services/Activity/FlashSaleSer.php::goodsList() 至 cancelOrder()。
• 提交和采购关联：FlashSaleSer::submitOrder()、createPoOrdersForFlashOrder()。
• 支付和释放：markPaidByPoOrder()、releaseByPoOrder()、releaseByPoCloseItems()。
• 支付回调：application/controllers/tasks/PayCenterNotify.php。
• OA 消费：application/controllers/tasks/OaNotify.php。
• 补偿：application/controllers/tasks/FlashSaleTask.php。
• 状态：application/KzData/Enums/FlashActivityEnums.php、PoOrderEnums.php。
• 物理表名：application/config/tables.php。

待环境联调确认

• 各环境真实 HTTP URL 前缀、网关鉴权头和 OPS 用户头格式。
• OPS 页面传入 fixed_price/discount_rate 的最终单位与页面转换位置。
• OA Provider 的超时、重试和外部幂等保证。
• 定时任务在各环境的 crontab/调度频率和告警接收人。
• 真实供给库存服务的降级策略、缓存时效和超时行为。

这些待验证项不影响理解当前代码主链路，但上线联调前必须逐项确认并回填本文。

请求-日志-数据变更追踪卡

多入口请求链路

日志证据矩阵

环节数据变更台账

子模块级独立追踪

子模块追踪：flash-config 秒杀活动配置

子模块追踪：flash-oa OA 提交与审批回调

子模块追踪：flash-scope 服务站范围与商品可见性

子模块追踪：flash-cart 购物车与原子锁量

子模块追踪：flash-preview 订单预览与价格库存复核

子模块追踪：flash-submit 秒杀下单与转采购

子模块追踪：flash-pay 秒杀支付与锁量转已用

子模块追踪：flash-release 取消、关闭与数量释放

子模块追踪：flash-compensate 超时与补偿任务