售后申请与销售退货申请

本文从真实代码出发，说明 DGJ2.0 与 SAAS/E站之间的销售退货申请、后台审核、退货入库、DGJ 财务冲账、下游退款和取消申请链路。

它要解决的不是“怎么新增一张销退单”这个单点问题，而是把下面六个容易混在一起的事实拆开：

1. SAAS 退款单和 DGJ 退货申请单是两个系统里的两张单。
2. DGJ 申请审核通过只进入“待入库”，不会直接增加库存。
3. 真正的库存回增发生在生成 150602 销退单和库存流水时。
4. DGJ 会同时生成负金额的销售退款/冲账记录，但支付渠道退款由 SAAS 在收到完成事件后按支付方式执行。
5. 已发货退货、未发货退款、挂账领料退货走的状态和库存路径不同。
6. PC 手工销退、渠道售后、预订单售后不是这张退货申请单的同一条流程。

读完后，应当可以只凭订单号和服务站 sid 回答：

• 申请是谁发起的，属于已发货退货还是未发货关单。
• SAAS 退款单、DGJ 申请单、DGJ 销退单和退款记录分别是什么单号。
• 当前停在 SAAS、DGJ 审核、DGJ 入库、MQ 还是支付渠道。
• 库存有没有回增，回增到哪个仓库和货位。
• DGJ 账务有没有生成，外部真实退款有没有发起。
• 当前能不能取消、重试、补消息或人工补偿。

1. 业务目标与范围

1.1 本文覆盖

1.2 本文不当作同一流程的场景

1.3 参与角色

2. 一句话业务脉络

flowchart LR
    A["SAAS 创建退款单 RFC..."] --> B["调用 DGJ createOrderReturn"]
    B --> C["DGJ 创建申请单 AR... 状态 1"]
    C --> D["OPS 审核 状态 1→2"]
    D --> E["MQ app_apply_return_checked"]
    E --> F["SAAS 退款单 0→11"]
    D --> G["OPS 选择仓库货位并入库"]
    G --> H["DGJ 创建 XS... 销退单 150602"]
    H --> I["库存流水和实时库存回增"]
    H --> J["DGJ 创建负金额销售退款记录"]
    I --> K["DGJ 申请单 2→3"]
    K --> L["MQ app_apply_return_finish"]
    L --> M["SAAS 按支付方式执行退款"]

必须记住：

AR... 是退货申请，XS... 是实际销退业务事实，RFC... 是 SAAS 退款单。审核、库存和外部退款分别发生在不同阶段。

3. 系统边界与调用关系

flowchart TB
    subgraph SAAS["SAAS / E站"]
        U["用户提交退货"]
        RS["RefundService"]
        RO["t_refund_order"]
        RD["t_refund_order_detail"]
        DC["DgjConsumer"]
        PAY["支付渠道/资金系统"]
    end
    subgraph DGJ["DGJ2.0"]
        API["inner/moveMall/Order"]
        SVC["SaOrderSer + ApplyReturnSer"]
        AR["申请主明细"]
        OPS["OPS 审核与入库"]
        INV["销退单 + 库存"]
        FIN["收款/退款冲账"]
    end
    subgraph MQ["RabbitMQ"]
        CHECKED["app_apply_return_checked"]
        FINISH["app_apply_return_finish"]
        INVENTORY["inventory_event"]
    end
    U --> RS
    RS --> RO
    RS --> RD
    RS --> API
    API --> SVC
    SVC --> AR
    AR --> OPS
    OPS --> INV
    OPS --> FIN
    OPS --> CHECKED
    OPS --> FINISH
    INV --> INVENTORY
    CHECKED --> DC
    FINISH --> DC
    DC --> RO
    DC --> PAY

4. 三类单号和关联键

4.1 单号不要混用

4.2 ID 传递关系

flowchart LR
    SO["SAAS 原订单 order_no"] --> RF["SAAS 退款单 refund_order_no"]
    RF -->|src_order_no| AR["DGJ 申请单 AR"]
    SO -->|src_sa_order_no| AR
    AR -->|srcOrderId/srcOrderNo| XS["DGJ 销退单 XS"]
    XS -->|stlId/stlNo| SKD["DGJ 退款冲账单 SKD"]
    RF -->|MQ order_no| CB["SAAS 退款回调处理"]

5. 代码入口地图

5.1 DGJ 主链路

5.2 SAAS 上下游证据

6. 接口总表

6.1 SAAS 调 DGJ

6.2 DGJ OPS

6.3 PC 手工销退

7. 已发货退货请求契约

7.1 代表性请求

下面是根据 SAAS OrderReturnRequest 和 DGJ validform_rt 还原的脱敏结构。真实域名、签名和内部鉴权由环境配置决定。

{
  "order_scene": "e_shop",
  "station_id": 10001,
  "storage_id": 3001,
  "contact_id": 88001,
  "order_id": 760001,
  "order_no": "RFC10001XXXX",
  "src_order_id": 650001,
  "src_order_no": "EORDERXXXX",
  "totalQty": 2,
  "totalAmount": 198.00,
  "expectAmount": 188.00,
  "remark": "客户退货",
  "return_type": 0,
  "entries": [
    {
      "skuId": "KZ-SKU-001",
      "qty": 2,
      "price": 99.00,
      "return_price": 94.00,
      "amount": 188.00,
      "discount": 10.00,
      "is_gift": 0,
      "areaId": 5001
    }
  ]
}

7.2 主字段解释

