高风险公共文件影响面

本文是 DGJ2.0 的“改公共代码前必读”手册。它回答的不是某一个业务怎么操作，而是：修改一个被多个业务共用的文件，会影响谁、改变哪些数据事实、需要防住哪些并发与兼容风险、最低必须回归什么。

代码根目录：/Users/zhoujiangbin/code/docker-dev-env/www/dgj2.0

1. 业务目标

• 避免修复秒杀、采购、销售等单一入口时破坏普通老链路。
• 把 Controller、Service、Model、MQ、回调、外部系统和页面资源的影响面连成一张图。
• 明确“代码成功”不等于“业务成功”，识别数据库事务以外的远程调用和消息副作用。
• 给开发、评审、测试和发布提供同一份风险语言与回归清单。
• 让后续工程师不必重新全库搜索，也能知道从哪里开始核对。

2. 什么时候必须使用本文

出现以下任一情况，都应按本文执行影响面审计：

3. 一页结论

当前静态代码扫描得到的引用文件数量如下。数量表示“包含该类名的 PHP 文件数”，用于衡量初始爆炸半径，不代表精确运行时调用次数。

最重要的五条规则：

1. 特殊业务必须用来源字段隔离。 秒杀来源以 srcOrderType=13 识别；orderType=30-Cxx-77 是订单类型，不能互相替代。
2. 查询条件的修改也是行为修改。 WHERE、JOIN、GROUP BY、总数 SQL 和分页 SQL 必须一起检查。
3. 事务只保护同一个数据库连接。 HTTP、MQ、Redis、文件和第三方系统不会随 MySQL 回滚。
4. 库存必须同时解释过程账与结果账。 流水记录为什么变，实时库存表示现在剩多少，两者缺一不可。
5. 回调天然会重复、乱序和迟到。 状态判断必须是可重入的业务幂等，不应只依赖消息不会重投。

flowchart LR
    E["PC / App / Inner / OpenAPI"] --> C["Controller"]
    C --> P["采购与销售公共 Service"]
    P --> M["Model 与分表"]
    P --> I["InventorySer"]
    P --> Q["MqSer"]
    P --> H["外部 HTTP Provider"]
    CB["支付 / OA / 订单 / 配送回调"] --> P
    T["定时任务与补偿"] --> P
    I --> DB["流水 + 实时库存"]
    Q --> OUT["下游系统"]
    H --> OUT

4. 风险分级

4.1 P0：可能造成资金、库存或重复单据

4.2 P1：可能改变共享业务行为

• 公共列表增加 OR 条件，导致特殊来源记录进入普通入口。
• 状态映射、订单类型、交易类型增加或改值。
• 支付信息过滤、关闭入口、退货入口和按钮权限改变。
• 分片算法、setSid() 调用时机、主从库选择改变。
• HTTP Provider 的超时、表单类型、结果解析和异常转换改变。

4.3 P2：主要影响展示、操作效率或可观察性

• 公共页面资源版本、打印模板、通用组件。
• 日志模块名、RequestId、脱敏字段。
• 枚举文案、提示文案、非业务关键排序。

P2 不代表可以不回归。公共资源加载失败时，可能让多个页面无法提交或打印。

5. 改动分类

评审时先给改动贴一种标签：

flowchart TD
    A["准备修改公共文件"] --> B{"是否有明确业务来源守卫"}
    B -->|是| C{"守卫字段是否来自持久化事实"}
    C -->|是| D["业务域内隔离"]
    C -->|否| E["风险不清"]
    B -->|否| F{"旧调用方结果是否完全不变"}
    F -->|是| G["共享兼容扩展"]
    F -->|否| H["共享行为改变"]
    D --> I["域内 + 守卫外回归"]
    G --> J["契约兼容回归"]
    H --> K["全链路回归"]
    E --> L["先补证据再修改"]

6. 总体影响面地图

7. InvPoService.php：采购老链路核心

文件：application/service/scm/InvPoService.php，约 8 千行。它不是单一“采购查询服务”，而是同时承载采购列表、退货、关闭、入库、支付和历史兼容。

7.1 方法簇

7.2 代表性入库请求

控制器最终传给 invPoInStorage($pageData) 的核心上下文可抽象为：

{
  "JXCSID": 10001,
  "JXCUID": 20001,
  "JXCUNAME": "operator",
  "orderId": 9000001,
  "entries": [
    {
      "outInfoId": 8000001,
      "srcOrderEntryId": 7000001,
      "invId": 6000001,
      "skuId": "SKU-DEMO",
      "qty": 2,
      "locationId": 30001,
      "locationAreaId": 40001
    }
  ]
}

字段名需以具体 Controller 的实际组装为准；本文示例只表达业务键和数据方向，不应直接作为生产请求。

7.3 入库主流程

sequenceDiagram
    participant U as PC/PDA/App
    participant S as InvPoService
    participant O as PoOutInfo
    participant P as PuInvoice
    participant I as InventorySer
    participant R as RealTimeInventory
    participant L as InventorySub
    participant Q as MQ/下游
    U->>S: invPoInStorage(pageData)
    S->>O: 查询可入库发货记录
    S->>S: checkInvPoInStorageQty
    S->>S: 开启数据库事务
    S->>P: addInvPur 生成 CG 主明细
    S->>I: save(inventoryRows)
    I->>R: increaseQty
    I->>L: 写库存分片流水
    S->>O: 更新发货/入库状态
    S->>S: updatePoStatus
    S-->>U: 返回入库结果
    S-->>Q: 库存或入库事件

