DGJ2.0 二期继续整理大纲

第一批文档已经回答了“项目有哪些业务模块、主流程怎么走、代码入口在哪里”。第二批建议继续补“能落地排查、能联调对接、能长期维护”的资料。下面按优先级列大纲，后续可以逐篇补成独立文档。

总体目标

继续整理时，不再只写模块介绍，而是把每个关键链路沉淀成可直接使用的工作资料：

新人能按文档找到入口、表、状态和排查命令。
前后端能按文档确认接口字段、状态含义和异常边界。
排查问题时能按文档定位日志、MQ、表数据和补偿任务。
改老逻辑时能知道哪些公共文件影响面大，哪些状态不能随便改。

已落地文章索引

二期规划已经按 P0、P1、P2 拆成独立文章：

P0：最值得优先补的资料

1. 表结构与业务表字典

目标：把核心表按业务域整理，说明主键、外键、状态字段、来源字段、金额字段和数量字段。

建议拆分：

采购表：po_order、po_order_info、po_order_pay_info、po_close_info、采购入库、采购退货。
销售表：销售主单、销售明细、销售出库、出库明细、收款明细。
库存表：库存流水、实时库存、仓库、货位、库存盘点。
活动表：秒杀活动、活动商品、购物车、秒杀订单、秒杀订单明细。
渠道表：渠道订单、渠道订单明细、渠道售后、渠道签收。
财务表：收付款主表、收付款明细、账户、白条授信、还款单。

整理重点：

哪张表是主表，哪张表是明细表。
哪些字段是业务状态，哪些字段是删除/关闭标记。
哪些字段跨系统关联，例如 srcOrderId、srcOrderNo、srcOrderType。
金额单位是元还是分，数量字段是正数还是正负方向。
哪些表会被报表中心同步，可能存在延迟。

2. 状态机和订单类型字典

目标：把分散在 application/KzData/Enums 里的状态整理成人能看懂的状态流转图。

建议拆分：

采购单状态机：草稿、待处理、审核中、待支付、待出库、配送中、已完成、关闭、退款、过期。
销售单状态机：待出库、部分出库、已完成、关闭。
销售出库状态机：已出库、派送中、已送达、已对账、已核销、已撤销。
秒杀活动状态机：草稿、审批中、审批通过、启用、提前结束、驳回。
秒杀订单状态机：待支付、已支付、已取消、已关闭。
渠道订单状态机：待审核、待发货、部分发货、已完成、已取消。

整理重点：

哪些状态允许编辑。
哪些状态允许关闭、撤销、退货。
哪些状态会扣库存或释放库存。
哪些状态由人工操作推进，哪些由 MQ/回调推进。
旧状态和兼容状态如何展示。

3. API 与入口字典

目标：让前端、联调同学知道每个业务接口在哪里、参数从哪里来、返回什么口径。

建议拆分：

PC 页面入口：application/controllers/scm、basedata、reports。
内部 API：application/controllers/inner。
App API：application/config/appapis.php 和 application/service/api/app。
老开放 API：application/config/apis.php 和 application/service/api。
任务入口：application/controllers/tasks。

整理重点：

接口 code 到实际文件的映射。
典型请求字段，例如 JXCSID、JXCUID、JXCUNAME、sid、orderId。
典型响应结构。
哪些接口有权限、登录态、服务站维度限制。
哪些接口是给外部系统调用，不适合前端直接调。

4. MQ、回调与补偿任务地图

目标：把订单中心、支付中心、OA、商品中心、调拨中心、TMS、SAAS 的消息流整理清楚。

建议拆分：

支付中心回调：PayCenterNotify.php。
订单中心回调：OrderCenterNotify.php。
OA 审批回调：OaNotify.php、OaResultNotify.php。
商品中心同步：ItemCenterNotify.php。
调拨/配送/TMS：DispatchCenterNotify.php、TMS 相关 tasks。
SAAS 同步：SaasOrderNotify.php、SyncOrderSer.php。
秒杀补偿：FlashSaleTask.php 和 FlashSaleSer 的补偿方法。

