系统总览与代码地图

一句话理解

DGJ2.0 是一个围绕服务站经营的进销存系统：上游承接商品、订单、活动、支付、OA、调拨、TMS 等中心系统，下游给 PC 后台、App、小程序、渠道方和报表平台提供业务能力。

技术形态

• PHP 版本要求：composer.json 中为 php >= 7.1
• 框架风格：CodeIgniter 老项目，入口控制器在 application/controllers
• 依赖：Guzzle、Monolog、MongoDB、Redis、Elasticsearch 6.7、PhpSpreadsheet、kz/kzmq、league/csv
• 自动加载：App\\ 指向 application/
• 数据访问：大量模型继承老模型基类，模型目录在 application/models
• 服务层：新老并存，application/Services 偏新，application/service 偏老

入口层

• application/controllers/scm：传统进销存页面入口，包含采购、销售、库存、收付款、任务。
• application/controllers/po：新采购相关入口，如采购订单详情、购物车、采购退货。
• application/controllers/sale：销售和出库相关入口。
• application/controllers/basedata：基础资料管理，如商品、客户、供应商、库存、价格、区域。
• application/controllers/inner：内部 API，给 OPS、活动、渠道、移动商城等系统使用。
• application/controllers/app：App 侧控制器。
• application/controllers/tasks：定时任务和 MQ 消费入口。
• application/controllers/reports：报表页面和报表接口入口。
• application/controllers/allcarpart：全车件相关业务入口。

服务层

• application/service/scm/InvPoService.php：老采购单列表、详情、关闭、退货展示等逻辑。
• application/Services/PoOrders/PoOrderSer.php：新采购领域服务，负责订单校验、创建、自制单同步、关闭、支付状态等。
• application/service/scm/InvSaService.php：老销售出库列表、详情、对账、核销等逻辑。
• application/Services/SaOrders/SaOrderSer.php：销售订单创建、出库、来源场景转换、库存扣减和下游同步。
• application/Services/Storage/InventorySer.php：库存流水和实时库存变更。
• application/Services/Activity/FlashActivitySer.php：OPS 秒杀活动管理。
• application/Services/Activity/FlashSaleSer.php：服务站侧秒杀商品、购物车、预览、下单、支付状态联动。
• application/Services/MoveMall：移动商城、智能询价、机器人、补货、马上送。
• application/Services/Channel：大客户渠道订单、商品、售后。
• application/Services/Mq/MqSer.php：MQ 生产者封装。
• application/Services/SyncOrder：销售单和出库单同步到下游。

模型层

常见模型目录和业务含义：

• application/models/bs：基础资料，商品、库存、客户、供应商、服务站、品牌、分类、账户。
• application/models/orders：采购单、销售单、预订单、采购关闭、采购出库、付款信息。
• application/models/saOrders：销售订单、销售出库单、销售异常、品牌统计。
• application/models/payment：收付款单、明细、还款单。
• application/models/activity：活动、秒杀活动、秒杀购物车、秒杀订单、活动商品。
• application/models/moveMall：移动商城、微仓、机器人会话、关键词、补货退货。
• application/models/channel：渠道订单、渠道订单明细、渠道售后。
• application/models/report：报表模型。

配置层

• application/config/routes.php：少量显式路由，多数沿 CI 默认 controller/method 路由。
• application/config/apis.php：老开放接口 code 到 service 文件映射，例如订单状态、出库、收款成功回调。
• application/config/appapis.php：App 接口 code 到 app service 文件映射，覆盖登录、商品、销售、采购、资金、系统、WMS、盘点。
• application/config/mq.php：MQ 配置。
• application/config/redis.php、memcached.php、mongodb.php、elasticsearch.php：缓存和检索配置。
• application/config/tables.php：大量表常量来源之一。

外部系统边界

• 订单中心：采购正向、售后、取消、自制订单下发、关闭。
• 支付中心：在线支付成功、支付异常、退款、授信还款、白条到期。
• OA：活动、授信或审批类业务的审批结果。
• OPS：活动配置、商品活动、品牌授权、白名单等运营能力。
• 商品中心：物料、结算价、套包、限购、敏感词、销售限价。
• 调拨中心 / TMS：发货、配送、物流状态、第三方运单号。
• SAAS / APP：E站商城、E站维修、订单和出库同步。
• 报表中心 / Hologres：采购、销售、库存、利润等聚合查询。

主链路脑图

基础资料
  -> 商品/客户/供应商/仓库/货位/价格
  -> 采购、销售、库存、活动共用

采购
  -> 草稿 -> 提交 -> 审核/支付 -> 待出库 -> 配送/入库 -> 完成/关闭/退货
  -> 影响采购明细、库存、付款、报表、订单中心

销售
  -> 开单 -> 待出库 -> 出库 -> 派送 -> 送达 -> 对账 -> 核销
  -> 影响库存、收款、客户余额、APP/SAAS 同步