需要同时核对的物理事实：

7.4 重复入库并发窗口

当前代码路径先读取可入库记录，再校验数量，之后才生成入库事实。如果两个请求在“发货记录仍可入库”的同一窗口并发到达，它们可能同时通过前置查询。

sequenceDiagram
    participant A as 请求 A
    participant B as 请求 B
    participant O as 发货明细
    participant DB as 入库与库存
    A->>O: 查询 billStatus=0
    O-->>A: 可入库
    B->>O: 查询 billStatus=0
    O-->>B: 可入库
    A->>DB: 创建 CG + 增库存
    B->>DB: 创建 CG + 增库存
    A->>O: 标记已处理
    B->>O: 标记已处理
    Note over DB: 若无原子占用/唯一键，可能形成重复事实

这类问题不能只靠“页面按钮禁用”解决。按钮只能降低人工重复点击，不能阻止重试、双端提交、网络超时后的再次提交或并行消费者。

7.5 推荐的原子占用模式

在同一事务中先用条件更新占用待处理行，并检查实际影响行数等于期望行数，占用成功后才创建入库和库存记录：

UPDATE t_scm_po_out_info_{shard}
SET billStatus = :processing_status,
    modifyTime = NOW()
WHERE sid = :sid
  AND id IN (:out_info_ids)
  AND billStatus = 0
  AND isDelete = 0;

随后检查：

affected_rows == count(distinct out_info_ids)

如果不相等，当前事务应回滚并提示“发货记录已被处理，请刷新”。

注意：BaseModel::updateItem() 声明为 bool，内部返回 affected_rows()。PHP 会把大于零的行数转换成 true，因此它不能用于判断“期望更新 3 行、实际只更新 1 行”。这种场景需要能够返回整数影响行数的专用 Model 方法。

7.6 重复入库只读检查

SELECT
    sid,
    srcOrderNo,
    srcOutNo,
    srcOrderEntryId,
    skuId,
    isGift,
    COUNT(*) AS row_count,
    SUM(qty) AS in_qty
FROM t_scm_pu_invoice_info_{shard}
WHERE sid = :sid
  AND srcOrderNo = :po_no
  AND isDelete = 0
GROUP BY sid, srcOrderNo, srcOutNo, srcOrderEntryId, skuId, isGift
HAVING COUNT(*) > 1;

不能仅以 COUNT(*) > 1 自动认定为错误：业务可能允许分批入库。还要核对每一组的累计入库数量是否超过对应发货数量，以及是否出现相同 srcOutNo + srcOrderEntryId + skuId + isGift 的重复整批提交。

7.7 公共查询条件风险

采购列表通常同时包含：主单、32 分片明细、发货汇总、入库汇总、关闭汇总。改变任一 JOIN 都可能改变列表行数。

flowchart TD
    A["采购主单"] --> B["采购明细"]
    B --> C["按明细聚合发货量"]
    B --> D["按明细聚合入库量"]
    B --> E["按明细聚合关闭量"]
    C --> F["可处理量"]
    D --> F
    E --> F
    F --> G["列表行"]
    G --> H["分页总数"]
    G --> I["按钮权限"]

改列表 SQL 时必须同步检查：

• 数据查询 SQL 与 count SQL 是否使用相同过滤条件。
• 一对多 JOIN 是否导致主单重复、分页数量变小。
• 新增 OR 是否被正确括号包围。
• billStatus=0 到底指主单状态还是发货/入库明细状态。
• sid 是否同时出现在主表和分表条件中。
• 历史状态是否仍需出现在退货、关闭或报表入口。

7.8 秒杀来源守卫

安全守卫示例：

if ((int)($order['srcOrderType'] ?? 0) === PoOrderEnums::SRC_ORDER_TYPE_FLASH_ACTIVITY) {
    // 只对秒杀来源执行支付方式过滤或库存补偿
}

危险写法：仅凭前端参数、订单文案或 orderType 模糊判断来源。

7.9 支付入口影响

getPayInfoNew()、noPagePay()、专属支付和聚合支付并非一条完全相同的链路。修改支付限制时要列清允许入口：

7.10 InvPoService 最小回归

• 普通采购：创建、提交、订单中心同步、待支付/非在线支付。
• 采购入库：一次入库、分批入库、重复请求、并发请求、超量入库。
• 采购关闭：部分行关、整单关、已入库后关闭、消息重复。
• 采购退货：普通退货、不良品、少发、在线支付未发货退货。
• 特殊来源：预订单、活动、秒杀、首配、直发。
• 查询：列表数据、总数、分页最后一页、导出和详情数量一致。

8. InvPoFactory.php：采购创建事务编排

文件：application/Services/InvPoFactory.php。

8.1 动态策略

构造函数按 $type 动态加载 App\Services\InvPo\{$type}Ser。当前调用方包括：

不存在的类型会抛出“无效的订单类型”，因此新增策略必须同时提供类、调用入口和回归用例。

8.2 saveOrder() 流程