7.3 明细字段解释

7.4 成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12345,
    "bill_no": "ARXXXX"
  }
}

SAAS 随后把这两个值保存到退款单的 sa_invoice_order_id、sa_invoice_order_no。字段名沿用历史命名，实际保存的是 DGJ 申请单，不是最终 150602 销退单。

8. OPS 接口请求

8.1 列表查询

{
  "page": 1,
  "rows": 20,
  "customer_id": 88001,
  "beginDate": "2026-07-01",
  "endDate": "2026-07-31",
  "status": 2,
  "search_type": 1,
  "skey": "ARXXXX"
}

8.2 审核

{
  "id": 12345
}

JXCSID、JXCUID、JXCUNAME 来自 DGJ 登录上下文。审核接口没有“驳回”参数；当前代码只支持通过，取消由 SAAS 在待处理状态调用。

8.3 入库

inStorage 接收表单字段 postData，其值是 JSON 字符串：

{
  "postData": "{\"id\":12345,\"entries\":[{\"skuId\":\"KZ-SKU-001\",\"qty\":2,\"return_price\":94,\"amount\":188,\"discount\":10,\"locationId\":3001,\"locationAreaId\":5001,\"description\":\"退货入库\"}]}"
}

服务端随后补充：

9. DGJ 申请状态机

application/KzData/Enums/ApplyReturnEnums.php 定义四个状态：

stateDiagram-v2
    [*] --> Pending: 普通已发货申请
    Pending: 1 待处理
    Stock: 2 待入库
    Finish: 3 已完成
    Cancel: 4 已取消
    Pending --> Stock: OPS 审核通过
    Pending --> Cancel: SAAS 取消申请
    Stock --> Finish: OPS 退货入库
    [*] --> Finish: 挂账领料/未发货 needAudit=false
    Finish --> [*]
    Cancel --> [*]

当前实现没有“审核驳回”状态。产品页面若展示“驳回”，必须先确认是否由前端映射为取消，不能凭名称推断后端存在驳回动作。

10. SAAS 退款状态机

SAAS RefundOrderEnums 与 DGJ 申请状态不是同一套枚举：

stateDiagram-v2
    [*] --> WaitAck: SAAS 提交已发货退货
    WaitAck: 0 待确认
    WaitRefund: 11 待退款
    Submitted: 1 已完成
    Canceled: 99 已取消
    WaitAck --> WaitRefund: DGJ 审核事件
    WaitAck --> Canceled: 用户取消
    WaitRefund --> Submitted: 支付/挂账退款完成
    [*] --> WaitRefund: 未发货退款

双系统状态对照：

11. 普通已发货申请创建

11.1 SAAS 侧先做业务结算

RefundService::submit 在本地事务中：

1. 读取原订单和明细。
2. 计算可退数量、原金额、优惠券分摊和可退金额。
3. 校验退款后金额不能低于 0.1 元。
4. 校验申请退款金额不大于可退金额。
5. 新增 t_refund_order 和 t_refund_order_detail。
6. 累加原订单、原明细的退款中数量和金额。
7. 组装 OrderReturnRequest 调用 DGJ。
8. 把 DGJ 返回的申请 ID、申请号回写 SAAS 退款单。

sequenceDiagram
    participant User as E站用户
    participant Refund as SAAS RefundService
    participant SDB as SAAS数据库
    participant Provider as DGJ Provider
    participant DGJ as DGJ Order API
    User->>Refund: 退货商品、数量、原因、期望退款
    Refund->>SDB: 读原订单/明细/已退数量
    Refund->>Refund: 计算数量、优惠和退款金额
    Refund->>SDB: 新增退款主明细并累加退货中数量
    Refund->>Provider: OrderReturnRequest
    Provider->>DGJ: createOrderReturn
    DGJ-->>Provider: DGJ申请ID与AR单号
    Provider-->>Refund: data
    Refund->>SDB: 回写sa_invoice_order_id/no

11.2 DGJ 防重复和基础校验

SaOrderSer::validform_rt 当前验证：

重要边界：

普通 E站申请在 DGJ validform_rt 中没有再次根据历史 150601/150602 计算可退数量。可退数量主要由 SAAS 提交前控制；DGJ 申请入库接口也只校验数量大于 0。因此不能把“DGJ 一定会阻止超申请入库”写成既定事实。

11.3 防重复锁

内部 Controller 调用：

RequestCheck::checkRepeat(
    RedisKeys::KEY_MOVE_OD_ADD_LOCK,
    json_encode($data)
);

实际行为：

flowchart TD
    A["收到创建请求"] --> B{"10秒请求锁成功?"}
    B -->|否| X["请勿重复提交"]
    B -->|是| C{"sid+退款单号已有申请?"}
    C -->|是| Y["订单号重复创建"]
    C -->|否| D["校验SKU和正数量"]
    D --> E["新增AR主表"]
    E --> F["批量新增AR明细"]
    F --> G["提交事务"]
    G --> H["发送新申请站内消息"]

11.4 申请落表

ApplyReturnSer::add 新增：

申请明细保存 sku_id、qty、price、return_price、amount、discount、remark、is_gift。仓库、货位不在申请明细中固化，实际入库时重新选择。

12. 审核流程

ApplyReturnSer::check：

1. 按 sid + id + status=1 读取申请。
2. 更新 status=2。
3. 写 check_id、check_name。
4. 调用 sendApplyReturnCheckedToAPP。