活动/秒杀
  -> OPS 建活动 -> OA 审批 -> 服务站选购 -> 生成秒杀单 -> 生成采购单 -> 支付/关闭回写

移动商城/渠道
  -> 外部订单/询价/机器人 -> DGJ 销售或采购单 -> 库存/支付/配送 -> 外部系统回调

任务/MQ
  -> 支付、OA、订单中心、商品中心、TMS、SAAS 消息
  -> 补偿、同步、状态推进、缓存刷新

系统上下游全景

flowchart LR
    subgraph Clients[调用端]
        PC[PC 后台]
        APP[App/PDA/小程序]
        OPS[OPS/内部平台]
        OPEN[渠道/OpenAPI]
    end

    subgraph DGJ[DGJ2 单体]
        C[Controller/路由]
        S[新旧 Service/Provider/Factory]
        M[Model/SQL]
        CACHE[Redis/ES/Mongo 缓存]
        TASK[Tasks/MQ 消费者]
    end

    subgraph Data[数据结果]
        MYSQL[(MySQL 业务表)]
        REPORT[(Hologres/报表中心)]
    end

    subgraph Centers[外部中心]
        ITEM[商品中心]
        ORDER[订单中心]
        PAY[支付中心]
        OA[OA]
        DISPATCH[调拨/配送/TMS]
        SAAS[SAAS/E站/APP]
    end

    PC --> C
    APP --> C
    OPS --> C
    OPEN --> C
    C --> S
    S --> M
    S <--> CACHE
    M --> MYSQL
    S --> Centers
    Centers --> TASK
    TASK --> S
    MYSQL --> REPORT

DGJ2 是业务编排和服务站账本，不是所有数据的最终权威：商品、订单审核、支付、OA、配送可能由外部中心主导；采购、销售、库存、收付款和服务站经营快照主要落在 DGJ2。排查前要先判断当前字段的主责系统。

五类请求入口

显式路由和默认路由

routes.php 只维护少量特殊映射，例如全车件 REST 风格路径。其他大量接口依赖 CodeIgniter 默认规则：URI 片段直接映射 Controller 和方法。因此：

• 看到 Controller 方法不能立即确定公网 URL，还要看 Nginx/OpenResty、入口文件和网关前缀。
• 全车件路由存在 kebab-case 到 Controller index/$action 的二次映射。
• App/OpenAPI 不能只按 Controller 路径寻找，要先从接口 code 找映射值。
• Tasks 是 CLI/MQ 入口，不应暴露给普通前端直接调用。

PC 请求生命周期

sequenceDiagram
    participant B as 浏览器
    participant N as Nginx/OpenResty
    participant I as index.php/CI Router
    participant C as BaseController/业务 Controller
    participant S as Service/Factory
    participant DB as Model/MySQL
    participant X as MQ/外部系统

    B->>N: GET/POST + session/cookie
    N->>I: 转发到 PHP 入口
    I->>C: 默认或显式路由到方法
    C->>C: 权限检查 + getPageData
    C->>C: 注入 JXCSID/JXCUID/JXCUNAME
    C->>S: 业务参数 + 登录上下文
    S->>DB: 查询/事务/状态更新
    opt 跨系统动作
        S->>X: HTTP/MQ/Provider
    end
    S-->>C: 结果或异常
    C-->>B: splash/splashJson/ajaxData

getPageData() 实际行为

BaseController::getPageData()：

1. 合并 GET 和 POST。
2. 调用历史参数过滤逻辑。
3. 把 page 最小归一为 1，rows 缺省为 99999。
4. 从登录态覆盖注入服务站、用户、区域和所属片区。

业务 Service 应优先使用服务端注入值，不信任 postData 中同名字段。排查跨站数据问题时，先确认 Controller 是否正确使用 JXCSID，再查 SQL 是否漏了 sid。

内部 API 生命周期

flowchart TD
    A[JSON/Form 请求] --> B[BaseApiController 构造]
    B --> C[解析 Content-Type 和 raw body]
    C --> D[记录 URI/body/header 请求日志]
    D --> E{是否内部服务并需要 token}
    E -- 是 --> F[校验 inner_token]
    F -- 失败 --> X[非法请求]
    E -- 否 --> G[读取 Request-Id/Inspire-Api-User/Shipper]
    F -- 通过 --> G
    G --> H[业务 Controller handle]
    H --> I[Request Entry 归一字段]
    I --> J[领域 Service]
    J --> K[表/缓存/Provider]
    K --> L[统一 JSON 返回并记录日志]

BaseApiController 会读取：

• Content-Type：JSON 走 raw_input_stream，其他内容合并 GET/POST/raw body。
• Request-Id：请求追踪标识。
• Inspire-Api-User：URL 编码 JSON 的 OPS 用户信息。
• Shipper：部分承运/内部业务上下文。
• inner_token：满足条件时执行内部服务鉴权。