sequenceDiagram
    participant C as Controller/活动服务
    participant R as Redis
    participant F as InvPoFactory
    participant S as 具体采购策略
    participant DB as MySQL
    participant O as 订单中心
    participant P as 支付版本服务
    C->>F: saveOrder(params)
    F->>R: 检查采购黑名单与加锁
    F->>DB: begin
    F->>S: saveOrder(params)
    S->>DB: 写采购主明细
    F->>DB: 保存购物车关联
    F->>O: toOrdercenter
    O-->>F: 订单与支付模式
    F->>P: queryVersion(sid)
    F->>DB: 更新 paymentType/status
    F->>DB: commit
    F->>R: 解锁
    F-->>C: success

8.3 事务边界

saveOrder() 在 MySQL 事务内调用订单中心和支付版本服务。数据库回滚无法撤销外部系统已成功创建的订单。

flowchart LR
    A["本地写采购单"] --> B["订单中心创建成功"]
    B --> C["后续本地更新失败"]
    C --> D["MySQL rollback"]
    D --> E["本地无单"]
    B --> F["订单中心已有单"]
    E -.不一致.-> F

评审必须回答：

• 订单中心以哪个字段幂等：通常应是 sourceOrderCode/billNo，需以对方契约确认。
• 本地重试是否会重复创建外部订单。
• 回滚后是否有查询外部状态并补偿/重建本地数据的流程。
• 临时库存释放是否覆盖所有失败点。
• Redis 锁的过期、进程崩溃和解锁归属是否安全。

8.4 参数与外部字段映射

9. PoOrderSer.php：新采购领域服务

文件：application/Services/PoOrders/PoOrderSer.php，约 2.5 千行。

9.1 主要责任

• checkOrderGoods()：下单商品规则。
• addPoOrder()、addSelfPoOrder()：采购单和自营订单创建。
• closeSelfOrder()、syncSelfOrder()：自营订单同步与关闭。
• cancelWaitPayOrder()：支付异常或超时取消。
• 采购库存与待发货数量查询。
• 采购购物车新增、更新和最低起订量处理。
• 地址、自提、订单截止时间等辅助能力。

9.2 风险关系

flowchart TD
    A["普通采购"] --> P["PoOrderSer"]
    B["预订单"] --> P
    C["活动/秒杀"] --> P
    D["支付异常回调"] --> P
    P --> O["采购主明细"]
    P --> K["供应库存查询"]
    P --> C1["购物车"]
    P --> S["销售未发货数量"]

PoOrderSer 会读取 SaOrderSer 的未发货数量参与采购可用量判断时，修改销售查询可能间接改变采购展示，这是跨领域的隐性影响。

9.3 回归重点

• orderType 与 srcOrderType 的组合，不只回归其中一个字段。
• 取消待支付单是否释放临时库存和活动锁定量。
• App/任务调用 service() 时，CLI 返回新实例、Web 返回进程内单例的差异。
• 购物车最小起订量和最大限购失败后缓存是否清理。
• 自提地址、仓库和服务站上下文是否一致。

10. InvSaService.php：销售、出库和对账老链路

文件：application/service/scm/InvSaService.php，约 9.5 千行，是当前最大的共享业务文件之一。

10.1 方法簇

10.2 销售出库副作用

sequenceDiagram
    participant U as PC/App/SAAS
    participant S as InvSaService
    participant DB as 销售订单与出库单
    participant I as InventorySer
    participant T as 配送/TMS
    participant Q as MQ
    U->>S: addOutBound/outBound
    S->>DB: 校验未出库数量
    S->>DB: 写销售出库主明细
    S->>I: 扣减库存并写流水
    S->>T: 创建或更新配送单
    S->>DB: 重算销售/出库状态
    S-->>Q: SAAS/App/下游状态事件
    S-->>U: 出库结果

必须明确 TMS 和 MQ 调用在事务提交前还是提交后。若 TMS 已成功而本地回滚，重试必须依赖稳定业务键更新原配送单，而不是创建第二单。

10.3 修改销售公共 SQL 的危险点

• sid%16 的销售订单明细和 _0_{sid%64} 的出库明细不能混用分片公式。
• 出库数量、退货数量的符号方向不同，不能只做 SUM(qty) 后不看 transType。
• 一张销售单可以部分出库，多张出库单参与状态重算。
• 对账、取消对账和自动核销共用出库单状态时，要保留历史状态兼容。
• SAAS 来源、App 来源和 PC 来源可能共用一张主表，但下游通知不同。

11. SaOrderSer.php：新销售领域服务

文件：application/Services/SaOrders/SaOrderSer.php。

11.1 主要入口

11.2 新旧销售服务关系

flowchart LR
    A["PC 老入口"] --> L["InvSaService"]
    B["App / SAAS / 新入口"] --> N["SaOrderSer"]
    L --> O["销售主单/明细"]
    N --> O
    L --> I["销售出库/库存"]
    N --> I
    O --> Q["同步与报表"]

不要假设修改其中一个服务不会影响另一个。它们写入同一批核心业务表，并可能互相调用或共享 Model、枚举和库存服务。

12. InventorySer.php：库存事实写入核心

文件：application/Services/Storage/InventorySer.php。

12.1 save() 的真实顺序

save($inventory, $iid=0, $billType=null) 对每一行先改变实时库存，循环结束后再批量写分片库存流水。旧流水主表写入已被注释。

sequenceDiagram
    participant B as 业务 Service
    participant I as InventorySer
    participant R as InventoryRealTimeModel
    participant C as Redis 最近出入库时间
    participant L as InventorySubModel
    B->>I: save(rows, iid, billType)
    opt iid 非空
        I->>I: delete(iid,billType) 反向旧流水
    end
    loop 每个库存行
        I->>R: increaseQty/decrementQty
        I->>C: 更新 in/out 时间
    end
    I->>L: 批量写库存分片流水