sequenceDiagram
    participant Ops as OPS审核人
    participant C as ApplyReturnOrder
    participant S as ApplyReturnSer
    participant DB as DGJ数据库
    participant MQ as RabbitMQ
    participant SaaS as SAAS DgjConsumer
    Ops->>C: check(id)
    C->>C: 校验APPLY_RETURN_CHECK
    C->>S: check(JXCSID/JXCUID/JXCUNAME)
    S->>DB: 查status=1
    S->>DB: 更新status=2和审核人
    S->>MQ: app_apply_return_checked
    MQ->>SaaS: order_id/order_no
    SaaS->>SaaS: 退款单0→11

审核事件：

{
  "order_id": 760001,
  "order_no": "RFC10001XXXX"
}

13. 入库预览如何选仓库和货位

inStorageDetail 不是库存写入，它用于给页面准备候选数据：

1. 读取申请主明细和客户。
2. 按 src_sa_order_no 找 DGJ 原销售单。
3. 按销售单 billNo 找原销售出库明细。
4. 以 skuId 建映射，默认带出原出库仓库和货位。
5. 再调用库存服务加载当前门店可选仓库和货位。

flowchart LR
    AR["申请明细 sku_id"] --> GOODS["物料中心 invId/名称/单位"]
    AR --> SO["原销售单 src_sa_order_no"]
    SO --> OUT["原销售出库明细"]
    OUT --> LOC["默认仓库和货位"]
    LOC --> PAGE["入库页面候选项"]
    GOODS --> PAGE

当前实现风险：

14. 退货入库事务

14.1 前置校验

ApplyReturnSer::validate 只明确验证：

• 申请 ID 非空。
• 明细非空。
• 每行 SKU 非空。
• 每行数量大于 0。
• 仓库和货位 ID 大于 0。

随后 inStorage 还会验证：

• 申请必须是当前 sid 且状态为 2。
• SKU 能在服务站物料缓存中找到。
• 仓库和货位能查询到。
• 原 DGJ 销售记录能按 src_sa_order_id/no 找到。

当前没有看到以下服务端强校验：

• 入库 SKU 集合必须与申请 SKU 集合完全相等。
• 入库数量不能大于申请数量。
• 入库总数量必须等于 total_qty。
• 入库货位一定属于选择的门店。

这些不是“系统一定允许”的结论，而是静态代码显示的风险点，必须通过接口回归和生产表约束继续确认。

14.2 事务内步骤

sequenceDiagram
    participant Ops as 仓库人员
    participant AR as ApplyReturnSer
    participant SO as SaOrderSer
    participant DB as DGJ数据库
    participant INV as InventorySer
    participant ACC as AccountService
    participant MQ as RabbitMQ
    Ops->>AR: inStorage(postData)
    AR->>DB: 查申请status=2
    AR->>DB: BEGIN
    AR->>SO: saOrderOut(150602)
    SO->>DB: 新增销退主表
    SO->>DB: 新增销退明细
    SO->>INV: save(销售退货)
    INV->>DB: 库存流水+实时库存
    AR->>SO: addPaymentForApp
    SO->>DB: 新增退款主明细
    SO->>ACC: 保存账户流水
    AR->>DB: 申请status 2→3
    AR->>DB: COMMIT
    AR->>MQ: inventory_event
    AR->>MQ: app_apply_return_finish

事务内包含：

事务提交后才发送两个 MQ。数据库事务不能回滚已经发生的外部消息，外部消息失败也不能回滚已提交数据库。

15. 销退单字段和正负方向

15.1 主表

saOutMainFieldsForApplyReturnId 和 saOutMainFields 共同组装实际销退单：

15.2 明细

flowchart LR
    A["申请数量 +2"] --> B["销退明细 qty +2"]
    B --> C["库存流水 +2"]
    C --> D["实时库存 +2"]
    E["申请金额 188"] --> F["销退主表 amount -188"]
    F --> G["退款明细 amount -188"]
    G --> H["客户往来冲减 188"]

数量和金额方向不能用同一个正负号理解：

• 销售出库 150601 通常库存数量为负。
• 销售退货 150602 库存数量为正。
• 销退业务金额为负，用于冲减销售收入和应收。

16. 库存回增

SaOrderSer::saOrderOut 将销退明细传给：

$InventorySer->save($v, 0, BillTypeEnums::SALE);

库存维度至少包含：

flowchart TD
    XS["150602销退明细"] --> FLOW["128分片库存流水"]
    XS --> RT["实时库存表"]
    FLOW --> REPORT["库存/销售/利润报表"]
    RT --> QUERY["可售库存和仓位查询"]
    XS --> MQ["inventory_event"]
    MQ --> DOWN["库存下游消费者"]

核对库存时要同时证明：

1. 销退明细存在且未删除。
2. 当月库存流水存在，数量方向为正。
3. 实时库存对应 sid+invId+仓库+货位 已增加。
4. inventory_event 是否发送成功只影响异步下游，不代表本地库存是否落库。

17. DGJ 退款/冲账记录

addPaymentForApp 读取刚生成的销退单，然后：

1. 创建 SKD... 主单。
2. 主单 billType=RECEIPT、transType=153001。
3. 退款明细的 transType=150602、transTypeName=销售退款。
4. stlId/stlNo 指向 DGJ 销退单。
5. amount 使用销退单负金额。
6. 调用 AccountService::saveAccounts 写账户流水。