内部 API 日志默认记录请求 body 和 header。新增接口时禁止把密码、token、支付敏感信息原样写入日志，应在入口或 Logger 层脱敏。

新旧代码分层如何理解

同一链路可能是“老 Controller -> 老 Service -> 新领域 Service -> Provider”。不要按目录新旧直接判断是否废弃，要用调用方搜索和环境开关确认。

数据访问和事务边界

flowchart LR
    C[Controller] --> S[Service]
    S --> BM[BaseModel/业务 Model]
    BM --> T[(业务主表/明细表)]
    S --> R[(Redis 锁/缓存)]
    S --> ES[(ES/Mongo)]
    S --> P[Provider/外部中心]
    T --> MQ[MqSer/SyncOrder]
    MQ --> D[下游消费者]

需要特别区分：

• MySQL 事务只能保证同一连接内的表写入，不能自动回滚已成功的 HTTP/MQ 外部动作。
• Redis 锁是短时互斥，不等于业务幂等。
• ES/Mongo/Redis 常是查询或缓存口径，不能用缓存结果替代库存/资金最终校验。
• 报表中心是异步聚合，允许短时延迟，但不允许长期与业务事实冲突。

三类常见响应

联调前先确认当前 Controller 使用哪一种返回方法。不要因为 HTTP 200 就判定业务成功，也不要强行要求所有历史接口立即改成同一种结构；统一响应属于跨前端契约改造，需要兼容期和完整调用方清单。

业务链路和主数据依赖

flowchart TD
    BASE[服务站/客户/供应商/商品/仓库/货位/价格] --> PO[采购]
    BASE --> SA[销售]
    BASE --> ACT[活动]
    PO --> INV[库存]
    SA --> INV
    ACT --> PO
    PO --> FUND[付款/退款]
    SA --> FUND2[收款/对账/核销]
    INV --> REPORT[报表/利润/经营分析]
    FUND --> REPORT
    FUND2 --> REPORT
    PO --> SYNC[订单中心/支付/OA/配送/SAAS]
    SA --> SYNC
    ACT --> SYNC

主数据错误会沿链路扩散：商品状态、仓库货位、客户账户或服务站区域不正确时，采购、销售、库存、支付和报表可能同时异常。排查业务单前先验证主数据快照和当前资料是否一致。

一次问题的定位顺序

1. 确认调用端、接口路径/code、环境、服务站和请求时间。
2. 根据入口找到 Controller 方法，确认请求解析和权限。
3. 记录主业务键：sid、业务单号、主单 ID、来源类型、来源单号、request ID。
4. 沿调用链进入 Service/Provider/Factory，列出状态前置条件。
5. 查主表、明细、数量/金额/日志表，不只看页面状态。
6. 涉及库存、资金时核对流水事实和实时结果。
7. 涉及异步时查生产日志、destination/routing key、消费 ACK/NACK。
8. 查自动补偿是否执行；人工处理前确认幂等和影响范围。
9. 对比下游和报表，区分实时失败、同步延迟和口径差异。

rg -n "class .*Controller|function 目标方法" application/controllers
rg -n "目标方法|业务单号字段|状态常量" application/service application/Services application/models
rg -n "目标表常量|物理表名" application/config/tables.php application
rg -n "routing key|destination|事件名" application/controllers/tasks application/Services/Mq application/KzData/Enums

系统级改动风险和回归

证据与待确认

已确认代码证据：index.php、application/config/routes.php、apis.php、appapis.php、tables.php、application/core/BaseController.php、Controller/Service/Model/Enum/Tasks 目录。

仍需按环境确认：

• Nginx/OpenResty 到不同入口目录的真实路由和域名。
• PC session、App 签名、OpenAPI 签名及内部 token 的环境配置。
• MQ、Redis、ES、Mongo、报表中心在开发/预发/生产的连接和降级策略。
• 老/新采购、销售服务的数据源和流量灰度开关。
• getThoroughData() 当前代码中参数过滤变量使用不一致的历史行为是否在运行路径被覆盖。

这些环境项应记录配置名和验证方式，不能在知识库中写入真实密码、密钥或 token。

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

多入口请求链路

日志证据矩阵

静态代码只能确认“应在哪个类和方法找”。具体日志文件名、日志平台索引及是否打印成功日志，必须在目标环境确认；没有日志时以数据库事实和下游回执补证，不能伪造日志文本。

环节数据变更台账

子模块级独立追踪

子模块追踪：pc-request PC 请求生命周期

子模块追踪：inner-api Inner 内部 API 生命周期

子模块追踪：app-gateway App tradeCode 网关

子模块追踪：openapi 老 OpenAPI 动态分发

子模块追踪：mq-consumer MQ 回调与消费者

子模块追踪：cli-task CLI 与定时任务

子模块追踪：transaction-data 统一事务与数据访问边界