如果调用方没有包裹数据库事务，前几行实时库存更新成功、后续一行失败时，会形成部分成功。即使调用方有事务，也要确认实时库存 Model 和流水 Model 使用同一个数据库连接。

12.2 库存写入字段

12.3 扣减分支

changeInventoryQty() 根据商品归属和站点库存控制配置选择是否允许负库存。

flowchart TD
    A{"qty > 0?"} -->|是| B["increaseQty"]
    A -->|否| C{"商品 sid == 1?"}
    C -->|是 快准商品| D{"服务站在快准库存控制名单?"}
    D -->|是| E["decrementQty 严格控制"]
    D -->|否| F["decrementQty 允许另一策略"]
    C -->|否 第三方商品| G{"服务站在第三方库存控制名单?"}
    G -->|是| H["decrementQty 使用第三方策略"]
    G -->|否| I["decrementQty 使用相反策略"]
    E --> J{"affected > 0?"}
    F --> J
    H --> J
    I --> J
    J -->|否| K["抛库存不足"]
    J -->|是| L["更新最近出入库时间"]

布尔参数的准确语义应继续以 InventoryRealTimeModel::decrementQty() 的 SQL 为准，不应只凭参数名猜测。修改名单判断时必须覆盖快准商品和第三方商品的四种组合。

12.4 delete() 是业务反向操作

delete(iid,billType,transType) 不是简单删除：它先读取旧流水，对每一行用 0 - old.qty 反向实时库存，再删除分片流水。

flowchart LR
    A["读取旧流水"] --> B["qty 取反"]
    B --> C["更新实时库存"]
    C --> D["删除流水"]

风险：

• 同一个 iid 条件过宽会反向不属于本次修改的流水。
• 反向库存成功后删除流水失败，会保留旧流水但实时库存已反向。
• 调用两次时，第二次查不到流水通常不会再次反向，但需确保第一次事务完整提交。
• delete() 调用 changeInventoryQty() 的参数位置要特别小心；areaType 与 transType 均为可选参数，位置传错会改变负库存/最近时间逻辑。

12.5 库存最小回归矩阵

13. KzInventorySer.php：供应库存查询公共适配

文件：application/Services/KzInventory/KzInventorySer.php。

13.1 查询流程

sequenceDiagram
    participant B as 业务调用方
    participant K as KzInventorySer
    participant P as KzInventoryProvider
    participant S as 库存中心
    B->>K: patchGetKzInventory(sid, skuIds, orderType)
    K->>K: 每 50 个 SKU 分批
    loop 每个批次
        K->>P: asyncGetInventoryBySkuIds
        P->>S: 异步 HTTP
        S-->>P: company/details/allowQty
        P-->>K: callback
    end
    K->>P: asyncWait
    K->>K: 按 skuCode/companyCode 归并
    K-->>B: 库存 Map

13.2 新旧格式差异

异步请求失败时 BaseProvider 会给 callback 空数组，整个批次可能静默缺失。调用方必须区分“真实零库存”和“外部批次查询失败”；当前静态代码不能证明所有调用方都做了这个区分。

14. MqSer.php：跨系统生产者公共门面

文件：application/Services/Mq/MqSer.php。

14.1 事件域

14.2 事务与 MQ 的四种结果

flowchart TD
    A["本地业务操作"] --> B{"数据库提交成功?"}
    B -->|否| C["不得让下游形成最终事实"]
    B -->|是| D{"MQ 发布成功?"}
    D -->|是| E["正常收敛"]
    D -->|否| F["本地成功 / 下游缺事件"]
    C --> G{"消息是否已提前发送?"}
    G -->|是| H["本地失败 / 下游可能已处理"]
    G -->|否| I["本地回滚"]
    F --> J["补偿任务或 Outbox"]
    H --> K["下游幂等 + 反向补偿"]

每个发送方法修改时都要核对：

• destination/routing key 是否与消费者注册一致。
• 消息体字段是新增可选、改名、删除还是类型变化。
• messageId 是否稳定；随机 ID 不能替代业务幂等键。
• 调用发生在事务提交前还是提交后。
• publish 失败是否抛异常，调用方是否会回滚。
• 是否有补偿任务可以基于业务事实重建消息。

14.3 代表性库存消息

{
  "sid": 10001,
  "iid": 9000001,
  "billType": "PU",
  "transType": "150501",
  "poOrderId": 7000001,
  "inventoryData": [
    {"invId": 6000001, "skuId": "SKU-DEMO", "qty": 2}
  ]
}

真实 routing key、包裹结构和字段类型以 MqSer 与 MqEventEnums 当前代码为准。

15. 回调消费者：支付、订单、配送与 OA

15.1 消费者地图

15.2 支付成功回调

PayCenterNotify::paycenterPayResult() 只接受 payStatus='02'。采购支付会把外部“分”转换成本地“元”，并写付款主明细、采购支付信息和订单状态。

sequenceDiagram
    participant P as 支付中心
    participant C as PayCenterNotify
    participant O as 采购/预订单
    participant F as Payment/PaymentInfo
    participant A as Account
    P->>C: pay_result(sourceOrderNo,payStatus,details)
    C->>C: 校验 payStatus == 02
    C->>O: 查询单据和允许支付状态
    C->>F: 写付款主明细
    C->>A: 写账户/资金事实
    C->>O: 推进支付与采购状态
    C-->>P: ACK

