销售、出库、配送与收款

1. 业务目标与边界

销售域负责服务站向维修厂、E站用户、移动商城客户、APP/机器人客户和外部 ERP 客户销售商品。完整链路不是一张“销售表”，而是三类业务事实：

1. 销售订单：客户要什么、数量和价格是多少，尚未必然扣库存。
2. 销售出库单：实际从哪个仓库/货位出了多少货，是扣库存和履约的事实。
3. 销售退货单：客户退回了什么，是库存增加和财务冲回的反向事实。

出库之后还会进入配送、自提、送达、对账、核销、撤销和下游同步。本文把这些状态、表、接口和数据变化分开说明。

2. 最容易混淆的入口

当前 InvSa.php 中的方法名带有明显历史包袱：

阅读代码或排查时，必须先确认当前单号属于 t_scm_sa_order、t_scm_sa_invoice 还是销售退货交易，再进入对应方法。

3. 参与角色和前置条件

4. 代码入口地图

5. PC 接口总表

5.1 销售订单

5.2 销售出库和履约

5.3 销售退货

6. App 接口 code

App code 只表示协议映射。鉴权、签名、网关 URL 和统一 request envelope 需在 API 字典中按环境补齐。

7. 销售订单请求与主流程

7.1 请求结构示例

{
  "postData": "{\"buId\":20001,\"billNo\":\"SO-EXAMPLE\",\"sourceType\":0,\"payType\":0,\"description\":\"门店销售\",\"entries\":[{\"invId\":10001,\"skuId\":\"SKU-001\",\"qty\":4,\"price\":199.00}]}"
}

示例只表达业务结构，具体字段和金额单位必须以当前页面 Network、InvSaService 校验和模型为准。服务端会从会话加入 sid/uid/userName，不应接受前端跨服务站指定。

核心字段：

7.2 创建流程

flowchart TD
    A[PC/APP/E站/SAAS/机器人发起销售] --> B[识别 order_scene/sourceType]
    B --> C[校验登录服务站 客户 商品 数量 价格 支付方式]
    C --> D{重复 SKU/客户/规则是否通过}
    D -- 否 --> X[返回校验错误]
    D -- 是 --> E[saOrderMainFields 映射来源和支付口径]
    E --> F[写销售订单主表]
    F --> G[写销售订单明细和扩展快照]
    G --> H{是否立即出库}
    H -- 否 --> I[销售单状态=待出库]
    H -- 是 --> J[进入出库流程]
    I --> K[SyncOrderSer 同步销售创建/更新]
    J --> K

SaOrderSer::saOrderMainFields() 是来源理解的关键：它把 E站商城、维修、活动、E站 APP IM/商城/活动和机器人等场景映射为 DGJ2 的 sourceType/payType/is_pay。不要由页面展示名称反推来源值。

8. 销售来源和支付口径

历史保留值 2、5、6、7、11、12、13 仍可能存在数据库中。新增逻辑不要删除旧枚举，否则列表、报表和消息反序列化会失去解释能力。

9. 销售出库请求与流程

9.1 请求结构示例

{
  "postData": "{\"id\":30001,\"buId\":20001,\"billNo_type\":0,\"entries\":[{\"saOrderInfoId\":40001,\"invId\":10001,\"skuId\":\"SKU-001\",\"qty\":4,\"locationId\":101,\"locationAreaId\":1001}]}"
}

出库的真实依据不是销售订单页面数量，而是每行剩余可出数量和当前货位实时库存。Controller 还会：

• 对微仓铺货校验客户已绑定微仓、仓库是可用移动仓。
• 判断销售单是否已有 SAAS 关联，决定 enableSync。
• 从报价关系补充每个商品的 saOfferBillNo。
• 使用 sid + 销售订单ID Redis 锁降低重复出库。

9.2 主流程

flowchart TD
    A[选择待出库销售单] --> B[读取每行销售量 已出库量 已关闭量]
    B --> C[选择仓库 货位 出库数量]
    C --> D[校验货位有效和实时库存]
    D --> E{数量是否超过剩余可出或库存}
    E -- 是 --> X[拒绝出库]
    E -- 否 --> F[Redis 锁销售订单]
    F --> G[事务新增销售出库主表]
    G --> H[新增出库明细和快照]
    H --> I[InventorySer 写销售出库流水]
    I --> J[扣减货位和实时库存]
    J --> K[更新销售订单明细已出库量]
    K --> L{订单剩余数量}
    L -- 全部出库 --> M[销售订单=已完成]
    L -- 仍有未出 --> N[销售订单=部分出库]
    M --> O[创建配送/自提并同步下游]
    N --> O

10. 出库系统时序