整理重点：

destination、routing key、事件类型。
消费方法入口。
消息幂等字段。
失败后是否重试。
有哪些手动补偿方法和排查命令。

P1：业务排查和联调最常用

5. 采购完整排查手册

围绕一个采购单号整理排查步骤：

查采购主单、明细、支付信息。
查订单中心审核状态。
查支付中心回调。
查关闭明细、退货单、退款状态。
查入库单和库存流水。
查是否影响秒杀、赠品活动或自制订单。

输出形式建议：一篇“采购单从创建到完成的排查 SOP”。

6. 销售完整排查手册

围绕一个销售单或出库单整理：

查销售单来源和支付方式。
查可出库数量和库存货位。
查出库单和库存流水。
查配送状态、签收状态、对账核销状态。
查 APP/SAAS 下游同步事件。

输出形式建议：一篇“销售单、出库单、退货单排查 SOP”。

7. 库存一致性排查手册

重点解决“列表有库存但下单失败”“库存流水和实时库存不一致”“报表库存和业务库存不一致”。

需要整理：

商品维度：skuId、invId、物料状态。
仓库维度：服务站仓、指定仓、供给仓、货位。
流水维度：采购入库、销售出库、退货入库、盘盈盘亏、调拨、关闭。
缓存维度：ES、Mongo、Redis、物料缓存。
报表维度：业务库和 Hologres DWD 表口径差异。

8. 秒杀活动专项手册

第一批已经写了主流程，二期可以补更细的联调和排查：

OPS 创建/导入/提交/OA/启用。
服务站商品列表、详情、加购、购物车、确认页。
生成秒杀订单和采购单。
支付成功、支付超时、主动取消、采购关闭。
locked_qty、used_qty、活动总量的校验 SQL。
补偿任务怎么跑、跑完看哪些表。

9. 财务和支付排查手册

围绕付款单、收款单、白条、退款整理：

支付中心消息如何落 payment 和 payment_info。
po_order_pay_info 如何关联采购单。
线上支付和线下挂账的差异。
白条、待退款账户、返利、专属返利分别怎么入账。
支付异常、退款异常、重复回调如何判断。

P2：长期维护和新人理解

10. 权限、菜单和白名单

建议整理：

后台菜单和资源权限如何配置。
application/controllers/inner/sys/OpsWhitelist.php 等白名单入口。
服务站权限、人员权限、特殊权限控制。
新增菜单/按钮/接口时需要补哪些配置。

11. 导入导出和 Excel 模板

建议整理：

秒杀活动商品导入导出。
基础资料导入。
采购、销售、库存、报表导出。
错误文件下载和字段校验。
PhpSpreadsheet 使用约定。

12. 搜索、缓存与索引

建议整理：

商品 ES 查询。
物料缓存、服务站物料缓存。
Redis key 枚举和缓存失效。
Mongo 缓存数据。
哪些业务读缓存，哪些业务必须读库。

13. 报表口径专题

建议整理：

采购明细报表。
采购入库报表。
销售明细报表。
销售对账报表。
库存报表。
利润报表。
客户往来账、供应商往来账。

重点写清楚：

业务库字段到 DWD 字段的映射。
查询条件和状态过滤。
与实时业务数据可能不一致的原因。

14. 外部系统对接清单

建议按系统整理：

订单中心：正向采购、售后、关闭、自制订单。
支付中心：支付结果、退款结果、异常。
OA：审批发起、审批结果。
商品中心：物料、价格、套包、限购、敏感词。
调拨中心/TMS：出库、配送、运单。
SAAS/APP：订单、出库、客户、微信订单。
VIN/数据平台：商品和车型相关。

每个系统都写：

DGJ 发出去什么。
DGJ 接收什么。
入口文件在哪里。
幂等字段是什么。
失败怎么补偿。

15. 本地开发、联调和日志定位

建议整理：