高风险点：

• 失败状态当前返回 NACK，需确认支付中心是否会持续重投以及是否符合协议。
• 采购允许从待支付和支付超时状态接收迟到成功，预订单允许状态集合不同。
• 重复消息依赖订单状态拦截，但数据库唯一键仍需线上确认。
• 外部金额除以 100，新增字段必须明确单位。
• 回调中 sleep(1) 处理零元单，可能影响消费者吞吐。

15.3 ACK/NACK 决策

flowchart TD
    A["收到消息"] --> B{"事件可识别?"}
    B -->|否| C["记录未知事件并按协议处理"]
    B -->|是| D{"业务键存在?"}
    D -->|否| E["NACK 或进入人工队列"]
    D -->|是| F{"已达到目标状态?"}
    F -->|是| G["幂等 ACK"]
    F -->|否| H{"当前状态允许迁移?"}
    H -->|否| I["记录乱序/非法迁移"]
    H -->|是| J["事务写入"]
    J --> K{"提交成功?"}
    K -->|是| G
    K -->|否| L["NACK 重试"]

“目标状态已完成”应返回幂等 ACK，还是 NACK，必须逐事件按消费者契约确认。无限 NACK 一个不可恢复的历史脏消息会阻塞队列。

16. FlashSaleSer.php：秒杀域共享核心

文件：application/Services/Activity/FlashSaleSer.php，约 5 千行。

16.1 责任范围

• 服务站访问与黑白名单。
• 商品列表、详情、套包与筛选。
• 购物车新增、更新、失效清理。
• 订单预览、提交、详情和取消。
• 锁定量 locked_qty、使用量 used_qty 的转移与释放。
• 秒杀订单转 30-Cxx-77 采购单，写 srcOrderType=13 来源关系。
• 支付成功、采购关闭、订单超时和补偿任务。

16.2 数量状态

stateDiagram-v2
    [*] --> Available: 活动可售
    Available --> Locked: 提交订单锁量
    Locked --> Used: 支付成功/采购成立
    Locked --> Available: 取消或超时释放
    Used --> Available: 合法关闭/退款补偿
    Used --> Used: 重复回调幂等

修改公共采购关闭、支付回调或库存释放时，必须确认是否会触发：

• releaseByPoOrder() 或相似释放逻辑。
• 同一 srcOrderId 是否已经释放。
• 部分关闭按行释放还是整单释放。
• 普通采购是否会误进入秒杀补偿。

16.3 采购来源关系

