采购、采购退货与采购入库

1. 业务目标与边界

采购域负责服务站从供应商、云仓、活动、预订单或订单中心获得商品，并把“采购意向”推进为可支付、可发货、可签收、可入库的业务单据。反向链路包含未发货关闭、采购退货、退货出库、退款和仓库确认。

本篇覆盖：

• PC 老采购入口、新采购/购物车入口和 App 采购入口。
• 草稿保存、修改、提交、审核、在线支付、发货、配送、入库、完成。
• 整单/明细关闭、待支付取消、退货申请和退货出库。
• 订单中心、支付中心、仓储库存和特殊活动来源联动。

不在本篇展开：采购报表每个指标的 DWD 口径、所有金融通道内部字段、每一种特殊订单的独立 PRD。这些在报表、财务、首配、活动专题中继续细分。

2. 参与角色和前置条件

3. 入口和代码地图

4. 采购接口总表

4.1 PC 主链路

当前分支证据缺口：Controller 明确调用 InvPoService->submitInvPo($data,$orderId)，但在当前工作区没有检索到这个方法定义。发布/联调前应确认是否由未同步代码、扩展装载或历史分支提供。本文不虚构其内部实现，提交后的状态以枚举、回调和其他可见 Service 为依据。

4.2 退货和仓内操作

4.3 App 和 WMS code

code 是应用协议入口，不等同固定 URL。联调时还要确认 API 网关请求结构、签名和统一返回包装。

5. 保存采购草稿请求

PC 老入口把业务 JSON 放在 postData 字符串中，登录上下文不应由业务表单伪造。

{
  "postData": "{\"locationId\":101,\"orderType\":\"30-Cxx-01\",\"description\":\"门店补货\",\"strict\":1,\"entries\":[{\"invId\":10001,\"qty\":10,\"packSpecType\":1}]}"
}

服务端处理顺序：

1. 检查 PU_ADD 权限。
2. 解析 postData，InvPoValidate::saveInvPo 校验仓库、备注和订单类型。
3. 从会话注入 sid/uid/name。
4. 校验仓库存在且不是移动仓，采购只能入普通仓。
5. 加载服务站区域，PoOrderSer::checkOrderGoods 校验物料、数量、供应关系和严格模式。
6. 急件配送到客户时校验 dispatchType/contactId 和联系人地址。
7. NormalOrderSaveService::savePoOrder 保存草稿。
8. 保存服务站最后一次商品包装规格，返回草稿 ID。

核心字段：

修改草稿多传 id，并强制当前 billStatus=0；已提交订单不能通过更新草稿接口改回去。

6. 正向采购主流程

flowchart TD
    A[服务站选品] --> B[保存采购草稿]
    B --> C[校验权限 仓库 订单类型 商品 数量 供应关系]
    C --> D{校验通过}
    D -- 否 --> X[返回错误 不生成有效草稿]
    D -- 是 --> E[写采购主单 明细 扩展]
    E --> F[提交采购单]
    F --> G{支付类型/来源规则}
    G -- 在线支付 --> H[采购单待支付]
    G -- 线下挂账或无需支付 --> I[待处理/审核]
    H --> J[支付中心处理]
    J --> K{支付结果}
    K -- 成功 --> I
    K -- 超时/取消 --> L[已过期或关闭 释放来源占用]
    I --> M[订单中心/供应方审核]
    M --> N{审核结果}
    N -- 驳回 --> O[审核不通过]
    N -- 通过 --> P[待出库]
    P --> Q[供应方出库]
    Q --> R[配送中]
    R --> S[服务站签收/入库]
    S --> T[库存增加 已入库数量累加]
    T --> U{全部履约或仍有未完成量}
    U -- 全部完成 --> V[采购单已完成]
    U -- 部分 --> W[保留待入库/配送或处理差异关闭]

7. 系统调用时序

sequenceDiagram
    participant U as 服务站用户
    participant C as InvPo Controller
    participant PS as 采购 Service
    participant DB as 采购数据库
    participant OC as 订单中心
    participant PAY as 支付中心
    participant WMS as 仓储/PDA
    participant INV as InventorySer

    U->>C: saveInvPo(postData)
    C->>PS: checkOrderGoods + savePoOrder
    PS->>DB: INSERT po_order/po_order_info
    DB-->>U: draft orderId
    U->>C: submitInvPo(orderId,postData)
    C->>PS: 提交采购
    alt 在线支付
        PS->>DB: billStatus=待支付
        PS->>PAY: 发起支付
        PAY-->>C: PayCenterNotify 支付回调
        C->>DB: payment/payment_info/payinfo + 采购状态
    else 线下或无需支付
        PS->>DB: billStatus=待处理/审核
    end
    PS->>OC: 同步正向采购
    OC-->>C: OrderCenterNotify 审核/取消/关闭消息
    C->>DB: 更新审核和履约状态
    OC-->>WMS: 发货/物流
    WMS->>C: 签收/入库请求
    C->>INV: 保存库存流水并增加实时库存
    INV->>DB: inventory/inventory_info/real_time
    C->>DB: 更新采购明细已入库数量和主单完成状态

