13 cloud warehouse process and state machines

云仓业务流程与状态机

本文档把云仓秒杀从“页面玩法”细化为可以进行原型、数据、接口和测试设计的完整业务流程。所有状态均以订单明细和云仓批次为主，不以整张订单笼统判断。

一、业务对象与边界

云仓业务包含两次彼此独立但可追溯的交易：

1. 首次购买：用户在集市云仓抢购并付款，取得对应商品数量的邮寄、自提或代销选择权。
2. 二次零售：用户选择代销后，平台把该批次商品通过 CRMEB 商城真实销售给普通消费用户。

flowchart LR
    A["商户供货或平台自营库存"] --> B["云仓活动商品及 SKU 批次"]
    B --> C["用户首次抢购付款"]
    C --> D["待选择去向"]
    D --> E["邮寄到家"]
    D --> F["线下自提"]
    D --> G["平台代销持仓"]
    G --> H["CRMEB 二次零售订单"]
    H --> I["完成并超过售后观察期"]
    I --> J["批次有效销售进度"]
    J --> K["用户本金与收益结算"]
    B --> L["首次有效购买数量"]
    L --> M["商户供货货款结算"]

Loading

商户货款由首次购买和供货验收决定；用户本金与收益由二次零售进度、结算模式和到期回购决定。两条链路不能互相等待或混算。

二、活动配置规则

1. 活动层配置

配置	说明
活动名称	用户端场次名称
活动开始/结束时间	控制抢购时间
展示时间	可提前预热
支付超时时间	未付款订单释放活动锁定库存
状态	草稿、待发布、未开始、进行中、已结束、已关闭

2. 活动商品层配置

配置	规则
商品来源	平台自营或审核通过的商户供货
商品/SKU	每个参加活动的 SKU 独立形成批次
抢购价	用户首次购买单价
活动库存	从来源库存预占，不与普通可售库存重复销售
每人限购	按用户、活动商品和 SKU 校验
支持邮寄	可选
支持自提	可选
支持代销	V1 必须开启
选择期限	活动结束后 1 至 7 天，默认 3 天
预计销售周期	从代销批次正式开始时间起计算
结算模式	三种模式中只能选择一种
用户收益分成率	作用于批次可分配销售利润
平台收益分成率	与用户分成率共同完成校验
到期回购比例	100%、90%、80% 或自定义，默认 100%
售后观察期	首次交易和二次零售分别配置固定选项
商户结算方式	V1 默认供货价结算

3. 发布前校验

活动商品满足以下条件才允许发布：

• 活动时间、商品、SKU、活动库存、抢购价和限购完整。
• 活动库存不大于已预占且可供履约的来源库存。
• 商户供货 SKU 已完成平台仓入库或等价供货验收，活动数量不大于验收可用数量。
• 至少配置平台代销，邮寄和自提可按商品增加。
• 预计销售周期大于 0。
• 用户收益分成率与平台收益分成率之和等于 100%。
• 自定义回购比例必须大于 0 且不超过 100%。
• 结算模式、回购比例、选择期限和售后观察期已确定。
• 商户供货商品已通过平台审核、完成供货规则确认和实际库存验收。
• 用户端需要展示的规则快照已经生成预览并经运营确认。

三、用户抢购与去向选择

1. 抢购主流程

进入集市云仓
→ 选择活动商品和数量
→ 校验活动状态、限购和库存
→ 创建待付款订单并锁定活动库存
→ 用户支付商品价款
→ 支付成功，订单明细进入“已付款待选择”
→ 用户可继续抢购或离开页面
→ 立即选择，或在活动结束后到订单中心集中选择

首次付款只处理商品价款，不要求地址、配送方式和运费。选择邮寄后再复用 CRMEB 地址与运费模板生成履约信息；需要用户承担运费时创建补运费支付单。

2. 订单明细单一去向

• 每个订单明细的全部数量只能选择邮寄、自提或代销其中一种。
• 同一个商品既要邮寄又要代销时，用户必须分别下单。
• 包邮商品选择邮寄后立即确认；需要补运费时，邮寄去向在补运费成功后才最终确认。
• 补运费支付超时且仍在选择期时退回“已付款待选择”；已经超过选择期限时自动转为平台代销。
• 最终去向确认后不可由用户自行修改。
• 尚未进入发货、核销或代销批次前，客服可通过有审批记录的异常流程撤销原选择并重新选择。
• 不允许使用“一个明细内的提货数量、代销数量”作为正常业务模型。

3. 首次退款边界