flowchart LR
    XS["销退单 XS / 150602"] --> PM["退款主单 SKD / 153001"]
    XS --> PI["退款明细 / 150602 / 销售退款"]
    PM --> PI
    PI --> ACC["账户流水"]
    PI --> CHECK["客户余额/对账单"]

这里的“销售退款”是 DGJ 财务系统里的负向收款和往来冲账事实。它不等于银联、微信或第三方资金已经退回用户。

18. 审核和完成 MQ

18.1 事件矩阵

18.2 完成事件

{
  "order_id": 760001,
  "order_no": "RFC10001XXXX",
  "return_type": 1
}

注意它与创建请求里的 return_type=0/1（正常品/不良品）不是同一个维度。

19. SAAS 收到事件后的退款

19.1 审核事件

DgjConsumer::returnChecked：

1. 按 refund_order_no = order_no 查退款单。
2. 更新 order_status=11 待退款。
3. 无论成功还是异常，finally 都返回 ACK。

19.2 完成事件

DgjConsumer::returnFinish 要求退款单当前状态必须是 11，然后按来源和支付方式分支：

flowchart TD
    A["收到app_apply_return_finish"] --> B{"SAAS退款单存在?"}
    B -->|否| X["记录不存在并ACK"]
    B -->|是| C{"状态是否11待退款?"}
    C -->|否| Y["告警并ACK"]
    C -->|是| D{"巨划算/微信来源?"}
    D -->|否| E["TdmgrProvider退款"]
    D -->|是| F{"支付方式"}
    F -->|银联同日| G["在线退款"]
    F -->|银联跨日| H["线下退款+清分标识"]
    F -->|挂账| I["退款单直接完成"]
    G --> J["回补SAAS库存"]
    H --> J
    I --> J

19.3 关键可靠性边界

SAAS 两个消费者都在 finally 返回 ACK。业务异常会记录日志和告警，但消息不会因为抛错自动 NACK 重投。因此：

• 审核事件消费失败会让 DGJ 已待入库、SAAS 仍待确认。
• 完成事件消费失败会让 DGJ 库存已回增、SAAS 仍待退款。
• 修复数据后需要明确的消息重放或业务补偿，不能等待自动重试。

20. 取消待审核申请

取消请求：

{
  "order_no": "RFC10001XXXX",
  "station_id": 10001
}

调用链：

sequenceDiagram
    participant User as SAAS用户
    participant RF as RefundService
    participant DGJ as DGJ cancelReturnOrder
    participant AR as ApplyReturnSer
    participant DB as 两边数据库
    User->>RF: 取消退款申请
    RF->>DB: 校验SAAS状态=0
    RF->>DGJ: 退款单号+sid
    DGJ->>AR: cancel
    AR->>DB: DGJ申请status 1→4
    DGJ-->>RF: success
    RF->>DB: 回退原单/明细退款中数量
    RF->>DB: SAAS退款单status 0→99

限制：

21. 挂账领料退货：创建即完成

21.1 适用条件

SaOrderSer::returnChargeOrder 处理“领料/自提类订单 + 挂账支付”的特殊退货。它与普通已发货退货最大的区别是：

• 不进入人工审核。
• 不等待 OPS 退货入库。
• 创建申请时直接生成 150602 销售退货事实。
• 同一请求中直接回增 DGJ 库存。
• 申请单初始状态就是 3 已完成。

SAAS 创建退款单时也会识别这一组合，将退款单直接放到已提交/待退款阶段，而不是普通的 0 待确认。

21.2 主流程

sequenceDiagram
    participant U as SAAS用户
    participant RS as RefundService
    participant API as createChargeOrderReturn
    participant SO as SaOrderSer
    participant AR as ApplyReturnSer
    participant DB as DGJ数据库
    participant MQ as MQ
    U->>RS: 提交挂账领料退货
    RS->>API: 退款单号、原销售单、退货明细
    API->>SO: returnChargeOrder
    SO->>AR: 创建status=3申请
    SO->>DB: 生成150602销退单
    SO->>DB: 回增库存和实时库存
    SO->>DB: 生成移动商城退货同步数据
    SO-->>API: application_id/application_no
    API-->>RS: success
    SO->>MQ: inventory_event
    SO->>MQ: 销退单同步SAAS

21.3 同一事务内外发生了什么

21.4 与普通退货的差异

重要风险：不能只根据申请状态 3 判断 SAAS 已经完成资金退款。此路径没有普通退货的完成事件闭环，必须同时核对 SAAS 退款单状态、销退单同步和支付类型。

22. 未发货退款：关原销售单而不是做退货入库

22.1 业务语义

未发货退款处理销售订单已经创建，但全部或部分商品尚未形成实际出库事实的场景。因为货还没有从 DGJ 库存扣出，所以它不应生成 150602 销售退货入库，也不应再次增加库存。

入口为：

• DGJ：inner/moveMall/Order/returnOrderNoOut
• Service：SaOrderSer::returnOrderNoOut
• SAAS：RefundInnerService 相关未发货退款流程

22.2 主流程

flowchart TD
    A["SAAS提交未发货退款"] --> B["DGJ校验原销售单和退款明细"]
    B --> C{"退全部还是退部分?"}
    C -->|overall| D["关闭整张销售订单"]
    C -->|portion| E["关闭指定未出库明细/数量"]
    D --> F["失效接单/待履约关系"]
    E --> F
    F --> G["创建状态3的退货申请事实"]
    G --> H["提交事务"]
    H --> I["发送app_apply_return_finish"]
    I --> J["return_type=2"]
    J --> K["SAAS继续退款"]