8. 采购状态机

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

stateDiagram-v2
    [*] --> 草稿: saveInvPo
    草稿 --> 待支付: 提交且在线支付
    草稿 --> 待处理: 提交且线下/无需支付
    待支付 --> 待处理: 支付成功
    待支付 --> 已过期: 超时或待支付取消
    待支付 --> 待退款: 支付异常/退回场景
    待处理 --> 审核中: 外部受理
    审核中 --> 待出库: 审核通过
    审核中 --> 审核不通过: 审核拒绝
    待出库 --> 配送中: 出库/发货
    配送中 --> 已完成: 全部签收并入库
    待处理 --> 已关闭: 允许取消/关闭
    待出库 --> 已关闭: 未发货关闭满足条件
    已过期 --> [*]
    审核不通过 --> [*]
    已关闭 --> [*]
    已完成 --> [*]

这是一张主流程图，不表示所有订单类型都能走每条边。特殊活动、直发、自提、首配、退货、授信订单会额外限制动作。

9. 订单类型和来源类型

orderType 决定“这是什么业务单”；srcOrderType/srcOrderId/srcOrderNo 决定“它从哪里来”。两者不能混用。

关键来源值：0 普通、8 采购退货、10 在线支付未发货退款、12 预订单、13 秒杀活动。

10. 支付数据链路

flowchart LR
    A[采购单待支付] --> B[获取支付信息/二维码/无页面支付]
    B --> C[支付中心受理]
    C --> D[PayCenterNotify 消费支付结果]
    D --> E{payStatus 是否成功口径}
    E -- 否 --> F[异常/退款分支 记录日志并按事件处理]
    E -- 是 --> G[写 t_scm_payment]
    G --> H[写 t_scm_payment_info]
    H --> I[写 t_scm_po_order_payinfo]
    I --> J[采购单退出待支付并记录 paymentTime]
    J --> K{特殊来源}
    K -- 秒杀 --> L[locked_qty 转 used_qty]
    K -- 预订单/活动/授信 --> M[调用各来源后处理]
    K -- 普通 --> N[进入审核/待处理链路]

支付成功并不只改采购状态。当前回调还可能：

• 生成付款主单和明细。
• 更新账户/授信/专属活动额度。
• 写采购支付关联表。
• 推进预订单或秒杀来源状态。
• 触发任务记录和后续审核/工单逻辑。

所以支付问题不能通过手工把 billStatus 改成 1 解决；必须核对账务、来源单和重复回调幂等。

11. 采购关闭流程

11.1 关闭类型

11.2 主流程

flowchart TD
    A[用户/订单中心/超时任务发起关闭] --> B[校验服务站 单据 状态 token]
    B --> C[Redis 锁防重复]
    C --> D{待支付取消?}
    D -- 是 --> E[PoOrderSer cancelWaitPayOrder]
    D -- 否 --> F[校验明细未发货/可关闭量和特殊订单限制]
    F --> G{可关闭}
    G -- 否 --> X[返回 can_not_close_reason]
    G -- 是 --> H[写 po_close_info]
    H --> I[更新明细数量拆分和主单 closeStatus/billStatus]
    I --> J[向订单中心/下游发送关闭确认或取消]
    J --> K{来源为秒杀/赠品/预订单}
    K -- 是 --> L[来源域释放锁量/额度/状态]
    K -- 否 --> M[完成关闭]

关闭必须区分“未发货关闭”和“已出库后的退货”。已出库数量不能伪装成关闭数量，否则采购、库存和财务三套事实会不一致。

12. 采购退货流程

sequenceDiagram
    participant U as 服务站
    participant C as InvPo/AfterSale
    participant S as 退货 Service/Provider
    participant DB as 采购退货表
    participant OC as 订单中心
    participant W as 仓库
    participant PAY as 支付中心

    U->>C: 选择原采购明细和可退数量
    C->>S: saveOrderBack / create
    S->>DB: 保存退货草稿和原单关联
    U->>C: submitOrderBack(orderId)
    C->>S: 校验来源和可退数量
    S->>OC: 提交售后审核
    OC-->>C: aftersale audit/update callback
    alt 审核通过需服务站出库
        U->>C: invPoOutStorage(locationId,areaId)
        C->>DB: 写退货出库事实并减少库存
        W-->>C: confirm warehouse/close
    else 未发货退货
        OC-->>C: 直接关闭未发货量
    end
    PAY-->>C: refund result
    C->>DB: 更新退款/退货状态和付款关联