本地项目如何启动。
Nginx/OpenResty 路由如何指向 DGJ2。
PHP、MySQL、Redis、MQ、ES、Mongo 配置在哪里。
常用日志目录。
如何按订单号、sid、billNo 搜日志。
本地和预发环境差异。

16. 高风险公共文件影响面

建议整理一份“改前必看”：

application/service/scm/InvPoService.php
application/service/scm/InvSaService.php
application/Services/PoOrders/PoOrderSer.php
application/Services/SaOrders/SaOrderSer.php
application/Services/Storage/InventorySer.php
application/Services/Mq/MqSer.php
application/KzData/Enums/*

每个文件写：

它影响哪些业务。
常见被复用的方法。
改动后必须回归哪些流程。
哪些参数或状态不能随意改名。

P3：代码里已存在、但还没有单独成篇的业务专题

这批模块不一定每天都改，但都有独立控制器、Service 或核心表。后续如果要把 DGJ2.0 业务图谱补得更完整，建议继续从 26 开始追加文章。

17. PDA / GPDA 扫码、盘点与仓内作业

建议文章：26_PDA_GPDA扫码盘点与仓内作业.md

入口文件：

application/controllers/pda/Purchase.php
application/controllers/pda/Sale.php
application/controllers/pda/TakeStock.php
application/controllers/pda/AreaChange.php
application/controllers/pda/OutStockCheck.php
application/controllers/inner/gpda/TakeStock.php
application/controllers/inner/gpda/GpdaStore.php
application/controllers/inner/gpda.back/Inventory.php
application/Services/Pda/*
application/Services/Gpda/*

核心表：

t_scm_inventory_check
t_scm_inventory_check_info
t_sys_pda_option_log
库存流水和实时库存表。

整理重点：

PDA 扫码采购入库、销售出库、盘点、货位调整的入口区别。
PDA/GPDA 和 PC 端库存逻辑是否共用 InventorySer。
扫码验货、货位选择、盘点差异、盘盈盘亏如何落库存流水。
盘点任务失败或重复提交时如何排查。

18. 服务站间调拨 STF 与调拨申请

建议文章：27_服务站间调拨_STF与调拨申请.md

入口文件：

application/controllers/stf/Apply.php
application/controllers/stf/Invoice.php
application/Services/Stf/ApplySer.php
application/Services/Stf/InvoiceSer.php
application/controllers/scm/InvTf.php

核心表：

t_scm_stf_apply
t_scm_stf_apply_info
t_scm_stf_invoice
t_scm_stf_invoice_info
t_scm_tf_invoice
t_scm_tf_invoice_info

整理重点：

服务站间调拨申请、审核、出库、入库流程。
调出方和调入方库存如何同时变化。
调拨收款、调拨付款交易类型如何入账。
调拨单和普通其他出入库、采购、销售的边界。

19. 对账单策略、生成、发送与收款同步

建议文章：28_对账单策略_生成发送与收款同步.md

入口文件：

application/controllers/reports/StatementBill.php
application/controllers/reports/StatementSend.php
application/controllers/reports/StatementStrategy.php
application/controllers/tasks/StatementNotify.php
application/controllers/tasks/StatementTasks.php
application/controllers/tasks/StatementSendConsumer.php
application/controllers/tasks/StatementStrategyConsumer.php
application/Services/Statement/*

核心表：

t_bs_statement_bill_v2
t_bs_statement_bill_detail_v2
t_bs_statement_bill_detail_item_v2
t_bs_statement_bill_task_v2
t_bs_need_statement_user
t_bs_statement_strategy_v2
t_bs_statement_strategy_relation_v2
t_bs_statement_send_record_v2

整理重点：

对账策略如何选客户、选周期、生成账单。
销售单、出库单、收款单如何进入对账明细。
对账单发送、客户接收状态、收款状态如何同步。
MQ 任务失败后如何补偿和重发。

20. 售后申请、销售退货申请与异常退货

建议文章：29_售后申请与销售退货申请.md

入口文件：

application/controllers/applyReturn/ApplyReturnOrder.php
application/Services/ApplyReturn/ApplyReturnSer.php
application/controllers/scm/InvSa.php
application/controllers/sale/SaReturnOrder.php
application/controllers/tasks/SaleReturn.php

核心表：

t_scm_apply_return_order
t_scm_apply_return_order_info
t_scm_abnormal_return_log
销售出库和库存流水表。

整理重点：

销售退货申请、审核、入库、退款/冲账流程。
异常退货和正常销售退货的区别。
退货数量如何影响原销售单、出库单和实时库存。
APP/SAAS 退货事件如何同步。

21. 税票、发票和开票资料

建议文章：30_税票与发票开具.md

入口文件：

application/Services/TaxInvoice/TaxInvoiceSer.php
application/controllers/basedata/TaxInvoice.php
application/controllers/inner/Invoice.php

核心表：

t_bs_contact
t_bs_contact_info
税票/开票资料相关模型和业务表。

整理重点：

客户开票资料维护。
发票申请、发票状态、业务单据关联。
销售、收款、对账单和发票之间的口径。
开票失败、资料变更、历史发票兼容。

22. 金融通道、银行支付与授信分期

建议文章：31_金融通道_银行支付与授信分期.md

入口文件：

application/controllers/financial/B2bPay.php
application/controllers/financial/BridgeBank.php
application/controllers/financial/BtInstallment.php
application/controllers/financial/Cmbc.php
application/controllers/financial/Icbc.php
application/controllers/financial/IcbcE.php
application/controllers/financial/Lakala.php
application/controllers/financial/MyBank.php
application/controllers/financial/TaiLong.php
application/controllers/financial/Xiaoyudian.php
application/Services/Financial/*

核心表：

支付、账户、授信、还款相关表。
各银行通道回调或中间状态表。

整理重点：

不同金融通道的入口、签名、回调和状态。
B2B 支付、桥接银行、分期、白条之间的边界。
通道失败、重复回调、金额不一致如何排查。
生产环境排查时哪些字段不能泄露。

23. 专属授信、返利与资金池

建议文章：32_专属授信_返利与资金池.md

入口文件：

application/Services/ExclusiveBaitiao/*
application/Services/ExclusiveRebate/*
application/controllers/inner/ExclusiveBaitiao.php
application/controllers/tasks/Baitiao.php

核心表：

t_bs_exclusive_baitiao_cash_pool
t_bs_exclusive_baitiao_activity
t_bs_exclusive_baitiao_activity_relations
t_bs_exclusive_baitiao_activity_apply
t_bs_baitiao_adjust_log
t_bs_baitiao_apply
t_bs_baitiao_apply_info

整理重点：

专属授信活动、报名申请、资金池、额度调整。
白条订单、还款单、支付回调如何串起来。
返利、专属返利、普通账户流水之间的区别。
到期提醒、逾期状态、额度释放如何排查。

24. 帮助中心、知识库、题库与搜索

建议文章：33_帮助中心_知识库_题库与搜索.md

入口文件：

application/controllers/help/Dgj.php
application/controllers/newhelp/Question.php
application/controllers/newhelp/Answer.php
application/controllers/newhelp/QuestionLib.php
application/controllers/knowledge/Knowledge.php
application/controllers/qa/Qa.php
application/Services/Help/*
application/Services/Knowledge/*
application/Services/Qa/QaSer.php

核心表：

t_help_question
t_help_answer
t_help_question_lib
t_knowledge
t_knowledge_category
t_knowledge_collect

整理重点：

提问、回答、题库导入、知识库发布和收藏。
帮助中心 ES 缓存如何建立和刷新。
题库 Excel 导入的错误文件和字段校验。
知识库同步到机器人或七鱼知识库的边界。

25. 轮胎小程序登记、理赔与属性配置

建议文章：34_轮胎小程序_登记理赔与属性配置.md

入口文件：

application/controllers/tyre/Claim.php
application/controllers/inner/tyre/Claim.php
application/controllers/inner/tyre/Registration.php
application/controllers/inner/tyre/Property.php
application/controllers/inner/tyre/User.php
application/Services/Tyre/*

核心表：

t_tyre_registration
t_tyre_claim
t_tyre_property
t_bs_image

整理重点：

轮胎登记、图片上传、理赔申请、理赔审核。
属性字典如何维护。
用户和服务站维度如何绑定。
理赔状态、图片资料缺失、重复提交如何排查。

26. 账号登录、设备、PC 授权与安全日志

建议文章：35_账号登录_设备_PC授权与安全.md

入口文件：

application/controllers/passport/*
application/controllers/app/passport/*
application/Services/Passport/LoginService.php
application/Services/Safe/AccountSafeSer.php
application/Services/Safe/AccountSafeLogSer.php
application/controllers/tasks/AccountSafeLog.php

核心表：

t_app_device
t_sys_pc_auths
t_sys_pc_versions
t_sys_pc_machines
t_sys_pc_login_control
t_sys_pc_upgrade_log
t_sys_pc_unbind_apply
t_sys_pc_bind_apply
t_bs_account_safe_log

整理重点：

PC 端机器码绑定、解绑申请、登录控制。
App 设备登录记录。
账号安全日志、异常登录、安全提醒。
登录失败、机器授权失败、版本升级失败如何排查。

27. 总分店、总部账号与经营报表

建议文章：36_总分店_总部账号与经营报表.md

入口文件：

application/controllers/headOffice/Account.php
application/controllers/headOffice/Reports.php
application/Services/HeadOffice/AccountService.php
application/Services/HeadOffice/ReportService.php

核心表：

t_sys_head_office_account
服务站、门店、客户、销售、库存和报表相关表。

整理重点：

总部账号和分店账号关系。
总部视角如何聚合采购、销售、库存、财务报表。
权限、数据范围、服务站切换如何控制。
总部报表和单站报表口径差异。

28. 客户运营、C 端营销活动与优惠券

建议文章：37_客户运营_C端营销与优惠券.md

入口文件：

application/controllers/market/ClientActivity.php
application/Services/Marketing/ClientActivitySer.php
application/controllers/tasks/ClientActivity.php
application/controllers/inner/ClientCoupon.php

核心表：

t_mkt_client_activity
t_mkt_client_activity_goods
t_mkt_client_activity_relations
t_mkt_client_activity_imgs
t_mkt_client_activity_apply
t_mkt_client_coupon_templates
t_mkt_client_coupon_send_log

整理重点：

C 端营销活动创建、报名、适用商品和服务站范围。
优惠券模板、发放日志和核销/使用边界。
和 E站活动、普通销售活动、秒杀活动的区别。
活动开始/结束 MQ、优惠券发放失败如何补偿。

29. 配送履约、自提、骑手与三方配送

建议文章：38_配送履约_自提骑手与三方配送.md

入口文件：

application/Services/Transport/TransportSer.php
application/Services/Transport/SelfDeliverySer.php
application/Services/SaOrders/ThirdDeliverySer.php
application/controllers/tasks/DispatchCenterNotify.php
application/config/appapis.php 中 transport* 接口。

核心表：

t_scm_third_party_delivery_order
t_sa_invoice_delivery_relation
销售出库单和采购出库相关表。

整理重点：

骑手接单、配送轨迹、到达、签收、取消。
自提和配送中心发货的状态差异。
三方配送单和销售出库单如何关联。
配送状态异常时如何按运单、出库单、骑手查日志。

30. AI 控台、机器人、IM 与 Udesk 客户同步

建议文章：39_AI控制台_机器人_IM_Udesk.md

入口文件：

application/controllers/aiConsole/Courier.php
application/Services/Ai/AiSer.php
application/Services/Ai/OilService.php
application/Services/MoveMall/Robot/*
application/Services/MoveMall/RobotV2/*
application/Services/IM/IMService.php
application/Services/Udesk/CustomerService.php
application/controllers/tasks/ImCenterNotify.php
application/controllers/tasks/UdeskAsync.php
application/controllers/tasks/UdeskNotify.php

核心表：

机器人会话、报价范围、搜索日志、IM、Udesk 同步相关表。

整理重点：

AI 报价、机器人会话、IM 消息和客户同步之间的关系。
Udesk 客户创建/异步同步失败如何补偿。
IM 业务消息如何消费。
机器人 V1/V2、移动商城机器人和 AI 控台的边界。

31. 数据修复、迁移脚本与临时任务治理

建议文章：40_数据修复_迁移脚本与临时任务治理.md

入口文件：

application/controllers/tasks/DataFix.php
application/controllers/tasks/GeneralTasks.php
application/controllers/tasks/*Migrate.php
application/controllers/tasks/Tmp*.php
application/Services/Migrate/*
application/controllers/temp/*
application/controllers/tools/*

核心表：

被修复业务表。
日志表、任务记录表、迁移过程表。

整理重点：

临时脚本如何识别是否仍可执行。
数据修复前如何备份、如何限制环境、如何记录修复 SQL。
迁移任务如何幂等、如何分批、如何回滚。
哪些脚本禁止在生产直接跑。

P4：低频但建议建立索引的专项

这些专题可以先只写“入口索引 + 风险提示”，等实际遇到需求或故障时再扩成完整 SOP。

41_报价_智能询价_报价规则专题.md：覆盖 QuoteManager、报价范围、报价规则、机器人报价配置。
42_电池用户_蓄电池可售范围专题.md：覆盖 BatteryUserService、蓄电池服务站可售分类品牌、缓存。
43_首配_预订单_首批配货专题.md：覆盖首配方案、预订单、预售、提货、售后。
44_大客户_临采_渠道订单专题.md：在现有外部渠道文档基础上细拆大客户临采、渠道供应商、签收和售后。
45_成本价_动态成本_利润计算专题.md：覆盖动态成本分表、出库成本、利润报表成本口径。
46_地址_区域_承运商时效专题.md：覆盖省市区、仓库地址、配送承运商、退货地址。
47_消息通知_站内信_推送专题.md：覆盖 t_sys_message、t_sys_message_text、t_app_push_log、消息任务。
48_开放平台_OpenAPI_老接口兼容专题.md：覆盖 Openapi.php、application/config/apis.php 和历史外部调用兼容。

建议整理顺序

我建议按这个顺序继续：

表结构与业务表字典。
状态机和订单类型字典。
MQ、回调与补偿任务地图。
采购完整排查手册。
销售完整排查手册。
库存一致性排查手册。
秒杀活动专项手册。
财务和支付排查手册。
API 与入口字典。
外部系统对接清单。
PDA / GPDA 扫码、盘点与仓内作业。
服务站间调拨 STF 与调拨申请。
对账单策略、生成、发送与收款同步。
售后申请、销售退货申请与异常退货。
税票、发票和金融通道。
帮助中心、知识库、题库与搜索。
账号登录、设备、PC 授权与安全。
数据修复、迁移脚本与临时任务治理。

这个顺序的好处是：先把数据和状态口径立住，再整理链路排查；否则直接写 SOP，容易遇到“状态是什么意思、表从哪来”还要来回补。

每篇文档统一模板

后续每个专题建议统一写成下面结构：

1. 业务目标
2. 适用场景
3. 入口文件
4. 核心 Service
5. 核心表
6. 状态和枚举
7. 主流程
8. 异常流程
9. MQ / 外部系统
10. 常用排查 SQL 或 rg 命令
11. 改动风险和回归清单

当下最建议马上补的 3 篇

如果只选三篇，我建议优先补：

表结构与业务表字典：这是所有业务理解的地基。
MQ、回调与补偿任务地图：这是线上排查最容易卡住的地方。
库存一致性排查手册：采购、销售、活动、移动商城都会踩这个点。