22.3 数据变化

22.4 return_type 三套含义不能混用

建议新接口或新事件拆成 goods_condition、close_scope、refund_scene 三个字段。现有代码必须结合接口和事件上下文解释，不能只看字段名。

23. PC 直接销售退货：另一条更强校验的链路

23.1 业务边界

PC 端 scm/InvSa/returnSale 和移动商城售后申请不是同一条链路。PC 直接销退通常由服务站人员在销售退货页面发起，直接形成 150602，核心实现位于：

• Controller：application/controllers/scm/InvSa.php
• Service：application/Services/InvSa/NormalSaleReturnSer.php
• 可退数量：InventoryService::getCanReturnQty
• 历史口径修正：NormalSaleSer::saReturnQtyFix
• 新旧页面灰度：SaleReturnPrevilegeCheck

allcarpart/sale/SaReturnOrder.php 主要是打印或转发入口，不能当作销售退货业务创建核心。

23.2 可退数量口径

对同一原出库明细，可退数量可抽象为：

可退数量
= 原销售出库数量
- 已生效销售退货数量
+ 当前编辑单据原先占用的退货数量
+ 历史修复表允许补回的数量

历史修正会参考 t_bs_return_goods_qty_fix。排查“明明卖过却不能退”时，不能只查原销售出库数量。

23.3 强校验项

23.4 PC 主流程

flowchart LR
    A["PC销售退货页面"] --> B["InvSa::returnSale"]
    B --> C["NormalSaleReturnSer"]
    C --> D["读取原出库及已退数量"]
    D --> E["getCanReturnQty"]
    E --> F{"数量/仓库/货位/属性通过?"}
    F -->|否| X["返回具体校验错误"]
    F -->|是| G["生成150602销退单"]
    G --> H["库存回增"]
    H --> I["财务往来处理"]
    I --> J["事务提交"]
    J --> K["发送库存/同步事件"]

23.5 排查时先区分入口

24. 表结构、分表和关系

24.1 DGJ 核心表

分表后缀必须按代码中的模型格式确认。本文给出当前常量和模型表达的取模关系，执行 SQL 前仍要用具体 Model 的 getTableName 或同类方法复核完整表名。

24.2 SAAS 核心表

24.3 关系图