退货保存有新旧双路径：PoPrivilegeAuthSer::isCallNewPoServer(sid) 为真时走 RefundProvider，否则走 DGJ2 本地 Service。排查同一接口在不同服务站表现不同时，第一步先确认这个路由开关。

秒杀来源退货还会经过 assertFlashActivityReturnAllowed... 限制，不能绕过活动生命周期直接做普通滞销品退货。

13. 采购入库与库存变化

13.1 仓内流程

flowchart TD
    A[物流签收/待入库列表] --> B[扫描箱码/商品码]
    B --> C[定位采购单 明细 仓库 货位]
    C --> D[计算发货量 已入库量 差异量 可入库量]
    D --> E{数量和货位合法}
    E -- 否 --> X[拒绝并返回超量/货位/商品错误]
    E -- 是 --> F[Redis 锁 goodsList 防重复提交]
    F --> G[写采购入库单和明细]
    G --> H[InventorySer 写库存流水]
    H --> I[实时库存和货位库存增加]
    I --> J[更新采购明细已入库数量]
    J --> K{全部完成}
    K -- 是 --> L[采购单已完成]
    K -- 否 --> M[保留配送/待入库并记录差异]

InvPo::invPoInStroage 使用 sid + md5(goodsList) 的 Redis 锁，锁时长 30 秒。它只能降低重复点击风险，最终仍需依靠数据库数量校验和事务保证不超入。

13.2 数量事实

采购数量排查至少同时看：

• 采购明细原始数量。
• 数量拆分表中的发货、入库、关闭、退货等累计值。
• 采购出库/物流明细事实。
• 采购入库单和库存流水。
• 关闭明细。
• 报表同步数据及延迟。

不能仅通过主单状态判断“是否已经入库”，也不能只修采购表而不核对库存流水和实时库存。

14. 外部消息入口

OrderCenterNotify 在订单中心 destination 上注册以下采购相关事件：

支付中心由 PayCenterNotify 消费支付成功、支付异常、退款、白条退回和分期等事件。具体 destination/routing key 和 payload 在 MQ 专题统一维护。

15. 核心表和读写矩阵

16. 数据关系图