• 用户仍处于“已付款待选择”时，可对整个订单明细申请首次退款。
• 用户已选代销但批次尚未冻结时，可对整个订单明细申请退款并撤销待入批次记录。
• 邮寄或自提最终确认后，按 CRMEB 实物订单售后处理，可根据实际履约支持部分数量售后。
• 代销批次已经开始后，不再把持仓撤回为普通首次退款；平台库存、质量或交易异常通过暂停批次、冻结账本、回购或补偿处理。
• 首次退款释放到活动库存还是来源库存，取决于活动是否仍在进行；所有变化必须生成库存流水。

4. 选择时限与提醒

时间点	系统动作
支付成功	展示“立即选择”和“稍后处理”，发送站内提醒
活动结束	订单中心生成待办聚合提醒
截止前 24 小时	再次提醒未选择用户
截止时间	未选择明细自动转为平台代销
自动代销后	记录系统操作、规则快照并通知用户

四、首次购买订单明细状态机

状态码建议	中文状态	进入条件	可执行动作
pending_payment	待付款	抢购下单并锁库存	支付、取消、超时关闭
paid_pending_choice	已付款待选择	支付成功	选择邮寄、自提、代销；申请首次退款
delivery_pending_freight	邮寄待补运费	选择邮寄且需补运费	支付运费、取消临时选择、等待超时处理
delivery_pending_fulfillment	邮寄待履约	地址和运费已确认	等待出库发货
delivery_in_transit	邮寄中	已发货	确认收货、申请售后
pickup_pending	自提待核销	已选择自提	展示核销码、申请售后
pickup_overdue	自提逾期待处理	超过活动配置的自提期限	客服协商继续自提、补邮费改寄或平台回购
consign_pending_batch	代销待入批次	已选择或超时自动代销	等待选择窗口关闭
consigning	代销中	批次冻结并开始代销	查看进度和账本
settling	结算中	达到节点或批次结束	查看结算明细
completed	已完成	邮寄/自提完成，或代销全部结清	查看历史
after_sale	售后中	存在退款或争议	等待处理
closed	已关闭	未支付超时、全额退款或作废	无

状态迁移要求：

• 支付回调、超时关闭、自动代销、批次入仓和结算都必须幂等。
• 每次状态变化记录原状态、新状态、业务事件、操作者、时间和备注。
• 整单状态只做汇总展示，最终判断以订单明细状态为准。
• 自提逾期不会由系统无条件改变商品去向。

五、库存池与数量口径

1. 库存池

库存池	用途
来源库存	平台自营或商户原商品库存
活动预占库存	已划入某云仓活动、暂不可被普通商城重复销售
付款锁定库存	用户已下单未付款，超时后释放
已付款待选择库存	用户已付款但尚未确定去向，已经属于有效购买候选量
邮寄/自提履约库存	已确定由用户直接取得的数量
云仓代销库存	已冻结为用户持仓、等待二次零售的数量
二次零售锁定库存	普通消费订单已下单、尚未成为有效售出的数量
平台回购库存	到期回购后转为平台所有的剩余数量

2. 数量恒等式

活动结束并处理完未支付订单后：

活动预占库存
= 有效付款数量
+ 未抢购退回数量
+ 支付超时释放数量
+ 首次退款退回数量

去向选择冻结后：

有效付款数量
= 邮寄数量
+ 自提数量
+ 代销冻结数量
+ 尚在首次售后处理数量

代销批次经营中：

代销冻结数量
= 有效代销售出数量
+ 二次零售锁定数量
+ 可售剩余数量
+ 售后冻结数量
+ 已回购数量

所有数量变化必须产生库存流水，不能只覆盖汇总字段。

六、云仓批次状态机

每场活动中的每个商品 SKU 形成一个批次。

状态码建议	中文状态	说明
draft	草稿	活动商品尚未发布
reserved	已预占	已从来源库存预占
selling	抢购中	活动进行中
choice_window	去向选择期	活动结束，等待已付款用户选择
consign_ready	待启动代销	选择截止，代销数量已冻结
consigning	代销中	已进入二次零售
matured	已到期	到达预计周期，等待剩余回购和最终核算
buying_back	回购中	正在处理未售商品回购
final_settlement	最终结算中	计算剩余本金、收益和回购款
closed	已关闭	数量、账本和结算全部闭合
suspended	已暂停	库存、质量或运营异常，暂停二次销售
cancelled	已取消	活动发布前或无有效付款时取消