sequenceDiagram
    participant U as 服务站
    participant C as InvSa Controller
    participant S as InvSaService/SaOrderSer
    participant DB as 销售数据库
    participant INV as InventorySer
    participant MQ as dgj_notify/MQ
    participant D as 配送中心/TMS
    participant DOWN as SAAS/E站/APP

    U->>C: addOutBound(postData)
    C->>S: addOutBound(登录上下文+enableSync)
    S->>DB: 锁/读取销售单和剩余数量
    S->>INV: 保存销售出库库存事务
    INV->>DB: 新增 inventory/info 并扣实时库存
    S->>DB: 新增 sa_invoice/info 更新 sa_order
    S->>D: 创建配送或自提关系
    S->>MQ: syncOutboundCreate / sendSaOrderOutToMq
    MQ-->>DOWN: dgj_notify 出库创建事件
    S-->>U: 出库单 ID/单号和状态
    D-->>C: 配送出库/物流/自提回调
    C->>DB: 更新出库履约状态
    C->>MQ: 同步状态到下游

11. 两套状态机

11.1 销售订单状态

stateDiagram-v2
    [*] --> 待出库: 创建销售订单
    待出库 --> 部分出库: 部分数量出库
    待出库 --> 已完成: 一次全部出库
    部分出库 --> 已完成: 剩余数量全部出库
    待出库 --> 已关闭: 关闭全部未出数量
    部分出库 --> 已关闭: 结单/关闭剩余数量
    已完成 --> [*]
    已关闭 --> [*]

11.2 销售出库单状态

stateDiagram-v2
    [*] --> 已出库: 出库成功
    已出库 --> 派送中: 配送接单/发车
    已出库 --> 已送达: 自提确认或直接送达
    派送中 --> 已送达: 配送完成
    已送达 --> 已对账: reconciliation
    已对账 --> 已送达: cancelReconciliation
    已对账 --> 已核销: 收款核销完成
    已出库 --> 已撤销: cancel 满足条件
    已撤销 --> [*]
    已核销 --> [*]

出库单状态不等于收款状态。已送达 可以仍未收款，已对账 也不必然全部核销。

12. 配送、自提和三方履约

DispatchCenterNotify 处理的关键回调：

三方配送至少涉及：

• t_scm_third_party_delivery_order：三方配送业务单。
• t_sa_invoice_delivery_relation：销售出库单和配送单关系。
• 出库单自身履约状态。
• 外部配送单号、轨迹和回调状态。

排查“已送达但页面仍派送中”时，要先确认回调有没有命中正确的出库单关系，而不是直接改出库状态。

13. 对账、收款和核销

13.1 三个独立维度

13.2 收款方式

• 0 挂账：形成客户应收，后续对账和收款核销。
• 1 现金：开单/出库时按业务规则形成现金收款。
• 2 微信：依赖外部支付结果或来源系统已支付口径。

13.3 对账流程

flowchart TD
    A[已送达/可对账出库单] --> B[选择单据或批量 ids]
    B --> C[校验出库状态 客户 金额和权限]
    C --> D[reconciliation/batchReconciliation]
    D --> E[出库单状态=已对账]
    E --> F{是否已足额收款/满足自动核销}
    F -- 否 --> G[保留未收或部分收款]
    F -- 是 --> H[写/关联收款分录]
    H --> I[收款状态=全部 出库单=已核销]
    E --> J[cancelReconciliation]
    J --> K[满足条件时回退对账状态]

对账不是简单改一个 billStatus。批量对账、自动对账和撤销对账需要核对付款金额、差额、客户、已核销记录及是否已进入不可逆财务流程。

14. 销售退货和出库撤销

14.1 销售退货

InvSa::add() 实际创建销售退货：

1. 校验 SA_ADD 权限。
2. 解析 postData。
3. 校验结算方式 wayId 未禁用。
4. 校验每个 locationAreaId 货位未删除。
5. 校验结算账户 accId 未禁用。
6. 从登录态注入 sid/uid/userName。
7. InvSaFactory('NormalSaleReturn')->addInvoice 创建销退单。
8. 将客户登记进需要生成对账单的用户集合。

销售退货交易类型通常是 150602，库存方向为增加；普通销售出库交易类型是 150601，方向为减少。历史撤销单可能仍以销售出库类型配合 billStatus=6 展示为销售退货效果，报表必须兼容。

14.2 出库撤销