erDiagram
    SCM_PO_ORDER ||--|{ SCM_PO_ORDER_INFO : order_id
    SCM_PO_ORDER ||--o| SCM_PO_ORDER_EXT : order_id
    SCM_PO_ORDER_INFO ||--o{ SCM_PO_ORDER_INFO_QTY : order_info_id
    SCM_PO_ORDER ||--o{ SCM_PO_ORDER_PAYINFO : order_id
    SCM_PO_ORDER_INFO ||--o{ SCM_PO_OUT_INFO : order_info_id
    SCM_PO_ORDER_INFO ||--o{ SCM_PO_CLOSE_INFO : src_order_info_id
    SCM_PO_ORDER ||--o{ SCM_PAYMENT_INFO : stl_id
    SCM_PAYMENT ||--|{ SCM_PAYMENT_INFO : payment_id
    SCM_PO_ORDER ||--o{ SCM_INVENTORY : source_order
    SCM_INVENTORY ||--|{ SCM_INVENTORY_INFO : inventory_id

旧表字段命名同时存在驼峰和下划线，ER 图使用业务语义名。写 SQL 前必须以目标环境表结构和模型字段为准。

17. 事务、锁和幂等边界

资金、库存和来源活动同时变化的操作属于高风险链路。禁止只改一个主状态来“修好页面”。

18. 按采购单号排查 SOP

18.1 主单、明细和来源

SELECT id, billNo, sid, billStatus, orderType, paymentType,
       closeStatus, srcOrderType, srcOrderId, srcOrderNo,
       paymentTime, createTime, modifyTime, isDelete
FROM t_scm_po_order
WHERE sid = :sid AND billNo = :po_bill_no;

SELECT *
FROM t_scm_po_order_info
WHERE sid = :sid AND orderId = :po_order_id
ORDER BY id;

SELECT *
FROM t_scm_po_order_info_qty
WHERE sid = :sid AND orderId = :po_order_id
ORDER BY orderInfoId, id;

先确认 orderType 和来源三字段，再决定查普通采购、活动、预订单还是退货链路。

18.2 支付

SELECT *
FROM t_scm_po_order_payinfo
WHERE sid = :sid AND orderId = :po_order_id
ORDER BY id;

SELECT p.id, p.billNo, p.billStatus, p.totalAmount, p.createTime,
       i.stlId, i.stlNo, i.amount, i.accId, i.wayId, i.createTime AS infoCreateTime
FROM t_scm_payment p
JOIN t_scm_payment_info i ON i.billId = p.id AND i.sid = p.sid
WHERE i.sid = :sid AND (i.stlId = :po_order_id OR i.stlNo = :po_bill_no)
ORDER BY p.id, i.id;

若字段名与环境不一致，以模型和 SHOW COLUMNS 的只读结果校正。核对支付中心回调时间、采购 paymentTime、付款分录和来源单状态是否同时推进。

18.3 发货、关闭和库存

SELECT * FROM t_scm_po_out_info
WHERE sid = :sid AND srcOrderId = :po_order_id
ORDER BY id;

SELECT * FROM t_scm_po_close_info
WHERE sid = :sid AND srcOrderId = :po_order_id AND isDelete = 0
ORDER BY id;

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 = :po_order_id OR i.srcOrderNo = :po_bill_no)
ORDER BY i.id, d.id;

18.4 代码定位

rg -n "function saveInvPo|function submitInvPo|function cancelWaitPayOrder" application
rg -n "function closeInvPo|function invPoInStorage|function invPoOutStorage" application
rg -n "TYPE_ORDERCENTER_ORDER_AUDIT|paycenterPayResult" application/controllers/tasks application/KzData/Enums
rg -n "SRC_ORDER_TYPE_FLASH_ACTIVITY|ORDERTYPE_FLASH_ORDER" application

19. 常见故障决策表

20. 改动风险和回归清单

高风险公共点

• InvPoService.php：关闭、入库、退货、支付方法调用面广。
• PoOrderSer.php：普通、活动、预订单、关闭和来源释放共用。
• PayCenterNotify.php：资金、采购状态、账户、来源业务同事务联动。
• InventorySer.php：所有库存方向共用，交易类型或正负号错误会扩散。
• PoOrderEnums.php：状态和订单类型被页面、任务、报表、MQ 共同使用。

最小回归集

• 普通采购保存、修改、删除、提交；移动仓被拒绝。
• 急件配送到站/客户、自提，联系人地址校验正确。
• 在线支付成功、失败、重复回调、超时取消；付款分录不重复。
• 线下挂账提交后不错误进入在线支付。
• 订单中心审核通过、驳回、取消、重复消息。
• 明细部分关闭、整单关闭、已有出库量时关闭被限制。
• 入库一次、分批入库、重复点击、超量、错误货位、发货差异。
• 不良品、滞销品、未发货、直采和首配退货的新旧服务路径。
• 秒杀/赠品/预订单来源在支付和关闭后正确回写。
• 采购主明细、数量拆分、关闭、库存流水和报表口径核对。

21. 证据索引和待确认项

已确认

• PC 请求入口：application/controllers/scm/InvPo.php。
• 请求校验：application/Validate/Po/InvPoValidate.php。
• 草稿保存：PoOrderSer::checkOrderGoods、NormalOrderSaveService::savePoOrder。
• 关闭/入出库入口：InvPoService::closeInvPo、closeInvPoOrder、invPoInStorage、invPoOutStorage。
• 支付入口和回调：InvPo 支付方法、tasks/PayCenterNotify.php。
• 订单中心事件：tasks/OrderCenterNotify.php。
• App/WMS code：application/config/appapis.php。
• 状态和类型：application/KzData/Enums/PoOrderEnums.php。
• 表名：application/config/tables.php。

待代码/环境确认

• 当前分支 InvPoService::submitInvPo 的真实定义位置和提交内部调用链。
• 各环境 PC、App、新采购服务的流量切换规则和真实网关 URL。
• 支付、订单中心和采购服务的消息幂等键及生产重试策略。
• 采购入库单物理表、库存主单来源字段在各历史版本的实际字段名。
• 报表中心同步频率和采购完成状态过滤口径。

这些缺口必须在对应专项文章继续回填；在确认前不要把推测当成生产事实。

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

多入口请求链路

日志证据矩阵

环节数据变更台账

子模块级独立追踪

以下每张卡只描述一个采购子模块。排查时先用稳定业务键选中卡片，再沿同一行从请求、代码、数据库走到日志和补偿，不把相邻采购动作混为一次事务。

子模块追踪：po-draft 采购草稿保存与编辑

子模块追踪：po-submit-audit 采购提交与审核

子模块追踪：po-payment 采购支付与支付回调

子模块追踪：po-delivery 采购发货与配送

子模块追踪：po-inbound 采购入库与库存增加

子模块追踪：po-close 采购关闭与取消

子模块追踪：po-return 采购退货与退货出库

子模块追踪：po-source 秒杀、赠品与预订单来源联动