批次可在全部商品提前有效售完并超过二次售后观察期后提前结束；否则在预计到期日进入回购和最终结算。

七、平台实际代销售出的认定

“平台实际代销售出”不是运营手工填写一个数量，而是由真实二次零售订单产生：

平台把云仓批次库存关联到普通商城 SKU
→ 普通消费用户下单
→ 系统按最早到期批次优先锁定库存
→ 订单支付、发货/自提、完成
→ 超过二次零售售后观察期
→ 对应订单明细转为有效代销售出
→ 更新批次累计有效销售数量和金额

V1 认定规则：

• 只自动认定 CRMEB 内真实零售订单，不允许运营直接修改“已售数量”。
• 线下或外部渠道销售暂不自动计入；后续如需支持，必须采用带凭证、审核和不可篡改流水的导入流程。
• 二次零售订单明细必须关联云仓批次、分配数量和分配金额。
• 跨批次销售按预计到期时间最早优先，同到期时间按入库时间最早优先。
• 同一批次不按某个用户先买先卖，而是按用户有效代销数量占比共同分摊累计进度。
• 订单退款、退货或部分退款必须冲减尚未确认的有效销售；已形成结算时生成冲正记录。

八、批次销售进度与金额口径

批次销售进度
= 批次累计有效代销售出数量 ÷ 批次代销冻结数量

计入进度的数量必须已完成二次零售售后观察期。只付款未发货、运输中、售后中和已退款数量均不计入。

批次累计确认销售收入
= 二次零售有效商品实付金额
+ 平台承担的优惠补贴
- 有效退款商品金额

不计入销售收入：

• 用户支付的二次零售运费。
• 平台另外收取的服务费。
• 未完成订单金额。
• 尚在售后观察期内的金额。

批次累计已售本金
= 云仓抢购单价 × 批次累计有效代销售出数量

批次累计可分配销售利润
= max(0, 批次累计确认销售收入 - 批次累计已售本金)

V1 中，平台日常仓储、推广、常规包装、平台券和支付手续费从平台分成中承担，不从上述用户利润基数临时扣除。

九、用户占比与累计应结算公式

用户批次占比
= 用户有效代销数量 ÷ 批次代销冻结数量

用户累计应得销售利润
= 批次累计可分配销售利润
× 用户批次占比
× 用户收益分成率快照

为避免重复支付，每次实际入账都使用累计差额：

本次应结算金额
= 当前累计应结算金额
- 历史已结算金额
- 已生成未完成结算单金额

金额计算使用统一高精度，展示到分；中间节点保留余数，批次最终结算时对最后一笔进行尾差调整，确保批次汇总与用户明细一致。

十、三种结算模式

模式 A：批次结束统一结算

代销期间只展示进度和预计金额，不实际返还本金或收益。

批次全部售完，或到期完成剩余回购后：

最终应付
= 已售商品对应本金
+ 用户累计应得销售利润
+ 未售商品回购款
- 已冲正/冻结金额

适合预计周期短、运营希望一次对账的商品。

模式 B：分期收益，批次结束返本金

销售进度首次达到 25%、50%、75%、100% 时，只结算截至该节点新增的用户收益，本金不提前返还。

批次结束时：

最终应付
= 用户全部已售本金
+ 未结算收益尾差
+ 未售商品回购款
- 已冲正/冻结金额

适合希望用户持续看到收益，但平台需要在周期内保留本金周转的商品。

模式 C：分期本金和收益

销售进度首次达到 25%、50%、75%、100% 时，按累计有效销售结果同步释放本金和收益。

用户累计可返本金
= 用户首次购买代销本金 × 批次销售进度

节点本次返还本金
= 用户累计可返本金 - 历史已返本金 - 已生成未完成返本金

批次到期未售完时，剩余未返本金按回购比例计算回购款。该模式是 V1 默认模式。

节点触发规则

• 进度一次跨越多个节点时，结算到当前已达到的最高节点，不重复生成多份相同累计金额。
• 100% 节点只有在全部数量成为有效代销售出后触发。
• 到期不足 100% 时不伪造 100% 销售节点，直接进入回购和最终结算。
• 所有节点任务必须使用批次、节点和结算类型组成唯一幂等键。

十一、两类未售场景

1. 活动没有抢购完

活动结束后：

1. 关闭新抢购。
2. 等待未支付订单超时并释放锁定量。
3. 扣除已经付款的数量。
4. 剩余数量退回平台自营或商户来源库存。
5. 生成活动库存退回流水。