sequenceDiagram
    participant U as 操作人
    participant C as InvSa::cancel
    participant F as NormalSale Factory
    participant INV as 库存域
    participant TMS as TransportSer
    participant SYNC as SyncOrderSer

    U->>C: cancel(id,reason)
    C->>C: 权限+参数+Redis锁
    C->>F: deleteInvoice(id,pageData)
    F->>INV: 生成反向库存/销退事实
    F-->>C: 原出库单和反向单结果
    C->>TMS: transportDelete(出库单撤销)
    C->>SYNC: syncOutboundCancel
    C-->>U: 撤销成功和业务 ID

来源为 ORDER_SOURCE_TYPE_KW 的出库撤销不走同样的下游同步条件。已配送、已对账或已核销的单据是否允许撤销，必须由 Service 状态校验决定，不能只依赖按钮是否显示。

15. 下游同步事件

SyncOrderSer 使用 destination dgj_notify 发送销售域事件：

MqSer 还提供 sendSaOrderOutToMq、sendSaOrderStatusToMq、sendSaOrderStatusToSass 等发送方法。维护时先查实际调用方和路由键，避免同一动作重复发两套消息。

16. 核心表读写矩阵

17. 数据关系图

erDiagram
    SCM_SA_ORDER ||--|{ SCM_SA_ORDER_INFO : order_id
    SCM_SA_ORDER_INFO ||--o| SCM_SA_ORDER_INFO_EXT : order_info_id
    SCM_SA_ORDER ||--o{ SCM_SA_INVOICE : source_order
    SCM_SA_INVOICE ||--|{ SCM_SA_INVOICE_INFO : invoice_id
    SCM_SA_INVOICE_INFO ||--o| SCM_SA_INVOICE_INFO_EXT : invoice_info_id
    SCM_SA_INVOICE ||--o{ DELIVERY_RELATION : invoice_id
    THIRD_DELIVERY_ORDER ||--o{ DELIVERY_RELATION : delivery_id
    SCM_SA_INVOICE ||--o{ SCM_PAYMENT_INFO : settlement_order
    SCM_PAYMENT ||--|{ SCM_PAYMENT_INFO : payment_id
    SCM_SA_INVOICE ||--o{ SCM_INVENTORY : source_order
    SCM_INVENTORY ||--|{ SCM_INVENTORY_INFO : inventory_id

业务追踪键至少包括 sid、销售订单 ID/单号、出库单 ID/单号、原订单明细 ID、来源类型和来源单号。不要只按数字 ID 跨服务站关联。

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

18.1 数量

对每个销售订单明细：

剩余可出数量 = 销售数量 - 已出库有效数量 - 已关闭数量

实际字段和历史撤销口径以 Service 为准。撤销出库不能继续计入有效已出库量；销售退货是新的反向事实，不等价于恢复原销售订单“未出库量”。

18.2 库存

• 销售出库：交易类型 150601，从指定仓库/货位扣减实时库存。
• 销售退货：交易类型 150602，退回指定仓库/货位并增加库存。
• 撤销出库：通常生成反向库存事实或销退效果，不能删除原库存流水抹掉审计。
• 列表库存、货位库存和报表库存可能来自不同数据源，排查时核对来源时间。

18.3 金额

• 销售订单是客户承诺和价格快照，出库单是实际履约金额事实。
• 折扣、赠品、报价单、历史售价和客户价可能影响每行金额。
• 收款金额通过付款/收款明细与出库单关联，部分收款不能标记全部核销。
• 销售退货要冲减收入/应收并可能影响原收款，不能只增加库存。

19. 事务、锁和幂等

Redis 锁只是短期互斥，不等同业务幂等。销售出库必须同时依靠销售剩余量和实时库存的数据库级校验。

20. 按单号排查 SOP

20.1 销售订单和出库单

SELECT id, billNo, sid, status, sourceType, buId,
       payType, totalAmount, createTime, modifyTime, isDelete
FROM t_scm_sa_order
WHERE sid = :sid AND billNo = :sa_order_no;

SELECT *
FROM t_scm_sa_order_info
WHERE sid = :sid AND orderId = :sa_order_id
ORDER BY id;

SELECT id, billNo, sid, billStatus, sourceType, buId,
       hxStateCode, totalAmount, createTime, modifyTime, isDelete
FROM t_scm_sa_invoice
WHERE sid = :sid AND (srcOrderId = :sa_order_id OR srcOrderNo = :sa_order_no)
ORDER BY id;

SELECT *
FROM t_scm_sa_invoice_info
WHERE sid = :sid AND billId IN (:invoice_ids)
ORDER BY billId, id;

字段名可能因历史版本存在大小写差异，先以模型或只读 SHOW COLUMNS 校正。

20.2 库存和收款

SELECT i.id, i.billNo, i.transType, i.billDate, d.*
FROM t_scm_inventory i
JOIN t_scm_inventory_info d ON d.billId = i.id AND d.sid = i.sid
WHERE i.sid = :sid
  AND (i.srcOrderId IN (:invoice_ids) OR i.srcOrderNo IN (:invoice_nos))
ORDER BY i.id, d.id;

SELECT p.id, p.billNo, p.billStatus, p.totalAmount,
       d.stlId, d.stlNo, d.amount, d.accId, d.wayId
FROM t_scm_payment p
JOIN t_scm_payment_info d ON d.billId = p.id AND d.sid = p.sid
WHERE d.sid = :sid
  AND (d.stlId IN (:invoice_ids) OR d.stlNo IN (:invoice_nos))
ORDER BY p.id, d.id;

20.3 配送关系

SELECT r.*, d.*
FROM t_sa_invoice_delivery_relation r
LEFT JOIN t_scm_third_party_delivery_order d ON d.id = r.delivery_order_id
WHERE r.sid = :sid AND r.sa_invoice_id IN (:invoice_ids)
ORDER BY r.id;

实际关系字段以模型为准。查不到关系时继续按外部配送单号、出库单号和回调日志搜索。

20.4 代码定位

rg -n "function addInvSaOr|function addOutBound|function cancel\(" application/controllers/scm/InvSa.php
rg -n "function saCreate|function saOrderOut|function saOrderMainFields" application/Services/SaOrders
rg -n "syncOutboundCreate|syncOutboundCancel|dgj_notify" application/Services
rg -n "dispatchCenterDeliveryStockOut|dispatchCenterLogisticeInfoNotify" application/controllers/tasks

21. 常见故障决策表

22. 改动风险和回归清单

高风险公共点

• InvSaService.php：老 PC 列表、出库、对账和退货仍大量共用。
• SaOrderSer.php：来源映射、订单和出库数量更新影响多个入口。
• InventorySer.php：销售出库、销退和其他库存业务共用。
• SyncOrderSer.php：SAAS/E站/APP 下游合同，字段改动会导致跨系统失败。
• SaOrderEnums.php：历史来源值和两套状态被页面、报表、MQ 共同依赖。

最小回归集

• 普通销售订单新增、修改、关闭；重复 SKU 和禁用客户拦截。
• E站商城、E站维修、活动、机器人、E站 APP 的挂账/微信来源映射。
• 一次全部出库、分批出库、剩余关闭、并发抢同一库存。
• 普通仓、移动仓和微仓铺货校验，已删除货位不可出库。
• 出库库存流水、实时库存、销售订单数量和出库单状态一致。
• 配送、自提、送达和重复回调；三方配送关系正确。
• 出库撤销生成反向库存、取消配送并通知下游。
• 挂账、现金、微信；未收、部分、全部收款。
• 单笔/批量对账、撤销对账、核销和有财务分录时的限制。
• 销售退货新增/修改、退货入库、原单/收款冲回。
• 老/新列表、PC/App 接口对同一单据的状态和金额一致。

23. 证据索引和待确认项

已确认

• PC 方法语义：application/controllers/scm/InvSa.php。
• 状态/来源/支付：application/KzData/Enums/SaOrderEnums.php。
• 表名：application/config/tables.php。
• 销售订单/出库核心：SaOrderSer.php、SaInvoiceSer.php、InvSaService.php。
• App code：application/config/appapis.php。
• 下游同步：application/Services/SyncOrder/SyncOrderSer.php。
• 配送回调：application/controllers/tasks/DispatchCenterNotify.php。
• 交易类型：application/KzData/Enums/TransTypeEnums.php。

待代码/环境确认

• addOutBound() 前段对请求进行 JSON 解析的历史代码和当前运行时实际数据形态。
• 老/新销售、出库列表的数据源切换开关和各环境覆盖范围。
• 销售创建/出库/撤销 MQ 的完整 payload、幂等键和重试策略。
• 自动核销的金额容差、差额和账户优先级规则。
• 第三方配送关系表在各版本的实际字段名和外部状态映射。
• E站微信支付成功与 DGJ2 收款分录的最终回调链。

待确认项会在销售排查、配送和财务专题继续回填，当前文章不把未验证行为写成绝对结论。

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

多入口请求链路

日志证据矩阵

环节数据变更台账

子模块级独立追踪

子模块追踪：sale-create 销售订单创建

子模块追踪：sale-outbound 销售出库单创建

子模块追踪：sale-stock 销售出库库存扣减

子模块追踪：sale-delivery 配送、自提与签收

子模块追踪：sale-receipt 对账、收款与核销

子模块追踪：sale-revoke 撤销出库与状态恢复

子模块追踪：sale-return 销售退货与退货入库

子模块追踪：sale-sync 销售与出库下游同步