erDiagram
    SAAS_ORDER ||--o{ SAAS_ORDER_DETAIL : contains
    SAAS_ORDER ||--o{ SAAS_REFUND_ORDER : requests
    SAAS_REFUND_ORDER ||--o{ SAAS_REFUND_DETAIL : contains
    SAAS_REFUND_ORDER ||--|| DGJ_APPLY_RETURN : "refund_order_no=order_no"
    DGJ_APPLY_RETURN ||--o{ DGJ_APPLY_RETURN_INFO : contains
    DGJ_APPLY_RETURN }o--|| DGJ_SA_ORDER : "src_order_id/no"
    DGJ_APPLY_RETURN ||--o| DGJ_SA_RETURN_INVOICE : creates
    DGJ_SA_RETURN_INVOICE ||--o{ DGJ_SA_RETURN_INFO : contains
    DGJ_SA_RETURN_INVOICE ||--o{ DGJ_INVENTORY_FLOW : changes
    DGJ_SA_RETURN_INVOICE ||--o{ DGJ_PAYMENT : offsets

24.4 单号追踪优先级

1. 有 RFC：先查退货申请，再取 sid、原销售单和申请状态。
2. 有 SAAS 退款单号：按 refund_order_no = DGJ order_no 关联。
3. 有 XS/SKD：查 trans_type=150602 的销退单，再反查来源申请。
4. 只有原销售单：先确认是否已出库，再分别查申请、销退和未发货关闭记录。
5. 只有 SKU：必须同时带 sid、时间范围、仓库和业务单号，避免扫分表。

25. 事务、幂等与并发

25.1 一致性边界

25.2 创建接口的两层防重

flowchart TD
    A["重复请求到达"] --> B{"Redis NX锁存在?"}
    B -->|是| X["拒绝重复提交"]
    B -->|否| C["设置10秒锁"]
    C --> D["查询sid+src_order_no是否已有申请"]
    D -->|有| Y["返回重复申请"]
    D -->|无| E["插入申请主明细"]
    E --> F["事务提交"]

Redis 锁只能压缩并发窗口，不能代替数据库唯一约束：

• 锁过期后重试仍依赖数据库查询。
• 两个进程在查询后、插入前仍存在竞态窗口。
• 取消单仍然属于“已存在申请”，同号重建可能失败。
• 若需要长期强幂等，应评估 sid + order_no 或 sid + src_order_no + scene 的唯一索引和兼容数据。

25.3 并发入库风险

sequenceDiagram
    participant A as 请求A
    participant B as 请求B
    participant DB as 数据库
    A->>DB: 读取申请status=2
    B->>DB: 读取申请status=2
    A->>DB: 创建150602和库存
    B->>DB: 也尝试创建150602和库存
    A->>DB: 更新申请status=3
    B->>DB: 更新申请status=3
    Note over A,B: 若没有行锁/唯一约束/CAS，存在重复入库窗口

静态代码能确认状态校验存在，但不能仅凭 Service 代码证明底层模型已使用 SELECT ... FOR UPDATE 或唯一索引。因此并发压测和数据库索引核验是发布前必要项。

25.4 建议的强幂等键

26. 失败窗口与补偿

26.1 失败矩阵

26.2 补偿决策树

flowchart TD
    A["收到售后异常"] --> B{"DGJ申请存在?"}
    B -->|否| C{"SAAS退款单存在?"}
    C -->|否| C1["修正请求后重新创建"]
    C -->|是| C2["核对SAAS是否应回滚或重调DGJ"]
    B -->|是| D{"申请状态"}
    D -->|1待审核| E["核对业务后正常审核/取消"]
    D -->|2待入库| F{"SAAS是否11待退款?"}
    F -->|否| F1["补checked事件/修正SAAS状态"]
    F -->|是| F2["继续正常入库"]
    D -->|3已完成| G{"150602是否应存在?"}
    G -->|已发货且不存在| G1["停止自动补库存，确认路径和数据缺口"]
    G -->|存在| H{"库存流水和实时库存一致?"}
    H -->|否| H1["按业务单做幂等库存补偿"]
    H -->|是| I{"SAAS退款完成?"}
    I -->|否| I1["按顺序补checked/finish/支付退款"]
    I -->|是| I2["闭环完成"]
    D -->|4已取消| J["确认SAAS=99且原单退款占用已释放"]

26.3 补偿顺序

1. 冻结继续人工操作，保存申请号、原单号、退款单号和 sid。
2. 判断退货场景：普通已发货、挂账领料、未发货、PC 直接销退。
3. 查申请状态和 SAAS 退款状态，确定断点。
4. 查 150602、库存流水、实时库存和退款记录。
5. 只补缺失的一步，不重跑整条链路。
6. MQ 补发携带原业务幂等键，并先确认消费者当前状态门槛。
7. 补偿后做两边状态、数量、金额和消息日志四组对账。

26.4 禁止操作

• 不要仅因 SAAS 未退款就再次执行 DGJ 入库。
• 不要直接把 DGJ 2 改成 3 而不生成销退、库存和财务事实。
• 不要先补发 finish，再补 checked；SAAS finish 要求状态 11。
• 不要把未发货退款当作库存回增。
• 不要只修实时库存而遗漏库存流水和来源单据。
• 不要在生产直接运行 tasks/SaleReturn.php::fix；当前代码包含硬编码 sid=1092，必须先专项审查。

27. 按现象排查

27.1 提交退货提示重复

flowchart TD
    A["提示重复提交/已有申请"] --> B["按refund_order_no查DGJ申请"]
    B --> C{"是否存在?"}
    C -->|是| D{"状态"}
    D -->|1/2/3| E["复用原申请继续流程"]
    D -->|4| F["确认业务是否允许换新退款单号"]
    C -->|否| G["检查10秒Redis锁和并发请求日志"]
    G --> H["确认是否请求超时但DB已提交"]

检查顺序：

1. 用退款单号查 t_scm_apply_return_order。
2. 查同一 sid + src_order_no 是否已有申请。
3. 对齐 SAAS t_refund_order。
4. 查调用日志是否存在超时、重复点击或网关重试。
5. 仅在确认 DGJ 没有业务事实后才允许重提。

27.2 DGJ 待入库，SAAS 仍待确认

这通常是 app_apply_return_checked 发送或消费失败。

1. 确认 DGJ 申请已经从 1 变为 2。
2. 查 DGJ MQ 发送日志。
3. 查 SAAS app_apply_return_checked.log。
4. 查 SAAS 退款单是否存在且当前为 0。
5. 修正阻塞原因后，幂等补发 checked 事件或按审批结果修正状态。

27.3 DGJ 已完成，SAAS 一直待退款

flowchart TD
    A["DGJ状态3/SAAS状态11"] --> B{"退货场景"}
    B -->|普通已发货| C["查150602和finish MQ"]
    B -->|挂账领料| D["查sendInvoiceToSass及特殊退款分支"]
    B -->|未发货| E["查close结果和return_type=2事件"]
    C --> F{"finish消费日志成功?"}
    E --> F
    F -->|否| G["修复后补发finish"]
    F -->|是| H["查支付渠道退款及SAAS库存回补"]

消费者异常也会 ACK，不能只看“收到消息”，必须看业务日志结果和退款单最终状态。

27.4 库存多了一次

1. 按业务单号查 150602 是否重复。
2. 按销退单号查库存流水主表是否重复。
3. 比较申请数量、销退明细数量、流水数量和实时库存增量。
4. 检查是否同时走了移动商城入库和 PC 直接销退。
5. 检查并发入库请求日志。
6. 修复时以业务流水为依据，不直接凭当前库存做减法。

27.5 申请商品和实际入库商品不一致

优先核对：

• 入库请求 entries 是否与申请明细逐行一致。
• 同 SKU 是否来自多个仓库/货位，inStorageDetail 的按 SKU 映射是否覆盖。
• 数量是否超过申请数。
• 请求中的 sku_id、仓库、货位是否来自前端可编辑字段。
• 150602 明细和库存流水最终写入了什么。

当前静态代码未证明入库阶段会完整重算“申请 SKU + 申请数量 + 原出库可退数量”，因此这是高优先级安全回归点。

28. 常用只读 SQL

以下 SQL 只用于定位思路。字段名、库名和完整分表名必须先按实际环境模型确认；生产环境只执行只读查询，不在文档中保存连接信息。

28.1 计算分表

SELECT
  :sid AS sid,
  MOD(:sid, 16)  AS sa_order_shard,
  MOD(:sid, 64)  AS sa_invoice_shard,
  MOD(:sid, 128) AS inventory_shard,
  MOD(:sid, 32)  AS payment_shard;

28.2 查退货申请

SELECT
  id, sid, order_no, src_order_id, src_order_no,
  status, checked, created_at, updated_at
FROM t_scm_apply_return_order
WHERE sid = :sid
  AND (order_no = :refund_order_no OR src_order_no = :source_order_no)
ORDER BY id DESC;

SELECT
  order_id, sku_id, return_qty, return_type,
  warehouse_id, location_id
FROM t_scm_apply_return_order_info
WHERE order_id = :application_id
ORDER BY id;

28.3 查原销售单

SELECT id, sid, bill_no, status, pay_type, created_at, updated_at
FROM t_scm_sa_order_0_N
WHERE sid = :sid
  AND (id = :source_order_id OR bill_no = :source_order_no);

SELECT id, oid, sku_id, qty, out_qty, close_qty
FROM t_scm_sa_order_info_0_N
WHERE oid = :source_order_id
ORDER BY id;

28.4 查 150602 销退单

SELECT
  id, sid, bill_no, trans_type, src_order_id, src_order_no,
  qty, amount, created_at
FROM t_scm_sa_invoice_0_N
WHERE sid = :sid
  AND trans_type = 150602
  AND (
    src_order_id = :application_id
    OR src_order_no = :refund_order_no
    OR bill_no = :sale_return_bill_no
  )
ORDER BY id DESC;

SELECT
  iid, sku_id, qty, warehouse_id, location_id, cost
FROM t_scm_sa_invoice_info_0_N
WHERE iid = :sale_return_invoice_id
ORDER BY id;

28.5 查库存流水和实时库存

SELECT id, sid, bill_no, trans_type, business_date, created_at
FROM t_scm_inventory_0_N
WHERE sid = :sid
  AND bill_no = :sale_return_bill_no
ORDER BY id DESC;

SELECT iid, sku_id, inv_id, warehouse_id, location_id, qty, cost
FROM t_scm_inventory_info_0_N
WHERE iid = :inventory_id
ORDER BY id;

SELECT sid, sku_id, inv_id, warehouse_id, location_id, qty, updated_at
FROM t_scm_inventory_real_time
WHERE sid = :sid
  AND sku_id IN (:sku_ids)
  AND warehouse_id = :warehouse_id
ORDER BY sku_id, location_id;

28.6 查 DGJ 收退款

SELECT id, sid, bill_no, trans_type, amount, status, created_at
FROM t_scm_payment_N
WHERE sid = :sid
  AND (
    bill_no = :refund_order_no
    OR src_order_no = :sale_return_bill_no
  )
ORDER BY id DESC;

SELECT pid, src_bill_no, amount, account_id
FROM t_scm_payment_info_N
WHERE pid = :payment_id
ORDER BY id;

28.7 查 SAAS 退款单

SELECT
  id, order_id, refund_order_no, order_status,
  refund_amount, sa_invoice_order_id, sa_invoice_order_no,
  created_at, updated_at
FROM t_refund_order
WHERE refund_order_no = :refund_order_no
ORDER BY id DESC;

SELECT refund_order_id, order_detail_id, sku_id, refund_qty, refund_amount
FROM t_refund_order_detail
WHERE refund_order_id = :refund_id
ORDER BY id;

28.8 四方数量对账

-- 分别从申请明细、150602明细、库存流水明细和SAAS退款明细汇总，
-- 再以 sku_id 为键比较。不要跨库直接照抄执行，建议分别查询后离线对齐。
SELECT sku_id, SUM(return_qty) AS apply_qty
FROM t_scm_apply_return_order_info
WHERE order_id = :application_id
GROUP BY sku_id;

期望关系：

普通已发货退货：
申请数量 = 150602数量 = DGJ库存回增数量 = SAAS退款明细数量

未发货退款：
申请关闭数量 = SAAS退款明细数量
且 150602数量 = 0、DGJ库存回增数量 = 0

29. 日志与代码检索

29.1 DGJ 代码定位

rg -n "createOrderReturn|createChargeOrderReturn|returnOrderNoOut|cancelReturnOrder" \
  application/controllers application/config

rg -n "function (add|check|inStorage|cancel|orderFinish)" \
  application/Services/ApplyReturn/ApplyReturnSer.php

rg -n "retOrder2|returnChargeOrder|returnOrderNoOut|addPaymentForApp" \
  application/Services/SaOrders/SaOrderSer.php

rg -n "sendApplyReturnCheckedToAPP|sendApplyReturnFinishToAPP|sendInventoryEvent" \
  application/Services/Mq/MqSer.php

29.2 SAAS 代码定位

rg -n "createOrderReturn|createChargeOrderReturn|returnOrderNoOut|cancelReturnOrder" \
  app/Providers/Dgj app/Service

rg -n "APP_APPLY_RETURN_CHECKED|APP_APPLY_RETURN_FINISH|returnChecked|returnFinish" \
  app/Amqp/Consumer/Dgj

rg -n "ORDER_STATUS_WAIT_ACK|ORDER_STATUS_SUBMITTED|ORDER_STATUS_FINISH|ORDER_STATUS_CANCEL" \
  app/Common/Constants/RefundOrderEnums.php

29.3 日志关键字

日志检索至少同时带两个条件，例如 refund_order_no + event_type 或 sid + application_id，避免同名业务单混淆。

30. 监控与对账

30.1 建议监控指标

30.2 每日对账口径

flowchart LR
    A["DGJ退货申请"] --> D["按退款单号/申请ID对齐"]
    B["DGJ 150602与库存"] --> D
    C["SAAS退款单与支付退款"] --> D
    D --> E{"状态、数量、金额一致?"}
    E -->|是| F["闭环归档"]
    E -->|否| G["生成差异类型"]
    G --> H["checked缺失"]
    G --> I["finish缺失"]
    G --> J["库存差异"]
    G --> K["资金退款差异"]

30.3 差异类型编码建议

31. 回归测试矩阵

31.1 主流程

31.2 状态和权限

31.3 参数和边界

31.4 幂等与故障

31.5 老流程影响

32. 当前代码高风险点

33. 静态代码无法证明的事项

以下事项必须通过环境配置、数据库定义、MQ 控制台或真实联调确认：

1. 退货申请表是否已有唯一索引以及索引列。
2. Model 更新方法是否隐含乐观锁、行锁或租户条件。
3. RequestCheck 使用的 Redis 集群、TTL 时钟和故障降级策略。
4. MQ producer 的 publisher confirm、持久化、重试和死信配置。
5. dgj_notify、dgj 的真实交换机、队列绑定和消费并发。
6. SAAS 消费异常告警是否稳定到达人，以及是否存在人工重放后台。
7. 各支付渠道同日/跨日退款的生产规则和资金到账 SLA。
8. 挂账领料路径当前产品契约是否确实不需要 finish 事件。
9. 入库仓库/货位是否允许前端修改，以及 WMS 是否有二次约束。
10. 线上物理分表名是否与代码默认格式完全一致。
11. t_scm_abnormal_return_log 的现网用途和数据修复治理流程。
12. 渠道、预售、采购退货是否复用了同一公共方法的隐藏分支。

文档维护时，确认一项就把它移动到对应事实章节，并记录验证日期、环境和证据。

34. 证据索引

34.1 DGJ

34.2 SAAS

34.3 阅读代码的推荐顺序

1. 先读 ApplyReturnEnums 和 RefundOrderEnums，理解两边状态。
2. 从 OrderProvider 确认真实接口 URL 和调用方。
3. 读 RefundService，理解 SAAS 本地事务和字段映射。
4. 读 DGJ Order Controller，区分四个入口。
5. 读 SaOrderSer 的三个退货分支。
6. 读 ApplyReturnSer 的审核、入库和取消。
7. 读 MqSer 和 SAAS DgjConsumer，补齐异步闭环。
8. 最后读 PC NormalSaleReturnSer，理解共用能力和老流程影响。

35. 一页式排查 SOP

flowchart TD
    START["输入：sid + RFC/退款单号 + 原销售单号"] --> S1["确认场景：已发货/挂账领料/未发货/PC直退"]
    S1 --> S2["查DGJ申请主明细和状态"]
    S2 --> S3["查SAAS退款主明细和状态"]
    S3 --> S4{"是否应生成150602?"}
    S4 -->|普通已发货/挂账领料| S5["查150602主明细"]
    S4 -->|未发货| S6["查原销售单关闭数量"]
    S5 --> S7["查库存流水与实时库存"]
    S6 --> S8["确认无库存回增"]
    S7 --> S9["查DGJ收退款和MQ发送"]
    S8 --> S9
    S9 --> S10["查SAAS checked/finish 消费"]
    S10 --> S11["查支付渠道真实退款"]
    S11 --> S12{"状态、数量、金额一致?"}
    S12 -->|是| DONE["记录证据，闭环"]
    S12 -->|否| FIX["按断点只补缺失步骤"]
    FIX --> VERIFY["重查四方数据和消息日志"]
    VERIFY --> DONE

记住六句话：

1. 先分场景：已发货退货、未发货退款和 PC 直退不是一条链路。
2. 先查状态再操作：DGJ 1/2/3/4 与 SAAS 0/11/1/99 要成对理解。
3. 申请不等于入库：普通申请创建时库存不变。
4. 完成不等于资金已退：DGJ 3 只证明 DGJ 业务完成。
5. ACK 不等于消费成功：SAAS 异常路径也会 ACK。
6. 只补断点，不重跑全链路：避免重复 150602、重复库存和重复退款。

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

多入口请求链路

日志证据矩阵

| 链路段 | 日志来源 | 可检索锚点 | 成功信号 | 失败信号 | 与下一段关联方式 | | --- | --- | --- | --- | --- | --- | --- | | 申请 | MoveMall/ApplyReturnSer | request_id、原单、apply ID、SKU | 申请主明细 commit | 超可退量、来源单不符、重复申请 | apply ID 关联原出库 | | 审核 | ApplyReturn Controller/Service | apply ID、动作、操作人 | 状态单向到通过/拒绝 | 并发审核、非法状态 | 申请状态触发退货单 | | 退货入库 | Return Service/InventorySer | return/original invoice、SKU、150602 | 实收量和库存 +n | 重复入库、超收、仓位错 | 退货单查流水/实时表 | | 退款同步 | Payment/MQ | refund/pay order、原销售单、message ID | 退款一次完成并 ACK | 重复退款、金额不符、漏回调 | 原支付单串联退款和申请 |

环节数据变更台账

子模块追踪：return-apply 售后申请创建

子模块追踪：return-audit 售后审核

子模块追踪：return-order 销售退货单创建

子模块追踪：return-inbound 退货入库与库存增加

子模块追踪：return-refund 退款与资金回退

子模块追踪：return-reject-cancel 驳回、取消与额度释放

子模块追踪：return-notify 售后状态通知