已付款待选择数量属于用户首次购买，不属于“未抢完库存”。

2. 代销周期内没有卖完

到期后：

1. 停止批次继续参与新二次零售分配。
2. 等待已锁定二次零售订单完成或释放。
3. 统计有效已售、售后冻结和最终未售数量。
4. 按用户持仓占比分配未售数量。
5. 按回购比例计算每个用户的回购款。
6. 平台支付或记入用户余额后取得该部分商品所有权。
7. 回购库存进入平台库存，不再给原用户产生后续收益。
8. 完成尾差、冲正和最终结算后关闭批次。

用户未售回购款
= 用户最终未售数量
× 用户云仓抢购单价
× 回购比例快照

十二、商户供货结算

商户云仓供货与用户二次代销收益分开核算。

V1 默认供货价模式：

商户有效首次购买数量
= 用户已付款数量
- 首次交易已退款数量
- 供货验收不合格数量

商户应结算货款
= 商户供货价 × 商户有效首次购买数量
- 商户承担的首次交易退款
- 已确认由商户承担的履约扣减

进入待结算需同时满足：

• 用户首次购买已经完成：邮寄为确认/自动收货，自提为核销，代销为持仓进入正式批次。
• 商品已完成云仓入库或约定供货验收。
• 首次交易售后观察期已结束。
• 不存在退款、质量争议或财务冻结。

用户选择邮寄、自提或代销，不改变商户首次供货货款的基础。后续二次零售是否售完，也不作为拖延商户货款的条件。

十三、亏损与异常边界

可能造成经营亏损的场景包括二次售价过低、平台优惠、仓储推广成本、退货赔付、损耗和折扣回购。

V1 处理原则：

• 二次售价低于用户抢购成本时，差额由平台补足后再计入批次收入。
• 平台券、平台补贴不降低批次确认销售收入。
• 常规仓储、包装、推广和支付成本从平台分成承担。
• 仓储损坏、盘亏和非用户原因质量问题不向用户账本追加负数。
• 用户可能承担的本金差额仅来自活动下单前明确展示并快照的折扣回购比例。
• 售后冲正优先冲减未结算金额；不足部分进入冻结和人工审核，不直接形成用户欠款。
• 批次存在质量或库存争议时先暂停销售和结算，保留完整事件与审批记录。

十四、关键验收场景

编号	场景	预期结果
CW-AT-001	用户付款后不选择并继续抢购	首笔订单保持待选择，不影响后续抢购
CW-AT-002	活动结束后用户集中选择	订单中心可逐笔选择，每个明细只能选一种方式
CW-AT-003	用户超期未选择	系统幂等转为代销并记录通知和操作日志
CW-AT-004	邮寄需用户承担运费	选择邮寄后计算并补付运费，首次商品订单金额不被改写
CW-AT-004A	补运费订单超时且仍在选择期	邮寄未最终生效，订单明细回到待选择
CW-AT-004B	补运费订单超时且已过选择期	订单明细自动转为代销且只执行一次
CW-AT-005	未支付订单超时	活动锁定库存释放，订单关闭
CW-AT-006	活动未抢完	未付款处理完后剩余库存退回来源库存
CW-AT-007	多批次同时可售	二次零售按最早到期批次分配
CW-AT-008	二次订单刚付款	不计入有效销售进度和用户结算
CW-AT-009	二次订单完成并过售后期	更新批次进度并检查结算节点
CW-AT-010	进度从 20% 跳到 55%	结算至 50% 累计目标，25% 不重复结算
CW-AT-011	到期只售出 70%	不生成 100% 销售节点，剩余 30% 进入回购
CW-AT-012	二次零售使用平台券	平台承担优惠，用户利润基数不被券额冲减
CW-AT-013	商户商品后续滞销	商户已按有效首次购买结算，不等待二次售完
CW-AT-014	已结算销售后来发生异常退款	生成冲正或冻结记录，不删除原账本
CW-AT-015	重复收到支付/定时任务事件	不重复扣库存、入批次或生成账本
CW-AT-016	待选择时申请退款	整个订单明细退款，库存按活动状态正确退回
CW-AT-017	代销批次开始后申请普通首次退款	拒绝非法状态迁移，并引导进入对应异常处理
CW-AT-018	自提逾期	进入异常待处理，不静默改为邮寄或代销

十五、关联文档

• 08-v1-settlement-policy.md
• 09-cloud-warehouse-seckill.md
• 12-v1-business-decisions-and-glossary.md
• 15-v1-data-model-draft.md