erDiagram
    FLASH_ORDER ||--o{ FLASH_ORDER_DETAIL : contains
    FLASH_ORDER ||--o{ SCM_PO_ORDER : creates
    SCM_PO_ORDER ||--o{ SCM_PO_ORDER_INFO : contains
    FLASH_ORDER {
      bigint id
      string order_no
      int order_status
    }
    SCM_PO_ORDER {
      bigint id
      string billNo
      int srcOrderType
      bigint srcOrderId
      string srcOrderNo
      string orderType
    }

17. BaseModel.php 与分表模型

文件：application/models/BaseModel.php。

17.1 公共行为

17.2 分片上下文

分片表必须在访问前确定 sid。常见公式包括采购明细 %32、销售明细 %16、销售出库 %64、库存流水 %128、盘点 %10。具体表以 Model 的 setSid()/getTableName() 为准。

flowchart LR
    A["请求 sid"] --> B["Model.setSid(sid)"]
    B --> C["计算 shard"]
    C --> D["设置物理表名"]
    D --> E["执行 SQL"]

危险场景：

• 先查询再 setSid()，读到上一次实例残留的表名。
• Web 下 BaseSer::service() 返回进程内单例，Service/Model 持有可变 sid。
• CLI 下每次 service() 新建实例，行为与常驻 Web 不完全一致。
• 批量处理多个 sid 时只设置一次分片。
• 用业务号猜分片，而真正分片键是 sid。

18. BaseProvider.php：外部 HTTP 公共行为

文件：application/Providers/BaseProvider.php。

18.1 请求生命周期

flowchart LR
    A["Provider 子类"] --> B["选择 form/json/body/query/multipart"]
    B --> C["同步或异步 Guzzle 请求"]
    C --> D{"HTTP 成功?"}
    D -->|否| E["超时/Provider 异常"]
    D -->|是| F{"sheet 下载?"}
    F -->|是| G["输出文件并 die"]
    F -->|否| H["XML 优先解析，否则 JSON"]
    H --> I["返回数组或 null"]

18.2 公共风险

18.3 Provider 回归

• JSON、form、query、body 和 multipart 各选一个现有调用。
• HTTP 200 业务失败码、HTTP 500、超时、无效 JSON、XML。
• 异步三个批次：全部成功、一个失败、全部失败。
• 下载响应的 Content-Disposition 和大文件内存。
• 日志脱敏，不输出 Authorization、Cookie 和敏感请求体。

19. 公共入口基类

19.1 BaseController.php

公共责任包括登录态、总部账号上下文、请求数据、RequestId、权限/会话和统一页面行为。修改登录判断会同时影响普通账号和总部账号。

19.2 BaseAppController.php / BaseService.php

OpenAPI/老 API 基类通常负责签名、请求锁、统一错误和调用日志。代码中请求锁使用 Redis NX EX 600：

KEY_REQUEST_ID_LOCK + requestId

重复请求是否释放锁取决于 isCanReleaseLock。修改锁生命周期时要回答：

• 请求成功后是否立即释放，还是需要十分钟业务幂等窗口。
• 超时后客户端重试是否会被误拒绝。
• 不同业务但相同 requestId 是否共享命名空间。
• 锁只防并发，数据库是否仍有业务唯一键。

19.3 BaseSer.php

service() 在 CLI 中每次返回新实例，在非 CLI 中按类名缓存实例。任何 Service 内的可变属性都可能跨同一请求中的多次调用保留。

flowchart TD
    A{"is_cli()?"} -->|是| B["new static 每次新实例"]
    A -->|否| C{"类实例已缓存?"}
    C -->|否| D["创建并缓存"]
    C -->|是| E["返回已有实例"]

不要在公共 Service 单例上长期保存 sid、临时筛选条件或上一次调用结果，除非每次入口都会显式覆盖并清理。

20. 配置、枚举和路由

20.1 tables.php

表常量是 Model 与手写 SQL 的公共名字来源。改常量前全局搜索常量名和物理表名，因为旧代码可能直接写字符串。

20.2 PoOrderEnums.php / SaOrderEnums.php / TransTypeEnums.php

枚举会影响：

• 状态机允许迁移。
• 列表筛选和按钮。
• 库存正负方向和报表。
• 外部订单类型映射。
• MQ 分支和回调识别。

改“值”比改“文案”危险得多。历史数据仍保存旧值时，删除常量会让老单无法展示或处理。

20.3 routes.php / appapis.php / apis.php

路由和 API 映射变化会影响入口是否能到达、鉴权基类、参数上下文和响应格式。新增入口必须确认它走 PC、App 网关、OpenAPI 还是 inner 边界，不能只复制 Controller 方法。

21. 公共视图 kzuilite.php

文件：application/views_v2/common/kzuilite.php 当前加载公共 kzuiadmin.lite_v2 资源版本。直接或间接引用页面包括销售订单、配送列表、报价商品搜索、商品管理、门店设置和调拨申请等。

flowchart TD
    K["kzuilite.php"] --> B1["new_base 系列布局"]
    K --> P1["销售订单"]
    K --> P2["配送列表"]
    K --> P3["报价搜索"]
    K --> P4["商品管理"]
    K --> P5["门店设置"]
    K --> P6["调拨申请"]

修改资源 URL 或版本时至少验证：

• 页面首屏无 JS 404、语法错误和组件未定义。
• 表格分页、弹窗、选择器、日期组件和提交按钮。
• 老缓存与新 HTML 混用时是否兼容。
• 页面是否通过公共 layout 间接加载，避免重复加载两次。

22. 典型跨切面风险

22.1 先写库还是先发消息

22.2 状态判断与副作用分离

安全顺序：

1. 根据稳定业务键查本地事实。
2. 判断是否已经达到目标状态。
3. 校验当前状态是否允许迁移。
4. 原子占用或加版本条件更新。
5. 写业务主事实和明细。
6. 同一事务提交。
7. 发送可重试的下游事件。
8. 用业务键验证最终收敛。

22.3 不能用兜底掩盖脏数据

危险例子：

• 找不到来源单时改查“最近一张同 SKU 单据”。
• 库存中心失败时把空数组当作零库存并缓存。
• 状态未知时默认映射成“正常”。
• 分表查不到时遍历所有分片并取第一条。
• 支付账户不匹配时默认使用第一个账户。

兜底必须区分“可预期兼容”和“数据关系已损坏”，后者应报警并阻止继续写入。

23. 改动前调用方扫描

23.1 类名与方法

cd /Users/zhoujiangbin/code/docker-dev-env/www/dgj2.0

rg -n "InvPoService|InvSaService|PoOrderSer|SaOrderSer" application
rg -n "InventorySer|KzInventorySer|InvPoFactory|FlashSaleSer" application
rg -n "MqSer|sendInventoryEvent|sendPoCloseOrderConfirm|sendSaOrderOutToMq" application

23.2 状态、来源与交易类型

rg -n "SRC_ORDER_TYPE_FLASH_ACTIVITY|ORDERTYPE_FLASH_ORDER|30-Cxx-77" application
rg -n "BILLSTATUS_|SA_STATUS_|OUT_BILLSTATUS_|ORDER_STATUS_" application
rg -n "TRANSTYPE_|150501|150601|170401|170402" application

23.3 SQL 与分表

rg -n "mix_where|group_by|count_all_results|JOIN|UNION" application/service/scm application/Services
rg -n "setSid\(|% ?(10|16|32|64|128)|getTable(Name)?\(" application/models application/Services
rg -n "updateItem\(|affected_rows\(|createOrUpdateItem\(" application

23.4 回调与外部副作用

rg -n "registryCallback|MqResultEnums::ACK|MqResultEnums::NACK" application/controllers/tasks
rg -n "trans_begin|trans_commit|trans_rollback" application/service application/Services
rg -n "Provider\(|requestSer|requestSerAsync|send.*Mq" application/service application/Services

24. 方法级影响面记录模板

每次修改公共方法，在评审描述中填写：

### 公共方法影响面

- 文件/方法：
- 改动分类：业务域内隔离 / 共享兼容 / 共享行为改变 / 风险不清
- 入口调用方：PC / App / Inner / OpenAPI / MQ / CLI
- 来源守卫：字段、值、持久化表
- 读取表：
- 写入表：
- 分片公式：
- 状态迁移：
- 库存/资金副作用：
- Redis/MQ/HTTP 副作用：
- 事务开始与提交位置：
- 重复请求行为：
- 失败补偿：
- 普通链路回归：
- 特殊来源回归：
- 线上待确认：

25. 最小回归矩阵

26. 症状导向排查

26.1 修秒杀后普通采购支付失败

1. 查 srcOrderType 守卫是否只包住秒杀分支。
2. 查是否误用 orderType=30-Cxx-77 替代来源。
3. 对比 getPayInfoNew()、noPagePay() 等所有支付入口。
4. 用普通采购和秒杀采购分别输出过滤前后的支付方式。
5. 查支付回调是否仍能识别普通采购状态。

26.2 同一发货单出现两张 CG 入库单

1. 以 sid + srcOrderNo + srcOutNo + srcOrderEntryId + skuId 查询入库明细。
2. 对比每张 CG 的创建时间和操作人。
3. 查发货明细的处理状态更新时间。
4. 查请求日志是否同秒、同 RequestId 或来自不同入口。
5. 核对是否存在原子占用和唯一索引；没有时按第 7.5 节设计修复。
6. 修复业务表后继续核对库存流水、实时库存和报表层。

26.3 MQ 显示发送成功但下游没有数据

1. 查 destination 和 routing key。
2. 查消费者是否注册该事件。
3. 查消息体业务键和字段类型。
4. 查发送发生时本地事务是否已提交。
5. 查下游幂等是否把消息当作重复丢弃。
6. 查重试、死信和补偿任务，禁止盲目重复发送资金/库存事件。

26.4 列表数量和导出数量不同

1. 比较列表 SQL、count SQL 和导出 SQL。
2. 检查一对多 JOIN 是否重复主记录。
3. 检查分页前后是否才执行分组。
4. 检查分片和 sid 条件。
5. 检查新状态/来源是否只在其中一个入口过滤。

26.5 库存流水正确但实时库存错误

1. 按 sid+invId+locationId+locationAreaId 汇总有效流水。
2. 对比实时库存同维度行，不要只按 SKU 汇总。
3. 查是否发生编辑单据的 delete()+save() 部分成功。
4. 查负库存配置和商品归属分支。
5. 查历史归档流水是否未纳入核对口径。

27. 只读 SQL 模板

27.1 采购单与来源

SELECT id, sid, billNo, billStatus, orderType,
       srcOrderType, srcOrderId, srcOrderNo,
       paymentType, paymentNumber, createTime, modifyTime
FROM t_scm_po_order
WHERE sid = :sid AND billNo = :bill_no AND isDelete = 0;

27.2 库存过程账

SELECT iid, billNo, billType, transType,
       invId, skuId, locationId, locationAreaId,
       qty, amount, createTime
FROM t_scm_inventory_info_{sid_mod_128}
WHERE sid = :sid
  AND billNo = :bill_no
ORDER BY createTime, id;

27.3 实时库存

SELECT sid, inv_id, sku_id, location_id, location_area_id,
       area_type, qty, modify_time
FROM t_scm_inventory_real_time
WHERE sid = :sid AND inv_id = :inv_id
ORDER BY location_id, location_area_id;

27.4 支付回调落账

SELECT p.id, p.sid, p.billNo, p.billType, p.srcOrderNo,
       p.totalAmount, p.createTime
FROM t_scm_payment_{payment_shard} p
WHERE p.sid = :sid AND p.srcOrderNo = :order_no
ORDER BY p.createTime, p.id;

物理表名和字段以目标环境 DDL 为准；生产只读查询应先限制 sid、业务号和时间范围。

28. 发布前门禁

28.1 开发自检

• [ ] 已给改动分类并说明来源守卫。
• [ ] 已列出所有直接和间接调用方。
• [ ] 已列出读取表、写入表和分片公式。
• [ ] 已画出事务边界和事务外副作用。
• [ ] 已证明重复请求、并发请求和乱序回调的结果。
• [ ] 已保留普通老链路行为。
• [ ] 已检查日志不包含密钥、完整 token、客户敏感信息。

28.2 代码评审

• [ ] 新增 OR 有括号，查询与 count 条件一致。
• [ ] 状态迁移只允许合法源状态。
• [ ] 批量条件更新检查了整数影响行数。
• [ ] Redis 锁不是唯一幂等手段。
• [ ] MQ/HTTP 失败行为和补偿责任明确。
• [ ] 枚举值没有破坏历史数据。
• [ ] 特殊来源未渗透普通入口。

28.3 测试证据

• [ ] 正常流程。
• [ ] 边界数量：0、1、最大值、部分处理。
• [ ] 相同请求重复两次。
• [ ] 两个并发请求。
• [ ] 外部超时、业务失败和空响应。
• [ ] MQ 重投与非法顺序。
• [ ] 数据库主单、明细、库存/资金流水和状态一致。
• [ ] 列表、详情、导出和报表口径未出现意外变化。

29. 安全修改模式

29.1 来源守卫包住最小代码块

$isFlash = (int)($order['srcOrderType'] ?? 0)
    === PoOrderEnums::SRC_ORDER_TYPE_FLASH_ACTIVITY;

if ($isFlash) {
    $payInfo = $this->filterFlashActivityPayInfo($payInfo, $subAccountId);
}

不要把整个普通支付流程复制成秒杀分支，避免两份逻辑长期漂移。

29.2 条件更新推进状态

UPDATE business_order
SET status = :target_status, modify_time = NOW()
WHERE id = :id
  AND status IN (:allowed_source_statuses);

只有影响行数为 1 才执行后续副作用；影响 0 行时重新读取，区分“已完成幂等”与“非法状态”。

29.3 用稳定业务键补偿

补偿任务输入应优先是 sid + billNo/orderNo + eventType，而不是数据库自增 ID 或一次请求生成的随机消息 ID。补偿前重新查询最终业务事实，再决定是否发送。

30. 当前代码已证明与待确认

30.1 静态代码已证明

• InventorySer::save() 先更新实时库存，最后批量写分片流水。
• 旧库存流水主表写入已注释，当前写 InventorySubModel。
• InventorySer::delete() 会先反向实时库存再删除流水。
• KzInventorySer 每 50 个 SKU 分批异步查询。
• 新旧库存格式对 allowQty<=0 明细的保留规则不同。
• InvPoFactory::saveOrder() 在 MySQL 事务内调用订单中心。
• 秒杀来源常量为 srcOrderType=13，订单类型为 30-Cxx-77。
• BaseModel::updateItem() 因 bool 返回类型不能保留批量影响行数。
• BaseProvider 异步失败会向 callback 传空数组。
• PayCenterNotify 注册 10 类支付事件，支付成功状态值为字符串 02。

30.2 仍需环境验证

31. 代码证据

• application/service/scm/InvPoService.php
• application/Services/InvPoFactory.php
• application/Services/PoOrders/PoOrderSer.php
• application/service/scm/InvSaService.php
• application/Services/SaOrders/SaOrderSer.php
• application/Services/Storage/InventorySer.php
• application/Services/KzInventory/KzInventorySer.php
• application/Services/Mq/MqSer.php
• application/Services/Activity/FlashSaleSer.php
• application/controllers/tasks/PayCenterNotify.php
• application/controllers/tasks/OrderCenterNotify.php
• application/controllers/tasks/DispatchCenterNotify.php
• application/controllers/tasks/OaNotify.php
• application/controllers/tasks/OaResultNotify.php
• application/models/BaseModel.php
• application/Providers/BaseProvider.php
• application/core/BaseController.php
• application/core/BaseAppController.php
• application/core/BaseService.php
• application/Services/BaseSer.php
• application/config/tables.php
• application/config/routes.php
• application/config/appapis.php
• application/config/apis.php
• application/KzData/Enums/PoOrderEnums.php
• application/KzData/Enums/SaOrderEnums.php
• application/KzData/Enums/TransTypeEnums.php
• application/KzData/Enums/MqEventEnums.php
• application/views_v2/common/kzuilite.php

32. 最终判断标准

一项公共文件修改只有同时满足以下条件，才算影响面已收敛：

1. 能从入口追到方法、表、状态、库存/资金和外部副作用。
2. 能明确普通来源和特殊来源的守卫边界。
3. 能解释重复、并发、乱序、超时和部分成功后的最终结果。
4. 能用 SQL、日志和消息业务键验证，而不是只看页面提示成功。
5. 已执行与风险等级匹配的回归，不以单个接口成功代替全链路成功。
6. 所有静态代码不能证明的环境事实都被单独列出，没有伪装成确定结论。

公共文件真正的风险不在“文件很大”，而在它把多个入口、多个数据事实和多个外部系统连接在一起。修改时先画清边界，再写代码，通常比上线后从库存或资金差异反推原因便宜得多。

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

多入口请求链路

日志证据矩阵

| 链路段 | 日志来源 | 可检索锚点 | 成功信号 | 失败信号 | 与下一段关联方式 | | --- | --- | --- | --- | --- | --- | --- | | 调用面盘点 | rg/静态调用图 | 公共类/方法、调用文件、入口类型 | 调用方清单覆盖 PC/App/MQ/task | 只看当前需求入口 | 调用方法映射业务类型/来源 | | 回归请求 | 各入口日志 | request_id、来源类型、业务单号 | 每个代表链路行为不变 | 非目标来源也进入新分支 | 单号回查对应领域表 | | 数据副作用 | Service/DB/MQ 日志 | 状态、transType、影响行数、routing key | 目标分支变更，旧分支等价 | 数量方向、事务、消息字段回归 | 主明细/流水/消费者对账 | | 外部兼容 | Provider/Consumer | 外部 request/message ID、版本/字段 | 新旧 payload 合同兼容 | 缺字段、类型变更、重复副作用 | 两端 ID + 业务单号 |

环节数据变更台账

子模块追踪：risk-invpo-service InvPoService 采购公共链

子模块追踪：risk-invpo-factory InvPoFactory 采购事务编排

子模块追踪：risk-poorder-ser PoOrderSer 新采购领域链

子模块追踪：risk-invsa-service InvSaService 销售公共链

子模块追踪：risk-saorder-ser SaOrderSer 新销售领域链

子模块追踪：risk-inventory-ser InventorySer 库存事实链

子模块追踪：risk-kzinventory-ser KzInventorySer 供给库存链

子模块追踪：risk-mq-ser MqSer 消息生产链

子模块追踪：risk-task-consumer 支付、订单、OA Consumer

子模块追踪：risk-base-model BaseModel 数据访问链

子模块追踪：risk-base-provider-view BaseProvider 与公共视图组件